AudioFile


Discussion

This header defines the types, constants, data structures and functions of the AudioFile API. The AudioFile API is used for reading and writing audio files on disk or in memory.



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.

Typedefs


AudioFileID


An opaque reference to an AudioFile object.

typedef struct OpaqueAudioFileID *AudioFileID; 

AudioFilePropertyID


A constant for an AudioFile property.

typedef UInt32 AudioFilePropertyID; 

AudioFile_ReadProc


A callback for reading data. used with AudioFileOpenWithCallbacks or AudioFileInitializeWithCallbacks.

typedef OSStatus (*AudioFile_ReadProc)( 
    void *inRefCon, 
    SInt64 inPosition, 
    ByteCount requestCount, 
    void *buffer, 
    ByteCount *actualCount); 
Parameter Descriptions
inRefCon
A pointer to the client data as set in the inRefCon parameter to AudioFileXXXWithCallbacks.
inPosition
An offset into the data from which to read.
requestCount
The number of bytes to read.
buffer
The buffer in which to put the data read.
actualCount
The callback should set this to the number of bytes successfully read.
result
The callback should return noErr on success, or an appropriate error code on failure.
Discussion

a function that will be called when AudioFile needs to read data.


AudioFile_WriteProc


A callback for writing data. used with AudioFileOpenWithCallbacks or AudioFileInitializeWithCallbacks.

typedef OSStatus (*AudioFile_WriteProc)( 
    void *inRefCon, 
    SInt64 inPosition, 
    ByteCount requestCount, 
    const void *buffer, 
    ByteCount *actualCount); 
Parameter Descriptions
inRefCon
A pointer to the client data as set in the inRefCon parameter to AudioFileXXXWithCallbacks.
inPosition
An offset into the data from which to read.
requestCount
The number of bytes to write.
buffer
The buffer containing the data to write.
actualCount
The callback should set this to the number of bytes successfully written.
result
The callback should return noErr on success, or an appropriate error code on failure.
Discussion

a function that will be called when AudioFile needs to write data.


AudioFile_GetSizeProc


A callback for getting the size of the file data. used with AudioFileOpenWithCallbacks or AudioFileInitializeWithCallbacks.

typedef SInt64 (*AudioFile_GetSizeProc)( 
    void *inRefCon); 
Parameter Descriptions
inRefCon
A pointer to the client data as set in the inRefCon parameter to AudioFileXXXWithCallbacks.
result
The callback should return the size of the data.
Discussion

a function that will be called when AudioFile needs to determine the size of the file data. This size is for all of the data in the file, not just the audio data.


AudioFile_SetSizeProc


A callback for setting the size of the file data. used with AudioFileOpenWithCallbacks or AudioFileInitializeWithCallbacks.

typedef OSStatus (*AudioFile_SetSizeProc)( 
    void *inRefCon, 
    SInt64 inSize); 
Parameter Descriptions
inRefCon
A pointer to the client data as set in the inRefCon parameter to AudioFileXXXWithCallbacks.
result
The callback should return the size of the data.
Discussion

a function that will be called when AudioFile needs to set the size of the file data. This size is for all of the data in the file, not just the audio data. This will only be called if the file is written to.

Structs and Unions


AudioFile_SMPTE_Time


A struct for describing a SMPTE time.

struct AudioFile_SMPTE_Time { 
    SInt8 mHours; 
    UInt8 mMinutes; 
    UInt8 mSeconds; 
    UInt8 mFrames; 
    UInt32 mSubFrameSampleOffset; 
}; 
Field Descriptions
mHours
The hours.
mMinutes
The minutes.
mSeconds
The seconds.
mFrames
The frames.
mSubFrameSampleOffset
The sample offset within a frame.

AudioFileMarker


A marker annotates a position in an audio file with additional information.

struct AudioFileMarker { 
    Float64 mFramePosition;  
    CFStringRef mName; 
    SInt32 mMarkerID;  
    AudioFile_SMPTE_Time mSMPTETime; 
    UInt32 mType; 
    UInt16 mReserved; 
    UInt16 mChannel; 
}; 
Field Descriptions
mFramePosition
The frame in the file counting from the start of the audio data.
mName
The name of this marker.
mMarkerID
A unique ID for this marker.
mSMPTETime
The SMPTE time for this marker.
mType
The marker type.
mReserved
A reserved field. Set to zero.
mChannel
The channel number that the marker refers to. Set to zero if marker applies to all channels.
Discussion

(description)


AudioFileMarkerList


(description)

