Next Page >

Hide TOC

Audio File Services Reference

Framework	AudioToolbox/AudioToolbox.h
Declared in	AudioFile.h

Overview

This document describes Audio File Services, a C programming interface in the Audio Toolbox framework, which is part of Core Audio.

Audio file objects enable you to read or write a wide variety of audio data to or from a disk or a buffer.

Audio File Services enable you to:

Create and initialize audio files
Open and close audio files
Optimize audio files
Read and write audio files
Work with user data
Work with global information

Audio File Services is a pure C interface that you can use in Cocoa and Carbon applications as well as Mac OS X command-line tools. This document describes Audio File Services for Mac OS X v10.5.

Functions by Task

Creating and Initializing Audio Files

Opening and Closing Audio Files

Optimizing Audio Files

Reading and Writing Audio Files

Working with User Data

Working with Global Information

Functions

AudioFileClose

Closes an audio file.

OSStatus AudioFileClose (
   AudioFileID inAudioFile
);

Parameters

inAudioFile: The file you want to close.

Return Value

A result code. See “Audio File Result Codes.”

Availability

Available in Mac OS X v10.2 and later.

Declared In

AudioFile.h

AudioFileCountUserData

Gets the number of chunks (user data items) with a specified ID in the file.

OSStatus AudioFileCountUserData (
   AudioFileID inAudioFile,
   UInt32 inUserDataID,
   UInt32 *outNumberItems
);

Parameters

inAudioFile: The audio file whose chunks are to be counted.
inUserDataID: The four-character code (such as COMM) of the chunk.
outNumberItems: On output, a pointer to the number of chunks of this type in the file.

Return Value

A result code. See “Audio File Result Codes.”

Discussion

In the context of this function, user data refers to chunks in AIFF, CAF, and WAVE files, to resources in Sound Designer II files, and possibly to other types of information in other files.

Availability

Available in Mac OS X v10.4 and later.

Declared In

AudioFile.h

AudioFileCreate

Creates a new audio file specified by a file system reference.

   
OSStatus AudioFileCreate (
   const struct FSRef *inParentRef,
   CFStringRef  inFileName,
   AudioFileTypeID inFileType,
   const AudioStreamBasicDescription *inFormat,
   UInt32 inFlags,
   struct FSRef *outNewFileRef,
      AudioFileID *outAudioFile);

Parameters

inParentRef: A pointer to the directory where the new file should be created.
inFileName: The name of the file to be created.
inFileType: The type of audio file to create. See “Built-In Audio File Types” for constants that can be used.
inFormat: A pointer to the structure that describes the format of the data.
inFlags: Relevant flags for creating or opening the file. Currently set to 0.
outNewFileRef: On output, a pointer to the location of the newly created file.
outAudioFile: On output, a pointer to the newly created audio file.

Return Value

A result code. See “Audio File Result Codes.”

Discussion

This function creates a new audio file located in the directory specified in the inParentRef parameter.

Availability

Available in Mac OS X v10.2 and later.

Declared In

AudioFile.h

AudioFileCreateWithURL

Creates a new audio file or initializes an existing file specified by a URL.

   
OSStatus AudioFileCreateWithURL (
   CFURLRef inFileRef,
   AudioFileTypeID inFileType,
   const AudioStreamBasicDescription *inFormat,
   UInt32 inFlags,
   AudioFileID *outAudioFile);

Parameters

inFileRef: The fully specified path of the file to create or initialize.
inFileType: The type of audio file to create. See “Built-In Audio File Types” for constants that can be used.
inFormat: A pointer to the structure that describes the format of the data.
inFlags: Relevant flags for creating or opening the file. If kAudioFileFlags_EraseFile is set, it erases an existing file. If the flag is not set, the function fails fails if the URL is an existing file.
outAudioFile: On output, a pointer to a newly created or initialized file.

Return Value

A result code. See “Audio File Result Codes.”

Discussion

Note that this function uses a CFURLRef rather than the FSRef used by the AudioFileCreate function.

Availability

Available in Mac OS X v10.5 and later.

Declared In

AudioFile.h

AudioFileGetGlobalInfo

Copies the value of a global property into a buffer.

OSStatus AudioFileGetGlobalInfo (
   AudioFilePropertyID inPropertyID,
   UInt32 inSpecifierSize,
   void *inSpecifier,
   UInt32 *ioDataSize,
   void *outPropertyData
);

Parameters

inPropertyID: The property whose value you want to get. For possible values, see “Audio File Global Info Properties.”
inSpecifierSize: The size of the specifier data.
inSpecifier: A pointer to a specifier, which, in this context, is a pointer to a buffer containing some data that is different for each property. The type of the data required is described in the description of each property.
ioDataSize: On input, a pointer to the size of the buffer specified in the outPropertyData parameter. On output, a pointer to the number of bytes written to the buffer.
outPropertyData: A pointer to the buffer in which to write the property data.

Return Value

A result code. See “Audio File Result Codes.”

Discussion

This function can be used to get information about the capabilities of Audio File Services data types, for example, to determine which file types can take which data formats, what file types are supported, what file type can hold a particular data type, and so forth. This function cannot be used to get information about the properties of particular files. So the properties whose information you are obtaining are global to the Audio File Services programming interface, not properties specific to any file.

Availability

Available in Mac OS X v10.3 and later.

Declared In

AudioFile.h

AudioFileGetGlobalInfoSize

Gets the size of a global audio file property.

