CoreAudioClock APIs.
Provide services for audio and MIDI-related synchronization and time unit conversions.
CAClockNew |
Create a new clock object.
extern OSStatus CAClockNew( UInt32 inReservedFlags, CAClockRef *outCAClock);
inReservedFlags
- Must be 0.
outCAClock
- Must be non-null. On successful return, the new clock object.
CAClockDispose |
Dispose a clock object.
extern OSStatus CAClockDispose( CAClockRef inCAClock);
inCAClock
- The clock object to be disposed.
CAClockGetPropertyInfo |
Gets information about a clock's property.
extern OSStatus CAClockGetPropertyInfo( CAClockRef inCAClock, CAClockPropertyID inPropertyID, UInt32 *outSize, Boolean *outWritable);
inCAClock
- The clock object.
inPropertyID
- The property being queried.
outSize
- If non-null, on exit, this is set to the size of the property's value.
outWritable
- If non-null, on exit, this indicates whether the property value is settable.
CAClockGetProperty |
Gets the current value of a clock's property.
extern OSStatus CAClockGetProperty( CAClockRef inCAClock, CAClockPropertyID inPropertyID, UInt32 *ioPropertyDataSize, void *outPropertyData);
inCAClock
- The clock object.
inPropertyID
- The property being fetched.
ioPropertyDataSize
- On entry, the size (in bytes) of the memory pointed to by outPropertyData. On exit, the actual size of the property data returned.
outPropertyData
- The value of the property is copied to the memory this points to.
CAClockSetProperty |
Changes the value of a clock's property.
extern OSStatus CAClockSetProperty( CAClockRef inCAClock, CAClockPropertyID inPropertyID, UInt32 inPropertyDataSize, const void *inPropertyData);
inCAClock
- The clock object.
inPropertyID
- The property being set.
inPropertyDataSize
- The size of the property data, in bytes.
inPropertyData
- Points to the property's new value.
CAClockAddListener |
Adds a callback function to receive notifications of changes to the clock's state.
extern OSStatus CAClockAddListener( CAClockRef inCAClock, CAClockListenerProc inListenerProc, void *inUserData);
inCAClock
- The clock object.
inListenerProc
- The callback function.
inUserData
- This value is passed to the callback function, in the userData parameter.
Note: The CAClockListenerProc may be called on a realtime thread internal to
the clock object.
CAClockRemoveListener |
Removes a listener callback function.
extern OSStatus CAClockRemoveListener( CAClockRef inCAClock, CAClockListenerProc inListenerProc, void *inUserData);
inCAClock
- The clock object.
inListenerProc
- The callback function.
inUserData
- The same value as was passed for inUserData when this function was registered with CAClockAddListener. (This allows a single callback function to be registered more than once, with different userData arguments.)
CAClockSetCurrentTime |
Sets the clock's current position on the media timeline.
extern OSStatus CAClockSetCurrentTime( CAClockRef inCAClock, const CAClockTime *inTime);
inCAClock
- The clock object.
inTime
- The new time position.
Call this to specify where on the media timeline playback will begin. The
supplied time must be in seconds, beats, or SMPTE (not host time or audio
samples). Must only be called when stopped.
CAClockGetCurrentTime |
Obtain the clock's current position on the media timeline.
extern OSStatus CAClockGetCurrentTime( CAClockRef inCAClock, CAClockTimeFormat inTimeFormat, CAClockTime *outTime);
inCAClock
- The clock object.
inTimeFormat
- Specifies the desired format for outTime.
outTime
- On exit, the clock's current time position.
CAClockGetStartTime |
Obtain the position on the media timeline where playback will start, or has already started.
extern OSStatus CAClockGetStartTime( CAClockRef inCAClock, CAClockTimeFormat inTimeFormat, CAClockTime *outTime);
inCAClock
- The clock object.
inTimeFormat
- Specifies the desired format for outTime.
outTime
- On exit, the clock's start time position.
CAClockTranslateTime |
Convert between time units.
extern OSStatus CAClockTranslateTime( CAClockRef inCAClock, const CAClockTime *inTime, CAClockTimeFormat inOutputTimeFormat, CAClockTime *outTime);
inCAClock
- The clock object.
inTime
- The time to be converted.
inOutputTimeFormat
- Specifies the desired format for outTime
outTime
- On exit, a time corresponding to inTime, converted to the desired time format.
CAClockStart |
Begin advancing the clock on its media timeline.
extern OSStatus CAClockStart( CAClockRef inCAClock);
inCAClock
- The clock object.
CAClockStop |
Stop advancing the clock on its media timeline.
extern OSStatus CAClockStop( CAClockRef inCAClock);
inCAClock
- The clock object.
CAClockArm |
Allow received sync messages to start the clock.
extern OSStatus CAClockArm( CAClockRef inCAClock);
inCAClock
- The clock object.
If a clock is slaved to an external transport (e.g. MIDI Time Code),
call this to indicate that the client is ready to start its transport in response
to the external transport having started.
The external time source will set the clock's start position and start
the clock.
CAClockDisarm |
Disallow received sync messages from starting the clock.
extern OSStatus CAClockDisarm( CAClockRef inCAClock);
inCAClock
- The clock object.
CAClockSetPlayRate |
Alter the clock's playback rate.
extern OSStatus CAClockSetPlayRate( CAClockRef inCAClock, Float64 inPlayRate);
inCAClock
- The clock object.
inPlayRate
- The clock's desired play rate.
Adjusts the ratio between the timebase and media time; e.g. at 0.5, the
media time will move half as quickly as timebase time.
CAClockGetPlayRate |
Obtain the clock's playback rate.
extern OSStatus CAClockGetPlayRate( CAClockRef inCAClock, Float64 *outPlayRate);
inCAClock
- The clock object.
outPlayRate
- On exit, the clock's playback rate.
Returns the clock's current play rate. If the clock is internally synced,
this will be the last rate set by CAClockSetPlayRate. If the clock is
externally synced, it will be the rate of the external sync source, where
timebase. (2.0 means twice as fast).
CAClockGetCurrentTempo |
Obtain the clock's current musical tempo.
extern OSStatus CAClockGetCurrentTempo( CAClockRef inCAClock, CAClockTempo *outTempo, CAClockTime *outTimestamp);
inCAClock
- The clock object.
outTempo
- On exit, the current tempo.
outTimestamp
- If non-null, on exit, the time at which the tempo last changed.
Returns the current instantaneous tempo and a timestamp indicating where on the
timeline the tempo most recently changed.
If the clock is externally synced, the returned tempo will not reflect the
effective tempo; this routine always reflects the client-specified tempo. To
obtain the effective tempo, multiply the current tempo by the current play
rate.
CAClockSetCurrentTempo |
Manually override the clock's musical tempo during playback.
extern OSStatus CAClockSetCurrentTempo( CAClockRef inCAClock, CAClockTempo inTempo, const CAClockTime *inTimestamp);
inCAClock
- The clock object.
inTempo
- The new desired tempo.
inTimestamp
- Specifies a precise point on the timeline where the tempo change is to take effect. If null, the tempo change takes effect immediately.
Effects a manual override of the tempo map while running. After stopping and
restarting, the original tempo map will be used again.
CAClockSecondsToSMPTETime |
Converts seconds to a SMPTE time representation.
extern OSStatus CAClockSecondsToSMPTETime( CAClockRef inCAClock, CAClockSeconds inSeconds, UInt16 inSubframeDivisor, SMPTETime *outSMPTETime);
inCAClock
- The clock object.
inSeconds
- The number of seconds to be converted (e.g. 3600 = 1 hour).
inSubframeDivisor
- The number of subframes per frame desired in outSMPTETime.
outSMPTETime
- On exit, the SMPTE time corresponding to inSeconds.
Converts seconds on the media timeline to a SMPTE time. The clock's current
SMPTE format and offset must be set appropriately.
CAClockSMPTETimeToSeconds |
Converts a SMPTE time representation to seconds.
extern OSStatus CAClockSMPTETimeToSeconds( CAClockRef inCAClock, const SMPTETime *inSMPTETime, CAClockSeconds *outSeconds);
inCAClock
- The clock object.
inSMPTETime
- The SMPTE time to be converted to seconds.
outSeconds
- On exit, the number of seconds corresponding to inSMPTETime.
Converts SMPTE time to seconds on the media timeline. The clock's current
SMPTE format and offset must be set appropriately.
CAClockBeatsToBarBeatTime |
Converts a number of beats to a CABarBeatTime structure.
extern OSStatus CAClockBeatsToBarBeatTime( CAClockRef inCAClock, CAClockBeats inBeats, UInt16 inSubbeatDivisor, CABarBeatTime *outBarBeatTime);
inCAClock
- The clock object.
inBeats
- The absolute beat count to be converted.
inSubbeatDivisor
- The number of units per beat.
outBarBeatTime
- On exit, the bar/beat/subbeat time corresponding to inBeats.
Converts a beat position on the media timeline to a CABarBeatTime, using the clock's meter track. Examples using 4/4 time and a subbeat divisor of 480:
inBeats | outBarBeatTime: bars . beats . units |
---|---|
0 | 1.1.0 |
1 | 1.2.0 |
4 | 2.1.0 |
4.5 | 2.1.240 |
CAClockBarBeatTimeToBeats |
Converts a CABarBeatTime structure to a number of beats.
extern OSStatus CAClockBarBeatTimeToBeats( CAClockRef inCAClock, const CABarBeatTime *inBarBeatTime, CAClockBeats *outBeats);
inCAClock
- The clock object.
inBarBeatTime
- The bar/beat/subunit time to be converted to beats.
outBeats
- On exit, the number of absolute beats corresponding to inBarBeatTime.
Converts a CABarBeatTime structure (bars/beats/subbeats) to a beat
position, using the clock's meter track.
CAClockSMPTEFormat |
A SMPTE format, specifying the frames per second (fps) and whether it is drop frame.
typedef UInt32 CAClockSMPTEFormat;
The possible values of a CAClockSMPTEFormat are found in
<CoreAudio/CoreAudioTypes.h>
. Values include
kSMPTETimeType30, kSMPTETimeType30Drop, etc. Note that formats with more
than 30 fps are not usable with MIDI Time Code.
CAClockRef |
A reference to a Core Audio Clock object.
typedef struct OpaqueCAClock * CAClockRef;
CAClockBeats |
MIDI quarter notes (see MIDI specs)
typedef Float64 CAClockBeats;
CAClockTempo |
A musical tempo in beats per minute.
typedef Float64 CAClockTempo; // beats per minute
CAClockListenerProc |
A client-supplied function called when the clock's state changes.
typedef void (*CAClockListenerProc)( void *userData, CAClockMessage message, const void *param);
userData
- The value passed to CAClockAddListener when the callback function was installed.
message
- Signifies the kind of event which occurred.
param
- This value is specific to the message (currently no messages have values).
CAClockTime |
Represents a time value using one of several possible units.
struct CAClockTime { CAClockTimeFormat format; UInt32 reserved; union { UInt64 hostTime; CAClockSamples samples; CAClockBeats beats; CAClockSeconds seconds; SMPTETime smpte; } time; };
format
- Specifies the time's format and units.
reserved
- Must be 0.
time
- The time value. Use the member of the union appropriate to the format (see the description of CAClockTimeFormat).
CABarBeatTime |
A display representation of a musical time in beats.
struct CABarBeatTime { SInt32 bar; UInt16 beat; UInt16 subbeat; UInt16 subbeatDivisor; UInt16 reserved; };
bar
- A measure number.
beat
- A beat number (1..n).
subbeat
- The numerator of the fractional number of beats.
subbeatDivisor
- The denominator of the fractional number of beats.
reserved
- Must be 0.
A clock's internal representation of musical time is in beats based on the
beginning of the timeline. Normally, such times should be displayed to the user
in terms of bars, beats, and subbeats (sometimes called "units" or "parts per
quarter" [PPQ]). This data structure is such a display representation.
By convention, bar 1 is the beginning of the sequence. Beat 1 is the first beat
of the measure. In 4/4 time, beat will have a value from 1 to 4. Music
applications often use beat divisions such as 480 and 960.
CATempoMapEntry |
A tempo change event.
struct CATempoMapEntry { CAClockBeats beats; CAClockTempo tempoBPM; // beats per minute };
beats
- The beat time at which the tempo changes.
tempoBPM
- The new tempo as of that time.
The clock's tempo map defines the correspondence between seconds and musical beats, and is used in conversions between the two.
CAMeterTrackEntry |
A time signature change event.
struct CAMeterTrackEntry { CAClockBeats beats; UInt16 meterNumer; UInt16 meterDenom; // 1,2,4,8 etc. };
beats
- The beat time at which the time signature (meter) changes.
meterNum
- The numerator of the new time signature.
meterDenom
- The denominator of the new time signature (1, 2, 4, 8, etc.).
The meter track is used for converting between beats as floating-point numbers (CAClockBeats) and their display representations (CABarBeatTime).
CAClockPropertyID |
The properties of a CoreAudioClock, accessible via CAClockGetProperty and CAClockSetProperty.
enum { // typedef UInt32 CAClockPropertyID; kCAClockProperty_InternalTimebase = 'intb', kCAClockProperty_TimebaseSource = 'itbs', kCAClockProperty_SyncMode = 'synm', kCAClockProperty_SyncSource = 'syns', kCAClockProperty_SMPTEFormat = 'smpf', kCAClockProperty_SMPTEOffset = 'smpo', kCAClockProperty_MIDIClockDestinations = 'mbcd', kCAClockProperty_MTCDestinations = 'mtcd', kCAClockProperty_MTCFreewheelTime = 'mtfw', kCAClockProperty_TempoMap = 'tmpo', kCAClockProperty_MeterTrack = 'metr', kCAClockProperty_Name = 'name' };
kCAClockProperty_InternalTimebase
- Type: CAClockTimebase. Selects the internal time reference for the clock (currently, host time, an audio device, or audio output unit).
kCAClockProperty_TimebaseSource
- Type: according to the internal timebase. If the timebase is kCAClockTimebase_AudioDevice, the value is an AudioDeviceID. For kCAClockTimebase_AudioOutputUnit, the value is an AudioUnit.
kCAClockProperty_SyncMode
- Type: CAClockSyncMode. Selects between internal synchronization and multiple external synchronization modes such as MIDI Time Code and MIDI beat clock.
kCAClockProperty_SyncSource
- Type: according to the sync mode. For kCAClockSyncMode, the value is a MIDIEndpointRef.
kCAClockProperty_SMPTEFormat
- Type: CAClockSMPTEFormat. Specifies the SMPTE format (fps, drop or non-drop) expected for received SMPTE messages, and used for transmitted SMPTE messages and SMPTE time representations.
kCAClockProperty_SMPTEOffset
- Type: CAClockSeconds. The SMPTE time, represented in seconds since 00:00:00:00, corresponding to a timeline position of 0 seconds.
kCAClockProperty_MIDIClockDestinations
- Type: array of MIDIEndpointRef. When non-empty, the clock will transmit MIDI beat clock to the MIDI endpoints in this list.
kCAClockProperty_MTCDestinations
- Type: array of MIDIEndpointRef. When non-empty, the clock will transmit MIDI Time Code to the MIDI endpoints in this list.
kCAClockProperty_MTCFreewheelTime
- Type: CAClockSeconds. When the sync mode is MIDI Time Code, this controls how long the reader will keep running after the last MTC message is received before stopping (default: 1 sec). Should be at least ~4 SMPTE frames in duration.
kCAClockProperty_TempoMap
- Type: array of CATempoMapEntry. Specifies a tempo map for the clock, defining the relationship between timeline positions in seconds and musical beats. Defaults to a constant tempo of 120 bpm.
kCAClockProperty_MeterTrack
- Type: array of CAMeterTrackEntry. Specifies the positions of musical time signature changes in the timeline. Used only for converting between beats and CABarBeatTime's (a display representaiton of a beat time).
kCAClockProperty_Name
- Type: CFStringRef. Sets a name for the clock. When a client sets the property, the clock retains a reference to the string. When a client gets the property, it receives a borrowed reference (i.e. the client must not release the string).
CAClockTimebase |
The available internal hardware time references for a clock.
enum { // typedef UInt32 CAClockTimebase; kCAClockTimebase_HostTime = 'host', kCAClockTimebase_AudioDevice = 'audi', kCAClockTimebase_AudioOutputUnit = 'auou' };
kCAClockTimebase_HostTime
- The clock's reference time is host time (as returned by
mach_absolute_time()
orHostTime()
).kCAClockTimebase_AudioDevice
- The clock's reference time is derived from an audio device.
kCAClockTimebase_AudioOutputUnit
- The clock's reference time is derived from the audio device addressed by an output Audio Unit.
CAClockSyncMode |
Specifies internal synchronization, or an external sync source type.
enum { // typedef UInt32 CAClockSyncMode; kCAClockSyncMode_Internal = 'intr', // sync to the internal timebase kCAClockSyncMode_MIDIClockTransport = 'mclk', // sync to MIDI beat clock, external transport kCAClockSyncMode_MTCTransport = 'mmtc' // sync to MIDI Time Code, external transport };
kCAClockSyncMode_Internal
- The clock is not driven by an external sync source.
kCAClockSyncMode_MIDIClockTransport
- The clock is driven by MIDI beat clock received from a CoreMIDI source endpoint.
kCAClockSyncMode_MTCTransport
- The clock is driven by MIDI Time Code received from a CoreMIDI source endpoint.
CAClockMessage |
The messages sent to a CAClockListenerProc to notify the client of changes to the clock's state.
enum { // typedef UInt32 CAClockMessage; kCAClockMessage_StartTimeSet = 'stim', kCAClockMessage_Started = 'strt', kCAClockMessage_Stopped = 'stop', kCAClockMessage_Armed = 'armd', kCAClockMessage_Disarmed = 'darm', kCAClockMessage_PropertyChanged = 'pchg', kCAClockMessage_WrongSMPTEFormat = '?smp' };
kCAClockMessage_StartTimeSet
- A new start time was set or received from an external sync source.
kCAClockMessage_Started
- The clock's time has started moving.
kCAClockMessage_Stopped
- The clock's time has stopped moving.
kCAClockMessage_Armed
- The client has called CAClockArm().
kCAClockMessage_Disarmed
- The client has called CAClockDisarm().
kCAClockMessage_PropertyChanged
- A clock property has been changed.
kCAClockMessage_WrongSMPTEFormat
- The clock is receiving SMPTE (MTC) messages in a SMPTE format that does not match the clock's SMPTE format.
CAClockTimeFormat |
The various units in which a clock can represent and report time.
enum { // typedef UInt32 CAClockTimeFormat; kCAClockTimeFormat_HostTime = 'host', kCAClockTimeFormat_Samples = 'samp', kCAClockTimeFormat_Beats = 'beat', // relative position on media timeline kCAClockTimeFormat_Seconds = 'secs', // relative position on media timeline kCAClockTimeFormat_SMPTESeconds = 'smps', // absolute SMPTE position in seconds kCAClockTimeFormat_SMPTETime = 'smpt' // SMPTETime structure };
kCAClockTimeFormat_HostTime
- Absolute host time, as returned by
mach_absolute_time()
.kCAClockTimeFormat_Samples
- Absolute audio samples, as a Float64. Available when the internal timebase is an audio device (or audio output unit). The units are in arbitrary sample numbers, corresponding to the audio device's current time, and at the device's current sample rate.
kCAClockTimeFormat_Beats
- Musical beats, as a Float64. This is a position on the clock's timeline.
kCAClockTimeFormat_Seconds
- Seconds, as a Float64. This is a position on the clock's timeline.
kCAClockTimeFormat_SMPTESeconds
- Seconds, as a Float64. This is the same as kCAClockTimeFormat_Seconds, except that the clock's SMPTE offset has been applied.
kCAClockTimeFormat_SMPTETime
- SMPTETime structure.
(Last Updated July 18, 2005)