struct AudioFileMarkerList { 
    UInt32 mSMPTE_TimeType; 
    UInt32 mNumberMarkers; 
    AudioFileMarker mMarkers[kVariableLengthArray]; 
}; 
Field Descriptions
(name) (description)
Discussion

(description)


AudioFileRegion


An AudioFileRegion specifies a segment of audio data.

struct AudioFileRegion { 
    UInt32 mRegionID; 
    CFStringRef mName; 
    UInt32 mFlags; 
    UInt32 mNumberMarkers; 
    AudioFileMarker mMarkers[kVariableLengthArray]; 
}; 
Field Descriptions
mRegionID
each region must have a unique ID.
mName
The name of the region.
mFlags
AudioFileRegionFlags.
mNumberMarkers
The number of markers in the mMarkers array.
mMarkers
A variable length array of AudioFileMarkers.
Discussion

Generally a region consists of at least two markers marking the beginning and end of the segment. There may also be other markers defining other meta information such as sync point.


AudioFileRegionList


A list of the AudioFileRegions in a file.

struct AudioFileRegionList { 
    UInt32 mSMPTE_TimeType; 
    UInt32 mNumberRegions; 
    AudioFileRegion mRegions[kVariableLengthArray]; 
}; 
Field Descriptions
mSMPTE_TimeType
This defines the SMPTE timing scheme used in the file. See CAFFile.h for the values used here.
mNumberRegions
The number of regions in the mRegions list.
mRegions
A list of AudioFileRegions. Note that AudioFileMarkers are variable length, so this list cannot be accessed as an array. Use the NextAudioFileRegion macro for traversing the list instead.
Discussion

This is the struct used by the kAudioFilePropertyRegionList property.


AudioFramePacketTranslation


used for properties kAudioFilePropertyPacketToFrame and kAudioFilePropertyFrameToPacket

struct AudioFramePacketTranslation { 
    SInt64 mFrame; 
    SInt64 mPacket; 
    UInt32 mFrameOffsetInPacket; 
}; 
Field Descriptions
mFrame
a frame number.
mPacket
a packet number.
mFrameOffsetInPacket
a frame offset in a packet.
Discussion

See description of kAudioFilePropertyPacketToFrame and kAudioFilePropertyFrameToPacket


AudioFilePacketTableInfo


This contains information about the number of valid frames in a file and where they begin and end.

struct AudioFilePacketTableInfo { 
    SInt64 mNumberValidFrames; 
    SInt32 mPrimingFrames; 
    SInt32 mRemainderFrames; 
}; 
Field Descriptions
mNumberValidFrames
the number of valid frames in the file.
mPrimingFrames
the number of invalid frames at the beginning of the file.
mRemainderFrames
the number of invalid frames at the end of the file.
Discussion

