QuickTime Movie Properties Reference

Overview

QuickTime movies and movie tracks have properties that an application can manage, including embedded metadata and sample tables that determine what, how, and when the movie will present its data.

Functions by Task

Working With QuickTime Metadata

• QTCopyMediaMetaData
• QTCopyMovieMetaData
• QTCopyTrackMetaData
• QTMetaDataAddItem
• QTMetaDataGetItemProperty
• QTMetaDataGetItemPropertyInfo
• QTMetaDataGetItemValue
• QTMetaDataGetNextItem
• QTMetaDataGetProperty
• QTMetaDataGetPropertyInfo
• QTMetaDataRelease
• QTMetaDataRemoveItem
• QTMetaDataRemoveItemsWithKey
• QTMetaDataRetain
• QTMetaDataSetItem
• QTMetaDataSetItemProperty
• QTMetaDataSetProperty

Working With QuickTime Sample Tables

• QTSampleTableAddSampleDescription
• QTSampleTableAddSampleReferences
• QTSampleTableCopySampleDescription
• QTSampleTableCreateMutable
• QTSampleTableCreateMutableCopy
• QTSampleTableGetDataOffset
• QTSampleTableGetDataSizePerSample
• QTSampleTableGetDecodeDuration
• QTSampleTableGetDisplayOffset
• QTSampleTableGetNextAttributeChange
• QTSampleTableGetNumberOfSamples
• QTSampleTableGetProperty
• QTSampleTableGetPropertyInfo
• QTSampleTableGetSampleDescriptionID
• QTSampleTableGetSampleFlags
• QTSampleTableGetTimeScale
• QTSampleTableGetTypeID
• QTSampleTableRelease
• QTSampleTableReplaceRange
• QTSampleTableRetain
• QTSampleTableSetProperty
• QTSampleTableSetTimeScale

Supporting Functions

• DisposeQTTrackPropertyListenerUPP
• InvokeQTTrackPropertyListenerUPP
• MusicMediaGetIndexedTunePlayer
• NewQTTrackPropertyListenerUPP
• QTAddMoviePropertyListener
• QTAddTrackPropertyListener
• QTGetMovieProperty
• QTGetMoviePropertyInfo
• QTGetTrackProperty
• QTGetTrackPropertyInfo
• QTRemoveMoviePropertyListener
• QTRemoveTrackPropertyListener
• QTSetMovieProperty
• QTSetTrackProperty
• DisposeQTBandwidthNotificationUPP Deprecated in OS X v10.4
• NewQTBandwidthNotificationUPP Deprecated in OS X v10.4
• QTBandwidthRelease Deprecated in OS X v10.4
• QTBandwidthRequest Deprecated in OS X v10.4
• QTBandwidthRequestForTimeBase Deprecated in OS X v10.4
• QTScheduledBandwidthRelease Deprecated in OS X v10.4
• QTScheduledBandwidthRequest Deprecated in OS X v10.4

Functions

DisposeQTTrackPropertyListenerUPP

Disposes a track property listener UPP.

void DisposeQTTrackPropertyListenerUPP (
   QTTrackPropertyListenerUPP userUPP
);

InvokeQTTrackPropertyListenerUPP

Invokes the specified property listener of a track.

void InvokeQTTrackPropertyListenerUPP (
   Track inTrack,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   void *inUserData,
   QTTrackPropertyListenerUPP userUPP
);

MusicMediaGetIndexedTunePlayer

Undocumented

ComponentResult MusicMediaGetIndexedTunePlayer (
   ComponentInstance ti,
   long sampleDescIndex,
   ComponentInstance *tp
);

NewQTTrackPropertyListenerUPP

Creates a new callback to monitor a track property.

QTTrackPropertyListenerUPP NewQTTrackPropertyListenerUPP (
   QTTrackPropertyListenerProcPtr userRoutine
);

QTAddMoviePropertyListener

