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
1 change: 1 addition & 0 deletions doc/lib/c/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,7 @@ inside. The header is the reference: each function carries a doc comment.
- **Ending cleanly.** When the input ends, finish every track, then call `moq_publish_catalog_finish()` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `moq_publish_close()` or `moq_route_free()` takes it offline. How long to keep it up is yours to decide. A track still open at the close ends with `UNROUTABLE` (an internal error over moq-transport, which has no such code), and its handle is released. Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity).
- **Timeline breaks.** On a seek or pause, call `moq_publish_media_discontinuity`, then keep timestamps moving forward and resume video on a keyframe.
- **Timestamps.** A `moq_timestamp` is exact: `value` units at `scale` units per second, so a 90 kHz tick survives a read and republish. Frames, datagrams, and JSON values point `timestamp` at theirs, valid as long as the payload. An untimed track has no scale, so there `has_scale` is false and `value` is the frame's group key (a datagram's sequence); every write takes one, with `moq_publish_group_start` naming a group's key. Stream tracks moq-c creates are timed, so their raw writes need one. Datagram tracks are separate and default to untimed; set their timescale when creating them to require timestamps. Stamp media frames and JSON writes from `moq_publish_catalog_now()`, the broadcast clock every track in the broadcast shares; media on a timeline of its own advertises the gap to the JSON tracks as catalog `delay`. JSON writes are converted to their track's milliseconds. A NULL timestamp on any write fails with `MOQ_ERROR_INVALID_POINTER`. A zero scale with `has_scale` set, or an out-of-range value, fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`.
- **Catalog timing.** Each catalog snapshot from `moq_consume_catalog` takes effect at the media timestamp `moq_consume_catalog_timestamp` fills. A zero `delay_us` delivers only the newest catalog; a player that holds each update until its media reaches that time passes its playout delay instead, and receives in order every update it may still need.
- **JSON values.** `moq_consume_json_value` fills `moq_json_value` with the document and its frame's timestamp. A snapshot consumer's callback fires for each state in order, but a group superseded before it is read is skipped.
- **JSON windows.** `moq_publish_json_window` publishes a sliding run of records: `moq_publish_json_window_push` appends at the back, `moq_publish_json_window_pop` drops from the front, and `moq_publish_json_window_cut` closes the open group at a natural boundary. The catalog has no window mode, so a reader names the track. `moq_consume_json_window_event` fills `moq_json_window_event` with a push (the record at `start`, in `json`), a pop of `[start, end)`, or a skip of `[start, end)` that this reader joined too late to receive. Set `checkpoint_records` to bound what each new group restates for a window you never pop.
- **Decoded reads.** `moq_decode_audio` and `moq_decode_video` deliver read ids in order: a frame, a gap where media was lost, or an end where the publisher stopped its encoder. Check `kind` on what `moq_decode_audio_read` or `moq_decode_video_read` writes. Free each id with `moq_decode_audio_read_free` or `moq_decode_video_read_free` promptly: a held video frame holds a decoder buffer, and the decoder stalls. A decoder reads everything the track still holds unless a live player sets `start` to `MOQ_DECODE_START_LATEST`, which joins at the newest group and skips the cached backlog. A decoder setup refusal reports `MOQ_ERROR_UNSUPPORTED_CONFIG` on its terminal callback, so the caller can try another rendition; later peer or decode failures retain their own error codes.
Expand Down
1 change: 1 addition & 0 deletions nix/Cargo.nix

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

23 changes: 23 additions & 0 deletions quest/m0/test-flakes-3/js-announce-reset.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# [S] js/net's reset Announce Stream test closes the session under load

## Goal

`js/net/src/lite/connection.test.ts`'s "a reset Announce Stream closes
moq-lite-07 with PROTOCOL_VIOLATION" passes every loaded `just check`.

## Plan

Found 2026-11-17 by `just check` on
[moq-dev/moq#8996](https://github.com/moq-dev/moq/pull/8996), whose change
touches no JS. Under the loaded check it hit bun's 5000 ms test timeout: the
session never closed. Run alone it passed 15 times in a row.

A timeout, not a wrong code, means the reset went unnoticed. Trace how the
connection reads the Announce Stream when the mock transport delivers the
reset before or alongside the ANNOUNCE_REQUEST it follows: if a path drops the
reset (a read that resolves with the message and never polls again, or a reset
raced against the stream's open), that is a bug in `js/net`, fixed there with
a regression test. Only if the trace shows the close is merely slow is the fix
in the test, by the epic's rules.

Public API: none. Wire: none.
29 changes: 0 additions & 29 deletions quest/m2/c-catalog-timing.md

This file was deleted.

2 changes: 1 addition & 1 deletion rs/moq-c/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ openh264 = ["moq-video/openh264"]
[dependencies]
anyhow = { workspace = true, features = ["backtrace"] }
bytes = { workspace = true }
hang = { workspace = true }
hang = { workspace = true, features = ["async"] }
kio = { workspace = true, features = ["async"] }
# Codecs only: OBS and the other C consumers do their own device I/O.
moq-audio = { workspace = true }
Expand Down
3 changes: 2 additions & 1 deletion rs/moq-c/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,7 +168,8 @@ int32_t moq_consume_closed(uint32_t broadcast, moq_status_callback on_closed, vo
int32_t moq_consume_closed_cancel(uint32_t watcher);

// Consuming: Catalog
int32_t moq_consume_catalog(uint32_t broadcast, moq_status_callback on_catalog, void *user_data);
int32_t moq_consume_catalog(uint32_t broadcast, uint64_t delay_us, moq_status_callback on_catalog, void *user_data);
int32_t moq_consume_catalog_timestamp(uint32_t catalog, moq_timestamp *dst);
int32_t moq_consume_catalog_cancel(uint32_t catalog);
int32_t moq_consume_catalog_free(uint32_t catalog);
int32_t moq_consume_video_config(uint32_t catalog, uint32_t index, moq_video_config *dst);
Expand Down
2 changes: 1 addition & 1 deletion rs/moq-c/c-tests/audio-decode-output.c
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ int main(void) {
pthread_mutex_lock(&c.mutex);
wait_until(&c, &c.broadcast);
pthread_mutex_unlock(&c.mutex);
int32_t catalogs = moq_consume_catalog((uint32_t)c.broadcast, on_catalog, &c);
int32_t catalogs = moq_consume_catalog((uint32_t)c.broadcast, 0, on_catalog, &c);
CHECK(catalogs > 0);
pthread_mutex_lock(&c.mutex);
wait_until(&c, &c.catalog);
Expand Down
2 changes: 1 addition & 1 deletion rs/moq-c/c-tests/decode-output.c
Original file line number Diff line number Diff line change
Expand Up @@ -267,7 +267,7 @@ int main(void) {
int32_t consume = c.broadcast;
pthread_mutex_unlock(&c.mu);

int32_t catalog_sub = moq_consume_catalog((uint32_t)consume, on_catalog, &c);
int32_t catalog_sub = moq_consume_catalog((uint32_t)consume, 0, on_catalog, &c);
if (catalog_sub <= 0) fail("error: moq_consume_catalog failed: %d\n", catalog_sub);

pthread_mutex_lock(&c.mu);
Expand Down
36 changes: 34 additions & 2 deletions rs/moq-c/src/api.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4489,7 +4489,8 @@ pub extern "C" fn moq_publish_json_window_finish(window: u32) -> i32 {
})
}

/// Create a catalog consumer for a broadcast.
/// Create a catalog consumer for a broadcast, for a reader playing `delay_us` microseconds
/// behind the live edge.
///
/// `on_catalog` is invoked with a positive catalog ID for each catalog update
/// (usable to query video/audio track information), then exactly once more with
Expand All @@ -4498,20 +4499,51 @@ pub extern "C" fn moq_publish_json_window_finish(window: u32) -> i32 {
/// touched again, so release `user_data` there. The terminal callback fires even
/// after [moq_consume_catalog_cancel].
///
/// Each update takes effect at its [moq_consume_catalog_timestamp]. A zero `delay_us` delivers
/// only the newest catalog, for a reader that applies each on arrival. A reader that holds each
/// update until its media reaches the update's timestamp passes its playout delay instead, and
/// receives in order every update it may still need: one stays deliverable until it falls
/// `delay_us` behind the live edge.
///
/// Returns a non-zero handle on success, or a negative code on failure.
///
/// # Safety
/// - The caller must keep `user_data` valid until the terminal (`<= 0`) `on_catalog` callback.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn moq_consume_catalog(
broadcast: u32,
delay_us: u64,
on_catalog: ffi::moq_status_callback,
user_data: *mut c_void,
) -> i32 {
ffi::enter(move || {
let broadcast = ffi::parse_id(broadcast)?;
let delay = std::time::Duration::from_micros(delay_us);
let on_catalog = unsafe { ffi::OnStatus::new(user_data, on_catalog)? };
State::lock().consume.catalog(broadcast, on_catalog)
State::lock().consume.catalog(broadcast, delay, on_catalog)
})
}

/// Query the media timestamp a catalog snapshot takes effect at.
///
/// A reader holds a snapshot it receives before its media reaches this time, and applies one
/// received late, or the first it receives, at once. On a scale-less catalog track `has_scale` is
/// false and `value` is a group key with no time, so the snapshot applies on arrival.
///
/// Returns a zero on success, or a negative code on failure.
///
/// # Safety
/// - The caller must ensure that `dst` is a valid pointer to a [moq_timestamp] struct.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn moq_consume_catalog_timestamp(catalog: u32, dst: *mut moq_timestamp) -> i32 {
ffi::enter(move || {
let catalog = ffi::parse_id(catalog)?;
if dst.is_null() {
return Err(Error::InvalidPointer);
}
let timestamp = State::lock().consume.catalog_timestamp(catalog)?;
unsafe { dst.write(timestamp) };
Ok(())
})
}

Expand Down
22 changes: 18 additions & 4 deletions rs/moq-c/src/consume.rs
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,9 @@ struct ConsumeCatalog {
// into `moq_catalog_section_*` instead of being dropped on parse.
catalog: moq_mux::catalog::hang::Catalog<moq_mux::catalog::hang::Extra>,

/// The media timestamp this snapshot takes effect at.
timestamp: moq_timestamp,

/// We need to store the codec information on the heap unfortunately.
audio_codec: Vec<String>,
video_codec: Vec<String>,
Expand Down Expand Up @@ -369,7 +372,8 @@ impl Consume {
self.closed_task.close(task, Error::NotFound)
}

pub fn catalog(&mut self, broadcast: Id, on_catalog: OnStatus) -> Result<Id, Error> {
/// Read a broadcast's catalog updates for a reader playing `delay` behind the live edge.
pub fn catalog(&mut self, broadcast: Id, delay: Duration, on_catalog: OnStatus) -> Result<Id, Error> {
let ConsumeBroadcast { broadcast, origin } =
self.broadcast.get(broadcast).ok_or(Error::BroadcastNotFound)?.clone();

Expand All @@ -384,7 +388,8 @@ impl Consume {
driver
.watch(async move {
// The consumer subscribes itself at catalog priority.
let catalog = broadcast.track(hang::catalog::Catalog::DEFAULT_NAME)?.into();
let track = broadcast.track(hang::catalog::Catalog::DEFAULT_NAME)?;
let catalog = hang::catalog::Consumer::new(track, delay);
Comment thread
kixelated marked this conversation as resolved.
Resolved
Self::run_catalog(on_catalog, broadcast.clone(), origin, catalog, close).await
})
.await
Expand All @@ -396,14 +401,14 @@ impl Consume {
callback: OnStatus,
broadcast: moq_net::broadcast::Consumer,
origin: Option<crate::origin::Consumer>,
mut catalog: moq_mux::catalog::hang::Consumer<moq_mux::catalog::hang::Extra>,
mut catalog: hang::catalog::Consumer<moq_mux::catalog::hang::Extra>,
mut close: oneshot::Receiver<()>,
) -> Result<(), Error> {
loop {
// `biased` so a pending close always wins over a ready update: a hot
// stream must not be able to starve the close signal, and we must not
// deliver another update once close has been requested.
let update = tokio::select! {
let moq_json::Timed { value: update, at } = tokio::select! {
biased;
_ = &mut close => return Ok(()),
next = catalog.next() => match next? {
Expand Down Expand Up @@ -452,6 +457,7 @@ impl Consume {
broadcast: broadcast.clone(),
origin: origin.clone(),
catalog: update,
timestamp: at.into(),
audio_codec,
video_codec,
audio_ref,
Expand All @@ -465,6 +471,11 @@ impl Consume {
}
}

/// The media timestamp a catalog snapshot takes effect at.
pub fn catalog_timestamp(&self, catalog: Id) -> Result<moq_timestamp, Error> {
Ok(self.catalog.get(catalog).ok_or(Error::CatalogNotFound)?.timestamp)
}

pub fn video_config(&mut self, catalog: Id, index: usize, dst: &mut moq_video_config) -> Result<(), Error> {
let consume = self.catalog.get(catalog).ok_or(Error::CatalogNotFound)?;

Expand Down Expand Up @@ -1399,6 +1410,7 @@ mod supervision_tests {
driver: driver.clone(),
}),
catalog,
timestamp: moq_timestamp::default(),
audio_codec: Vec::new(),
video_codec: Vec::new(),
audio_ref: Vec::new(),
Expand Down Expand Up @@ -1435,6 +1447,7 @@ mod rendition_tests {
broadcast: broadcast.consume(),
origin: None,
catalog,
timestamp: moq_timestamp::default(),
audio_codec: Vec::new(),
video_codec: Vec::new(),
audio_ref: Vec::new(),
Expand Down Expand Up @@ -1583,6 +1596,7 @@ mod tests {
broadcast: broadcast.consume(),
origin: None,
catalog,
timestamp: moq_timestamp::default(),
audio_codec: Vec::new(),
video_codec: Vec::new(),
audio_ref: Vec::new(),
Expand Down
12 changes: 11 additions & 1 deletion rs/moq-c/src/error.rs
Original file line number Diff line number Diff line change
Expand Up @@ -313,7 +313,7 @@ pub enum Error {

/// Error from the hang media layer.
#[error("hang error: {0}")]
Hang(#[from] hang::Error),
Hang(hang::Error),

/// Error from the moq-mux consumer layer.
#[error("mux error: {0}")]
Expand Down Expand Up @@ -362,6 +362,16 @@ pub enum Error {
Unsupported(String),
}

// A lost track reports the transport code every other consumer does, not a hang failure.
impl From<hang::Error> for Error {
fn from(err: hang::Error) -> Self {
match err {
hang::Error::Moq(e) => Error::Moq(e),
e => Error::Hang(e),
}
}
}

impl From<moq_json::Error> for Error {
fn from(err: moq_json::Error) -> Self {
match err {
Expand Down
Loading