AFSoundfile Class Reference


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

-
initAsInput
- initAsOutput


Opening Input Files

- open
-
openURL:


Opening Output Files

- createAIFFWithSamplingRate:
-
createWAVWithSamplingRate:
-
createAACWithSamplingRate:
-
createCAFWithSamplingRate:
-
createWithFileType:samplingRate:channels:
-
createWithFileType:descriptor:
-
createURL:type:samplingRate:channels:overWrite:
-
createURL:type:descriptor:overWrite:


Closing Files

- close


File Properties

- url
-
samplingRate
-
setSamplingRate:


Resampling

- resamplingRate
-
setResamplinRate:
-
resamplingQuality
- setResamplingQuality:


Channels and Channel Masks

- channels
-
setChannels:
- channelMask
-
setChannelMask:



Navigation

- elapsed
- duration
- cueTo:


Data Transfers

- getBuffers:numberOfBuffers:samples:
- putBuffers:numberOfBuffers:samples:




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
one of the Audio File Types that is listed here,

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
one of the Audio File Types that is listed here,

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


- (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


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'

}