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
3 changes: 1 addition & 2 deletions quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
51 changes: 42 additions & 9 deletions quest/m2/cmaf-opus-surround.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,54 @@
# [S] Carry surround Opus through CMAF
# [M] Carry surround Opus through CMAF

## Goal

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<OpusChannelMapping>` (`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<OpusChannelMapping>` 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.
15 changes: 0 additions & 15 deletions quest/m2/mp4-atom-dops-mapping.md

This file was deleted.