CODEWITHSUNDEEP
ioscore-audioaudiounitaudiotoolbox
JackyJohnson
JackyJohnson

Reputation: 3126

AudioToolbox AUAudioFilePlayer properties description

I'm confused as to the following properties of AUAudioFilePlayer. The documentation from Apple is confusing at best:

  1. kAudioUnitProperty_ScheduleStartTimeStamp

  2. kAudioUnitProperty_ScheduledFilePrime

  3. kAudioUnitProperty_ScheduledFileRegion

Can someone please provide some clarification on each usage? It seems like their usage overlap? Thanks.

Upvotes: 2

Views: 580

Answers (1)

Nick
Nick

Reputation: 628

Yeah, it is confusing.

The StartTime is exactly what you'd think it is: it defines the beginning of the playback timeline for all slices/regions that you're scheduling for that audio unit.

Since the audio data needs to be pulled into RAM prior to playing, "priming" basically tells the system to begin reading the audio file (the specified number of frames) into memory.

You have the option of playing just a part of a file (beginning some number of frames into the file and/or ending some number of frames before the end of the file). These are called "regions" and this is the property you use if you want to play just a portion (or region) of an audio file.

Have a look at AudioUnitProperties.h:

Start Time

The audio unit will not play any slices following initialization or reset, until its start time has been set. The start time establishes the beginning of a timeline: the timestamps of all slices in the schedule are relative to the start time.

Set a start time by setting the kAudioUnitProperty_ScheduleStartTimeStamp property with an AudioTimeStamp structure. If the timestamp contains a valid sample time (timestamp.mFlags & kAudioTimeStampSampleTimeValid), then playback begins when the timestamp passed to the AudioUnitRender function reaches the specified sample time. If the specified sample time is -1, playback begins on the next render cycle.

If the start timestamp does not contain a valid sample time, but does contain a valid host time (timestamp.mFlags & kAudioTimeStampHostTimeValid), then the specified host time is translated to the sample time at which playback will begin. A host time of 0 means "start on the next render cycle."

The kAudioUnitProperty_ScheduleStartTimeStamp property may be queried to obtain the time at which playback began. If the start time has not yet been reached, the timestamp returned will be whatever the host application last set.

Priming

You should set kAudioUnitProperty_ScheduledFilePrime after scheduling initial file regions to be played and before starting playback. This SetProperty call will begin reading the audio files and not return until the number of frames specified by the property value have been read.

Scheduling Regions

To schedule the playback of a region of an audio file, set the kAudioUnitProperty_ScheduledFileRegion property. This is a ScheduledAudioFileRegion structure. mTimeStamp.mSampleTime must be valid and is interpreted relative to the unit's start time -- the start time semantics (using kAudioUnitProperty_ScheduleStartTimeStamp) are identical to those of AUScheduledSoundPlayer. Unlike the ScheduledAudioSlice structures, the unit makes copies of ScheduledAudioFileRegions, so you may create them on the stack or otherwise reuse/dispose of them immediately after scheduling them.

Upvotes: 2

Related Questions