Some data formats may have packets whose contents are not completely valid, but represent priming or remainder frames that are not meant to be played. For example a file with 100 packets of AAC is nominally 1024 * 100 = 102400 frames of data. However the first 2112 frames of that may be priming frames and there may be some number of remainder frames added to pad out to a full packet of 1024 frames. The priming and remainder frames should be discarded. The total number of packets in the file times the frames per packet (or counting each packet's frames individually for a variable frames per packet format) minus mPrimingFrames, minus mRemainderFrames, should equal mNumberValidFrames.


AudioFileTypeAndFormatID


This is used as a specifier for kAudioFileGlobalInfo_AvailableStreamDescriptions

struct AudioFileTypeAndFormatID { 
    AudioFileTypeID mFileType; 
    UInt32 mFormatID; 
}; 
Field Descriptions
mFileType
a four char code for the file type such as kAudioFileAIFFType, kAudioFileCAFType, etc.
mFormatID
a four char code for the format ID such as kAudioFormatLinearPCM, kAudioFormatMPEG4AAC, etc.
Discussion

This struct is used to specify a desired audio file type and data format ID so that a list of stream descriptions of available formats can be obtained.

Enumerations


Audio File Types


Constants for the built-in audio file types.

enum { 
    kAudioFileAIFFType = 'AIFF', 
    kAudioFileAIFCType = 'AIFC', 
    kAudioFileWAVEType = 'WAVE', 
    kAudioFileSoundDesigner2Type = 'Sd2f', 
    kAudioFileNextType = 'NeXT', 
    kAudioFileMP3Type = 'MPG3', 
    kAudioFileAC3Type = 'ac-3', 
    kAudioFileAAC_ADTSType = 'adts', 
    kAudioFileMPEG4Type = 'mp4f', 
    kAudioFileM4AType = 'm4af', 
    kAudioFileCAFType = 'caff' 
}; 
Constants
kAudioFileAIFFType
Audio Interchange File Format (AIFF)
kAudioFileAIFCType
Audio Interchange File Format Compressed (AIFF-C)
kAudioFileWAVEType
Microsoft WAVE
kAudioFileSoundDesigner2Type
Sound Designer II
kAudioFileNextType
NeXT / Sun
kAudioFileMP3Type
MPEG 2 Layer 3 (.mp3)
kAudioFileAC3Type
AC-3
kAudioFileAAC_ADTSType
Advanced Audio Coding (AAC) Audio Data Transport Stream (ADTS)
kAudioFileMPEG4Type
kAudioFileM4AType
kAudioFileCAFType
CoreAudio File Format.
Discussion

These constants are used to indicate the type of file to be written, or as a hint to what type of file to expect from data provided.


AudioFile


These are the error codes returned from the AudioFile API.

enum { 
    kAudioFileUnspecifiedError = 'wht?', 
    kAudioFileUnsupportedFileTypeError = 'typ?', 
    kAudioFileUnsupportedDataFormatError = 'fmt?', 
    kAudioFileUnsupportedPropertyError = 'pty?', 
    kAudioFileBadPropertySizeError = '!siz', 
    kAudioFilePermissionsError = 'prm?', 
    kAudioFileNotOptimizedError = 'optm', 
    // file format specific error codes 
    kAudioFileInvalidChunkError = 'chk?', 
    kAudioFileDoesNotAllow64BitDataSizeError = 'off?', 
    kAudioFileInvalidPacketOffsetError = 'pck?', 
    kAudioFileInvalidFileError = 'dta?', 
    kAudioFileOperationNotSupportedError = 0x6F703F3F // 'op??', integer used because of trigraph 
}; 
Constants
kAudioFileUnspecifiedError
An unspecified error has occurred.
kAudioFileUnsupportedFileTypeError
The file type is not supported.
kAudioFileUnsupportedDataFormatError
The data format is not supported by this file type.
kAudioFileUnsupportedPropertyError
The property is not supported.
kAudioFileBadPropertySizeError
The size of the property data was not correct.
kAudioFilePermissionsError
The operation violated the file permissions. For example, trying to write to a file opened with fsRdPerm.
kAudioFileNotOptimizedError
There are chunks following the audio data chunk that prevent extending the audio data chunk. The file must be optimized in order to write more audio data.
kAudioFileInvalidChunkError
The chunk does not exist in the file or is not supported by the file.
kAudioFileDoesNotAllow64BitDataSizeError
The a file offset was too large for the file type. AIFF and WAVE have a 32 bit file size limit.
kAudioFileInvalidPacketOffsetError
A packet offset was past the end of the file, or not at the end of the file when writing a VBR format, or a corrupt packet size was read when building the packet table.
kAudioFileInvalidFileError
The file is malformed, or otherwise not a valid instance of an audio file of its type.
kAudioFileOperationNotSupportedError
The operation cannot be performed. For example, setting kAudioFilePropertyAudioDataByteCount to increase the size of the audio data in a file is not a supported operation. Write the data instead.
Discussion

error codes


AudioFileLoopDirection


These constants describe the playback direction of a looped segment of a file.

enum { 
    kAudioFileLoopDirection_NoLooping = 0, 
    kAudioFileLoopDirection_Forward = 1, 
    kAudioFileLoopDirection_ForwardAndBackward = 2, 
    kAudioFileLoopDirection_Backward = 3 
}; 
Constants
kAudioFileLoopDirection_NoLooping
The segment is not looped.
kAudioFileLoopDirection_Forward
play segment forward.
kAudioFileLoopDirection_Backward
play segment backward.
kAudioFileLoopDirection_ForwardAndBackward
play segment forward and backward.

AudioFileMarkerType


constants for types of markers within a file. Used in the mType field of AudioFileMarker.

enum { 
    kAudioFileMarkerType_Generic = 0, 
}; 
Constants
kAudioFileMarkerType_Generic
A generic marker. See CAFFile.h for marker types specific to CAF files.

AudioFileRegionFlags


These are flags for an AudioFileRegion that specify a playback direction.

enum { 
    kAudioFileRegionFlag_LoopEnable = 1, 
    kAudioFileRegionFlag_PlayForward = 2, 
    kAudioFileRegionFlag_PlayBackward = 4 
}; 
Constants
kAudioFileRegionFlag_LoopEnable
If this flag is set, the region will be looped. One or both of the following must also be set.
kAudioFileRegionFlag_PlayForward
If this flag is set, the region will be played forward.
kAudioFileRegionFlag_PlayBackward
If this flag is set, the region will be played backward.
Discussion

One or multiple of these flags can be set. For example, if both kAudioFileRegionFlag_LoopEnable and kAudioFileRegionFlag_PlayForward are set, then the region will play as a forward loop. If only kAudioFileRegionFlag_PlayForward is set, then the region will be played forward once.


Audio


constants for AudioFile get/set property calls

enum { 
    kAudioFilePropertyFileFormat = 'ffmt', 
    kAudioFilePropertyDataFormat = 'dfmt', 
    kAudioFilePropertyIsOptimized = 'optm', 
    kAudioFilePropertyMagicCookieData = 'mgic', 
    kAudioFilePropertyAudioDataByteCount = 'bcnt', 
    kAudioFilePropertyAudioDataPacketCount = 'pcnt', 
    kAudioFilePropertyMaximumPacketSize = 'psze', 
    kAudioFilePropertyDataOffset = 'doff', 
    kAudioFilePropertyChannelLayout = 'cmap', 
    kAudioFilePropertyDeferSizeUpdates = 'dszu', 
    kAudioFilePropertyDataFormatName = 'fnme', 
    kAudioFilePropertyMarkerList = 'mkls', 
    kAudioFilePropertyRegionList = 'rgls', 
    kAudioFilePropertyPacketToFrame = 'pkfr', 
    kAudioFilePropertyFrameToPacket = 'frpk', 
    kAudioFilePropertyChunkIDs = 'chid', 
    kAudioFilePropertyInfoDictionary = 'info', 
    kAudioFilePropertyPacketTableInfo = 'pnfo' 
}; 
Constants
kAudioFilePropertyFileFormat
An AudioFileTypeID that identifies the format of the file
kAudioFilePropertyDataFormat
An AudioStreamBasicDescription describing the format of the audio data
kAudioFilePropertyIsOptimized
A UInt32 indicating whether an Audio File has been optimized. Optimized means it is ready to start having sound data written to it. A value of 0 indicates the file needs to be optimized. A value of 1 indicates the file is currently optimized.
kAudioFilePropertyMagicCookieData
A void * pointing to memory set up by the caller. Some file types require that a magic cookie be provided before packets can be written to the file, so this property should be set before calling AudioFileWriteBytes()/AudioFileWritePackets() if a magic cookie exists.
kAudioFilePropertyAudioDataByteCount
a UInt64 that indicates the number of bytes of audio data contained in the file
kAudioFilePropertyAudioDataPacketCount
a UInt64 that indicates the number of packets of audio data contained in the file
kAudioFilePropertyMaximumPacketSize
a UInt32 that indicates the maximum size of a packet for the data contained in the file
kAudioFilePropertyDataOffset
a SInt64 that indicates the byte offset in the file of the audio data.
kAudioFilePropertyChannelLayout
An AudioChannelLayout struct.
kAudioFilePropertyDeferSizeUpdates
A UInt32. If 1, then updating the files sizes in the header is not done for every write, but deferred until the file is read, optimized or closed. This is more efficient, but less safe since, if the application crashes before the size is updated, the file may not be readable. The default value is zero, it always updates header.
kAudioFilePropertyDataFormatName
This is deprecated. Use kAudioFormatProperty_FormatName in AudioFormat.h instead.
kAudioFilePropertyMarkerList
access the list of markers defined in the file. returns an AudioFileMarkerList. The CFStringRefs in the returned structs must be released by the client. (available in 10.2.4 and later)
kAudioFilePropertyRegionList
access the list of regions defined in the file. returns an Array of AudioFileRegions. The CFStringRefs in the returned structs must be released by the client. (available in 10.2.4 and later)
kAudioFilePropertyPacketToFrame
pass a AudioFramePacketTranslation with mPacket filled out and get mFrame back. mFrameOffsetInPacket is ignored.
kAudioFilePropertyFrameToPacket
pass a AudioFramePacketTranslation with mFrame filled out and get mPacket and mFrameOffsetInPacket back.
kAudioFilePropertyChunkIDs
returns an array of OSType four char codes for each kind of chunk in the file.
kAudioFilePropertyInfoDictionary
returns a CFDictionary filled with information about the data contined in the file. See dictionary key constants already defined for info string types. AudioFileComponents are free to add keys to the dictionaries that they return for this property... caller is responsible for releasing the CFObject
kAudioFilePropertyPacketTableInfo
Gets or sets an AudioFilePacketTableInfo struct for CAF files. When setting, the sum of mNumberValidFrames, mPrimingFrames and mRemainderFrames must be the same as the total number of frames in all packets. If not you will get a paramErr. The best way to ensure this is to get the value of the property and make sure the sum of the three values you set has the same sum as the three values you got.
Discussion

File Properties


Audio


constants for AudioFileGetGlobalInfo properties

enum { 
    kAudioFileGlobalInfo_ReadableTypes = 'afrf', 
    kAudioFileGlobalInfo_WritableTypes = 'afwf', 
    kAudioFileGlobalInfo_FileTypeName = 'ftnm', 
    kAudioFileGlobalInfo_ExtensionsForType = 'fext', 
    kAudioFileGlobalInfo_AllExtensions = 'alxt', 
    kAudioFileGlobalInfo_AvailableFormatIDs = 'fmid', 
    kAudioFileGlobalInfo_AvailableStreamDescriptionsForFormat = 'sdid', 
    kAudioFileGlobalInfo_HFSTypeCodesForType = 'fhfs', 
    kAudioFileGlobalInfo_AllHFSTypeCodes = 'ahfs' 
}; 
Constants
kAudioFileGlobalInfo_ReadableTypes
No specifier needed. Must be set to NULL. Returns an array of UInt32 containing the file types (i.e. AIFF, WAVE, etc) that can be opened for reading.
kAudioFileGlobalInfo_WritableTypes
No specifier needed. Must be set to NULL. Returns an array of UInt32 containing the file types (i.e. AIFF, WAVE, etc) that can be opened for writing.
kAudioFileGlobalInfo_FileTypeName
Specifier is a pointer to a AudioFileTypeID containing a file type. Returns a CFString containing the name for the file type.
kAudioFileGlobalInfo_ExtensionsForType
Specifier is a pointer to a AudioFileTypeID containing a file type. Returns a CFArray of CFStrings containing the file extensions that are recognized for this file type.
kAudioFileGlobalInfo_AllExtensions
No specifier needed. Must be set to NULL. Returns a CFArray of CFStrings containing all file extensions that are recognized. The array be used when creating an NSOpenPanel.
kAudioFileGlobalInfo_AvailableFormatIDs
Specifier is a pointer to a AudioFileTypeID containing a file type. Returns a array of format IDs for formats that can be read.
kAudioFileGlobalInfo_AvailableStreamDescriptionsForFormat
Specifier is a pointer to a AudioFileTypeAndFormatID struct defined below. Returns an array of AudioStreamBasicDescriptions which have all of the formats for a particular file type and format ID. The AudioStreamBasicDescriptions have the following fields filled in: mFormatID, mFormatFlags, mBitsPerChannel
kAudioFileGlobalInfo_HFSTypeCodesForType
Specifier is a pointer to an AudioFileTypeID. Returns an array of HFSTypeCodes corresponding to that file type. The first type in the array is the preferred one for use when writing new files.
kAudioFileGlobalInfo_AllHFSTypeCodes
No specifier needed. Must be set to NULL. Returns an array of HFSTypeCode's containing all HFSTypeCodes that are recognized.

Discussion

File Global Info Properties

#defines


NumBytesToNumAudioFileMarkers


Converts a size in bytes to the number of AudioFileMarkers that can be contained in that number of bytes.

#define NumBytesToNumAudioFileMarkers(
    inNumBytes)  
