Enum hls_m3u8::tags::VariantStream

pub enum VariantStream<'a> {
    ExtXIFrame {
        uri: Cow<'a, str>,
        stream_data: StreamData<'a>,
    },
    ExtXStreamInf {
        uri: Cow<'a, str>,
        frame_rate: Option<UFloat>,
        audio: Option<Cow<'a, str>>,
        subtitles: Option<Cow<'a, str>>,
        closed_captions: Option<ClosedCaptions<'a>>,
        stream_data: StreamData<'a>,
    },
}

A server may offer multiple MediaPlaylist files to provide different encodings of the same presentation.

If it does so, it should provide a MasterPlaylist that lists each VariantStream to allow clients to switch between encodings dynamically.

The server must meet the following constraints when producing VariantStreams in order to allow clients to switch between them seamlessly:

• Each VariantStream must present the same content.

• Matching content in VariantStreams must have matching timestamps. This allows clients to synchronize the media.

• Matching content in VariantStreams must have matching ExtXDiscontinuitySequence.

• Each MediaPlaylist in each VariantStream must have the same target duration. The only exceptions are subtitle renditions and MediaPlaylists containing an ExtXIFramesOnly tag, which may have different target durations if they have PlaylistType::Vod.

• Content that appears in a MediaPlaylist of one VariantStream but not in another must appear either at the beginning or at the end of the MediaPlaylist and must not be longer than the target duration.

• If any MediaPlaylists have an PlaylistType tag, all MediaPlaylists must have an PlaylistType tag with the same value.

• If the Playlist contains an PlaylistType tag with the value of VOD, the first segment of every MediaPlaylist in every VariantStream must start at the same media timestamp.

• If any MediaPlaylist in a MasterPlaylist contains an ExtXProgramDateTime tag, then all MediaPlaylists in that MasterPlaylist must contain ExtXProgramDateTime tags with consistent mappings of date and time to media timestamps.

• Each VariantStream must contain the same set of Date Ranges, each one identified by an ExtXDateRange tag(s) with the same ID attribute value and containing the same set of attribute/value pairs.

In addition, for broadest compatibility, VariantStreams should contain the same encoded audio bitstream. This allows clients to switch between VariantStreams without audible glitching.

Variants

ExtXIFrame

The VariantStream::ExtXIFrame variant identifies a MediaPlaylist file containing the I-frames of a multimedia presentation. It stands alone, in that it does not apply to a particular URI in the MasterPlaylist.

Fields of ExtXIFrame

uri: Cow<'a, str>

The URI identifies the I-frame MediaPlaylist file. That Playlist file must contain an ExtXIFramesOnly tag.

Note

This field is required.

stream_data: StreamData<'a>

Some fields are shared between VariantStream::ExtXStreamInf and VariantStream::ExtXIFrame.

Note

This field is optional.

ExtXStreamInf

VariantStream::ExtXStreamInf specifies a VariantStream, which is a set of renditions that can be combined to play the presentation.

Fields of ExtXStreamInf

uri: Cow<'a, str>

The URI specifies a MediaPlaylist that carries a rendition of the VariantStream. Clients that do not support multiple video renditions should play this rendition.

Note

This field is required.

frame_rate: Option<UFloat>

The value is an unsigned float describing the maximum frame rate for all the video in the VariantStream.

Note

Specifying the frame rate is optional, but is recommended if the VariantStream includes video. It should be specified if any video exceeds 30 frames per second.

audio: Option<Cow<'a, str>>

It indicates the set of audio renditions that should be used when playing the presentation.

It must match the value of the ExtXMedia::group_id of an ExtXMedia tag elsewhere in the MasterPlaylist whose ExtXMedia::media_type is MediaType::Audio.

Note

This field is optional.

subtitles: Option<Cow<'a, str>>

It indicates the set of subtitle renditions that can be used when playing the presentation.

It must match the value of the ExtXMedia::group_id of an ExtXMedia tag elsewhere in the MasterPlaylist whose ExtXMedia::media_type is MediaType::Subtitles.

Note

This field is optional.

closed_captions: Option<ClosedCaptions<'a>>

It indicates the set of closed-caption renditions that can be used when playing the presentation.

Note

This field is optional.

stream_data: StreamData<'a>

Some fields are shared between VariantStream::ExtXStreamInf and VariantStream::ExtXIFrame.

Note

This field is optional.

Implementations

impl<'a> VariantStream<'a>

