libfreemkv/docs/mp4-audio.md

MP4 audio sample entries (src/mux/mp4/audio.rs)

Module scope

The entry always describes the syntax actually found in the first audio frame, not the codec the playlist claimed: a track the playlist calls DD+ whose first syncframe is a legacy AC-3 one is declared ac-3/dac3. The fit oracle (audio_fits) in this module, mirrored by the sink, is what decides which codecs are muxable at all.

EAC3_MIN_BSID

Lowest bsid that identifies an Annex-E (E-AC-3) bitstream: ETSI TS 102 366 Annex E uses bsid 16, while 8 is AC-3 and 9/10 are the AC-3 alternate bit stream syntax of Annex D. Both the parser and the sample-entry chooser read this one constant so they cannot disagree about which syntax was found.

BitReader::read

The accumulate step ((v << 1) | bit) is one instance of a pattern repeated throughout this file — shift an accumulator left by exactly the width of the next field, then OR in that field, mask-limited to the same width (the push closures in dac3_box, dec3_box and ddts_box; the multi-byte bit-field extractions in parse_eac3 and parse_dts). Because the shift always vacates precisely the bits the OR then fills, and never more, the two operands never share a set bit — so | and ^ agree on every input, always. Mutation testing flags each of these | sites as a surviving |→^ mutant; that is expected and is not a coverage gap. Don't write tests chasing it and don't "fix" it by switching to ^ — either spelling is correct and equally unenforceable by a test, so | stays because it is the conventional way to write "set these bits" in a bitstream packer.

dec3_box

data_rate states the bitstream's rate in kbit/s and must be non-zero; only parse_eac3 computes one, so this box is written only for a config that came from an Annex-E syncframe (see dolby_sample_entry).

DTS_AMODE_CH

DTS core base channel count per AMODE (all 16 defined values). Matches the per-AMODE channel counts in ETSI TS 102 114 §5.3.1, the same table the decodability gate in dts.rs (DTS_AMODE_COUNT) also uses, so a spec-legal DTS-ES / 6.1 / 7.1 core (AMODE 13→7, 14/15→8) is declared with its true channel count in the mp4 AudioSampleEntry / ddts box rather than a truncated 6.

DTS_AMODE_LAYOUT

ddts ChannelLayout speaker mask (ETSI TS 102 114 / DTS-in-ISOBMFF) per core AMODE. Bit assignment: 0=C, 1=L/R, 2=Ls/Rs, 3=LFE, 4=Cs, 5=Lh/Rh, 6=Lsr/Rsr, 7=Ch, 8=Oh, 9=Lc/Rc, 10=Lw/Rw, 11=Lss/Rss, 12=LFE2, 13=Lhs/Rhs, 14=Chr, 15=Lhr/Rhr. Paired bits denote two speakers, single bits one.

This must stay consistent with DTS_AMODE_CH: the ddts box declares both a channel count and this mask, and a decoder may trust either — so a mask that describes fewer speakers than the declared count makes the box self-contradictory and provokes a downmix or an outright error. The previous _ => 0x0007 catch-all did exactly that for AMODE 6, 7, and 10 through 15. AMODE 6 (L + R + S) is the reachable one: its S is a single centre-surround, not the Ls/Rs pair, so it is 3 channels and 0x0012, not 4 and 0x0006. ddts_channel_layout_speaker_count_matches_declared_channels pins the invariant for all 16 values.

The AMODE annotations on the table name the layout ETSI TS 102 114 §5.3.1 gives for that AMODE and the mask that encodes it. Three of them used to be rotated by one (AMODE 2 labelled "sum/difference", 3 "left/right total", 4 plain "L/R") and AMODE 9 was labelled "5.1 core with LFE" although 0x0007 is the 5.0 mask — LFE is bit 3, OR'd in separately by dts_channel_layout. Both mislabels invited a "correction" to the values, which are right and are pinned by ddts_channel_layout_speaker_count_matches_declared_channels.

dts_channel_layout

amode must be 0..=15; parse_dts rejects the reserved 16..=63 before this is reached, so there is no layout to invent for them.

audio_fits

Fit oracle for an audio codec: does mp4:// currently carry it? Covers the Dolby family (AC-3 / E-AC-3) and DTS (core / DTS-HD HRA / DTS-HD MA — the core is described, whole access units pass through). TrueHD, LPCM, AAC are not yet mapped and are skipped with a loud report (never silently dropped).

Test fixtures

ac3_frame_distinct (line ~905 in the test module): AC-3 syncframe with every BSI field distinct: fscod=1 (44.1 kHz), frmsizecod=37 (bit_rate_code 18), bsid=8, bsmod=5, acmod=6 (2/2), lfeon=1 → 4.1 = 5 channels. byte4 = fscod(2)=01 | frmsizecod(6)=100101 → 0x65; byte5 = bsid(5)=01000 | bsmod(3)=101 → 0x45; byte6 = acmod(3)=110 | surmixlev(2)=00 | lfeon=1 | pad 00 → 0xC4. acmod 6 has surround but no centre, so per §5.4.2 cmixlev is absent and surmixlev is present: lfeon lands at bit 5 of byte 6.

eac3_frame_distinct: Annex-E syncframe with every field distinct: frmsiz=0x123 (292 words → 584 bytes), fscod=1 (44.1 kHz), numblkscod=0 (1 block → 256 samples), acmod=5 (3/1), lfeon=1 → 5 channels, bsid=16. byte2 = strmtyp 00 | substreamid 000 | frmsiz hi 001 → 0x01; byte3 = frmsiz lo 0x23; byte4 = fscod 01 | numblkscod 00 | acmod 101 | lfeon 1 → 0x4B; byte5 = bsid 10000 | dialnorm hi 000 → 0x80.

eac3_frame_fscod3: Annex-E syncframe with fscod=3 — the reduced-sample-rate path, which no other fixture reaches. fscod2=2 → 16 kHz, 6 blocks; acmod=2, lfeon=0. byte4 = fscod 11 | fscod2 10 | acmod 010 | lfeon 0 = 0xE4. Exactly 6 bytes: also the minimum-length Annex-E header.

dts_frame_high_bits_set: a DTS core whose split fields all have their high parts set, so a lost high bit is visible: NBLKS bit 6 (byte 4 bit 0) and FSIZE bits 13-12 (byte 5 bits 1-0). NBLKS=79 → 2560 samples; FSIZE=0x3000 → core 12289. AMODE=9, SFREQ=13 (48 kHz), LFF=1 out of byte 10 = 0x0A.