Functions


ExtAudioFileOpen
Opens an audio file.
ExtAudioFileWrapAudioFileID
Wrap an AudioFileID in an ExtAudioFileRef.
ExtAudioFileCreateNew
Create a new audio file.
ExtAudioFileDispose
Close the file and dispose the object.
ExtAudioFileRead
Perform a synchronous sequential read.
ExtAudioFileWrite
Perform a synchronous sequential write.
ExtAudioFileWriteAsync
Perform an asynchronous sequential write.
ExtAudioFileSeek
Seek to a specific frame position.
ExtAudioFileTell
Return the file's read/write position.
ExtAudioFileGetPropertyInfo
Get information about a property
ExtAudioFileGetProperty
Get a property value.
ExtAudioFileSetProperty
Set a property value.

ExtAudioFileOpen


Opens an audio file.

extern OSStatus ExtAudioFileOpen(
    const FSRef *inFSRef, 
    ExtAudioFileRef *outExtAudioFile); 
Parameter Descriptions
inFSRef
The audio file to read.
outExtAudioFile
On exit, a newly-allocated ExtAudioAudioFileRef.
function result
An OSStatus error code.

Discussion

Allocates a new ExtAudioFileRef, for reading an existing audio file.

Availability
Introduced in Mac OS X 10.4.

ExtAudioFileWrapAudioFileID


Wrap an AudioFileID in an ExtAudioFileRef.

extern OSStatus ExtAudioFileWrapAudioFileID(
    AudioFileID inFileID, 
    Boolean inForWriting, 
    ExtAudioFileRef *outExtAudioFile) ; 
Parameter Descriptions
inFileID
The AudioFileID to wrap.
inForWriting
True if the AudioFileID is a new file opened for writing.
outExtAudioFile
On exit, a newly-allocated ExtAudioAudioFileRef.
function result
An OSStatus error code.

Discussion

Allocates a new ExtAudioFileRef which wraps an existing AudioFileID. The client is responsible for keeping the AudioFileID open until the ExtAudioFileRef is disposed.

Availability
Introduced in Mac OS X 10.4.

ExtAudioFileCreateNew


Create a new audio file.

extern OSStatus ExtAudioFileCreateNew(
    const FSRef *inParentDir, 
    CFStringRef inFileName, 
    AudioFileTypeID inFileType, 
    const AudioStreamBasicDescription *inStreamDesc, 
    const AudioChannelLayout *inChannelLayout, 
    ExtAudioFileRef *outExtAudioFile) ; 
Parameter Descriptions
inParentDir
The directory in which to create the new file.
inFileName
The name of the new file.
inFileType
The type of file to create. This is a constant from AudioToolbox/AudioFile.h, e.g. kAudioFileAIFFType. Note that this is not an HFSTypeCode.
inStreamDesc
The format of the audio data to be written to the file.
inChannelLayout
The channel layout of the audio data. If non-null, this must be consistent with the number of channels specified by inStreamDesc.
outExtAudioFile
On exit, a newly-allocated ExtAudioAudioFileRef.
function result
An OSStatus error code.

Discussion

Creates a new audio file.

If the file to be created is in an encoded format, it is permissible for the sample rate in inStreamDesc to be 0, since in all cases, the file's encoding AudioConverter may produce audio at a different sample rate than the source. The file will be created with the audio format actually produced by the encoder.

Availability
Introduced in Mac OS X 10.4.

ExtAudioFileDispose


Close the file and dispose the object.

extern OSStatus ExtAudioFileDispose(
    ExtAudioFileRef inExtAudioFile) ; 
Parameter Descriptions
inExtAudioFile
The extended audio file object.
function result
An OSStatus error code.

Discussion

Closes the file and deletes the object. If no frames were written to an ExtAudioFile allocated by ExtAudioFileCreateNew, the output file is deleted.

Availability
Introduced in Mac OS X 10.4.

ExtAudioFileRead


Perform a synchronous sequential read.

extern OSStatus ExtAudioFileRead(
    ExtAudioFileRef inExtAudioFile, 
    UInt32 *ioNumberFrames, 
    AudioBufferList *ioData) ; 
Parameter Descriptions
inExtAudioFile
The extended audio file object.
ioNumberFrames
On entry, ioNumberFrames is the number of frames to be read from the file. On exit, it is the number of frames actually read. A number of factors may cause a fewer number of frames to be read, including the supplied buffers not being large enough, and internal optimizations. If 0 frames are returned, however, this indicates that end-of-file was reached.
ioData
Buffer(s) into which the audio data is read.
function result
An OSStatus error code.

Discussion

If the file has a client data format, then the audio data from the file is translated from the file data format to the client format, via the ExtAudioFile's internal AudioConverter.

