|
ADC Home > Reference Library > Reference > Audio > Core Audio > Audio Toolbox Framework Reference
|
CoreAudioClock.h |
| Includes: |
CoreAudioClock APIs.
Provide services for audio and MIDI-related synchronization and time unit conversions.
CAClockAddListener |
Adds a callback function to receive notifications of changes to the clock's state.
extern OSStatus CAClockAddListener( CAClockRef inCAClock, CAClockListenerProc inListenerProc, void *inUserData);
inCAClockinListenerProcinUserDataAn OSStatus error code.
Note: The CAClockListenerProc may be called on a realtime thread internal to
the clock object.
CAClockArm |
Allow received sync messages to start the clock.
extern OSStatus CAClockArm( CAClockRef inCAClock);
inCAClockAn OSStatus error code.
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.
CAClockBarBeatTimeToBeats |
Converts a CABarBeatTime structure to a number of beats.
extern OSStatus CAClockBarBeatTimeToBeats( CAClockRef inCAClock, const CABarBeatTime *inBarBeatTime, CAClockBeats *outBeats);
inCAClockinBarBeatTimeoutBeatsAn OSStatus error code.
Converts a CABarBeatTime structure (bars/beats/subbeats) to a beat
position, using the clock's meter track.
CAClockBeatsToBarBeatTime |
Converts a number of beats to a CABarBeatTime structure.
extern OSStatus CAClockBeatsToBarBeatTime( CAClockRef inCAClock, CAClockBeats inBeats, UInt16 inSubbeatDivisor, CABarBeatTime *outBarBeatTime);
inCAClockinBeatsinSubbeatDivisoroutBarBeatTimeAn OSStatus error code.
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 |
CAClockDisarm |
Disallow received sync messages from starting the clock.
extern OSStatus CAClockDisarm( CAClockRef inCAClock);
inCAClockAn OSStatus error code.
CAClockDispose |
Dispose a clock object.
extern OSStatus CAClockDispose( CAClockRef inCAClock);
inCAClockAn OSStatus error code.
CAClockGetCurrentTempo |
Obtain the clock's current musical tempo.
extern OSStatus CAClockGetCurrentTempo( CAClockRef inCAClock, CAClockTempo *outTempo, CAClockTime *outTimestamp);
inCAClockoutTempooutTimestampAn OSStatus error code.
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.
CAClockGetCurrentTime |
Obtain the clock's current position on the media timeline.
extern OSStatus CAClockGetCurrentTime( CAClockRef inCAClock, CAClockTimeFormat inTimeFormat, CAClockTime *outTime);
inCAClockinTimeFormatoutTimeAn OSStatus error code.
CAClockGetPlayRate |
Obtain the clock's playback rate.
extern OSStatus CAClockGetPlayRate( CAClockRef inCAClock, Float64 *outPlayRate);
inCAClockoutPlayRateAn OSStatus error code.
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 1.0 means that it is running at exactly the same rate as the clock's timebase. (2.0 means twice as fast).
CAClockGetProperty |
Gets the current value of a clock's property.
extern OSStatus CAClockGetProperty( CAClockRef inCAClock, CAClockPropertyID inPropertyID, UInt32 *ioPropertyDataSize, void *outPropertyData);
inCAClockinPropertyIDioPropertyDataSizeoutPropertyDataAn OSStatus error code.
CAClockGetPropertyInfo |
Gets information about a clock's property.
extern OSStatus CAClockGetPropertyInfo( CAClockRef inCAClock, CAClockPropertyID inPropertyID, UInt32 *outSize, Boolean *outWritable);
inCAClockinPropertyIDoutSizeoutWritableAn OSStatus error code.
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);
inCAClockinTimeFormatoutTimeAn OSStatus error code.
CAClockNew |
Create a new clock object.
extern OSStatus CAClockNew( UInt32 inReservedFlags, CAClockRef *outCAClock);
inReservedFlagsoutCAClockAn OSStatus error code.
CAClockRemoveListener |
Removes a listener callback function.
extern OSStatus CAClockRemoveListener( CAClockRef inCAClock, CAClockListenerProc inListenerProc, void *inUserData);
inCAClockinListenerProcinUserDataAn OSStatus error code.
CAClockSecondsToSMPTETime |
Converts seconds to a SMPTE time representation.
extern OSStatus CAClockSecondsToSMPTETime( CAClockRef inCAClock, CAClockSeconds inSeconds, UInt16 inSubframeDivisor, SMPTETime *outSMPTETime);
inCAClockinSecondsinSubframeDivisoroutSMPTETimeAn OSStatus error code.
Converts seconds on the media timeline to a SMPTE time. The clock's current
SMPTE format and offset must be set appropriately.
CAClockSetCurrentTempo |
Manually override the clock's musical tempo during playback.
extern OSStatus CAClockSetCurrentTempo( CAClockRef inCAClock, CAClockTempo inTempo, const CAClockTime *inTimestamp);
inCAClockinTempoinTimestampAn OSStatus error code. If this call is made while stopped, kCAClock_CannotSetTimeError is returned.
Effects a manual override of the tempo map while running. After stopping and
restarting, the original tempo map will be used again.
CAClockSetCurrentTime |
Sets the clock's current position on the media timeline.
extern OSStatus CAClockSetCurrentTime( CAClockRef inCAClock, const CAClockTime *inTime);
inCAClockinTimeAn OSStatus error code.
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.
CAClockSetPlayRate |
Alter the clock's playback rate.
extern OSStatus CAClockSetPlayRate( CAClockRef inCAClock, Float64 inPlayRate);
inCAClockinPlayRateAn OSStatus error code.
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.
CAClockSetProperty |
Changes the value of a clock's property.
extern OSStatus CAClockSetProperty( CAClockRef inCAClock, CAClockPropertyID inPropertyID, UInt32 inPropertyDataSize, const void *inPropertyData);
inCAClockinPropertyIDinPropertyDataSizeinPropertyDataAn OSStatus error code.
CAClockSMPTETimeToSeconds |
Converts a SMPTE time representation to seconds.
extern OSStatus CAClockSMPTETimeToSeconds( CAClockRef inCAClock, const SMPTETime *inSMPTETime, CAClockSeconds *outSeconds);
inCAClockinSMPTETimeoutSecondsAn OSStatus error code.
Converts SMPTE time to seconds on the media timeline. The clock's current
SMPTE format and offset must be set appropriately.
CAClockStart |
Begin advancing the clock on its media timeline.
extern OSStatus CAClockStart( CAClockRef inCAClock);
inCAClockAn OSStatus error code.
CAClockStop |
Stop advancing the clock on its media timeline.
extern OSStatus CAClockStop( CAClockRef inCAClock);
inCAClockAn OSStatus error code.
CAClockTranslateTime |
Convert between time units.
extern OSStatus CAClockTranslateTime( CAClockRef inCAClock, const CAClockTime *inTime, CAClockTimeFormat inOutputTimeFormat, CAClockTime *outTime);
inCAClockinTimeinOutputTimeFormatoutTimeAn OSStatus error code.
CAClockBeats |
MIDI quarter notes (see MIDI specs)
typedef Float64 CAClockBeats;
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).
CAClockRef |
A reference to a Core Audio Clock object.
typedef struct OpaqueCAClock * CAClockRef;
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.
CAClockTempo |
A musical tempo in beats per minute.
typedef Float64 CAClockTempo; // beats per minute
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.
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).
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).
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.
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.
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).
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.
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.
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.
|