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.
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);
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.
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.
AudioFileInitialize |
Write over an existing audio file.
extern OSStatus AudioFileInitialize ( const FSRef *inFileRef, AudioFileTypeID inFileType, const AudioStreamBasicDescription *inFormat, UInt32 inFlags, AudioFileID *outAudioFile);
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.
Use AudioFileInitialize to wipe clean an existing audio file and prepare it to be populated with new data.
AudioFileOpen |
Open an existing audio file.
extern OSStatus AudioFileOpen ( const FSRef *inFileRef, SInt8 inPermissions, AudioFileTypeID inFileTypeHint, AudioFileID *outAudioFile);
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.
Open an existing audio file for reading or reading and writing.
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);
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.
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);
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.
AudioFileClose |
Close an existing audio file.
extern OSStatus AudioFileClose ( AudioFileID inAudioFile);
inAudioFile
- an AudioFileID.
AudioFileOptimize |
Move the audio data to the end of the file and other internal optimizations of the file structure.
extern OSStatus AudioFileOptimize ( AudioFileID inAudioFile);
inAudioFile
- an AudioFileID.
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.
AudioFileReadBytes |
Read bytes of audio data from the audio file.
extern OSStatus AudioFileReadBytes ( AudioFileID inAudioFile, Boolean inUseCache, SInt64 inStartingByte, UInt32 *ioNumBytes, void *outBuffer);
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.
Returns eofErr when read encounters end of file.
AudioFileWriteBytes |
Write bytes of audio data to the audio file.
extern OSStatus AudioFileWriteBytes ( AudioFileID inAudioFile, Boolean inUseCache, SInt64 inStartingByte, UInt32 *ioNumBytes, const void *inBuffer);
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
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);
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.
For all uncompressed formats, packets == frames.
ioNumPackets less than requested indicates end of file.
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);
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.
For all uncompressed formats, packets == frames.
AudioFileCountUserData |
Get the number of user data items with a certain ID in the file
extern OSStatus AudioFileCountUserData ( AudioFileID inAudioFile, UInt32 inUserDataID, UInt32 *outNumberItems);
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.
"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".
AudioFileGetUserDataSize |
Get the size of user data in a file
extern OSStatus AudioFileGetUserDataSize ( AudioFileID inAudioFile, UInt32 inUserDataID, UInt32 inIndex, UInt32 *outUserDataSize);
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.
AudioFileGetUserData |
Get the data of a chunk in a file.
extern OSStatus AudioFileGetUserData ( AudioFileID inAudioFile, UInt32 inUserDataID, UInt32 inIndex, UInt32 *ioUserDataSize, void *outUserData);
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.
AudioFileSetUserData |
Set the data of a chunk in a file.
extern OSStatus AudioFileSetUserData ( AudioFileID inAudioFile, UInt32 inUserDataID, UInt32 inIndex, UInt32 inUserDataSize, const void *inUserData);
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).
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);
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.
AudioFileGetProperty |
Copies the value for a property of an AudioFile into a buffer.
extern OSStatus AudioFileGetProperty( AudioFileID inAudioFile, AudioFilePropertyID inPropertyID, UInt32 *ioDataSize, void *outPropertyData);
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.
AudioFileSetProperty |
Sets the value for a property of an AudioFile .
extern OSStatus AudioFileSetProperty( AudioFileID inAudioFile, AudioFilePropertyID inPropertyID, UInt32 inDataSize, const void *inPropertyData);
inAudioFile
- an AudioFileID.
inPropertyID
- an AudioFileProperty constant.
inDataSize
- the size of the property data.
inPropertyData
- the buffer containing the property data.
AudioFileGetGlobalInfoSize |
Get information about the size of a global property.
extern OSStatus AudioFileGetGlobalInfoSize( AudioFilePropertyID inPropertyID, UInt32 inSpecifierSize, void *inSpecifier, UInt32 *outDataSize);
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.
AudioFileGetGlobalInfo |
Copies the value for a global property into a buffer.
extern OSStatus AudioFileGetGlobalInfo( AudioFilePropertyID inPropertyID, UInt32 inSpecifierSize, void *inSpecifier, UInt32 *ioDataSize, void *outPropertyData);
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.
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);
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.
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);
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.
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);
inRefCon
- A pointer to the client data as set in the inRefCon parameter to AudioFileXXXWithCallbacks.
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);
inRefCon
- A pointer to the client data as set in the inRefCon parameter to AudioFileXXXWithCallbacks.
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.
AudioFile_SMPTE_Time |
A struct for describing a SMPTE time.
struct AudioFile_SMPTE_Time { SInt8 mHours; UInt8 mMinutes; UInt8 mSeconds; UInt8 mFrames; UInt32 mSubFrameSampleOffset; };
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; };
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.
(description)
AudioFileMarkerList |
(description)
struct AudioFileMarkerList { UInt32 mSMPTE_TimeType; UInt32 mNumberMarkers; AudioFileMarker mMarkers[kVariableLengthArray]; };
- (name) (description)
(description)
AudioFileRegion |
An AudioFileRegion specifies a segment of audio data.
struct AudioFileRegion { UInt32 mRegionID; CFStringRef mName; UInt32 mFlags; UInt32 mNumberMarkers; AudioFileMarker mMarkers[kVariableLengthArray]; };
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.
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]; };
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.
This is the struct used by the kAudioFilePropertyRegionList property.
AudioFramePacketTranslation |
used for properties kAudioFilePropertyPacketToFrame and kAudioFilePropertyFrameToPacket
struct AudioFramePacketTranslation { SInt64 mFrame; SInt64 mPacket; UInt32 mFrameOffsetInPacket; };
mFrame
- a frame number.
mPacket
- a packet number.
mFrameOffsetInPacket
- a frame offset in a packet.
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; };
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.
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; };
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.
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.
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' };
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.
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 };
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.
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 };
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, };
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 };
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.
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' };
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.
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' };
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.
File Global Info Properties
NumBytesToNumAudioFileMarkers |
Converts a size in bytes to the number of AudioFileMarkers that can be contained in that number of bytes.
#define NumBytesToNumAudioFileMarkers( inNumBytes)
inNumBytes
- a number of bytes.
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)
inNumMarkers
- a number of AudioFileMarkers.
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)))
inAFRegionPtr
- a pointer to the current region.
because AudioFileRegions are variable length, you cannot access them as an array. Use NextAudioFileRegion to walk the list.
(Last Updated July 18, 2005)