mirror of
https://github.com/freemkv/libfreemkv.git
synced 2026-10-07 18:13:10 +00:00
Matthew Jackson
6e14fc0c0c
Security - Remove the unsafe Vec::set_len over recycled sector buffers — UB reachable from safe code (GHSA-j8ww-f5fg-9pmh, low). Uses Vec::resize; pooling unchanged. CI / tooling - clippy on stable with the MSRV single-sourced from Cargo.toml; cargo-deny dependency-audit gate with first-party git sources allowed (#15); audience-based comment-guard (#17). Docs - README (keydb ownership, BD-J parser count), drive-access transport/reset notes, mux timeline module-doc links.
80 lines
4.2 KiB
Markdown
80 lines
4.2 KiB
Markdown
# `src/mux/codec/mod.rs` — extended notes
|
|
|
|
Relocated prose from doc comments in `mod.rs`, trimmed there to stay within
|
|
the comment-guard's prose caps. Each `//`/`///` pointer in the source names
|
|
the section here it corresponds to.
|
|
|
|
## `Frame::discontinuity`
|
|
|
|
Carried per-FRAME (not per-PES) because buffering parsers decouple the frame
|
|
from the PES that carried the gap signal: MPEG-2 emits whole GOPs, H.264/HEVC
|
|
lag one access unit behind the PES that produced them. A clean rip leaves
|
|
every frame `false`; the flag is only ever set on the degraded/conceal path
|
|
(P3/B1), when a frame's data begins after packets the demuxer never received
|
|
— an undecryptable unit concealed as NULL-TS upstream, or a continuity break
|
|
in a damaged source.
|
|
|
|
## Drop-on-undecodable policy across codecs ("clean muxes always")
|
|
|
|
- **Audio with independent access units** (DTS, AC-3/E-AC-3, …) gates each AU
|
|
through a per-codec corruption check and drops the ones that fail, keeping
|
|
A/V sync (a drop is a silence gap, never a shift) and logging every drop
|
|
via the shared `dropgate::DropTally`. DTS validates via its core-frame
|
|
header (ETSI TS 102 114); AC-3 uses its native frame CRC.
|
|
- **LPCM is excluded on purpose**: raw PCM carries no framing or integrity
|
|
data, so a corrupt sample is indistinguishable from a quiet one — there is
|
|
nothing to detect, so nothing can be honestly dropped.
|
|
- **Video is excluded on purpose**: H.264/HEVC/MPEG-2/VC-1 are inter-frame
|
|
predicted, so dropping one frame corrupts every frame that references it
|
|
until the next keyframe. Video instead resyncs at GOP/IDR boundaries (the
|
|
ResyncGate) and lets the decoder conceal — a fundamentally different model
|
|
than per-frame audio dropping.
|
|
- TrueHD/MLP, FLAC, MP2/MP3 and AAC-ADTS also gate undecodable frames via a
|
|
`DropTally` (poison/drop-forward for MLP's inter-AU restart state on a
|
|
major-sync boundary; CRC/sync-verdict drops for the passthrough codecs).
|
|
|
|
## `codec_private()` — why "absent" is the only truthful answer for some parsers
|
|
|
|
A codec parser's `codec_private()` feeds `DiscStream::codec_private`, which
|
|
the MKV muxer turns directly into the track's `CodecPrivate` element (RFC
|
|
9559 §5.1.4.1.24): `Some(bytes)` writes an element holding exactly those
|
|
bytes, `None` omits the element entirely. The two are NOT interchangeable —
|
|
a zero-length `CodecPrivate` asserts that the codec's initialisation data IS
|
|
empty, which is not true of any codec, and a one-byte one asserts a config no
|
|
decoder can parse.
|
|
|
|
The gating parsers (ADTS, MPEG audio, FLAC) and the passthrough parser
|
|
extract no configuration at all: they validate and forward frames whose
|
|
configuration is carried in band (ADTS headers, MPEG-1 audio frame headers,
|
|
FLAC frame headers) or supplied by the source container. Having derived
|
|
nothing, the only truthful answer they can give is "absent" — any `Some`
|
|
would be a value they invented. Nothing else in the test suite distinguished
|
|
the two, so each of these impls could have returned a fabricated `Some` and
|
|
produced a malformed track header unnoticed.
|
|
|
|
## `provenance_guard` test module
|
|
|
|
Every emitted frame must carry the source byte offset of the packet it came
|
|
from. That invariant held only for video for as long as it existed: `dts`,
|
|
`ac3`, `adts`, `truehd`, `pgs`, `dvdsub`, `flac`, `lpcm`, `mpegaudio` and the
|
|
passthrough parser all built frames with `source: None`, so a multi-clip
|
|
title could not place audio or subtitles by byte and fell back to inferring
|
|
the clip from timestamps — which is what made branched titles run minutes
|
|
long.
|
|
|
|
Nothing asserted it, so nothing caught it. Finding it took a brace-balanced
|
|
scan of the tree by hand, which also turned up five sites a regex had
|
|
missed. `provenance_guard` is that scan, as a test.
|
|
|
|
### `code_only` / `frame_literals` design
|
|
|
|
`frame_literals` walks `Frame { .. }` literals with balanced braces. A regex
|
|
cannot do this — `Frame` blocks contain nested braces (`coding: Some(..)`,
|
|
closures) and a non-greedy match stops at the first `}`, which is how five
|
|
sites survived the first pass.
|
|
|
|
`code_only` strips line comments before scanning. A comment that MENTIONS
|
|
`source: None` is prose, not a construction — this guard's own doc comment
|
|
tripped it on the first run, which is the same mistake as grepping a file
|
|
and matching its commentary.
|