libfreemkv/docs/mp4-read.md

mp4 read (src/mux/mp4/read.rs) — internal notes

MAX_TRACKS

Track count is otherwise unbounded (a crafted moov can pack tens of thousands of trak boxes), and the per-track PID is 0x1011 + track_idx, which overflows u16 past ~61k tracks. Real titles have well under a hundred tracks.

MAX_SAMPLE_COUNT

MP4 sample-table fields (stsz sample_count, stts/ctts run-lengths) are untrusted 32-bit values; a crafted box can declare billions of entries in a few bytes. Real titles stay far under this (a 10 h/60 fps track is ~2M samples), so clamping to it caps a hostile file's allocation without truncating any legitimate track.

MIN_FILE_BYTES_PER_SAMPLE

Only vide and soun tracks are indexed here, and no real coded video or audio access unit is anywhere near this small: the shortest legal AC-3 frame is 128 bytes, an AAC frame is hundreds, and a video sample carries at least a NAL header plus slice data. A 2-hour title runs to thousands of file bytes per sample, so this cannot truncate a genuine track — it only stops a crafted sample table from claiming more samples than the file could possibly hold.

Test rationale (mod tests)

FakeBigReader

A Read + Seek backed by a small crafted prefix followed by an endless run of zeros, reporting len bytes total on seek(End). Lets a test exercise a hundred-MiB-to-multi-GiB boundary (MAX_ALLOC_BYTES, a sparse-file-inflated file_len) without a real backing allocation of that size for the SOURCE side — only the destination buffer the code under test allocates is real, which is the point of the test.

parse_stss_reads_two_distinct_entries_from_their_own_offsets

