Functions


AudioFileCreate
creates a new audio file
AudioFileInitialize
Write over an existing audio file.
AudioFileOpen
Open an existing audio file.
AudioFileInitializeWithCallbacks
Wipe clean an existing file. You provide callbacks that the AudioFile API will use to get the data.
AudioFileOpenWithCallbacks
Open an existing file. You provide callbacks that the AudioFile API will use to get the data.
AudioFileClose
Close an existing audio file.
AudioFileOptimize
Move the audio data to the end of the file and other internal optimizations of the file structure.
AudioFileReadBytes
Read bytes of audio data from the audio file.
AudioFileWriteBytes
Write bytes of audio data to the audio file.
AudioFileReadPackets
Read packets of audio data from the audio file.
AudioFileWritePackets
Write packets of audio data to the audio file.
AudioFileCountUserData
Get the number of user data items with a certain ID in the file
AudioFileGetUserDataSize
Get the size of user data in a file
AudioFileGetUserData
Get the data of a chunk in a file.
AudioFileSetUserData
Set the data of a chunk in a file.
AudioFileGetPropertyInfo
Get information about the size of a property of an AudioFile and whether it can be set.
AudioFileGetProperty
Copies the value for a property of an AudioFile into a buffer.
AudioFileSetProperty
Sets the value for a property of an AudioFile .
AudioFileGetGlobalInfoSize
Get information about the size of a global property.
AudioFileGetGlobalInfo
Copies the value for a global property into a buffer.

AudioFileCreate


creates a new audio file

extern OSStatus AudioFileCreate (
    const FSRef *inParentRef, 
    CFStringRef inFileName, 
    AudioFileTypeID inFileType, 
    const AudioStreamBasicDescription *inFormat, 
    UInt32 inFlags, 
    FSRef *outNewFileRef, 
    AudioFileID *outAudioFile); 
Parameter Descriptions
inParentRef
an FSRef to the directory where the new file should be created.
inFileName
a CFStringRef containing the name of the file to be created.
inFileType
an AudioFileTypeID indicating the type of audio file to create.
inFormat
an AudioStreamBasicDescription describing the data format that will be added to the audio file.
inFlags
relevant flags for creating/opening the file. Currently zero.
outNewFileRef
if successful, the FSRef of the newly created file.
outAudioFile
if successful, an AudioFileID that can be used for subsequent AudioFile calls.
function result
returns noErr if successful.
Discussion

creates a new audio file located in the parent directory provided. Upon success, an AudioFileID is returned which can be used for subsequent calls to the AudioFile APIs.

Availability
Introduced in Mac OS X 10.2

AudioFileInitialize


Write over an existing audio file.

extern OSStatus AudioFileInitialize (
    const FSRef *inFileRef, 
    AudioFileTypeID inFileType, 
    const AudioStreamBasicDescription *inFormat, 
    UInt32 inFlags, 
    AudioFileID *outAudioFile); 
Parameter Descriptions
inFileRef
the FSRef of an existing audio file.
inFileType
an AudioFileTypeID indicating the type of audio file to initialize the file to.
inFormat
an AudioStreamBasicDescription describing the data format that will be added to the audio file.
inFlags
flags for creating/opening the file. Currently zero.
outAudioFile
upon success, an AudioFileID that can be used for subsequent AudioFile calls.
function result
returns noErr if successful.
Discussion

Use AudioFileInitialize to wipe clean an existing audio file and prepare it to be populated with new data.

Availability
Introduced in Mac OS X 10.2

AudioFileOpen


Open an existing audio file.

extern OSStatus AudioFileOpen (
    const FSRef *inFileRef, 
    SInt8 inPermissions, 
    AudioFileTypeID inFileTypeHint, 
    AudioFileID *outAudioFile); 
Parameter Descriptions
inFileRef
the FSRef of an existing audio file.
inPermissions
use the permission constants used by FSOpenFork().
inFileTypeHint
For files which have no filename extension and whose type cannot be easily or uniquely determined from the data (ADTS,AC3), this hint can be used to indicate the file type. Otherwise you can pass zero for this. The hint is only used on OS versions 10.3.1 or greater. For OS versions prior to that, opening files of the above description will fail.
outAudioFile
upon success, an AudioFileID that can be used for subsequent AudioFile calls.
function result
returns noErr if successful.
Discussion

Open an existing audio file for reading or reading and writing.

Availability
Introduced in Mac OS X 10.2

AudioFileInitializeWithCallbacks


Wipe clean an existing file. You provide callbacks that the AudioFile API will use to get the data.

