diff --git a/dart/moq/lib/src/aliases.dart b/dart/moq/lib/src/aliases.dart index 8727301bc0d..fa998168f97 100644 --- a/dart/moq/lib/src/aliases.dart +++ b/dart/moq/lib/src/aliases.dart @@ -85,7 +85,7 @@ typedef GroupProducer = MoqGroupProducer; /// The read side of a single group: yields timestamped raw frames. typedef GroupConsumer = MoqGroupConsumer; -/// The write side of a media track fed pre-framed payloads. +/// The write side of a media track; discontinuity() marks a break between pre-framed payloads. typedef MediaProducer = MoqMediaProducer; /// The write side of a media track fed a raw byte stream, with frame boundaries inferred. diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 4ada2c2a1c7..7016449c5d1 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -6871,6 +6871,7 @@ class FfiConverterMoqGroupRequest { abstract class MoqMediaProducerInterface { void cut(); MoqTrackDemand demand(); + void discontinuity(); void finish(); void flush({required int timestampUs}); String name(); @@ -6923,6 +6924,15 @@ class MoqMediaProducer implements MoqMediaProducerInterface { ); } + void discontinuity() { + return rustCall((status) { + uniffi_moq_ffi_fn_method_moqmediaproducer_discontinuity( + uniffiClonePointer(), + status, + ); + }, moqExceptionErrorHandler); + } + void finish() { return rustCall((status) { uniffi_moq_ffi_fn_method_moqmediaproducer_finish( @@ -10912,6 +10922,14 @@ external Pointer uniffi_moq_ffi_fn_method_moqmediaproducer_demand( Pointer uniffiStatus, ); +@Native, Pointer)>( + assetId: _uniffiAssetId, +) +external void uniffi_moq_ffi_fn_method_moqmediaproducer_discontinuity( + Pointer ptr, + Pointer uniffiStatus, +); + @Native, Pointer)>( assetId: _uniffiAssetId, ) @@ -12309,6 +12327,9 @@ external int uniffi_moq_ffi_checksum_method_moqmediaproducer_cut(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqmediaproducer_demand(); +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_method_moqmediaproducer_discontinuity(); + @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqmediaproducer_finish(); @@ -12909,6 +12930,10 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqmediaproducer_demand() != 44491) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } + if (uniffi_moq_ffi_checksum_method_moqmediaproducer_discontinuity() != + 37570) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } if (uniffi_moq_ffi_checksum_method_moqmediaproducer_finish() != 38480) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } diff --git a/dart/moq_ffi/lib/src/uniffi_runtime.dart b/dart/moq_ffi/lib/src/uniffi_runtime.dart index ab87a64ed3f..1eefdf6293d 100644 --- a/dart/moq_ffi/lib/src/uniffi_runtime.dart +++ b/dart/moq_ffi/lib/src/uniffi_runtime.dart @@ -8,6 +8,7 @@ import "dart:ffi"; import "dart:io" show Platform, File, Directory; import "dart:isolate"; import "dart:typed_data"; + import "package:ffi/ffi.dart"; class UniffiInternalError implements Exception { @@ -247,6 +248,7 @@ mixin FfiConverterPrimitive on FfiConverter { @override T lower(T value) => value; } + Uint8List createUint8ListFromInt(int value) { int length = value.bitLength ~/ 8 + 1; if (length != 4 && length != 8) { diff --git a/doc/bin/gstreamer.md b/doc/bin/gstreamer.md index c3695b214d9..fa2cc877e5e 100644 --- a/doc/bin/gstreamer.md +++ b/doc/bin/gstreamer.md @@ -83,6 +83,11 @@ default, for file, demuxed, and network media: their arrival reflects the disk or the network, not the original encoder, and a GStreamer segment cannot tell the two apart. Text and opaque pads refuse it. +After a pause, flush, or changed TIME segment, the next media buffer starts a new +timeline epoch and resets the handoff baseline. The pause does not inflate +advertised jitter, and previously measured maxima remain. Resumed timestamps +must continue forward on the broadcast media clock. + ## moqsrc Pads are named by kind and appear as the catalog announces renditions: diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index 7a3c5b08dd7..33f78530676 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -59,6 +59,8 @@ if (session < 0) For a locally encoded media track, call `moq_publish_media_flush(media, timestamp_us)` after `moq_publish_media_frame` with the same broadcast-clock PTS. The monotonic handoff time is sampled inside libmoq. Do not call it for file, pipe, or network imports; those remain clock-free. Invalid handles and unrepresentable timestamps return a negative error code. +Call `moq_publish_media_discontinuity(media)` when the source seeks, pauses, or changes its time base. It publishes a timeline marker and restarts handoff measurement without lowering advertised jitter. Resume with timestamps that continue forward on the broadcast media clock; this does not permit timestamp rewinds. + ## Connection stats Every field in `moq_connection_stats` carries a matching `_valid` flag, diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index 564d4e06edb..62f4f630ec1 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -109,6 +109,8 @@ catalog and container types are there, so already-encoded frames flow through `MediaProducer.flush(timestampUs: ...)` records the handoff of a locally encoded frame on the broadcast media clock. Call it after `writeFrame` only for live encoder output; file, pipe, and network imports stay clock-free. `MediaProducer` aliases the generated FFI object, so its method is available directly. +Call `media.discontinuity()` when the source seeks, pauses, or changes its time base. It publishes a timeline marker and restarts handoff measurement without lowering advertised jitter. Resume with timestamps that continue forward on the broadcast media clock; this does not permit timestamp rewinds. + ## Connection stats `session.stats()` returns a `ConnectionStats` snapshot. Each field is `null` diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index 001f5a50e4a..d910f5d17c0 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -71,6 +71,8 @@ broadcast.Finish() // keep the producer reachable while publishing, then finis For locally encoded media, call `MediaProducer.Flush(timestampUs)` after `WriteFrame` with the same broadcast-clock PTS. It measures catalog jitter at the transport handoff. File, pipe, and network imports should omit `Flush`; built-in encoders observe their own output. +Call `media.Discontinuity()` when the source seeks, pauses, or changes its time base. It publishes a timeline marker and restarts handoff measurement without lowering advertised jitter. Resume with timestamps that continue forward on the broadcast media clock; this does not permit timestamp rewinds. + The three advertising operations: `client.CreateBroadcast(path)` (or `origin.CreateBroadcast`) returns an unannounced producer, invisible to everyone; `broadcast.Announce(route)` / `broadcast.Unannounce()` own that exact-path diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index a241ad6b0cb..5ba62e70611 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -53,6 +53,8 @@ Moq.connect("https://relay.example.com").use { moq -> `MediaProducer.flush(timestampUs)` records a locally encoded frame's transport handoff on the broadcast media clock. Call it after `writeFrame` for live encoder output; omit it for file, pipe, and network imports. `MediaProducer` is a typealias, so the generated method is available directly. +Call `media.discontinuity()` when the source seeks, pauses, or changes its time base. It publishes a timeline marker and restarts handoff measurement without lowering advertised jitter. Resume with timestamps that continue forward on the broadcast media clock; this does not permit timestamp rewinds. + The three advertising operations: `moq.createBroadcast(path)` (or `origin.createBroadcast`) returns an unannounced producer, invisible to everyone; `broadcast.announce(route)` / `broadcast.unannounce()` own that exact-path diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index a41cb7255bd..4d9eac1b703 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -71,6 +71,8 @@ asyncio.run(main()) For already-encoded live output, call `audio.flush(timestamp_us)` after each `audio.write_frame` with the same broadcast-clock PTS. It samples the transport handoff for catalog jitter. File, pipe, and network imports should omit `flush`; raw-pixel and PCM encoders inside the binding measure their own output. +Call `audio.discontinuity()` when the source seeks, pauses, or changes its time base. It publishes a timeline marker and restarts handoff measurement without lowering advertised jitter. Resume with timestamps that continue forward on the broadcast media clock; this does not permit timestamp rewinds. + The three advertising operations, as the other bindings spell them: `client.create_broadcast(path)` (or `OriginProducer.create_broadcast`) returns an unannounced producer, invisible to everyone; `broadcast.announce(route)` / diff --git a/doc/lib/rs/moq-mux.md b/doc/lib/rs/moq-mux.md index 7be69723be9..be641e96197 100644 --- a/doc/lib/rs/moq-mux.md +++ b/doc/lib/rs/moq-mux.md @@ -43,9 +43,12 @@ measure batch span or reorder delay for jitter. Locally encoded frames call `container::Producer::flush(timestamp, Instant::now())`; jitter is the spread above that track's own recent minimum lateness, and delay is how far that minimum trails the earliest track on the same catalog. Both are published as -soon as they rise. Generic imports remain clock-free. Invalid or decreasing -jitter or delay is rejected before the edit is retained, including while the -initial catalog is reserved. +soon as they rise. `import::Track::discontinuity()` marks a source seek or +pause, clears partial input, and restarts the flush baseline without lowering +advertised values. It forwards the container timeline marker, so resumed +timestamps must continue forward on the broadcast clock. Generic imports remain +clock-free. Invalid or decreasing jitter or delay is rejected before the edit is +retained, including while the initial catalog is reserved. Codec importers propagate catalog and media errors through their configuration and frame-writing methods. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index a9aa8b3c440..cbbcefa6bca 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -57,6 +57,8 @@ session.shutdown() For already-encoded live output, call `audio.flush(timestampUs:)` after `writeFrame` with the same broadcast-clock PTS. It measures catalog jitter at the transport handoff. File, pipe, and network imports should omit `flush`; built-in encoders observe their own output. +Call `audio.discontinuity()` when the source seeks, pauses, or changes its time base. It publishes a timeline marker and restarts handoff measurement without lowering advertised jitter. Resume with timestamps that continue forward on the broadcast media clock; this does not permit timestamp rewinds. + The three advertising operations: `session.publish.createBroadcast(path:)` returns an unannounced producer, invisible to everyone; `broadcast.announce(route:)` / `broadcast.unannounce()` own that exact-path advertisement; diff --git a/go/wrapper/publish.go b/go/wrapper/publish.go index 6eccc6d8f67..a7462126279 100644 --- a/go/wrapper/publish.go +++ b/go/wrapper/publish.go @@ -365,6 +365,11 @@ func (m *MediaProducer) Flush(timestampUs uint64) error { return m.inner.Flush(timestampUs) } +// Discontinuity marks a timeline break and restarts handoff measurement, preserving advertised jitter. +func (m *MediaProducer) Discontinuity() error { + return m.inner.Discontinuity() +} + // Cut draws a group boundary here. // // Audio has no boundary of its own (every packet is independently decodable), so this is diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index 38883f6cdaa..9c8639bce8e 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -62,7 +62,7 @@ typealias GroupProducer = uniffi.moq.MoqGroupProducer typealias GroupConsumer = uniffi.moq.MoqGroupConsumer // Media (codec-aware) producers and consumers. -/** The write side of a media track fed pre-framed payloads. */ +/** The write side of a media track; discontinuity() marks a break between pre-framed payloads. */ typealias MediaProducer = uniffi.moq.MoqMediaProducer /** The write side of a media track fed a raw byte stream, with frame boundaries inferred. */ typealias MediaStreamProducer = uniffi.moq.MoqMediaStreamProducer diff --git a/py/moq-rs/moq/publish.py b/py/moq-rs/moq/publish.py index cbaf29ba13c..10248a2bc9c 100644 --- a/py/moq-rs/moq/publish.py +++ b/py/moq-rs/moq/publish.py @@ -102,6 +102,10 @@ def flush(self, timestamp_us: int) -> None: """ self._inner.flush(timestamp_us) + def discontinuity(self) -> None: + """Mark a timeline break and restart handoff measurement, preserving advertised jitter.""" + self._inner.discontinuity() + def cut(self) -> None: """Draw a group boundary here. diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index ad004a566fc..004dc26d511 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -146,6 +146,8 @@ def test_publish_media_cut_and_seek(): # The same boundary, with the next group explicitly numbered. media.write_frame(b"opus frame", 60_000) media.seek(42) + media.discontinuity() + media.write_frame(b"resumed opus frame", 100_000) media.finish() broadcast.finish() diff --git a/quest/m1/README.md b/quest/m1/README.md index 022226b8084..f9cd59c56fa 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -39,7 +39,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics. - [IETF announce count](/quest/m1/ietf-announce-count.md) - an opt-in moq-transport extension carries the replay count, so IETF announce consumers go live without a timer - [Publish delay](/quest/m1/publish-delay.md) - js/publish encoders advertise `delay` behind the earliest rendition, like moq-mux -- [Import discontinuity](/quest/m1/import-discontinuity.md) - a seek or pause resets the flush jitter baseline, from moqsink, libmoq, and moq-ffi - [Data jitter](/quest/m1/data-jitter.md) - JSON and binary tracks with a capture time advertise a detected `delay` and `jitter` - [Moxygen compatibility](/quest/m1/moxygen/README.md) - one subgroup per group, whole-group FETCH, and one datagram per group, never a full moxygen pass - [JavaScript FETCH](/quest/m1/js-fetch.md) - generic on-demand group serving and IETF FETCH for browser publishers diff --git a/quest/m1/import-discontinuity.md b/quest/m1/import-discontinuity.md deleted file mode 100644 index c5c2fd6025a..00000000000 --- a/quest/m1/import-discontinuity.md +++ /dev/null @@ -1,20 +0,0 @@ -# [S] Import discontinuity - -## Goal - -A publisher that seeks or pauses tells its importer so, and the flush jitter -measurement restarts instead of counting the break. `moqsink` does it on a -seek, and C and FFI publishers can do it too. - -## Plan - -- `moq_mux::container::Producer::discontinuity()` already resets the flush - baseline (`catalog/estimate.rs`). `import::Track` gains a `discontinuity()` - that forwards to it, and the codec importers without one gain it too. Only - the baseline resets; advertised values are never lowered. -- `moqsink` calls it when a pad re-anchors after a flush or a new segment - (`rs/moq-gst/src/sink/pad.rs`). Test that a seek on an `encoder` pad does - not raise the advertised jitter. -- Expose it as `moq_publish_media_discontinuity` in libmoq and as - `discontinuity()` in moq-ffi and its hand-written wrappers, per the - Cross-Package Sync table. This is additive, so it lands on `main`. diff --git a/rs/libmoq/src/api.rs b/rs/libmoq/src/api.rs index 66e353a052a..13d263077a0 100644 --- a/rs/libmoq/src/api.rs +++ b/rs/libmoq/src/api.rs @@ -2212,6 +2212,18 @@ pub extern "C" fn moq_publish_media_flush(media: u32, timestamp_us: u64) -> i32 }) } +/// Mark a timeline break and restart handoff measurement without lowering advertised jitter. +/// +/// Publishes a discontinuity marker; resumed frames must continue the broadcast media clock. +/// Returns zero on success, or a negative code on failure. +#[unsafe(no_mangle)] +pub extern "C" fn moq_publish_media_discontinuity(media: u32) -> i32 { + ffi::enter(move || { + let media = ffi::parse_id(media)?; + State::lock().publish.media_discontinuity(media) + }) +} + /// Replace the catalog properties shared by every video rendition. /// /// Rotation is clockwise and normalized to the nearest quarter turn. A field whose matching `has_*` flag is false is removed from the next catalog update. diff --git a/rs/libmoq/src/publish.rs b/rs/libmoq/src/publish.rs index fd7db2f6816..951093f8a72 100644 --- a/rs/libmoq/src/publish.rs +++ b/rs/libmoq/src/publish.rs @@ -245,6 +245,13 @@ impl Publish { Ok(()) } + /// Mark a timeline break on this media importer. + pub fn media_discontinuity(&mut self, media: Id) -> Result<(), Error> { + let track = self.media.get_mut(media).ok_or(Error::MediaNotFound)?; + track.discontinuity()?; + Ok(()) + } + /// Draw a group boundary on this media importer. /// /// This ends the open group; the next frame starts a new one. Audio has no boundary of its own diff --git a/rs/libmoq/src/test.rs b/rs/libmoq/src/test.rs index 535d3574d89..9919eada4e2 100644 --- a/rs/libmoq/src/test.rs +++ b/rs/libmoq/src/test.rs @@ -1953,10 +1953,13 @@ fn media_cut_bounds_audio_groups() { 0 ); assert_eq!(moq_publish_media_seek(media, 42), 0); + assert_eq!(moq_publish_media_discontinuity(media), 0); // Both report a missing importer rather than panicking on an unknown id. assert!(moq_publish_media_flush(9999, 0) < 0); assert!(moq_publish_media_flush(media, u64::MAX) < 0); + assert!(moq_publish_media_discontinuity(9999) < 0); + assert!(moq_publish_media_discontinuity(0) < 0); assert!(moq_publish_media_cut(9999) < 0); assert!(moq_publish_media_seek(9999, 0) < 0); diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index 04822ca67ce..54386f575ac 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -971,6 +971,17 @@ impl MoqMediaProducer { Ok(()) } + /// Mark a timeline break and restart handoff measurement without lowering advertised jitter. + /// + /// Publishes a discontinuity marker; resumed frames must continue the broadcast media clock. + pub fn discontinuity(&self) -> Result<(), MoqError> { + let _guard = crate::ffi::enter(); + let mut guard = self.inner.lock().unwrap(); + let media = guard.as_mut().ok_or(MoqError::Closed)?; + media.import.discontinuity()?; + Ok(()) + } + /// Draw a group boundary here. /// /// Audio has no boundary of its own (every packet is independently decodable), so this is the diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 265dee6162e..f07af2e68fa 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -1368,7 +1368,9 @@ async fn dynamic_track_request_can_publish_media() { assert_eq!(frame.payload, payload); assert_eq!(frame.timestamp_us, 20_000); + media.discontinuity().unwrap(); media.finish().unwrap(); + assert!(matches!(media.discontinuity(), Err(MoqError::Closed))); } #[tokio::test] diff --git a/rs/moq-gst/src/sink/imp.rs b/rs/moq-gst/src/sink/imp.rs index e07f6c0178a..d1c7d5685cf 100644 --- a/rs/moq-gst/src/sink/imp.rs +++ b/rs/moq-gst/src/sink/imp.rs @@ -1022,7 +1022,15 @@ impl MoqSink { /// Close the gate: an EOS earned from here on waits for the next entry to PLAYING. fn leave_playing(&self) { - self.control.lock().unwrap().playing = false; + let mut control = self.control.lock().unwrap(); + if !std::mem::replace(&mut control.playing, false) { + return; + } + // Running time stops in PAUSED while the encoder handoff clock keeps advancing. + for pad in self.obj().sink_pads() { + let pad = pad.downcast::().expect("sink pad type"); + pad.lifecycle().media.discontinuity(); + } } fn publish_finished(&self, finished: Finished) { @@ -1092,6 +1100,62 @@ mod tests { glib::Object::builder::().build() } + #[test] + fn a_playing_pause_cycle_does_not_raise_encoder_jitter() { + gst::init().unwrap(); + let sink = sink(); + sink.set_property("url", "https://127.0.0.1:1"); + sink.set_property("broadcast", "pause-test"); + let pad = sink + .request_pad_simple("sink_0") + .unwrap() + .downcast::() + .unwrap(); + sink.set_state(gst::State::Paused).unwrap(); + let mut broadcast = moq_net::broadcast::Info::new().produce(); + let catalog = moq_mux::catalog::Producer::new(&mut broadcast, moq_mux::catalog::Config::default()).unwrap(); + let caps = gst::Caps::builder("audio/x-opus") + .field("rate", 48_000i32) + .field("channels", 2i32) + .build(); + assert!(matches!( + pad.lifecycle().media.observe_caps( + &broadcast, + &catalog, + ProducerOptions::new(&caps).with_track("audio").with_encoder(true) + ), + CapsOutcome::Active(_) + )); + let segment = gst::FormattedSegment::::new(); + pad.lifecycle().media.observe_segment(segment.upcast()); + sink.set_state(gst::State::Playing).unwrap(); + let anchor = Instant::now(); + for (pts, arrival) in [(0, 0), (20, 120), (40, 6_000), (60, 6_020)] { + if pts == 40 { + sink.set_state(gst::State::Paused).unwrap(); + sink.set_state(gst::State::Playing).unwrap(); + } + assert_eq!( + pad.lifecycle() + .media + .push_buffer( + Bytes::from_static(b"opus frame"), + Some(gst::ClockTime::from_mseconds(pts)), + None, + None, + anchor + Duration::from_millis(arrival) + ) + .unwrap(), + PushOutcome::Published + ); + } + assert_eq!( + catalog.snapshot().audio.renditions["audio"].jitter, + Some(Duration::from_millis(100)) + ); + sink.set_state(gst::State::Null).unwrap(); + } + fn spec(element: &super::super::MoqSink, name: &str) -> glib::ParamSpec { element.find_property(name).unwrap() } diff --git a/rs/moq-gst/src/sink/pad.rs b/rs/moq-gst/src/sink/pad.rs index 23ecdb1a33f..dcbc84bec90 100644 --- a/rs/moq-gst/src/sink/pad.rs +++ b/rs/moq-gst/src/sink/pad.rs @@ -49,13 +49,27 @@ struct Media { /// irregularly a local encoder delivers. Imports leave it off: their arrival times describe the /// file or network, not the encoder. encoder: bool, + /// Apply a timeline break before the next valid frame, using the normal write error path. + discontinuity: bool, + /// A video break closed the group, and a pause resumes mid-GOP, so deltas drop until a keyframe + /// opens the next one. + keyframe: bool, } impl Media { - /// Publish one frame at `micros` on the media clock, handed over at `now`. - fn write(&mut self, data: &Bytes, micros: u64, now: Instant) -> Result<()> { + /// Publish one frame at `micros` on the media clock, handed over at `now`. Returns false when a + /// delta frame is dropped while waiting for the keyframe after a break. + fn write(&mut self, data: &Bytes, micros: u64, now: Instant) -> Result { + if std::mem::take(&mut self.discontinuity) { + self.track.discontinuity()?; + self.keyframe = !self.audio; + } let ts = hang::container::Timestamp::from_micros(micros).ok(); - self.track.decode(data, ts)?; + match self.track.decode(data, ts) { + Err(moq_mux::Error::MissingKeyframe(_)) if self.keyframe => return Ok(false), + result => result?, + } + self.keyframe = false; // One group (one QUIC stream) per audio packet, so the relay forwards it without waiting for // the next. if self.audio { @@ -66,7 +80,7 @@ impl Media { let ts = ts.context("encoder frame timestamp out of range")?; self.track.flush(ts, now)?; } - Ok(()) + Ok(true) } } @@ -464,7 +478,13 @@ impl Pad { } other => anyhow::bail!("unsupported caps: {other}"), }; - self.track = Some(Sink::Media(Box::new(Media { track, audio, encoder }))); + self.track = Some(Sink::Media(Box::new(Media { + track, + audio, + encoder, + discontinuity: false, + keyframe: false, + }))); self.caps = Some(caps.clone()); Ok(name) } @@ -590,7 +610,14 @@ impl Pad { self.segment_info = Some(info); match classify_segment(prev.as_ref(), &info) { Ok(()) => { - self.segment = segment.downcast::().ok(); + let segment = segment.downcast::().ok(); + if self.segment.is_some() + && self.segment != segment + && let Some(Sink::Media(media)) = self.track.as_mut() + { + media.discontinuity = true; + } + self.segment = segment; self.state = PadState::Active; } Err(reason) => { @@ -606,13 +633,23 @@ impl Pad { /// Re-anchor on FLUSH. A flushing seek rewinds running time, so the timeline must restart: dropping /// the segment moves the pad to NoSegment (the next SEGMENT is accepted fresh via `prev = None`). The - /// producer is kept (FLUSH is not EOS); the codec's partial-AU reset is a documented follow-up. + /// producer is kept (FLUSH is not EOS); its next frame declares the break and resets partial input. pub fn flush(&mut self) { + self.discontinuity(); self.state = PadState::NoSegment; self.segment = None; self.segment_info = None; } + /// Restart measurement on the next frame while retaining the current segment. + pub fn discontinuity(&mut self) { + if self.segment.is_some() + && let Some(Sink::Media(media)) = self.track.as_mut() + { + media.discontinuity = true; + } + } + /// Maps a buffer PTS to a MoQ timestamp without enforcing frame-level monotonicity: frames arrive in /// decode order and B-frames carry non-monotonic presentation timestamps, so a PTS regression is /// normal reordering. Timeline breaks are caught at the SEGMENT level (the `Invalid` state). @@ -666,7 +703,13 @@ impl Pad { match timestamp { Ok(micros) => { let result: Result<()> = match self.track.as_mut().expect("track present") { - Sink::Media(media) => media.write(&data, micros, now), + Sink::Media(media) => match media.write(&data, micros, now) { + Ok(false) => { + gst::debug!(CAT, "dropping delta frame until the keyframe after a break"); + return Ok(PushOutcome::Dropped); + } + result => result.map(|_| ()), + }, Sink::Text(text) => match std::str::from_utf8(&data) { // A cue with no duration would never be dismissed, so drop it rather than pin it // on screen; the demuxer supplies one for every real subtitle sample. @@ -1629,6 +1672,92 @@ mod tests { assert_eq!(jitter("import"), None, "an import's arrival never reaches the catalog"); } + #[test] + fn encoder_seek_does_not_measure_the_pause_as_jitter() { + gst::init().unwrap(); + for boundary in ["segment", "flush", "pause"] { + let (broadcast, catalog) = producers(); + let mut pad = Pad::new(); + pad.observe_caps( + &broadcast, + &catalog, + producer_options(&h264_caps(), Some("encoder")).with_encoder(true), + ); + let anchor = Instant::now(); + for (pts, arrival) in [(0, 0), (33, 33), (66, 166)] { + pad.observe_segment(time_segment()); + assert_eq!( + pad.push_buffer( + h264_keyframe_au(), + Some(gst::ClockTime::from_mseconds(pts)), + None, + None, + anchor + std::time::Duration::from_millis(arrival) + ) + .unwrap(), + PushOutcome::Published + ); + } + let before = catalog.snapshot().video.renditions["encoder"].jitter; + assert_eq!(before, Some(std::time::Duration::from_millis(100))); + match boundary { + "flush" => pad.flush(), + "pause" => pad.discontinuity(), + _ => {} + } + // Seek in the source while keeping the broadcast media clock moving forward. + for (pts, arrival) in [(30_000, 6_000), (30_033, 6_033)] { + let pts = if boundary == "pause" { + // Pausing preserves the segment while the running clock stops. + pts - 29_000 + } else { + pad.observe_segment(time_segment_at(30_000, 1_000)); + pts + }; + assert_eq!( + pad.push_buffer( + h264_keyframe_au(), + Some(gst::ClockTime::from_mseconds(pts)), + None, + None, + anchor + std::time::Duration::from_millis(arrival) + ) + .unwrap(), + PushOutcome::Published + ); + } + assert_eq!( + catalog.snapshot().video.renditions["encoder"].jitter, + before, + "boundary={boundary}" + ); + } + } + + // A pause resumes mid-GOP: the break closed the group, so deltas drop until the next keyframe + // instead of invalidating the pad. + #[test] + fn video_pause_drops_deltas_until_the_next_keyframe() { + gst::init().unwrap(); + let (broadcast, catalog) = producers(); + let mut pad = Pad::new(); + pad.observe_caps(&broadcast, &catalog, producer_options(&h264_caps(), Some("video"))); + pad.observe_segment(time_segment()); + let delta = Bytes::from_static(&[0, 0, 0, 1, 0x61, 0xe0, 0x12, 0x34]); + let now = Instant::now(); + let push = |pad: &mut Pad, data: Bytes, pts: u64| { + pad.push_buffer(data, Some(gst::ClockTime::from_mseconds(pts)), None, None, now) + .unwrap() + }; + assert_eq!(push(&mut pad, h264_keyframe_au(), 0), PushOutcome::Published); + assert_eq!(push(&mut pad, delta.clone(), 33), PushOutcome::Published); + pad.discontinuity(); + assert_eq!(push(&mut pad, delta.clone(), 66), PushOutcome::Dropped); + assert_eq!(push(&mut pad, delta.clone(), 100), PushOutcome::Dropped); + assert_eq!(push(&mut pad, h264_keyframe_au(), 133), PushOutcome::Published); + assert_eq!(push(&mut pad, delta, 166), PushOutcome::Published); + } + // Text and opaque tracks carry no codec jitter, so asking them to measure one is a mistake to report // rather than a setting to ignore. #[test] diff --git a/rs/moq-mux/src/codec/av1/import.rs b/rs/moq-mux/src/codec/av1/import.rs index dac785c7592..913e41312bd 100644 --- a/rs/moq-mux/src/codec/av1/import.rs +++ b/rs/moq-mux/src/codec/av1/import.rs @@ -224,6 +224,11 @@ impl Import { Ok(()) } + /// Mark a timeline break and restart measurement without lowering advertised values. + pub fn discontinuity(&mut self) -> crate::Result<()> { + self.track.discontinuity() + } + /// Close the current group and open the next one at `sequence`. pub fn seek(&mut self, sequence: u64) -> Result<()> { self.track.seek(sequence)?; diff --git a/rs/moq-mux/src/codec/flac/import.rs b/rs/moq-mux/src/codec/flac/import.rs index 39d68fa9253..a2564adc444 100644 --- a/rs/moq-mux/src/codec/flac/import.rs +++ b/rs/moq-mux/src/codec/flac/import.rs @@ -70,6 +70,11 @@ impl Import { Ok(()) } + /// Mark a timeline break and restart measurement without lowering advertised values. + pub fn discontinuity(&mut self) -> crate::Result<()> { + self.track.discontinuity() + } + /// Close the current group and open the next one at `sequence`. pub fn seek(&mut self, sequence: u64) -> crate::Result<()> { self.track.seek(sequence)?; diff --git a/rs/moq-mux/src/codec/mp3.rs b/rs/moq-mux/src/codec/mp3.rs index c3cf45ac4e1..f1cd26c703c 100644 --- a/rs/moq-mux/src/codec/mp3.rs +++ b/rs/moq-mux/src/codec/mp3.rs @@ -158,6 +158,11 @@ impl Import { Ok(()) } + /// Mark a timeline break and restart measurement without lowering advertised values. + pub fn discontinuity(&mut self) -> crate::Result<()> { + self.track.discontinuity() + } + /// Close the current group and open the next one at `sequence`. pub fn seek(&mut self, sequence: u64) -> crate::Result<()> { self.track.seek(sequence)?; diff --git a/rs/moq-mux/src/codec/vp8/import.rs b/rs/moq-mux/src/codec/vp8/import.rs index 7eabb0a2f3d..01837a89b9b 100644 --- a/rs/moq-mux/src/codec/vp8/import.rs +++ b/rs/moq-mux/src/codec/vp8/import.rs @@ -141,6 +141,11 @@ impl Import { Ok(()) } + /// Mark a timeline break and restart measurement without lowering advertised values. + pub fn discontinuity(&mut self) -> crate::Result<()> { + self.track.discontinuity() + } + /// Close the current group and open the next one at `sequence`. pub fn seek(&mut self, sequence: u64) -> crate::Result<()> { self.track.seek(sequence)?; diff --git a/rs/moq-mux/src/codec/vp9/import.rs b/rs/moq-mux/src/codec/vp9/import.rs index 71f64b6433e..8369e14c3e7 100644 --- a/rs/moq-mux/src/codec/vp9/import.rs +++ b/rs/moq-mux/src/codec/vp9/import.rs @@ -141,6 +141,11 @@ impl Import { Ok(()) } + /// Mark a timeline break and restart measurement without lowering advertised values. + pub fn discontinuity(&mut self) -> crate::Result<()> { + self.track.discontinuity() + } + /// Close the current group and open the next one at `sequence`. pub fn seek(&mut self, sequence: u64) -> crate::Result<()> { self.track.seek(sequence)?; diff --git a/rs/moq-mux/src/import/track.rs b/rs/moq-mux/src/import/track.rs index 45212b9e46f..4430b6d1797 100644 --- a/rs/moq-mux/src/import/track.rs +++ b/rs/moq-mux/src/import/track.rs @@ -460,6 +460,44 @@ impl Track { } } + /// Mark a timeline break, clearing partial frames and restarting handoff measurement. + /// + /// Publishes a marker without lowering advertised values; resumed timestamps must continue forward. + pub fn discontinuity(&mut self) -> Result<()> { + self.group_start = None; + match self.kind { + TrackKind::Avc3 { + ref mut split, + ref mut import, + } => { + split.reset(); + import.discontinuity() + } + TrackKind::Avc1 { ref mut import, .. } => import.discontinuity(), + TrackKind::Hev1 { + ref mut split, + ref mut import, + } => { + split.reset(); + import.discontinuity() + } + TrackKind::Hvc1 { ref mut import, .. } => import.discontinuity(), + TrackKind::Av01 { + ref mut split, + ref mut import, + } => { + split.reset(); + import.discontinuity() + } + TrackKind::Vp8(ref mut import) => import.discontinuity(), + TrackKind::Vp9(ref mut import) => import.discontinuity(), + TrackKind::Aac(ref mut import) => import.discontinuity(), + TrackKind::Opus(ref mut import) => import.discontinuity(), + TrackKind::Mp3(ref mut import) => import.discontinuity(), + TrackKind::Flac(ref mut import) => import.discontinuity(), + } + } + /// Close the current group and open the next one at `sequence`. pub fn seek(&mut self, sequence: u64) -> Result<()> { self.group_start = None; @@ -990,6 +1028,35 @@ mod tests { assert_eq!(collect_groups(subscriber).await, vec![3, 2]); } + #[tokio::test(start_paused = true)] + async fn discontinuity_resets_audio_measurement_and_separates_groups() { + let (mut broadcast, catalog) = new_broadcast(); + let (import, subscriber) = opus_import(&mut broadcast, &catalog); + let mut import: Track = import.into(); + let anchor = std::time::Instant::now(); + for (pts, arrival) in [(0, 0), (20, 120)] { + let timestamp = Timestamp::from_micros(pts * 1_000).unwrap(); + import.decode(b"a", Some(timestamp)).unwrap(); + import + .flush(timestamp, anchor + Duration::from_millis(arrival)) + .unwrap(); + } + let before = catalog.snapshot().audio.renditions["audio"].jitter; + assert_eq!(before, Some(Duration::from_millis(100))); + import.discontinuity().unwrap(); + for (pts, arrival) in [(100, 6_000), (120, 6_020)] { + let timestamp = Timestamp::from_micros(pts * 1_000).unwrap(); + import.decode(b"b", Some(timestamp)).unwrap(); + import + .flush(timestamp, anchor + Duration::from_millis(arrival)) + .unwrap(); + } + assert_eq!(catalog.snapshot().audio.renditions["audio"].jitter, before); + import.finish().unwrap(); + // The middle group is the established empty-payload discontinuity marker. + assert_eq!(collect_groups(subscriber).await, vec![2, 1, 2]); + } + /// Cutting after every frame is still available, and is what a caller wanting the lowest /// latency does: one group (one QUIC stream) per packet, forwarded without waiting. #[tokio::test(start_paused = true)] diff --git a/swift/Sources/Moq/Media.swift b/swift/Sources/Moq/Media.swift index 13ab75acfc7..d2494b20cd6 100644 --- a/swift/Sources/Moq/Media.swift +++ b/swift/Sources/Moq/Media.swift @@ -136,6 +136,11 @@ public final class MediaProducer: Sendable { try ffi.flush(timestampUs: timestampUs) } + /// Mark a timeline break and restart handoff measurement, preserving advertised jitter. + public func discontinuity() throws { + try ffi.discontinuity() + } + /// Draw a group boundary here. /// /// Audio has no boundary of its own (every packet is independently decodable), so this is the