diff --git a/quest/m1/decode-priority.md b/quest/m1/decode-priority.md deleted file mode 100644 index 3c04c3ca3f..0000000000 --- a/quest/m1/decode-priority.md +++ /dev/null @@ -1,20 +0,0 @@ -# [S] Decode consumers take a subscription priority - -## Goal - -`moq_video::decode::Options` and `moq_audio::decode::Options` carry the -subscription priority their consumer fetches at, defaulting to hang's -`PRIORITY.video` and `PRIORITY.audio` as fixed today, so a player can fetch a -less important source behind a more important one under congestion. - -## Plan - -Each consumer hardcodes hang's priority for its kind today -(`rs/moq-video/src/decode/consumer.rs`, and its audio twin). Recommended: a -consumer that changes its priority while running updates its subscription in -place rather than resubscribing. Prove it with a test that reads the -priority off the publisher's aggregate subscription. - -Needed by [the studio's viewer priorities](https://github.com/moq-dev/studio/blob/main/quest/m2/compose/controls.md), -found by [moq-dev/studio#218](https://github.com/moq-dev/studio/pull/218), -and by [moq play composites layers](/quest/m3/layers/play.md). diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index dc01d7e2c7..248a569c4f 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -94,6 +94,10 @@ pub struct Options { pub estimate: bool, /// Initial cached-group policy. pub start: Start, + /// The subscription priority, ordering this track against the others on the session under + /// congestion: higher is sent first. Defaults to hang's `PRIORITY.audio`; + /// [`Consumer::set_priority`] moves it while running. + pub priority: i8, } impl Default for Options { @@ -104,6 +108,7 @@ impl Default for Options { delay: Delay::default(), estimate: true, start: Start::default(), + priority: hang::catalog::PRIORITY.audio, } } } @@ -124,6 +129,8 @@ impl Options { pub struct Consumer { decoder: Decoder, track: moq_mux::container::Consumer, + /// The subscription's preferences, for a priority change. + control: moq_net::track::Control, resampler: Option, /// Converts the decoded layout to the output's, when they differ. remix: Option, @@ -243,10 +250,7 @@ impl Consumer { // max too, so a narrower one while joining would drop the groups queued behind a reader // slow to take its first, and the publisher should never see a stated zero min first. let mut subscriber = track - .subscribe( - playout - .subscription(moq_net::track::Subscription::default().with_priority(hang::catalog::PRIORITY.audio)), - ) + .subscribe(playout.subscription(moq_net::track::Subscription::default().with_priority(options.priority))) .await?; // Latest skips cached history; a warmup is primed by trimming the newest group's // start, like any other join. Move the local cursor, not Subscription::ranges: the @@ -259,6 +263,7 @@ impl Consumer { { subscriber = subscriber.with_range(live_edge.group..); } + let control = subscriber.control(); let track = subscriber; let max_age = track.info().max_age; let max_delay = options @@ -289,6 +294,7 @@ impl Consumer { stated, decoder, track, + control, resampler: None, remix, options, @@ -348,6 +354,17 @@ impl Consumer { self.max_delay = max.min(self.max_age.unwrap_or(std::time::Duration::MAX)); } + /// Move [`Options::priority`] mid-stream, updating the subscription in place rather than + /// resubscribing, so nothing already fetched is dropped or fetched again. + pub fn set_priority(&mut self, priority: i8) { + self.options.priority = priority; + let subscription = self.control.subscription(); + if subscription.priority != priority { + // Closed only once the track ended, when there is nothing left to prioritize. + let _ = self.control.update(subscription.with_priority(priority)); + } + } + /// The playout delay to hold ahead of the playhead right now: the fixed /// [`Delay::min`], or with [`Options::estimate`] the estimate from every frame read so far. /// @@ -1065,6 +1082,34 @@ mod tests { ); } + /// The priority reaches the publisher's aggregate subscription at hang's audio default, and a + /// change moves that subscription in place, keeping the moved delay with it. + #[tokio::test(start_paused = true)] + async fn priority_reaches_the_subscription_and_moves_in_place() { + let broadcast = moq_net::broadcast::Info::new().produce(); + let track = broadcast + .create_track("audio", hang::container::track_info(hang::catalog::PRIORITY.audio)) + .unwrap(); + let catalog = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Pcm, 48_000, 1); + let mut consumer = Consumer::new(&broadcast.consume(), &catalog, "audio", Options::new()) + .await + .unwrap(); + assert_eq!( + track.subscription().map(|sub| sub.priority), + Some(hang::catalog::PRIORITY.audio) + ); + + consumer.set_priority(-20); + assert_eq!(consumer.options().priority, -20); + assert_eq!(track.subscription().map(|sub| sub.priority), Some(-20)); + + // A later delay change rewrites the subscription without undoing the priority. + consumer.set_max_delay(Duration::from_secs(2)); + let subscription = track.subscription().unwrap(); + assert_eq!(subscription.priority, -20); + assert_eq!(subscription.delay.max, Some(Duration::from_secs(2))); + } + /// A moved max delay reaches the subscription, plus the warmup, clamped to the max age. #[tokio::test(start_paused = true)] async fn a_moved_max_delay_reaches_the_subscription() { diff --git a/rs/moq-video/README.md b/rs/moq-video/README.md index 5cf21a3266..a1c6bb9b11 100644 --- a/rs/moq-video/README.md +++ b/rs/moq-video/README.md @@ -247,7 +247,9 @@ for captured frames. `decode::Config::scale_hint` asks a decoder with a hardware `Frame::resize` for the exact size. `decode::Consumer` takes `decode::Options`, which pairs that config with the subscription's `start` and `delay`: a `decode::Delay` whose `min` is your playout delay, where a cold join starts, and -whose `max` is how far behind the live edge a stalled group may fall. +whose `max` is how far behind the live edge a stalled group may fall. Its +`priority` (hang's video priority by default) orders the track against others on +the session under congestion, and `decode::Consumer::set_priority` moves it in place. `decode::Consumer::arrival` reports when the access unit behind the latest picture arrived, even when the decoder reordered or held it back, so a player can feed a playout clock or split latency into network and decode time. diff --git a/rs/moq-video/src/decode/consumer.rs b/rs/moq-video/src/decode/consumer.rs index ae1df6460c..83ca8d7efd 100644 --- a/rs/moq-video/src/decode/consumer.rs +++ b/rs/moq-video/src/decode/consumer.rs @@ -79,11 +79,15 @@ pub enum Start { /// /// `#[non_exhaustive]`: build via [`Options::new`] (or `default()`) and set the /// fields, so future knobs don't break callers. -#[derive(Clone, Debug, Default)] +#[derive(Clone, Debug)] #[non_exhaustive] pub struct Options { /// The decoder: backend, output representation, scaling hint. pub decoder: Config, + /// The subscription priority, ordering this track against the others on the session under + /// congestion: higher is sent first. Defaults to hang's `PRIORITY.video`; + /// [`Consumer::set_priority`] moves it while running. + pub priority: i8, /// Where to start on a track that already holds groups. pub start: Start, /// How far behind the live edge playback runs. [`Delay::min`] is the @@ -96,8 +100,19 @@ pub struct Options { pub delay: Delay, } +impl Default for Options { + fn default() -> Self { + Self { + decoder: Config::default(), + priority: hang::catalog::PRIORITY.video, + start: Start::default(), + delay: Delay::default(), + } + } +} + impl Options { - /// Defaults: a default [`Config`], every cached group, real-time latency. + /// Defaults: a default [`Config`], hang's video priority, every cached group, real-time latency. pub fn new() -> Self { Self::default() } @@ -111,6 +126,8 @@ impl Options { /// `moq_audio::decode::Consumer`. pub struct Consumer { slot: Slot, + /// The subscription's preferences, reachable while a read holds the reader. + control: moq_net::track::Control, name: String, /// When the access unit behind the latest picture returned arrived. arrival: Option, @@ -176,9 +193,10 @@ impl Consumer { name: impl Into, options: Options, ) -> Result { - let reader = Reader::open(broadcast, catalog, &name.into(), &options).await?; + let (reader, control) = Reader::open(broadcast, catalog, &name.into(), &options).await?; Ok(Self { name: reader.decoder.name().to_owned(), + control, slot: Slot::Idle(Box::new(reader)), arrival: None, }) @@ -189,6 +207,18 @@ impl Consumer { &self.name } + /// Move the subscription priority mid-stream, updating the subscription in place + /// rather than resubscribing, so nothing already fetched is dropped or fetched again. + /// + /// A read in flight is unaffected; an ended track ignores it. + pub fn set_priority(&mut self, priority: i8) { + let subscription = self.control.subscription(); + if subscription.priority != priority { + // Closed only once the track ended, when there is nothing left to prioritize. + let _ = self.control.update(subscription.with_priority(priority)); + } + } + /// When the access unit behind the latest picture [`read`](Self::read) returned /// landed in this node's cache ([`moq_mux::container::Consumer::arrival`]). /// @@ -276,7 +306,7 @@ impl Reader { catalog: &VideoConfig, name: &str, options: &Options, - ) -> Result { + ) -> Result<(Self, moq_net::track::Control), Error> { let decoder = Sink::open(catalog, &options.decoder).await.map_err(|err| match err { // Only a codec or description this build cannot decode is a refusal of the // rendition. Backend and worker faults keep their own variants. @@ -289,7 +319,7 @@ impl Reader { // The whole delay from the first request, as the container keeps it, so the publisher // never sees a stated zero min before the container's update. let mut subscription = - playout.subscription(moq_net::track::Subscription::default().with_priority(hang::catalog::PRIORITY.video)); + playout.subscription(moq_net::track::Subscription::default().with_priority(options.priority)); // A decoder often opens on a track that is already cached: a replacement decoder // subscribes while its predecessor still holds groups, and a rendition switched away from // and back to stays warm on the origin for `moq_net::model::track::IDLE_LINGER` (cached @@ -313,6 +343,7 @@ impl Reader { if options.start == Start::Latest { subscriber.largest().await; } + let control = subscriber.control(); let track = subscriber; // The catalog says how the track is framed, and it is not always the legacy // wire: `moq import fmp4` publishes CMAF. Reading a moof+mdat fragment as a @@ -331,7 +362,7 @@ impl Reader { recover: true, leading_floor: None, }; - Ok(reader) + Ok((reader, control)) } /// The next item this decoder alone produces, with its access unit's arrival @@ -717,6 +748,69 @@ mod tests { ); } + /// The priority reaches the publisher's aggregate subscription at hang's video default, and a + /// change while a read waits moves that subscription in place: the waiting read still gets + /// the next picture. + #[tokio::test] + async fn priority_reaches_the_subscription_and_moves_in_place() { + let broadcast = moq_net::broadcast::Info::new().produce(); + let track = broadcast + .create_track("video", hang::container::track_info(hang::catalog::PRIORITY.video)) + .unwrap(); + let published = track.clone(); + let subscriber = broadcast.consume(); + let mut producer = moq_mux::container::Producer::new( + track, + moq_mux::catalog::hang::Container::Legacy(moq_mux::container::Kind::Data), + ); + let catalog = VideoConfig::new(hang::catalog::H264 { + inline: true, + profile: 0x42, + constraints: 0, + level: 30, + }); + let options = Options { + decoder: Config { + kind: Kind::Named(probe::BUFFERED_NAME.into()), + ..Config::new() + }, + ..Options::new() + }; + let mut consumer = Consumer::new(&subscriber, &catalog, "video", options).await.unwrap(); + assert_eq!( + published.subscription().map(|sub| sub.priority), + Some(hang::catalog::PRIORITY.video) + ); + + consumer.set_priority(10); + assert_eq!(published.subscription().map(|sub| sub.priority), Some(10)); + + // Park a read on the empty track, so the reader is held by the read in flight. + { + let read = consumer.read(); + tokio::pin!(read); + assert!(futures::poll!(read.as_mut()).is_pending()); + } + consumer.set_priority(-20); + assert_eq!(published.subscription().map(|sub| sub.priority), Some(-20)); + + producer + .write(moq_mux::container::Frame { + timestamp: Timestamp::from_micros(0).unwrap(), + duration: None, + payload: Bytes::from_static(b"access unit"), + keyframe: true, + }) + .unwrap(); + let _finished = producer.finish().unwrap(); + let frame = consumer + .next_frame() + .await + .unwrap() + .expect("the waiting read's picture"); + assert_eq!(frame.timestamp, Timestamp::from_micros(0).unwrap()); + } + /// The age budget is the subscription's and not the decoder's: it reaches /// the publisher through the track subscription, while the decoder opens /// with exactly the config it was handed. @@ -1462,6 +1556,7 @@ mod tests { }, start: Start::Latest, delay, + ..Options::new() }, )); // The open waits for the live edge with its subscription open, so the first aggregate