mp4forge 0.8.0

Rust library and CLI for inspecting, probing, extracting, muxing, and rewriting MP4 structures
Documentation
  • Typed MP4 and ISOBMFF box model with registry-backed custom box support
  • Low-level traversal, extraction, stringify, probe, and writer APIs
  • Thin typed path-based helpers and byte-slice convenience wrappers for common extraction, rewrite, and probe flows
  • Fragmented top-level sidx analysis, planning, and rewrite APIs for supported layouts
  • Feature-gated decryption APIs and a sync-only decrypt CLI for the supported protected MP4 families
  • Built-in CLI for decrypt, divide, dump, edit, extract, mux, probe, and psshdump
  • Shared-fixture coverage for regular MP4, fragmented MP4, encrypted init segments, QuickTime-style metadata cases, and derived real codec fixtures for additional codec-family coverage

Installation

[dependencies]

mp4forge = "0.8.0"

# With optional features:
# mp4forge = { version = "0.8.0", features = ["async"] }
# mp4forge = { version = "0.8.0", features = ["decrypt"] }
# mp4forge = { version = "0.8.0", features = ["decrypt", "async"] }
# mp4forge = { version = "0.8.0", features = ["mux"] }
# mp4forge = { version = "0.8.0", features = ["mux", "async"] }
# mp4forge = { version = "0.8.0", features = ["serde"] }

Install the CLI from crates.io:

cargo install mp4forge --locked

Install the current checkout locally:

cargo install --path . --locked

The published crate includes both the library and the mp4forge binary from src/bin/mp4forge.rs.

Feature Flags

mp4forge keeps the default dependency surface minimal and currently exposes these optional public feature flags:

  • async: enables the additive library-side async I/O surface for seekable readers and writers. This rollout is Tokio-based, expects a Tokio runtime in the caller, targets seekable AsyncRead + AsyncSeek and AsyncWrite + AsyncSeek inputs and outputs, supports normal multithreaded tokio::spawn usage for the supported library paths, and keeps the current CLI on the existing sync path.
  • decrypt: enables the additive decryption input, progress, and support-matrix types that fix the public shape for the decryption surface while keeping the default build unchanged. The landed sync library path covers the Common Encryption family (cenc, cens, cbc1, cbcs), PIFF-triggered compatibility behavior, OMA DCF atom files and protected movie layouts, Marlin IPMP ACBC and ACGK OD-track movies, and the retained IAEC protected-movie path. When combined with async, it also enables the additive file-backed Tokio async decrypt companions, while the CLI remains on the synchronous path.
  • mux: enables the additive mux task surface and the retained low-level helpers underneath it. The library path covers the narrow public MuxRequest model with repeated track specs plus optional segment_duration or fragment_duration, real ftyp/moov/mdat writing for sync callers, additive async real-container writing when combined with async, internal chunk and duration coordination on one mux event graph, the retained low-level seekable and progressive payload assembly helpers, and one-sample-at-a-time seekable or progressive readers. It also enables the sync-only mux CLI route for one output MP4 built from repeated path-first --track inputs.
  • serde: derives Serialize and Deserialize for the reusable public report structs under mp4forge::cli::probe and mp4forge::cli::dump, along with their nested public codec-detail, media-characteristics, FieldValue, and FourCc data. This is intended for library-side report embedding and uses the Rust field names of those public structs; the CLI -format outputs keep their existing hand-authored JSON and YAML schemas.

CLI

USAGE: mp4forge COMMAND [ARGS]

COMMAND:
  decrypt      decrypt a protected MP4 file
  divide       split a fragmented MP4 into track playlists
  dump         display the MP4 box tree
  edit         rewrite selected boxes
  extract      extract raw boxes by type or path
  mux          merge one video track plus audio, text, and subtitle tracks into one MP4
  psshdump     summarize pssh boxes
  probe        summarize an MP4 file

decrypt is available when the crate is built with --features decrypt. The CLI stays sync-only, accepts repeated --key ID:KEY, optional --fragments-info FILE, and optional --show-progress, and reuses the same library decryption surface that backs the feature-gated sync and async APIs.

