bookclerk_mp4
ISO-BMFF (MP4) container plumbing: read a progressive file, pick samples by
media time, and write a faststart ftyp + moov + mdat M4B in one pass.
remux_progressive streams payloads through a SampleTransform, and the
only implementation this crate ships is CopySamples. A store that has to
turn its own ciphertext into plaintext keeps both the key and the cipher on
its side of that trait, inside its own plugin process.
That split is why two very similar remuxers used to exist: the host needed
one for clear media and the Audible plugin needed one that could decrypt
mid-copy, and neither could take on the other's dependencies. The transform
hook removes the copy without moving the boundary — see docs/server/media.md for
why the boundary is where it is.
| Item | Kind | Summary |
|---|---|---|
SampleTransform |
trait | Rewrites sample payloads as they stream from input to output. |
BrandDurations |
struct | Brand intro/outro durations from Audible chapter_info. |
AudioTrack |
struct | Parsed audio track summary (timescale, samples, codec). |
Mp4File |
struct | Parsed progressive (non-fragmented) MP4 relevant to remux. |
Mp4aConfig |
struct | Clear AAC (mp4a) decoder config extracted from a progressive MP4/M4A/M4B. |
MoovLocation |
struct | Where a file's moov sits. |
SampleReader |
struct | Reads sample payloads by absolute file offset, buffered. |
CopySamples |
struct | Copies every sample through untouched. |
ProgressiveWriteInput |
struct | Inputs for writing a progressive faststart M4B (ftyp + moov + mdat) in one pass. |
RemuxOptions |
struct | Options controlling sample-copy remux (trim window, etc.). |
TrimRange |
struct | Optional media-time trim window in milliseconds (absolute, pre-rebase). |
ChunkMapEntry |
struct | One run from the sample-to-chunk (stsc) table. |
SampleInfo |
struct | One audio sample, located and timed. |
Mp4Error |
enum | Errors from MP4 parse, remux, and in-place patch operations. |
SampleEntryKind |
enum | Codec or encryption FourCC found in the track's sample description. |
brand_durations_from_chapter_info |
function | Read brand intro/outro durations from chapter_info JSON. |
brand_trim_range |
function | Build a media trim window that drops Audible branding audio. |
rebase_chapters_after_brand_trim |
function | Adjust flat chapter start offsets after brand trim so cues/metadata stay aligned. |
runtime_length_ms_from_chapter_info |
function | Read runtime_length_ms / runtimeLengthMs from chapter_info JSON. |
extract_mp4a_config |
function | Read sample-rate / channel count / ASC from a clear mp4a sample entry. |
parse_mp4 |
function | Parses top-level boxes and the primary audio track from an MP4/M4A/M4B file. |
sample_entry_bytes |
function | The audio track's whole sample entry box (size, type and body, its codec configuration box included), as stsd holds it, so another file can describe the same samples without decoding them. |
track_duration_ms |
function | Absolute duration of the audio track in milliseconds. |
pad_moov_to |
function | Grow moov to exactly total bytes by appending a free child. |
read_moov |
function | Read a file's moov, and note where it sits. |
shift_chunk_offsets |
function | Move every chunk offset in moov past above by delta bytes. |
strip_trailing_free |
function | Drop a moov's trailing free child, if it has one. |
top_level_boxes |
function | Every box at the top level, in file order. |
write_moov_in_place |
function | Write moov back where the old one was, padding it to the same length. |
remux_progressive |
function | Copy (and optionally trim) a progressive MP4 into a faststart M4B, passing every payload through transform. |
write_progressive_m4b |
function | Write a progressive faststart M4B by streaming one sample at a time. |
build_samples |
function | Builds a flat sample table from stts / stsc / stsz / stco (or co64). |
select_samples_by_ms |
function | Indices of the samples whose media time overlaps [start_ms, end_ms). |
Result |
type alias | Result alias for this crate's error type. |
RESERVED_MOOV_SLACK |
constant | Slack every moov this crate writes carries, as a trailing free child. |
boxutil: Low-level big-endian readers and MP4 box walking.edit: Editing amoovthat is already in memory: find a box, replace a child, and keep every enclosing size field consistent.fixture: Synthetic progressive MP4 files for tests.
pub trait SampleTransform {
fn retain(&mut self, kept: &[usize]) -> Result<()>;
fn sample(&mut self, index: usize, payload: &mut [u8]) -> Result<()>;
}
Rewrites sample payloads as they stream from input to output.
The remuxer moves bytes and rebuilds tables; it never inspects a payload.
A caller that has to turn its own ciphertext into plaintext keeps the key and
the cipher on its side of this trait, which is how store plugins decrypt
their downloads without any of that living here. CopySamples is the only
implementation in this crate.
fn retain(&mut self, kept: &[usize]) -> Result<()>
The original sample indices kept by the trim, in output order.
Called once before any payload, so a transform holding per-sample state (a table of initialization vectors, say) can narrow it to the same selection and then index it by output position.
Returns an error when the operation fails.
fn sample(&mut self, index: usize, payload: &mut [u8]) -> Result<()>
Rewrite output sample index in place. The length must not change.
Returns an error when the operation fails.
Implemented by: CopySamples
pub struct BrandDurations {
pub intro_ms: u64,
pub outro_ms: u64,
}
Brand intro/outro durations from Audible chapter_info.
Fields
intro_ms: Brand intro (pre-roll) duration in milliseconds.outro_ms: Brand outro (post-roll) duration in milliseconds.
pub fn is_empty(self) -> bool
True when both intro and outro are zero (nothing to trim).
Implements: Clone, Copy, Debug, Default, Eq, PartialEq
pub struct AudioTrack {
pub trak: BoxHeader,
pub timescale: u32,
pub duration: u64,
pub sample_entry_kind: SampleEntryKind,
pub sample_entry_type_offset: u64,
pub samples: Vec<SampleInfo>,
}
Parsed audio track summary (timescale, samples, codec).
Fields
trak: ISO-BMFFtrak(track) FourCC.timescale: Media timescale (ticks per second) for this track.duration: Track duration in media timescale ticks.sample_entry_kind: Codec or encryption FourCC found in the track's sample description.sample_entry_type_offset: Absolute file offset of the 4-byte sample-entry type inside stsd.samples: Decoded sample table (offsets, sizes, durations) for this track.
Implements: Debug
pub struct Mp4File {
pub path: PathBuf,
pub file_size: u64,
pub ftyp: BoxHeader,
pub moov: BoxHeader,
pub mdat: BoxHeader,
pub major_brand: FourCC,
pub compatible_brands: Vec<FourCC>,
pub mvhd_timescale: u32,
pub mvhd_duration: u64,
pub audio: AudioTrack,
pub moov_bytes: Vec<u8>,
pub ftyp_bytes: Vec<u8>,
}
Parsed progressive (non-fragmented) MP4 relevant to remux.
Fields
path: Absolute path to the MP4 file that was parsed.file_size: Total file size in bytes.ftyp: ISO-BMFFftyp(file type) FourCC.moov: ISO-BMFFmoov(movie metadata) FourCC.mdat: ISO-BMFFmdat(media data) FourCC.major_brand: Primary brand FourCC fromftyp(e.g.M4A,isom).compatible_brands: Compatible brand FourCCs advertised inftyp.mvhd_timescale: Movie-header timescale (ticks per second).mvhd_duration: Movie-header duration inSelf::mvhd_timescaleticks.audio: Primary audio track summary when present.moov_bytes: Raw moov bytes (including header) — used when rewriting with patched stsd.ftyp_bytes: Rawftypbox bytes (including header) for remux / patch.
Implements: Debug
pub struct Mp4aConfig {
pub sample_rate: u32,
pub channels: u16,
pub asc: Vec<u8>,
}
Clear AAC (mp4a) decoder config extracted from a progressive MP4/M4A/M4B.
Fields
sample_rate: Audio sample rate in Hz from the sample entry.channels: Channel count from the sample entry.asc: AudioSpecificConfig fromesdsDecoderSpecificInfo.
Implements: Clone, Debug
pub struct MoovLocation {
pub start: u64,
pub len: u64,
pub is_last: bool,
}
Where a file's moov sits.
Fields
start: Byte offset of this box or region within the file.len: Total box length,freepadding included.is_last: Whethermoovis the last box in the file, in which case it can grow past its slack for the price of an append.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub struct SampleReader {
/* private fields */
}
Reads sample payloads by absolute file offset, buffered.
Samples sit in track order in a progressive mdat, so consecutive reads are
usually already in place, and otherwise a short hop ahead. Both cases are
served out of the buffer; only a jump past it costs a real seek. Reading in
some other order still works, just without the benefit.
pub fn open(path: &Path) -> Result<Self>
Opens path for buffered sample reads.
path- Filesystem path to a progressive MP4/M4A/M4B.
Reader positioned at byte 0.
Returns crate::Mp4Error::Io when the file cannot be opened.
pub fn new(file: File) -> Self
Wraps an already-opened file with a buffered sample reader.
file- Seekable file handle positioned anywhere (reader seeks per sample).
Buffered reader ready for Self::read_sample.
pub fn read_sample(&mut self, offset: u64, size: usize, buf: &mut Vec<u8>) -> Result<()>
Fill buf with exactly size bytes from offset, resizing it to match.
offset- Absolute byte offset in the file.size- Number of bytes to read.buf- Destination buffer resized tosize.
The successful result value for this operation.
Returns Mp4Error::Container when the sample would end past the end of
the file (a forged or truncated sample table), and an I/O error when the
read itself fails.
Implements: Debug
pub struct CopySamples;
Copies every sample through untouched.
Implements: Clone, Copy, Debug, Default, SampleTransform
pub struct ProgressiveWriteInput<'a> {
pub moov_bytes: &'a [u8],
pub moov_file_start: u64,
pub sample_entry_type_offset: u64,
pub audio_timescale: u32,
pub mvhd_timescale: u32,
pub sample_sizes: &'a [u32],
pub durations: &'a [u32],
}
Inputs for writing a progressive faststart M4B (ftyp + moov + mdat) in one pass.
Fields
moov_bytes: Rawmoovbytes used while rewriting sample tables.moov_file_start: File offset where themoovbox begins.sample_entry_type_offset: File offset of the sample-entry FourCC insidestsd.audio_timescale: Audio track media timescale (ticks per second).mvhd_timescale: Movie-header timescale (ticks per second).sample_sizes: Per-sample byte sizes copied into the output.durations: Per-sample durations in media timescale ticks.
pub struct RemuxOptions {
pub trim: Option<TrimRange>,
}
Options controlling sample-copy remux (trim window, etc.).
Fields
trim: Optional start/end trim window applied during remux.
Implements: Clone, Debug, Default
pub struct TrimRange {
pub start_ms: u64,
pub end_ms: Option<u64>,
}
Optional media-time trim window in milliseconds (absolute, pre-rebase).
Fields
start_ms: Trim start offset in milliseconds from the beginning of the audio.end_ms: Exclusive end;Nonemeans "through end of media".
Implements: Clone, Copy, Debug, Default, Deserialize<'de>, Serialize
pub struct ChunkMapEntry {
pub first_chunk: u32,
pub samples_per_chunk: u32,
pub sample_description_index: u32,
}
One run from the sample-to-chunk (stsc) table.
Fields
first_chunk: 1-based first chunk index for thisstscentry.samples_per_chunk: Number of samples in each chunk of this run.sample_description_index: 1-based index into the sample description table.
Implements: Clone, Debug
pub struct SampleInfo {
pub offset: u64,
pub size: u32,
pub start_cts: u64,
pub duration: u32,
pub chunk_index: u32,
}
One audio sample, located and timed.
Fields
offset: Absolute file offset of the sample payload.size: Total box size in bytes including the header.start_cts: Composition start time in media timescale ticks.duration: Sample duration in media timescale ticks.chunk_index: 1-based chunk index that contains this sample.
Implements: Clone, Debug
pub enum Mp4Error {
Container(String),
Transform(String),
NoRoom { needed: usize, available: usize },
Io(Error),
}
Errors from MP4 parse, remux, and in-place patch operations.
Variants
Container: The file does not match the shape this crate can read or write.Transform: Acrate::SampleTransformrefused a payload. The crate never produces this itself; it carries the caller's reason out through the remuxer.NoRoom: A rebuiltmoovoutgrew the space reserved for it, so it cannot be swapped in without moving the media. Callers fall back to a rewrite.needed: Bytes required for the rebuiltmoov.available: Bytes currently reserved for in-place swap.
Io: Underlying filesystem or stream I/O failure.
pub fn container(detail: impl Into<String>) -> Self
Shorthand for Mp4Error::Container.
detail- Human-readable error detail.
Updated Self for chaining.
pub fn transform(detail: impl Into<String>) -> Self
Shorthand for Mp4Error::Transform.
detail- Human-readable error detail.
Updated Self for chaining.
Implements: Debug, Display, Error, From<Error>
pub enum SampleEntryKind {
Aavd,
Mp4a,
Enca,
Other(FourCC),
}
Codec or encryption FourCC found in the track's sample description.
Variants
Aavd: Audible Adrm encrypted AAC (aavd).Mp4a: Clear AAC (mp4a).Enca: Common Encryption audio (enca).Other: Opaque error wrapped fromanyhow.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub fn brand_durations_from_chapter_info(info: &Value) -> BrandDurations
Read brand intro/outro durations from chapter_info JSON.
Accepts both snake_case (brand_intro_duration_ms) and camelCase
(brandIntroDurationMs) — Audible's live API uses camelCase.
pub fn brand_trim_range(
brand: BrandDurations,
runtime_length_ms: Option<u64>,
) -> Option<TrimRange>
Build a media trim window that drops Audible branding audio.
Classic Libation: shift the first chapter start by intro_ms and shorten the
last chapter by outro_ms, then remux only the remaining media. We express
the same idea as an absolute [start_ms, end_ms) window on the full file.
When outro_ms > 0 but runtime_length_ms is missing, returns None so we
do not silently leave branding on the tail while trimming only the intro.
Callers should supply runtime (from chapter_info or a media probe) first,
and log when they still get None for a non-empty brand.
pub fn rebase_chapters_after_brand_trim(
chapters: &[(String, u64)],
brand: BrandDurations,
runtime_length_ms: Option<u64>,
) -> Vec<(String, u64)>
Adjust flat chapter start offsets after brand trim so cues/metadata stay aligned.
Drops chapters that fall entirely inside the stripped intro, rebases survivors
so the first kept chapter starts at 0, and shortens the implied end by outro_ms.
pub fn runtime_length_ms_from_chapter_info(info: &Value) -> Option<u64>
Read runtime_length_ms / runtimeLengthMs from chapter_info JSON.
pub fn extract_mp4a_config(mp4: &Mp4File) -> Result<Mp4aConfig>
Read sample-rate / channel count / ASC from a clear mp4a sample entry.
mp4-mp4input for this call.
On success, the inner Mp4aConfig value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
Panics when an internal invariant does not hold.
pub fn parse_mp4(path: &Path) -> Result<Mp4File>
Parses top-level boxes and the primary audio track from an MP4/M4A/M4B file.
path- Filesystem path involved in this operation.
On success, the inner Mp4File value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub fn sample_entry_bytes(mp4: &Mp4File) -> Result<Vec<u8>>
The audio track's whole sample entry box (size, type and body, its
codec configuration box included), as stsd holds it, so another file
can describe the same samples without decoding them.
Returns a container error when the entry does not lie inside moov or
states a size smaller than a box header.
pub fn track_duration_ms(track: &AudioTrack) -> u64
Absolute duration of the audio track in milliseconds.
track-trackinput for this call.
u64 result.
pub fn pad_moov_to(moov: &mut Vec<u8>, total: usize) -> Result<()>
Grow moov to exactly total bytes by appending a free child.
Mp4Error::NoRoom when moov is already longer than total, or when the
gap is too small to express — a free box cannot be shorter than its own
header, so one to seven spare bytes are as unusable as none.
Panics when an internal invariant does not hold.
pub fn read_moov(path: &Path) -> Result<(MoovLocation, Vec<u8>)>
Read a file's moov, and note where it sits.
Only the box headers and moov itself are read, so the cost is the header's
and not the file's.
path- Filesystem path involved in this operation.
The successful result value for this operation.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub fn shift_chunk_offsets(moov: &mut [u8], above: u64, delta: i64) -> Result<()>
Move every chunk offset in moov past above by delta bytes.
Chunk offsets are absolute file positions, so an edit that shifts the media
has to correct them — and an edit that only appeared to shift it, because
the work happened in a scratch file laid out differently, has to correct them
back. Only what sits after the edit moves, which is why above is usually
where moov starts: media in front of the header stays put.
moov-moovinput for this call.above- Numericabovevalue for this call.delta- Numericdeltavalue for this call.
The successful result value for this operation.
Returns an error when the underlying I/O, parse, network, or store operation fails.
Panics when an internal invariant does not hold.
pub fn strip_trailing_free(moov: &mut Vec<u8>) -> Result<bool>
Drop a moov's trailing free child, if it has one.
Anything appended to moov goes after its last child, so the slack has to
come off before an edit and go back on after it. Returns whether one was
there to remove.
moov-moovinput for this call.
On success, the inner bool value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub fn top_level_boxes(file: &mut File) -> Result<Vec<BoxHeader>>
Every box at the top level, in file order.
file- Open file handle.
On success, the inner Vec<BoxHeader> value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub fn write_moov_in_place(path: &Path, at: MoovLocation, moov: &[u8]) -> Result<()>
Write moov back where the old one was, padding it to the same length.
The media does not move, so every chunk offset in the file stays true.
Mp4Error::NoRoom when the rebuilt moov does not fit the space the old
one occupied and cannot simply be appended to.
pub fn remux_progressive(
input: &Path,
output: &Path,
opts: &RemuxOptions,
transform: &mut dyn SampleTransform,
) -> Result<()>
Copy (and optionally trim) a progressive MP4 into a faststart M4B, passing
every payload through transform.
Sample payloads are streamed one buffer at a time. Only the retained sizes, durations, and read offsets are held in memory; the parsed sample table is never cloned.
input- Candidate score input from the public catalog.output- Filesystem path (output).opts- Options struct for this operation.transform-transforminput for this call.
The successful result value for this operation.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub fn write_progressive_m4b<F>(
output: &Path,
input: ProgressiveWriteInput<'_>,
fill_sample: F,
) -> Result<()>
where
F: FnMut(usize, &mut Vec<u8>) -> Result<()>,
Write a progressive faststart M4B by streaming one sample at a time.
Layout is written as ftyp + moov + mdat in a single pass (no full-file
rewrite), and ftyp always declares M4B brands. fill_sample(i, buf) must
populate buf with the payload for sample i (length must match
sample_sizes[i]). Only one sample buffer is live at a time.
Callers that assemble their own sample plan — from fragments, say, rather
than from one progressive mdat — use this directly.
output- Filesystem path (output).input- Candidate score input from the public catalog.fill_sample-fill_sampleinput for this call.
The successful result value for this operation.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub fn build_samples(
stts: &[(u32, u32)],
stsc: &[ChunkMapEntry],
sample_sizes: &[u32],
chunk_offsets: &[u64],
) -> Result<Vec<SampleInfo>>
Builds a flat sample table from stts / stsc / stsz / stco (or co64).
stts- Numericsttsvalue for this call.stsc-stscinput for this call.sample_sizes- Numericsample_sizesvalue for this call.chunk_offsets- Numericchunk_offsetsvalue for this call.
On success, the inner Vec<SampleInfo> value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
Panics when an internal invariant does not hold.
pub fn select_samples_by_ms(
samples: &[SampleInfo],
timescale: u32,
start_ms: u64,
end_ms: Option<u64>,
) -> Vec<usize>
Indices of the samples whose media time overlaps [start_ms, end_ms).
Indices rather than clones: a long audiobook has millions of samples, and the caller needs the original positions anyway to line up any per-sample state it keeps of its own. Output composition times are rebased by the writer.
samples-samplesinput for this call.timescale- Numerictimescalevalue for this call.start_ms- Numericstart_msvalue for this call.end_ms- Numericend_msvalue for this call.
Collected results (may be empty).
pub type Result<T> = Result<T, Mp4Error>;
Result alias for this crate's error type.
pub const RESERVED_MOOV_SLACK: usize = _;
Slack every moov this crate writes carries, as a trailing free child.
A megabyte covers a full tag set, a cover, and a chapter track for a book with several hundred chapters — the things that get added after the media is already on disk. Against the file it protects, which is hundreds of megabytes of audio, it costs about a thousandth; against the alternative, which is rewriting all of that to make room, it costs nothing at all.
Generated from crates/bookclerk-mp4 at main · View as Markdown