---

Atoms, QuickTime Atoms, and Atom Containers

QuickTime makes frequent use of data types known as atoms. You do not normally need to deal with QuickTime at the atomic level. In general, there are higher-level functions that allow you to, for example, create a movie, add or delete a track, or set a track’s media type, without directly manipulating, or necessarily knowing anything about, atoms.

To understand the various ways movies can be delivered over a network, however, it is useful to know how movies are stored in files, and QuickTime movies are stored in files as atoms.

An atom is simply a container; it has a 4-byte length field, which specifies its total size (including the length field), and a 4-byte type field, typically four ASCII characters, which specifies the type of atom it is. The type field can be followed by data, the amount and kind of data depending on the atom type.

The smallest possible atom is therefore 8 bytes: a 4-byte size field and a 4-byte type field, with no data.

One atom can contain other atoms, allowing you to nest them in arbitrary hierarchies. This makes atoms handy building blocks for larger data structures.

You can “insert” one atom into another simply by appending the new atom and adding its size to the size field of the original atom. The original atom has now been extended to “contain” the new atom. If the original atom is inside yet another atom, that atom can be extended in the same manner.

An atom inside another atom is sometimes called a child atom. Child atoms at the same level in a hierarchy are called siblings. An atom that has other atoms inside is called a parent atom or container atom. An atom that has tabular data inside, instead of other atoms, is called a leaf atom.

Because an atom begins with its size, it is easy to “walk” an atom structure by skipping from atom to atom within the structure. You can quickly scan a collection of atoms for an atom of a particular type or skip over an atom you are not interested in.

A QuickTime movie is a parent atom whose type is 'moov'.

Each track in a movie is a child atom of type 'trak' inside a 'moov' atom.

Each track atom contains other child atoms, such as an edit list atom and a media atom. These atoms in turn contain other atoms, such as a media handler atom or various sample table atoms. The sample tables are leaf atoms.

Specific atoms are documented in the QuickTime API Reference, and may also be described conceptually in the documentation of a relevant topic, function, or group of functions. Additional details of the content and structure of various atoms can be found in the QuickTime File Format specification.

A refinement of the basic atom, used for some types of QuickTime data, is the QuickTime atom, or QT atom. This type of atom has additional header fields that specify the version of a particular atom type, an ID that allows you to distinguish one atom of a given type from its siblings in a hierarchy, and other useful information. It also has the restriction of containing either tabular data or other atoms, but never both. (If a QT atom needs to contain data about itself, in addition to containing other atoms, the necessary data is simply wrapped in an atom.)

At the highest level, a hierarchy of QT atoms is stored in an atom container. This is a unique data structure (not an atom) that contains a hierarchy of QT atoms.

Complex data structures, such as compression settings, are commonly stored in atom containers. This allows these data structures to be flexible and extensible, unlike a rigid struct. Properties can be stored as atoms, and it is possible to find out if a particular instance of the structure has a given property, and what data format the property takes, before getting or setting the property. The QT atoms within a container are typically accessed by their byte offsets within the container, which makes data transfer quick and efficient.

---