Parameter Descriptions
inNumBytes
a number of bytes.
result
the number of AudioFileMarkers that can be contained in that number of bytes.
Discussion

This can be used for the kAudioFilePropertyMarkerList property when calculating the number of markers that will be returned.


NumAudioFileMarkersToNumBytes


Converts a number of AudioFileMarkers to a size in bytes.

#define NumAudioFileMarkersToNumBytes(
    inNumMarkers)  
Parameter Descriptions
inNumMarkers
a number of AudioFileMarkers.
result
the size in bytes required to contain that number of AudioFileMarkers.
Discussion

This can be used for the kAudioFilePropertyMarkerList property when calculating the size required to contain a number of AudioFileMarkers.


NextAudioFileRegion


convenience macro for traversing the region list.

#define NextAudioFileRegion(
    inAFRegionPtr) \ ((
    AudioFileRegion*)((
    char*)(
    inAFRegionPtr) + offsetof(
    AudioFileRegion, mMarkers) + ((
    inAFRegionPtr)->mNumberMarkers)*sizeof(
    CAFMarker))) 
Parameter Descriptions
inAFRegionPtr
a pointer to the current region.
result
a pointer to the region after the current region. This does not protect you from walking off the end of the list, so obey mNumberRegions.
Discussion

because AudioFileRegions are variable length, you cannot access them as an array. Use NextAudioFileRegion to walk the list.

(Last Updated July 18, 2005)