extern OSStatus AudioFileInitializeWithCallbacks ( 
    void *inRefCon, 
    AudioFile_ReadProc inReadFunc, 
    AudioFile_WriteProc inWriteFunc, 
    AudioFile_GetSizeProc inGetSizeFunc, 
    AudioFile_SetSizeProc inSetSizeFunc, 
    AudioFileTypeID inFileType, 
    const AudioStreamBasicDescription *inFormat, 
    UInt32 inFlags, 
    AudioFileID *outAudioFile); 
Parameter Descriptions
inRefCon
a constant that will be passed to your callbacks.
inReadFunc
a function that will be called when AudioFile needs to read data.
inWriteFunc
a function that will be called when AudioFile needs to write data.
inGetSizeFunc
a function that will be called when AudioFile needs to know the file size.
inSetSizeFunc
a function that will be called when AudioFile needs to set the file size.

inFileType
an AudioFileTypeID indicating the type of audio file to which to initialize the file.
inFormat
an AudioStreamBasicDescription describing the data format that will be added to the audio file.
inFlags
flags for creating/opening the file. Currently zero.
outAudioFile
upon success, an AudioFileID that can be used for subsequent AudioFile calls.
function result
returns noErr if successful.
Availability
Introduced in Mac OS X 10.3.

AudioFileOpenWithCallbacks


Open an existing file. You provide callbacks that the AudioFile API will use to get the data.

extern OSStatus AudioFileOpenWithCallbacks ( // not seekable, read only 
    void *inRefCon, 
    AudioFile_ReadProc inReadFunc, 
    AudioFile_WriteProc inWriteFunc, 
    AudioFile_GetSizeProc inGetSizeFunc, 
    AudioFile_SetSizeProc inSetSizeFunc, 
    AudioFileTypeID inFileTypeHint, 
    AudioFileID *outAudioFile); 
Parameter Descriptions
inRefCon
a constant that will be passed to your callbacks.
AudioFile_ReadProc
a function that will be called when AudioFile needs to read data.
AudioFile_WriteProc
a function that will be called when AudioFile needs to write data.
AudioFile_GetSizeProc
a function that will be called when AudioFile needs to know the file size.
AudioFile_SetSizeProc
a function that will be called when AudioFile needs to set the file size.

inFileTypeHint
For files which have no filename extension and whose type cannot be easily or uniquely determined from the data (ADTS,AC3), this hint can be used to indicate the file type. Otherwise you can pass zero for this. The hint is only used on OS versions 10.3.1 or greater. For OS versions prior to that, opening files of the above description will fail.
outAudioFile
upon success, an AudioFileID that can be used for subsequent AudioFile calls.
function result
returns noErr if successful.
Availability
Introduced in Mac OS X 10.3.

AudioFileClose


Close an existing audio file.

extern OSStatus AudioFileClose (
    AudioFileID inAudioFile); 
Parameter Descriptions
inAudioFile
an AudioFileID.
function result
returns noErr if successful.
Availability
Introduced in Mac OS X 10.2

AudioFileOptimize


Move the audio data to the end of the file and other internal optimizations of the file structure.

extern OSStatus AudioFileOptimize (
    AudioFileID inAudioFile); 
Parameter Descriptions
inAudioFile
an AudioFileID.
function result
returns noErr if successful.
Discussion

Optimize the file so additional audio data can be appended to the existing data. Generally, this will place the audio data at the end of the file so additional writes can be placed to the file end. This can be a potentially expensive and time-consuming operation and should not be used during time critical operations. There is a kAudioFilePropertyIsOptimized property for checking on the optimized state of the file.

Availability
Introduced in Mac OS X 10.2

AudioFileReadBytes


Read bytes of audio data from the audio file.

extern OSStatus AudioFileReadBytes (
    AudioFileID inAudioFile, 
    Boolean inUseCache, 
    SInt64 inStartingByte, 
    UInt32 *ioNumBytes, 
    void *outBuffer); 
Parameter Descriptions
inAudioFile
an AudioFileID.
inUseCache
true if it is desired to cache the data upon read, else false
inStartingByte
the byte offset of the audio data desired to be returned
ioNumBytes
on input, the number of bytes to read, on output, the number of bytes actually read.
outBuffer
outBuffer should be a void * to user allocated memory large enough for the requested bytes.
function result
returns noErr if successful.
Discussion

Returns eofErr when read encounters end of file.

Availability
Introduced in Mac OS X 10.2

AudioFileWriteBytes


Write bytes of audio data to the audio file.

