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
2 changes: 1 addition & 1 deletion dart/moq/lib/src/aliases.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
25 changes: 25 additions & 0 deletions dart/moq_ffi/lib/src/moq.dart
Original file line number Diff line number Diff line change
Expand Up @@ -6871,6 +6871,7 @@ class FfiConverterMoqGroupRequest {
abstract class MoqMediaProducerInterface {
void cut();
MoqTrackDemand demand();
void discontinuity();
void finish();
void flush({required int timestampUs});
String name();
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -10912,6 +10922,14 @@ external Pointer<Void> uniffi_moq_ffi_fn_method_moqmediaproducer_demand(
Pointer<RustCallStatus> uniffiStatus,
);

@Native<Void Function(Pointer<Void>, Pointer<RustCallStatus>)>(
assetId: _uniffiAssetId,
)
external void uniffi_moq_ffi_fn_method_moqmediaproducer_discontinuity(
Pointer<Void> ptr,
Pointer<RustCallStatus> uniffiStatus,
);

@Native<Void Function(Pointer<Void>, Pointer<RustCallStatus>)>(
assetId: _uniffiAssetId,
)
Expand Down Expand Up @@ -12309,6 +12327,9 @@ external int uniffi_moq_ffi_checksum_method_moqmediaproducer_cut();
@Native<Uint16 Function()>(assetId: _uniffiAssetId)
external int uniffi_moq_ffi_checksum_method_moqmediaproducer_demand();

@Native<Uint16 Function()>(assetId: _uniffiAssetId)
external int uniffi_moq_ffi_checksum_method_moqmediaproducer_discontinuity();

@Native<Uint16 Function()>(assetId: _uniffiAssetId)
external int uniffi_moq_ffi_checksum_method_moqmediaproducer_finish();

Expand Down Expand Up @@ -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");
}
Expand Down
2 changes: 2 additions & 0 deletions dart/moq_ffi/lib/src/uniffi_runtime.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -247,6 +248,7 @@ mixin FfiConverterPrimitive<T> on FfiConverter<T, T> {
@override
T lower(T value) => value;
}

Uint8List createUint8ListFromInt(int value) {
int length = value.bitLength ~/ 8 + 1;
if (length != 4 && length != 8) {
Expand Down
5 changes: 5 additions & 0 deletions doc/bin/gstreamer.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 2 additions & 0 deletions doc/lib/c/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<field>_valid` flag,
Expand Down
2 changes: 2 additions & 0 deletions doc/lib/dart/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
2 changes: 2 additions & 0 deletions doc/lib/go/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions doc/lib/kt/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions doc/lib/py/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)` /
Expand Down
9 changes: 6 additions & 3 deletions doc/lib/rs/moq-mux.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 2 additions & 0 deletions doc/lib/swift/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
5 changes: 5 additions & 0 deletions go/wrapper/publish.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions py/moq-rs/moq/publish.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 2 additions & 0 deletions py/moq-rs/tests/test_local.py
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down
1 change: 0 additions & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
20 changes: 0 additions & 20 deletions quest/m1/import-discontinuity.md

This file was deleted.

12 changes: 12 additions & 0 deletions rs/libmoq/src/api.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
7 changes: 7 additions & 0 deletions rs/libmoq/src/publish.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions rs/libmoq/src/test.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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);

Expand Down
11 changes: 11 additions & 0 deletions rs/moq-ffi/src/producer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions rs/moq-ffi/src/test.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
66 changes: 65 additions & 1 deletion rs/moq-gst/src/sink/imp.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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::<MoqSinkPad>().expect("sink pad type");
pad.lifecycle().media.discontinuity();
}
}

fn publish_finished(&self, finished: Finished) {
Expand Down Expand Up @@ -1092,6 +1100,62 @@ mod tests {
glib::Object::builder::<super::super::MoqSink>().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::<MoqSinkPad>()
.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::<gst::ClockTime>::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()
}
Expand Down
Loading
Loading