Installs a callback to monitor a movie property.

OSErr QTAddMoviePropertyListener (
   Movie inMovie,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   QTMoviePropertyListenerUPP inListenerProc,
   void *inUserData
);

QTAddTrackPropertyListener

Installs a callback to monitor a track property.

OSErr QTAddTrackPropertyListener (
   Track inTrack,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   QTTrackPropertyListenerUPP inListenerProc,
   void *inUserData
);

QTCopyMediaMetaData

Retains a media's metadata object and returns it.

OSStatus QTCopyMediaMetaData (
   Media inMedia,
   QTMetaDataRef *outMetaData
);

QTCopyMovieMetaData

Retains a movie's metadata object and returns it.

OSStatus QTCopyMovieMetaData (
   Movie inMovie,
   QTMetaDataRef *outMetaData
);

QTCopyTrackMetaData

Retains a track's metadata object and returns it.

OSStatus QTCopyTrackMetaData (
   Track inTrack,
   QTMetaDataRef *outMetaData
);

QTGetMovieProperty

Returns the value of a specific movie property.

OSErr QTGetMovieProperty (
   Movie inMovie,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   ByteCount inPropValueSize,
   QTPropertyValuePtr outPropValueAddress,
   ByteCount *outPropValueSizeUsed
);

QTGetMoviePropertyInfo

Returns information about the properties of a movie.

OSErr QTGetMoviePropertyInfo (
   Movie inMovie,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   QTPropertyValueType *outPropType,
   ByteCount *outPropValueSize,
   UInt32 *outPropertyFlags
);

QTGetTrackProperty

Returns the value of a specific track property.

OSErr QTGetTrackProperty (
   Track inTrack,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   ByteCount inPropValueSize,
   QTPropertyValuePtr outPropValueAddress,
   ByteCount *outPropValueSizeUsed
);

QTGetTrackPropertyInfo

Returns information about the properties of a track.

OSErr QTGetTrackPropertyInfo (
   Track inTrack,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   QTPropertyValueType *outPropType,
   ByteCount *outPropValueSize,
   UInt32 *outPropertyFlags
);

QTMetaDataAddItem

Adds an inline metadata item to the metadata storage format.

OSStatus QTMetaDataAddItem (
   QTMetaDataRef inMetaData,
   QTMetaDataStorageFormat inMetaDataFormat,
   QTMetaDataKeyFormat inKeyFormat,
   const UInt8 *inKeyPtr,
   ByteCount inKeySize,
   const UInt8 *inValuePtr,
   ByteCount inValueSize,
   UInt32 inDataType,
   QTMetaDataItem *outItem
);

QTMetaDataGetItemProperty

Returns a property of a metadata item.

OSStatus QTMetaDataGetItemProperty (
   QTMetaDataRef inMetaData,
   QTMetaDataItem inItem,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   ByteCount inPropValueSize,
   QTPropertyValuePtr outPropValueAddress,
   ByteCount *outPropValueSizeUsed
);

QTMetaDataGetItemPropertyInfo

Returns information about a property of a metadata item.

OSStatus QTMetaDataGetItemPropertyInfo (
   QTMetaDataRef inMetaData,
   QTMetaDataItem inItem,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   QTPropertyValueType *outPropType,
   ByteCount *outPropValueSize,
   UInt32 *outPropFlags
);

QTMetaDataGetItemValue

Returns the value of a metadata item from an item identifier.

OSStatus QTMetaDataGetItemValue (
   QTMetaDataRef inMetaData,
   QTMetaDataItem inItem,
   UInt8 *outValuePtr,
   ByteCount inValueSize,
   ByteCount *outActualSize
);

QTMetaDataGetNextItem

Returns the next metadata item corresponding to a specified key.