extern OSStatus AudioFileWriteBytes (
    AudioFileID inAudioFile, 
    Boolean inUseCache, 
    SInt64 inStartingByte, 
    UInt32 *ioNumBytes, 
    const void *inBuffer); 
Parameter Descriptions
inAudioFile
an AudioFileID.
inUseCache
true if it is desired to cache the data upon write, else false
inStartingByte
the byte offset where the audio data should be written
ioNumBytes
on input, the number of bytes to write, on output, the number of bytes actually written.
inBuffer
inBuffer should be a void * containing the bytes to be written
function result
returns noErr if successful.
Availability
Introduced in Mac OS X 10.2

AudioFileReadPackets


Read packets of audio data from the audio file.

extern OSStatus AudioFileReadPackets (
    AudioFileID inAudioFile, 
    Boolean inUseCache, 
    UInt32 *outNumBytes, 
    AudioStreamPacketDescription *outPacketDescriptions, 
    SInt64 inStartingPacket, 
    UInt32 *ioNumPackets, 
    void *outBuffer); 
Parameter Descriptions
inAudioFile
an AudioFileID.
inUseCache
true if it is desired to cache the data upon read, else false
outNumBytes
on output, the number of bytes actually returned
outPacketDescriptions
on output, an array of packet descriptions describing the packets being returned. NULL may be passed for this parameter. Nothing will be returned for linear pcm data.
inStartingPacket
the packet index of the first packet desired to be returned
ioNumPackets
on input, the number of packets to read, on output, the number of packets actually read.
outBuffer
outBuffer should be a pointer to user allocated memory of size: number of packets requested times file's maximum (or upper bound on) packet size.
function result
returns noErr if successful.
Discussion

For all uncompressed formats, packets == frames. ioNumPackets less than requested indicates end of file.

Availability
Introduced in Mac OS X 10.2

AudioFileWritePackets


Write packets of audio data to the audio file.

extern OSStatus AudioFileWritePackets (
    AudioFileID inAudioFile, 
    Boolean inUseCache, 
    UInt32 inNumBytes, 
    AudioStreamPacketDescription *inPacketDescriptions, 
    SInt64 inStartingPacket, 
    UInt32 *ioNumPackets, 
    const void *inBuffer); 
Parameter Descriptions
inAudioFile
an AudioFileID.
inUseCache
true if it is desired to cache the data upon write, else false
inNumBytes
the number of bytes being provided for write
inPacketDescriptions
an array of packet descriptions describing the packets being provided. Not all formats require packet descriptions to be provided. NULL may be passed if no descriptions are required.
inStartingPacket
the packet index of where the first packet provided should be placed.
ioNumPackets
on input, the number of packets to write, on output, the number of packets actually written.
inBuffer
a void * to user allocated memory containing the packets to write.
function result
returns noErr if successful.
Discussion

For all uncompressed formats, packets == frames.

Availability
Introduced in Mac OS X 10.2

AudioFileCountUserData


Get the number of user data items with a certain ID in the file

extern OSStatus AudioFileCountUserData (
    AudioFileID inAudioFile, 
    UInt32 inUserDataID, 
    UInt32 *outNumberItems); 
Parameter Descriptions
inAudioFile
an AudioFileID.
inUserDataID
the four char code of the chunk.
outNumberItems
on output, if successful, number of chunks of this type in the file.
function result
returns noErr if successful.
Discussion

"User Data" refers to chunks in AIFF, CAF and WAVE files, or resources in Sound Designer II files, and possibly other things in other files. For simplicity, referred to below as "chunks".

Availability
Introduced in Mac OS X 10.4.

AudioFileGetUserDataSize


Get the size of user data in a file

extern OSStatus AudioFileGetUserDataSize (
    AudioFileID inAudioFile, 
    UInt32 inUserDataID, 
    UInt32 inIndex, 
    UInt32 *outUserDataSize); 
Parameter Descriptions
inAudioFile
an AudioFileID.
inUserDataID
the four char code of the chunk.
inIndex
an index specifying which chunk if there are more than one.
outUserDataSize
on output, if successful, the size of the user data chunk.
function result
returns noErr if successful.
Availability
Introduced in Mac OS X 10.4.

AudioFileGetUserData


Get the data of a chunk in a file.

extern OSStatus AudioFileGetUserData (
    AudioFileID inAudioFile, 
    UInt32 inUserDataID, 
    UInt32 inIndex, 
    UInt32 *ioUserDataSize, 
    void *outUserData); 