parse_stss had no direct positive-path test anywhere in this file — only its short-buffer safety was pinned. Two real, distinct entries in a buffer sized to exactly fit them (b.len() == 16, so the second entry's o + 4 == b.len() exactly) separates every arithmetic mutant at once: an o = 8 + i*4 → 8 - i*4 slip reads the count field instead of the second entry; an i*4 → i/4 slip re-reads the FIRST entry for the second (integer division collapses i=1 back to the same offset as i=0); and an o + 4 > b.len() → o + 4 < b.len() slip breaks out on the very first entry, because there IS more room after it (12 < 16) — leaving the set empty instead of holding both.

parse_stss_count_lie_is_bounded_by_the_box_not_trusted

A declared count larger than the box can hold (a lie, or a truncated box) must be bounded by the per-entry guard, not by trusting the count — the SAME contract parse_stco/parse_stsc/parse_stts pin with their own "count lie" tests. Bounded HERE means the loop must stop, not read past the end: an o + 4 > b.len() → o - 4 > b.len() mutant almost never fires (o - 4 stays small for every realistic o), so it lets the loop walk straight past a truncated box into an out-of-bounds be32 read.

sample_offsets_advances_through_distinct_sizes_within_one_chunk

sidx must advance by exactly one PER SAMPLE PLACED, so the third (and every later) sample in a chunk picks up its own size, not the first sample's reused over and over. With only two samples in a chunk this bug is invisible — the second sample's pushed offset was already computed from sizes[0] before sidx had a chance to matter — so this test needs a chunk with THREE distinctly-sized samples to expose it.

stream_read_allows_a_sample_of_exactly_max_alloc_bytes

Stream::read's own s.size as u64 > MAX_ALLOC_BYTES cap — a SEPARATE call site from read_moov's (see read_moov_allows_a_payload_of_exactly_max_alloc_bytes / the module doc's note on the same policy hardened at only one of two sites elsewhere in this crate). A >↔>= mutant here would reject a sample of exactly the cap, which must be allowed. Builds an Mp4Reader directly (its fields are private but visible to this module's tests) over a FakeBigReader so the 256 MiB sample doesn't need a real backing file — only the destination buffer read() allocates is real.

stream_read_rejects_a_sample_one_byte_over_max_alloc_bytes

The same cap's other edge: one byte OVER it must still be rejected. A >↔== mutant would only catch a sample of EXACTLY the cap and let anything larger through — the worse direction to get wrong, since it turns the cap into a no-op for every real oversized/hostile sample.

stts_expands_runs_to_per_sample_deltas_in_order

stts run-length expansion — ISO/IEC 14496-12 §8.6.1.2. The box stores (sample_count, sample_delta) runs; the reader must expand them back to one delta PER SAMPLE, in order, or every sample after the first run lands on the wrong decode time.

(This test used to be called stts_and_ctts_expand while touching no ctts box at all. The composition-offset half now lives in ctts_build_and_parse_are_exact_inverses_over_signed_offsets and b_frame_presentation_order_survives_the_mp4_round_trip.)

declared_track_duration_equals_frame_count_times_frame_duration

A track's declared duration must be its real length. mdhd.duration is in the MEDIA timescale and mvhd.duration in the movie timescale (ISO/IEC 14496-12 §8.2.2, §8.4.2); a player uses them to draw the seek bar and to decide when the title ends, so a zeroed or constant duration makes a correct file unseekable and apparently empty.

moov_tree_carries_the_mandatory_track_header_and_media_boxes

The moov tree must carry the boxes ISO/IEC 14496-12 makes mandatory for a playable track, with the field values the spec fixes. These live in this module rather than the writer's because the box-walking helpers (find_box) are here — asserting through them means the test reads the file the way the demuxer does, instead of re-deriving the layout.

Nothing in the demux path needs tkhd/vmhd/smhd/dinf, so an empty one of any of them round-trips through this crate unnoticed while making the file unplayable elsewhere.

table_parsers_reject_every_length_up_to_the_header_size

Every one of these five table parsers opens with if b.len() < 8 { return <empty> } before reading count = be32(b, 4), which needs b.len() >= 8. No existing fixture ever called any of them with a buffer shorter than 8 bytes — every test builds a complete box — so a <→== mutant of that guard (which only early-returns at EXACTLY b.len() == 8, letting every length below it fall through to the out-of-bounds be32 read) had nothing to fail against. Pins the entire boundary at once, every length from 0 through 8, for all five.

parse_stco_co64_reads_each_byte_from_its_own_offset

co64's 8-byte offsets are decoded byte-by-byte (u64::from_be_bytes([b[o], b[o+1], ..., b[o+7]])) — a SEPARATE code path from the 32-bit stco case, which goes through be32 instead and was never itself built with a co64 fixture anywhere in this file. Every byte here is distinct, so an index slip (off by one, negated, or scaled) that reads the wrong byte cannot agree by coincidence.

parse_stsd_rejects_every_length_below_the_header_size

Every buffer shorter than the 8-byte version+flags+entry_count header must return None — never fall through to &b[8..], which would slice past the end and panic. b.len() == 8 is the boundary itself (see the equivalence note on parse_stsd's guard); everything strictly below it must be rejected by THIS check, not rely on a later one that isn't reached yet.

parse_esds_asc_boundary_checks_are_independent

The final guard is asc_len == 0 || end > b.len() — two independent rejection reasons, not one condition that needs both. Pins each half:

• asc_len == 0 must be rejected even though end == pos is trivially in bounds (an ||→&& mutant would let a useless zero-length ASC through as Some(vec![]));
• end > b.len() means TRUNCATED, not "anything before the buffer's end" — trailing bytes after a complete ASC (end < b.len()) must still succeed (a >→< mutant rejects exactly this, the common case of an esds embedded inside a larger box with more child boxes or padding after it).

read_moov_exactly_header_sized_is_a_valid_empty_box

box_size < header_len rejects a box that cannot even hold its own header. A box whose size is EXACTLY header_len (8, no 64-bit largesize) is the boundary itself: legal (an empty box), so an empty moov — size 8, zero payload bytes — must parse to Ok(vec![]), not be rejected by a <→<=/== mutant that also rejects the boundary.

read_moov_rejects_a_box_that_overruns_the_file_via_the_or_not_and_guard

The forward-progress / EOF guard is box_size < header_len || pos.checked_add(box_size).is_none_or(|end| end > file_end) — an ||↔&& mutant only shows up on an input where EXACTLY ONE side is true. A box that claims to run 992 bytes past a file that ends right after its header satisfies only the second clause (box_size >= header_len, so the first is false); under && the guard would not fire, and read_moov would instead fail later inside read_exact with a plain UnexpectedEof — a different, uncoded io::Error rather than this crate's Mp4Invalid (ErrorKind::InvalidData), which the guard exists to produce uniformly for every malformed box.

read_moov_allows_a_payload_of_exactly_max_alloc_bytes

payload_len > MAX_ALLOC_BYTES is a SEPARATE, sparse-file-proof cap from the EOF check above (see read_moov_over_cap_rejected_despite_inflated_file_len). A >→>= mutant would reject a moov whose payload is EXACTLY MAX_ALLOC_BYTES, which must be allowed.

edit_list_media_time_shifts_the_presentation_timeline

Regression (silent A/V desync): the sample timeline was built purely from stts/ctts starting at tick 0 and no edts/elst was ever parsed, so the presentation timeline an edit list defines was discarded. A non-empty edit with media_time = 1024 — the standard way encoder delay is expressed — must move the track's presentation, not be ignored.

parse_elst_v1_entry_bytes_come_from_their_own_offsets

Every byte of a version-1 entry's segment_duration (8 bytes) and media_time (8 bytes) at its own offset — not a neighbour's. The existing fixtures elsewhere use 5_000u64 and -1i64, which are almost all zero/0xFF bytes, so an index slip that reads an adjacent byte (or a header byte outside the entry) often reads the SAME value and the test cannot tell. Every byte here is distinct and nonzero, and the header bytes are zero, so any wrong index — off by one, negated, or scaled — pulls in a value that cannot match by coincidence.

elst_offset_ticks_stays_safe_at_zero_empty_ticks_even_with_a_zero_movie_timescale

Some(mts) if empty_movie_ticks > 0 and the None branch's if empty_movie_ticks > 0 are both guards around a tracing::warn!/delay computation that, at empty_movie_ticks == 0, must produce the exact same answer as skipping it (0 ticks of delay — there is no empty edit to convert). The one case where the two are NOT interchangeable is movie_timescale == Some(0): skipping the arithmetic returns 0, but entering it divides by that zero timescale and panics. Real callers never pass this — from_reader filters mvhd's timescale through .filter(|&t| t != 0) before it ever reaches this function (see mdhd_timescale_zero_does_not_divide_by_zero for the sibling guard on the media timescale) — but the function itself has to stay panic-free at its own boundary, independent of what its one caller happens to do today, because libfreemkv runs inside the long-lived autorip service and a panic there is downtime.

audio_trak_hostile_count

A crafted file with a fixed-size stsz (sample_size != 0) claiming count = 0xFFFFFFFF must not inflate the sample index past the file's own byte length. from_reader sets sample_budget = MAX_SAMPLE_COUNT.min(file_len), so a few-hundred-byte file bounds the Vec<SampleRef> to a few hundred — NOT the 16M MAX_SAMPLE_COUNT ceiling. Mutation check: revert the budget to a bare MAX_SAMPLE_COUNT and this file yields ~16M samples, failing the <= file_len (and < MAX_SAMPLE_COUNT) assertions below. Built by a minimal-but-complete audio trak whose fixed-size stsz LIES about its sample count (u32::MAX), with an stsc/stts wide enough to place whatever count survives the budget.

sample_index_ram_is_bounded_by_a_multiple_of_the_file

The RAM amplification the byte-per-sample budget actually bounds: a small crafted file whose stsz claims u32::MAX samples must not force an eager multi-hundred-MB index. At ~60 bytes of RAM per indexed sample, a budget of one sample per file byte gave ~60x the input size; the assertion pins the amplification factor rather than a raw count, so it fails if the budget ever goes back to counting samples per byte.

audio_trak_missing

Build an audio trak identical to audio_trak(48_000) but with the named stbl child box omitted. Used to reach the untrusted-input guards that drop a track whose stsz says samples exist yet whose stco/co64 (chunk offsets) or stsc (sample-to-chunk map) is missing — without such a table every sample offset would resolve near file byte 0.

missing_stco_drops_track_all_dropped_is_invalid

A track with samples (stsz) but no chunk-offset table (stco/co64) must be DROPPED, not indexed with offsets that resolve near file byte 0. With it the only track, the whole file fails Mp4Invalid. Mutation check: delete the if chunk_offsets.is_empty() { continue; } guard and from_reader returns Ok (garbage samples), flipping this to FAIL.

missing_stsc_drops_track_all_dropped_is_invalid

A track with samples (stsz) and chunk offsets (stco) but no sample-to-chunk map (stsc) must be DROPPED — without stsc the samples cannot be placed against the chunk offsets and would pack from byte 0. Mutation check: delete the if stsc.is_empty() { continue; } guard and from_reader returns Ok, flipping this to FAIL.

missing_stts_drops_track_all_dropped_is_invalid

A track with samples (stsz) but no time-to-sample table (stts, mandatory per ISO/IEC 14496-12 §8.6.1) must be DROPPED — without it every sample takes dur=0, collapsing the whole track onto one instant (all-zero timestamps). With it the only track, the file fails Mp4Invalid. Mutation check: delete the if durations.is_empty() { continue; } guard and from_reader returns Ok (all-zero-timestamp samples), flipping this to FAIL.

stsc_placing_fewer_samples_than_stsz_drops_the_track

An stsc that PASSES the non-empty guard but places fewer samples than stsz declares must drop the track. sample_offsets used to pack the unplaced tail after the last known offset, inventing a position, so those frames were read from arbitrary file bytes — the same "emit garbage" outcome the stco/stsc presence guards exist to refuse.

Mutation check: restore the trailing while offsets.len() < sizes.len() pack-after-last loop and this file indexes 3 samples instead of erroring.

short_stts_drops_the_track_like_an_absent_one

A SHORT stts — present and non-empty, but covering fewer samples than stsz declares — must drop the track just like an absent one. The tail samples took dur = 0, collapsing the whole tail onto a single timestamp, which is the exact degenerate timing the absent-stts guard refuses.

Mutation check: weaken the guard back to durations.is_empty() and this file indexes 3 samples whose last two share one timestamp.

mdhd_language_boundary_rejects_short_not_merely_non_exact

The length guard is b.len() < off + 2 — reject too SHORT, not "not exactly off + 2". Pins both edges of that boundary for the version-0 offset (off == 20):

• b.len() == off (no room for the packed field at all) must return None, not read two bytes past the end;
• b.len() == off + 3 (one byte MORE than the minimum) must still succeed — a <→> mutant of the guard would reject this case, since off + 3 > off + 2.

parse_stsd_takes_height_from_its_own_field_not_the_width_beside_it

height is the SECOND of the two 16-bit dimensions in a VisualSampleEntry, at byte 26 — width sits at 24. Reading the wrong one is silent: the value is still a plausible dimension, so the track's seeded resolution simply comes out wrong (1920 read as a height would classify a 1080p title as UHD). The two are deliberately different here; a fixture with width == height would pass under either offset.

parse_stsd_reads_channelcount_from_its_own_field_and_defaults_a_short_entry

channelcount is at byte 16 of an AudioSampleEntry, after the 8 reserved bytes that follow data_reference_index. An offset slip reads a reserved field, and reserved fields are conventionally zero — which would make every audio track come out as 0 channels rather than fail. The short-entry fallback of 2 is pinned in the same test: an entry with no room for the fixed part still has to name SOME channel count, and 0 is not a usable one.

parse_stsd_extracts_aac_codec_private_only_when_the_body_is_long_enough

mp4a's codec_private (the AudioSpecificConfig inside a child esds box) is only read when the entry is Codec::Aac AND its body is at least the 28-byte fixed AudioSampleEntry part — find_box(&body[28..], ...) would slice past the end otherwise. No existing test built an actual mp4a entry, so neither half of that guard (&&, or the >= 28 on its right) was constrained: an &&→|| mutant reaches the same &body[28..] on a codec-only match, and a >=→< mutant loses a real title's AAC CodecPrivate outright by only running on entries too short to have one.

parse_stsd_recognises_every_audio_fourcc

Every recognised audio fourcc must map to its own Codec, checked one by one. ec-3/dtsc/dtse/dtsh/dtsl had no coverage at all before this test — a deleted match arm for any of them falls through to the catch-all _ => return None, silently dropping every E-AC-3 or DTS variant track from the title instead of remuxing it.

read_descriptor_len_is_a_four_byte_base_128_varint

A descriptor length is a base-128 varint: 7 bits per byte, continued while the top bit is set, to a maximum of FOUR bytes. Every existing esds fixture uses a single-byte length, so the continuation path is unconstrained by them — yet a multi-byte length is exactly what an esds carrying a long AudioSpecificConfig (or one written by a tool that always pads to 4 bytes, which is common) uses.

parse_esds_asc_steps_over_every_optional_es_descriptor_field

The optional ES_Descriptor fields (ISO/IEC 14496-1 §7.2.6.5) are selected by three flag bits, and each one that is set inserts bytes before the DecoderConfigDescriptor. Skipping them wrongly does not corrupt anything — the tag check fails and parse_esds_asc returns None, so the AAC track simply loses its CodecPrivate and the remux emits AAC no decoder can initialise.

The existing fixture has flags = 0, so all three skips are unconstrained. This one sets all three at once and still has to reach the same ASC.

find_boxes_capped_refuses_a_box_smaller_than_its_own_header

A box header is 8 bytes, so a declared size below 8 cannot describe a box — and taking it at face value slices payload[pos + 8 .. pos + size] with the start past the end, which panics. A crafted moov is untrusted input read straight off a user's file.

find_boxes_capped_decodes_the_size_field_from_its_own_bytes

The declared box size is decoded from four specific bytes (payload[pos..pos+4], big-endian). A size deliberately chosen so byte 1 differs from byte 0 catches an index slip that rereads byte 0 (or any other wrong offset) instead of the byte the field actually occupies — with a small size every byte but the last is zero, so such a slip would go unnoticed.

sample_offsets_clamps_an_stsc_run_that_outruns_the_chunk_table

An stsc entry names a first_chunk that may exceed the chunk count the stco actually declares (a truncated or crafted table). The run it would fill has to be clamped to the chunks that exist — indexing spc past its length is a panic on a file the user merely opened.

The clamp is only reachable through a NON-final entry: the final entry's end is n_chunks by construction, so a fixture whose only over-range entry is last never reaches the line.

elst_offset_ticks_honours_the_first_media_edit_not_the_last

ISO/IEC 14496-12 §8.6.6: an edit list may hold several media edits. This frame model can only express a constant shift, so it honours the LEADING one and logs the rest — taking the last instead would shift the whole track by a trim that belongs to a later segment, i.e. silent A/V desync of exactly the size of the difference.

mvhd_timescale_version_1_reads_past_the_64_bit_times

A version-1 mvhd carries 64-bit creation/modification times, so its timescale sits at byte 20 rather than 12 (ISO/IEC 14496-12 §8.2.2). Every existing fixture is version 0, so the version-1 offset is unconstrained by them — and it is not a hypothetical: writers emit version 1 whenever the movie duration does not fit 32 bits.

A wrong offset reads part of the 64-bit modification time, which is a large arbitrary number — and the movie timescale is the denominator that converts an empty edit's delay into media ticks, so the A/V offset it produces is arbitrary too.

parse_elst_entry_count_is_capped

Only the leading empty edits and the FIRST media edit shape the offset, so MAX_ELST_ENTRIES bounds what a crafted elst can allocate. Without it a box declaring millions of entries — and carrying the bytes for them, inside a moov already capped at 256 MiB — expands to a Vec of 20-byte tuples for no benefit at all.

non_av_handler_track_is_dropped_not_folded_into_audio

A hdlr of anything other than vide/soun (e.g. a hint or subtitle track) must be dropped, not folded into the audio branch. Before this guard existed as a literal &h == b"soun" comparison, weakening it to "anything that isn't vide" would silently turn a hint track's stsd entry into a fabricated AudioStream — with whatever codec its sample entry happened to name.

per_track_pid_arithmetic_is_exact_past_the_first_track

The per-track PID is 0x1011 + track_idx for video and 0x1100 + track_idx for audio. At track_idx == 0 a +↔-/* mutant of either is invisible (0x1011 + 0 == 0x1011 - 0 == 0x1011 * 0… no — * 0 is 0, already different — but +↔- specifically needs track_idx != 0 to separate). Four tracks (two video, two audio) push track_idx to 1 and 3 respectively, so every one of +→*, +→- is forced to disagree with the correct PID on the second track of its kind.

track_idx_advances_past_a_sample_less_track

A track whose stsz is absent (n == 0) still occupies a track_idx slot and must still advance the counter for the NEXT track — otherwise two tracks collide on the same PID, or (worse, if the increment direction is reversed) track_idx underflows a usize and panics on the very first sample-less track.

sample_budget_is_shared_and_exhausted_across_tracks

The global sample_budget is DECREMENTED by each track's real sample count, and it is SHARED across tracks — a track late in the file gets only what earlier tracks left behind. Build two tracks that both LIE about their sample count (stsz fixed-size, count = u32::MAX, as in audio_trak_hostile_count): the file is tiny, so the first track's clamped count exactly exhausts the whole initial budget, and the second track — clamped against what's left — must come back with ZERO samples. An +=//= mutant of the decrement either grows the budget or leaves it nonzero, letting the second track claim samples it must not have.

elst_offset_ticks

Presentation-time offset an edit list imposes on a track's samples, in the track's MEDIA timescale ticks (ISO/IEC 14496-12 §8.6.5-§8.6.6).

Two constructs cover essentially every real edit list, and both reduce to a constant shift of the whole track:

• an EMPTY edit (media_time == -1) before the media edit, whose segment_duration — in MOVIE timescale ticks — delays presentation;
• a non-empty edit whose media_time trims that much media off the front.

So the offset is (sum of leading empty segment_durations) - media_time. A list with several non-empty edits, or a non-empty edit at a rate other than 1, describes a timeline this frame model cannot express (it would need samples dropped, reordered or repeated); the leading edit is still honoured, and the part that is not is LOGGED rather than passed off as a faithful copy.

MAX_ALLOC_BYTES

The EOF check alone is not enough: file_len is cheaply inflatable with a sparse file (truncate -s 8G), so a crafted stsz size or moov box size just under an 8 GiB apparent length would otherwise force a multi-GiB allocation. No real sample or moov approaches this.