This page is based on information obtained from various places at the QuickTime API website. More details about the QT Atom architecture are available here.
QuickTime stores most of its data using specialized structures, called QT Atoms. The QT atom architecture is a simple, yet powerful, way to construct arbitrarily complex hierarchical data structures.
Each QT Atom carries its own size and type information, as well as its data. There are several advantages to using QT atoms for holding and passing information:
QT Atoms are stored in QT Atom Containers. You can think of a newly-created QT atom container as the root of a tree structure that contains no children.
A QT atom container contains QT atoms (Figure 1). Each QT atom contains either data or other atoms.
You can use the QT atoms API (part of the Movie Toolbox) to search through QT atom hierarchies until you get to leaf atoms, then read the leaf atom's data from its various fields.
![]() |
Each atom has an offset that describes its position within the container. In addition, each QT atom has a type and an ID. The atom type describes the kind of information the atom represents. For example, movie atoms are type 'moov' , while the track atoms inside them are type 'trak'. The atom ID is used to differentiate child atoms of the same type with the same parent; an atom's ID must be unique for a given parent and type. In addition to the atom ID, each atom has a 1-based index that describes its order relative to other child atoms of the same type and parent. You can uniquely identify a QT atom in three ways:
You can store and retrieve atoms in a QT atom container by index, ID, or both. For example:
You can also create, store, and retrieve atoms using both ID and index to create an arbitrarily complex, extensible data structure.
Warning: Since QT atoms are offsets into a data structure, they can be changed during editing operations on QT atom containers, such as inserting or deleting atoms. For a given atom, editing child atoms is safe, but editing sibling or parent atoms invalidates that atom's offset.
Note: For cross-platform purposes, all data in a QT atom is expected to be in big-endian format.
Parsing the QT atom container
As a developer, you do not need to parse the QT atom container format yourself. Instead, you can use the QT atom functions to:
Most QT atom functions take two parameters to specify a particular atom: the atom container that contains the atom and the offset of the atom in the atom container data structure. You obtain an atom's offset by calling either QT_FindChildByID or QT_FindChildByIndex.
When calling any QT atom function for which you specify a parent atom as a parameter, you can pass 0 as an atom offset to indicate that the specified parent atom is the atom container itself. For example, you would call the QT_FindChildByIndex command and pass 0 for the parent atom parameter to indicate that the requested child atom is a child of the atom container itself.