Parameter Descriptions
inAudioFile
an AudioFileID.
inUserDataID
the four char code of the chunk.
inIndex
an index specifying which chunk if there are more than one.
ioUserDataSize
the size of the buffer on input, size of bytes copied to buffer on output
outUserData
a pointer to a buffer in which to copy the chunk data.
function result
returns noErr if successful.
Availability
Introduced in Mac OS X 10.4.

AudioFileSetUserData


Set the data of a chunk in a file.

extern OSStatus AudioFileSetUserData (
    AudioFileID inAudioFile, 
    UInt32 inUserDataID, 
    UInt32 inIndex, 
    UInt32 inUserDataSize, 
    const void *inUserData); 
Parameter Descriptions
inAudioFile
an AudioFileID.
inUserDataID
the four char code of the chunk.
inIndex
an index specifying which chunk if there are more than one.
inUserDataSize
on input the size of the data to copy, on output, size of bytes copied from the buffer
inUserData
a pointer to a buffer from which to copy the chunk data (only the contents of the chunk, not including the chunk header).
function result
returns noErr if successful.
Availability
Introduced in Mac OS X 10.4.

AudioFileGetPropertyInfo


Get information about the size of a property of an AudioFile and whether it can be set.

extern OSStatus AudioFileGetPropertyInfo(
    AudioFileID inAudioFile, 
    AudioFilePropertyID inPropertyID, 
    UInt32 *outDataSize, 
    UInt32 *isWritable); 
Parameter Descriptions
inAudioFile
an AudioFileID.
inPropertyID
an AudioFileProperty constant.
outDataSize
the size in bytes of the current value of the property. In order to get the property value, you will need a buffer of this size.
isWritable
will be set to 1 if writable, or 0 if read only.
function result
returns noErr if successful.
Availability
Introduced in Mac OS X 10.2

AudioFileGetProperty


Copies the value for a property of an AudioFile into a buffer.

extern OSStatus AudioFileGetProperty(
    AudioFileID inAudioFile, 
    AudioFilePropertyID inPropertyID, 
    UInt32 *ioDataSize, 
    void *outPropertyData); 
Parameter Descriptions
inAudioFile
an AudioFileID.
inPropertyID
an AudioFileProperty constant.
ioDataSize
on input the size of the outPropertyData buffer. On output the number of bytes written to the buffer.
outPropertyData
the buffer in which to write the property data.
function result
returns noErr if successful.
Availability
Introduced in Mac OS X 10.2

AudioFileSetProperty


Sets the value for a property of an AudioFile .

extern OSStatus AudioFileSetProperty(
    AudioFileID inAudioFile, 
    AudioFilePropertyID inPropertyID, 
    UInt32 inDataSize, 
    const void *inPropertyData); 
Parameter Descriptions
inAudioFile
an AudioFileID.
inPropertyID
an AudioFileProperty constant.
inDataSize
the size of the property data.
inPropertyData
the buffer containing the property data.
function result
returns noErr if successful.
Availability
Introduced in Mac OS X 10.2

AudioFileGetGlobalInfoSize


Get information about the size of a global property.

extern OSStatus AudioFileGetGlobalInfoSize(
    AudioFilePropertyID inPropertyID, 
    UInt32 inSpecifierSize, 
    void *inSpecifier, 
    UInt32 *outDataSize); 
Parameter Descriptions
inPropertyID
an AudioFileGlobalInfo property constant.
inSpecifierSize
The size of the specifier data.
inSpecifier
A specifier is a buffer of data used as an input argument to some of the global info properties.
outDataSize
the size in bytes of the current value of the property. In order to get the property value, you will need a buffer of this size.
function result
returns noErr if successful.
Availability
Introduced in Mac OS X 10.3.

AudioFileGetGlobalInfo


Copies the value for a global property into a buffer.

extern OSStatus AudioFileGetGlobalInfo(
    AudioFilePropertyID inPropertyID, 
    UInt32 inSpecifierSize, 
    void *inSpecifier, 
    UInt32 *ioDataSize, 
    void *outPropertyData); 
Parameter Descriptions
inPropertyID
an AudioFileGlobalInfo property constant.
inSpecifierSize
The size of the specifier data.
inSpecifier
A specifier is a buffer of data used as an input argument to some of the global info properties.
ioDataSize
on input the size of the outPropertyData buffer. On output the number of bytes written to the buffer.
outPropertyData
the buffer in which to write the property data.
function result
returns noErr if successful.
Availability
Introduced in Mac OS X 10.3.

(Last Updated July 18, 2005)