mux is available when the crate is built with --features mux. The CLI route stays sync-only and accepts repeated --track inputs, one required positional output path, and at most one of --segment_duration or --fragment_duration. The current public --track grammar is path-first: PATH imports one raw source or every supported track from one MP4 source, while PATH#video, PATH#audio, PATH#audio:N, PATH#text, PATH#text:N, and PATH#track:ID select one specific track from a containerized source. The landed path-only auto-detection currently covers MP4, supported AVI audio streams plus H.263/JPEG/PNG/MPEG-4 Part 2/H.264/AVC1 video streams, supported MPEG-PS MPEG audio streams plus LPCM audio plus MPEG-4 Part 2/H.264/H.265/VVC video streams, supported MPEG-TS MPEG audio streams plus AAC LATM/MHAS plus AC-3/E-AC-3/AC-4/DTS/TrueHD audio plus MPEG-2/AV1/AVS3/MPEG-4 Part 2/H.264/H.265/VVC video streams, AAC ADTS, MP3, AC-3, E-AC-3, AC-4, AMR, AMR-WB, QCP voice audio, DTS core audio, AAC LATM, Dolby TrueHD, leading-sync MHAS MPEG-H, IAMF, H.263 elementary video, MPEG-2 elementary video, MPEG-4 Part 2 elementary video, H.264 Annex B, H.265 Annex B, VVC Annex B, raw AV1 OBU, raw AV1 Annex B, IVF-backed AV1, IVF-backed VP8, IVF-backed VP9, JPEG still images, PNG still images, WAVE/AIFF/AIFC PCM, native FLAC, Ogg-backed FLAC, Ogg-backed Opus, Ogg-backed Vorbis, Ogg-backed Speex, Ogg-backed Theora, and CAF-backed ALAC. Broader DTS-family sample-entry variants remain supported through MP4 track import, and the broader demux-backed path-only families continue to move over behind the same public shape. MP4-track merges continue to cover the broader registered sample-entry families because they preserve encoded sample-entry bytes from the source file, and mixed video/audio/text/subtitle jobs retain imported handler names and languages on the real MP4 path. The matching sync and async library entry points use the same MuxRequest surface, while the retained lower-level mux helpers remain available separately when you need staged planning or payload-copy behavior without the task-level request layer. The public mp4forge::mux::sample_reader helpers can also expose stable text or subtitle track identity when you construct them with companion MuxTrackConfig values.

divide currently targets fragmented inputs with up to one video track from AVC, HEVC, Dolby Vision on HEVC, AV1, VP8, or VP9 and one audio track from MP4A-based audio, Opus, AC-3, E-AC-3, AC-4, ALAC, DTS-family entries, FLAC, IAMF, MPEG-H, or PCM, including encrypted wrappers that preserve those original sample-entry formats. Subtitle and text tracks remain unsupported in the current divide output model. Pass -validate when you want the same probe-driven layout checks without creating any output files.

dump defaults to the existing human-readable tree view. Pass -format json or -format yaml for deterministic structured tree export with stable payload_fields for supported boxes; -full and -a still control when large raw or unsupported payloads expand beyond the default summary-oriented view. Add repeatable -path <box/path> filters when you want text or structured output rooted at only the matched parsed subtrees instead of the whole file.

edit keeps the existing global tfdt replacement and -drop behavior, and now also accepts repeatable -path filters when you want -base_media_decode_time to target only matching parsed box paths.

psshdump defaults to the existing human-readable protection summary. Pass -format json or -format yaml for deterministic structured reports with box offsets, system IDs, KIDs, Data bytes, and the legacy raw-box base64 payload. Add repeatable -path <box/path>, -system-id <uuid>, or -kid <uuid> filters when you want text and structured reports to return only the matching protection boxes.

probe defaults to structured JSON output. When the input carries parsed codec-configuration boxes, the report now includes a nested codec_details object per track for families such as AVC, HEVC, AV1, VP8/VP9, MP4A, Opus, AC-3, PCM, XML subtitles, text subtitles, and WebVTT. When sample entries carry btrt, colr, pasp, or fiel, the richer CLI path also emits nested media_characteristics data such as declared bitrate, colorimetry, pixel aspect ratio, and field-order hints. Pass -detail light for a lighter-weight probe that skips per-sample, per-chunk, bitrate, and IDR aggregation, or use mp4forge::probe::ProbeOptions from the library when you need the same control programmatically.

See the examples/ directory for the crate's low-level and high-level API usage patterns, including the feature-gated decrypt example, the feature-gated real-mux and mux/sample-reader examples, and the Tokio-based async library example behind the optional async feature.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in mp4forge by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.