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§
Structs§
- Av01
- Av1c
- Avc1
- Avcc
- AvccExt
- Co64
- Compressor
- Covr
- Ctts
- Ctts
Entry - Desc
- Dinf
- Dref
- Edts
- Elst
- Elst
Entry - Emsg
- Esds
- Fixed
Point - FourCC
- A four-character code used to identify atoms.
- Free
- Ftyp
- Hdlr
- Header
- A atom header, which contains the atom’s kind and size.
- Hev1
- Hvc1
- HvcC
Array - Hvcc
- Ilst
- Matrix
- Mdat
- A media data atom.
- Mdhd
- Mdia
- Mehd
- Mfhd
- Minf
- Moof
- Moov
- Mp4a
- Mvex
- Mvhd
- Name
- Ratio
- Represents the ratio between two numbers.
- RgbColor
- Rgba
Color - Skip
- Smhd
- Stbl
- Stco
- Stsc
- Stsc
Entry - Stsd
- Stss
- Stsz
- Sample Size Box (stsz)
- Stts
- Stts
Entry - Styp
- Tfdt
- Tfhd
- Tkhd
- Traf
- Trak
- Trex
- Trun
- Trun
Entry - Tx3g
- Udta
- Url
- Visual
- Vmhd
- Vp08
- Vp09
- VpcC
- Year
- Zeroed
- u24
- u48
Enums§
- Any
- Any of the supported atoms.
- Codec
- Called a “sample entry” in the ISOBMFF specification.
- Emsg
Timestamp - Error
- Meta
- Stsz
Samples
Traits§
- 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.
- Decode
Atom - Decode an atom using the provided header
- Decode
Maybe - Decode a type from a buffer if we have enough data.
- Encode
- Encode a type to a buffer.
- Read
Atom - Read an atom from a reader provided the header.
- Read
From - Read a type from a reader.
- Read
Until - Keep discarding atoms until the desired atom is found.
- WriteTo
- Write a type to a writer.