mp4box/
lib.rs

1//! # mp4box
2//!
3//! A minimal, dependency-light MP4/ISOBMFF parser and editor for Rust.
4//!
5//! This crate parses the MP4 box tree (including 64-bit "large" boxes, UUID
6//! boxes, and the codec configuration inside `stsd` sample entries), decodes
7//! known box types into typed structures, extracts per-sample tables from
8//! progressive and fragmented (fMP4/DASH/CMAF) files, and performs
9//! non-destructive box editing with automatic size and chunk-offset fixup.
10//!
11//! ## Features
12//! - Core parser with only `anyhow` + `serde` as dependencies, working with
13//!   any `Read + Seek` source
14//! - Typed structured decoding ([`registry::StructuredData`]) for headers,
15//!   sample tables, fragments, DRM boxes (`pssh`/`tenc`), and codec
16//!   configuration (`esds` AudioSpecificConfig, `avcC`, `hvcC`, ...)
17//! - Per-sample tables ([`track_samples_from_path`]) for progressive and
18//!   fragmented files: DTS/PTS, sizes, offsets, keyframes
19//! - Tolerant parsing ([`get_boxes_tolerant`]): partial tree plus located
20//!   issues instead of an error on damaged files
21//! - Non-destructive editing (`edit` feature, [`edit::Editor`]): remove /
22//!   insert / replace boxes, patch fields, set tags, faststart
23//! - iTunes metadata reading ([`get_itunes_tags`]) and writing
24//! - JSON-serializable output perfect for web UIs and APIs
25//! - Command-line tools (`cli` feature): `mp4dump`, `mp4info`,
26//!   `mp4samples`, `mp4edit`
27//!
28//! ## Use Cases
29//! - CLIs for inspecting MP4 structure (e.g. `mp4dump`)
30//! - Tauri/Electron desktop apps that need JSON output for UI
31//! - Backend services that need to inspect or validate MP4 files
32//! - Media processing tools and debugging utilities
33//!
34//! # Quick start
35//!
36//! ```no_run
37//! use mp4box::get_boxes;
38//! use std::fs::File;
39//!
40//! fn main() -> anyhow::Result<()> {
41//!     let mut file = File::open("video.mp4")?;
42//!     let size = file.metadata()?.len();
43//!     
44//!     // Parse structure only
45//!     let boxes = get_boxes(&mut file, size, false)?;
46//!     println!("Found {} top-level boxes", boxes.len());
47//!     
48//!     // Parse with decoding of known box types
49//!     let mut file = File::open("video.mp4")?;
50//!     let decoded_boxes = get_boxes(&mut file, size, true)?;
51//!     
52//!     // Print file type info
53//!     if let Some(ftyp) = decoded_boxes.iter().find(|b| b.typ == "ftyp") {
54//!         println!("File type: {}",
55//!             ftyp.decoded.as_deref().unwrap_or("unknown"));
56//!     }
57//!     
58//!     Ok(())
59//! }
60//! ```
61//!
62//! ## Lower-level parsing
63//!
64//! For more control, you can use the lower-level parser functions:
65//!
66//! ```no_run
67//! use mp4box::parser::{read_box_header, parse_children};
68//! use mp4box::known_boxes::KnownBox;
69//! use std::fs::File;
70//! use std::io::{Seek, SeekFrom};
71//!
72//! fn main() -> anyhow::Result<()> {
73//!     let mut file = File::open("video.mp4")?;
74//!     let file_len = file.metadata()?.len();
75//!     
76//!     while file.stream_position()? < file_len {
77//!         let header = read_box_header(&mut file)?;
78//!         let known = KnownBox::from(header.typ);
79//!         println!("Box: {} ({}) at offset {:#x}",
80//!             header.typ, known.full_name(), header.start);
81//!             
82//!         let end = if header.size == 0 { file_len } else { header.start + header.size };
83//!         file.seek(SeekFrom::Start(end))?;
84//!     }
85//!     Ok(())
86//! }
87//! ```
88//!
89//! For more examples, see the `mp4dump` and `mp4info` binaries in this repository.
90
91pub mod api;
92pub mod boxes;
93pub mod drm;
94#[cfg(feature = "edit")]
95pub mod edit;
96pub mod known_boxes;
97pub mod parser;
98pub mod registry;
99pub mod samples;
100pub mod util;
101
102pub use boxes::{BoxHeader, BoxKey, BoxRef, FourCC, NodeKind};
103pub use parser::{
104    MAX_BOX_DEPTH, ParseIssue, parse_boxes, parse_boxes_tolerant, parse_children, read_box_header,
105};
106pub use registry::{
107    BoxValue, Co64Data, CttsData, CttsEntry, HdlrData, MdhdData, Registry, SampleEntry, StcoData,
108    StructuredData, StscData, StscEntry, StsdData, StssData, StszData, SttsData, SttsEntry,
109    default_registry,
110};
111
112// High-level API
113pub use api::{
114    Box, HexDump, get_boxes, get_boxes_tolerant, get_boxes_with_registry, get_itunes_tags,
115    hex_range,
116};
117pub use samples::{SampleInfo, TrackSamples, track_samples_from_path, track_samples_from_reader};
mp4box/lib.rs

mp4box/
lib.rs
