From a2c17e7f29f29013e9fa3b4071b0852937a7e98c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 17 Oct 2026 21:25:13 -0700 Subject: [PATCH] quest(m2): fold mp4-atom dOps mapping into CMAF surround Opus The mp4-atom dOps change only pays off with surround Opus, so its breaking 0.17 release lands with that work in one moq PR. Co-Authored-By: Claude Opus 5.5 --- quest/m2/README.md | 3 +- quest/m2/cmaf-opus-surround.md | 51 +++++++++++++++++++++++++------ quest/m2/mp4-atom-dops-mapping.md | 15 --------- 3 files changed, 43 insertions(+), 26 deletions(-) delete mode 100644 quest/m2/mp4-atom-dops-mapping.md diff --git a/quest/m2/README.md b/quest/m2/README.md index c4b934a361d..3151893e01a 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -52,8 +52,7 @@ ranked just below deterministic TS legs, which it requires. - [CMake qlog option for OBS](/quest/m2/obs-qlog.md) - an OBS build can opt into qlog trace capture through moq-ffi's `qlog` feature - [AudioToolbox decode](/quest/m2/audio-decode-audiotoolbox.md) - macOS and iOS decode HE-AAC, multichannel AAC, and what else the framework offers - [AudioToolbox encode](/quest/m2/audio-encode-audiotoolbox.md) - macOS and iOS encode AAC-LC -- [mp4-atom dOps mapping](/quest/m2/mp4-atom-dops-mapping.md) - a released mp4-atom reads and writes any `dOps` channel mapping family and table -- [CMAF surround Opus](/quest/m2/cmaf-opus-surround.md) - fMP4 import and export carry an Opus channel mapping table +- [CMAF surround Opus](/quest/m2/cmaf-opus-surround.md) - a released mp4-atom carries the `dOps` channel mapping table, and fMP4 import and export carry it through the OpusHead - [GPU CI](/quest/m2/gpu-ci.md) - NVIDIA tests run nightly on real hardware, and `just rs nvidia` runs them locally instead of skipping - [Simulcast rung disable](/quest/m2/simulcast-rung-disable.md) - JS, Rust/FFI, and OBS publishers stop encoding the top renditions their grant cannot fund, advertise `enabled: false`, and re-enable with hysteresis - [Discover media headroom](/quest/m2/quic-probe.md) - test useful-media pacing before adding redundant probe traffic diff --git a/quest/m2/cmaf-opus-surround.md b/quest/m2/cmaf-opus-surround.md index 233e7c8f027..f7e264f6ba1 100644 --- a/quest/m2/cmaf-opus-surround.md +++ b/quest/m2/cmaf-opus-surround.md @@ -1,4 +1,4 @@ -# [S] Carry surround Opus through CMAF +# [M] Carry surround Opus through CMAF ## Goal @@ -6,16 +6,49 @@ An fMP4 Opus track whose `dOps` declares channel mapping family 1 imports with its mapping table in the OpusHead description, and a family 1 description exports to a `dOps` that keeps the table. Today both directions refuse it. +This needs a released `mp4-atom` whose `Dops` decodes and encodes any channel +mapping family as `channel_mapping: Option` (`None` is +family 0), the shape drafted in kixelated/mp4-atom#246. That is a breaking +`mp4-atom` 0.17. + ## Plan -Build the head from the `dOps` family and table with `opus::Mapping` on import, -and write the table from the parsed head on export in place of the -`UnsupportedMappingFamily` refusal in `synthesize_audio_trak`. Keep refusing -families the head cannot describe. +Decided 2026-10-17: the `mp4-atom` change is not worth landing on its own. +Alone it only swaps `mp4-atom`'s generic decode error for +`UnsupportedMappingFamily`; the payoff is surround Opus. So the former +`mp4-atom-dops-mapping` quest (draft moq-dev/moq#5819) folded in here, and +the breaking `mp4-atom` release lands only when this quest does. + +Order: land kixelated/mp4-atom#246, release `mp4-atom` 0.17, then one moq PR +that bumps `rs/moq-mux` to `mp4-atom = "0.17"` and does the import and export. +A git patch to the branch cannot stand in for the release, since `cargo deny` +refuses unknown git sources. + +Settled in #246 and #5819: + +- `Dops` decode and encode both check the table against the output channel + count and the RFC 7845 ยง5.1.1 stream rules, failing with + `Error::InvalidCombination`. Family 0 encodes byte-identically. +- `family` stays a raw `u8`; family-specific limits (family 1 allows at most 8 + channels) are the consumer's, which `opus::Mapping` already enforces. +- `mp4-atom` does not check that family 0 declares one or two channels; moq's + Opus config checks its own head, so that is left alone. + +Open for the implementing PR (maintainer's call, in #246): -Regression: a family 1 5.1 `dOps` round-trips through import and export with -its table intact. +1. `Dops` shape. Recommended: `Option` beside + `output_channel_count`. Alternatives: a flat `channel_mapping_family: u8` + plus an optional table, which mirrors the spec but allows family 0 with a + table; or an enum replacing `output_channel_count`, which drops the + redundant count but breaks every caller harder. +2. Table field name. Recommended: `channel_mapping`, mirroring the spec. + Alternative: `table`, which reads better at call sites. -## Required +In moq-mux, build the head from the `dOps` family and table with +`opus::Mapping` on import, where the importer today relies on `mp4-atom` +refusing a nonzero family. On export, write the table from the parsed head in +place of the `UnsupportedMappingFamily` refusal in `synthesize_audio_trak`. +Keep refusing families the head cannot describe. -- [mp4-atom dOps mapping](/quest/m2/mp4-atom-dops-mapping.md) - `Dops` carries the mapping family and table +Regression: a family 1 5.1 `dOps` built with `mp4-atom` round-trips through +import and export with its table intact. diff --git a/quest/m2/mp4-atom-dops-mapping.md b/quest/m2/mp4-atom-dops-mapping.md deleted file mode 100644 index 3d1f4d818de..00000000000 --- a/quest/m2/mp4-atom-dops-mapping.md +++ /dev/null @@ -1,15 +0,0 @@ -# [S] mp4-atom dOps channel mapping - -## Goal - -A released `mp4-atom` decodes and encodes a `dOps` box with any channel mapping -family, exposing the family and its table (stream count, coupled count, and the -per-channel mapping) instead of refusing a nonzero family. This repository -bumps to that release. - -## Plan - -The work lands in kixelated/mp4-atom. Validate the table against the output -channel count on decode rather than trusting it, and keep family 0 encoding -byte-identical. The bump here is a separate, small step once the release -ships.