Movie Clocks, Sound Clocks, and Video Output

This chapter describes how to set a movie’s master clock, how a movie’s default clock is chosen, the use of the sound clock, how to use SetMovieMasterClock with video output components, and the component capability flags defined for clock components.

Overview

Clock components are used by the Movie Toolbox for time bases. A movie master clock is what drives a movie’s time base.

A time base defines a movie’s current time value and the rate at which time passes for the movie. The rate specifies the speed and direction in which time travels in a movie. A time base also contains a reference to a clock which provides timing for the time base.

When an application opens a movie containing a sound track, QuickTime uses the sound clock as the movie master clock. The sound clock is a clock component provided directly by the selected audio output device, or (if the audio output device doesn’t provide one) a clock that simply watches the samples go by on their way out to the hardware and derives a clock from that.

In other words, if you play a movie containing audio and video media, the video will play at whatever rate the audio hardware is playing. If the movie lacks a sound track, QuickTime will use the system clock as the movie master clock.

The clock QuickTime chooses via this process is called the default clock.

You can obtain the clock component associated with a given media by calling MediaGetClock.

The component capability flags describe the capabilities of the clock component: specifically whether the clock keeps a constant rate (as opposed to drifting) and whether the component supports callback functions.

Setting and Changing the Master Clock

This section describes how to set and change the master clock associated with a movie time base.

You can obtain the clock component associated with a given media by calling MediaGetClock.

The ChooseMovieClock Function

ChooseMovieClock assigns a default clock to a movie. If you have changed a movie’s master clock with SetMovieMasterClock, or would like to reset a movie’s clock, use the ChooseMovieClock function.

Associated Components: The Video Output Component Clock

A Video Output Clock is the clock component associated with a specific video output component. This clock allows the time base used by a QuickTime movie to be driven by a specific output hardware device’s clock, in order to synchronize video and sound when the output device is in use.

An application can ask for the clock component associated with the video output component and use this clock as a movie’s master clock.

When using a Video Output Component, you can get an Instance of the Clock Component associated with the Video Output Component by calling QTVideoOutputGetClock.

Once you have this Clock Instance, it can be associated with a Movie by calling SetMovieMasterClock. Because a change to the display mode could affect a clock component, your application should call QTVideoOutputGetClock only between calls to the QTVideoOutputBegin and QTVideoOutputEnd functions.

When you want to reset the movie master clock back to the default clock, use ChooseMovieClock.

If you were previously using SetMovieMasterClock to reset a movies clock to the default clock, you should change to the new ChooseMovieClock method:

ChooseMovieClock(myMovie, 0);

Associated Components: Sound Output Component

A Sound Output Component is a software module that identifies, controls, and plays audio on a specific hardware device. Video output components, in addition to having a clock component, can have a Sound Output Component associated with them.

Developers can change the Sound Output Component used by a Media Handler by calling MediaSetSoundOutputComponent. This allows choosing between using the audio device associated with a video output device, another sound output device installed on the system, or the default sound output device.

Using the Sound Output Component Associated With the Video Output Component

To find the Sound Output Components associated with a Video Output Component use QTVideoOutputGetIndSoundOutput. Once the component is retrieved, call MediaSetSoundOutputComponent to set the sound output component for a media handler.

Component theSoundOut = 0;
ComponentInstance theVOutClock = NULL;
UnsignedFixed theSupportedAudioRate, myWantedAudioRate = eAudioRate48khz;
    ...
 
// Does this Video Output Component have a
// Sound Output Component associated with it?
if (ComponentFunctionImplemented(theInstance,
        kQTVideoOutputGetIndSoundOutputSelect)) {
    // Get the first sound output component associated
    // with the video output component
    err = QTVideoOutputGetIndSoundOutput(inVOComponentInstance,
                 1, &theSoundOut);
    if (err || 0 == theSoundOut) goto bail;
 
    // Not all sound output components support all sample
    // rates, use GetSoundOutputInfo with the siSampleRateAvailable
    // selector and figure it out
    theSupportedAudioRate = MyChooseAudioRate(myWantedAudioRate,
                                                theSoundOut);
 
    // Set the sample rate for the audio output
    err = SoundComponentSetInfo((ComponentInstance)theSoundOut,
                     NULL, siSampleRate, (void *)theSupportedAudioRate);
    if (err) goto bail;
 
    // For each audio tracks media set the sound output component
    for (i = 0;i < theNumberAudioTracks; i++) {
        err = MediaSetSoundOutputComponent(inAudioMediaHandlers[i],
                                                        theSoundOut);
        if (err) goto bail;
    }
}
 