(Note that the use of sequential reads/writes means that an ExtAudioFile must not be read on multiple threads; clients wishing to do this should use the lower-level AudioFile API set).

Availability
Introduced in Mac OS X 10.4.

ExtAudioFileWrite


Perform a synchronous sequential write.

extern OSStatus ExtAudioFileWrite(
    ExtAudioFileRef inExtAudioFile, 
    UInt32 inNumberFrames, 
    const AudioBufferList *ioData) ; 
Parameter Descriptions
inExtAudioFile
The extended audio file object.
inNumberFrames
The number of frames to write.
ioData
The buffer(s) from which audio data is written to the file.
function result
An OSStatus error code.

Discussion

If the file has a client data format, then the audio data in ioData is translated from the client format to the file data format, via the ExtAudioFile's internal AudioConverter.

Availability
Introduced in Mac OS X 10.4.

ExtAudioFileWriteAsync


Perform an asynchronous sequential write.

extern OSStatus ExtAudioFileWriteAsync(
    ExtAudioFileRef inExtAudioFile, 
    UInt32 inNumberFrames, 
    const AudioBufferList *ioData) ; 
Parameter Descriptions
inExtAudioFile
The extended audio file object.
inNumberFrames
The number of frames to write.
ioData
The buffer(s) from which audio data is written to the file.
function result
An OSStatus error code.

Discussion

Writes the provided buffer list to an internal ring buffer and notifies an internal thread to perform the write at a later time. The first time this is called, allocations may be performed. You can call this with 0 frames and null buffer in a non-time-critical context to initialize the asynchronous mechanism. Once initialized, subsequent calls are very efficient and do not take locks; thus this may be used to write to a file from a realtime thread.

The client must not mix synchronous and asynchronous writes to the same file.

Pending writes are not guaranteed to be flushed to disk until ExtAudioFileDispose is called.

N.B. Errors may occur after this call has returned. Such errors may be returned from subsequent calls to this function.

Availability
Introduced in Mac OS X 10.4.

ExtAudioFileSeek


Seek to a specific frame position.

extern OSStatus ExtAudioFileSeek(
    ExtAudioFileRef inExtAudioFile, 
    SInt64 inFrameOffset) ; 
Parameter Descriptions
inExtAudioFile
The extended audio file object.
inFrameOffset
The desired seek position, in sample frames, relative to the beginning of the file.
function result
An OSStatus error code.

Discussion

Sets the file's read position to the specified sample frame number. The next call to ExtAudioFileRead will return samples from precisely this location, even if it is located in the middle of a packet.

This function's behavior with files open for writing is currently undefined.

Availability
Introduced in Mac OS X 10.4.

ExtAudioFileTell


Return the file's read/write position.

extern OSStatus ExtAudioFileTell(
    ExtAudioFileRef inExtAudioFile, 
    SInt64 *outFrameOffset) ; 
Parameter Descriptions
inExtAudioFile
The extended audio file object.
outFrameOffset
On exit, the file's current read/write position in sample frames.
function result
An OSStatus error code.

Availability
Introduced in Mac OS X 10.4.

ExtAudioFileGetPropertyInfo


Get information about a property

extern OSStatus ExtAudioFileGetPropertyInfo(
    ExtAudioFileRef inExtAudioFile, 
    ExtAudioFilePropertyID inPropertyID, 
    UInt32 *outSize, 
    Boolean *outWritable) ; 
Parameter Descriptions
inExtAudioFile
The extended audio file 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.
function result
An OSStatus error code.

Availability
Introduced in Mac OS X 10.4.

ExtAudioFileGetProperty


Get a property value.

extern OSStatus ExtAudioFileGetProperty(
    ExtAudioFileRef inExtAudioFile, 
    ExtAudioFilePropertyID inPropertyID, 
    UInt32 *ioPropertyDataSize, 
    void *outPropertyData) ; 
Parameter Descriptions
inExtAudioFile
The extended audio file 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.
function result
An OSStatus error code.

Availability
Introduced in Mac OS X 10.4.

ExtAudioFileSetProperty


Set a property value.

extern OSStatus ExtAudioFileSetProperty(
    ExtAudioFileRef inExtAudioFile, 
    ExtAudioFilePropertyID inPropertyID, 
    UInt32 inPropertyDataSize, 
    const void *inPropertyData) ; 
Parameter Descriptions
inExtAudioFile
The extended audio file object.
inPropertyID
The property being set.
inPropertyDataSize
The size of the property data, in bytes.
inPropertyData
Points to the property's new value.
function result
An OSStatus error code.

Availability
Introduced in Mac OS X 10.4.

(Last Updated July 18, 2005)