OSStatus QTMetaDataGetNextItem (
   QTMetaDataRef inMetaData,
   QTMetaDataStorageFormat inMetaDataFormat,
   QTMetaDataItem inCurrentItem,
   QTMetaDataKeyFormat inKeyFormat,
   const UInt8 *inKeyPtr,
   ByteCount inKeySize,
   QTMetaDataItem *outNextItem
);

QTMetaDataGetProperty

Returns a property of a metadata object.

OSStatus QTMetaDataGetProperty (
   QTMetaDataRef inMetaData,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   ByteCount inPropValueSize,
   QTPropertyValuePtr outPropValueAddress,
   ByteCount *outPropValueSizeUsed
);

QTMetaDataGetPropertyInfo

Returns information about a property of a metadata object.

OSStatus QTMetaDataGetPropertyInfo (
   QTMetaDataRef inMetaData,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   QTPropertyValueType *outPropType,
   ByteCount *outPropValueSize,
   UInt32 *outPropFlags
);

QTMetaDataRelease

Decrements the retain count of a metadata object.

void QTMetaDataRelease (
   QTMetaDataRef inMetaData
);

QTMetaDataRemoveItem

Removes a metadata item from a storage format.

OSStatus QTMetaDataRemoveItem (
   QTMetaDataRef inMetaData,
   QTMetaDataItem inItem
);

QTMetaDataRemoveItemsWithKey

Removes metadata items with a specific key from the storage format.

OSStatus QTMetaDataRemoveItemsWithKey (
   QTMetaDataRef inMetaData,
   QTMetaDataStorageFormat inMetaDataFormat,
   QTMetaDataKeyFormat inKeyFormat,
   const UInt8 *inKeyPtr,
   ByteCount inKeySize
);

QTMetaDataRetain

Increments the retain count of a metadata object.

QTMetaDataRef QTMetaDataRetain (
   QTMetaDataRef inMetaData
);

QTMetaDataSetItem

Sets the value of the metadata item from the item identifier.

OSStatus QTMetaDataSetItem (
   QTMetaDataRef inMetaData,
   QTMetaDataItem inItem,
   UInt8 *inValuePtr,
   ByteCount inValueSize,
   UInt32 inDataType
);

QTMetaDataSetItemProperty

Sets a property of a metadata item.

OSStatus QTMetaDataSetItemProperty (
   QTMetaDataRef inMetaData,
   QTMetaDataItem inItem,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   ByteCount inPropValueSize,
   ConstQTPropertyValuePtr inPropValueAddress
);

QTMetaDataSetProperty

Sets a property of a metadata object.

OSStatus QTMetaDataSetProperty (
   QTMetaDataRef inMetaData,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   ByteCount inPropValueSize,
   ConstQTPropertyValuePtr inPropValueAddress
);

QTRemoveMoviePropertyListener

Removes a movie property monitoring callback.

OSErr QTRemoveMoviePropertyListener (
   Movie inMovie,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   QTMoviePropertyListenerUPP inListenerProc,
   void *inUserData
);

QTRemoveTrackPropertyListener

Removes a track property monitoring callback

OSErr QTRemoveTrackPropertyListener (
   Track inTrack,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   QTTrackPropertyListenerUPP inListenerProc,
   void *inUserData
);

QTSampleTableAddSampleDescription

Adds a sample description to a sample table, returning a sample description ID that can be used to refer to it.

OSStatus QTSampleTableAddSampleDescription (
   QTMutableSampleTableRef sampleTable,
   SampleDescriptionHandle sampleDescriptionH,
   long mediaSampleDescriptionIndex,
   QTSampleDescriptionID *sampleDescriptionIDOut
);

QTSampleTableAddSampleReferences

Adds sample references to a sample table.

OSStatus QTSampleTableAddSampleReferences (
   QTMutableSampleTableRef sampleTable,
   SInt64 dataOffset,
   ByteCount dataSizePerSample,
   TimeValue64 decodeDurationPerSample,
   TimeValue64 displayOffset,
   SInt64 numberOfSamples,
   MediaSampleFlags sampleFlags,
   QTSampleDescriptionID sampleDescriptionID,
   SInt64 *newSampleNumOut
);

