repository·master·Indexed 19 days ago
https://github.com/mozilla/mp4parse-rustA high-performance Rust implementation of an ISO base media file format (mp4) parser used by Firefox. The project consists of the core Rust parser (mp4parse) and a C API wrapper (mp4parse-capi) for cross-language compatibility. It allows for the extraction of track metadata, audio and video sample information, AVIF image data, and PSSH info for EME playback.
mp4parse-rust is an MP4 track metadata parser. Its primary goal is to provide a pure-Rust implementation of the ISO base media file format (mp4) parser used by Firefox. The project is split into two main components:
mp4parse: The core parser written in Rust.mp4parse-capi: A C API that wraps the Rust parser, allowing its functionality to be consumed by non-Rust environments.mp4parse is a Rust-based parser designed for the ISO base media file format (MP4). It is used to extract metadata from MP4 files.mp4parse-capi provides a C interface to the mp4parse Rust library, allowing developers to parse ISO base media file format (mp4) metadata from C, C++, or other languages that can interface with C ABIs.
For general information about the underlying parser, its capabilities, and the project structure, refer to the main mp4parse-rust repository documentation.
mp4parse-capi package includes example programs located in mp4parse_capi/examples. Note that these examples are not automatically executed by cargo test; they must be built and run manually to verify that changes have not broken the C API usage.You can run the conventional tests for both the Rust core (mp4parse) and the C API (mp4parse-capi) using the standard Cargo test command. Tests are located in the respective src/lib.rs files and the tests/ directories of each package.
cargo testThe CheckedInteger<T> is a zero-overhead wrapper around integer types used to enforce checked arithmetic throughout the parser. It ensures that operations like addition and subtraction do not silently overflow, which is critical when handling large file offsets or timestamps.
Key behaviors:
Option<Self>, where None indicates an overflow or underflow.CheckedInteger<u64> allows subtracting a larger u64 from a smaller one, returning a CheckedInteger<i64> to represent negative results (useful for calculating relative time offsets).From<T> to wrap values and From<CheckedInteger<i64>> for i64 to unwrap them.Error::InvalidData is returned, it contains a Status value. Status provides specific reasons for why the data was considered invalid, often referencing specific ISO/IEC specifications (e.g., ColrBadQuantity for incorrect colour information or IlocNotFound for missing item locations). This is particularly useful for debugging malformed MP4/HEIF files.The parser can extract metadata from an MP4 file by parsing the meta box (as defined in ISOBMFF § 8.11.1). This includes parsing ilst (iTunes metadata list) entries and, if the meta-xml feature is enabled, XML or Binary XML boxes.
Metadata fields extracted include:
album, artist, album_artist, comment, title, composer, encoder, encoded_by, copyright, grouping, category, keyword, podcast_url, podcast_guid, description, long_description, lyrics, tv_network_name, tvepisode_name, tv_show_name, purchase_date, owner, sort_name, sort_artist, sort_album, sort_album_artist, sort_composer.year, track_number, total_tracks, disc_number, total_discs, beats_per_minute, tv_season, tv_episode_number.hd_video, compilation, advisory (AdvisoryRating), media_type (MediaType), podcast, gapless_playback, genre (Genre).cover_art.The ParseStrictness enum controls how the parser handles irregularities in the MP4 stream:
track_id values are found, it will return Err(Error::from(Status::Invalid)).track_id values are found, it will issue a warning and use the first occurrence instead of failing.You can iterate through the boxes within an MP4 file using BoxIter. By calling next_box() on a BoxIter instance, you receive an Option<BMFFBox>. If the result is Some(box), you can access the box's header via get_header() or read its content. If the result is None, you have reached the end of the stream or the end of the current box sequence.
let mut iter = BoxIter::new(&mut src);
while let Some(mut b) = iter.next_box()? {
let header = b.get_header();
// Process box...
}The ParseStrictness enum controls how strictly the parser adheres to the ISO specifications. This is useful when dealing with non-compliant or ambiguous media files.
Variants:
Permissive: Only errors on ambiguous inputs.Normal (Default): Errors on 'shall' directives in the spec and logs warnings for 'should' directives.Strict: Errors on both 'shall' and 'should' directives.In MP4/HEIF streams, an alpha channel is often represented as an auxiliary item. You can identify if an item is an alpha channel by checking its AuxiliaryType property for the specific URN: urn:mpeg:mpegB:cicp:systems:auxiliary:alpha.
While the is_alpha method is internal to the ItemPropertiesBox implementation in this segment, the logic relies on matching the ItemProperty::AuxiliaryType variant containing the correct aux_type string.