Skip to main content

moq_wasm/media/
catalog.rs

1use msf::Track;
2
3/// An independent draft-ietf-moq-msf-02 catalog (ยง5).
4#[derive(Debug, Clone, PartialEq)]
5pub struct Catalog {
6    catalog: msf::Catalog,
7}
8
9/// Which tracks `Catalog::select` takes: every field given must match.
10#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
11pub struct TrackQuery<'a> {
12    /// The `role`, such as `video`, `audio` or `eventtimeline`.
13    pub role: Option<&'a str>,
14    /// The `packaging`, such as `loc` or `eventtimeline`.
15    pub packaging: Option<&'a str>,
16    /// The codec string or its first element: `avc1` matches `avc1.42e01f`.
17    pub codec: Option<&'a str>,
18    /// Which matching track to take; `None` takes the first in the catalog.
19    pub prefer: Option<BitratePreference>,
20}
21
22/// Which bitrate `TrackQuery::prefer` picks. A track without a bitrate,
23/// which draft-ietf-moq-msf-02 requires only of audio and video, counts as
24/// the highest.
25#[derive(Debug, Clone, Copy, PartialEq, Eq)]
26pub enum BitratePreference {
27    Lowest,
28    Highest,
29}
30
31impl Catalog {
32    pub fn parse(payload: &[u8]) -> Result<Self, msf::CatalogParseError> {
33        Ok(Self {
34            catalog: msf::Catalog::parse(payload)?,
35        })
36    }
37
38    pub fn tracks(&self) -> &[Track] {
39        self.catalog.tracks.as_deref().unwrap_or_default()
40    }
41
42    pub fn select(&self, query: &TrackQuery) -> Option<&Track> {
43        let mut matching = self.tracks().iter().filter(|track| {
44            // A role or packaging is compared as it is written; an absent role is
45            // `null`, so it matches none.
46            query.role.is_none_or(|role| {
47                serde_json::to_value(&track.role).is_ok_and(|value| value == role)
48            }) && query.packaging.is_none_or(|packaging| {
49                serde_json::to_value(&track.packaging).is_ok_and(|value| value == packaging)
50            }) && query.codec.is_none_or(|codec| {
51                track
52                    .codec
53                    .as_deref()
54                    .is_some_and(|own| own == codec || own.split('.').next() == Some(codec))
55            })
56        });
57        let bitrate = |track: &&Track| track.bitrate.unwrap_or(u64::MAX);
58        match query.prefer {
59            None => matching.next(),
60            Some(BitratePreference::Lowest) => matching.min_by_key(bitrate),
61            Some(BitratePreference::Highest) => matching.max_by_key(bitrate),
62        }
63    }
64}
65
66#[cfg(test)]
67mod tests {
68    use super::*;
69
70    fn catalog() -> Catalog {
71        let payload = serde_json::json!({
72            "version": "draft-02",
73            "tracks": [
74                {"name": "video", "packaging": "loc", "role": "video", "isLive": true,
75                 "codec": "avc1.42e01f", "bitrate": 2_000_000, "width": 1280, "height": 720,
76                 "framerate": 30},
77                {"name": "video_low", "packaging": "loc", "role": "video", "isLive": true,
78                 "codec": "avc1.42e01e", "bitrate": 300_000, "width": 320, "height": 180,
79                 "framerate": 30},
80                {"name": "audio", "packaging": "loc", "role": "audio", "isLive": true,
81                 "codec": "opus", "bitrate": 64_000, "samplerate": 48_000,
82                 "channelConfig": "1"},
83            ],
84        });
85        Catalog::parse(payload.to_string().as_bytes()).unwrap()
86    }
87
88    #[test]
89    fn select_takes_the_first_match_or_the_preferred_bitrate() {
90        // Arrange
91        let catalog = catalog();
92        let video = |prefer| TrackQuery {
93            role: Some("video"),
94            prefer,
95            ..TrackQuery::default()
96        };
97
98        // Act
99        let first = catalog.select(&video(None));
100        let lowest = catalog.select(&video(Some(BitratePreference::Lowest)));
101        let highest = catalog.select(&video(Some(BitratePreference::Highest)));
102
103        // Assert
104        assert_eq!(first.map(|track| track.name.as_str()), Some("video"));
105        assert_eq!(lowest.map(|track| track.name.as_str()), Some("video_low"));
106        assert_eq!(highest.map(|track| track.name.as_str()), Some("video"));
107    }
108
109    #[test]
110    fn a_codec_matches_its_first_element_and_every_field_must_match() {
111        // Arrange
112        let catalog = catalog();
113
114        // Act
115        let by_codec = catalog.select(&TrackQuery {
116            codec: Some("opus"),
117            packaging: Some("loc"),
118            ..TrackQuery::default()
119        });
120        let avc = catalog.select(&TrackQuery {
121            codec: Some("avc1"),
122            role: Some("audio"),
123            ..TrackQuery::default()
124        });
125
126        // Assert
127        assert_eq!(by_codec.map(|track| track.name.as_str()), Some("audio"));
128        assert!(avc.is_none());
129    }
130}