Inside Macintosh: QuickTime Reference

Sample Format

Each sample in the movie media is a QuickTime Atom Container. All root level atoms and their contents are enumerated in the following list. Note that the contents of all atoms are stored in big-endian format.

kMovieMediaDataReference: This atom contains a data reference type and a data reference. The data reference type is stored as an OSType at the start of the atom. The data reference is stored following the data reference type. If the data reference type is URL and the data reference is for a movie on the Apple Web site, the contents of the atom would be: "url http://www.apple.com/foo.mov".; There may be more than one atom of this type. The first atom of this type should have an atom ID of 1. Additional data references should be numbered sequentially.
kMovieMediaDefaultDataReferenceID: This atom contains a QTAtomID which indicates the ID of the data reference to use when instantiating the embedded movie for this sample. If this atom is not present, the data reference with an ID of 1 is used.
kMovieMediaSlaveTime: This atom contains a Boolean that indicates whether or not the TimeBase of the embedded movie should be slaved to the TimeBase of the parent movie. If the TimeBase is slaved, the embedded movie's zero time will correspond to the start time of its movie media sample. Further, the playback rate of the embedded movie will always be the same as the parent movie's. If the TimeBase is not slaved, the embedded movie will default to a rate of zero, and a default time of whatever default time value it instantiated with (which may not be zero). If the TimeBase is not slaved, the embedded movie can be played by either including an AutoPlay atom in the movie media sample or by using a Wired Action. If this atom is not present, the embedded movie defaults to not slaved.
kMovieMediaSlaveAudio: This atom contains a Boolean that indicates whether or not the audio properties of the embedded movie should be slaved to those of the parent movie. When audio is slaved, all audio properties of the containing track are duplicated in the embedded movie. These properties include sound volume, balance, bass and treble, and level metering. If this atom is not present, the embedded movie defaults to not slaved audio.
kMovieMediaSlaveGraphicsMode: This atom contains a Boolean that indicates how the graphics mode of the containing track is applied to the embedded movie. If the graphics mode is not slaved, then the entire embedded movie is imaged using its own graphics modes. Then the result of the drawing of the embedded movie is composited onto the containing movie using the graphics mode of the containing track. If the graphics mode is slaved, then the graphics mode of each track in the embedded movie is ignored and instead the graphics mode of the containing track is used. In this case, the tracks of the embedded movie composite their drawing directly into the parent movie's contents. If this atom is not present, the graphics mode defaults to not slaved. Graphics mode slaving is useful for compositing semi-transparent media -- for example a PNG with an alpha channel -- on top of other media.
kMovieMediaSlaveTrackDuration: This atom contains a Boolean that indicates how the Movie Media Handler should react when the duration of the embedded movie is different than the duration of the movie media sample that it is contained by. When the movie media sample is created, the duration of the embedded movie may not yet be known. Therefore, the duration of the media sample may not be correct. In this case, the Movie Media Handler can do one of two things. If this atom is not present or it contains a value of false, the Movie Media Handler will respect the duration of media sample that contains the embedded movie. If the embedded movie has a longer duration than the movie media sample, the embedded movie will be truncated to the duration of the containing movie media sample. If the embedded movie is shorter, there will be a gap after it is finished playing. If this atom contains a value of true, the duration of the movie media sample will be adjusted to match the actual duration of the embedded movie. Because it is not possible to change an existing media sample, this will cause a new media sample to be added to the movie and the track's edit list to be updated to reference the new sample instead of the original sample.

Note: When the duration of the embedded movie's sample is adjusted, by default no other tracks are adjusted. This can cause the overall temporal composition to change in unintended ways. To maintain the complete temporal composition, a higher level data structure which describes the temporal relationships between the various tracks must also be included with the movie.

kMovieMediaAutoPlay: This atom contains a Boolean that indicates whether or not the embedded movie should start playing immediately after being instantiated. This atom is only used if the TimeBase of the embedded movie is not slaved to the parent movie (see the kMovieMediaSlaveTime atom for more information). If auto play is requested, the movie will be played at its preferred rate after being instantiated. If this atom is not present, the embedded movie will not automatically play.
kMovieMediaLoop: This atom contains a UInt8 that indicates how the embedded movie should loop. This atom is only used if the TimeBase of the embedded movie is not slaved to the parent movie (see the kMovieMediaSlaveTime atom for more information). If this atom contains a zero, or if this atom is not present, the embedded movie will not loop. If this atom contains a value of 1, the embedded movie will loop normally -- that is, when it reaches the end it will loop back to the beginning. If this atom contains a value of 2, the embedded movie will use palindrome looping. All other values are reserved.
kMovieMediaUseMIMEType: This atom contains text (not a C string or a pascal string) that indicates the MIME type of the movie import component that should be used to instantiate this media. This is useful in cases where the data reference may not contain MIME type information. If this atom is not present, the MIME type of the data reference as determined at instantiation time will be used. This atom is intended to allow content creators a method for working around MIME type binding problems. It should not typically be required, and should not be included in movie media samples by default.
kMovieMediaTitle: Currently unused. Would contain text indicating the name of the embedded movie.
kMovieMediaAltText: This atom contains text (not a C string or a pascal string) that is displayed to the user when the embedded movie is being instantiated or if the embedded movie cannot be instantiated. If this atom is not present, the name of the data reference (typically the file name) will be used.
kMovieMediaClipBegin: This atom contains a MovieMediaTimeRecord which indicates the time of the embedded movie that should be used. The clip begin atom provides a way to specify that a portion of the beginning of the embedded movie should not be used. If this atom is not present, the beginning of the embedded movie will not be changed. Note that this atom does not change the time at which the embedded movie begins playing in the parent movie's time line. If the time specified in the clip begin atom is greater than the duration of the embedded movie, then the embedded movie will not play at all.

struct MovieMediaTimeRecord { wide time; TimeScale scale; };

kMovieMediaClipDuration

This atom contains a MovieMediaTimeRecord which indicates the duration of the embedded movie that should be used. The clip duration atom is applied by removing media from end of the embedded movie. If the clip duration atom is not present, then no media is removed from the end of the embedded movie. In situations where the sample contains both a clip duration and a clip begin atom, the clip begin is applied first. If the clip duration specifies a value that is larger than the duration of the embedded movie, no change is made to the embedded movie.
kMovieMediaEnableFrameStepping: This atom contains a Boolean which indicates whether or not the embedded movie should be considered when performing step operations, specifically using the interesting time calls with the nextTimeStep flag. If this atom is not present or is set to false, the embedded movie is not included in step calculations. If the atom is set to true, it is included in step calculations.
kMovieMediaBackgroundColor: This atom contains an RGBColor which is used for filling the background when the movie is being instantiated or when it fails to instantiate.
kMovieMediaRegionAtom: This atom contains a number of child atoms, shown below, which describe how the Movie Media Handler should resize the embedded movie. If this atom is not present, the Movie Media Handler will resize the child movie to completely fill the containing track's box.
kMovieMediaRectangleAtom: This atom contains four child atoms that define a rectangle. Not all child atoms must be present: top and left must both appear together, width and height must both appear together. The dimensions contained in this rectangle are used in place of the track box when applying the contents of the spatial adjustment atom. If the top and left are not specified, the top and left of the containing track's box are used. If the width and height are not specified, the width and height of the containing track's box are used. Each child atom contains a UInt32.

Inside Macintosh: QuickTime Reference