Crate mp4_atom

Expand description

§mp4-atom

This library provides encoding for the ISO Base Media File Format (ISO/IEC 14496-12). It’s meant to be low level, performing encoding/decoding of the binary format without validation or interpretation of the data. You have to know what boxes to expect!

§Atoms

MP4 files are made up of atoms, which are boxes of data. They have an upfront size and a FourCC code to identify the type of box. Examples include Moov, Mdat, Trak, etc.

Unfortunately, the specification is quite complex and often gated behind a paywall. Using this library does require some additional knowledge of the format otherwise you should use a higher level library.

MP4 atoms are often optional and unordered. The simplest way to decode with this library is with Any::decode, returning any supported atom in a giant enum. For encoding you will call encode on the atom directly, ex: [Moov::encode].

§Traits

This library gates functionality behind quite a few traits:

Atom is primarily used for encoding/decoding but also provides Atom::KIND.
Decode and Encode when using byte slices.
ReadFrom and WriteTo when using synchronous IO.
(feature = “tokio”) [AsyncReadFrom] and [AsyncWriteTo] when using asynchronous IO.
Buf and BufMut for encoding/decoding contiguous byte slices.

Additionally, there are some extra traits for decoding atoms given a header. This is useful to avoid decoding large Mdat atoms by first reading the header separately.

DecodeAtom when using byte slices.
ReadAtom when using synchronous IO.
(feature = “tokio”) [AsyncReadAtom] when using asynchronous IO.

There’s no equivalent for encoding because the size of the atom is required upfront.

§Examples

§Decoding/encoding a byte buffer

use std::io::Cursor;
use mp4_atom::{Any, Encode, Decode, Ftyp, Buf};

 // A simple ftyp atom
let mut input = Cursor::new(b"\0\0\0\x14ftypiso6\0\0\x02\0mp41");
let atom = Any::decode(&mut input)?;

// Make sure we got the right atom
assert_eq!(atom, Ftyp {
   major_brand: b"iso6".into(),
   minor_version: 512,
   compatible_brands: vec![b"mp41".into()],
}.into());

// Encode it back
let mut output = Vec::new();
atom.encode(&mut output)?;

assert_eq!(input.get_ref().as_slice(), output.as_slice());

§Synchronous IO

NOTE: reading a Mdat atom will read the entire contents into memory. See the next example to avoid this.

use mp4_atom::{Any, ReadFrom, WriteTo, Ftyp};

let mut reader = std::io::stdin();


let atom = Any::read_from(&mut input)?;

// Make sure we got the right atom
assert_eq!(atom, Ftyp {
   major_brand: b"iso6".into(),
   minor_version: 512,
   compatible_brands: vec![b"mp41".into()],
}.into());

// Encode it back to a Write type
let writer = std::io::stdout();
atom.write_to(&mut writer)?;

§Handling large atoms

To avoid reading large files into memory, you can call Header::read_from manually:

use mp4_atom::{Atom, Any, Header, ReadFrom, ReadAtom, WriteTo, Ftyp, Moov};

let mut reader = std::io::stdin();

let header = Header::read_from(&mut reader)?;
match header.kind {
  Ftyp::KIND => {
    let ftyp = Ftyp::read_atom(&header, &mut reader)?;

     // Make sure we got the right atom
     assert_eq!(ftyp, Ftyp {
       major_brand: b"iso6".into(),
       minor_version: 512,
       compatible_brands: vec![b"mp41".into()],
     });
   },
   Moov::KIND => {
     // Manually decode the moov
     match header.size {
       Some(size) => { /* read size bytes */ },
       None => { /* read until EOF */ },
     };
   },
   _ => {
     // You can also use Any if you prefer
     let any = Any::read_atom(&header, &mut reader)?;
     println!("Unknown atom: {:?}", any);
   }
};

§Asynchronous IO

Enable using the tokio feature. It’s the same as the above two but using [AsyncReadFrom], [AsyncWriteTo], and [AsyncReadAtom] instead.

Modules§

esds

Structs§