OSStatus AudioFileGetGlobalInfoSize (
   AudioFilePropertyID inPropertyID,
   UInt32 inSpecifierSize,
   void *inSpecifier,
   UInt32 *outDataSize
);

Parameters

inPropertyID: The property whose data size you want to get. For possible values, see “Audio File Global Info Properties.”
inSpecifier: A pointer to a specifier (a pointer to a buffer containing some data which is different for each property. The type of the data required is described in the description of each property.)
outDataSize: A pointer to the size in bytes of the current value of the property. To get the size of the property value, you need a buffer of this size.

Return Value

A result code. See “Audio File Result Codes.”

Discussion

This function can be used to get information about the capabilities of Audio File Service data types, for example, to determine which file types can take which data formats.

Availability

Available in Mac OS X v10.3 and later.

Declared In

AudioFile.h

AudioFileGetUserData

Gets the data of a chunk in an audio file.

OSStatus AudioFileGetUserData (
   AudioFileID inAudioFile,
   UInt32 inUserDataID,
   UInt32 inIndex,
   UInt32 *ioUserDataSize,
   void *outUserData
);

Parameters

inAudioFile: The audio file whose chunk you want to get.
inUserDataID: The four-character code of the designated chunk.
inIndex: An index specifying which chunk with the four-character code specified in the inUserDataID parameter you want to query.
ioUserDataSize: On input, a pointer to the size of the buffer containing the designated chunk. On output, a pointer to the size of bytes copied to the buffer.
outUserData: A pointer to a buffer in which to copy the chunk data.

Return Value

A result code. See “Audio File Result Codes.”

Availability

Available in Mac OS X v10.4 and later.

Declared In

AudioFile.h

AudioFileGetUserDataSize

Gets the size of a chunk in an audio file.

OSStatus AudioFileGetUserDataSize (
   AudioFileID inAudioFile,
   UInt32 inUserDataID,
   UInt32 inIndex,
   UInt32 *outUserDataSize
);

Parameters

inAudioFile: The audio file whose chunk size you want to find out.
inUserDataID: The four-character code of the designated chunk.
inIndex: An index specifying which chunk with the four-character code specified in the inUserDataID parameter you want to query.
outUserDataSize: On output, a pointer the size of the user data chunk.

Return Value

A result code. See “Audio File Result Codes.”

Availability

Available in Mac OS X v10.4 and later.

Declared In

AudioFile.h

AudioFileInitialize

Deletes the content of an existing audio file.

   
OSStatus AudioFileInitialize (
   const struct FSRef *inFileRef,
   AudioFileTypeID inFileType,
   const AudioStreamBasicDescription *inFormat,
   UInt32 inFlags,
   AudioFileID *outAudioFile);

Parameters

inFileRef: A pointer to the audio file you want to initialize.
inFileType: The type of audio file to initialize the file to.
inFormat: A pointer to the structure that describes the format of the data.
inFlags: Flags for creating or opening the file. Currently set to 0.
outAudioFile: On output, a pointer to the newly created audio file.

Return Value

A result code. See “Audio File Result Codes.”

Availability

Available in Mac OS X v10.2 and later.

Declared In

AudioFile.h

AudioFileInitializeWithCallbacks

Deletes the content of an existing file based on callbacks you provide to get the data.

OSStatus AudioFileInitializeWithCallbacks (
   void *inClientData,
   AudioFile_ReadProc inReadFunc,
   AudioFile_WriteProc inWriteFunc,
   AudioFile_GetSizeProc inGetSizeFunc,
   AudioFile_SetSizeProc inSetSizeFunc,
   AudioFileTypeID inFileType,
   const AudioStreamBasicDescription *inFormat,
   UInt32 inFlags,
   AudioFileID *outAudioFile
);

Parameters

inClientData: A pointer to a constant passed to your callbacks. Th constant should contain any information you use to manage the state for reading data from the file.
inReadFunc: A function called when it is necessary to read data.
inWriteFunc: A function called when it is necessary to write data.
inGetSizeFunc: A function called when it is necessary to know the size of the existing file.
inSetSizeFunc: A function called when it is necessary to set the size of the existing file.
inFileType: The type of audio file to initialize
inFormat: A pointer to a structure that describes the format of the data.
inFlags: Flags for creating or opening the file. Currently set to 0.
outAudioFile: On output, a pointer to the newly initialized audio file.

Return Value

A result code. See “Audio File Result Codes.”

Availability

Available in Mac OS X v10.3 and later.

Declared In

AudioFile.h

AudioFileOpen

Opens an existing audio file (specified by a file system reference) for reading or reading and writing.

   
OSStatus AudioFileOpen (
   const struct FSRef *inFileRef,
   SInt8 inPermissions,
   AudioFileTypeID inFileTypeHint,
   AudioFileID *outAudioFile);

Parameters

inFileRef: A pointer to the audio file you want to open.
inPermissions: The permissions you want to designate for the file. Use the permission constants associated with the file system’s FSOpenFork function.
inFileTypeHint: A hint to indicate the file type of the designated file. For files without filename extensions and with types not easily or uniquely determined from the data (such as ADTS,AC3), use this hint to indicate the file type. Otherwise, pass 0. Only use this hint in OS X versions 10.3.1 or greater. In all earlier versions, any attempt to open these files fails.
outAudioFile: On output, a pointer to the newly opened file.

Return Value

A result code. See “Audio File Result Codes.”

