Next Page >

Hide TOC

QuickTime Movie Track and Media Reference

Framework	Frameworks/QuickTime.framework
Declared in	Movies.h

Overview

Track and media management functions help with the construction and editing of QuickTime movies.

Functions by Task

Adding Samples to Media Structures

Creating Tracks and Media Structures

Determining Movie Creation and Modification Time

Disabling Movies and Tracks

Editing Tracks

Enhancing Movie Playback Performance

Finding and Adding Samples

High-Level Movie Editing Functions

Locating a Movie's Tracks and Media Structures

Low-Level Movie Editing Functions

Manipulating Media Input Maps

Movie Functions

Movie Posters and Movie Previews

Movies and Your Event Loop

Selecting Media Handlers

Undo for Movies

Undo for Tracks

Working With Alternate Tracks

Working With Media Samples

Working With Media Time

Working With Movie Spatial Characteristics

Working With QuickTime Sample Tables

Working With Sound Volume

Working With Track References

Working With Track Sound

Working With Track Time

Working With User Data

Supporting Functions

Functions

AddClonedTrackToMovie

Constructs a clone of an existing track in a movie.

OSErr AddClonedTrackToMovie (
   Track srcTrack,
   Movie dstMovie,
   long flags,
   Track *dstTrack
);

Parameters

sourceTrack

Indicates the track to be cloned. Your application obtains this track identifier from such functions as NewMovieTrack and GetMovieTrack. This is the source of the sample table once the cloned track is constructed.

destinationMovie

Indicates the movie where the cloned track should be created. Your application obtains this identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle. Currently, this must be the movie that contains the source track.

flags

Flags (see below) that determine how cloning should be performed. You currently must pass kQTCloneShareSamples. See these constants:

kQTCloneShareSamples
kQTCloneDontCopyEdits

dstTrack

The address of storage where a reference to the newly constructed track is returned. If the function fails, this storage is set to NIL.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Special Considerations

Most QuickTime developers should never need to call this function.

Version Notes

Introduced in QuickTime 5.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Movies.h

AddEmptyTrackToMovie

Duplicates a track from a movie into the same movie or into another movie.

OSErr AddEmptyTrackToMovie (
   Track srcTrack,
   Movie dstMovie,
   Handle dataRef,
   OSType dataRefType,
   Track *dstTrack
);

Parameters

srcTrack: The source track for this operation. Your application obtains this track identifier from such functions as NewMovieTrack and GetMovieTrack.
dstMovie: The destination movie for this operation. This can be the same movie as the source track or a different movie.
dataRef: A handle to the data reference. The type of information stored in the handle depends upon the data reference type specified by dataRefType.
dataRefType: The type of data reference; see Data References. If the data reference is an alias, you must set the parameter to rAliasType, indicating that the reference is an alias.
dstTrack: The newly created track's identifier is returned in this parameter. If AddEmptyTrackToMovie fails, the resulting track identifier is set to NIL.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

This function returns a newly created, empty track. The newly created track has the same media type and track settings as the specified track. However, no data is copied from the source track to the new track. To copy data from the source track to the new track, use InsertTrackSegment after calling AddEmptyTrackToMovie.

Version Notes

This function has been available since QuickTime 2.0.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Movies.h

AddMediaSample

Adds sample data and a description to a media.

OSErr AddMediaSample (
   Media theMedia,
   Handle dataIn,
   long inOffset,
   unsigned long size,
   TimeValue durationPerSample,
   SampleDescriptionHandle sampleDescriptionH,
   long numberOfSamples,
   short sampleFlags,
   TimeValue *sampleTime
);

Parameters

theMedia

The media for this operation. Your application obtains this media identifier from such functions as NewTrackMedia and GetTrackMedia. See Media Identifiers.

dataIn

A handle to the sample data. The AddMediaSample function adds this data to the media specified by the parameter theMedia. You specify the number of bytes of sample data with the size parameter. You can use the inOffset parameter to specify a byte offset into the data referred to by this handle.

inOffset

Specifies an offset into the data referred to by the handle contained in the dataIn parameter. Set this parameter to 0 if there is no offset.

