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
11 changes: 0 additions & 11 deletions cpp/obs/src/moq-output.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -639,17 +639,11 @@ void MoQOutput::AudioData(struct encoder_packet *packet)
// Audio has no keyframes, so it has no group boundary of its own: without this the whole
// stream is one group. Cut per frame, which is one QUIC stream per packet forwarded without
// waiting for the next, the right trade for live. Video groups at its own keyframes.
// Cut before observing the flush so a failed observation never leaves the group open.
if (auto result = track.producer->cut(); !result) {
LOG_ERROR("Failed to cut audio group: %s", result.error().to_string().c_str());
return;
}

if (auto result = track.producer->flush(*timestamp); !result) {
LOG_ERROR("Failed to observe audio encoder flush: %s", result.error().to_string().c_str());
return;
}

total_bytes_sent += packet->size;
}

Expand Down Expand Up @@ -686,11 +680,6 @@ void MoQOutput::VideoData(struct encoder_packet *packet)
return;
}

if (auto result = track.producer->flush(*timestamp); !result) {
LOG_ERROR("Failed to observe video encoder flush: %s", result.error().to_string().c_str());
return;
}

total_bytes_sent += packet->size;
}

Expand Down
28 changes: 1 addition & 27 deletions dart/moq_ffi/lib/src/moq.dart
Original file line number Diff line number Diff line change
Expand Up @@ -11100,7 +11100,6 @@ abstract class MoqMediaTrackProducerInterface {
MoqTrackDemand demand();
void discontinuity();
void finish();
void flush({required int timestampUs});
void seek({required int sequence});
void writeFrame({required MoqFrame frame});
}
Expand Down Expand Up @@ -11208,16 +11207,6 @@ class MoqMediaTrackProducer implements MoqMediaTrackProducerInterface {
}, moqExceptionErrorHandler);
}

void flush({required int timestampUs}) {
return rustCall((status) {
uniffi_moq_ffi_fn_method_moqmediatrackproducer_flush(
uniffiClonePointer(),
FfiConverterUInt64.lower(timestampUs),
status,
);
}, moqExceptionErrorHandler);
}