Availability

Available in Mac OS X v10.2 and later.

Declared In

AudioFile.h

AudioFileOpenURL

Open an existing audio file specified by a URL for reading or reading and writing.

   
OSStatus AudioFileOpenURL (
   CFURLRef inFileRef,
   SInt8 inPermissions,
   AudioFileTypeID inFileTypeHint,
   AudioFileID *outAudioFile);

Parameters

inFileRef: The URL of an existing audio file.
inPermissions: Permissions for the designated file. Use the permission constants associated with the FSOpenFork function (declared in the Core Services Files.h header file).
inFileTypeHint: A hint for the file type of the designated file. For files without filename extensions and with types not easily or uniquely determined from the data (such as ADTS or AC3), use this hint to indicate the file type. Otherwise, pass 0. Only use this hint in OS X versions 10.3.1 or greater. In all earlier versions, any attempt to open these files fails.
outAudioFile: On output, a pointer to the newly opened audio file.

Return Value

A result code. See “Audio File Result Codes.”

Availability

Available in Mac OS X v10.5 and later.

Declared In

AudioFile.h

AudioFileOpenWithCallbacks

Opens an existing file with callbacks you provide.

OSStatus AudioFileOpenWithCallbacks (
   void *inClientData,
   AudioFile_ReadProc inReadFunc,
   AudioFile_WriteProc inWriteFunc,
   AudioFile_GetSizeProc inGetSizeFunc,
   AudioFile_SetSizeProc inSetSizeFunc,
   AudioFileTypeID inFileTypeHint,
   AudioFileID *outAudioFile
);

Parameters

inClientData: A pointer to a constant passed to your callbacks. Th constant should contain any information you use to manage the state for reading data from the file.
inReadFunc: A function called when it is necessary to read data.
inWriteFunc: A function called when it is necessary to write data.
inGetSizeFunc: A function called when it is necessary to know the total file size.
inSetSizeFunc: A function called when it is necessary to set the file size.
inFileTypeHint: A hint about the type of the designated file. For files with no filename extension and without a type easily or uniquely determined from the data (ADTS,AC3), use this hint to indicate the file type. Otherwise, pass 0 for this parameter. The hint is only available on OS X versions 10.3.1 or greater. In versions prior to OS X 10.3.1, opening files such files fails.
outAudioFile: On output, a pointer to the newly opened file.

Return Value

A result code. See “Audio File Result Codes.”

Availability

Available in Mac OS X v10.3 and later.

Declared In

AudioFile.h

AudioFileOptimize

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

OSStatus AudioFileOptimize (
   AudioFileID inAudioFile
);

Parameters

inAudioFile: The audio file you want to optimize.

Return Value

A result code. See “Audio File Result Codes.”

Discussion

This function optimizes the file so additional audio information can be appended to the existing data. Typically, this operation places the audio data at the end of the file. Hence, additional data can be written to the end of the file.

Do not use this potentially expensive and time-consuming operation during time-critical operations. Instead, use the kAudioFilePropertyIsOptimized constant to check on the optimized state of the file.

Availability

Available in Mac OS X v10.2 and later.

Declared In

AudioFile.h

AudioFileReadBytes

Reads bytes of audio data from an audio file.

OSStatus AudioFileReadBytes (
   AudioFileID inAudioFile,
   Boolean inUseCache,
   SInt64 inStartingByte,
   UInt32 *ioNumBytes,
   void *outBuffer
);

Parameters

inAudioFile: The audio file whose bytes of audio data you want to read.
inUseCache: Set to true if you want to cache the data. You should cache reads and writes if you read or write the same portion of a file multiple times. To request that the data not be cached, if possible, set to false. You should not cache reads and writes if you read or write data from a file only once.
inStartingByte: The byte offset of the audio data you want to be returned.
ioNumBytes: On input, a pointer to the number of bytes to read. On output, a pointer to the number of bytes actually read.
outBuffer: A pointer to user-allocated memory large enough for the requested bytes.

Return Value

A result code. See “Audio File Result Codes.”

Discussion

This function returns eofErr when the read operation encounters the end of the file. Note that Audio File Services only reads one 32-bit chunk of a file at a time.

Availability

Available in Mac OS X v10.2 and later.

Declared In

AudioFile.h

AudioFileReadPackets

Reads packets of audio data from an audio file.

OSStatus AudioFileReadPackets (
   AudioFileID inAudioFile,
   Boolean inUseCache,
   UInt32 *outNumBytes,
   AudioStreamPacketDescription *outPacketDescriptions,
   SInt64 inStartingPacket,
   UInt32 *ioNumPackets,
   void *outBuffer
);

Parameters

inAudioFile: The audio file from which packets of audio data are to be read.
inUseCache: Set to true to cache the data. Otherwise, set to false.
outNumBytes: On output, a pointer to the number of bytes actually returned.
outPacketDescriptions: A pointer to an array of packet descriptions that have been allocated The array must contain at least as many entries as have been requested to read. On output, these packet descriptions are filled out with the correct information if the format is VBR. Pass NULL if the data format is CBR. Packet descriptions are not necessary for CBR data and are not filled out even if passed.
inStartingPacket: The packet index of the first packet you want to be returned.
ioNumPackets: On input, a pointer to the number of packets to read. On output, the number of packets actually read.
outBuffer: A pointer to user-allocated memory. Its size is determined by multiplying the the number of packets requested times the maximum (or upper bound on) packet size of the designated audio file.