size

The number of bytes of sample data to be added to the media. This parameter indicates the total number of bytes in the sample data to be added to the media, not the number of bytes per sample. Use the numberOfSamples parameter to indicate the number of samples that are contained in the sample data.

durationPerSample

The duration of each sample to be added. You must specify this parameter in the media's time scale. For example, if you are adding sound that was sampled at 22 kHz to a media that contains a sound track with the same time scale, you would set durationPerSample to 1. Similarly, if you are adding video that was recorded at 10 frames per second to a video media that has a time scale of 600, you would set this parameter to 60 to add a single sample.

sampleDescriptionH

A handle to a SampleDescription structure. Some media structures may require sample descriptions. There are different descriptions for different types of samples. For example, a media that contains compressed video requires that you supply an ImageDescription structure. A media that contains sound requires that you supply a SoundDescription structure. If the media does not require a SampleDescription structure, set this parameter to NIL.

numberOfSamples

The number of samples contained in the sample data to be added to the media. The Movie Toolbox considers the value of this parameter as well as the value of the size parameter when it determines the size of each sample that it adds to the media. You should set the value of this parameter so that the resulting sample size represents a reasonable compromise between total data retrieval time and the overhead associated with input and output (I/O). You should also consider the speed of the data storage device; CD-ROM devices are much slower than hard disks, for example, and should therefore have a smaller sample size. For a video media, set a sample size that corresponds to the size of a frame. For a sound media, choose a number of samples that corresponds to between 0.5 and 1.0 seconds of sound. In general, you should not create groups of sound samples that are less than 2 KB in size or greater than 15 KB. Typically, a sample size of about 8 KB is reasonable for most storage devices.

sampleFlags

Contains flags (see below) that control the add operation. Set unused flags to 0. See these constants:

mediaSampleNotSync

sampleTime

A pointer to a time value. After adding the sample data to the media, the AddMediaSample function returns the time where the sample was inserted in the time value referred to by this parameter. If you don't want to receive this information, set this parameter to NIL.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

Your application specifies the sample and the media for the operation. AddMediaSample updates the media so that it contains the sample data. One call to this function can add several samples to a media; however, all the samples must be the same size. Samples are always appended to the end of the media. Furthermore, the media duration is extended each time a sample is added.

// AddMediaSample coding example

// See "Discovering QuickTime," page 250

#define kSoundSampleDuration    1

#define kSyncSample             0

#define kTrackStart             0

#define kMediaStart             0

#define kFix1                   0x00010000

void CreateMySoundTrack (Movie movie)

    Track                       track;

    Media                       media;

    Handle                      hSound =NIL;

    SoundDescriptionHandle      hSoundDesc =NIL;

    long                        lDataOffset;

    long                        lDataSize;

    long                        lNumSamples;

    hSound =GetResource(soundListRsrc, 128);

    if (hSound ==NIL)

        return;

    hSoundDesc =(SoundDescriptionHandle)NewHandle(4);

    CreateMySoundDescription(hSound,

                            hSoundDesc,

                            &lDataOffset,

                            &lNumSamples,

                            &lDataSize);

    track =NewMovieTrack(movie, 0, 0, kFullVolume);

    media =NewTrackMedia(track, SoundMediaType,

                                FixRound((**hSoundDesc).sampleRate),

                                NIL, 0);

    BeginMediaEdits(media);

    AddMediaSample(media,

                    hSound,

                    lDataOffset,        // offset in data

                    lDataSize,

                    kSoundSampleDuration,   // duration of each sound

                                            //  sample

                    (SampleDescriptionHandle)hSoundDesc,

                    lNumSamples,

                    kSyncSample,        // self-contained samples

                    NIL);

    EndMediaEdits(media);

    InsertMediaIntoTrack(track,

                            kTrackStart,    // track start time

                            kMediaStart,    // media start time

                            GetMediaDuration(media),

                            kFix1);

    if (hSoundDesc !=NIL)

        DisposeHandle((Handle)hSoundDesc);

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Movies.h

AddMediaSample2