Ac3
Ac3SpecificBox
Ainf
AmrSampleEntry
Audio
AuxInfo: Auxiliary information type and parameter shared by saiz and saio, ISO/IEC 14496-12:2022 Sect 8.7.8 / 8.7.9.
Auxc
Av01
Av1c
Avc1
Avcc
AvccExt
Btrt
C2pa: Represents the C2PA box/atom. https://spec.c2pa.org/specifications/specifications/2.4/specs/C2PA_Specification.html#uuid_box
Camm: CameraMotionMetadataSampleEntry (‘camm’), used for camera motion metadata tracks (e.g. gyroscope/accelerometer samples).
Ccst
Chnl
Chpl: Nero-style Chapter List Box (chpl).
ChplEntry: One chapter entry inside a Chpl.
Clap
Cmpd
Co64
Component
Compressor
Copyright: An iTunes-style copyright notice, written by FFmpeg and iTunes for the copyright metadata key.
Covr
Cprt
Cslg
Ctts
CttsEntry
Damr
Desc: An iTunes-style desc (description) metadata item.
Dfla
Dinf
Dops
Dref
Dtyp: Metadata Datatype Definition Atom (‘dtyp’).
Eac3
Ec3IndependentSubstream
Ec3SpecificBox
Edts
Elst
ElstEntry
Emeb: EventMessageEmptyBox (‘emeb’), a sample carried by an Event Message track (the Evte sample entry) to signal that no event is active for the enclosing sample’s duration.
Emib: EventMessageInstanceBox (‘emib’), the sample format used by CMAF/DASH Event Message tracks (the Evte sample entry). Carries the same information as the top-level Emsg box, but as sample content (i.e. inside mdat) rather than a structural box, so it must be decoded explicitly from the sample bytes rather than via Any.
Emsg
Esds
Evte: EventMessageSampleEntry (‘evte’), used by CMAF/DASH “Event Message tracks” to carry timed Emsg boxes as samples instead of inline in fragments.
EvteSample: The content of a single sample in an Event Message track (the Evte sample entry).
ExplicitSpeakerPosition
ExtendedType: A 16-byte code used to identify UUID boxes.
Fiel
FixedPoint
Fl32
Fl64
Flac
FontEntry: Font table for tx3g
FourCC: A four-character code used to identify atoms.
Fpcm
FragmentInfo
Free: Free padding space, will be automatically skipped during parsing. Also see Skip for a similar atom.
Ftab
Ftyp
Hdlr
Header: A atom header, which contains the atom’s kind and size.
Hev1
Hmhd
Hvc1
HvcCArray: One entry of HEVCDecoderConfigurationRecord.arrays: a group of NAL units of a single nal_unit_type (typically VPS, SPS, PPS, or SEI).
Hvcc: HEVCConfigurationBox / HEVCDecoderConfigurationRecord, ISO/IEC 14496-15:2022 Sect 8.3.3.
Idat: ItemDataBox
Iinf: Item information box containing every item entry.
Iloc
Ilst
IlstData: The content of an iTunes-style data atom.
Imir
In24
In32
Ipcm
Ipco
Ipma
Iprp
Iref
Irot
Iscl
Ispe
ItemInfoEntry: Describes one item stored in an iinf item information box.
ItemLocation
ItemLocationExtent
Jpeg: Photo - JPEG (‘jpeg’), QuickTime’s Motion JPEG visual sample entry.
KeyEntry: A single entry in a Metadata Item Keys Box (‘keys’).
Keyd: Metadata Key Declaration Box (‘keyd’).
Keys: Metadata Item Keys Box (‘keys’).
Kind
Lhvc
Loca: Metadata Locale Box (‘loca’).
Lpcm
Matrix
Mdat: A media data atom.
Mdhd
Mdia
Mebx: BoxedMetadataSampleEntry (‘mebx’), used for multiplexed/“boxed” timed metadata tracks (e.g. per-sample GPS or camera metadata with multiple typed keys sharing a single track).
MebxItem: One item in a MebxSample: a value box whose type is a local_key_id declared in the corresponding Mebx sample entry’s keys table.
MebxKey: A Metadata Key Box: one local-key declaration inside a Mebx sample entry’s keys table (MetadataKeyTableBox).
MebxSample: The content of a single sample in a mebx (multiplexed/“boxed” timed metadata) track (the Mebx sample entry): a concatenation of one or more value boxes, one per declared key present at this sample’s time.
Mehd
Meta
MetaData: MetaDataSampleEntry base fields.
Mett: TextMetaDataSampleEntry (‘mett’), used for text-based timed metadata tracks.
Metx: XMLMetaDataSampleEntry (‘metx’), used for XML-based timed metadata tracks.
Mfhd
Mfra: MovieFragmentRandomAccessBox (mfra).
Mfro: MovieFragmentRandomAccessOffsetBox (mfro).
Minf
Moof
Moov
Mp3: MPEG-1/2 Audio Layer III (MP3) sample entry, as used by QuickTime and other tools that store MP3 directly rather than wrapping it in mp4a/esds.
Mp4a
Mvex
Mvhd
Name
Nmhd
Opus
Pasp
Pcm
PcmC
PcmFormat: The resolved sample format of a PCM sample entry.
Pitm
Pixi
PlainText: Plain text sample entry.
Prft
PropertyAssociation
PropertyAssociations
Ratio: Represents the ratio between two numbers.
Reference
RgbColor
RgbaColor
Rref
Rtng
S16l
Saio: SampleAuxiliaryInformationOffsetsBox, ISO/IEC 14496-12:2022 Sect 8.7.9
Saiz: Sample AuxiliaryInformationSizesBox, ISO/IEC 14496-12:2022 Sect 8.7.8
Samr
Sbgp: SampleToGroupBox, ISO/IEC 14496-12:2024 Sect 8.9.2
SbgpEntry
SchemeIdEntry: A single scheme entry in a Silb box.
SegmentReference
Senc
Setu: Metadata Setup Box (‘setu’).
Sgpd: SampleGroupDescriptionBox, ISO/IEC 14496-12:2024 Sect 8.9.3
SgpdEntry
Sidx
Silb: SchemeIdListBox (‘silb’), an optional child of Evte declaring the event schemes that may appear in the track.
Skip: Free padding space, will be automatically skipped during parsing. Also see Free for a similar atom.
Smhd
Sowt
Stbl
Stco
Sthd
Stsc
StscEntry
Stsd
Stss
Stsz: Sample Size Box (stsz)
Stts
SttsEntry
Styp
Subs: SubSampleInformationBox, ISO/IEC 14496-12:2024 Sect 8.7.7
SubsEntry
SubsSubsample
Taic
Tfdt
Tfhd
Tfra
Tkhd
Tool
TrackReferenceTypeBox: Track reference type box.
Traf
Trak
Tref: Track reference box
Trex
Trun
TrunEntry: A single sample entry in a trun box.
Twos
Tx3g: Text track sample description format for tx3g
TxtC: TextConfigBox (‘txtC’), configuration for a TextMetaDataSampleEntry (‘mett’).///
Udta
UncompressedComponent
Uncv
Uri: URIBox (’uri ’), the URI identifying the metadata scheme for a URIMetaSampleEntry (‘urim’).
UriI: URIInitBox (‘uriI’), optional initialization data for a URIMetaSampleEntry (‘urim’).
Urim: URIMetaSampleEntry (‘urim’), used for URI-based timed metadata tracks.
Url
Visual
Vlab
Vmhd
Vp08
Vp09
VpcC
VttC
Wvtt
Year
Zeroed
u24
u48

