Skip to content
Merged
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
3 changes: 1 addition & 2 deletions quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,7 @@ removal, a rename, or a wire, catalog, or format change that is free until
`mpegts`, one strict rule);
[declared ends](/quest/m2/time-addressing/consumers.md), back from m3.
- **Native media and gateways.** [The video producer](/quest/m2/video-producer.md),
[the hole wait](/quest/m2/delay-hole-wait.md),
[a chained WHEP pull's shutdown](/quest/m2/whep-chain-shutdown.md), and
[the hole wait](/quest/m2/delay-hole-wait.md), and
[upstream str0m](https://github.com/moq-dev/moq/pull/8963), which reverses the
2026-10-30 vendoring.
- **Bindings.** [The C API as `libmoq`](/quest/m2/libmoq-name.md), reversing 2026-10-25.
Expand Down
39 changes: 0 additions & 39 deletions quest/m2/whep-chain-shutdown.md

This file was deleted.

26 changes: 26 additions & 0 deletions quest/m3/flv-export-arrival.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# [XS] An FLV export judges a frame on when it landed

## Goal

`container::flv::Export` hands the jitter buffer each frame's real arrival, as the TS and MKV
exports do, so a track the buffer holds back (its reads gated by `Buffer::full`) is not judged as
sent further and further ahead of its decode time.

## Plan

Found 2026-11-17 while chasing a spurious `the source's clock runs ... ppm off ours` from
`moq import webrtc --connect <whep> -- export rtmp --connect <rtmp>` (the quest that fixed it
deleted its file). `FlvTrack::empty` is when the source last returned `Pending`, and
`Export::fill` uses it as every frame's `arrived` (`rs/moq-mux/src/container/flv/export.rs`),
ignoring `Event::Frame { arrived }`, which carries the time the frame landed in the cache. A track
whose reads `full` gates never returns `Pending`, so `empty` stops moving, and each frame read
looks older than the last by the time it waited: replaying a recorded trace, one audio track's
`decode - arrived` grew 0.5 s to 1.6 s over 1.5 s. Use `arrived.max(track.empty)` (the MKV export
takes `arrived.max(track.subscribed)`), and add a test that gates one track and checks the
buffer sees no lead growing.

The maintainer kept this quest (2026-11-17, [on the PR that found it](https://github.com/moq-dev/moq/pull/9032#issuecomment-6962042151)).

## Related

- [Container export ends cleanly](/quest/m3/export-close.md) - the same exports' shutdown
52 changes: 52 additions & 0 deletions rs/moq-net/src/model/origin.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4472,6 +4472,23 @@ impl FrontServeRun {
}
}

/// A front dropped before it ended, as when its origin is torn down, ends the logical tracks it
/// was serving as closed, rather than leave them to warn as producers dropped unfinished.
impl Drop for FrontServeRun {
fn drop(&mut self) {
let close = |logical: &mut Logical| {
if let Logical::Accepted(accepted) = std::mem::replace(logical, Logical::Ended) {
let _ = accepted.abort(Error::Closed);
}
};
match &mut self.state {
FrontRunState::Start(_) => {}
FrontRunState::Serve(serve) => serve.tracks.values_mut().for_each(|io| close(&mut io.logical)),
FrontRunState::InFlight(in_flight) => in_flight.iter_mut().for_each(|io| close(&mut io.logical)),
}
}
}

impl kio::Task for FrontServeRun {
type Output = ();

Expand Down Expand Up @@ -9140,6 +9157,41 @@ mod tests {
assert_eq!(warns, 0, "a clean logical end must not drop an unfinished producer");
}

/// A torn-down origin ends the logical tracks its fronts were serving, rather than warn about
/// producers dropped unfinished.
#[kio::test]
#[cfg(feature = "async")]
async fn teardown_ends_the_logical_tracks() {
let (producer, mut driver) = Producer::new(Config::from(origin(1)));
let consumer = producer.consume();
let source = producer.route("room", RouteOptions::default()).unwrap();
let _source_track = source.broadcast().create_track("video", None).unwrap();
let waiter = kio::Waiter::noop();

// The driver runs the front that answers each of these.
let mut request = Box::pin(consumer.request("room", None));
let front = loop {
driver.poll(kio::clock::now(), &waiter).unwrap();
if let Some(front) = request.as_mut().now_or_never() {
break front.unwrap();
}
kio::clock::sim::yield_now().await;
};
let track = front.track("video").unwrap();
let mut subscribing = Box::pin(track.subscribe(None));
let subscriber = loop {
driver.poll(kio::clock::now(), &waiter).unwrap();
if let Some(subscriber) = subscribing.as_mut().now_or_never() {
break subscriber.unwrap();
}
kio::clock::sim::yield_now().await;
};

let warns = count_drop_warnings("track::Producer dropped without finish", || drop(driver));
assert_eq!(warns, 0, "a torn-down front must not drop an unfinished track");
drop(subscriber);
}

#[kio::test]
async fn default_config_mints_a_real_hop() {
let config = Config::default();
Expand Down
5 changes: 5 additions & 0 deletions rs/moq-webrtc/src/codec/av1.rs
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,11 @@ impl codec::Bridge for Bridge {
Ok(())
}

fn discontinuity(&mut self) -> Result<()> {
self.import.discontinuity()?;
Ok(())
}

fn finish(self: Box<Self>) -> Result<codec::Finished> {
Ok(Box::new(self.import.finish()?))
}
Expand Down
5 changes: 5 additions & 0 deletions rs/moq-webrtc/src/codec/h264.rs
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,11 @@ impl codec::Bridge for Bridge {
Ok(())
}

fn discontinuity(&mut self) -> Result<()> {
self.import.discontinuity()?;
Ok(())
}

fn finish(self: Box<Self>) -> Result<codec::Finished> {
Ok(Box::new(self.import.finish()?))
}
Expand Down
5 changes: 5 additions & 0 deletions rs/moq-webrtc/src/codec/h265.rs
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,11 @@ impl codec::Bridge for Bridge {
Ok(())
}

fn discontinuity(&mut self) -> Result<()> {
self.import.discontinuity()?;
Ok(())
}

fn finish(self: Box<Self>) -> Result<codec::Finished> {
Ok(Box::new(self.import.finish()?))
}
Expand Down
23 changes: 23 additions & 0 deletions rs/moq-webrtc/src/codec/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,10 @@ pub struct Frame {
pub trait Bridge: Send {
fn push(&mut self, frame: Frame) -> Result<()>;

/// Mark a break in the published track's timeline before the next frame, which opens a group,
/// as the session's clock stepped.
fn discontinuity(&mut self) -> Result<()>;

/// Finish the published track after its final frame, returning what keeps serving it while
/// the finished broadcast is held.
fn finish(self: Box<Self>) -> Result<Finished>;
Expand All @@ -66,6 +70,9 @@ pub(crate) trait DeferredImport: Send + Sized {
/// Decode one complete codec frame.
fn decode(&mut self, frame: Bytes, pts: moq_net::Timestamp) -> moq_mux::Result<()>;

/// Mark a break in the active media track's timeline.
fn discontinuity(&mut self) -> moq_mux::Result<()>;

/// Finish the active media track.
fn finish(self) -> moq_mux::Result<moq_mux::container::Finished<moq_mux::catalog::hang::Container, VideoConfig>>;

Expand All @@ -86,6 +93,10 @@ impl DeferredImport for moq_mux::codec::vp8::Import {
moq_mux::codec::vp8::Import::finish(self)
}

fn discontinuity(&mut self) -> moq_mux::Result<()> {
moq_mux::codec::vp8::Import::discontinuity(self)
}

fn abort(self, err: moq_net::Error) {
moq_mux::codec::vp8::Import::abort(self, err);
}
Expand All @@ -104,6 +115,10 @@ impl DeferredImport for moq_mux::codec::vp9::Import {
moq_mux::codec::vp9::Import::finish(self)
}

fn discontinuity(&mut self) -> moq_mux::Result<()> {
moq_mux::codec::vp9::Import::discontinuity(self)
}

fn abort(self, err: moq_net::Error) {
moq_mux::codec::vp9::Import::abort(self, err);
}
Expand Down Expand Up @@ -164,6 +179,14 @@ impl<I: DeferredImport> DeferredVideo<I> {
import.decode(frame, pts).map_err(Into::into)
}

/// Mark a break in the media track's timeline, which a track no frame has created yet has none of.
pub fn discontinuity(&mut self) -> Result<()> {
match &mut self.state {
DeferredState::Active(import) => import.discontinuity().map_err(Into::into),
_ => Ok(()),
}
}

/// Finish the media track, whether or not a frame ever created its importer.
pub fn finish(self) -> Result<Finished> {
Ok(match self.state {
Expand Down
5 changes: 5 additions & 0 deletions rs/moq-webrtc/src/codec/opus.rs
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,11 @@ impl codec::Bridge for Bridge {
Ok(())
}

fn discontinuity(&mut self) -> Result<()> {
self.import.discontinuity()?;
Ok(())
}

fn finish(self: Box<Self>) -> Result<codec::Finished> {
Ok(Box::new(self.import.finish()?))
}
Expand Down
4 changes: 4 additions & 0 deletions rs/moq-webrtc/src/codec/vp8.rs
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,10 @@ impl codec::Bridge for Bridge {
self.import.decode(frame.payload, pts)
}

fn discontinuity(&mut self) -> Result<()> {
self.import.discontinuity()
}

fn finish(self: Box<Self>) -> Result<codec::Finished> {
self.import.finish()
}
Expand Down
4 changes: 4 additions & 0 deletions rs/moq-webrtc/src/codec/vp9.rs
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,10 @@ impl codec::Bridge for Bridge {
self.import.decode(frame.payload, pts)
}

fn discontinuity(&mut self) -> Result<()> {
self.import.discontinuity()
}

fn finish(self: Box<Self>) -> Result<codec::Finished> {
self.import.finish()
}
Expand Down
70 changes: 66 additions & 4 deletions rs/moq-webrtc/src/ingest.rs
Original file line number Diff line number Diff line change
Expand Up @@ -33,10 +33,17 @@ impl IngestSink {
pub fn routed(route: moq_net::origin::Route, config: moq_mux::catalog::Config) -> Result<Self> {
let mut broadcast = route.broadcast().clone();
let catalog = moq_mux::catalog::Producer::new(&mut broadcast, config)?;
Ok(Self {
_route: Some(route),
..Self::new(broadcast, catalog)
})
let mut sink = Self::new(broadcast, catalog);
sink._route = Some(route);
Ok(sink)
}
}

/// Dropped before the session ends, as when the pull's future is cancelled at shutdown, the sink
/// aborts its tracks instead of leaving them unfinished. A finished or aborted sink has nothing left.
impl Drop for IngestSink {
fn drop(&mut self) {
session::MediaSink::abort(self, moq_net::Error::Cancel);
}
}

Expand Down Expand Up @@ -79,6 +86,10 @@ impl session::MediaSink for IngestSink {
Ok(())
}

fn on_discontinuity(&mut self, mid: str0m::media::Mid) -> Result<()> {
self.bridges.discontinuity(mid)
}

fn on_frame(&mut self, mid: str0m::media::Mid, frame: codec::Frame) -> Result<()> {
self.bridges.push(mid, frame)
}
Expand Down Expand Up @@ -158,4 +169,55 @@ mod tests {
drop(linger);
assert!(consumer.is_closed());
}

/// A step in the session timeline breaks the track's timeline with a group of its own, which
/// is what lets a reader's clock re-anchor instead of read the step as drift.
#[tokio::test(start_paused = true)]
async fn a_step_publishes_a_marker_group() {
let mut broadcast = moq_net::broadcast::Info::new().produce();
let consumer = broadcast.consume();
let catalog = moq_mux::catalog::Producer::new(&mut broadcast, Default::default()).unwrap();
let mut sink = IngestSink::new(broadcast, catalog);
let audio = str0m::media::MediaKind::Audio;
sink.on_track("0".into(), audio, str0m::format::Codec::Opus, Some((48_000, 2)))
.unwrap();
let frame = |timestamp_us| codec::Frame {
timestamp_us,
payload: bytes::Bytes::from_static(&[0xfc, 0xff, 0xfe]),
};
let mut track = consumer.track("0.opus").unwrap().subscribe(None).await.unwrap();
let mut groups = 0;
let mut read = async |track: &mut moq_net::track::Subscriber| {
while let Ok(Ok(Some(_))) = kio::clock::timeout(Duration::from_millis(100), track.recv_group()).await {
groups += 1;
}
};
sink.on_frame("0".into(), frame(20_000)).unwrap();
read(&mut track).await;
sink.on_frame("0".into(), frame(40_000)).unwrap();
read(&mut track).await;
sink.on_discontinuity("0".into()).unwrap();
read(&mut track).await;
sink.on_frame("0".into(), frame(400_000)).unwrap();
read(&mut track).await;
assert_eq!(groups, 4, "two frames, the marker, and the frame after it");
}

/// Dropping a sink before its session ends, as when shutdown cancels a pull, aborts its
/// tracks and the catalog rather than leaving them to warn as dropped unfinished.
#[tokio::test]
async fn a_dropped_sink_aborts_its_tracks() {
let mut broadcast = moq_net::broadcast::Info::new().produce();
let consumer = broadcast.consume();
let catalog = moq_mux::catalog::Producer::new(&mut broadcast, Default::default()).unwrap();
let mut sink = IngestSink::new(broadcast, catalog.clone());
let audio = str0m::media::MediaKind::Audio;
sink.on_track("0".into(), audio, str0m::format::Codec::Opus, Some((48_000, 2)))
.unwrap();
let mut track = consumer.track("0.opus").unwrap().subscribe(None).await.unwrap();

drop(sink);
drop(catalog);
assert!(matches!(track.recv_group().await, Err(moq_net::Error::Cancel)));
}
}
Loading