Struct VideoLayout 

pub struct VideoLayout<'a> { /* private fields */ }

Corresponds to the #EXT-X-STREAM-INF:REQ-VIDEO-LAYOUT attribute.

See StreamInf for a link to the HLS documentation for this attribute.

The format described in HLS is an unordered, slash separated list of specifiers, where each specifier value is an enumerated string. Due to the specifiers being unordered, the values within a specifier must all share a common prefix. As of draft 18 there are two specifiers defined:

• Channel, prefixed with CH-
• Projection, prefixed with PROJ-

VideoLayout abstracts these nuances of syntax away and provides typed access to the values. To support forwards compatibility it also exposes any values with unknown prefixes via Self::unknown_entries. And at any stage the user has an escape hatch to the inner Cow<str> via Self::as_ref.

Implementations

impl<'a> VideoLayout<'a>

pub fn new( channels: impl Into<EnumeratedStringList<'a, VideoChannelSpecifier>>, projection: impl Into<EnumeratedStringList<'a, VideoProjectionSpecifier>>, ) -> Self

Construct a new VideoLayout.

Note that VideoChannelSpecifier and VideoProjectionSpecifier can be used directly here. For example:

let video_layout = VideoLayout::new(
    EnumeratedStringList::from([
        VideoChannelSpecifier::Stereo, VideoChannelSpecifier::Mono
    ]),
    EnumeratedStringList::from([VideoProjectionSpecifier::ParametricImmersive]),
);
assert_eq!("CH-STEREO,CH-MONO/PROJ-PRIM", video_layout.as_ref());

Since &str implements Into<EnumeratedStringList> we can also use string slice directly, but care should be taken to follow the correct format:

let video_layout = VideoLayout::new("CH-STEREO,CH-MONO", "PROJ-PRIM");
assert_eq!("CH-STEREO,CH-MONO/PROJ-PRIM", video_layout.as_ref());

The From<&str> implementation ensures that the order of specifiers does not impact the parsed value:

let layout_1 = VideoLayout::from("CH-STEREO,CH-MONO/PROJ-PRIM");
let layout_2 = VideoLayout::from("PROJ-PRIM/CH-STEREO,CH-MONO");
assert_eq!(layout_1.channels(), layout_2.channels());
assert_eq!(layout_1.projection(), layout_2.projection());
assert_eq!(2, layout_1.channels().iter().count());
assert!(layout_1.channels().contains(VideoChannelSpecifier::Stereo));
assert!(layout_1.channels().contains(VideoChannelSpecifier::Mono));
assert_eq!(1, layout_1.projection().iter().count());
assert!(layout_1.projection().contains(VideoProjectionSpecifier::ParametricImmersive));

impl VideoLayout<'_>

pub fn channels(&self) -> EnumeratedStringList<'_, VideoChannelSpecifier>

Defines the video channels.

This collects all specifiers who’s first element is prefixed with CH. The HLS specification stipulates that specifier values must all share the same prefix so checking the first value in the slash separated specifier is deemed enough. The EnumeratedStringList ensures that even invalid mixed members will be captured in the list, so information will not be lost.

Example:

let video_layout = VideoLayout::new("CH-STEREO,CH-MONO", "");
assert_eq!(2, video_layout.channels().iter().count());
assert!(video_layout.channels().contains(VideoChannelSpecifier::Stereo));
assert!(video_layout.channels().contains(VideoChannelSpecifier::Mono));
assert_eq!("CH-STEREO,CH-MONO", video_layout.as_ref());

Example with unknown specifier:

let video_layout = VideoLayout::new("CH-3D", "");
assert_eq!(1, video_layout.channels().iter().count());
assert!(video_layout.channels().contains("CH-3D"));
assert_eq!("CH-3D", video_layout.as_ref());

pub fn projection(&self) -> EnumeratedStringList<'_, VideoProjectionSpecifier>

Defines how a two-dimensional rectangular image must be transformed in order to display it faithfully to a viewer.

This collects all specifiers who’s first element is prefixed with PROJ. The HLS specification stipulates that specifier values must all share the same prefix so checking the first value in the slash separated specifier is deemed enough. The EnumeratedStringList ensures that even invalid mixed members will be captured in the list, so information will not be lost.

Example:

let video_layout = VideoLayout::new("", "PROJ-EQUI,PROJ-HEQU");
assert_eq!(2, video_layout.projection().iter().count());
assert!(video_layout.projection().contains(VideoProjectionSpecifier::Equirectangular));
assert!(video_layout.projection().contains(VideoProjectionSpecifier::HalfEquirectangular));
assert_eq!("PROJ-EQUI,PROJ-HEQU", video_layout.as_ref());

Example with unknown specifier:

let video_layout = VideoLayout::new("", "PROJ-360");
assert_eq!(1, video_layout.projection().iter().count());
assert!(video_layout.projection().contains("PROJ-360"));
assert_eq!("PROJ-360", video_layout.as_ref());

pub fn unknown_entries(&self) -> impl Iterator<Item = &str>

At the time of writing the HLS specification only defined 2 entries (described here via Self::channels and Self::projection). In case more entries are added later, this method will expose those as a split on '/', filtered to remove the channels and projection parts.

For example:

let video_layout = VideoLayout::from("CH-STEREO/NEURAL-INJECT/PROJ-PRIM");
let mut unknown = video_layout.unknown_entries();
assert_eq!(Some("NEURAL-INJECT"), unknown.next());

Trait Implementations

impl AsRef<str> for VideoLayout<'_>

fn as_ref(&self) -> &str

Converts this type into a shared reference of the (usually inferred) input type.

impl<'a> Clone for VideoLayout<'a>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for VideoLayout<'a>

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

Formats the value using the given formatter.

impl Display for VideoLayout<'_>

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

Formats the value using the given formatter.

impl<'a> From<&'a str> for VideoLayout<'a>

fn from(value: &'a str) -> Self

Converts to this type from the input type.

impl<'a> From<VideoLayout<'a>> for Cow<'a, str>

fn from(value: VideoLayout<'a>) -> Self

Converts to this type from the input type.

impl<'a> PartialEq for VideoLayout<'a>

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> StructuralPartialEq for VideoLayout<'a>