pub fn is_associated(&self, media: &ExtXMedia<'_>) -> bool

Checks if a VariantStream and an ExtXMedia element are associated.

Example

use hls_m3u8::tags::{ExtXMedia, VariantStream};
use hls_m3u8::types::{ClosedCaptions, MediaType, StreamData};

let variant_stream = VariantStream::ExtXStreamInf {
    uri: "https://www.example.com/init.bin".into(),
    frame_rate: None,
    audio: Some("ag1".into()),
    subtitles: Some("sg1".into()),
    closed_captions: Some(ClosedCaptions::group_id("cc1")),
    stream_data: StreamData::builder()
        .bandwidth(1_110_000)
        .video("vg1")
        .build()
        .unwrap(),
};

assert!(variant_stream.is_associated(
    &ExtXMedia::builder()
        .media_type(MediaType::Audio)
        .group_id("ag1")
        .name("audio example")
        .build()
        .unwrap(),
));

pub fn into_owned(self) -> VariantStream<'static>

Makes the struct independent of its lifetime, by taking ownership of all internal Cows.

Note

This is a relatively expensive operation.

Methods from Deref<Target = StreamData<'a>>

pub fn bandwidth(&self) -> u64

The peak segment bitrate of the VariantStream in bits per second.

If all the MediaSegments in a VariantStream have already been created, the bandwidth value must be the largest sum of peak segment bitrates that is produced by any playable combination of renditions.

(For a VariantStream with a single MediaPlaylist, this is just the peak segment bit rate of that MediaPlaylist.)

An inaccurate value can cause playback stalls or prevent clients from playing the variant. If the MasterPlaylist is to be made available before all MediaSegments in the presentation have been encoded, the bandwidth value should be the bandwidth value of a representative period of similar content, encoded using the same settings.

Example

let mut stream = StreamData::new(20);

stream.set_bandwidth(5);
assert_eq!(stream.bandwidth(), 5);

Note

This field is required.

pub fn average_bandwidth(&self) -> Option<u64>

The average bandwidth of the stream in bits per second.

It represents the average segment bitrate of the VariantStream. If all the MediaSegments in a VariantStream have already been created, the average bandwidth must be the largest sum of average segment bitrates that is produced by any playable combination of renditions.

(For a VariantStream with a single MediaPlaylist, this is just the average segment bitrate of that MediaPlaylist.)

An inaccurate value can cause playback stalls or prevent clients from playing the variant. If the MasterPlaylist is to be made available before all MediaSegments in the presentation have been encoded, the average bandwidth should be the average bandwidth of a representative period of similar content, encoded using the same settings.

Example

let mut stream = StreamData::new(20);

stream.set_average_bandwidth(Some(300));
assert_eq!(stream.average_bandwidth(), Some(300));

Note

This field is optional.

pub fn codecs(&self) -> Option<&Codecs<'a>>

A list of formats, where each format specifies a media sample type that is present in one or more renditions specified by the VariantStream.

Valid format identifiers are those in the ISO Base Media File Format Name Space defined by “The ‘Codecs’ and ‘Profiles’ Parameters for “Bucket” Media Types“ (RFC6381).

For example, a stream containing AAC low complexity (AAC-LC) audio and H.264 Main Profile Level 3.0 video would be

let codecs = Codecs::from(&["mp4a.40.2", "avc1.4d401e"]);

Example

use hls_m3u8::types::Codecs;

let mut stream = StreamData::new(20);

stream.set_codecs(Some(&["mp4a.40.2", "avc1.4d401e"]));
assert_eq!(
    stream.codecs(),
    Some(&Codecs::from(&["mp4a.40.2", "avc1.4d401e"]))
);

Note

This field is optional, but every instance of VariantStream::ExtXStreamInf should include a codecs attribute.

pub fn resolution(&self) -> Option<Resolution>

The resolution of the stream.

Example

use hls_m3u8::types::Resolution;

let mut stream = StreamData::new(20);

stream.set_resolution(Some((1920, 1080)));
assert_eq!(stream.resolution(), Some(Resolution::new(1920, 1080)));

Note

This field is optional, but it is recommended if the VariantStream includes video.

pub fn hdcp_level(&self) -> Option<HdcpLevel>

High-bandwidth Digital Content Protection level of the VariantStream.

Example

use hls_m3u8::types::HdcpLevel;
let mut stream = StreamData::new(20);

stream.set_hdcp_level(Some(HdcpLevel::None));
assert_eq!(stream.hdcp_level(), Some(HdcpLevel::None));

Note

This field is optional.

pub fn video(&self) -> Option<&Cow<'a, str>>

It indicates the set of video renditions, that should be used when playing the presentation.

It must match the value of the ExtXMedia::group_id attribute ExtXMedia tag elsewhere in the MasterPlaylist whose ExtXMedia::media_type attribute is video. It indicates the set of video renditions that should be used when playing the presentation.

Example

let mut stream = StreamData::new(20);

stream.set_video(Some("video_01"));
assert_eq!(stream.video(), Some(&"video_01".into()));

Note

This field is optional.

Trait Implementations

impl<'a> Clone for VariantStream<'a>

fn clone(&self) -> VariantStream<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for VariantStream<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Deref for VariantStream<'a>

type Target = StreamData<'a>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'a> Display for VariantStream<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Hash for VariantStream<'a>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<'a> Ord for VariantStream<'a>

fn cmp(&self, other: &VariantStream<'a>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<'a> PartialEq<&'_ VariantStream<'a>> for VariantStream<'a>

fn eq(&self, other: &&Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<'a> PartialEq<VariantStream<'a>> for VariantStream<'a>

fn eq(&self, other: &VariantStream<'a>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &VariantStream<'a>) -> bool

This method tests for !=.

impl<'a> PartialOrd<VariantStream<'a>> for VariantStream<'a>

fn partial_cmp(&self, other: &VariantStream<'a>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a> TryFrom<&'a str> for VariantStream<'a>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(input: &'a str) -> Result<Self, Self::Error>

Performs the conversion.

impl<'a> Eq for VariantStream<'a>

impl<'a> StructuralEq for VariantStream<'a>

impl<'a> StructuralPartialEq for VariantStream<'a>