Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 0 additions & 20 deletions quest/m1/decode-priority.md

This file was deleted.

53 changes: 49 additions & 4 deletions rs/moq-audio/src/decode/consumer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -104,6 +108,7 @@ impl Default for Options {
delay: Delay::default(),
estimate: true,
start: Start::default(),
priority: hang::catalog::PRIORITY.audio,
}
}
}
Expand All @@ -124,6 +129,8 @@ impl Options {
pub struct Consumer {
decoder: Decoder,
track: moq_mux::container::Consumer<moq_mux::catalog::hang::Container>,
/// The subscription's preferences, for a priority change.
control: moq_net::track::Control,
resampler: Option<Resampler>,
/// Converts the decoded layout to the output's, when they differ.
remix: Option<Remix>,
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -289,6 +294,7 @@ impl Consumer {
stated,
decoder,
track,
control,
resampler: None,
remix,
options,
Expand Down Expand Up @@ -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.
///
Expand Down Expand Up @@ -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() {
Expand Down
4 changes: 3 additions & 1 deletion rs/moq-video/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
107 changes: 101 additions & 6 deletions rs/moq-video/src/decode/consumer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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()
}
Expand All @@ -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<Instant>,
Expand Down Expand Up @@ -176,9 +193,10 @@ impl Consumer {
name: impl Into<String>,
options: Options,
) -> Result<Self, Error> {
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,
})
Expand All @@ -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`]).
///
Expand Down Expand Up @@ -276,7 +306,7 @@ impl Reader {
catalog: &VideoConfig,
name: &str,
options: &Options,
) -> Result<Self, Error> {
) -> 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.
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down