Return Value

A result code. See “Audio File Result Codes.”

Discussion

For all uncompressed formats, this function equates packets with frames. When the ioNumPackets parameter returns fewer packets than requested, it indicates an end-of-file condition. Note that Audio File Services only reads one 32-bit chunk of a file at a time.

Availability

Available in Mac OS X v10.2 and later.

Declared In

AudioFile.h

AudioFileRemoveUserData

Removes a chunk of data from an audio file.

OSStatus AudioFileRemoveUserData (
   AudioFileID inAudioFile,
   UInt32 inUserDataID,
   UInt32 inIndex
);

Parameters

inAudioFile: The audio file whose chunk of data you want to remove.
inUserDataID: The four-character code such as COMM of the designated chunk.
inIndex: An index specifying which chunk with the four-character code specified in the inUserDataID parameter you want to query.

Return Value

A result code. See “Audio File Result Codes.”

Availability

Available in Mac OS X v10.4 and later.

Declared In

AudioFile.h

AudioFileSetUserData

Sets the data of a chunk in an audio file.

OSStatus AudioFileSetUserData (
   AudioFileID inAudioFile,
   UInt32 inUserDataID,
   UInt32 inIndex,
   UInt32 inUserDataSize,
   const void *inUserData
);

Parameters

inAudioFile: The audio file whose chunk of data you want to set.
inUserDataID: The four-character code of the designated chunk.
inIndex: An index specifying which chunk with the four-character code specified in the inUserDataID parameter you want to query.
inUserDataSize: On input, the size of the data to copy. On output, the size of the bytes copied from the buffer.
inUserData: A pointer to a buffer from which to copy the chunk data.

Return Value

A result code. See “Audio File Result Codes.”

Availability

Available in Mac OS X v10.4 and later.

Declared In

AudioFile.h

AudioFileWriteBytes

Writes bytes of audio data to an audio file.

OSStatus AudioFileWriteBytes (
   AudioFileID inAudioFile,
   Boolean inUseCache,
   SInt64 inStartingByte,
   UInt32 *ioNumBytes,
   const void *inBuffer
);

Parameters

inAudioFile: The audio file to which you want to write bytes of data.
inUseCache: Set to true if you want to cache the data. Otherwise, set to false.
inStartingByte: The byte offset where the audio data should be written.
ioNumBytes: On input, a pointer the number of bytes to write. On output, a pointer to the number of bytes actually written.
inBuffer: A pointer to a buffer containing the bytes to be written.

Return Value

A result code. See “Audio File Result Codes.”

Availability

Available in Mac OS X v10.2 and later.

Declared In

AudioFile.h

AudioFileWritePackets

Writes packets of audio data to an audio data file.

OSStatus AudioFileWritePackets (
   AudioFileID inAudioFile,
   Boolean inUseCache,
   UInt32 inNumBytes,
   const AudioStreamPacketDescription *inPacketDescriptions,
   SInt64 inStartingPacket,
   UInt32 *ioNumPackets,
   const void *inBuffer
);

Parameters

inAudioFile: The audio file to write to.
inUseCache: Set to true if you want to cache the data. Otherwise, set to false.
inNumBytes: The number of bytes of audio data being written.
inPacketDescriptions: A pointer to an array of packet descriptions for the audio data. Not all formats require packet descriptions. If no packet descriptions are required, for instance, if you are writing CBR data, pass NULL.
inStartingPacket: The packet index for the placement of the first provided packet.
ioNumPackets: On input, a pointer to the number of packets to write. On output, a pointer to the number of packets actually written.
inBuffer: A pointer to user-allocated memory containing the new audio data to write to the audio data file.

Return Value

A result code. See “Audio File Result Codes.”

Discussion

For all uncompressed formats, this function equates packets with frames.

Availability

Available in Mac OS X v10.2 and later.

Declared In

AudioFile.h

Callbacks by Task

Reading and Writing Audio File Data

Getting the Size of Audio File Data

Callbacks

AudioFile_GetSizeProc

Gets the size of the file data when used in conjunction with the AudioFileOpenWithCallbacks or AudioFileInitializeWithCallbacks. functions.)

   
   SInt64 (*AudioFile_GetSizeProc)(
   void *inClientData);

If you name your function MyAudioFile_GetSizeProc, you would declare it like this:

   SInt64 MyAudioFile_GetSizeProc (
   void *inClientData);

Parameters

inClientData: A pointer to the client data as set in the inClientData parameter to the AudioFileOpenWithCallbacks or AudioFileInitializeWithCallbacks functions.

Return Value

The callback should return the size of the data.

Availability

Available in Mac OS X v10.3 and later.

Declared In

AudioFile.h

AudioFile_ReadProc

Reads audio data when used in conjunction with the AudioFileOpenWithCallbacks or AudioFileInitializeWithCallbacks functions.)

   
typedef OSStatus (*AudioFile_ReadProc)(
   void     *inClientData,
   SInt64    inPosition,
   UInt32    requestCount,
   void     *buffer,
   UInt32   *actualCount);

If you name your function MyAudioFile_ReadProc, you would declare it like this:


OSStatus MyAudioFile_ReadProc (
   void     *inClientData,
   SInt64    inPosition,
   UInt32    requestCount,
   void     *buffer,
   UInt32   *actualCount);

Parameters

