QTAtoms |
This page is based on information obtained from various places at the QuickTime API website http://developer.apple.com/techpubs/quicktime/qtdevdocs/RM/frameset.htm. More details about the QT Atom architecture is available at http://developer.apple.com/techpubs/quicktime/qtdevdocs/REF/refAppD.htm.
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 QF_FindChildByID or QF_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 QF_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.
QT_NewAtomContainer | Creates a new atom container in memory |
QT_FreeAtomContainer | Releases the memory occupied by an atom container |
QT_GetContainerData | Retrieves the data of an atom container |
QT_GetChildrenTypes | Retrieves all children atom types in the child list of the specified parent atom |
QT_CountChildrenOfType | Returns the number of atoms of a given type in the child list of the specified parent atom |
QT_InsertChild | Creates a new child atom for the specified parent atom |
QT_InsertChildren | Inserts a container of atoms as children of the specified parent atom |
QT_FindChildByIndex | Retrieves an atom by type and index from the child list of the specified parent atom |
QT_FindChildByID | Retrieves an atom by type and ID from the child list of the specified parent atom |
QT_RemoveAtom | Removes an atom and its children from the specified atom container |
QT_RemoveChildren | Removes all the children of an atom from the specified atom container |
QT_SetAtomID | Changes the ID of an atom |
QT_GetAtomInfo | Retrieves the type, index and ID of an atom |
QT_SetAtomData | Changes the data of a leaf atom |
QT_GetAtomData | Retrieves the data of a leaf atom |
QT_GetAtomDataSize | Retrieves the data size of a leaf atom |
QT_ReplaceAtom | Replaces the contents of an atom and its children with a different atom and its children |
QT_CopyAtom | Copies an atom and its children to a new atom container |
QT_GetAtomParent | Retrieves the type, index and ID of an atom |