libfreemkv/docs/mkv-mux.md

# MKV muxer internals (`src/mux/mkv.rs`)

Overflow rationale relocated here by `ci/comment-guard.py` (long-form prose
that would otherwise exceed the internal-comment cap). Each section is
pointed to from the corresponding `//` comment in the source.

## Blu-ray 3D MVC BlockAddition mapping

`BLOCK_ADD_ID_TYPE_MVCC` is the `mvcC` BlockAddIDType — the
`MVCDecoderConfigurationRecord` fourcc, big-endian ASCII `'m''v''c''C'`.
Matroska BlockAdditionMapping/BlockAddIDType for a Blu-ray 3D MVC
configuration (RFC 9559 + Matroska Codec Specifications §4.1.5; equals
ISO/IEC 14496-15 `MVCConfigurationBox('mvcC')`). The per-frame dependent
(right-eye) view rides as a BlockAdditional under this mapping.

## MVC decoder config record layout

`mvc_decoder_config_record` builds an `MVCDecoderConfigurationRecord`
(ISO/IEC 14496-15:2013 §7.6.2) from the dependent view's subset-SPS (NAL
type 15) and PPS NAL units. This is the `BlockAddIDExtraData` for the
`mvcC` BlockAdditionMapping (and, in the ISO container, the
`MVCConfigurationBox('mvcC')` payload).

Layout mirrors the AVCDecoderConfigurationRecord except `byte[4]`
repurposes the AVC record's `bit(6) reserved` as
`complete_representation(1) | explicit_au_track(1) | reserved '1111'(4)`.
`profile`/`compat`/`level` describe the WHOLE MVC stream and come from the
subset SPS (bytes 1..=3). `length_size_minus_one` MUST match the base avcC
(freemkv always emits 4-byte length prefixes → 3). SPSs precede subset SPSs
in the array; here the array carries the dependent view's parameter sets.

Returns `None` if either param set is absent, too short, or exceeds the
16-bit length field (a param set > 65535 bytes is non-conforming and would
mis-frame the record).

## MVC CodecPrivate layout

`mvc_codec_private` builds the `CodecPrivate` for an MVC (Blu-ray 3D) base
track: the base view's `AVCDecoderConfigurationRecord` (`avcc`) followed by
an `mvcC` extension block, per the Matroska Codec Specifications §4.3.9:

```text
avcC ‖ u32be(extension_block_size − 4) ‖ "mvcC" ‖ MVCDecoderConfigurationRecord
```

