Adding Samples to Media Structures

This section describes several functions your application can use to directly manipulate media samples. Note that GetMediaSampleReferences and AddMediaSampleReferences are plural forms added to GetMediaSampleReference and AddMediaSampleReference. They let you work with multiple samples at once, which is generally more efficient.

• BeginMediaEdits

• EndMediaEdits

• AddMediaSample

• AddMediaSampleReference

• GetMediaSample

• GetMediaSampleReference

• GetMediaSampleReferences

• AddMediaSampleReferences

• SetMediaDefaultDataRefIndex

• SetMediaPreferredChunkSize

• GetMediaPreferredChunkSize

This section describes Movie Toolbox functions that directly manipulate media samples. These functions are used only by applications that create movies or add data to existing movies.

You add samples to a media by calling the AddMediaSample function. You can indicate that the sample to be added is not a sync sample. Sync samples do not rely on preceding frames for content. Some compression algorithms conserve space by eliminating duplication between consecutive frames in a sample. In image data, sync samples are referred to as key frames.

You can obtain the data in a media sample by calling the GetMediaSample function. If you are going to add samples to a media, you must do so within a media-editing session. You start a media-editing session by calling the BeginMediaEdits function. Once you have finished adding samples to the media, you end the editing session by calling the EndMediaEdits function.

Once you have added samples to a media, you can work with references to those samples by calling the AddMediaSampleReference and GetMediaSampleReference functions. You do not have to be in a media-editing session to use these functions.

Finding Interesting Times

The Movie Toolbox provides a set of functions that help you locate samples in movies, tracks, and media structures. These functions are based on the concept of “interesting times.” An interesting time refers to a time value in a movie, track, or media that meets certain search criteria. You specify the search criteria to the Movie Toolbox. The Movie Toolbox then scans the movie, track, or media, and locates time values that meet those search criteria.

You can use these functions to search through image sequences. For example, you may want to locate each frame in an image sequence. Or you may be more interested in key frames, especially if you are trying to optimize display performance. In image data, sync samples are referred to as key frames. An easy way to determine whether a movie has been edited is to look for track edits in the movie data. You may also be interested in searching for samples in a movie’s media. If you set the appropriate search criteria, the Movie Toolbox locates the appropriate frames for you. You need the functions described in this section because QuickTime doesn’t have a fixed rate. Each frame can have its own duration.

The Movie Toolbox identifies an interesting time by specifying its starting time and duration. The starting time indicates the time in the movie, track, or media where the search criteria are met. The duration indicates the length of time during which the search criteria remain in effect. For example, if you are looking for samples in a media, the start time would indicate the beginning of the sample, and the duration would indicate the length of time to the next sample. In this case, you could find the next media sample by adding the duration to the start time. These duration values are always positive; you determine the direction of the search by setting the sign of the rate value you supply to the functions.

Note that movie interesting times are defined in the scope of the movie as a whole. As a result, one interesting time ends when another interesting time starts in any track in the movie. For example, if you are looking for key frames in a movie, the duration value from one interesting time tells you when the next key frame starts. However, that second key frame may be in a different track in the movie. Therefore, the duration of the interesting time does not necessarily correspond to the duration of the key frame.

You can use the GetMovieNextInterestingTime function to locate times of interest in a movie. The GetTrackNextInterestingTime function lets you work with tracks. Use the GetMediaNextInterestingTime function to locate samples in a media.

Working With Movie User Data

Each movie, track, and media can contain a user data list, which your application can use in any way you want. A user data list contains all the user data for a movie, track, or media. Each user data list may contain one or more user data items.

The functions your application can use to work with movie user data are listed below. Each movie, track and media can contain a user data list, which can be used for any purpose you like.

• GetMovieUserData

• GetTrackUserData

• GetMediaUserData

• GetNextUserDataType

• CountUserDataType

• AddUserData

• GetUserData

• RemoveUserData

• AddUserDataText

• GetUserDataText

• RemoveUserDataText

• SetUserDataItem

• GetUserDataItem

• NewUserData

• DisposeUserData

• PutUserDataIntoHandle

• NewUserDataFromHandle

Each user data item carries a type identifier. This type is stored in a long integer. Apple has reserved all lowercase user data type values. You are free to create user data type values using uppercase letters. Apple recommends using type values that begin with the copyright symbol.