From 643ebabe4a09df179ddbb69b2cf11ddd77b7f198 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 08:46:28 -0800 Subject: [PATCH 1/4] quest: plan one join interval for video and audio encoders Co-Authored-By: Claude Opus 5.5 --- quest/m1/api-audit/README.md | 1 + quest/m1/api-audit/join-interval.md | 61 +++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+) create mode 100644 quest/m1/api-audit/join-interval.md diff --git a/quest/m1/api-audit/README.md b/quest/m1/api-audit/README.md index ba3863d96f1..3250642e3e5 100644 --- a/quest/m1/api-audit/README.md +++ b/quest/m1/api-audit/README.md @@ -75,6 +75,7 @@ Rejected in planning: ## Required - [Routes are the origin API](/quest/m1/api-audit/route/README.md) - apps announce exact or prefix routes through one `Route` handle that owns its broadcast and carries an `instance`, prefix routes can serve a held broadcast, and readers get a listing plus `follow` +- [Encoders take a join interval](/quest/m1/api-audit/join-interval.md) - video's `keyframeInterval`/`Gop`, audio's `groupDuration`, and the C hints become one `joinInterval` time in JS, Rust, FFI, and C ## Related diff --git a/quest/m1/api-audit/join-interval.md b/quest/m1/api-audit/join-interval.md new file mode 100644 index 00000000000..88c166f806d --- /dev/null +++ b/quest/m1/api-audit/join-interval.md @@ -0,0 +1,61 @@ +# [M] Encoders take a join interval + +## Goal + +Every publisher-facing knob that spaces a track's join points is a time +called the join interval, named after the catalog's `media.join.interval` it +feeds, in every language and for both media: + +- `@moq/publish`: `Video.Encoder`'s `keyframeInterval` and `Audio.Encoder`'s + `groupDuration` (and `el.audio.groupDuration`) become `joinInterval`. +- `moq-video`: `encode::Config::gop: Gop` becomes + `join_interval: Duration` (default 2 s), and the `Gop` enum is deleted. +- `moq-audio`: `encode::Options::group_duration` becomes `join_interval`. +- `moq-ffi`: `MoqVideoGop` is deleted, and the video encoder output takes + `join_interval: Option`. +- `moq-c`: the video output's `gop` frame count becomes `join_interval_us` + (0 keeps the default), and the video and audio hints' `group_duration_us` / + `has_group_duration` become `join_interval_us` / `has_join_interval`. + +Defaults and behavior stay the same: video still forces an earlier keyframe +for a joiner, and audio still opens a group on the first frame at least the +interval past the last one. Every rename is a breaking change on `main` with a +MIGRATE note in each package. `release` keeps the old names. + +Non-goals: the catalog's own field, which is already `join.interval`, and +timestamp-driven video joins (the encoder still converts the interval to a +frame count at the configured framerate). + +## Plan + +Decided 2026-11-06 (maintainer, /quest-complete while queueing +[moq-dev/moq#7279](https://github.com/moq-dev/moq/pull/7279)): + +- ✅ **The name is "join interval"** (`joinInterval`, `join_interval`, + `join_interval_us`). Audio codecs have no keyframes and encoders have no + groups, but both knobs set how often a viewer can join, which the catalog + already calls the join interval. "join > keyframe." Not chosen: + `keyframeInterval` for audio too, `groupInterval`, a bare `interval`. +- ✅ **Scope covers video and the C hints**, not only the audio encoder + knobs. Not chosen: audio encoder knobs only; dropping the rename. +- ✅ **Rust video takes a plain `Duration`** (shape A). The encoder converts + it to frames internally, as `Gop::keyframe_every` does today, and + `Gop::duration` goes with the enum, since the catalog reads the interval + directly. Not chosen: a non-exhaustive `Join` enum to keep an extension + point; placing joins by frame timestamp (needs every backend to honor + forced IDRs and an open codec GOP); a `join_frames` count in Rust, FFI, + and C. +- ✅ Milestone m1, in this epic, since it makes names mirror across Rust, JS, + and the bindings. + +The video `Encoder::new` refuses a zero interval, as `Gop::validate` refuses +zero frames today; a positive interval shorter than one frame rounds up to one +frame, as `Gop::keyframe_every` does. Audio keeps zero meaning a group per +frame. + +Update `doc/lib/js/publish.md`, `doc/lib/c/index.md`, `doc/lib/rs/moq-audio.md`, +`rs/moq-video/README.md`, and every caller (`moq-cli`, `moq-transcode`, the +backends, the FFI and C wrappers and their language bindings). + +Public API: breaking in `@moq/publish`, `moq-video`, `moq-audio`, `moq-ffi` +and its bindings, and the `moq-c` ABI. Wire: none. From d69983d879b37c386ced92933f08ce1157ef21fd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 08:48:00 -0800 Subject: [PATCH 2/4] quest: name the knob join, not joinInterval Co-Authored-By: Claude Opus 5.5 --- quest/m1/api-audit/README.md | 2 +- quest/m1/api-audit/join-interval.md | 61 ---------------------------- quest/m1/api-audit/join.md | 63 +++++++++++++++++++++++++++++ 3 files changed, 64 insertions(+), 62 deletions(-) delete mode 100644 quest/m1/api-audit/join-interval.md create mode 100644 quest/m1/api-audit/join.md diff --git a/quest/m1/api-audit/README.md b/quest/m1/api-audit/README.md index 3250642e3e5..15877d379bb 100644 --- a/quest/m1/api-audit/README.md +++ b/quest/m1/api-audit/README.md @@ -75,7 +75,7 @@ Rejected in planning: ## Required - [Routes are the origin API](/quest/m1/api-audit/route/README.md) - apps announce exact or prefix routes through one `Route` handle that owns its broadcast and carries an `instance`, prefix routes can serve a held broadcast, and readers get a listing plus `follow` -- [Encoders take a join interval](/quest/m1/api-audit/join-interval.md) - video's `keyframeInterval`/`Gop`, audio's `groupDuration`, and the C hints become one `joinInterval` time in JS, Rust, FFI, and C +- [Encoders take a join](/quest/m1/api-audit/join.md) - video's `keyframeInterval`/`Gop`, audio's `groupDuration`, and the C hints become one `join` time in JS, Rust, FFI, and C ## Related diff --git a/quest/m1/api-audit/join-interval.md b/quest/m1/api-audit/join-interval.md deleted file mode 100644 index 88c166f806d..00000000000 --- a/quest/m1/api-audit/join-interval.md +++ /dev/null @@ -1,61 +0,0 @@ -# [M] Encoders take a join interval - -## Goal - -Every publisher-facing knob that spaces a track's join points is a time -called the join interval, named after the catalog's `media.join.interval` it -feeds, in every language and for both media: - -- `@moq/publish`: `Video.Encoder`'s `keyframeInterval` and `Audio.Encoder`'s - `groupDuration` (and `el.audio.groupDuration`) become `joinInterval`. -- `moq-video`: `encode::Config::gop: Gop` becomes - `join_interval: Duration` (default 2 s), and the `Gop` enum is deleted. -- `moq-audio`: `encode::Options::group_duration` becomes `join_interval`. -- `moq-ffi`: `MoqVideoGop` is deleted, and the video encoder output takes - `join_interval: Option`. -- `moq-c`: the video output's `gop` frame count becomes `join_interval_us` - (0 keeps the default), and the video and audio hints' `group_duration_us` / - `has_group_duration` become `join_interval_us` / `has_join_interval`. - -Defaults and behavior stay the same: video still forces an earlier keyframe -for a joiner, and audio still opens a group on the first frame at least the -interval past the last one. Every rename is a breaking change on `main` with a -MIGRATE note in each package. `release` keeps the old names. - -Non-goals: the catalog's own field, which is already `join.interval`, and -timestamp-driven video joins (the encoder still converts the interval to a -frame count at the configured framerate). - -## Plan - -Decided 2026-11-06 (maintainer, /quest-complete while queueing -[moq-dev/moq#7279](https://github.com/moq-dev/moq/pull/7279)): - -- ✅ **The name is "join interval"** (`joinInterval`, `join_interval`, - `join_interval_us`). Audio codecs have no keyframes and encoders have no - groups, but both knobs set how often a viewer can join, which the catalog - already calls the join interval. "join > keyframe." Not chosen: - `keyframeInterval` for audio too, `groupInterval`, a bare `interval`. -- ✅ **Scope covers video and the C hints**, not only the audio encoder - knobs. Not chosen: audio encoder knobs only; dropping the rename. -- ✅ **Rust video takes a plain `Duration`** (shape A). The encoder converts - it to frames internally, as `Gop::keyframe_every` does today, and - `Gop::duration` goes with the enum, since the catalog reads the interval - directly. Not chosen: a non-exhaustive `Join` enum to keep an extension - point; placing joins by frame timestamp (needs every backend to honor - forced IDRs and an open codec GOP); a `join_frames` count in Rust, FFI, - and C. -- ✅ Milestone m1, in this epic, since it makes names mirror across Rust, JS, - and the bindings. - -The video `Encoder::new` refuses a zero interval, as `Gop::validate` refuses -zero frames today; a positive interval shorter than one frame rounds up to one -frame, as `Gop::keyframe_every` does. Audio keeps zero meaning a group per -frame. - -Update `doc/lib/js/publish.md`, `doc/lib/c/index.md`, `doc/lib/rs/moq-audio.md`, -`rs/moq-video/README.md`, and every caller (`moq-cli`, `moq-transcode`, the -backends, the FFI and C wrappers and their language bindings). - -Public API: breaking in `@moq/publish`, `moq-video`, `moq-audio`, `moq-ffi` -and its bindings, and the `moq-c` ABI. Wire: none. diff --git a/quest/m1/api-audit/join.md b/quest/m1/api-audit/join.md new file mode 100644 index 00000000000..93cd339bdab --- /dev/null +++ b/quest/m1/api-audit/join.md @@ -0,0 +1,63 @@ +# [M] Encoders take a join + +## Goal + +Every publisher-facing knob that spaces a track's join points is a time +called `join`, after the catalog's `media.join` it feeds, in every language +and for both media: + +- `@moq/publish`: `Video.Encoder`'s `keyframeInterval` and `Audio.Encoder`'s + `groupDuration` (and `el.audio.groupDuration`) become `join`. +- `moq-video`: `encode::Config::gop: Gop` becomes `join: Duration` + (default 2 s), and the `Gop` enum is deleted. +- `moq-audio`: `encode::Options::group_duration` becomes `join`. +- `moq-ffi`: `MoqVideoGop` is deleted, and the video encoder output takes + `join: Option`. +- `moq-c`: the video output's `gop` frame count becomes `join_us` (0 keeps + the default), and the video and audio hints' `group_duration_us` / + `has_group_duration` become `join_us` / `has_join`. + +Defaults and behavior stay the same: video still forces an earlier keyframe +for a joiner, and audio still opens a group on the first frame at least +`join` past the last one. Every rename is a breaking change on `main` with a +MIGRATE note in each package. `release` keeps the old names. + +Non-goals: the catalog's own `media.join.interval` field, and +timestamp-driven video joins (the encoder still converts `join` to a frame +count at the configured framerate). + +## Plan + +Decided 2026-11-06 (maintainer, /quest-complete while queueing +[moq-dev/moq#7279](https://github.com/moq-dev/moq/pull/7279)): + +- ✅ **The name is `join`** (`join_us` in C). Audio codecs have no keyframes + and encoders have no groups, but both knobs set how often a viewer can + join, which the catalog already calls `media.join`. "join > keyframe." + The maintainer avoids compound words, and "Interval" reads like a unit. + Its doc comment must say it is the time between join points, since a bare + `join` can read like a method or a boolean. Not chosen: `joinInterval`, + `keyframeInterval` for audio too, `groupInterval`, `interval`, `cadence` + (collides with capture cadence), `period`. +- ✅ **Scope covers video and the C hints**, not only the audio encoder + knobs. Not chosen: audio encoder knobs only; dropping the rename. +- ✅ **Rust video takes a plain `Duration`** (shape A). The encoder converts + it to frames internally, as `Gop::keyframe_every` does today, and + `Gop::duration` goes with the enum, since the catalog reads `join` + directly. Not chosen: a non-exhaustive `Join` enum to keep an extension + point; placing joins by frame timestamp (needs every backend to honor + forced IDRs and an open codec GOP); a frame count in Rust, FFI, and C. +- ✅ Milestone m1, in this epic, since it makes names mirror across Rust, JS, + and the bindings. + +The video `Encoder::new` refuses a zero `join`, as `Gop::validate` refuses +zero frames today; a positive `join` shorter than one frame rounds up to one +frame, as `Gop::keyframe_every` does. Audio keeps zero meaning a group per +frame. + +Update `doc/lib/js/publish.md`, `doc/lib/c/index.md`, `doc/lib/rs/moq-audio.md`, +`rs/moq-video/README.md`, and every caller (`moq-cli`, `moq-transcode`, the +backends, the FFI and C wrappers and their language bindings). + +Public API: breaking in `@moq/publish`, `moq-video`, `moq-audio`, `moq-ffi` +and its bindings, and the `moq-c` ABI. Wire: none. From 899cd72ee235bc37a92f563576a1bcd9a6d267e6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 09:17:56 -0800 Subject: [PATCH 3/4] quest: one join at three levels, zero refused, catalog reads the effective join Co-Authored-By: Claude Opus 5.5 --- quest/m1/api-audit/join.md | 45 +++++++++++++++++++++++++++++++------- 1 file changed, 37 insertions(+), 8 deletions(-) diff --git a/quest/m1/api-audit/join.md b/quest/m1/api-audit/join.md index 93cd339bdab..ec99c99577e 100644 --- a/quest/m1/api-audit/join.md +++ b/quest/m1/api-audit/join.md @@ -7,7 +7,8 @@ called `join`, after the catalog's `media.join` it feeds, in every language and for both media: - `@moq/publish`: `Video.Encoder`'s `keyframeInterval` and `Audio.Encoder`'s - `groupDuration` (and `el.audio.groupDuration`) become `join`. + `groupDuration` (and `el.audio.groupDuration`) become `join`, and + `Rendition.joinInterval` becomes `Rendition.join`. - `moq-video`: `encode::Config::gop: Gop` becomes `join: Duration` (default 2 s), and the `Gop` enum is deleted. - `moq-audio`: `encode::Options::group_duration` becomes `join`. @@ -17,9 +18,14 @@ and for both media: the default), and the video and audio hints' `group_duration_us` / `has_group_duration` become `join_us` / `has_join`. -Defaults and behavior stay the same: video still forces an earlier keyframe -for a joiner, and audio still opens a group on the first frame at least -`join` past the last one. Every rename is a breaking change on `main` with a +`join` means the time between join points at every level of `@moq/publish`: +an encoder's config `join` is the requested value, `Rendition.join` is the +effective value the encoder holds to, and `Broadcast.join` stays the longest +across renditions, published as `media.join.interval`. + +Defaults stay the same: video still forces an earlier keyframe for a joiner, +and audio still opens a group on the first frame at least `join` past the +last one. Zero changes: every language refuses a `join` of zero (below). Every rename is a breaking change on `main` with a MIGRATE note in each package. `release` keeps the old names. Non-goals: the catalog's own `media.join.interval` field, and @@ -50,10 +56,33 @@ Decided 2026-11-06 (maintainer, /quest-complete while queueing - ✅ Milestone m1, in this epic, since it makes names mirror across Rust, JS, and the bindings. -The video `Encoder::new` refuses a zero `join`, as `Gop::validate` refuses -zero frames today; a positive `join` shorter than one frame rounds up to one -frame, as `Gop::keyframe_every` does. Audio keeps zero meaning a group per -frame. +Decided 2026-11-06 (maintainer, /quest-complete, on Pullfrog's review of +[moq-dev/moq#8036](https://github.com/moq-dev/moq/pull/8036)): + +- ✅ **One word at three levels**: `Rendition.joinInterval` becomes + `Rendition.join` too, so the requested, effective, and broadcast-wide + values share one name and meaning. Not chosen: keeping `joinInterval`; + a different name for the encoder knob. +- ✅ **Zero is refused everywhere.** Today JS video keyframes every frame at + `keyframeInterval: 0`, audio opens a group per frame at zero, and Rust video + and FFI already refuse it. Each encoder now rejects a zero `join` at + configuration, which changes behavior for JS and audio callers passing 0; + each package's MIGRATE note says so. C's zero-initialized video config + keeps 0 as "the default", since C has no `Option`; the C hints already + require a nonzero `join_us` when `has_join` is set. Not chosen: zero means + every frame everywhere; leaving each language's zero as is. + +A positive `join` shorter than one frame rounds up to one frame, as +`Gop::keyframe_every` does today. + +The catalog advertises the effective `join`, not the requested one, since +`media.join.interval` promises an upper bound and sets the HLS/DASH segment +grid. The video encoder keeps an internal effective duration after rounding +to frames (what `Gop::duration` supplies today): the default 2 s at +30000/1001 fps is 60 frames, or 2002 ms, and a 1 ms `join` at 30 fps is one +frame, about 33.3 ms. That effective value is what `Rendition.join` and the +Rust catalog read. Regression tests cover a fractional frame rate and a +positive sub-frame `join`. Update `doc/lib/js/publish.md`, `doc/lib/c/index.md`, `doc/lib/rs/moq-audio.md`, `rs/moq-video/README.md`, and every caller (`moq-cli`, `moq-transcode`, the From bec62bba04f6e33c9bd808b31f46fc709becedeb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Fri, 6 Nov 2026 10:15:21 -0800 Subject: [PATCH 4/4] quest: migration notes go in the PR's Impact section, per AGENTS.md Co-Authored-By: Claude Opus 5.5 --- quest/m1/api-audit/join.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/quest/m1/api-audit/join.md b/quest/m1/api-audit/join.md index ec99c99577e..ea5d00439fc 100644 --- a/quest/m1/api-audit/join.md +++ b/quest/m1/api-audit/join.md @@ -25,8 +25,9 @@ across renditions, published as `media.join.interval`. Defaults stay the same: video still forces an earlier keyframe for a joiner, and audio still opens a group on the first frame at least `join` past the -last one. Zero changes: every language refuses a `join` of zero (below). Every rename is a breaking change on `main` with a -MIGRATE note in each package. `release` keeps the old names. +last one. Zero changes: every language refuses a `join` of zero (below). +Every rename is a breaking change on `main`, with a migration note per +package in the PR's Impact section. `release` keeps the old names. Non-goals: the catalog's own `media.join.interval` field, and timestamp-driven video joins (the encoder still converts `join` to a frame @@ -67,7 +68,7 @@ Decided 2026-11-06 (maintainer, /quest-complete, on Pullfrog's review of `keyframeInterval: 0`, audio opens a group per frame at zero, and Rust video and FFI already refuse it. Each encoder now rejects a zero `join` at configuration, which changes behavior for JS and audio callers passing 0; - each package's MIGRATE note says so. C's zero-initialized video config + the PR's Impact section says so. C's zero-initialized video config keeps 0 as "the default", since C has no `Option`; the C hints already require a nonzero `join_us` when `has_join` is set. Not chosen: zero means every frame everywhere; leaving each language's zero as is.