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
Avc3: An H.264 sample entry like Avc1, except parameter sets may also be in-band in the samples.
Avcc
AvccExt
Blin: Stereo Camera System Baseline: the distance between the lens centres, in micrometres.
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).
Cams: Stereo Camera System. A reader may refuse a cams that holds anything besides a single blin, so a writer leaves must and unknown empty and does not write an empty cams.
Cbmp: Cubemap Projection, Spherical Video V2.
Ccst
Chnl
Chpl: Nero-style Chapter List Box (chpl).
ChplEntry: One chapter entry inside a Chpl.
Clap
Cmfy: Stereo Comfort. A reader may refuse a cmfy that holds anything besides a single dadj, so a writer leaves must and unknown empty and does not write an empty cmfy.
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
Dadj: Stereo Comfort Disparity Adjustment, in 1/10000 of the width of one eye’s view (-10000 to 10000). Half of it is added to the left eye and half subtracted from the right.
Damr
Desc: An iTunes-style desc (description) metadata item.
Dfla
Dinf
Disp: DisparityBox (‘disp’): the stereo disparity shift of timed text. In a sample entry it is the default, in a sample it overrides the default.
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
Equi: Equirectangular Projection, Spherical Video V2. The bounds are 0.32 fixed-point fractions of the projection, measured from each edge, that the frame does not cover; all zero for a full 360° frame.
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.
Eyes: Stereo View Box. The spec requires stri; it is optional here, as a parser does not validate, but a writer sets it.
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.
Hero: Hero Stereo Eye Description: the eye to show in 2D. Values of 3 and above are reserved, and readers treat them as no hero eye.
Hev1
Hfov: Horizontal Field of View Box, from Apple’s QuickTime and ISO Base Media File Formats and Spatial and Immersive Media, in units of 1/1000 degree. A sibling of vexu in the sample entry.
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
Mshp: Mesh Projection, Spherical Video V2. data holds the mesh boxes and any boxes after them, compressed with raw DEFLATE (RFC 1951, no zlib or gzip header) when encoding_four_cc is dfl8, or as-is when it is raw . crc is the CRC-32 of every byte after it.
Must: Required Box Types Box: the types of sibling boxes a reader must understand to use the parent box. Zero entries are reserved.
Mvex
Mvhd
Name
Nmhd
Opus
OpusChannelMapping: A nonzero channel mapping family and its table, laid out as RFC 7845 §5.1.1 describes.
Pack: View Packing.
Pasp
Pcm
PcmC
PcmFormat: The resolved sample format of a PCM sample entry.
Pitm
Pixi
Pkin: View Packing Information. A view_packing_kind of zero is a placeholder for a packing set later.
PlainText: Plain text sample entry.
Prft
Prhd: Projection Header, Spherical Video V2: the pose, in 16.16 fixed-point degrees.
Prji: Projection Information.
Proj: Projection Box, Spherical Video V2.
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
Spatial: The projection and stereo boxes of a visual sample entry. Entries hold it as spatial: Option<Box<Spatial>>, since it is large and usually absent.
St3d: Stereoscopic 3D Video Box, Spherical Video V2.
Stbl
Stco
Sthd
Stri: Stereo View Information. Readers must treat a box with non-zero reserved bits as invalid, so such a box does not decode and is kept verbatim.
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
Sv3d: Spherical Video Box, Spherical Video V2.
Svhd: Spherical Video Header, Spherical Video V2.
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
Urn: A name-based data reference and its location.
Vexu: Video Extended Usage Box, from Apple’s QuickTime and ISO Base Media File Formats and Spatial and Immersive Media. The same document defines its children below, and the sibling Hfov.
VexuProj: The Projection Box inside vexu: the projection kind, and optionally the box for that kind. A writer sets prji: a reader may refuse a proj without one.
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.
DrefEntry: An entry in a data reference box.
EmsgTimestamp
Error
FlacMetadataBlock
IlstDataValue: A IlstData value, interpreted according to its wire-level type indicator.
ProjKind
ReferenceTime
SencBoxVersion
SpeakerPosition
StszSamples
SubsSubsampleSize
TrunSamples: The samples of a trun box.
TrunSamplesIter: An iterator over the entries of TrunSamples.
UncC
Uuid
VexuProjKind: The box for a projection kind, a sibling of prji whose type matches its projection_kind. None of these boxes defines any fields yet.

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