The size field is the extension block length **excluding the 4-byte size
field itself** — i.e. `4 ("mvcC") + record.len()`. This is the track-level
MVC signal that decoders and media analyzers read (the per-frame
`BlockAdditional` under the `mvcC` BlockAdditionMapping carries the
dependent view's data). A plain (2D) track never calls this — it writes its
`avcc` verbatim.

## CICP colour resolution precedence

`cicp_for_video` resolves a video stream's CICP colour code points —
`(matrix, transfer, primaries, range)`, ITU-T H.273 — using a single
precedence so EVERY sink (the MKV muxer here AND the FVI sidecar in
`videomap.rs`) agrees and can never drift:

1. **Measured CICP** read from the bitstream (HEVC/H.264 VUI
   `colour_description` or MPEG-2 `sequence_display_extension`) is
   AUTHORITATIVE — copied through verbatim when present.
2. Otherwise fall back to the coarse `color_space` enum (a playlist nibble /
   PAL-NTSC guess), THEN apply the HDR-driven transfer override: BT.2020
   only appears on HDR UHD, where the real transfer is PQ (16) for
   HDR10/HDR10+/DV or HLG (18) for HLG — never the SDR transfer 14 the enum
   alone would emit.

## HDR10 unit conversions and SEI primary order

`write_hdr10` emits the HDR10 static-metadata children of the Matroska
`Colour` element: `MasteringMetadata` (chromaticity / luminance floats)
plus `MaxCLL` / `MaxFALL` (uints). Called ONLY when the metadata was
measured from the bitstream SEI, so it is never written for SDR content.

Unit conversions (Rec. ITU-T H.265 D.3.28 → RFC 9559 / Matroska):
- chromaticity: SEI integer × 0.00002 → Matroska float in [0, 1]
- luminance:    SEI integer × 0.0001  → Matroska float in cd/m²
- MaxCLL / MaxFALL: already cd/m² integers → written as uints verbatim

The SEI primary order is c=0 Green, c=1 Blue, c=2 Red (D.3.28); the
`Hdr10Metadata` arrays preserve that SEI order, so index 0 → G, 1 → B,
2 → R is mapped onto the Matroska R/G/B element layout here.

## Language element default rationale

`language_or_und` is the Matroska `Language` element the muxer writes for
a stream whose source reported `lang`. RFC 9559 §12 defines the element as
an ISO 639-2 code and gives no meaning to an empty one; the code for "no
language stated" is `und`, and that is what a source with no language
table (the HD-DVD EVO stream probe, a Blu-ray STN slot with no language
bytes) has to emit. The element is written unconditionally by
`MkvMuxer::new`, so this is the one place that decides it — a source-side
default would have to be repeated in every scanner and would still leave
the muxer able to ship an invalid file.

## Why BlockGroup buffering avoids per-frame seeks

`MkvMuxer::block_group_buf` is a reusable scratch buffer for assembling
ONE BlockGroup before it is written with a single `write_all`.

The BlockGroup path is the hot one — the MPEG-2 parser stamps a per-frame
duration, so every I/P/B frame lands there, plus AC-3 audio and PGS
subtitles (~350k BlockGroups for a 90-minute feature). Building the
element in memory means its size is known before it reaches the file, so
no `start_master`/`end_master` back-patch is needed: that removes the
per-frame `stream_position()` + two `seek()`s, each of which flushed the
4 MiB `BufWriter` (`BufWriter` does not override `stream_position`, so a
position query is `seek(Current(0))` = flush + lseek) and reset the
writeback pipeline's `last_flush_pos`. Kept on the muxer so the allocation
is made once, not per frame.

## dropped_pre_cluster logging rationale

`MkvMuxer::dropped_pre_cluster` counts frames handed to `write_frame` that
were dropped because no cluster was open yet (a cluster only opens on a
keyframe from the primary video track, whatever index that is — not
necessarily track 0). See `write_frame` for the cluster-driver invariant.

The ALL-dropped case is surfaced as an error by `finish()`, but via
`frame_count == 0`, not via this counter. A PARTIAL drop — leading audio /
subtitle frames ahead of the first video IDR, or an M2TS whose PMT lists
audio before video — is normal enough not to fail the mux, but it used to
leave NO record anywhere: the field was incremented at two sites and read
nowhere (no log, no error, no accessor), so those frames vanished from the
output with `completed = true`, an empty `undelivered_streams`, and
nothing in the log. `finish()` now logs the count — that log is the
field's only reader, so do not delete it and turn this back into dead
bookkeeping.

## TimestampScale choice

`TIMESTAMP_SCALE_NS`: nanoseconds per Matroska timestamp tick, 0.1 ms
(100_000 ns).

The classic 1 ms scale truncates two distinct cadences onto the same tick:
- 23.976 fps video frames are ~41.7 ms apart, but with B-frame reorder two
  neighbouring frames can round to the same whole millisecond — a decoder
  then derives colliding DTS ("non monotonically increasing dts").
- TrueHD audio access units are 0.833 ms (1/1200 s); at 1 ms granularity
  every AU truncates to a 1 ms grid and the per-track monotonic nudge has
  to space them at a fabricated 1 ms instead of their true 0.833 ms.

0.1 ms resolves both: 41.7 ms and 0.833 ms each map to distinct ticks, so
frames stop colliding and audio keeps its real cadence. Player/parser
support for sub-millisecond TimestampScale is universal (it is the spec
default mechanism). The cost is a smaller per-cluster i16 span (see
`MAX_BLOCK_REL`), handled by splitting clusters and emitting a Cue for the
split (see `write_frame`).

## cluster duration vs. i16 block-relative limit

`CLUSTER_DURATION_TICKS`: nominal new-cluster interval (2 s) expressed in
TimestampScale ticks.

A keyframe only OPENS a new cluster once this much has elapsed since the
open cluster's timestamp, so the actual cluster span runs from this value
up to roughly this value plus one GOP (the next keyframe lands a GOP
later). With a typical ≤ 1 s GOP that worst-case span (~3 s ≈ 30_000
ticks) stays UNDER the i16 block-relative limit (`MAX_BLOCK_REL` = 32_767
ticks ≈ 3.27 s at the 0.1 ms scale), so video keyframes drive Cue-aligned
cluster boundaries and the i16-overflow split path stays a rare fallback
(long audio-only stretches or pathological multi-second GOPs) rather than
the common case. The classic 5 s window would, at this scale, force an
unaligned i16 split inside every cluster.

## MAX_BLOCK_REL / MIN_BLOCK_REL rationale

`MAX_BLOCK_REL` is the maximum block-relative timestamp expressible in the
signed 16-bit SimpleBlock/Block field (`i16::MAX` ticks). A frame whose
offset from the open cluster's timestamp falls outside
`i16::MIN..=i16::MAX` ticks forces a new cluster (see `write_frame`) so
the `as i16` cast can never wrap — in EITHER direction. PES timestamps
come from untrusted disc/file bytes and can back-jump on discontinuities,
so the lower bound matters as much as the upper one. At a 0.1 ms scale
i16::MAX is ~3.27 s, well under the 5 s cluster window, so a long-GOP /
audio-only stretch can hit this bound before the keyframe boundary — the
split path must (and does) push a Cue. `MIN_BLOCK_REL` is the
corresponding lower bound (`i16::MIN`).

## monotonic_ts non-monotonic DTS rationale

`monotonic_ts` forces a per-track block timestamp (in TimestampScale
ticks) to be strictly later than the previous one written for that track.
`prev` is the last timestamp for the track (`None` for the first frame).
Fixes non-monotonic DTS: some audio PES PTS truncate to the same tick as
the prior frame (or tick back one from rounding), which strict
players/decoders reject. At the 0.1 ms scale a TrueHD AU (0.833 ms = ~8
ticks) no longer collides with its neighbour, so this rarely fires for
lossless audio — but a +1-tick nudge (0.1 ms, sub-AU and inaudible) still
guards genuine same-tick collisions on any no-reorder track. Never moves a
timestamp earlier.

## block_ts rationale

`block_ts` computes the per-track block timestamp. The strictly-monotonic
nudge is applied to AUDIO/SUBTITLE tracks only; ALL VIDEO tracks are
returned UNCHANGED.

With B-frames, a video frame's presentation PTS is legitimately
non-monotonic in decode/storage order (a B-frame sits between its
anchors, below the frame stored just before it). Forcing it
strictly-increasing clobbers those PTS to prev+1ms — a `copy` remux
preserves the (wrong) value, but a decoder derives DTS from the HEVC POC
and finds them colliding ("non monotonically increasing dts", thousands
per title). Matroska SimpleBlock permits non-monotonic block timestamps
(signed block-relative offsets), so video keeps its true PES PTS; only
no-reorder tracks (audio, subtitles), where a same-millisecond collision
IS a real defect, get nudged.

The exemption is keyed on `is_video` (track type), NOT a track index: a
title can carry more than one video track — e.g. a Dolby Vision
enhancement layer at index 1 — and every one must keep its true PTS.
Keying on `track_idx == 0` clamped the EL and reintroduced the exact
non-monotonic-DTS warning this exemption exists to prevent.

## track_vint widths

`track_vint` encodes a Matroska track number as an EBML VINT into a stack
buffer, returning the buffer and the used length. Track numbers are small
(1-based, a handful of tracks), so 1 byte covers `< 0x80`, 2 bytes covers
`< 0x4000`, and 3 bytes covers `< 0x20_0000`; no heap allocation, called
once per block on the mux hot path.

Each width uses a marker bit that must NOT collide with the payload's top
byte: the 1-byte marker is 0x80 (7 payload bits), the 2-byte marker 0x40
(14 payload bits), the 3-byte marker 0x20 (21 payload bits). Handling all
three in RELEASE (not just `debug_assert`) means an out-of-2-byte-range
track number can never silently clobber the marker bit and corrupt the
block. Real discs never approach even the 2-byte range; the 21-bit
ceiling is an absurd upper bound kept as a `debug_assert`.

## codecPrivate path history

Pre-0.13 had a deferred codecPrivate path (placeholder + seek-back fill)
for video, but the PES pipeline hands it up-front via `DiscTitle`, so that
path was never exercised — removed in the 0.13 dead-code sweep.

## set_clips seam-correction rationale

`MkvMuxer::set_clips` drives seam correction from the title's PlayItem
marks instead of inferring it from PTS jumps.

A multi-clip Blu-ray playlist joins its clips with overlaps and skips
that PTS inspection cannot recover: a forward jump is indistinguishable
from frames lost to damaged media, and an overlap smaller than the
reorder threshold is invisible. Given the marks, each clip is placed at
the sum of the earlier clips' durations, so the output runs exactly as
long as the playlist says the title is.

No-op for a title with fewer than two clips or without usable marks —
DVD, HD-DVD and file sources keep the inference path.

## write_frame_at seam/MVC BlockAdditional rationale

`write_frame_at` is `write_frame` (test-only convenience wrapper) with
the frame's SOURCE BYTE OFFSET.

Under a seam plan that offset identifies which clip the frame came from
by lookup rather than by inferring it from the timestamp — which is
ambiguous inside an overlap, where two clips' mark ranges both contain
the same instant. Callers that have a `PesFrame` should pass
`frame.source.map(|s| s.byte)`; `write_frame` is the same call with no
provenance, which falls back to the mark heuristics.

`block_additional`, when `Some`, is attached to the frame as a Matroska
`BlockAdditional` (BlockAddID=2) — Blu-ray 3D (MVC): the base view is the
Block and the dependent (right-eye) access unit rides as the
BlockAdditional under the track's `mvcC` mapping. Such a frame is always
a `BlockGroup` (never a SimpleBlock), with a `ReferenceBlock` when it is
not a keyframe. `None` for every non-3D frame.

## finish() cluster-driver invariant

`MkvMuxer::finish` finishes the MKV file: writes the Cues element.

A cluster only opens on a keyframe from the PRIMARY VIDEO TRACK — the
first track whose type is video, at whatever index it occupies (see
`cluster_driver`, which is `primary_video_track.unwrap_or(0)`; index 0 is
only the fallback for a file with no video track at all). The caller must
deliver a keyframe on that track before (or alongside) other-track data.
This said "track-0" and required the caller to place video at index 0,
which the code has never actually required — so a reader debugging
dropped frames would suspect track ordering, which is not it. If no such
keyframe ever arrives, every `write_frame` is silently dropped; rather
than emit a structurally valid but empty MKV (zero clusters, zero
frames), `finish` returns `Error::MkvInvalid` when frames were submitted
but none were written.

## write_block_group ReferenceBlock/keyframe-bit

`write_block_group` writes a BlockGroup (Block + BlockDuration, plus a
ReferenceBlock when the frame is not a keyframe).

`reference` is `Some(offset_ticks)` for a non-keyframe and `None` for a
keyframe. Inside a BlockGroup the SimpleBlock `0x80` keyframe bit is
reserved and MUST be 0, so a non-keyframe that omits ReferenceBlock is
indistinguishable from an intra frame. This path is NOT subtitle-only:
the MPEG-2 parser stamps a per-frame duration, so every MPEG-2 video
frame (I, P and B) arrives here.

## write_block_group_mvc reference/duration

`write_block_group_mvc` writes a BlockGroup carrying the base view Block
plus the MVC dependent (right-eye) access unit as a `BlockAdditional`
(BlockAddID=2), per the track's `mvcC` BlockAdditionMapping. A
non-keyframe frame gets a `ReferenceBlock` (`reference` = referenced
keyframe offset in ticks) so it is not mistaken for a seek point;
`BlockDuration` is written when known.

## removed parse_resolution/parse_sample_rate/parse_channels history

Old `parse_resolution`/`parse_sample_rate`/`parse_channels` helpers were
removed — `Resolution::pixels()`, `SampleRate::hz()`,
`AudioChannels::count()` replace them.

## keyframe_survives_roundtrip regression history

`keyframe_survives_roundtrip_for_duration_bearing_frames` asserts keyframe
flags survive a write→read round-trip for frames that carry a per-frame
DURATION, i.e. the BlockGroup path.

Regression: every MPEG-2 frame carries a duration (the parser stamps one
on I, P and B alike), so ALL MPEG-2 video is written as BlockGroup, not
SimpleBlock. Inside a BlockGroup the SimpleBlock `0x80` keyframe bit is
reserved and the writer emits 0 — keyframe-ness lives ONLY in the
presence/absence of a ReferenceBlock. Two halves were broken:
  - the writer discarded `keyframe` on this path (no ReferenceBlock ever),
    so a shipped DVD rip marked every P/B frame as a seek point;
  - the reader ignored ReferenceBlock and read the always-0 reserved bit,
    so EVERY BlockGroup frame read back as a non-keyframe.

Downstream that silently dropped all video on `mkv://`(MPEG-2)→`m2ts://`
(TsMuxer drops non-key video until the first keyframe) and made
`mkv://`→`mkv://` / `stdio://` fail E6008 (MkvMuxer opens a cluster only
on a track-0 video keyframe → zero frames written).

A SimpleBlock case (duration `None`) is asserted alongside so a fix that
regresses the non-duration path is caught too.

## mkvstream preroll test

`mkvstream_preserves_video_keyframe_after_audio_preroll` runs end-to-end
through the REAL `MkvStream::create`/`write`/`finish` path (deferred
Pending→activate buffering), in the shape the DVD pipeline actually
produces: several AC-3 audio frames arrive BEFORE the first video frame
(audio emits per-PES immediately, while MPEG-2 holds its first GOP), and
the video frame carries a per-frame DURATION so it is written as a
BlockGroup.

Guards the same regression as
`keyframe_survives_roundtrip_for_duration_bearing_frames`, but across the
buffering machinery rather than the bare muxer — the video keyframe must
still be a keyframe after being buffered and replayed on activation.

## frames_dropped_before_first_cluster_are_counted rationale

Frames dropped before the first cluster opens must be COUNTED, and the
count must survive to `finish()` so it can be reported. The counter was
incremented at two sites and read nowhere — no log, no error, no
accessor — so a partial drop (leading audio/subtitle frames ahead of the
first video IDR, or an M2TS whose PMT lists audio before video) silently
omitted those frames from the output while the run reported
`completed = true` with an empty `undelivered_streams` and nothing in
the log. `finish()` now logs it; this pins the accounting the log
depends on.

## zero_cues_voids_seekhead_entry rationale

When no Cues element is written (zero cue points), the SeekHead must NOT
retain a CUES entry that back-patches to the Cues offset — that offset
now holds Tags / EOF, a dangling pointer to a non-Cues element. finish()
Voids the unused CUES Seek entry instead. (The empty-cues case is
defensive — the normal path pushes a cue with every cluster — so the
test clears the cue list directly before finalizing.)

## second_video_track_pts_not_clobbered rationale

Regression for the second-video-track bug: a Dolby Vision enhancement
layer is video but NOT track 0. The exemption must follow track TYPE, so
the EL's B-frame PTS are preserved exactly like the main video's — not
clamped to prev+1ms (which reintroduced the non-monotonic-DTS flood on
the EL stream). Drives the muxer through both video tracks and asserts
every video block timecode equals its source PTS.

## clip_boundary_with_straggler test rationale

End-to-end output regression (the symptom, at the block-timecode level):
a large clip-boundary reset WITH an interleaved straggler audio frame
from clip 1's tail, driven through the full muxer. Asserts cluster
timestamps are monotonic non-decreasing AND the timeline reaches past
the boundary (clip 2 present) without ratcheting. This is the test that
would have caught BOTH the original `-820000` non-monotonic band and the
straggler ratchet that made everything after the boundary unseekable.

## epoch_driver_follows_primary_video rationale

Regression for the hardcoded-`track 0` epoch driver: on an M2TS/PMT
title the PMT may list an AUDIO ES before the VIDEO ES, so `streams[0]`
is audio and the video is at index 1. The epoch driver must follow the
PRIMARY VIDEO track (first video index), not the literal 0. If audio
(index 0) drove epochs, its sparse/lagging PTS would ratchet the
frontier and false-trigger boundary resets, inflating the timeline. This
drives the muxer with audio=track0 / video=track1 and asserts cluster
timestamps stay monotonic and the timeline does NOT ratchet past the
real span.

## dvd_two_letter_language_becomes_iso_639_2 rationale

RFC 9559 §12 / the Matroska `Language` element spec restrict the legacy
`Language` element to the Matroska language form (ISO 639-2, three
lowercase letters), never ISO 639-1 (two letters). The DVD IFO
audio-attribute block itself carries a raw ISO 639-1 code (e.g. "en") on
disc — `ifo::parse_audio_attr` converts it to ISO 639-2 before returning,
via `ifo::dvd_lang_to_iso639_2`. This mimics the real DVD pipeline
(`disc/dvd.rs`'s `Stream::Audio` construction) end to end: real on-disc
IFO bytes -> `ifo::parse_audio_attr` -> `disc::AudioStream` ->
`MkvTrack::audio` -> the muxer -> the emitted `Language` element.

## a_source_with_no_language_emits_und rationale

A source that knows no language at all leaves `language` EMPTY, and the
muxer writes the `Language` element unconditionally — so an empty string
becomes a zero-length `Language` in the shipped file, which is not a
Matroska language form (RFC 9559 §12 wants three ISO 639-2 letters) and
is not the ISO 639-2 code for "unknown" either.

This is the state every HD-DVD rip is in: `disc::hddvd`'s EVO stream
probe has no language table to read and sets `language: String::new()`
on every audio stream it finds. The DVD path normalises to "und" in
`ifo::parse_audio_attr`; the guard has to exist at the muxer too, which
is the one place every source funnels through.

## dvd_unmapped_or_empty_language_becomes_und rationale

An unmapped or absent DVD language code (bytes 0x00 0x00 in the IFO
attribute block) must degrade to the valid Matroska "undetermined" code
`und`, never to an empty string or a raw 2-letter code — both of which
violate the Matroska language form.

## emitted_language_for_dvd_code

Builds an 8-byte DVD IFO audio-attribute block (AC-3, 48 kHz, 6ch)
carrying `code` in the language bytes, runs it through the real DVD
pipeline (`ifo::parse_audio_attr` -> `disc::AudioStream` ->
`MkvTrack::audio` -> the muxer) and returns the value that actually lands
in the emitted Matroska `Language` element.

## dvd_language_outside_the_menu_vocabulary rationale

The ISO 639-1 -> ISO 639-2 conversion must cover the WHOLE of ISO 639-1,
not just the handful of languages that happen to appear in Blu-ray
menu-graphic filenames. A Region-2 disc routinely carries Romanian,
Bulgarian, Croatian, Serbian, Slovak, Slovenian, Hebrew, Estonian,
Latvian, Lithuanian, Icelandic and so on; if those all collapse to `und`,
every one of a disc's subtitle tracks emits the same `Language` value and
nothing else tells them apart (DVD streams carry an empty `label`). A
valid-but-identical code is worse for the user than the invalid one it
replaced, so each of these must reach the emitted `Language` element as
its own correct three-letter code.

## dvd_era_language_aliases_map_to_the_modern_code rationale

DVD-Video froze its language list on the 1988 edition of ISO 639-1,
which spelled Hebrew `iw`, Indonesian `in` and Yiddish `ji`. Real discs
authored to that list carry those bytes, so they must map to the same
ISO 639-2 codes as the modern `he` / `id` / `yi` spellings rather than
degrading to `und`.

## unknown_dvd_language_still_yields_exactly_und rationale

Widening the table must not weaken the degradation guarantee: a code
that is not ISO 639-1 at all still has to yield exactly `und`, a valid
Matroska language value, and never a passed-through two-letter code, an
empty string, or a guess.

## mkv_pgs_wrong_forced_label_is_cleared rationale

A wrong vendor forced label is CLEARED by the content — but only where
the content can carry that argument. During a full mux every display set
on the track is seen, so "this track has hundreds of display sets and
not one of them is forced" is as complete as evidence gets; and a
sibling track that does carry `forced_on_flag` proves the authoring
house sets it, so the absence on this track means something.

Before this, `finish()` only ever promoted 0→1, so a track wrongly
labelled forced stayed forced in the output no matter what the disc
contained.

## mkv_pgs_forced_label_survives rationale

The guard that stops the above clearing from being reckless. On a disc
whose authoring never sets `forced_on_flag` — they exist — no track has
any forced display set, so "no forced display set here" is a fact about
the authoring, not about the track. The vendor label is then the only
information there is and must survive.

## a_title_the_seam_plan_emptied audit finding

`a_title_the_seam_plan_emptied_is_not_reported_as_a_skippable_stub`
asserts a seam-plan clip list whose marks exclude every frame must fail
with `SinkWroteNothing`, NOT `MkvInvalid`.

Audit finding: both gates in `finish()` were dead code under test —
`set_clips` was never called anywhere in the suite, so
`continuity.dropped_total()` was always 0 and neither branch could be
reached. Swapping the two `frame_count == 0` checks left the whole suite
green, while a title the seam plan emptied came back as `MkvInvalid` —
which `is_skippable_title_stub` classifies as an empty nav/menu stub, so
an all-titles rip would silently omit a real feature and exit 0.

## all_block_groups rationale

`all_block_groups` parses EVERY BlockGroup in the output, in emission
order.

A presence check like `find_id(data, ebml::REFERENCE_BLOCK).is_some()`
cannot express what actually matters here: ReferenceBlock's ID is the
single byte 0xFB, and finding one somewhere in the file says nothing
about WHICH blocks carry it. A mutant emitting a ReferenceBlock on every
BlockGroup — keyframes included — satisfies that check while making
every frame read back as a non-keyframe, which is the exact defect these
tests exist to guard.

## dolby_vision_config dvcC bit-packing layout

`dolby_vision_config` (dvcC) bit packing: byte 2 = profile(7 bits) << 1 |
level high bit; byte 3 = level low 5 bits << 3 | rpu | el | bl; byte 4 =
bl_compat_id << 4.

## parse_bps_tags decode rationale

`parse_bps_tags` parses the `Tags` master into `(TagTrackUID, BPS)`
pairs, decoding the BPS `TagString` back to a number.

The previous assertion was
`String::from_utf8_lossy(&data).contains("800")` over the WHOLE file,
which a wrong BPS passes trivially — 80000 contains "800", and so does
any unrelated byte run that happens to spell it. The bitrate a media
player displays has to be the real one, so decode it.

## seekhead_chapters_entry rationale

The Chapters Seek entry has to be back-patched like every other one. It
is the only fixup whose offset comes from an `Option`, so it is the only
one that can quietly fall through to the `_ => 0` arm and ship a
SeekPosition of 0 — a chapter index a player resolves to the Segment
header. Only titles WITH chapters exercise it, and every SeekHead test
until now used a chapterless title.

## video_track_survives_a_zero rationale

`MkvTrack::video` divides by two disc-supplied numbers: the frame-rate
numerator and the display-aspect denominator. Both come off an IFO/MPLS
scan of a damaged disc, and a zero in either one is an arithmetic panic
that takes down the whole `autorip` service — not a bad file. The guards
exist; nothing proved they were load-bearing.

## secondary_streams_are_never_the_default rationale

FlagDefault marks the track a player selects with no user input. A
SECONDARY stream (a Dolby Vision enhancement layer, a director's
commentary) must never be it: default-selecting the DV EL shows a viewer
the wrong picture, and default-selecting a commentary track the wrong
audio. `is_default` is the inverse of `secondary` on both the video and
the audio builder; neither inversion was asserted.

## subtitle_codec_id_distinguishes_vobsub_from_pgs rationale

DVD subtitles are VobSub, Blu-ray subtitles are PGS, and the codec ID is
what tells a player which parser to hand the bitstream to. The subtitle
builder's fallback is PGS, so a lost `Codec::DvdSub` arm silently labels
every DVD subtitle track as PGS — a track that displays nothing.

## hdr_format_overrides_the_transfer rationale

The HDR transfer override is the only thing that turns the coarse
`color_space` nibble into a PQ/HLG code point. Every earlier test paired
HDR10 with BT.2020, whose enum mapping already yields PQ — so the
override itself was never observed. A disc whose playlist nibble says
BT.709 while the scan detected HDR10 (an ordinary UHD mis-tag) is the
case that separates them: without the override it ships transfer 1 (SDR
gamma) and the picture renders washed out.

## mvc_decoder_config_record_boundaries rationale

`mvc_decoder_config_record` frames a Blu-ray 3D parameter set with
16-bit length prefixes. Its bounds are exact: 4 bytes is the shortest
subset SPS it can read `profile`/`compat`/`level` out of, and 0xFFFF is
the largest length the field can express. Off by one at either end and a
valid 3D title silently loses its mvcC mapping (no 3D signal) or writes
a record whose declared length does not match its payload.