Adds sample data and a description to a media.

OSErr AddMediaSample2 (
   Media theMedia,
   const UInt8 *dataIn,
   ByteCount size,
   TimeValue64 decodeDurationPerSample,
   TimeValue64 displayOffset,
   SampleDescriptionHandle sampleDescriptionH,
   ItemCount numberOfSamples,
   MediaSampleFlags sampleFlags,
   TimeValue64 *sampleDecodeTimeOut
);

Parameters

theMedia

The media for this operation. You obtain this media identifier from such functions as NewTrackMedia and GetTrackMedia.

dataIn

A handle to the sample data. The function adds this data to the media specified by theMedia. You specify the number of bytes of sample data with the size parameter.

size

decodeDurationPerSample

The duration of each sample to be added, representing the amount of time that passes while the sample data is being displayed. You must specify this parameter in the media's time scale. For example, if you are adding sound that was sampled at 22 kHz to a media that contains a sound track with the same time scale, you would set durationPerSample to 1. Similarly, if you are adding video that was recorded at 10 frames per second to a video media that has a time scale of 600, you would set this parameter to 60. Note that this is the duration per sample, regardless of the number of samples being added.

displayOffset

A 64-bit time value that specifies the offset between the decode time (the start time of the track plus the duration of all previous samples) and the display time. This value is normally zero unless the sample is frame reordering compressed video.

sampleDescriptionH

numberOfSamples

The number of samples contained in the sample data to be added to the media. The Movie Toolbox considers the value of this parameter as well as the value of the size parameter when it determines the size of each sample that it adds to the media. You should set the value of this parameter so that the resulting sample size represents a reasonable compromise between total data retrieval time and the overhead associated with input and output. You should also consider the speed of the data storage device; CD-ROM devices are much slower than hard disks, for example, and should therefore have a smaller sample size. For a video media, set a sample size that corresponds to the size of a frame. For a sound media, choose a number of samples that corresponds to between 0.5 and 1.0 seconds of sound. In general, you should not create groups of sound samples that are less than 2 KB in size or greater than 15 KB. Typically, a sample size of about 8 KB is reasonable for most storage devices.

sampleFlags

Flags that control the add operation; set unused flags to 0: mediaSampleNotSync Indicates that the sample to be added is not a sync sample. Set this flag to 1 if the sample is not a sync sample; set it to 0 if the sample is a sync sample. See these constants:

mediaSampleNotSync

sampleDecodeTimeOut

A pointer to a time value that represents the sample decode time. After adding the sample data to the media, the function returns in this parameter the time where the sample was inserted. If you don't want to receive this information, set this parameter to NIL.

Return Value

An error code. Returns noErr if there is no error. You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result.

Discussion

Your application specifies the sample and the media for the operation. This function updates the media so that it contains the sample data. One call to this function can add several samples to a media. This function replaces AddMediaSample; it adds 64-bit support and support for frame reordering video compression (display offset).

Availability

Available in Mac OS X v10.3 and later.

Declared In

Movies.h

AddMediaSampleFromEncodedFrame

Adds sample data and description from an encoded frame to a media.

OSErr AddMediaSampleFromEncodedFrame (
   Media theMedia,
   ICMEncodedFrameRef encodedFrame,
   TimeValue64 *sampleDecodeTimeOut
);

Parameters

theMedia: The media for this operation. You obtain this media identifier from such functions as NewTrackMedia and GetTrackMedia
encodedFrame: An encoded frame token returned by an ICMCompressionSequence.
sampleDecodeTimeOut: A pointer to a time value. After adding the sample data to the media, the function returns the decode time where the first sample was inserted in the time value referred to by this parameter. If you don't want to receive this information, set this parameter to NULL.

Return Value

An error code. Returns noErr if there is no error. You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result.

Discussion

This is a convenience API to make it easy to add frames emitted by new ICM compression functions to media. It can return these errors:

Availability

Available in Mac OS X v10.3 and later.

Declared In

Movies.h

AddMediaSampleReference

Works with samples that have already been added to a movie data file.

