mirror of
https://github.com/sile/hls_m3u8.git
synced 2024-09-27 22:11:54 +00:00
581 lines
21 KiB
Rust
581 lines
21 KiB
Rust
use std::collections::HashSet;
|
|
use std::fmt;
|
|
use std::str::FromStr;
|
|
|
|
use derive_builder::Builder;
|
|
use shorthand::ShortHand;
|
|
|
|
use crate::line::{Line, Lines, Tag};
|
|
use crate::tags::{
|
|
ExtM3u, ExtXIndependentSegments, ExtXMedia, ExtXSessionData, ExtXSessionKey, ExtXStart,
|
|
ExtXVersion, VariantStream,
|
|
};
|
|
use crate::types::{ClosedCaptions, MediaType, ProtocolVersion};
|
|
use crate::utils::tag;
|
|
use crate::{Error, RequiredVersion};
|
|
|
|
/// The master playlist describes all of the available variants for your
|
|
/// content.
|
|
/// Each variant is a version of the stream at a particular bitrate and is
|
|
/// contained in a separate playlist.
|
|
#[derive(ShortHand, Debug, Clone, Builder, PartialEq)]
|
|
#[builder(build_fn(validate = "Self::validate"))]
|
|
#[builder(setter(into, strip_option))]
|
|
#[shorthand(enable(must_use, get_mut, collection_magic))]
|
|
pub struct MasterPlaylist {
|
|
/// The [`ExtXIndependentSegments`] tag signals that all media samples in a
|
|
/// [`MediaSegment`] can be decoded without information from other segments.
|
|
///
|
|
/// # Note
|
|
///
|
|
/// This tag is optional.
|
|
///
|
|
/// If this tag is specified it will apply to every [`MediaSegment`] in
|
|
/// every [`MediaPlaylist`] in the [`MasterPlaylist`].
|
|
///
|
|
/// [`MediaSegment`]: crate::MediaSegment
|
|
/// [`MediaPlaylist`]: crate::MediaPlaylist
|
|
#[builder(default)]
|
|
independent_segments: Option<ExtXIndependentSegments>,
|
|
/// The [`ExtXStart`] tag indicates a preferred point at which to start
|
|
/// playing a Playlist.
|
|
///
|
|
/// # Note
|
|
///
|
|
/// This tag is optional.
|
|
#[builder(default)]
|
|
start: Option<ExtXStart>,
|
|
/// The [`ExtXMedia`] tag is used to relate [`MediaPlaylist`]s,
|
|
/// that contain alternative renditions of the same content.
|
|
///
|
|
/// For example, three [`ExtXMedia`] tags can be used to identify audio-only
|
|
/// [`MediaPlaylist`]s, that contain English, French, and Spanish
|
|
/// renditions of the same presentation. Or, two [`ExtXMedia`] tags can
|
|
/// be used to identify video-only [`MediaPlaylist`]s that show two
|
|
/// different camera angles.
|
|
///
|
|
/// # Note
|
|
///
|
|
/// This tag is optional.
|
|
///
|
|
/// [`MediaPlaylist`]: crate::MediaPlaylist
|
|
#[builder(default)]
|
|
media: Vec<ExtXMedia>,
|
|
/// A list of all streams of this [`MasterPlaylist`].
|
|
///
|
|
/// # Note
|
|
///
|
|
/// This tag is optional.
|
|
#[builder(default)]
|
|
variants: Vec<VariantStream>,
|
|
/// The [`ExtXSessionData`] tag allows arbitrary session data to be
|
|
/// carried in a [`MasterPlaylist`].
|
|
///
|
|
/// # Note
|
|
///
|
|
/// This tag is optional.
|
|
#[builder(default)]
|
|
session_data: Vec<ExtXSessionData>,
|
|
/// This is a list of [`ExtXSessionKey`]s, that allows the client to preload
|
|
/// these keys without having to read the [`MediaPlaylist`]s first.
|
|
///
|
|
/// # Note
|
|
///
|
|
/// This tag is optional.
|
|
///
|
|
/// [`MediaPlaylist`]: crate::MediaPlaylist
|
|
#[builder(default)]
|
|
session_keys: Vec<ExtXSessionKey>,
|
|
/// This is a list of all tags that could not be identified while parsing
|
|
/// the input.
|
|
///
|
|
/// # Note
|
|
///
|
|
/// This tag is optional.
|
|
#[builder(default)]
|
|
unknown_tags: Vec<String>,
|
|
}
|
|
|
|
impl MasterPlaylist {
|
|
// TODO: finish builder example!
|
|
/// Returns a builder for a [`MasterPlaylist`].
|
|
///
|
|
/// # Example
|
|
///
|
|
/// ```
|
|
/// use hls_m3u8::tags::ExtXStart;
|
|
/// use hls_m3u8::MasterPlaylist;
|
|
///
|
|
/// MasterPlaylist::builder()
|
|
/// .start(ExtXStart::new(20.123456))
|
|
/// .build()?;
|
|
/// # Ok::<(), Box<dyn ::std::error::Error>>(())
|
|
/// ```
|
|
pub fn builder() -> MasterPlaylistBuilder { MasterPlaylistBuilder::default() }
|
|
}
|
|
|
|
impl RequiredVersion for MasterPlaylist {
|
|
fn required_version(&self) -> ProtocolVersion {
|
|
required_version![
|
|
self.independent_segments,
|
|
self.start,
|
|
self.media,
|
|
self.variants,
|
|
self.session_data,
|
|
self.session_keys
|
|
]
|
|
}
|
|
}
|
|
|
|
impl MasterPlaylistBuilder {
|
|
fn validate(&self) -> Result<(), String> {
|
|
self.validate_variants().map_err(|e| e.to_string())?;
|
|
self.validate_session_data_tags()
|
|
.map_err(|e| e.to_string())?;
|
|
|
|
Ok(())
|
|
}
|
|
|
|
fn validate_variants(&self) -> crate::Result<()> {
|
|
if let Some(variants) = &self.variants {
|
|
self.validate_stream_inf(variants)?;
|
|
self.validate_i_frame_stream_inf(variants)?;
|
|
}
|
|
|
|
Ok(())
|
|
}
|
|
|
|
fn validate_stream_inf(&self, value: &[VariantStream]) -> crate::Result<()> {
|
|
let mut closed_captions_none = false;
|
|
|
|
for t in value {
|
|
if let VariantStream::ExtXStreamInf {
|
|
audio,
|
|
subtitles,
|
|
closed_captions,
|
|
stream_data,
|
|
..
|
|
} = &t
|
|
{
|
|
if let Some(group_id) = &audio {
|
|
if !self.check_media_group(MediaType::Audio, group_id) {
|
|
return Err(Error::unmatched_group(group_id));
|
|
}
|
|
}
|
|
if let Some(group_id) = &stream_data.video() {
|
|
if !self.check_media_group(MediaType::Video, group_id) {
|
|
return Err(Error::unmatched_group(group_id));
|
|
}
|
|
}
|
|
if let Some(group_id) = &subtitles {
|
|
if !self.check_media_group(MediaType::Subtitles, group_id) {
|
|
return Err(Error::unmatched_group(group_id));
|
|
}
|
|
}
|
|
|
|
if let Some(closed_captions) = &closed_captions {
|
|
match &closed_captions {
|
|
ClosedCaptions::GroupId(group_id) => {
|
|
if closed_captions_none {
|
|
return Err(Error::custom(
|
|
"If one ClosedCaptions is None all have to be None!",
|
|
));
|
|
}
|
|
|
|
if !self.check_media_group(MediaType::ClosedCaptions, group_id) {
|
|
return Err(Error::unmatched_group(group_id));
|
|
}
|
|
}
|
|
_ => {
|
|
if !closed_captions_none {
|
|
closed_captions_none = true;
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
Ok(())
|
|
}
|
|
|
|
fn validate_i_frame_stream_inf(&self, value: &[VariantStream]) -> crate::Result<()> {
|
|
for t in value {
|
|
if let VariantStream::ExtXIFrame { stream_data, .. } = &t {
|
|
if let Some(group_id) = stream_data.video() {
|
|
if !self.check_media_group(MediaType::Video, group_id) {
|
|
return Err(Error::unmatched_group(group_id));
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
Ok(())
|
|
}
|
|
|
|
fn validate_session_data_tags(&self) -> crate::Result<()> {
|
|
let mut set = HashSet::new();
|
|
|
|
if let Some(value) = &self.session_data {
|
|
set.reserve(value.len());
|
|
|
|
for t in value {
|
|
if !set.insert((t.data_id(), t.language())) {
|
|
return Err(Error::custom(format!("Conflict: {}", t)));
|
|
}
|
|
}
|
|
}
|
|
|
|
Ok(())
|
|
}
|
|
|
|
fn check_media_group<T: AsRef<str>>(&self, media_type: MediaType, group_id: T) -> bool {
|
|
if let Some(value) = &self.media {
|
|
value
|
|
.iter()
|
|
.any(|t| t.media_type() == media_type && t.group_id().as_str() == group_id.as_ref())
|
|
} else {
|
|
false
|
|
}
|
|
}
|
|
}
|
|
|
|
impl RequiredVersion for MasterPlaylistBuilder {
|
|
fn required_version(&self) -> ProtocolVersion {
|
|
// TODO: the .flatten() can be removed as soon as `recursive traits` are
|
|
// supported. (RequiredVersion is implemented for Option<T>, but
|
|
// not for Option<Option<T>>)
|
|
// https://github.com/rust-lang/chalk/issues/12
|
|
required_version![
|
|
self.independent_segments.flatten(),
|
|
self.start.flatten(),
|
|
self.media,
|
|
self.variants,
|
|
self.session_data,
|
|
self.session_keys
|
|
]
|
|
}
|
|
}
|
|
|
|
impl fmt::Display for MasterPlaylist {
|
|
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
|
|
writeln!(f, "{}", ExtM3u)?;
|
|
|
|
if self.required_version() != ProtocolVersion::V1 {
|
|
writeln!(f, "{}", ExtXVersion::new(self.required_version()))?;
|
|
}
|
|
|
|
for value in &self.media {
|
|
writeln!(f, "{}", value)?;
|
|
}
|
|
|
|
for value in &self.variants {
|
|
writeln!(f, "{}", value)?;
|
|
}
|
|
|
|
for value in &self.session_data {
|
|
writeln!(f, "{}", value)?;
|
|
}
|
|
|
|
for value in &self.session_keys {
|
|
writeln!(f, "{}", value)?;
|
|
}
|
|
|
|
if let Some(value) = &self.independent_segments {
|
|
writeln!(f, "{}", value)?;
|
|
}
|
|
|
|
if let Some(value) = &self.start {
|
|
writeln!(f, "{}", value)?;
|
|
}
|
|
|
|
for value in &self.unknown_tags {
|
|
writeln!(f, "{}", value)?;
|
|
}
|
|
|
|
Ok(())
|
|
}
|
|
}
|
|
|
|
impl FromStr for MasterPlaylist {
|
|
type Err = Error;
|
|
|
|
fn from_str(input: &str) -> Result<Self, Self::Err> {
|
|
let input = tag(input, ExtM3u::PREFIX)?;
|
|
let mut builder = Self::builder();
|
|
|
|
let mut media = vec![];
|
|
let mut variants = vec![];
|
|
let mut session_data = vec![];
|
|
let mut session_keys = vec![];
|
|
let mut unknown_tags = vec![];
|
|
|
|
for line in Lines::from(input) {
|
|
match line? {
|
|
Line::Tag(tag) => {
|
|
match tag {
|
|
Tag::ExtXVersion(_) => {
|
|
// This tag can be ignored, because the
|
|
// MasterPlaylist will automatically set the
|
|
// ExtXVersion tag to the minimum required version
|
|
// TODO: this might be verified?
|
|
}
|
|
Tag::ExtInf(_)
|
|
| Tag::ExtXByteRange(_)
|
|
| Tag::ExtXDiscontinuity(_)
|
|
| Tag::ExtXKey(_)
|
|
| Tag::ExtXMap(_)
|
|
| Tag::ExtXProgramDateTime(_)
|
|
| Tag::ExtXDateRange(_)
|
|
| Tag::ExtXTargetDuration(_)
|
|
| Tag::ExtXMediaSequence(_)
|
|
| Tag::ExtXDiscontinuitySequence(_)
|
|
| Tag::ExtXEndList(_)
|
|
| Tag::ExtXPlaylistType(_)
|
|
| Tag::ExtXIFramesOnly(_) => {
|
|
return Err(Error::custom(format!(
|
|
"This tag isn't allowed in a master playlist: {}",
|
|
tag
|
|
)));
|
|
}
|
|
Tag::ExtXMedia(t) => {
|
|
media.push(t);
|
|
}
|
|
Tag::VariantStream(t) => {
|
|
variants.push(t);
|
|
}
|
|
Tag::ExtXSessionData(t) => {
|
|
session_data.push(t);
|
|
}
|
|
Tag::ExtXSessionKey(t) => {
|
|
session_keys.push(t);
|
|
}
|
|
Tag::ExtXIndependentSegments(t) => {
|
|
builder.independent_segments(t);
|
|
}
|
|
Tag::ExtXStart(t) => {
|
|
builder.start(t);
|
|
}
|
|
_ => {
|
|
// [6.3.1. General Client Responsibilities]
|
|
// > ignore any unrecognized tags.
|
|
unknown_tags.push(tag.to_string());
|
|
}
|
|
}
|
|
}
|
|
Line::Uri(uri) => {
|
|
return Err(Error::custom(format!("Unexpected URI: {:?}", uri)));
|
|
}
|
|
_ => {}
|
|
}
|
|
}
|
|
|
|
builder.media(media);
|
|
builder.variants(variants);
|
|
builder.session_data(session_data);
|
|
builder.session_keys(session_keys);
|
|
builder.unknown_tags(unknown_tags);
|
|
|
|
builder.build().map_err(Error::builder)
|
|
}
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::*;
|
|
use crate::types::StreamData;
|
|
use pretty_assertions::assert_eq;
|
|
|
|
#[test]
|
|
fn test_parser() {
|
|
assert_eq!(
|
|
concat!(
|
|
"#EXTM3U\n",
|
|
"#EXT-X-STREAM-INF:",
|
|
"BANDWIDTH=150000,CODECS=\"avc1.42e00a,mp4a.40.2\",RESOLUTION=416x234\n",
|
|
"http://example.com/low/index.m3u8\n",
|
|
"#EXT-X-STREAM-INF:",
|
|
"BANDWIDTH=240000,CODECS=\"avc1.42e00a,mp4a.40.2\",RESOLUTION=416x234\n",
|
|
"http://example.com/lo_mid/index.m3u8\n",
|
|
"#EXT-X-STREAM-INF:",
|
|
"BANDWIDTH=440000,CODECS=\"avc1.42e00a,mp4a.40.2\",RESOLUTION=416x234\n",
|
|
"http://example.com/hi_mid/index.m3u8\n",
|
|
"#EXT-X-STREAM-INF:",
|
|
"BANDWIDTH=640000,CODECS=\"avc1.42e00a,mp4a.40.2\",RESOLUTION=640x360\n",
|
|
"http://example.com/high/index.m3u8\n",
|
|
"#EXT-X-STREAM-INF:BANDWIDTH=64000,CODECS=\"mp4a.40.5\"\n",
|
|
"http://example.com/audio/index.m3u8\n"
|
|
)
|
|
.parse::<MasterPlaylist>()
|
|
.unwrap(),
|
|
MasterPlaylist::builder()
|
|
.variants(vec![
|
|
VariantStream::ExtXStreamInf {
|
|
uri: "http://example.com/low/index.m3u8".into(),
|
|
frame_rate: None,
|
|
audio: None,
|
|
subtitles: None,
|
|
closed_captions: None,
|
|
stream_data: StreamData::builder()
|
|
.bandwidth(150000)
|
|
.codecs("avc1.42e00a,mp4a.40.2")
|
|
.resolution((416, 234))
|
|
.build()
|
|
.unwrap()
|
|
},
|
|
VariantStream::ExtXStreamInf {
|
|
uri: "http://example.com/lo_mid/index.m3u8".into(),
|
|
frame_rate: None,
|
|
audio: None,
|
|
subtitles: None,
|
|
closed_captions: None,
|
|
stream_data: StreamData::builder()
|
|
.bandwidth(240000)
|
|
.codecs("avc1.42e00a,mp4a.40.2")
|
|
.resolution((416, 234))
|
|
.build()
|
|
.unwrap()
|
|
},
|
|
VariantStream::ExtXStreamInf {
|
|
uri: "http://example.com/hi_mid/index.m3u8".into(),
|
|
frame_rate: None,
|
|
audio: None,
|
|
subtitles: None,
|
|
closed_captions: None,
|
|
stream_data: StreamData::builder()
|
|
.bandwidth(440000)
|
|
.codecs("avc1.42e00a,mp4a.40.2")
|
|
.resolution((416, 234))
|
|
.build()
|
|
.unwrap()
|
|
},
|
|
VariantStream::ExtXStreamInf {
|
|
uri: "http://example.com/high/index.m3u8".into(),
|
|
frame_rate: None,
|
|
audio: None,
|
|
subtitles: None,
|
|
closed_captions: None,
|
|
stream_data: StreamData::builder()
|
|
.bandwidth(640000)
|
|
.codecs("avc1.42e00a,mp4a.40.2")
|
|
.resolution((640, 360))
|
|
.build()
|
|
.unwrap()
|
|
},
|
|
VariantStream::ExtXStreamInf {
|
|
uri: "http://example.com/audio/index.m3u8".into(),
|
|
frame_rate: None,
|
|
audio: None,
|
|
subtitles: None,
|
|
closed_captions: None,
|
|
stream_data: StreamData::builder()
|
|
.bandwidth(64000)
|
|
.codecs("mp4a.40.5")
|
|
.build()
|
|
.unwrap()
|
|
},
|
|
])
|
|
.build()
|
|
.unwrap()
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn test_display() {
|
|
assert_eq!(
|
|
MasterPlaylist::builder()
|
|
.variants(vec![
|
|
VariantStream::ExtXStreamInf {
|
|
uri: "http://example.com/low/index.m3u8".into(),
|
|
frame_rate: None,
|
|
audio: None,
|
|
subtitles: None,
|
|
closed_captions: None,
|
|
stream_data: StreamData::builder()
|
|
.bandwidth(150000)
|
|
.codecs("avc1.42e00a,mp4a.40.2")
|
|
.resolution((416, 234))
|
|
.build()
|
|
.unwrap()
|
|
},
|
|
VariantStream::ExtXStreamInf {
|
|
uri: "http://example.com/lo_mid/index.m3u8".into(),
|
|
frame_rate: None,
|
|
audio: None,
|
|
subtitles: None,
|
|
closed_captions: None,
|
|
stream_data: StreamData::builder()
|
|
.bandwidth(240000)
|
|
.codecs("avc1.42e00a,mp4a.40.2")
|
|
.resolution((416, 234))
|
|
.build()
|
|
.unwrap()
|
|
},
|
|
VariantStream::ExtXStreamInf {
|
|
uri: "http://example.com/hi_mid/index.m3u8".into(),
|
|
frame_rate: None,
|
|
audio: None,
|
|
subtitles: None,
|
|
closed_captions: None,
|
|
stream_data: StreamData::builder()
|
|
.bandwidth(440000)
|
|
.codecs("avc1.42e00a,mp4a.40.2")
|
|
.resolution((416, 234))
|
|
.build()
|
|
.unwrap()
|
|
},
|
|
VariantStream::ExtXStreamInf {
|
|
uri: "http://example.com/high/index.m3u8".into(),
|
|
frame_rate: None,
|
|
audio: None,
|
|
subtitles: None,
|
|
closed_captions: None,
|
|
stream_data: StreamData::builder()
|
|
.bandwidth(640000)
|
|
.codecs("avc1.42e00a,mp4a.40.2")
|
|
.resolution((640, 360))
|
|
.build()
|
|
.unwrap()
|
|
},
|
|
VariantStream::ExtXStreamInf {
|
|
uri: "http://example.com/audio/index.m3u8".into(),
|
|
frame_rate: None,
|
|
audio: None,
|
|
subtitles: None,
|
|
closed_captions: None,
|
|
stream_data: StreamData::builder()
|
|
.bandwidth(64000)
|
|
.codecs("mp4a.40.5")
|
|
.build()
|
|
.unwrap()
|
|
},
|
|
])
|
|
.build()
|
|
.unwrap()
|
|
.to_string(),
|
|
concat!(
|
|
"#EXTM3U\n",
|
|
//
|
|
"#EXT-X-STREAM-INF:",
|
|
"BANDWIDTH=150000,CODECS=\"avc1.42e00a,mp4a.40.2\",RESOLUTION=416x234\n",
|
|
"http://example.com/low/index.m3u8\n",
|
|
//
|
|
"#EXT-X-STREAM-INF:",
|
|
"BANDWIDTH=240000,CODECS=\"avc1.42e00a,mp4a.40.2\",RESOLUTION=416x234\n",
|
|
"http://example.com/lo_mid/index.m3u8\n",
|
|
//
|
|
"#EXT-X-STREAM-INF:",
|
|
"BANDWIDTH=440000,CODECS=\"avc1.42e00a,mp4a.40.2\",RESOLUTION=416x234\n",
|
|
"http://example.com/hi_mid/index.m3u8\n",
|
|
//
|
|
"#EXT-X-STREAM-INF:",
|
|
"BANDWIDTH=640000,CODECS=\"avc1.42e00a,mp4a.40.2\",RESOLUTION=640x360\n",
|
|
"http://example.com/high/index.m3u8\n",
|
|
//
|
|
"#EXT-X-STREAM-INF:BANDWIDTH=64000,CODECS=\"mp4a.40.5\"\n",
|
|
"http://example.com/audio/index.m3u8\n"
|
|
)
|
|
.to_string()
|
|
);
|
|
}
|
|
}
|