Controlling the Audio Clock

When a task uses the audio clock to time audio events, it expects a default audio clock frequency of about 239.674 Hz. At that frequency, each audio tick lasts 184 DSP sample frames (approximately 4.172 milliseconds).

If a task wants to change that frequency for speeding up or slowing down clock-defined audio events or for getting finer or coarser timing control, the task must ask first to own the clock. It can then change the frequency by directly stating a new frequency or by defining a new audio tick duration in DSP frames. As long as the task owns the clock, no other task can change the clock's frequency.

Owning the Audio Clock

To make a task the owner of the audio clock, use this call:

Item OwnAudioClock( void )

It accepts no arguments and, when it executes, assigns clock ownership to the calling task. OwnAudioClock() returns the item number of a semaphore used to claim clock ownership. If unsuccessful, OwnAudioClock() returns a negative value (an error code). Store the returned semaphore item number; you need it to be able to make clock-changing calls.

Once a task owns the audio clock, that task alone can change the frequency of the clock. You may want your task to take ownership of the audio clock even if you do not want to change the clock rate. As owner of the clock, you can be sure that no other tasks can unexpectedly change the clock rate, an important safeguard if a stable clock rate is essential to the task's timing.

When a task is no longer concerned with the audio clock rate, it should give up ownership of the clock so that other tasks can own the clock if necessary. To do so, use this call:

Err DisownAudioClock( Item Owner )

The call accepts the item number of the clock semaphore. When executed, it takes back audio clock ownership from the calling task and makes clock ownership available to other tasks. It returns 0 if successful, or a negative value (an error code) if unsuccessful.

Setting the Audio Clock Rate

Once a task owns the audio clock, it can change the clock's frequency by directly specifying a new frequency or by specifying the length of each audio tick. To directly specify a new frequency, use this call:

Err SetAudioRate( Item Owner, frac16 Rate )

The call accepts two arguments: the item number of the clock semaphore and a frequency specified as a 16.16 value. The frequency must fall within the range of 60 to 1000 Hz.

When it executes, SetAudioRate() checks the semaphore number to be sure that it specifies clock ownership and, if so, the call changes the audio clock rate to the specified new frequency. If successful, SetAudioRate() returns 0; if unsuccessful, it returns a negative value (an error code).

If you set a high clock rate, the system performance can suffer. Try not to go much higher than 500 Hz.

A task that does not own the clock can successfully use this call as long as it has the proper semaphore item number. This means that the clock owning task can pass that number to a cooperating task (a thread or child task, for example) so that the second task can change the audio rate.

Setting Audio Tick Duration

A task can also change the audio clock frequency by specifying the length of the audio tick duration in DSP frames. To do so, use this call:

Err SetAudioDuration( Item Owner, uint32 Frames )

The call accepts the item number of the clock semaphore and the number of frames for which each audio tick should last. Tick duration can range from a minimum of 44 frames (which sets the frequency to approximately 1000 Hz) to a maximum of 735 frames (which sets the frequency to 60 Hz).

When it executes, SetAudioDuration() checks the semaphore number to be sure that it specifies clock ownership and, if so, changes the duration of the audio tick to the specified number of frames. If successful, the call returns 0; if unsuccessful, it returns a negative value (an error code).

SetAudioDuration() has the same setting limitations as SetAudioRate(). If you set a tick duration that's too short, the system performance can suffer. Note that SetAudioDuration() also accepts the correct ownership item from any task, so the clock owning task can pass that number to another cooperating task if it wishes.

Checking the Current Audio Clock Setting

If you need to know the audio clock's current frequency, use this call:

frac16 GetAudioRate( void )

The call accepts no arguments and returns the current frequency of the audio clock in Hertz as a 16.16 value.

To check the current duration of an audio tick, use this call:

uint32 GetAudioDuration( void )

The call accepts no arguments and returns the current duration in DSP frames of an audio tick.