inClientData: A pointer to the client data as set in the inClientData parameter to AudioFileOpenWithCallbacks or AudioFileInitializeWithCallbacks.
inPosition: An offset into the data from which to read.
requestCount: The number of bytes to read.
buffer: A pointer to the buffer in which to put the data read.
actualCount: On output, the callback should set this parameter to a pointer to the number of bytes successfully read.

Return Value

A result code. See “Audio File Result Codes.”

Discussion

This callback function is called when Audio File Services needs to read data.

Availability

Available in Mac OS X v10.5 and later.

Declared In

AudioFile.h

AudioFile_WriteProc

A callback for writing file data when used in conjunction with the AudioFileOpenWithCallbacks or AudioFileCreateWithURL functions.)

   
OSStatus (*AudioFile_WriteProc) (
   void          *inClientData,
   SInt64         inPosition,
   UInt32         requestCount,
   const void    *buffer,
   UInt32        *actualCount);

If you name your function MyAudioFile_WriteProc, you would declare it like this:


OSStatus (MyAudioFile_WriteProc)(
   void     *inClientData,
   SInt64    inPosition,
   UInt32    requestCount,
   void     *buffer,
   UInt32   *actualCount);

Parameters

inClientData: A pointer to the client data as set in the inClientData parameter to AudioFileOpenWithCallbacks orAudioFileInitializeWithCallbacks.
inPosition: An offset into the data from which to read.
requestCount: The number of bytes to write.
buffer: A pointer to the buffer containing the data to write.
actualCount: Upon completion, the callback should set this to a pointer to the number of bytes successfully written.

Return Value

A result code. See “Audio File Result Codes.”

Discussion

This callback function is invoked when Audio File Services needs to write data.

Availability

Available in Mac OS X v10.3 and later.

Declared In

AudioFile.h

Data Types

AudioFileID

Defines an opaque data type that represents an audio file object.

typedef    struct OpaqueAudioFileID    *AudioFileID;

Availability

Available in Mac OS X v10.2 and later.

Declared In

AudioFile.h

AudioFilePropertyID

A constant for an audio file property.

typedef UInt32            AudioFilePropertyID;

Availability

Available in Mac OS X v10.2 and later.

Declared In

AudioFile.h

AudioFile_SMPTE_Time

A data structure for describing SMPTE (Society of Motion Picture and Television Engineers) time.


struct AudioFile_SMPTE_Time
   {
   SInt8 mHours;
   UInt8 mMinutes;
   UInt8 mSeconds;
   UInt8 mFrames;
   UInt32 mSubFrameSampleOffset;
};
typedef struct AudioFile_SMPTE_Time AudioFile_SMPTE_Time;

Fields

mHours: The hours.
mMinutes: The minutes.
mSeconds: The seconds.
mFrames: The frames.
mSubFrameSampleOffset: The sample offset within a frame.

Availability

Available in Mac OS X v10.3 and later.

Declared In

AudioFile.h

AudioFileMarker

An audio file 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;
};
typedef struct AudioFileMarker AudioFileMarker;

Fields

mFramePosition: The frame in the file counting from the start of the audio data.
mName: The name of the marker.
mMarkerID: A unique ID for the marker.
mSMPTETime: The SMPTE time for this marker.
mType: The marker type.
mReserved: A reserved field. Set to 0.
mChannel: The channel number referred to by the marker. Set to 0 if the marker applies to all channels.

Availability

Available in Mac OS X v10.3 and later.

Declared In

AudioFile.h

AudioFileMarkerList

A list of markers associated with an audio file, including their SMPTE time type, the number of markers, and the markers themselves.


struct AudioFileMarkerList
   {
   UInt32                mSMPTE_TimeType;
   UInt32                mNumberMarkers;
   AudioFileMarker       mMarkers[kVariableLengthArray];
};
typedef struct AudioFileMarkerList AudioFileMarkerList;

Fields

mSMPTE_TimeType: The SMPTE time type of the whole list of markers in an audio file.
mNumberMarkers: The number of markers in the list.
mMarkers[kVariableLengthArray]: A array describing the length of the marker list.

Availability

Available in Mac OS X v10.3 and later.

Declared In

AudioFile.h

AudioFileRegion

An audio file region specifies a segment of audio data.


struct AudioFileRegion
   {
   UInt32                mRegionID;
   CFStringRef           mName;
   UInt32                mFlags;
   UInt32                mNumberMarkers;
   AudioFileMarker       mMarkers[kVariableLengthArray];
};
typedef struct AudioFileRegion AudioFileRegion;

Fields

mRegionID: A unique ID associated with the audio file region.
mName: The name of the region.
mFlags: Audio File Services region flags. For details, see “Audio File Region Flags.”
mNumberMarkers: The number of markers in the array specified in the mMarkers parameter.
mMarkers: A description of where the data in the region starts. For details, see “Audio File Marker Types.”

Discussion

Typically, a region consists of at least two markers designating the beginning and end of the segment. Other markers might define additional meta information such as sync point.

Availability

Available in Mac OS X v10.3 and later.

Declared In

AudioFile.h

AudioFile RegionList

A list of the audio file regions in a file.


struct AudioFileRegionList
   {
   UInt32                mSMPTE_TimeType;
   UInt32                mNumberRegions;
   AudioFileRegion       mRegions[kVariableLengthArray];
};
typedef struct AudioFileRegionList AudioFileRegionList;

Fields

mSMPTE_TimeType

The SMPTE timing scheme used in the file. See Core Audio’s CAFFile.h header file for the values used here. For more information, see Core Audio Overview.