void seek({required int sequence}) {
return rustCall((status) {
uniffi_moq_ffi_fn_method_moqmediatrackproducer_seek(
Expand Down Expand Up @@ -17820,15 +17809,6 @@ external void uniffi_moq_ffi_fn_method_moqmediatrackproducer_finish(
Pointer<RustCallStatus> uniffiStatus,
);

@Native<Void Function(Pointer<Void>, Uint64, Pointer<RustCallStatus>)>(
assetId: _uniffiAssetId,
)
external void uniffi_moq_ffi_fn_method_moqmediatrackproducer_flush(
Pointer<Void> ptr,
int timestamp_us,
Pointer<RustCallStatus> uniffiStatus,
);

@Native<Void Function(Pointer<Void>, Uint64, Pointer<RustCallStatus>)>(
assetId: _uniffiAssetId,
)
Expand Down Expand Up @@ -19747,9 +19727,6 @@ uniffi_moq_ffi_checksum_method_moqmediatrackproducer_discontinuity();
@Native<Uint16 Function()>(assetId: _uniffiAssetId)
external int uniffi_moq_ffi_checksum_method_moqmediatrackproducer_finish();

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

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

Expand Down Expand Up @@ -20449,15 +20426,12 @@ void _checkApiChecksums() {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqmediatrackproducer_discontinuity() !=
32931) {
25213) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqmediatrackproducer_finish() != 45426) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqmediatrackproducer_flush() != 51126) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_method_moqmediatrackproducer_seek() != 37244) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
Expand Down
26 changes: 10 additions & 16 deletions doc/bin/gstreamer.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ nix shell github:moq-dev/moq/release#moq-gst --command gst-launch-1.0 -e \
# Publish a test pattern
gst-launch-1.0 -e videotestsrc is-live=true ! x264enc tune=zerolatency ! h264parse \
! video/x-h264,stream-format=byte-stream,alignment=au ! mux.sink_0 \
moqsink name=mux url=https://cdn.moq.dev/anon broadcast=<your-name>.hang sink_0::encoder=true
moqsink name=mux url=https://cdn.moq.dev/anon broadcast=<your-name>.hang
```

Install via `apt install gstreamer1.0-moq` or `dnf install gstreamer1-moq`
Expand Down Expand Up @@ -58,8 +58,7 @@ directly. A cue with no duration is dropped rather than left on screen.
Audio packets share groups of at least 20 ms while forwarding as they arrive.
Each `sink_%u` request pad is one track. Pad properties: `track` names it
(default: after the codec), `container=loc` publishes it as
[LOC](/concept/standard#loc) instead of the legacy hang container,
`encoder=true` marks it as fed by a local encoder, and
[LOC](/concept/standard#loc) instead of the legacy hang container, and
`track-status`/`track-error` report its lifecycle. Element properties:
`url`, `broadcast`, `tls-disable-verify`, `quic-idle-timeout`, `quic-keylog`,
`quic-keep-alive`, `linger`, and read-only `status`, `connected`, `moq-version`, and
Expand Down Expand Up @@ -100,19 +99,14 @@ in the same shape as the relay's sessions track. One read returns both from
the same instant, so their difference is 1 while connected. Unlike `status`, a
drop you did not poll still moves both counters.

Set `encoder=true` on audio and video pads a local encoder feeds
(`x264enc`, `opusenc`, ...). The pad then measures how late each frame reaches
the sink behind its running time and raises the catalog `jitter` by the spread,
and `delay` by how far it trails the earliest such pad, so players buffer for an
encoder that delivers irregularly or behind the others. Leave it off, the
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 resets
the handoff measurement baseline. The pause does not inflate
advertised jitter, and previously measured maxima remain. Resumed timestamps
must continue forward on the broadcast media clock.
The catalog `delay` of each pad is how far its buffers' timestamps trail ones
the other pads already pushed, so players buffer for an encoder that delivers
behind the others. Arrival time is never measured, so file, demuxed, and network
media advertise the same values as a live encoder.

After a pause, flush, or changed TIME segment, the pad stops holding the others
back until its next buffer, and previously measured maxima remain. Resumed
timestamps must continue forward on the broadcast media clock.

A video pad joining mid-GOP drops delta frames until its first keyframe. If a
source rewinds below the producer's live edge without signalling a break, the
Expand Down
29 changes: 15 additions & 14 deletions doc/concept/audio-jitter.md
Original file line number Diff line number Diff line change
Expand Up @@ -304,24 +304,25 @@ business.

## The advertised flush span, and how it composes

A hang rendition may advertise `jitter`: the largest delay the publisher has
seen between a frame being ready and handing it to the transport. It is
A hang rendition may advertise `jitter`: the largest span of media the
publisher writes behind a frame's timestamp, from B-frame reordering or a batch
written together. It is
described in [hang](/concept/hang) and specified in
[draft-lcurley-moq-hang](/draft/moq-hang). The two quantities share a word and
get confused for each other, so plainly:

| | Advertised `jitter` | The estimate here |
| --- | --- | --- |
| Measured by | the publisher, once | each receiver, continuously |
| Measured at | the transport handoff | the receiver's transport |
| Covers | encoder latency, packet packing, reorder, segmentation | all of that, plus the network |
| Measured from | media timestamps | the receiver's arrival times |
| Covers | packet packing, reorder, segmentation | all of that, plus encoder latency and the network |
| Is | a declared lower bound | an observation |

**They compose as a maximum, and the reason matters.** Both are the same
formula, lateness relative to a windowed minimum, evaluated one hop apart. The
receiver measures from the frame's media timestamp to its own arrival, so the
publisher's flush delay is already inside every number on this page: a publisher
flushing 100 ms of media at once produces arrivals whose relative delay reaches
**They compose as a maximum, and the reason matters.** Both are lateness
behind the media timestamp, evaluated one hop apart. The receiver measures from
the frame's media timestamp to its own arrival, so the publisher's batching is
already inside every number on this page: a publisher writing 100 ms of media at
once produces arrivals whose relative delay reaches
100 ms less one frame, on a perfect network, with no help from the catalog.

So the advertised value is a **floor**, not an addend:
Expand All @@ -335,7 +336,7 @@ publishers that need it most. Taking the maximum on the grounds that they
"describe the same quantity" reaches the right operation by the wrong argument:
they are the same quantity measured at different points, and the receiver's
point strictly contains the publisher's. The floor earns its place by being
correct *immediately*, before the estimator has seen a full flush cycle, which
correct *immediately*, before the estimator has seen a full batch, which
is the one thing a measurement cannot be.

## Across renditions
Expand All @@ -346,9 +347,9 @@ constant offset between tracks cancels out of `measured`: a video encoder that
flushes 200 ms behind the audio encoder produces the same video target as one
that does not, and its frames would all arrive 200 ms late for the shared clock.

The catalog `delay` field carries that offset: how far a rendition's minimum
flush lateness trails the broadcast's earliest rendition, measured by the
publisher and never lowered. It is an addend, not a floor, because nothing on
The catalog `delay` field carries that offset: how far a rendition's
timestamps trail those the broadcast's other renditions already wrote, measured
by the publisher and never lowered. It is an addend, not a floor, because nothing on
this page contains it. The shared playout is the largest requirement among the
renditions actually subscribed:

Expand All @@ -357,7 +358,7 @@ playout = max over subscribed renditions of (delay + target)
```

A receiver **must not** subtract one rendition's `delay` from another's. Each is
a lifetime maximum taken against a sliding baseline, so two values need not
a lifetime maximum taken against whichever rendition was ahead, so two values need not
share an origin: if the earliest rendition later drifts behind another, their
difference understates the real spread. The maximum never under-buffers,
because the subscribed renditions' spread is measured from an earliest baseline
Expand Down
6 changes: 3 additions & 3 deletions doc/concept/hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,8 +65,8 @@ A few things the catalog can express beyond decoder config:
- **Labels.** Any rendition may carry a human-readable `label` for a track picker. The map key stays the rendition's ID, so labels need not be unique and renaming one doesn't rename the track.
- **Renditions in another broadcast.** A rendition may point at a relative broadcast path, so a transcoder can publish a ladder that adds low rungs and references the source's original rendition without re-publishing its bytes. The path resolves against where the consumer found the catalog, so a reference that escapes above the root names nothing and the catalog is rejected. `@moq/watch` and `moqsrc` follow a referenced path's announcements like their own, restarting the rendition on each instance that serves it; every other reader, such as `moq play`, the exporters, and the bindings, waits for the first one announced and keeps it, and an exporter ends the rendition with it. An optional `epoch` beside the path names the [publisher instance](/concept/moq-lite#publisher-epochs) it expects: a route proving another instance ends the rendition instead of falling back to it, while a route without an epoch (an older version) cannot prove one, so there it is best effort.
- **Track names.** The map key is a rendition's ID and, by default, its track name. A rendition sets `track` only when the two must differ, such as two renditions of same-named tracks in different broadcasts, or a rendition whose media changed and so needs a new name; readers subscribe to `track` when present. An ID can't name both a video and an audio rendition.
- **Jitter.** A rendition can say how far its frames fell behind the media clock before the publisher flushed them, in whole milliseconds rounded up. Encoders report the spread of lateness above each rendition's own recent minimum, so a constant encoder delay is not jitter; container imports estimate batch spans without counting ingest delay. It describes the publisher, never the network, only grows over the life of a stream, and a player sizes its buffer to at least this much. A `0` is read as absent.
- **Delay.** A rendition can also say how far its frames reach the transport behind the broadcast's earliest rendition, measured the same way from each rendition's minimum lateness, so a video encoder running 200 ms behind audio advertises `delay: 200` on video. It follows the same rules as jitter. A player holds the largest `delay + jitter` among the renditions it subscribes to, and never subtracts one rendition's `delay` from another's.
- **Jitter.** A rendition can say how much media it writes behind a frame's timestamp, in whole milliseconds rounded up: the reorder delay of B-frames and the span of a fragment or batch written together. It is measured from media timestamps alone, never the time a frame was written, so neither a constant encoder delay nor a capture clock counts. It describes the publisher, never the network, only grows over the life of a stream, and a player sizes its buffer to at least this much. A `0` is read as absent.
- **Delay.** A rendition can also say how far its frames' timestamps trail those another rendition already wrote, so a video encoder running 200 ms behind audio advertises `delay: 200` on video. A rendition alone measures none. It follows the same rules as jitter. A player holds the largest `delay + jitter` among the renditions it subscribes to, and never subtracts one rendition's `delay` from another's.
- **Colour.** A video rendition may carry `color`: the H.273 primaries, transfer, matrix, and range, plus the HDR10 mastering display and content light levels, so a renderer can set up HDR without parsing the bitstream. The Rust importers fill it from the SPS VUI, AV1 sequence header, and VP9 header, then fill gaps from a container's `colr` box or Matroska `Colour` element; the stream wins a disagreement. The HDR10 values come from H.264 and H.265 SEI or AV1 metadata OBUs in MPEG-TS and raw elementary streams, an AV1 track's av1C, or Matroska, but not yet from H.264 or H.265 in fMP4 or FLV. Nothing in `@moq/watch` reads it yet.
- **Spatial media.** A video rendition may carry `projection` (flat `rectilinear`, or `equirectangular` with the degrees of longitude it spans, 180 for VR180) and `stereo` (`mono`, `left-right`, or `top-bottom` frame packing), and an audio rendition may carry `layout: "ambisonic"` for AmbiX channels. Readers treat a value they don't recognize as absent. Nothing in `@moq/watch` renders them yet.
- **Disabled renditions.** An audio or video rendition with `enabled: false` has no frames coming, and a player must not select it. Pausing a rendition in `@moq/publish` keeps it in the catalog this way rather than removing it, so a mute is a one-field update; a disabled video rendition encodes one black keyframe first, so a player that predates the field shows black instead of a frozen picture. The field is written only when false. The older video `stalled` field is no longer written, and readers ignore it.
Expand Down Expand Up @@ -141,7 +141,7 @@ into it on a raw track.
The rest is descriptive: `compression` (`deflate`, the same group-scoped
`deflate-raw` the catalog uses), `schema` on a JSON track, `mime` on a binary
one, `bitrate`, `jitter`, and `delay` with the same meaning as for media, plus
the optional `broadcast` reference and `track` name. A publisher measures `jitter` and `delay`
the optional `broadcast` reference and `track` name. A publisher measures `delay`
only from payloads stamped with their capture time on the broadcast clock. A
consumer that doesn't recognize a `mode` or `compression` ignores that track and
round-trips it verbatim.
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/c/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ inside. The header is the reference: each function carries a doc comment.
- **fMP4 import.** `MOQ_CONTAINER_FORMAT_FMP4` splits each fragment into one frame per sample; `MOQ_CONTAINER_FORMAT_CMAF` republishes it whole.
- **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `moq_publish_media_cut`: after every frame, or at a segment cadence to align with video.
- **Ending cleanly.** When the input ends, finish every track, then call `moq_publish_finish()`. It consumes the broadcast and returns a finish handle that keeps it announced and serving the finished tracks, writing the linger, their longest max age, to `linger_us`. Keep the handle for that long on your own clock so a subscriber still catching up can drain them, then `moq_publish_finish_close()` it; closing early is the interrupt. `moq_publish_close()` stays the abrupt end.
- **Live encoder timing.** After writing a frame you encoded yourself, call `moq_publish_media_flush` with the same timestamp so the catalog advertises your jitter. Skip it for file and network imports. On a seek or pause, call `moq_publish_media_discontinuity`, then keep timestamps moving forward and resume video on a keyframe.
- **Timeline breaks.** On a seek or pause, call `moq_publish_media_discontinuity`, then keep timestamps moving forward and resume video on a keyframe.
- **JSON values.** `moq_consume_json_value` fills `moq_json_value` with the document and its frame's `timestamp_us`, rounded down to a whole microsecond; `timestamp_present` is false on an untimed track. A snapshot consumer's callback fires for each state in order, but a group superseded before it is read is skipped.
- **Decoded frames hold decoder buffers.** Free each frame id with `moq_decode_video_frame_free` promptly, or the decoder stalls.
- **Stats.** `moq_session_stats()` fills `moq_connection_stats` with `rtt_us`, `estimated_send_rate_bps`, and the byte and packet counters (`bytes_sent`, `bytes_received`, `bytes_lost`, `packets_sent`, `packets_received`, `packets_lost`). Each has a `<field>_valid` flag, false when the transport does not report it, which is not the same as zero. `moq_session_snapshot()` adds the negotiated `protocol`. A failed dial or dropped connection reaches the session's `on_state` with its `failure` code, and `moq_error()` gives the reason during that callback. Hold the handle returned by `moq_session_recv_bandwidth()` to request receive estimates. `moq_bandwidth_consumer_peek()` reads the estimate and `moq_bandwidth_consumer_changed()` waits for a change. `moq_bandwidth_consumer_close()` releases demand; the last consumer stops PROBE. Stats snapshots do not request it.
Expand Down
Loading
Loading