QTSampleTableCopySampleDescription

Retrieves a sample description from a sample table.

OSStatus QTSampleTableCopySampleDescription (
   QTSampleTableRef sampleTable,
   QTSampleDescriptionID sampleDescriptionID,
   long *mediaSampleDescriptionIndexOut,
   SampleDescriptionHandle *sampleDescriptionHOut
);

QTSampleTableCreateMutable

Creates a new, empty sample table.

OSStatus QTSampleTableCreateMutable (
   CFAllocatorRef allocator,
   TimeScale timescale,
   void *hints,
   QTMutableSampleTableRef *newSampleTable
);

QTSampleTableCreateMutableCopy

Copies a sample table.

OSStatus QTSampleTableCreateMutableCopy (
   CFAllocatorRef allocator,
   QTSampleTableRef sampleTable,
   void *hints,
   QTMutableSampleTableRef *newSampleTable
);

QTSampleTableGetDataOffset

Returns the data offset of a sample.

SInt64 QTSampleTableGetDataOffset (
   QTSampleTableRef sampleTable,
   SInt64 sampleNum
);

QTSampleTableGetDataSizePerSample

Returns the data size of a sample.

ByteCount QTSampleTableGetDataSizePerSample (
   QTSampleTableRef sampleTable,
   SInt64 sampleNum
);

QTSampleTableGetDecodeDuration

Returns the decode duration of a sample.

TimeValue64 QTSampleTableGetDecodeDuration (
   QTSampleTableRef sampleTable,
   SInt64 sampleNum
);

QTSampleTableGetDisplayOffset

Returns the offset from decode time to display time of a sample.

TimeValue64 QTSampleTableGetDisplayOffset (
   QTSampleTableRef sampleTable,
   SInt64 sampleNum
);

QTSampleTableGetNextAttributeChange

Finds the next sample number at which one or more of a set of given sample attributes change.

OSStatus QTSampleTableGetNextAttributeChange (
   QTSampleTableRef sampleTable,
   SInt64 startSampleNum,
   QTSampleTableAttribute attributeMask,
   SInt64 *sampleNumOut
);

QTSampleTableGetNumberOfSamples

Returns the number of samples in a sample table.

SInt64 QTSampleTableGetNumberOfSamples (
   QTSampleTableRef sampleTable
);

QTSampleTableGetProperty

Returns the value of a specific sample table property.

OSStatus QTSampleTableGetProperty (
   QTSampleTableRef sampleTable,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   ByteCount inPropValueSize,
   QTPropertyValuePtr outPropValueAddress,
   ByteCount *outPropValueSizeUsed
);

QTSampleTableGetPropertyInfo

Returns information about the properties of a sample table.

OSStatus QTSampleTableGetPropertyInfo (
   QTSampleTableRef sampleTable,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   QTPropertyValueType *outPropType,
   ByteCount *outPropValueSize,
   UInt32 *outPropertyFlags
);

QTSampleTableGetSampleDescriptionID

Returns the sample description ID of a sample.

QTSampleDescriptionID QTSampleTableGetSampleDescriptionID (
   QTSampleTableRef sampleTable,
   SInt64 sampleNum
);

QTSampleTableGetSampleFlags

Returns the media sample flags of a sample.

MediaSampleFlags QTSampleTableGetSampleFlags (
   QTSampleTableRef sampleTable,
   SInt64 sampleNum
);

QTSampleTableGetTimeScale

Returns the timescale of a sample table.

TimeScale QTSampleTableGetTimeScale (
   QTSampleTableRef sampleTable
);

QTSampleTableGetTypeID

Returns the CFTypeID value for the current sample table.

CFTypeID QTSampleTableGetTypeID (
   void
);

QTSampleTableRelease