mNumberRegions

The number of regions in the list specified in the mRegions parameter.

mRegions

A list of more than one audio file regions. For information on the AudioFileRegion data type, see AudioFileRegion.

Audio file markers are variable length, so this list cannot be accessed as an array. For details on the AudioFileMarker data type, see AudioFileMarker.

Use the NextAudioFileRegion convenience macro (declared in AudioFile.h) for traversing the region list instead. This macro enables you to step to the next region in the data that Audio File Services returns.

Discussion

This structure is used by the kAudioFilePropertyRegionList property.

Availability

Available in Mac OS X v10.3 and later.

Declared In

AudioFile.h

AudioFramePacketTranslation

A data structure used by the kAudioFilePropertyPacketToFrame and kAudioFilePropertyFrameToPacket properties.


struct AudioFramePacketTranslation
   {
   SInt64 mFrame;
   SInt64 mPacket;
   UInt32 mFrameOffsetInPacket;
};
typedef struct AudioFramePacketTranslation AudioFramePacketTranslation;

Fields

mFrame: A frame number.
mPacket: A packet number.
mFrameOffsetInPacket: A frame offset in a packet.

Availability

Available in Mac OS X v10.3 and later.

Declared In

AudioFile.h

AudioFilePacketTableInfo

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; }; typedef struct AudioFilePacketTableInfo AudioFilePacketTableInfo;

Fields

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 might have packets with contents that are not completely valid, but that represent priming or remainder frames not intended for playback. For example, a file with 100 packets of AAC is nominally 1024 * 100 = 102400 frames of data. However, the first 2112 frames might be priming frames.

A number of remainder frames might be added to pad out to a full packet of 1024 frames. Discard the priming and remainder frames.

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.

Availability

Available in Mac OS X v10.3 and later.

Declared In

AudioFile.h

AudioFileTypeandFormat ID

A specifier for the constantkAudioFileGlobalInfo_AvailableStreamDescriptionsForFormat.


struct AudioFileTypeAndFormatID
   {
   AudioFileTypeID  mFileType;
   UInt32           mFormatID;
};
typedef struct AudioFileTypeAndFormatID AudioFileTypeAndFormatID;

Fields