OSErr AddMediaSampleReference (
   Media theMedia,
   long dataOffset,
   unsigned long size,
   TimeValue durationPerSample,
   SampleDescriptionHandle sampleDescriptionH,
   long numberOfSamples,
   short sampleFlags,
   TimeValue *sampleTime
);

Parameters

theMedia

The media for this operation. Your application obtains this media identifier from such functions as NewTrackMedia and GetTrackMedia. See Media Identifiers.

dataOffset

The offset into the movie data file. This parameter is used differently by each data handler. For example, for the standard HFS data handler, this parameter specifies the offset into the file. This parameter contains either data you add yourself or the data offset returned by GetMediaSampleReference.

size

The number of bytes of sample data to be identified by the reference. This parameter indicates the total number of bytes in the sample data, not the number of bytes per sample. Use numberOfSamples to indicate the number of samples that are contained in the reference.

durationPerSample

The duration of each sample in the reference. You must specify this parameter in the media's time scale. For example, if you are referring to sound that was sampled at 22 kHz in a media that contains a sound track with the same time scale, to add a reference to a single sample you would set durationPerSample to 1. Similarly, if you are referring to video that was recorded at 10 frames per second in a video media that has a time scale of 60, you would set this parameter to 6 to add a reference to a single sample.

sampleDescriptionH

A handle to a SampleDescription structure. Some media structures may require sample descriptions. There are different descriptions for different types of samples. For example, a media that contains compressed video requires that you supply an ImageDescription structure. A media that contains sound requires that you supply a sound description structure. If the media does not require a SampleDescription structure, set this parameter to NIL.

numberOfSamples

The number of samples contained in the reference. For details, see AddMediaSample. If the media does not require a SampleDescription structure, set this parameter to NIL.

sampleFlags

Contains flags (see below) that control the operation. Set unused flags to 0. See these constants:

mediaSampleNotSync

sampleTime

A pointer to a time value. After adding the reference to the media, the AddMediaSampleReference function returns the time where the reference was inserted in the time value referred to by this parameter. If you don't want to receive this information, set this parameter to NIL.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

This function does not add sample data to the file or device that contains a media. Rather, it defines references to sample data that you previously added to a movie data file. Instead of actually writing out samples to disk, this function writes out references to existing samples, which you specify in dataOffset and the size parameter. As with AddMediaSample, your application specifies the media for the operation. Note that one reference may refer to more than one sample; all the samples described by a reference must be the same size. This function does not update the movie data file as part of the add operation. Therefore, your application does not have to call BeginMediaEdits before calling AddMediaSampleReference.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Movies.h

AddMediaSampleReferences

Adds groups of samples to a movie data file.

OSErr AddMediaSampleReferences (
   Media theMedia,
   SampleDescriptionHandle sampleDescriptionH,
   long numberOfSamples,
   SampleReferencePtr sampleRefs,
   TimeValue *sampleTime
);

Parameters

theMedia: The media for this operation. Your application obtains this media identifier from such functions as NewTrackMedia and GetTrackMedia. See Media Identifiers.
sampleDescriptionH: A handle to a SampleDescription structure. Some media structures may require sample descriptions. There are different descriptions for different types of samples. For example, a media that contains compressed video requires that you supply an ImageDescription structure. A media that contains sound requires that you supply a sound description structure. If you don't want the SampleDescription structure, set this parameter to NIL.
numberOfSamples: The number of SampleReferenceRecord structures pointed to by the sampleRefs parameter. Each structure may contain one or more contiguous samples. For details, see AddMediaSample.
sampleRefs: A pointer to the number of SampleReferenceRecord structures specified by the numberOfSamples parameter.
sampleTime: A pointer to a time value. After adding the reference to the media, the AddMediaSampleReferences function returns the time where the reference was inserted, using the time scale referred to by this parameter. If you don't want to receive this information, set this parameter to NIL.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

Using this function instead of AddMediaSampleReference can greatly improve the performance of operations that involve adding a large number of samples to a movie at one time. AddMediaSampleReferences provides no capabilities that weren't previously available with AddMediaSampleReference.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Movies.h

