Important:
This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
Technical Note TN2198
Using the QuickTime 64-bit Timecode Media Handler
With the release of Mac OS X 10.5 and QuickTime 7.3, a new Timecode Media Handler supporting 64-bit counter values has been added to QuickTime. This Technical note discusses APIs and capabilities available with this new Timecode Media Handler allowing developers to work with 64-bit counter values.
Timecode media allows QuickTime movies to store additional timing information that is not created by or for QuickTime. This additional timing information is typically derived from the original source material for example, SMPTE timecode or audio sample rate. In essence, you can think of a timecode media as providing a link between QuickTime-specific timing information and the original timing information from the source material.
QuickTime has supplied a Timecode Media Handler (TimeCodeMediaType or 'tmcd') supporting a 32-bit counter since the release of QuickTime 2.0. With the release of Mac OS X 10.5 and QuickTime 7.3, a new Timecode Media Handler (TimeCode64MediaType or 'tc64') has been added supporting 64-bit counter values.
The new timecode media type (TimeCode64MediaType) uses an SInt64 to store timecode samples and can therefore be used in situations where the older TimeCodeMediaType would fail due to its 32-bit counter limit. For example, for audio sampled above 48kHz a 32-bit counter is insufficient to store all timecode values that are valid within a range of 24 hours.
The 64-bit TimeCode64MediaType media handler is implemented as a separate media handler component. The advantage is that the behavior and APIs offered by the original TimeCodeMediaType timecode media handler remain unchanged.
Developers with the need for a 64-bit counter can opt-in to using the TimeCode64MediaType media handler and corresponding APIs. This allows QuickTime to provide both the original timecode media support and the newer 64-bit timecode media enhancement without requiring developers to change existing code to deal with 64-bit samples.
No new data types or structures have been added to support TimeCode64MediaType media. Each media sample in the TimeCode64MediaType media is a 64-bit signed quantity; an SInt64 as defined in MacTypes.h.
The new APIs use existing data structures; TimeCodeDescription and TimeCodeDef from QuickTimeComponents.h, SMPTETime from CoreAudioTypes.h and return CFString's instead of pascal strings.
TimeCode64MediaType
// Movies.h
/* TimeCode64MediaType: 64-bit time code media */
enum {
TimeCode64MediaType = 'tc64'
};
TimeCode64Counter
// QuickTimeComponents.h
/* 64-bit counter */
typedef SInt64 TimeCode64Counter;
SMPTETime
// CoreAudioTypes.h
// SMPTETime
// A structure for holding a SMPTE time.
struct SMPTETime
{
SInt16 mSubframes; /* The number of subframes in the full message */
SInt16 mSubframeDivisor; /* The number of subframes per frame (typically 80) */
UInt32 mCounter; /* The total number of messages received */
UInt32 mType; /* The kind of SMPTE time using the SMPTE time type constants */
UInt32 mFlags; /* A set of flags that indicate the SMPTE state */
SInt16 mHours; /* The number of hours in the full message */
SInt16 mMinutes; /* The number of minutes in the full message */
SInt16 mSeconds; /* The number of seconds in the full message */
SInt16 mFrames; /* The number of frames in the full message */
};
TimeCodeDef
// QuickTimeComponents.h
// TimeCodeDef
// The timecode media sample description
struct TimeCodeDef {
long flags; /* Flags that provide timecode format information, such as drop-frame, etc.*/
TimeScale fTimeScale; /* Contains the time scale for interpreting the frameDuration field */
/* This field indicates the number of time units per second (eg. 2997) */
TimeValue frameDuration; /* Specifies how long each frame lasts, in the units defined by the */
/* fTimeScale field (eg. 100) */
UInt8 numFrames; /* Indicates the number of frames stored per second (eg. 30) OR In the case */
/* of timecodes that are interpreted as counters, this field indicates the */
/* number of frames stored per timer "tick" */
UInt8 padding; /* unused padding */
};
TimeCodeDescription
// QuickTimeComponents.h
// TimeCodeDescription
// The timecode media sample description
struct TimeCodeDescription {
long descSize; /* Specifies the size of the sample description, in bytes */
long dataFormat; /* Indicates the sample description type */
long resvd1; /* Set to 0 */
short resvd2; /* Set to 0 */
short dataRefIndex; /* Contains an index value indicating which of the media's data references */
/* contains the sample data for this sample description */
long flags; /* Reserved, set to 0 */
TimeCodeDef timeCodeDef; /* Contains a timecode definition structure that defines timecode */
/* format information */
long srcRef[1]; /* Contains the timecode's source information. This is formatted as a user data */
/* item that is stored in the sample description. The media handler provides */
/* functions that allow you to get and set this data */
The following APIs work with the TimeCode64MediaType media handler component and should only be used with TimeCode64MediaType media. They are not compatible with TimeCodeMediaType media and are not implemented in the older TimeCodeMediaType media handler.
These APIs may be called when using both the TimeCode64MediaType and the TimeCodeMediaType media handlers as they do not deal with media samples or strings.
TCGetSourceRef
HandlerError TCGetSourceRef(MediaHandler mh,
TimeCodeDescriptionHandle tcdH,
UserData *srefH)
Description:
Retrieves the source information from the timecode media sample reference.
Parameters:
mh - A timecode media handler. You obtain this identifier by calling GetMediaHandler. May be either the 32-bit
Timecode Media Handler or the 64-bit Timecode Media Handler.
tcdH - Specifies a handle to a TimeCodeDescription structure that defines the media sample reference for this
operation.
srefH - Specifies a pointer to a handle that will receive the source information as a UserDataRecord
structure. It is your responsibility to dispose of this structure when you are done with it.
TCSetSourceRef
HandlerError TCSetSourceRef(MediaHandler mh,
TimeCodeDescriptionHandle tcdH,
UserData srefH)
Description:
Changes the source information in the timecode media sample reference.
Parameters:
mh - A timecode media handler. You obtain this identifier by calling GetMediaHandler. May be either the 32-bit
Timecode Media Handler or the 64-bit Timecode Media Handler.
tcdH - Specifies a handle containing the timecode media sample reference that is to be updated.
srefH - Specifies a handle to the source information to be placed in the sample reference as a UserDataRecord
structure. It is your responsibility to dispose of this structure when you are done with it.
TCGetTimeCodeFlags
HandlerError TCGetTimeCodeFlags(MediaHandler mh,
long *flags)
Description:
Retrieves the timecode control flags.
Parameters:
mh - A timecode media handler. You obtain this identifier by calling GetMediaHandler. May be either the 32-bit
Timecode Media Handler or the 64-bit Timecode Media Handler.
flags - A pointer to a field that is to receive a control flag: tcdfShowTimeCode.
TCSetTimeCodeFlags
HandlerError TCSetTimeCodeFlags(MediaHandler mh,
long flags,
long flagsMask)
Description:
Changes the flag that affects how the toolbox handles timecode information.
Parameters:
mh - A timecode media handler. You obtain this identifier by calling GetMediaHandler. May be either the 32-bit
Timecode Media Handler or the 64-bit Timecode Media Handler.
flags - The new flag value. Can contain the control flag tcdfShowTimeCode.
flagsMask - Specifies which of the flag values are to change. The media handler modifies only those flag
values that correspond to bits that are set to 1 in this parameter. Use the flag values from the
flags parameter. To turn off timecode display, set the tcdfShowTimeCode flag to 1 in the flagsMask
parameter and to 0 in the flags parameter.
TCGetDisplayOptions
HandlerError TCGetDisplayOptions(MediaHandler mh,
TCTextOptionsPtr textOptions)
Description:
Retrieves the text characteristics that apply to timecode information displayed in a movie.
Parameters:
mh - A timecode media handler. You obtain this identifier by calling GetMediaHandler. May be either the 32-bit
Timecode Media Handler or the 64-bit Timecode Media Handler.
textOptions - A pointer to a TCTextOptions structure. This structure will receive font and style information.
TCSetDisplayOptions
HandlerError TCSetDisplayOptions(MediaHandler mh,
TCTextOptionsPtr textOptions)
Description:
Sets the text characteristics that apply to timecode information displayed in a movie.
Parameters:
mh - A timecode media handler. You obtain this identifier by calling GetMediaHandler. May be either the 32-bit
Timecode Media Handler or the 64-bit Timecode Media Handler.
textOptions - A pointer to a TCTextOptions structure. This structure contains font and style information.
You can create a timecode track and TimeCode64MediaType media in the same manner that you create any other track. Call NewMovieTrack to create the timecode track, and use NewTrackMedia to create the track’s media. Be sure to specify a media type value of TimeCode64MediaType when you call NewTrackMedia.
Listing 1 Create the track and media.
Track theTCTrack = 0;
Media theTCMedia = 0;
MediaHandler theTCMediaHandler;
...
// create a new track and TimeCode64MediaType media
The timecode media sample description contains the control information that allows QuickTime to interpret the samples. This includes the timecode format information. Each sample in the timecode track provides timecode information for a span of movie time and includes duration information.
The actual sample data contains a frame number that identifies one or more content frames that use this timecode. Stored as a SInt64, this value identifies the first frame in the group of frames that use this timecode.