mFileType: A four-character code for the file type (for instance, the kAudioFileAIFFType type.
mFormatID: A four-character code for the format ID such as kAudioFormatLinearPCM, kAudioFormatMPEG4AAC, and so forth. (See the AudioFormat.h header file for declarations.)

Discussion

This structure specifies a desired audio file type and data format ID so you can obtain a list of stream descriptions of available formats.

Availability

Available in Mac OS X v10.3 and later.

Declared In

AudioFile.h

Constants

Built-In Audio File Types

Constants shipped with Mac OS X indicating the type of file to be written or a hint about what type of file to expect from data provided.

   
enum {
   kAudioFileAIFFType                = 'AIFF',
   kAudioFileAIFCType                = 'AIFC',
   kAudioFileWAVEType                = 'WAVE',
   kAudioFileNextType                = 'NeXT',
   kAudioFileMP3Type                 = 'MPG3',
   kAudioFileMP2Type                 = 'MPG2',
   kAudioFileMP1Type                 = 'MPG1',
   kAudioFileAC3Type                 = 'ac-3',
   kAudioFileAAC_ADTSType            = 'adts',
   kAudioFileMPEG4Type               = 'mp4f',
   kAudioFileM4AType                 = 'm4af',
   kAudioFileCAFType                 = 'caff',
   kAudioFile3GPType                 = '3gpp',
   kAudioFile3GP2Type                = '3gp2',
   kAudioFileAMRType                 = 'amrf'
};
   
typedef UInt32            AudioFileTypeID;

Constants

kAudioFileAIFFType

An Audio Interchange File Format (AIFF) file.

Available in Mac OS X v10.2 and later.

Declared in AudioFile.h

kAudioFileAIFCType

An Audio Interchange File Format Compressed (AIFF-C) file.

Available in Mac OS X v10.2 and later.

Declared in AudioFile.h

kAudioFileWAVEType

A Microsoft WAVE file.

Available in Mac OS X v10.2 and later.

Declared in AudioFile.h

kAudioFileSoundDesigner2Type

A Sound Designer II file.

Available in Mac OS X v10.2 and later.

Declared in AudioFile.h

kAudioFileNextType

A NeXT or Sun Microsystems file.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAudioFileMP3Type

An MPEG Audio Layer 3 (.mp3) file.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAudioFileMP2Type

An MPEG Audio Layer 2 (.mp2) file.

Available in Mac OS X v10.5 and later.

Declared in AudioFile.h

kAudioFileMP1Type

An MPEG Audio Layer 1 (.mp1) file.

Available in Mac OS X v10.5 and later.

Declared in AudioFile.h

kAudioFileAC3Type

An AC-3 file.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAudioFileAAC_ADTSType

An Advanced Audio Coding (AAC) Audio Data Transport Stream (ADTS) file.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAudioFileMPEG4Type

An MPEG 4 file.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAudioFileM4AType

An M4A file.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAudioFileCAFType

A Core Audio File Format file.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

Declared In

AudioFile.h

Audio File Creation Flags

Flags for use with the AudioFileCreateWithURL and AudioFileCreate functions.

   
enum {
   kAudioFileFlags_EraseFile                = 1
   kAudioFileFlags_DontPageAlignAudioData   = 2
};

Constants

kAudioFileFlags_EraseFile

If set, the AudioFileCreateWithURL function erases the contents of an existing file. If not set, then the function fails if the file already exists.

Available in Mac OS X v10.5 and later.

Declared in AudioFile.h

kAudioFileFlags_DontPageAlignAudioData

Typically, the audio data in a file is page aligned. To make reading the file data as fast as possible, you can use page-aligned data to take advantage of optimized code paths in the file system. However, when space is at a premium, you might want to avoid the additional padding required to attain alignment. To do so, set this flag when calling AudioFileCreate or AudioFileCreateWithURL.

Available in Mac OS X v10.5 and later.

Declared in AudioFile.h

Declared In

AudioFile.h

Audio File Loop Direction Constants

The playback direction of a looped segment of an audio file.

   
enum {
   kAudioFileLoopDirection_NoLooping = 0,
   kAudioFileLoopDirection_Forward = 1,
   kAudioFileLoopDirection_ForwardAndBackward = 2,
   kAudioFileLoopDirection_Backward = 3
};

Constants

kAudioFileLoopDirection_NoLooping

The segment is not looped.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAudioFileLoopDirection_Forward

Play the segment forward.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAudioFileLoopDirection_Backward

Play the segment backward.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAudioFileLoopDirection_ForwardAndBackward

Play the segment forward and backward.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

Declared In

AudioFile.h

Audio File Marker Types

A type of marker within a file used in the mType field of the AudioFileMarker structure.

   
enum {
   kAudioFileMarkerType_Generic = 0,
};

Constants

kAudioFileMarkerType_Generic

A generic marker.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

Declared In

AudioFile.h

Audio File Region Flags

Flags that specify a playback direction for an AudioFileRegion structure.

   
enum {
   kAudioFileRegionFlag_LoopEnable = 1,
   kAudioFileRegionFlag_PlayForward = 2,
   kAudioFileRegionFlag_PlayBackward = 4
};

Constants

kAudioFileRegionFlag_LoopEnable

If set, the region is looped. You must set one or both of the remaining flags must also be set for the region to be looped.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAudioFileRegionFlag_PlayForward

If set, the region is played forward.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAudioFileRegionFlag_PlayBackward

If set, the region is played backward.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

Discussion

You can set one or more of these flags. For example, if both kAudioFileRegionFlag_LoopEnable and kAudioFileRegionFlag_PlayForward are set, the region plays as a forward loop. If only kAudioFileRegionFlag_PlayForward is set, the region is played forward once. if both kAudioFileRegionFlag_PlayForward and kAudioFileRegionFlag_PlayBackward are set, the region plays forward then backward, then forward.

Declared In

AudioFile.h

Info String Keys

Key values of properties to get and set using Audio File Services functions and provide a common way to get the same information out of several different kinds of files.

   
#define kAFInfoDictionary_Artist                        "artist"
#define kAFInfoDictionary_Album                         "album"
#define kAFInfoDictionary_Tempo                         "tempo"
#define kAFInfoDictionary_KeySignature "key signature"
#define kAFInfoDictionary_TimeSignature "time signature"
#define kAFInfoDictionary_TrackNumber "track number"
#define kAFInfoDictionary_Year                          "year"
#define kAFInfoDictionary_Composer                      "composer"
#define kAFInfoDictionary_Lyricist                      "lyricist"
#define kAFInfoDictionary_Genre                         "genre"
#define kAFInfoDictionary_Title                         "title"
#define kAFInfoDictionary_RecordedDate "recorded date"
#define kAFInfoDictionary_Comments                      "comments"
#define kAFInfoDictionary_Copyright                     "copyright"
#define kAFInfoDictionary_SourceEncoder "source encoder"
#define kAFInfoDictionary_EncodingApplication "encoding application"
#define kAFInfoDictionary_NominalBitRate "nominal bit rate"
#define kAFInfoDictionary_ChannelLayout "channel layout"
#define kAFInfoDictionary_ApproximateDurationInSeconds "approximate duration in
   seconds"

Constants

kAFInfoDictionary_Artist

An artist.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAFInfoDictionary_Album

An album.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAFInfoDictionary_Tempo

A tempo.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAFInfoDictionary_KeySignature

A key signature.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAFInfoDictionary_TimeSignature

A time signature.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAFInfoDictionary_TrackNumber

A track number.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAFInfoDictionary_Year

A year.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAFInfoDictionary_Composer

A composer.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAFInfoDictionary_Lyricist

A lyricist.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAFInfoDictionary_Genre

A genre.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAFInfoDictionary_Title

A title.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAFInfoDictionary_RecordedDate

A recorded date.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAFInfoDictionary_Comments

Comments.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAFInfoDictionary_Copyright

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAFInfoDictionary_SourceEncoder

A source encoder.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAFInfoDictionary_EncodingApplication

An encoding application.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAFInfoDictionary_NominalBitRate

A nominal bit rate.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAFInfoDictionary_ChannelLayout

A channel layout.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAFInfoDictionary_ApproximateDurationInSeconds

An approximate duration in seconds.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

Declared In

AudioFile.h

Audio File Properties

Properties used by the functions described in getting and setting pieces of data in audio files. See “Working with Global Information” for details.


enum { kAudioFilePropertyFileFormat kAudioFilePropertyDataFormat kAudioFilePropertyIsOptimized kAudioFilePropertyMagicCookieData kAudioFilePropertyAudioDataByteCount kAudioFilePropertyAudioDataP kAudioFilePropertyMaximumPacketSize kAudioFilePropertyDataOffset kAudioFilePropertyChannelLayout kAudioFilePropertyDeferSizeUpdates kAudioFilePropertyDataFormatName kAudioFilePropertyMarkerList kAudioFilePropertyRegionList kAudioFilePropertyPacketToFrame kAudioFilePropertyFrameToPacket kAudioFilePropertyChunkIDs kAudioFilePropertyInfoDictionary kAudioFilePropertyPacketTableInfo kAudioFilePropertyFormatList kAudioFilePropertyPacketSize kAudioFilePropertyReserveDuration kAudioFilePropertyEstimatedDuration kAudioFilePropertyBitRate };

= 'ffmt', = 'dfmt', = 'optm', = 'mgic', = 'bcnt', acketCount = 'pcnt', = 'psze', = 'doff', = 'cmap', = 'dszu', = 'fnme', = 'mkls', = 'rgls', = 'pkfr', = 'frpk', = 'chid', = 'info', = 'pnfo', = 'flst', UpperBound = 'pkub', = 'rsrv', = 'edur', = 'brat'

Constants

kAudioFilePropertyFileFormat

The format of the audio data file.

Available in Mac OS X v10.2 and later.

Declared in AudioFile.h

kAudioFilePropertyDataFormat

An audio stream basic description containing the format of the audio data.

Available in Mac OS X v10.2 and later.

Declared in AudioFile.h

kAudioFilePropertyFormatList

To support formats such as AAC SBR in which an encoded data stream can be decoded to multiple destination formats, this property returns an array of audio format list item values (declared in AudioFormat.h) of those formats. Typically, this returns an audio format list item with the same audio stream basic description returned by kAudioFilePropertyDataFormat.

Available in Mac OS X v10.5 and later.

Declared in AudioFile.h

kAudioFilePropertyIsOptimized

Indicates whether a designated audio file has been optimized, that 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.

Available in Mac OS X v10.2 and later.

Declared in AudioFile.h

kAudioFilePropertyMagicCookieData

A pointer to memory set up by the caller. Some file types require that a magic cookie be provided before packets can be written to an audio file. Set this property before you call AudioFileWriteBytes or AudioFileWritePackets if a magic cookie exists.

Available in Mac OS X v10.2 and later.

Declared in AudioFile.h

kAudioFilePropertyAudioDataByteCount

Indicates the number of bytes of audio data in the designated file.

Available in Mac OS X v10.2 and later.

Declared in AudioFile.h

kAudioFilePropertyAudioDataPacketCount

Indicates the number of packets of audio data in the designated file.

Available in Mac OS X v10.2 and later.

Declared in AudioFile.h

kAudioFilePropertyMaximumPacketSize

Indicates the maximum size of a packet for the data in the designated file.

Available in Mac OS X v10.2 and later.

Declared in AudioFile.h

kAudioFilePropertyDataOffset

Indicates the byte offset in the file of the designated audio data.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAudioFilePropertyChannelLayout

An audio channel layout structure.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAudioFilePropertyDeferSizeUpdates

The default value (0) always updates header. If set to 1, updating the files sizes in the header is not performed every time data is written. Instead, the updating is deferred until the file has been read, optimized, or closed. This process is more efficient, but not as safe. If an application crashes before the size has been updated, the file might not be readable.

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h

kAudioFilePropertyDataFormatName

This constant is deprecated in Mac OS X v 10.5 and later. Do not use. Instead, use kAudioFormatProperty_FormatName (declared in the AudioFormat.h header file).

Available in Mac OS X v10.2 and later.

Declared in AudioFile.h

kAudioFilePropertyMarkerList

Accesses the list of markers defined in the file and returns an audio file marker list. The CF string references the returned structures must be released by the client.

Available in Mac OS X v10.2.4 and later.

Declared in AudioFile.h

kAudioFilePropertyRegionList

Accesses the list of regions defined in the file and returns an array of audio file region values. The CF string references in the returned structures must be released by the client.)

