Module mp4 

Hand-rolled MP4/M4A box layer: parse the structure, read iTunes metadata, and regenerate moov (with patched chunk offsets) to synthesize a re-tagged file whose mdat audio payload is served verbatim. Strict: anything outside the supported shape (single audio track, one mdat, non-fragmented) is rejected.

Structs

BoxHeader

A parsed box header (the payload need not be in memory). Public so the core reader can reason about box bounds while seeking.

Mp4Bounds

Audio payload bounds within the backing file (the verbatim mdat payload).

Mp4Scan

Everything synthesize_layout needs, read from the backing file once.

OversizeDrop

An embedded covr image or binary ---- payload that a reader skipped because it exceeded the caller’s size cap. Carries only a descriptor and the payload’s byte size — never the bytes themselves — so the caller can log the lossy drop (the format layer has no logging facade) without materializing the oversized item out of a potentially large moov (#343).

Enums

Mp4ScanError

Error from the seeking MP4 reader: an IO failure reading the file, or a structural/format problem. Kept distinct so the core layer can map IO to CoreError::Io (preserving errno) and format to CoreError::Format.

Functions

box_header

Parse a box header from hdr (>= 8 bytes; >= 16 if it uses a 64-bit largesize). remaining is the byte count from this box’s start to EOF, used to resolve a size == 0 (“extends to end”) box.

locate_audio

Parse the file and return the mdat payload bounds, or an error to skip it.

read_binary_tags

Extract opaque (non-text) MP4 ---- freeform atoms for binary-tag passthrough. One EmbeddedBinaryTag per binary-typed (type code != 1) data sub-box of each ---- atom: key ----:<mean>:<name>, payload the data value bytes (after the 8-byte [type][locale] header). Text freeform atoms (type 1) are handled by read_tags, so the two paths never double-store. Lenient: malformed atoms are skipped. Every data sub-box is inspected, so a mixed atom carrying both a text and a binary value recovers the binary one.

read_binary_tags_reporting

Like read_binary_tags, but also returns the oversized ---- values skipped over max_binary_tag_bytes, so the caller can log each lossy drop. The size check still happens before any copy — an oversized value is described, never materialized. See OversizeDrop.

read_pictures

Lenient: returns empty / skips any malformed atom and never errors — this only seeds cover art from existing files, so a missing or garbled picture must simply be absent. Every data child of every covr atom yields one picture (the iTunes multiple-artwork convention); non-data children are skipped.

read_pictures_reporting

Like read_pictures, but also returns the oversized covr images skipped over max_art_bytes, so the caller can log each lossy drop. The size check still happens before any copy — an oversized image is described, never materialized. See OversizeDrop.

read_structure

read_structure_from

Read the structural boxes (ftyp, moov, and the mdat header) by seeking, never reading the mdat payload — for audiobooks that payload is hundreds of MB and is served from the backing file at read time. Produces an Mp4Scan byte-identical to read_structure on the same file, so synthesis is unchanged.

read_tags

Lenient: returns empty / skips any malformed atom and never errors — this only seeds metadata from existing files, so a missing or garbled tag must simply be absent. Text atoms map via the vocabulary; trkn/disk yield track/disc numbers as "N"/"N/M"; ---- freeform atoms key on their name (folded when known). Every data sub-box of an atom is read, so multi-value atoms recover all their values. Other atoms are skipped.

synthesize_layout

Regenerate a re-tagged moov and produce the serving layout [ftyp][regenerated moov][mdat header][mdat payload]. The mdat payload is served verbatim, merely relocated, so every chunk offset shifts by a constant delta. Patching only offset VALUES (never box sizes) means new_moov_size is computable before delta — no circular dependency. Cover art (every non-empty art row, in input order) and opaque ---- binary tags stream from the DB at read time, splicing into the layout.