QuickTime File Format Specification: Track Atoms

< Previous PageNext Page >

Hide TOC

Track Atoms

Track atoms define a single track of a movie. A movie may consist of one or more tracks. Each track is independent of the other tracks in the movie and carries its own temporal and spatial information. Each track atom contains its associated media atom.

Tracks are used specifically for the following purposes:

To contain media data references and descriptions (media tracks).
To contain modifier tracks (tweens, and so forth).
To contain packetization information for streaming protocols (hint tracks). Hint tracks may contain references to media sample data or copies of media sample data. For more information about hint tracks, refer to “Hint Media.”

Note that a QuickTime movie cannot consist solely of hint tracks or modifier tracks; there must be at least one media track. Furthermore, media tracks cannot be deleted from a hinted movie, even if the hint tracks contain copies of the media sample data—in addition to the hint tracks, the entire unhinted movie must remain.

Figure 2-6 shows the layout of a track atom. Track atoms have an atom type value of 'trak'. The track atom requires a track header atom ('tkhd') and a media atom ('mdia'). Other child atoms are optional, and may include a track profile atom ('prfl'), a track clipping atom ('clip'), a track matte atom ('matt'), an edit atom ('edts'), a track reference atom ('tref'), a track load settings atom ('load'), a track input map atom ('imap'), and a user data atom ('udta').

Figure 2-6 The layout of a track atom

Track atoms contain the following data elements.

Size: A 32-bit integer that specifies the number of bytes in this track atom.
Type: A 32-bit integer that identifies the atom type; this field must be set to 'trak'.
Track profile atom: See “Track Profile Atom” for details.
Track header atom: See “Track Header Atoms” for details.
Clipping atom: See “Clipping Atoms” for more information.
Track matte atom: See “Track Matte Atoms” for more information.
Edit atom: See “Edit Atoms” for details.
Track reference atom: See “Track Reference Atoms”” for details.
Track load settings atom: See “Track Load Settings Atoms” for details.
Track input map atom: See “Track Input Map Atoms”” for details.
Media atom: See “Media Atoms” for details.
User-defined data atom: See “User Data Atoms” for more information.

Track Profile Atom

Profile atoms can be children of movie atoms or track atoms. For details on profile atoms, see “The Movie Profile Atom.”

Track Header Atoms

The track header atom specifies the characteristics of a single track within a movie. A track header atom contains a size field that specifies the number of bytes and a type field that indicates the format of the data (defined by the atom type 'tkhd').

Figure 2-7 shows the structure of the track header atom.

Figure 2-7 The layout of a track header atom

The track header atom contains the track characteristics for the track, including temporal, spatial, and volume information.

Track header atoms contain the following data elements.

Size

A 32-bit integer that specifies the number of bytes in this track header atom.

Type

A 32-bit integer that identifies the atom type; this field must be set to 'tkhd'.

Version

A 1-byte specification of the version of this track header.

Flags

Three bytes that are reserved for the track header flags. These flags indicate how the track is used in the movie. The following flags are valid (all flags are enabled when set to 1).

Track enabled

Indicates that the track is enabled. Flag value is 0x0001.

Track in movie

Indicates that the track is used in the movie. Flag value is 0x0002.

Track in preview

Indicates that the track is used in the movie’s preview. Flag value is 0x0004.

Track in poster

Indicates that the track is used in the movie’s poster. Flag value is 0x0008.

Creation time

A 32-bit integer that indicates the calendar date and time (expressed in seconds since midnight, January 1, 1904) when the track header was created. It is strongly recommended that this value should be specified using coordinated universal time (UTC).

Modification time

A 32-bit integer that indicates the calendar date and time (expressed in seconds since midnight, January 1, 1904) when the track header was changed. It is strongly recommended that this value should be specified using coordinated universal time (UTC).

Track ID

A 32-bit integer that uniquely identifies the track. The value 0 cannot be used.

Reserved

A 32-bit integer that is reserved for use by Apple. Set this field to 0.

Duration

A time value that indicates the duration of this track (in the movie’s time coordinate system). Note that this property is derived from the track’s edits. The value of this field is equal to the sum of the durations of all of the track’s edits. If there is no edit list, then the duration is the sum of the sample durations, converted into the movie timescale.

Reserved

An 8-byte value that is reserved for use by Apple. Set this field to 0.

Layer

A 16-bit integer that indicates this track’s spatial priority in its movie. The QuickTime Movie Toolbox uses this value to determine how tracks overlay one another. Tracks with lower layer values are displayed in front of tracks with higher layer values.

Alternate group

A 16-bit integer that specifies a collection of movie tracks that contain alternate data for one another. QuickTime chooses one track from the group to be used when the movie is played. The choice may be based on such considerations as playback quality, language, or the capabilities of the computer.

Volume

A 16-bit fixed-point value that indicates how loudly this track’s sound is to be played. A value of 1.0 indicates normal volume.

Reserved

A 16-bit integer that is reserved for use by Apple. Set this field to 0.

Matrix structure

The matrix structure associated with this track. See Figure 2-8 for an illustration of a matrix structure.

Track width

A 32-bit fixed-point number that specifies the width of this track in pixels.

Track height

A 32-bit fixed-point number that indicates the height of this track in pixels.

Clipping Atoms

Clipping atoms specify the clipping regions for movies and for tracks. The clipping atom has an atom type value of 'clip'.

Figure 2-8 shows the layout of a clipping atom.

Figure 2-8 The layout of a clipping atom

Clipping atoms contain the following data elements.

Size: A 32-bit integer that specifies the number of bytes in this clipping atom.
Type: A 32-bit integer that identifies the atom type; this field must be set to 'clip'.
Clipping region atom: See “Clipping Region Atoms.”

Clipping Region Atoms

The clipping region atom contains the data that specifies the clipping region, including its size, bounding box, and region. Clipping region atoms have an atom type value of 'crgn'.

The layout of the clipping region atom is shown in Figure 2-8.

Clipping region atoms contain the following data elements.

Size: A 32-bit integer that specifies the number of bytes in this clipping region atom.
Type: A 32-bit integer that identifies the atom type; this field must be set to 'crgn'.
Region size: The region size, region boundary box, and clipping region data fields constitute a QuickDraw region.
Region boundary box: The region size, region boundary box, and clipping region data fields constitute a QuickDraw region.
Clipping region data: The region size, region boundary box, and clipping region data fields constitute a QuickDraw region.

Track Matte Atoms

Track matte atoms are used to visually blend the track’s image when it is displayed.

Track matte atoms have an atom type value of 'matt'.

Figure 2-9 shows the layout of track matte atoms.

Figure 2-9 The layout of a track matte atom

Track matte atoms contain the following data elements.

Size

A 32-bit integer that specifies the number of bytes in this track matte atom.

Type

A 32-bit integer that identifies the atom type; this field must be set to 'matt'.

Compressed matte atom

The actual matte data.

See “Compressed Matte Atoms” for details.

Compressed Matte Atoms

The compressed matte atom specifies the image description structure and the matte data associated with a particular matte atom. Compressed matte atoms have an atom type value of 'kmat'.

The layout of the compressed matte atom is shown in Figure 2-9.

Compressed matte atoms contain the following data elements.

Size: A 32-bit integer that specifies the number of bytes in this compressed matte atom.
Type: A 32-bit integer that identifies the atom type; this field must be set to 'kmat'.
Version: A 1-byte specification of the version of this compressed matte atom.
Flags: Three bytes of space for flags. Set this field to 0.
Matte image description structure: An image description structure associated with this matte data. The image description contains detailed information that governs how the matte data is used. See “Video Sample Description” for more information about image descriptions.
Matte data: The compressed matte data, which is of variable length.

Edit Atoms

You use edit atoms to define the portions of the media that are to be used to build up a track for a movie. The edits themselves are contained in an edit list table, which consists of time offset and duration values for each segment. Edit atoms have an atom type value of 'edts'.

Figure 2-10 shows the layout of an edit atom.

In the absence of an edit list, the presentation of a track starts immediately. An empty edit is used to offset the start time of a track.

Note: If the edit atom or the edit list atom is missing, you can assume that the entire media is used by the track.

Figure 2-10 The layout of an edit atom

Edit atoms contain the following data elements.

Size: A 32-bit integer that specifies the number of bytes in this edit atom.
Type: A 32-bit integer that identifies the atom type; this field must be set to 'edts'.
Edit list atom: See “Edit List Atoms.”

Edit List Atoms

You use the edit list atom, also shown in Figure 2-10, to map from a time in a movie to a time in a media, and ultimately to media data. This information is in the form of entries in an edit list table, shown in Figure 2-11. Edit list atoms have an atom type value of 'elst'.

Edit list atoms contain the following data elements.

Size: A 32-bit integer that specifies the number of bytes in this edit list atom.
Type: A 32-bit integer that identifies the atom type; this field must be set to 'elst'.
Version: A 1-byte specification of the version of this edit list atom.
Flags: Three bytes of space for flags. Set this field to 0.
Number of entries: A 32-bit integer that specifies the number of entries in the edit list atom that follows.
Edit list table: An array of 32-bit values, grouped into entries containing 3 values each. Figure 2-11 shows the layout of the entries in this table.

Figure 2-11 The layout of an edit list table entry

An edit list table entry contains the following elements.

Track duration: A 32-bit integer that specifies the duration of this edit segment in units of the movie’s time scale.
Media time: A 32-bit integer containing the starting time within the media of this edit segment (in media timescale units). If this field is set to –1, it is an empty edit. The last edit in a track should never be an empty edit. Any difference between the movie’s duration and the track’s duration is expressed as an implicit empty edit.
Media rate: A 32-bit fixed-point number that specifies the relative rate at which to play the media corresponding to this edit segment. This rate value cannot be 0 or negative.

Track Load Settings Atoms

Track load settings atoms contain information that indicates how the track is to be used in its movie. Applications that read QuickTime files can use this information to process the movie data more efficiently. Track load settings atoms have an atom type value of 'load'.

Figure 2-12 The layout of a track load settings atom

Track load settings atoms contain the following data elements.

Size

A 32-bit integer that specifies the number of bytes in this track load settings atom.

Type

A 32-bit integer that identifies the atom type; this field must be set to 'load'.

Preload start time

A 32-bit integer specifying the starting time, in the movie’s time coordinate system, of a segment of the track that is to be preloaded. Used in conjunction with the preload duration.

Preload duration

A 32-bit integer specifying the duration, in the movie’s time coordinate system, of a segment of the track that is to be preloaded. If the duration is set to –1, it means that the preload segment extends from the preload start time to the end of the track. All media data in the segment of the track defined by the preload start time and preload duration values should be loaded into memory when the movie is to be played.

Preload flags

A 32-bit integer containing flags governing the preload operation. Only two flags are defined, and they are mutually exclusive. If preload flags is set to 1, the track is to be preloaded regardless of whether it is enabled. If preload flags is set to 2, the track is to be preloaded only if it is enabled.

Default hints

A 32-bit integer containing playback hints. More than one flag may be enabled. Flags are enabled by setting them to 1. The following flags are defined.

Double buffer

This flag indicates that the track should be played using double-buffered I/O. This flag’s value is 0x0020.

High quality

This flag indicates that the track should be displayed at highest possible quality, without regard to real-time performance considerations. This flag’s value is 0x0100.

Track Reference Atoms

Track reference atoms define relationships between tracks. Track reference atoms allow one track to specify how it is related to other tracks. For example, if a movie has three video tracks and three sound tracks, track references allow you to identify the related sound and video tracks. Track reference atoms have an atom type value of 'tref'.

Track references are unidirectional and point from the recipient track to the source track. For example, a video track may reference a time code track to indicate where its time code is stored, but the time code track would not reference the video track. The time code track is the source of time information for the video track.

A single track may reference multiple tracks. For example, a video track could reference a sound track to indicate that the two are synchronized and a time code track to indicate where its time code is stored.

A single track may also be referenced by multiple tracks. For example, both a sound and video track could reference the same time code track if they share the same timing information.

If this atom is not present, the track is not referencing any other track in any way. Note that the array of track reference type atoms is sized to fill the track reference atom. Track references with a reference index of 0 are permitted. This indicates no reference.

Figure 2-13 shows the layout of a track reference atom.

Figure 2-13 The layout of a track reference atom

A track reference atom contains the following data elements.

Size: A 32-bit integer that specifies the number of bytes in this track reference atom.
Type: A 32-bit integer that identifies the atom type; this field must be set to 'tref'.
Track reference type atoms: A list of track reference type atoms containing the track reference information. These atoms are described next.

Each track reference atom defines relationships with tracks of a specific type. The reference type implies a track type. Table 2-2 shows the track reference types and their descriptions.

**Table 2-2** Track reference types
Reference type	Description
`'tmcd'`	Time code. Usually references a time code track.
`'chap'`	Chapter or scene list. Usually references a text track.
`'sync'`	Synchronization. Usually between a video and sound track. Indicates that the two tracks are synchronized. The reference can be from either track to the other, or there may be two references.
`'scpt'`	Transcript. Usually references a text track.
`'ssrc'`	Nonprimary source. Indicates that the referenced track should send its data to this track, rather than presenting it. The referencing track will use the data to modify how it presents its data. See “Track Input Map Atoms” for more information.
`'hint'`	The referenced tracks contain the original media for this hint track.

Each track reference type atom contains the following data elements.

Size: A 32-bit integer that specifies the number of bytes in this track reference type atom.
Type: A 32-bit integer that identifies the atom type; this field must be set to one of the values shown in Table 2-2.
Track IDs: A list of track ID values (32-bit integers) specifying the related tracks. Note that this is one case where track ID values can be set to 0. Unused entries in the atom may have a track ID value of 0. Setting the track ID to 0 may be more convenient than deleting the reference.

You can determine the number of track references stored in a track reference type atom by subtracting its header size from its overall size and then dividing by the size, in bytes, of a track ID.

Track Input Map Atoms

Track input map atoms define how data being sent to this track from its nonprimary sources is to be interpreted. Track references of type 'ssrc' define a track’s secondary data sources. These sources provide additional data that is to be used when processing the track. Track input map atoms have an atom type value of 'imap'.

Figure 2-14 shows the layout of a track input atom. This atom contains one or more track input atoms. Note that the track input map atom is a QT atom structure.

Figure 2-14 The layout of a track input map atom

Each track input map atom contains the following data elements.

Size: A 32-bit integer that specifies the number of bytes in this track input map atom.
Type: A 32-bit integer that identifies the atom type; this field must be set to 'imap'.
Track input atoms: A list of track input atoms specifying how to use the input data.

The input map defines all of the track’s secondary inputs. Each secondary input is defined using a separate track input atom.

Each track input atom contains the following data elements.

Size: A 32-bit integer that specifies the number of bytes in this track input atom.
Type: A 32-bit integer that identifies the atom type; this field must be set to ' in' (note that the two leading bytes must be set to 0x00).
Atom ID: A 32-bit integer relating this track input atom to its secondary input. The value of this field corresponds to the index of the secondary input in the track reference atom. That is, the first secondary input corresponds to the track input atom with an atom ID value of 1; the second to the track input atom with an atom ID of 2, and so on.
Reserved: A 16-bit integer that must be set to 0.
Child count: A 16-bit integer specifying the number of child atoms in this atom.
Reserved: A 32-bit integer that must be set to 0.

The track input atom, in turn, may contain two other types of atoms: input type atoms and object ID atoms. The input type atom is required; it specifies how the data is to be interpreted.

The input type atom contains the following data elements.

Size: A 32-bit integer that specifies the number of bytes in this input type atom.
Type: A 32-bit integer that identifies the atom type; this field must be set to ' ty' (note that the two leading bytes must be set to 0x00).
Input type: A 32-bit integer that specifies the type of data that is to be received from the secondary data source. Table 2-3 lists valid values for this field.

**Table 2-3** Input types
Input identifier	Value	Description
`kTrackModifierTypeMatrix`	1	A 3 x 3 transformation matrix to transform the track’s location, scaling, and so on.
`kTrackModifierTypeClip`	2	A QuickDraw clipping region to change the track’s shape.
`kTrackModifierTypeVolume`	3	An 8.8 fixed-point value indicating the relative sound volume. This is used for fading the volume.
`kTrackModifierTypeBalance`	4	A 16-bit integer indicating the sound balance level. This is used for panning the sound location.
`kTrackModifierTypeGraphicsMode`	5	A graphics mode record (32-bit integer indicating graphics mode, followed by an RGB color) to modify the track’s graphics mode for visual fades.
`kTrackModifierObjectMatrix`	6	A 3x3 transformation matrix to transform an object within the track’s location, scaling, and so on.
`kTrackModifierObjectGraphicsMode`	7	A graphics mode record (32-bit integer indicating graphics mode, followed by an RGB color) to modify an object within the track’s graphics mode for visual fades.
`kTrackModifierTypeImage`	`'vide’`	Compressed image data for an object within the track. Note that this was `kTrackModifierTypeSpriteImage`.

If the input is operating on an object within the track (for example, a sprite within a sprite track), an object ID atom must be included in the track input atom to identify the object.

The object ID atom contains the following data elements.

Size: A 32-bit integer that specifies the number of bytes in this object ID atom.
Type: A 32-bit integer that identifies the atom type; this field must be set to 'obid'.
Object ID: A 32-bit integer identifying the object.

< Previous PageNext Page >

Hide TOC

Last updated: 2007-09-04

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.




	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. \| Terms of use \| Privacy Notice