// Use the Video Output Clock as the Master Clock
// Set up the video output clock after sound or it
// gets set back to the default clock
if (ComponentFunctionImplemented(inVOComponentInstance,
                                  kQTVideoOutputGetClockSelect)) {
    err = QTVideoOutputGetClock(inVOComponentInstance, &theVOutClock);
    if (err || NULL == theVOutClock) goto bail;
 
    SetMovieMasterClock(inMovie, (Component)theVOutClock, NULL);
}

Switching Back to the Default Sound Output Component

To switch back to the Default Sound Output Component, use MediaSetSoundOutputComponent and pass in NULL for the Component parameter.

// Set the Sound Output back to the Default Sound Output
for (i = 0;i < theNumberAudioTracks; i++) {
    err = MediaSetSoundOutputComponent(theAudioMediaHandler[i], NULL);
    if (err) goto bail;
}
 
// Switch back to the default clock
ChooseMovieClock(myMovie, 0);

Choosing the Clock

As mentioned in the section Associated Components: Sound Output Component, choosing a Sound Output Component will reset the master clock. Therefore, once you choose the Sound Output Component, you should then set up the movie’s master clock. You can either use the Video Output Clock (a logical choice when using a Video Output Component), or you could chose the default clock to provide audio and video sync for a movie.

When using the Video Output Clock, be sure to set the movie’s clock back to the default clock before calling QTVideoOutputEnd.

If you want to use the Video Output Clock, call SetMovieMasterClock and pass in the Video Output Clock Instance.

// Use the Video Output Clock as the Master Clock
// Set up the video output clock after sound or it
// gets set back to the default clock
if (ComponentFunctionImplemented(theVOComponentInstance,
                                  kQTVideoOutputGetClockSelect)) {
    err = QTVideoOutputGetClock(gVOComponentInstance, &theVOutClock);
    if (err || NULL == theVOutClock) goto bail;
 
    SetMovieMasterClock(myMovie, (Component)theVOutClock, NULL);
}

When choosing or switching to the Default Clock, use ChooseMovieClock.

// Use the default clock
ChooseMovieClock(myMovie, 0);

Remember, not all sound devices have clocks, and not all video output components have clock components associated with them, so be sure to check.

SetMovieMasterClock and ChooseMovieClock will cancel each other out; the last API called is the one that sets the clock.

MediaSetSoundOutputComponent can change the movie master clock.

Component Capability Flags for Clocks

The Component Manager allows a clock component to specify information about its capabilities in the componentFlags field of the component description structure. Apple has defined two component flags for clock components. These flags specify information about the capabilities of the clock component. The component author sets these flags in the componentFlags field of the component’s ComponentDescription structure. The following constants can be used to manipulate these flags. Clock component authors should set them appropriately for their clock.

enum {
    kClockRateIsLinear = 1,        /* clock keeps constant rate */
    kClockImplementsCallBacks = 2  /* clock supports callback events */
};

kClockRateIsLinear indicates that your clock maintains a constant rate. Most clocks that you deal with in the everyday world fall into this category. An example of a clock with an irregular rate is a clock that is dependent on the position of the Macintosh computer’s mouse; the clock’s rate might change depending upon where the user moves the mouse. Set this flag to 1 if your clock has a constant rate.

kClockImplementsCallBacks indicates that your clock supports callback events. Set this flag to 1 if your clock supports callback events.

You should set the componentFlags field appropriately in the component description structure that is associated with your clock component.



Copyright © 2005, 2018 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2018-06-04