AddMediaSampleReferences64

Provides a 64-bit version of AddMediaSampleReferences.

OSErr AddMediaSampleReferences64 (
   Media theMedia,
   SampleDescriptionHandle sampleDescriptionH,
   long numberOfSamples,
   SampleReference64Ptr sampleRefs,
   TimeValue *sampleTime
);

Parameters

theMedia: The media for this operation. Your application obtains this media identifier from such functions as NewTrackMedia and GetTrackMedia. See Media Identifiers.
sampleDescriptionH: A handle to a SampleDescription structure. Some media structures may require sample descriptions. There are different descriptions for different types of samples. For example, a media that contains compressed video requires that you supply an ImageDescription structure. A media that contains sound requires that you supply a sound description structure. If you don't want the SampleDescription structure, set this parameter to NIL.
numberOfSamples: The number of SampleReference64Record structures pointed to by the sampleRefs parameter. Each structure may contain one or more contiguous samples. For details, see AddMediaSample.
sampleRefs: A pointer to the number of SampleReference64Record structures specified by the numberOfSamples parameter.
sampleTime: A pointer to a time value. After adding the reference to the media, the AddMediaSampleReferences function returns the time where the reference was inserted, using the time scale referred to by this parameter. If you don't want to receive this information, set this parameter to NIL.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

The only difference between this function and AddMediaSampleReferences is that the sampleRefs parameter points to SampleReference64Record structures instead of SampleReferenceRecord structures.

Special Considerations

New applications should use this function instead of the 32-bit version.

Version Notes

Introduced in QuickTime 4.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Movies.h

AddMovieSelection

Adds one or more tracks to a movie.

void AddMovieSelection (
   Movie theMovie,
   Movie src
);

Parameters

theMovie: The destination movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.
src: The source movie for this operation. AddMovieSelection adds the tracks from this movie to the destination movie. The function adds these tracks at the time specified by the current selection in the destination movie.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Discussion

This function scales the source movie so that it fits into the destination selection. If the current selection in the destination movie has a 0 duration, the Movie Toolbox adds the segment at the beginning of the current selection. The entire source movie is used regardless of the selection in the source movie. The Movie Toolbox removes any empty tracks from the destination movie after the add operation. If you have assigned a progress function to the destination movie, the Movie Toolbox calls that progress function during long add operations. Following is an example of using this function:

// AddMovieSelection coding example

// See "Discovering QuickTime," page 363

Movie           movie1;

TimeValue       lOldDuration;

Movie           movie2;

long            lIndex, lOrigTrackCount, lReferenceIndex;

Track           track, trackSprite;

// get the first track in original movie and position at the start

trackSprite =GetMovieIndTrack(movie1, 1);

SetMovieSelection(movie1, 0, 0);

// remove all tracks except video in modifier movie

for (lIndex =1; lIndex <=GetMovieTrackCount(movie2); lIndex++) {

    Track       track =GetMovieIndTrack(movie2, lIndex);

    OSType      dwType;

    GetMediaHandlerDescription(GetTrackMedia(track),

                                &dwType, NIL, NIL);

    if (dwType !=VideoMediaType) {

        DisposeMovieTrack(track);

        lIndex--;

// add the modifier track to original movie

lOldDuration =GetMovieDuration(movie1);

AddMovieSelection(movie1, movie2);

DisposeMovie(movie2);

// truncate the movie to the length of the original track

DeleteMovieSegment(movie1, lOldDuration,

                    GetMovieDuration(movie1) - lOldDuration);

// associate the modifier track with the original sprite track

track =GetMovieIndTrack(movie1, lOrigTrackCount + 1);

AddTrackReference(trackSprite, track, kTrackModifierReference,

                    &lReferenceIndex);

Special Considerations

Some Movie Toolbox functions can take a long time to execute. For example, if you call FlattenMovie and specify a large movie, the Movie Toolbox must read and write all the sample data for the movie. During such operations you may wish to display some kind of progress indicator to the user. A progress function is an application-defined function that you can create to track the progress of time-consuming activities and keep the user informed.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Movies.h