diff --git a/quest/m1/README.md b/quest/m1/README.md index 19d5d1a11a7..2a4368d685f 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -174,7 +174,6 @@ removed). - [Bindings name every session code](/quest/m1/ffi-malformed-auth-kind.md) - MALFORMED_AUTH_TOKEN and its siblings reach moq-ffi, moq-c, and the wrappers - [Unbounded groups](/quest/m1/unbounded-groups/README.md) - groups and frames lose their size caps; the cache sheds parts of a group under pressure and refills the holes in place - [Next Object on a cold Rust copy](/quest/m1/next-object-cold-copy.md) - a join after an upstream group report starts at the first frame received, never skipping -- [An HLS viewer starts capture](/quest/m1/hls-record-demand.md) - a record-track subscriber counts as demand for its rendition's media - [gofmt-clean Go wrapper](/quest/m1/go-gofmt.md) - `just go check` fails on unformatted Go - [moqsrc max-delay](/quest/m1/gst-max-delay.md) - GStreamer's `moqsrc` takes a `max-delay` property instead of a hard-coded 1 s budget - [JS SETUP rejection ownership](/quest/m1/js-setup-rejection.md) - reproduce an unhandled version-refusal rejection without weakening the refusal diff --git a/quest/m1/eager-encode/README.md b/quest/m1/eager-encode/README.md index 1c603311649..748457cbe88 100644 --- a/quest/m1/eager-encode/README.md +++ b/quest/m1/eager-encode/README.md @@ -45,8 +45,7 @@ The epic's own work, once the children land: replay = local subscriber"), [iOS capture](/quest/m2/mobile-capture-ios.md), [video hardware](/quest/m3/video-hardware.md), and [time-addressed consumers](/quest/m1/time-addressing/consumers.md)'s - HLS-only-viewer clause. [An HLS viewer starts capture](/quest/m1/hls-record-demand.md) - narrows to the opt-in mode. + HLS-only-viewer clause. ## Required diff --git a/quest/m1/hls-record-demand.md b/quest/m1/hls-record-demand.md deleted file mode 100644 index 9e64910044c..00000000000 --- a/quest/m1/hls-record-demand.md +++ /dev/null @@ -1,26 +0,0 @@ -# [S] An HLS viewer starts capture - -## Goal - -`moq publish` starts capturing a rendition when its only subscriber is an HLS -export, so an HLS-only viewer gets media. - -## Plan - -Decided 2026-10-28 (maintainer), from -[moq-dev/moq#6937](https://github.com/moq-dev/moq/pull/6937), which made HLS -records on by default: a subscriber to a rendition's record track counts as -demand for that rendition's media. - -- `moq publish` encodes on demand from media-track demand - (`rs/moq-cli/src/publish.rs`), but the HLS export reads a rendition's - records before subscribing to its media, so the record subscriber alone - never starts capture. This was already true with `--hls` before #6937. -- Make record-track demand reach the media's demand where records are - produced (`rs/moq-mux/src/hls.rs`), so every on-demand publisher benefits, - not only the CLI. The demand ends when the record track's last subscriber - leaves. -- Test an HLS-only viewer against `moq publish`: capture starts and segments - appear. - -Public API: none expected. Wire: none. diff --git a/rs/moq-audio/src/encode/capture.rs b/rs/moq-audio/src/encode/capture.rs index 41d6464fbdc..23253b259f7 100644 --- a/rs/moq-audio/src/encode/capture.rs +++ b/rs/moq-audio/src/encode/capture.rs @@ -2501,7 +2501,7 @@ mod tests { [Open::Stream(input), Open::Stream(resumed)], ); let mut live = Vec::new(); - let mut records = None; + let mut hls = None; for samples in [&first, &second] { let mut track = fixture.subscribe().await; @@ -2509,15 +2509,12 @@ mod tests { drop(track); // The break is marked when the second run resumes, and its stop declares the unhinted // duration. - if records.is_none() && live.len() > 1 { - let hls = fixture.catalog.snapshot().audio.renditions["audio"] - .hls - .clone() - .expect("the audio track declares its HLS records once the first run stops"); - records = Some( - moq_mux::hls::Consumer::subscribe(&fixture.consumer, &hls) - .await - .unwrap(), + if hls.is_none() && live.len() > 1 { + hls = Some( + fixture.catalog.snapshot().audio.renditions["audio"] + .hls + .clone() + .expect("the audio track declares its HLS records once the first run stops"), ); } wait_for(&mut fixture.publication, Status::Waiting).await; @@ -2525,9 +2522,13 @@ mod tests { tokio::time::sleep(moq_mux::hls::DEFAULT_DURATION + Duration::from_millis(100)).await; } - let (mut catalog, _consumer) = fixture.finish().await; + let (mut catalog, consumer) = fixture.finish().await; catalog.finish().unwrap(); - let mut records = records.unwrap(); + // Read only now: a record reader is demand too, and would have kept the capture from + // idling between the runs. + let mut records = moq_mux::hls::Consumer::subscribe(&consumer, &hls.unwrap()) + .await + .unwrap(); let mut listed = Vec::new(); while let Some(event) = records.next().await.unwrap() { match event { diff --git a/rs/moq-mux/src/container/fmp4/import.rs b/rs/moq-mux/src/container/fmp4/import.rs index bb676a23ba0..0d51c7ddf40 100644 --- a/rs/moq-mux/src/container/fmp4/import.rs +++ b/rs/moq-mux/src/container/fmp4/import.rs @@ -489,7 +489,10 @@ impl Import { // Enroll every track for HLS records: passthrough writes groups by hand (no // `container::Producer`), so the recorder is fed directly at each fragment. - let recorder = self.catalog.enroll(track.name(), None)?; + let mut recorder = self.catalog.enroll(track.name(), None)?; + if let Some(recorder) = recorder.as_mut() { + recorder.lend(&track); + } // Whatever the descriptor declared (a bitrate) is authoritative; the rest is filled by // `estimate` as fragments arrive. diff --git a/rs/moq-mux/src/container/producer.rs b/rs/moq-mux/src/container/producer.rs index afc6802b9b8..65b92ab4846 100644 --- a/rs/moq-mux/src/container/producer.rs +++ b/rs/moq-mux/src/container/producer.rs @@ -425,8 +425,12 @@ where self } - /// Report each written group through `recorder` into the track's HLS records. - pub(crate) fn with_recorder(mut self, recorder: Option) -> Self { + /// Report each written group through `recorder` into the track's HLS records, whose readers + /// count as demand for this track. + pub(crate) fn with_recorder(mut self, mut recorder: Option) -> Self { + if let Some(recorder) = recorder.as_mut() { + recorder.lend(&self.inner); + } self.recorder = recorder; self } diff --git a/rs/moq-mux/src/hls.rs b/rs/moq-mux/src/hls.rs index f8ac8226880..a10420ea1e8 100644 --- a/rs/moq-mux/src/hls.rs +++ b/rs/moq-mux/src/hls.rs @@ -33,6 +33,10 @@ //! rendition's records and yields decoded [`Event`]s. On the wire each record track is a //! [`compress`](moq_net::track::Info::compress)ed [`moq_json::window`] whose groups restate the //! recent records. +//! +//! An edge reads only the records and fetches media per segment request, so it never subscribes to +//! the media. A record track's subscribers therefore count as demand for its media track: while +//! any remain, a local subscription keeps the media wanted, so an on-demand publisher produces it. use std::collections::{BTreeMap, VecDeque}; use std::sync::{Arc, Mutex}; @@ -589,7 +593,7 @@ impl Tracks { live } }; - Ok(Recorder { live }) + Ok(Recorder { live, lend: None }) } /// The record track and nominal duration advertised for `name`, once its duration is known. @@ -671,6 +675,75 @@ fn round(duration: Duration) -> Duration { Duration::from_millis(units(duration)) } +/// Lends a record track's demand to its media track: while anyone subscribes to the records, a +/// local subscription keeps the media wanted, so an on-demand publisher produces the media that an +/// HLS export, which reads only the records, describes and fetches. +/// +/// Driven by the record track's wakeups rather than a task, since nothing here owns a runtime. A +/// wake polls inline on the waking thread, reading the record track, so it relies on kio and +/// moq-net waking a track's waiters only once its lock is released. The waker holds this weakly, so +/// dropping the [`Recorder`] ends the subscription and the registration together. Both track +/// handles are weak, so neither keeps its track open. +struct Lend { + records: moq_net::track::Demand, + media: moq_net::track::Consumer, + /// The subscription held while the records are wanted. Never polled: holding it is the demand. + held: Option, + waiter: kio::Waiter, +} + +impl Lend { + fn new(records: moq_net::track::Demand, media: moq_net::track::Consumer) -> Arc> { + let lend = Arc::new_cyclic(|weak| { + let waker = std::task::Waker::from(Arc::new(LendWaker(weak.clone()))); + Mutex::new(Self { + records, + media, + held: None, + waiter: kio::Waiter::new(waker), + }) + }); + Self::poll(&lend); + lend + } + + /// Follow the record track's demand until it next changes. + fn poll(lend: &Mutex) { + let mut lend = lend.lock().unwrap(); + let lend = &mut *lend; + loop { + match lend.records.poll_wanted_changed(&lend.waiter) { + Poll::Pending => return, + Poll::Ready(Ok(Some(_))) => { + if lend.held.is_none() { + lend.held = Some(lend.media.subscribe(None).into_inner()); + } + } + Poll::Ready(Ok(None)) => lend.held = None, + Poll::Ready(Err(_)) => { + lend.held = None; + return; + } + } + } + } +} + +/// Re-polls a [`Lend`] when its record track's demand changes. +struct LendWaker(std::sync::Weak>); + +impl std::task::Wake for LendWaker { + fn wake(self: Arc) { + self.wake_by_ref(); + } + + fn wake_by_ref(self: &Arc) { + if let Some(lend) = self.0.upgrade() { + Lend::poll(&lend); + } + } +} + /// Reports one track's frames into its live record track. /// /// Move-only: it is the track's reporting handle, minted by [`Tracks::track`] and held by a @@ -678,9 +751,23 @@ fn round(duration: Duration) -> Duration { /// segment; the record track stays open until [`Tracks::finish`]. pub(crate) struct Recorder { live: Arc>, + /// Lends the record track's demand to the media track, once [`Self::lend`] names it. + lend: Option>>, } impl Recorder { + /// Keep `media`, the track this recorder reports, wanted while anyone subscribes to its + /// records, so an HLS export that reads only the records still starts an on-demand publisher. + /// The demand ends when the record track's last subscriber leaves, or this recorder drops. + pub fn lend(&mut self, media: &moq_net::track::Producer) { + let records = { + let live = self.live.lock().unwrap(); + live.output.as_ref().map(|output| output.track.demand()) + }; + // A record track that already failed has no readers to lend for. + self.lend = records.map(|records| Lend::new(records, media.consume())); + } + /// The track's fixed nominal segment duration, once known. pub fn declared(&self) -> Option { self.live.lock().unwrap().segmenter.declared() @@ -1181,6 +1268,64 @@ mod test { assert_eq!(records, [(0, 0, false), (1, 1, true), (2, 0, false), (3, 1, true)]); } + /// A record track's readers are demand for its media, so an HLS export, which subscribes only to + /// the records, starts an on-demand publisher, and its leaving stops it. + #[tokio::test] + async fn record_readers_want_the_media() { + let broadcast = moq_net::broadcast::Info::new().produce(); + let media = broadcast.create_track("video", None).unwrap(); + let demand = media.demand(); + let tracks = Tracks::new(&broadcast); + let mut recorder = tracks.track("video", hinted()).unwrap(); + recorder.lend(&media); + assert_eq!(demand.wanted(), None, "nobody reads the records yet"); + + let hls = tracks.hls("video").unwrap(); + let records = Consumer::subscribe(&broadcast.consume(), &hls).await.unwrap(); + assert!(demand.wanted().is_some(), "a record reader wants the media"); + let again = Consumer::subscribe(&broadcast.consume(), &hls).await.unwrap(); + drop(records); + assert!(demand.wanted().is_some(), "another reader remains"); + drop(again); + assert_eq!(demand.wanted(), None, "the last reader left"); + + // Dropping the recorder ends the lend, even with a reader still on the records. + let _records = Consumer::subscribe(&broadcast.consume(), &hls).await.unwrap(); + assert!(demand.wanted().is_some()); + drop(recorder); + assert_eq!(demand.wanted(), None, "the recorder is gone"); + } + + /// A join over the record track's refresh ratio is answered by the next record's fresh group, + /// whose demand wake reaches the lend only once the track's lock is released, not under it. + #[tokio::test] + async fn a_refreshing_join_keeps_lending() { + let broadcast = moq_net::broadcast::Info::new().produce(); + let media = broadcast.create_track("video", None).unwrap(); + let demand = media.demand(); + let tracks = Tracks::new(&broadcast); + let mut recorder = tracks.track("video", hinted()).unwrap(); + recorder.lend(&media); + + let hls = tracks.hls("video").unwrap(); + let _first = Consumer::subscribe(&broadcast.consume(), &hls).await.unwrap(); + // Enough records that a join outweighs the refresh ratio and asks for a fresh group. + for group in 0..64 { + recorder.frame(group, ms(group * 4_000)); + } + let records = broadcast.consume().track("video.hls").unwrap(); + let before = records.subscribe(None).await.unwrap().largest().await; + let _late = Consumer::subscribe(&broadcast.consume(), &hls).await.unwrap(); + recorder.frame(64, ms(64 * 4_000)); + + let after = records.subscribe(None).await.unwrap().largest().await; + assert!( + after.map(|at| at.group) > before.map(|at| at.group), + "the join was answered with a fresh group" + ); + assert!(demand.wanted().is_some(), "the readers still want the media"); + } + #[test] fn a_taken_record_track_name_fails_enrollment() { let broadcast = moq_net::broadcast::Info::new().produce(); diff --git a/rs/moq-net/src/model/track.rs b/rs/moq-net/src/model/track.rs index 5c059498871..b0029e4fa99 100644 --- a/rs/moq-net/src/model/track.rs +++ b/rs/moq-net/src/model/track.rs @@ -489,6 +489,10 @@ pub(crate) struct TrackState { // Kept here (rather than threaded through every handle) so any holder reaches it. subscriptions: kio::Lock, + // Demand wakes a write owes, fired once the state guard is released (see + // [`Self::deferred`]). A woken waker may read this track, so none fires under its lock. + deferred: Vec, + // The fills readers queued for groups they miss (see [`Fill`]), same reasoning: a miss // queues here and a `Requests` drains. fills: kio::Shared, @@ -1902,11 +1906,21 @@ impl TrackState { /// changes it, even one below a reached end. /// /// `answers` when it is a group subscribers receive, which answers a pending refresh. + /// + /// The demand wakes it owes wait in [`Self::deferred`] for the caller to fire once its guard + /// is released. fn advance(&mut self, sequence: u64, answers: bool) { self.max_sequence = Some(self.max_sequence.map_or(sequence, |max| max.max(sequence))); self.cache.advance_largest(Position::group(sequence)); - let mut wakes = self.subscriptions.lock().wrote(sequence, answers); - wakes.wake(); + let wakes = self.subscriptions.lock().wrote(sequence, answers); + if !wakes.is_empty() { + self.deferred.push(wakes); + } + } + + /// Take the wakes [`Self::advance`] deferred, to fire once the state guard is released. + pub(super) fn deferred(&mut self) -> Deferred { + Deferred(std::mem::take(&mut self.deferred)) } /// The sequence the next append takes: one past this track's own writes. @@ -2749,6 +2763,18 @@ impl TrackState { } } +/// Demand wakes taken out of the track state, fired once its guard is gone. +#[must_use = "fire the wakes once the guard is released"] +pub(super) struct Deferred(Vec); + +impl Deferred { + pub(super) fn wake(self) { + for mut wakes in self.0 { + wakes.wake(); + } + } +} + /// Record `err` and close the track, the shared tail of every abort, returning the open /// groups to abort once the guard is gone. fn commit_abort(mut state: kio::Mut<'_, TrackState>, err: Error) -> OpenGroups { @@ -2970,6 +2996,9 @@ impl Producer { } state.cap(&group.handle())?; state.commit_group(&group.handle()); + let deferred = state.deferred(); + drop(state); + deferred.wake(); Ok(group) } @@ -2993,6 +3022,9 @@ impl Producer { group::Producer::new(group::Info { sequence }, track, state.cache.clone()).with_meter(self.stats.meter()); state.cap(&group.handle())?; state.commit_group(&group.handle()); + let deferred = state.deferred(); + drop(state); + deferred.wake(); Ok(group) } @@ -3053,7 +3085,9 @@ impl Producer { meter.datagram(datagram.stored_len()); state.push_datagram(datagram); let cache = state.cache.clone(); + let deferred = state.deferred(); drop(state); + deferred.wake(); cache.settle(None); Ok(sequence) } @@ -3103,7 +3137,9 @@ impl Producer { meter.datagram(datagram.stored_len()); state.push_datagram(datagram); let cache = state.cache.clone(); + let deferred = state.deferred(); drop(state); + deferred.wake(); cache.settle(None); Ok(()) } diff --git a/rs/moq-net/src/model/track/fill.rs b/rs/moq-net/src/model/track/fill.rs index cfe30cde48f..c71757c73e3 100644 --- a/rs/moq-net/src/model/track/fill.rs +++ b/rs/moq-net/src/model/track/fill.rs @@ -1028,8 +1028,13 @@ impl Inner { return Err(Error::Duplicate); } // Cache the group before answering: readers resolve an accept through the cache. - let res = - TrackState::modify(&self.state).and_then(|mut state| state.insert_group_request(sequence, frames, info)); + let res = TrackState::modify(&self.state).and_then(|mut state| { + let res = state.insert_group_request(sequence, frames, info); + let deferred = state.deferred(); + drop(state); + deferred.wake(); + res + }); if let Ok(mut outcome) = self.result.write() { outcome.accept(sequence..end); if let Ok(group) = &res diff --git a/rs/moq-video/src/encode/producer.rs b/rs/moq-video/src/encode/producer.rs index 82d344fcdf3..e756be25469 100644 --- a/rs/moq-video/src/encode/producer.rs +++ b/rs/moq-video/src/encode/producer.rs @@ -3,7 +3,7 @@ //! Encoding is strictly on demand: the track and its catalog rendition are //! advertised immediately (the rendition is probed from the encoder, since //! nothing has been encoded yet), and the encoder itself only runs while a -//! subscriber is watching. Capture opens its camera once at startup to learn +//! subscriber is watching, or reading its HLS records. Capture opens its camera once at startup to learn //! the mode it negotiates, then keeps it closed between viewers. This mirrors //! `moq-boy`, which pauses its emulator while //! [`Demand::wanted`](moq_net::track::Demand::wanted) is `None`. @@ -1551,9 +1551,6 @@ mod tests { .hls .clone() .expect("the video track advertises its HLS records"); - let mut records = moq_mux::hls::Consumer::subscribe(&fixture.consumer, &hls) - .await - .unwrap(); let mut live = Vec::new(); for _ in 0..2 { @@ -1569,8 +1566,11 @@ mod tests { tokio::time::sleep(moq_mux::hls::DEFAULT_DURATION + Duration::from_millis(100)).await; } - let (mut catalog, _consumer) = fixture.finish().await; + let (mut catalog, consumer) = fixture.finish().await; catalog.finish().unwrap(); + // Read only now: a record reader is demand too, and would have kept the capture + // from idling between the runs. + let mut records = moq_mux::hls::Consumer::subscribe(&consumer, &hls).await.unwrap(); let mut listed = Vec::new(); while let Some(event) = records.next().await.unwrap() { match event { @@ -1835,6 +1835,66 @@ mod tests { } } + /// An HLS export subscribes only to a rendition's records, never its media, yet that alone + /// opens the camera and records the segment it captures. + #[tokio::test(start_paused = true)] + async fn an_hls_only_viewer_starts_capture() { + // Off Apple, encoding waits on an OS thread. Keep Tokio from auto-advancing + // the paused clock to a timer deadline while that thread answers. + let (hold, released) = tokio::sync::oneshot::channel::<()>(); + let clock = tokio::task::spawn_blocking(move || { + let _ = released.blocking_recv(); + }); + // Capture streams are !Send on macOS. + tokio::task::LocalSet::new() + .run_until(async { + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let consumer = broadcast.consume(); + let catalog = + moq_mux::catalog::Producer::new(&mut broadcast, moq_mux::catalog::Config::default()).unwrap(); + let options = Capture { + kind: encoder::Kind::Software, + ..Capture::default() + }; + let (control, driver) = Control::new(broadcast.clone(), catalog, options).unwrap(); + + let rate = crate::FrameRate::new(10, 1).unwrap(); + let (_probe, probe) = Synthetic::open(crate::Size::new(320, 240), rate); + let (camera, stream) = Synthetic::open(crate::Size::new(320, 240), rate); + let source = Streams::new([probe, stream]); + let opens = source.opens.clone(); + let run = tokio::task::spawn_local(driver.run_with(source)); + + // The capture is hinted, so the catalog names its records before any segment. + let mut catalog = + moq_mux::catalog::Consumer::<()>::new(&consumer, moq_mux::catalog::CatalogFormat::Hang) + .await + .unwrap(); + let hls = loop { + let snapshot = catalog.next().await.unwrap().expect("a catalog"); + if let Some(hls) = snapshot.video.renditions.values().find_map(|config| config.hls.clone()) { + break hls; + } + }; + assert_eq!(opens.load(Ordering::SeqCst), 1, "only the probe opened the camera"); + + let mut records = moq_mux::hls::Consumer::subscribe(&consumer, &hls).await.unwrap(); + camera.push_native(surface(), us(0)); + let event = records.next().await.unwrap().expect("a record"); + assert!( + matches!(event, moq_mux::hls::Event::Push { index: 0, .. }), + "unexpected event {event:?}" + ); + assert_eq!(opens.load(Ordering::SeqCst), 2, "the records' reader opened the camera"); + + drop(control); + run.await.unwrap().unwrap(); + }) + .await; + drop(hold); + clock.await.unwrap(); + } + /// Drop the controls while the driver sits in its `opens`th open, which never finishes. async fn abandon( control: Control,