Enums§

Any: Any of the supported atoms.
AnySampleGroupEntry
AudioChannelPosition: ISO/IEC 23091-3 Audio Channel Position
ChannelStructure
ClockType
Codec: Called a “sample entry” in the ISOBMFF specification.
Colr
DataType: The value type declared by a Dtyp atom.
EmsgTimestamp
Error
FlacMetadataBlock
IlstDataValue: A IlstData value, interpreted according to its wire-level type indicator.
ReferenceTime
SencBoxVersion
SpeakerPosition
StszSamples
SubsSubsampleSize
UncC
Uuid

Traits§

AnyAtom: A trait to help casting to/from Any. From/TryFrom use concrete types, but if we want to use generics, then we need a trait.
Atom: A helper to encode/decode a known atom type.
Buf: A contiguous buffer of bytes.
BufMut: A mutable contiguous buffer of bytes.
Decode: Decode a type from a buffer.
DecodeAtom: Decode an atom using the provided header
DecodeMaybe: Decode a type from a buffer if we have enough data.
Encode: Encode a type to a buffer.
MetaAtom: A trait to signify that this is a common meta atom.
ReadAtom: Read an atom from a reader provided the header.
ReadFrom: Read a type from a reader.
ReadUntil: Keep discarding atoms until the desired atom is found.
ToBytes
UuidAtom
WriteTo: Write a type to a writer.

Type Aliases§

Result

Crate mp4_atom

Crate mp4_atom Copy item path

§mp4-atom

§Atoms

§Traits

§Examples

§Decoding/encoding a byte buffer

§Synchronous IO

§Handling large atoms

§Asynchronous IO

Modules§

Structs§

Enums§

Traits§

Type Aliases§

Crate mp4_atom