Decrements the retain count of a sample table.

void QTSampleTableRelease (
   QTSampleTableRef sampleTable
);

QTSampleTableReplaceRange

Replaces a range of samples in a sample table with a range of samples from another sample table.

OSStatus QTSampleTableReplaceRange (
   QTMutableSampleTableRef destSampleTable,
   SInt64 destStartingSampleNum,
   SInt64 destSampleCount,
   QTSampleTableRef sourceSampleTable,
   SInt64 sourceStartingSampleNum,
   SInt64 sourceSampleCount
);

QTSampleTableRetain

Increments the retain count of a sample table.

QTSampleTableRef QTSampleTableRetain (
   QTSampleTableRef sampleTable
);

QTSampleTableSetProperty

Sets the value of a specific sample table property.

OSStatus QTSampleTableSetProperty (
   QTSampleTableRef sampleTable,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   ByteCount inPropValueSize,
   ConstQTPropertyValuePtr inPropValueAddress
);

QTSampleTableSetTimeScale

Changes the timescale of a sample table.

OSStatus QTSampleTableSetTimeScale (
   QTMutableSampleTableRef sampleTable,
   TimeScale newTimeScale
);

QTSetMovieProperty

Sets the value of a specific movie property.

OSErr QTSetMovieProperty (
   Movie inMovie,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   ByteCount inPropValueSize,
   ConstQTPropertyValuePtr inPropValueAddress
);

QTSetTrackProperty

Sets the value of a specific track property.

OSErr QTSetTrackProperty (
   Track inTrack,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   ByteCount inPropValueSize,
   ConstQTPropertyValuePtr inPropValueAddress
);

Callbacks

QTBandwidthNotificationProc

Undocumented

typedef OSErr (*QTBandwidthNotificationProcPtr) (long flags, void *reserved, void *refcon);

If you name your function MyQTBandwidthNotificationProc, you would declare it this way:

OSErr MyQTBandwidthNotificationProc (
   long    flags,
   void    *reserved,
   void    *refcon );

Data Types

QTBandwidthNotificationUPP

Represents a type used by the Movie Properties API.

typedef STACK_UPP_TYPE(QTBandwidthNotificationProcPtr) QTBandwidthNotificationUPP;

QTBandwidthReference

Represents a type used by the Movie Properties API.

typedef struct OpaqueQTBandwidthReference * QTBandwidthReference;

QTScheduledBandwidthPtr

Represents a type used by the Movie Properties API.

typedef QTScheduledBandwidthRecord * QTScheduledBandwidthPtr;

QTScheduledBandwidthRecord

Provides information to the QTScheduledBandwidthRequest function.

struct QTScheduledBandwidthRecord {
   long             recordSize;
   long             priority;
   long             dataRate;
   CompTimeValue    startTime;
   CompTimeValue    duration;
   TimeScale        scale;
   TimeBase         base;
};

Fields

recordSize

Discussion

The number of bytes in this structure.

priority

Discussion

Undocumented

dataRate

Discussion

The data rate.

startTime

Discussion

The bandwidth usage start time.

duration

Discussion

Duration of bandwidth usage, or 0 if unknown.

scale

Discussion

The timescale of the duration field.

base

Discussion

The time base.

QTScheduledBandwidthReference

Represents a type used by the Movie Properties API.

typedef struct OpaqueQTScheduledBandwidthReference * QTScheduledBandwidthReference;

Constants

kQTPropertyClass_SampleTable

Constants grouped with kQTPropertyClass_SampleTable.

