Skip to content

dOps: decode and encode any channel mapping family - #246

Merged
kixelated merged 1 commit into
mainfrom
dops-channel-mapping
Oct 28, 2026
Merged

kixelated merged 1 commit into
mainfrom
dops-channel-mapping

Conversation

@kixelated

@kixelated kixelated commented Oct 17, 2026 •

Copy link
Copy Markdown
Owner

Dops refused any nonzero channel mapping family on decode and always wrote family 0, so surround Opus (family 1, ambisonics 2/3, unpositioned 255) could not pass through.

Changes

  • Dops gains channel_mapping: Option<OpusChannelMapping>; None is family 0 (no table).
  • New OpusChannelMapping { family, stream_count, coupled_count, channel_mapping: Vec<u8> }.
  • Decode and encode both check the table instead of trusting it: nonzero family, nonzero output channel count, one entry per output channel, at least one stream, coupled count at most the stream count, at most 255 decoded channels, and every entry either 255 (silence) or a decoded channel. Failures are Error::InvalidCombination.
  • Family 0 encoding is unchanged byte for byte (tested).
  • Family-specific limits (for example family 1 allowing at most 8 channels) are left to the consumer, since family stays a raw u8.

Public API

Breaking: a new public field on Dops, plus the new exported OpusChannelMapping. Serde input without the field still deserializes, as None.

Why

moq needs it for two things. One is surround Opus over CMAF: an fMP4 Opus track with a family 1 dOps should import with its mapping table, and a family 1 track should export to a dOps that keeps it. Today both directions refuse it. The other is ambisonic fMP4 (family 2), which needs the table to tell first-order ambisonics apart from the non-diegetic stereo variants.

The change is breaking, so it ships in the 0.17.0 release alongside kixelated/mp4-atom#254. That way downstream takes one breaking bump instead of two.

Shape

  • Option<OpusChannelMapping> sits beside output_channel_count. A flat family: u8 plus an optional table would allow family 0 with a table. An enum replacing output_channel_count would break every caller harder.
  • OpusChannelMapping avoids a generic ChannelMapping at the crate root, next to chnl. The table field mirrors the spec's ChannelMapping. Rename it to table if you prefer how dops.channel_mapping.table reads at call sites.

(Written by Claude Opus 5.5)

🤖 Generated with Claude Code

Dops now carries the family and its table (stream count, coupled count, and per-channel mapping) as channel_mapping, None for family 0, instead of refusing a nonzero family. The table is checked against the output channel count and the RFC 7845 5.1.1 stream rules on both decode and encode. Family 0 encodes byte-identically.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
kixelated added a commit to moq-dev/moq that referenced this pull request Oct 17, 2026
mp4-atom now decodes any dOps channel mapping family (kixelated/mp4-atom#246), so the Opus importer can no longer rely on it refusing a table. Refuse one explicitly until surround import lands, and point the workspace at the mp4-atom branch until it releases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bradh

bradh commented Oct 17, 2026

Copy link
Copy Markdown
Collaborator

Still in draft. What is the plan?

@kixelated

Copy link
Copy Markdown
Owner Author

Still in draft. What is the plan?

Step 1, figure out why AI wanted this change.

@kixelated

Copy link
Copy Markdown
Owner Author

@bradh The plan is to ship this in 0.17.0 next to kixelated/mp4-atom#254, so downstream takes a single breaking bump.

moq needs it so fMP4 Opus with channel mapping family 1 (surround) or family 2 (ambisonics) can pass through CMAF import and export. Today Dops fails to decode those, and it can only encode family 0. Decode and encode both validate the table against RFC 7845 §5.1.1, and family 0 still encodes byte-for-byte as before. It's ready for review now. I've updated the description with the reasoning and the shape alternatives.

(Written by Claude Opus 5.5)

@coderabbitai

coderabbitai Bot commented Oct 28, 2026

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 59 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 8ea49ffe-81fa-4104-a907-109dbc45ad45
Commits

Reviewing files that changed from the base of the PR and between 748db4a and 6cb4683.

Files selected for processing: 1
  • src/moov/trak/mdia/minf/stbl/stsd/opus.rs
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review 🔄 Running since 2026-10-28T19:23:06.078335Z 6cb4683 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@kixelated
kixelated merged commit 3e150f9 into main Oct 28, 2026
2 checks passed
@kixelated
kixelated deleted the dops-channel-mapping branch October 28, 2026 19:28
@github-actions github-actions Bot mentioned this pull request Oct 28, 2026
@kixelated

Copy link
Copy Markdown
Owner Author

@bradh I reviewed it, lemme know if you disagree with anything.

AdrianEddy added a commit to AdrianEddy/mp4-atom that referenced this pull request Nov 9, 2026
…of every family, family 3's demixing matrix whole, and refuses a table that breaks RFC 7845's rules.

Dops gains channel_mapping: Option<OpusChannelMapping>, upstream's shape (kixelated#246). In family 3 the table is RFC 8486's 2 x (N + M) x C octet matrix, read whole where upstream reads C octets. Decode checks the counts before it reads the table, so a matrix cut to one octet per channel, as libavformat's MP4 muxer writes it, is refused by name.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants