Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
Creating Tracks and Media Structures
This book describes the functions your application can use to create and dispose of tracks and media structures. These functions are used when creating movies or when editing movies at the track level.
The Movie Toolbox provides several functions that allow your application to create new movie tracks and media structures and to dispose of existing tracks and media structures. You use these functions when you are creating a new movie or when you are editing an existing movie.
You can use the
NewMovieTrack function to create a new track for a specified movie. Conversely, you can use the
DisposeMovieTrack function to dispose of an existing track.
Your application can create a new media for a track by calling the
NewTrackMedia function. You can use the
DisposeTrackMedia function to dispose of an existing media.
Working With Track References
Track references allow you to relate tracks to one another. For example, this can help you identify the text track that contains the subtitles for a movie’s audio track and relate that text track to a particular audio track.
About Track References
Although QuickTime has always allowed the creation of movies that contain more than one track, it has not been able to specify relationships between those tracks. Track references are a new feature of QuickTime that allow you to relate a movie’s tracks to one another. The QuickTime track-reference mechanism supports many-to-many relationships. That is, any movie track may contain one or more track references, and any track may be related to one or more other tracks in the movie.
Track references can be useful in a variety of ways. For example, track references can be used to relate timecode tracks to other movie tracks. (See Timecode Media Handler for more information about timecode tracks.) You might consider using track references to identify relationships between video and sound tracks: identifying the track that contains dialog and the track that contains background sounds, for example. Another use of track references is to associate one or more text tracks that contain subtitles with the appropriate audio track or tracks.
Track references are also used to create chapter lists, as described below.
Every movie track contains a list of its track references. Each track reference identifies another, related track. That related track is identified by its track identifier. The track reference itself contains information that allows you to classify the references by type. This type information is stored in an
OSType data type. You are free to specify any type value you want. Note, however, that Apple has reserved all lowercase type values.
You may create as many track references as you want, and you may create more than one reference of a given type. Each track reference of a given type is assigned an index value. The index values start at 1 for each different reference type. The toolbox maintains these index values so that they always start at 1 and count by 1.
Track Reference Functions
This section describes the functions that manipulate track references. Track references define relations between tracks. For example, a timecode track may be related to several other tracks, or a text track may contain subtitles for a particular audio track.
AddTrackReference function allows you to relate one track to another. The
DeleteTrackReference function removes that relationship. The
GetTrackReference functions allow you to modify an existing track reference so that it identifies a different track. The
GetTrackReferenceCount functions allow you to scan all of a track’s track references.
Timecode Media Handler
Timecode tracks allow you to store external timecode information, such as SMPTE timecodes, in your QuickTime movies. QuickTime now provides a new timecode media handler that interprets the data in these tracks.
A chapter list provides a set of named entry points into a movie, allowing the user to jump to a preselected point in the movie from a convenient pop-up list.
The movie controller automatically recognizes a chapter list and will create a pop-up list from it. When the user makes a selection from the pop-up, the controller will jump to the appropriate point in the movie.
To create a chapter list, you must create a text track with one sample for each chapter. The display time for each sample corresponds to the point in the movie that marks the beginning of that chapter. You must also create a track reference of type
'chap' from an enabled track of the movie to the text track. It is the
'chap' track reference that makes the text track into a chapter list. The track containing the reference can be of any type (audio, video, mpeg, etc.), but it must be enabled for the chapter list to be recognized.
Given an enabled track
AddTrackReference to create the chapter reference:
AddTrackReference( myVideoTrack, theTextTrack,
kTrackReferenceChapterList, &addedIndex );
kTrackReferenceChapterList is defined in
Movies.h. It has the value
The text track which constitutes the chapter list does not need to be enabled, and normally is not. If it is enabled, the text track will be displayed as part of the movie, just like any other text track, in addition to functioning as a chapter list.
If more than one enabled track includes a
'chap' track reference, QuickTime will use the first chapter list that it finds.
Working With Data References
This section describes the functions used to work with data references. Media structures point to their actual sample data using data references. For sound and video media, data references identify the files that contain the data. Media handlers also use data references in order to manipulate media data.
Media structures identify how and where to find their sample data by means of data references. For sound and video media, data references identify files that contain media data; the media data is stored in the data forks of these files. Media handlers use these data references in order to manipulate media data. A single media may contain one or more data references.
Each data reference contains type information that identifies how the reference is specified. Most QuickTime data references use alias information to locate the corresponding files. The type value for data references that use aliases is
The Movie Toolbox identifies a media’s data references with an index value. Index values always range from 1 to the number of references in the media. Data reference indexes provide a convenient way to access each reference in a media.
The Movie Toolbox provides a set of functions that allow you to work with data references. This section describes those functions.
You can use the
GetMediaDataRef function to retrieve information about a media’s data reference. You can add a data reference to a media by calling the
AddMediaDataRef function. The
SetMediaRef function lets you change which file a specified media associates with its data storage.
Your application can determine the number of data references in a media by calling the
QuickTime contains functions your application can use to work with alternate tracks. Alternate tracks are used to create a single movie that can, for example, play back with different language audio tracks in different countries, or with different quality audio or video on different model computers.
For further information about alternate tracks, see QuickTime Movie Internals Guide.
The Movie Toolbox provides a number of functions that allow your application to perform editing operations on tracks. These functions work with track segments (pieces of a track that are defined by a starting time and duration) and therefore give you a great deal of control over the editing process. These functions are similar to the low-level editing functions for movies that were described earlier in this chapter. However, these functions may copy movie data, if required by the operation.
When you edit a track you may change the duration of the movie that contains that track.
CopyTrackSettings function lets you copy certain important settings from one track to another.
You can use the
InsertTrackSegment function to copy a segment from one track to another, by reference or by moving data, or to copy a segment within a track. The
InsertTrackEmptySegment function allows you to insert an empty segment into a track.
You can use the
InsertMediaIntoTrack function to insert a media into a track.
Your application can delete a segment from a track by calling the
You can change a segment’s duration by calling the
ScaleTrackSegment function. This function stretches or shrinks the segment to accommodate a specified duration.
You can use the
GetTrackEditRate function to determine the rate of the track edit of a specified track at an indicated time.