Available in Mac OS X v10.3 and later.

Declared in AudioFile.h</

Audio File Services Reference

Overview

Functions by Task

Creating and Initializing Audio Files

Opening and Closing Audio Files

Optimizing Audio Files

Reading and Writing Audio Files

Working with User Data

Working with Global Information

Functions

AudioFileClose

Parameters

Return Value

Availability

Declared In

AudioFileCountUserData

Parameters

Return Value

Discussion

Availability

Declared In

AudioFileCreate

Parameters

Return Value

Discussion

Availability

See Also

Declared In

AudioFileCreateWithURL

Parameters

Return Value

Discussion

Availability

See Also

Declared In

AudioFileGetGlobalInfo

Parameters

Return Value

Discussion

Availability

Declared In

AudioFileGetGlobalInfoSize

Parameters

Return Value

Discussion

Availability

Declared In

AudioFileGetUserData

Parameters

Return Value

Availability

See Also

Declared In

AudioFileGetUserDataSize

Parameters

Return Value

Availability

Declared In

AudioFileInitialize

Parameters

Return Value

Availability

Declared In

AudioFileInitializeWithCallbacks

Parameters

Return Value

Availability

See Also

Declared In

AudioFileOpen

Parameters

Return Value

Availability

See Also

Declared In

AudioFileOpenURL

Parameters

Return Value

Availability

See Also