enum {
   /*
   * Property class for sample tables.
   */
   kQTPropertyClass_SampleTable  = 'qtst',
   /*
   * The total decode duration of all samples in the sample table.
   * Read-only.
   */
   kQTSampleTablePropertyID_TotalDecodeDuration = 'tded', /* TimeValue64,
   Read */
   /*
   * The least display offset in the table. (-50 is a lesser offset
   * than 20.)  Read-only.
   */
   kQTSampleTablePropertyID_MinDisplayOffset = '<ddd', /* TimeValue64,
   Read */
   /*
   * The greatest display offset in the table. (20 is a greater offset
   * than -50.)  Read-only.
   */
   kQTSampleTablePropertyID_MaxDisplayOffset = '>ddd', /* TimeValue64,
   Read */
   /*
   * The least display time of all samples in the table,
   relative to
   * the decode time of the first sample in the table.  Read-only.
   */
   kQTSampleTablePropertyID_MinRelativeDisplayTime = '<dis', /* TimeValue64,
   Read */
   /*
   * The greatest display time of all samples in the table,
   relative to
   * the decode time of the first sample in the table.  Read-only.
   */
   kQTSampleTablePropertyID_MaxRelativeDisplayTime = '>dis' /* TimeValue64,
   Read */
};

QTSampleTableGetNextAttributeChange Values

Constants passed to QTSampleTableGetNextAttributeChange.

enum {
   /*
   * Set this flag to find first num such that samples num-1 and num
   * are not adjacent,
   ie,
   dataOffset of num-1 + dataSize of num-1 !=
   * dataOffset of num
   */
   kQTSampleTableAttribute_DiscontiguousData = 1L << 0,
   /*
   * Set this flag to find the first sample with data size per sample
   * different from that of the starting sample.
   */
   kQTSampleTableAttribute_DataSizePerSampleChange = 1L << 1,
   /*
   * Set this flag to find the first sample with decode duration
   * different from that of the starting sample.
   */
   kQTSampleTableAttribute_DecodeDurationChange = 1L << 2,
   /*
   * Set this flag to find the first sample with display offset
   * different from that of the starting sample.
   */
   kQTSampleTableAttribute_DisplayOffsetChange = 1L << 3,
   /*
   * Set this flag to find the first sample with sample description ID
   * different from that of the starting sample.
   */
   kQTSampleTableAttribute_SampleDescriptionIDChange = 1L << 4,
   /*
   * Set this flag to find the first sample with any media sample flags
   * different from those of the starting sample.
   */
   kQTSampleTableAttribute_SampleFlagsChange = 1L << 5,
   /*
   * If no flags are set,
   find the first sample with any attribute
   * different from the starting sample.
   */
   kQTSampleTableAnyAttributeChange = 0
};

QTSampleTableGetSampleFlags Values

Constants passed to QTSampleTableGetSampleFlags.

enum {
   mediaSampleNotSync            = 1 << 0, /* sample is not a sync sample (eg. is frame differenced */
   mediaSampleShadowSync         = 1 << 1, /* sample is a shadow sync */
   mediaSampleDroppable          = 1 << 27, /* sample is not required to be decoded for later samples to be decoded properly */
   mediaSamplePartialSync        = 1 << 16, /* sample is a partial sync (e.g.,
   I frame after open GOP) */
   mediaSampleHasRedundantCoding = 1 << 24, /* sample is known to contain redundant coding */
   mediaSampleHasNoRedundantCoding = 1 << 25, /* sample is known not to contain redundant coding */
   mediaSampleIsDependedOnByOthers = 1 << 26, /* one or more other samples depend upon the decode of this sample */
   mediaSampleIsNotDependedOnByOthers = 1 << 27, /* synonym for mediaSampleDroppable */
   mediaSampleDependsOnOthers    = 1 << 28, /* sample's decode depends upon decode of other samples */
   mediaSampleDoesNotDependOnOthers = 1 << 29, /* sample's decode does not depend upon decode of other samples */
   mediaSampleEarlierDisplayTimesAllowed = 1 << 30 /* samples later in decode order may have earlier display times */
};

Constants

mediaSampleNotSync

Returned for frame-differenced video sample data.

Available in OS X v10.0 and later.

Declared in Movies.h.