Technical Note TN2052

ChooseMovieClock and Video Output Components

CONTENTS Who's your Master Clock? The ChooseMovieClock API Associated Components - The Video Output Component Clock Using the associated Video Output Clock Associated Components - Sound Output component Using the associated Sound Output Component Switching back to the Default Sound Output Component Choosing the Clock Using the Video Output Component Clock Switching back to the Default Clock Caveats Sample Code References Downloadables

This technote discusses the ChooseMovieClock API introduced in QuickTime 6. It explains how this call should be used with Video Output Components and in instances where SetMovieMasterClock was previously being used to reset a movie's clock. This information is primarily for developers using Video Output Component or modifying a movie's master clock by calling SetMovieMasterClock. [May 07 2002]

Who's your Master Clock?

Clock components provide time related services, and 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. See Time and the Movie Toolbox for more information.

When an application opens a movie containing a sound track, QuickTime will use the "sound clock" as the movie master clock. This "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.

We'll call the Clock QuickTime chooses via this process the Default Clock.

Back to top

The ChooseMovieClock API

ChooseMovieClock will assign 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 API.

    void ChooseMovieClock( Movie m, long flags );

Back to top

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.

Back to top

Using the Video Output Component Clock

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 QTVideoOutputBegin and QTVideoOutputEnd.

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);

Back to top

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.

It should be noted that calling MediaSetSoundOutputComponent can change the movie master clock.

Back to top

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);
}

Back to top

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);

Back to top

Choosing the Clock

As mentioned in the above 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.

Back to top

Using the Video Output Component Clock

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);
}

Back to top

Switching back to the Default Clock

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

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

Back to top

Caveats

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. Therefore, setting the Movie Master Clock to the Video Output Clock MUST be done after setting up the Sound Output Device or it gets set back to the default clock.

Back to top

Sample Code

SimpleVideoOut

SoftVideoOutputComponent / SoftCodec Transfer Codec

Back to top

References

Video Output Components

Transfer Codecs for Video Output Components

Accelerated Video Support

Time and the Movie Toolbox

About Clock Components

Back to top

Downloadables

Back to top