Overview
The AFSoundfile is used to access a sound file on Mac OS X. When a file is opened for reading, sound buffers are read from the file. When a file is opened for writing, successive buffers are written to the file.
AFSoundfile uses the Mac OS X Extended Audio File Services library and work with all file formats that are supported by ExtAudioFile (including AIFF, WAV, AAC and CAF).
You can create any number of AFSoundfile objects, each one pointing to a different sound file. Multiple input AFSoundfile can also point to the same sound file.
You must use -initAsInput or initAsOutput to initialize an AFSoundfile object.
Tasks
Creating Instances
Opening Input Files
Opening Output Files
- createAIFFWithSamplingRate:
- createWAVWithSamplingRate:
- createAACWithSamplingRate:
- createCAFWithSamplingRate:
- createWithFileType:samplingRate:channels:
- createWithFileType:descriptor:
- createURL:type:samplingRate:channels:overWrite:
- createURL:type:descriptor:overWrite:
Closing Files
File Properties
Resampling
Channels and Channel Masks
Navigation
Data Transfers
Instance Methods
channels
Returns the number of channels of the underlying file. Zero is returned when there is no underlying file. With an output AFSoundfile, you can set the number of channels by using the -setChannels: method.
You can transfer a subset of the channels in the file by setting up a channel mask.
- (int)channels
Return Value
The number of channels of the underlying file.
channelMask
Returns the channel mask of the receiver.
The number of channels of the receiver's sound card is determined by the channels.
You can transfer fewer channels by setting up a channel mask. A channel mask is an integer. Each bit of the integer corresponds to a physical channel. The least significant bit is the first channel, the next bit represents the second channels, etc. For example, a mask of 0x5 represents the first and third channels of a sound card.
A mask bit that addresses a non-existing channel is ignored. A channel mask of 0 is a special case and it represents all channels in the sound card.
- (int)channelMask
Return Value
The channel mask.
close
Closes a file that was previously opened or created and attached to the receiver. -close calls the ExtAudioFileDispose routine in Core Audio, and releases any URL that was kept. For an output receiver, close will finish writing the output file. The receiver automatically calls -close when it is released by everyone, so that mechanism can also be used in place of -close.
An output file may not be readable without closing it.
- (void)close
createAACWithSamplingRate:
Presents an NSSavePanel to create a stereo AAC file and sets up the buffers that match the file type.
The file will be a compressed to the Advanced Audio Coding (AAC) format and embedded in an MPEG-4 file container. The usual file extension is m4a.
Returns noErr (0) if successful.
Returns kNotOutputSoundfile if the receiver is not an output AFSoundfile object.
- (OSStatus)createAACWithSamplingRate:(float)samplingRate
Parameters
samplingRate
sampling rate
used for the receiver's output sound file.
Return Value
Status of createAACWithSamplingRate (0 if successful). See constants.
createAIFFWithSamplingRate:
Presents an NSSavePanel to create a stereo AIFF (Apple Audio Interchange File Format) file and sets up the buffers that match the file type.
Returns noErr (0) if successful.
Returns kNotOutputSoundfile if the receiver is not an output AFSoundfile object.
- (OSStatus)createAIFFWithSamplingRate:(float)samplingRate
Parameters
samplingRate
sampling rate
used for the receiver's output sound file.
Return Value
Status of createAIFFWithSamplingRate (0 if successful). See constants.
createCAFWithSamplingRate:
Presents an NSSavePanel to create a stereo file with the CAF (Apple Core Audio Format) container and sets up the buffers that match the file type.
Returns noErr (0) if successful.
Returns kNotOutputSoundfile if the receiver is not an output AFSoundfile object.
- (OSStatus)createCAFWithSamplingRate:(float)samplingRate
Parameters
samplingRate
sampling rate
used for the receiver's output sound file.
Return Value
Status of createCAFWithSamplingRate (0 if successful). See constants.
createURL:type:descriptor:overWrite:
Create a file for the given URL, file type and AudioStreamBasicDescription, and sets up the buffers that match the descriptor. The overWite flag, if true, allows the receiver to remove an existing file with the same URL. The sampling rate and number of channels are part of the descriptor.
Returns noErr (0) if successful.
Returns kNotOutputSoundfile if the receiver is not an output AFSoundfile object.
- (OSStatus)createURL:(NSURL*)url type:(AudioFileTypeID)fileType descriptor:(AudioStreamBasicDescription*)descriptor overWrite:(Boolean)overwrite
Parameters
url
a file
URL,
fileType
an Audio File
Type that is specified in
<CoreAudio/AudioFile.h>,
descriptor
an
AudioStreamBasicDescription that matches the fileType
parameter,
overWrite
flag to allow an
exiting file to be overwritten.
Return Value
Status of the creation (0 if successful). See constants.
createURL:type:samplingRate:channels:overWrite:
Create a file for the given URL, file type, sampling rate and number of channels. Sets up the buffers that match the file type, sampling rate and number of channels.
Returns noErr (0) if successful.
Returns kNotOutputSoundfile if the receiver is not an output AFSoundfile object.
- (OSStatus)createURL:(NSURL*)url type:(AudioFileTypeID)fileType samplingRate:(float)samplingRate channels:(int)channels overWrite:(Boolean)overwrite
Parameters
url
a file
URL,
fileType
samplingRate
sampling rate
used for the receiver's output sound file,
channels
number of
channels in the receiver's output sound file,
overWrite
flag to allow an
exiting file to be overwritten.
Return Value
Status of the creation (0 if successful). See constants.
createWAVWithSamplingRate:
Presents an NSSavePanel to create a stereo WAV (Windows Waveform Audio File Format) file and sets up the buffers that match the file type.
Returns noErr (0) if successful.
Returns kNotOutputSoundfile if the receiver is not an output AFSoundfile object.
- (OSStatus)createWAVWithSamplingRate:(float)samplingRate
Parameters
samplingRate
sampling rate
used for the receiver's output sound file.
Return Value
Status of createWAVWithSamplingRate (0 if successful). See constants.
createWithFileType:descriptor:
Presents an NSSavePanel to create a file with the given type and AudioStreamBasicDescription, and sets up the buffers that match the descriptor. The sampling rate and number of channels are part of the descriptor.
Returns noErr (0) if successful.
Returns kNotOutputSoundfile if the receiver is not an output AFSoundfile object.
- (OSStatus)createWithFileType:(AudioFileTypeID)fileType descriptor:(AudioStreamBasicDescription*)descriptor
Parameters
fileType
an Audio File
Type that is specified in
<CoreAudio/AudioFile.h>,
descriptor
an
AudioStreamBasicDescription that matches the fileType
parameter.
Return Value
Status of the creation (0 if successful). See constants.
createWithFileType:samplingRate:channels:
Presents an NSSavePanel to create a file with the specified type, sampling rate and number of channels. Sets up the buffers that match the file type, sampling rate and number of channels.
Returns noErr (0) if successful.
Returns kNotOutputSoundfile if the receiver is not an output AFSoundfile object.
- (OSStatus)createWithFileType:(AudioFileTypeID)fileType samplingRate:(float)samplingRate channels:(int)channels
Parameters
fileType
samplingRate
sampling rate
used for the receiver's output sound file,
channels
number of
channels in the receiver's output sound file.
Return Value
Status of the creation (0 if successful). See constants.
cueTo:
Repositions the receiver to the number of seconds from the start of the file. An output receiver ignores this call.
- (void)cueTo:(float)seconds
Parameters
seconds
the number of
seconds from the beginning to cue a sound file to.
duration
Returns the length of the sound file in number of seconds. For an output receiver, this is the same as -elapsed (see below)
- (float)duration
Return Value
The length of the file, in seconds.
elapsed
Returns the current file position in number of seconds from the start of the file.
- (float)elapsed
Return Value
The elapsed time from the start of the file, in seconds.
getBuffers:numberOfBuffers:samples:
The receiver must be an input AFSoundfile object.
The client supplies an array of floating point buffer pointers to -getBuffers. The array must be at least the size of the number of buffers. Each pointer must be pointed to a floating point array that is at least as long as the number of requested samples.
The samples are resampled to the resampling rate of the receiver.
- (OSError)getBuffers:(float**)buffers numberOfBuffers:(int)n samples:(int)samples
Parameters
buffers
an array pointers
to floating point buffers. There should be
n
such pointers,
and each buffer should hold samples
floating point
values,
n
the number of
buffers. For example, this is 2 for a stereo
device,
samples
number of
floating point samples per buffer.
Return Value
Returns the status codes listed here and errors that are returned by Core Audio's ExtAudioFileRead, including EOF (see <MacErrors.h>). Returns noErr (0) if getBuffer is successful.
initAsInput
Initializes the receiver as an input AFSoundfile object.
- (id)initAsInput
Return Value
An initialized AFSoundfile object or nil if the object could not be initialized.
initAsOutput
Initializes the receiver as an output AFSoundfile object.
- (id)initAsOutput
Return Value
An initialized AFSoundfile object or nil if the object could not be initialized.
open
Presents an NSOpenPanel for file selection and sets up the buffers that match the audio file type. Returns noErr (0) if successful.
Returns kNotInputSoundfile if the receiver is not an input AFSoundfile object.
- (OSStatus)open
Return Value
Status of open 0 if successful. See constants.
openURL:
Opens the file for the URL and sets up the buffers that match the audio file type. Returns noErr (0) if successful.
Returns kNotInputSoundfile if the receiver is not an input AFSoundfile object.
- (OSStatus)openURL:(NSURL*)url
Parameters
url
the URL of the
file that is to be used as the input sound file by the
receiver.
Return Value
Status of openURL (0 if successful). See constants.
putBuffers:numberOfBuffers:samples:
The receiver must be an output AFSoundfile object.
The client supplies an array of floating point buffer pointers to -putBuffers. The array must be at least the size of the number of buffers. Each pointer must be pointed to a floating point array that is at least as long as the number of requested samples.
The samples are resampled to the resampling rate of the receiver.
- (OSError)putBuffers:(float**)buffers numberOfBuffers:(int)n samples:(int)samples
Parameters
buffers
an array pointers
to floating point buffers. There should be
n
such pointers,
and each buffer should hold samples
floating point
values,
n
the number of
buffers. For example, this is 2 for a stereo
device,
samples
number of
floating point samples per buffer.
Return Value
Returns the status codes listed here and errors that are returned by Core Audio's ExtAudioFileWrite (see <MacErrors.h>). Returns noErr (0) if putBuffer is successful.
resamplingQuality
Returns the current resampling quality (see below for resampling rate).
Resampling is performed with the embedded AudioConverter that is in the ExtAudioFile. The resamplingQuality is a number between 0 and 4. The number corresponds respectively to the five AudioConverter qualities:
kAudioConverterQuality_Min
kAudioConverterQuality_Low
kAudioConverterQuality_Medium
kAudioConverterQuality_High
kAudioConverterQuality_Max
kAudioConverterQuality_Low
kAudioConverterQuality_Medium
kAudioConverterQuality_High
kAudioConverterQuality_Max
- (int)resamplingQuality
Return Value
The current resampling quality.
resamplingRate
Returns the current resampling rate in the number of samples per second (e.g., 11025.0)
Audio data is encoded in the sound file at the file's sampling rate (see below). The rate that buffers are passed between the client and the AFSoundfile can be resampled to a different rate. One reason to do this to ensure that buffers for multiple objects in the Audio Library work at a constant sampling rate even when physical devices and files have different sampling rates.
If the resampling rate is set to 0.0, no resampling is done and the buffers are transferred at the sampling rate of the underlying sound file of the receiver.
Resampling is performed with the embedded AudioConverter that is in the ExtAudioFile (see -resamplingQuality).
- (float)resamplingRate
Return Value
The current resampling rate (0.0 if no resampling).
samplingRate
Returns the sampling rate of the underlying file.
- (float)samplingRate
Return Value
The current sound file's sampling rate.
setChannels:
Sets the number of channels that is written by an output AFSoundfile object. -setChannels: has no effect if the receiver is an input AFSoundfile.
You can write a subset of the channels in the file by setting up a channel mask. Zeros are written out to the channels that are not assigned in the channel mask.
- (void)setChannels:(int)channels
Parameters
channels
the number of
channels.
setChannelMask:
Sets the channel mask.
- (void)setChannelMask:(int)mask
Parameters
mask
the channel
Mask
setResamplingQuality:
Sets the resampling quality of an input AFSoundfile. The default number is 3.
- (void)setResamplingQuality:(int)resamplingQuality
Parameters
resamplingQuality
resampling
quality, an integer between 0 and 4. See
-resamplingQuality for the meaning of the
integers.
setResamplingRate:
Sets the resampling rate. (see also -setResamplingQuality).
- (void)setResamplingRate:(float)resamplingRate
Parameters
resamplingRate
resampling
rate in samples/second
setSamplingRate:
Sets the sampling rate of an output sound file. This has no affect if the receiver is an input AFSoundfile object.
- (void)setSamplingRate:(float)samplingRate
Parameters
samplingRate
sampling rate in
samples/second
url
Returns the url of the underlying sound file.
- (NSURL*)url
Return Value
The url of the underlying sound file.
Constants
#define
kNotInputSoundfile -400
#define kNotOutputSoundfile -401
#define kOpenCancelledByUser -402
#define kCannotOpenFile -403
#define kFormatNotImplemented -404
#define kNotOutputSoundfile -401
#define kOpenCancelledByUser -402
#define kCannotOpenFile -403
#define kFormatNotImplemented -404
The following Audio File Types are directly supported by Audio Library. They are defined in <CoreAudio/AudioFile.h>.
enum {
kAudioFileAIFFType =
'AIFF',
kAudioFileWAVEType = 'WAVE',
kAudioFileM4AType = 'm4af', // AAC in MPEG-4 container
kAudioFileCAFType = 'caff'
kAudioFileWAVEType = 'WAVE',
kAudioFileM4AType = 'm4af', // AAC in MPEG-4 container
kAudioFileCAFType = 'caff'
}