AFSoundcard Class Reference


Overview


The AFSoundcard is the object that represents a specific sound card in Core Audio. When it is started, an input AFSoundcard calls its delegate when there is a sound buffer available from an input sound card, and an output AFSoundcard calls its delegate when a sound buffer is need by an output sound card.

You can create any number of AFSoundcard objects, each one pointing to a different sound card. Multiple AFSoundcards can also point to the same sound card.

An AFSoundcard also calls its delegate when certain information regarding the sound cards change. The AFSoundcard calls it delegate when any external sound card is added or removed, and if the properties of the selected sound card changes. For example, when a different process changes the volume of the selected sound card, the AFSoundcard notifies its delegate with the value that the volume has changed to, when the sampling rate of the selected sound card changes, the AFSoundcard notifies its delegate with the value of the new sampling rate.

The AFSoundcard can manage a set of NSPopUpButtons. Managed NSPopupButtons can be a menu of all sound devices in Core Audio. A NSPopupButton can also be a menu of sources, a menu of sampling rates or a menu of bit depths in the selected sound card. The AFSoundcard can also manage a set of NSSliders which represent the volume of each channel of the sound card.

When an NSControl is given to AFSoundcard to manage, the control automatically tracks changes made to the selected sound card by a different process. If the user changes the NSControl value, AFSoundcard sends the changes to Core Audio.

It is highly recommended that you do nothing yourself with an NSControl, but simply send it to the AFSoundcard to manage.



Tasks


Creating Instances

Device

Getting Device Properties

Device Source

Device Bit depth and Number of channels

Device Sampling Rate

Device Volume Controls

Buffers

Channel Masks

Setting the Delegate

Resampling

Sampling State

Rate Scalar

Pushing Data Samples

Access to Internal Classes



Instance Methods


bufferLength

Returns the buffer length of the receiver.

When the buffer length is set to 0, AFSoundcard uses the buffer length from Core Audio.

- (int)bufferLength

Return Value

The buffer length.



channelMask

Returns the channel mask of the receiver.

The physical number of channels of the receiver's sound card is contained in the format. This is the default number of buffers that are transferred with the inputReceivedFromSoundcard and outputNeededBySoundCard calls of the AFSoundcardDelegate.

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.



delegate

Returns the receiver's delegate.

- (id <AFSoundcardDelegate>)delegate

Return Value

The receiver's delegate.



deviceHasVolumeControl:

Returns true if the volume of a particular channel of the selected sound card is adjustable.

Channel 0 is a master channel of the sound card, channel 1 is the first channel, channel 2 is the second channel, etc.

- (Boolean)deviceHasVolumeControl:(int)channel

Parameters

channel
Return Value

True if the volume for the particular channel is adjustable.



deviceID

Returns the Core Audio AudioDeviceID of the selected sound card.

- (AudioDeviceID)deviceID

Return Value

The AudioDeviceID of the selected sound card.



deviceList

Returns the AFList of the receiver. You probably won't need to use this, since an array of AFDevice objects can be obtained with the -devices method below. The AFList does however, allow you to find the current default device and to search for the AFDevice given an AudioDeviceID or a name.

There are usually two lists, one for input devices and one for output devices. The receiver returns the AFList that was initialized with.

- (AFList*)deviceList

Return Value

The AFList for the receiver.



devices

Returns an NSArray containing the AFDevices that are currently available to the receiver. If the receiver is an input AFSoundcard, the array contains only input AFDevices, and if the receiver is an output AFSoundcard, the array contains only output AFDevices.

- (NSArray*)devices

Return Value

An array of AFDevice objects.



format

Returns the current AFFormat. The AFFormat contains the number of bits and channels for the sound card.

- (AFFormat*)format

Return Value

The current AFFormat or nil if the format is not available.



initWithDeviceList:

Initializes the AFSoundcard object from an AFList. If the AFList is an input list of devices, the initialized object is an input AFSoundcard, otherwise, it is an output AFSoundcard.

It is best not to use this directly, since you will need to create your own AFList. Instead, let AFManager create an AFSoundcard object for you.

- (id)initWithDeviceList:(AFList*)deviceList

Parameters

deviceList
Return Value

An initialized AFSoundcard object or nil if the object could not be created.



isInput

Returns true if the receiver was initialized as an input AFSoundcard.

- (Boolean)isInput

Return Value

True if the AFSoundcard object is initialized as an input list. Returns false otherwise.



isRunning

Returns true if the receiver is sampling its sound card (see -start).

- (Boolean)isRunning

Return Value

True if the receiver is sampling.



pushBuffers:numberOfBuffers:samples:rateScalar:

This is an alternate way to submit data buffers to an output sound card. The "normal" way, after starting an output sound card, is for the delegate to wait for an -outputNeededBySoundcard call, where the data buffers are "pulled" by the sound card.

Instead of supplying buffers when the data is pulled, you can also push data to the sound card. To do this, return false to the -outputNeededBySoundcard request. The delegate can use the -outputNeededBySoundcard routine to provide buffer management timing, or it could simply not implement a -outputNeededBySoundcard call.

You can "push" data to the receiver by using the -pushBuffers method, making sure that the calls are made at the appropriate periodicity.

The rateScalar parameter lets you change the sampling rates by small amounts from the nominal sampling rate of the output sound card. If the data is sources from an input AFSoundcard, the rate scalar parameter should come from the input AFSoundcard. If you are generating audio buffers from a sound file or from a timer (e.g., NSTimer) that is running at a constant rate, set the rate scalar parameter to 1.0 and the sampling will be performed at the physical sampling rate of the output sound card.

- (void)pushBuffers:(float**)buffers numberOfBuffers:(int)n samples:(int)samples rateScalar:(Float64)rateScalar

Parameters

buffers
n
samples
rateScalar


rateScalar

Returns the rate scalar for the receiver's selected sound card.

The rate scalar is a high resolution (64 bit floating point) number that Core Audio determines from the actual sampling rate of a sound card. A rate scalar of precisely 1.0 means that the actual sampling rate of a sound card, as measured by the computer's clock, is precisely equal to the "nominal" sampling rate (i.e., the sampling rate of that you have selected).

A rate scalar that is not precisely 1.0 does not mean that the sound card's clock is wrong -- it could just as well be the computer's clock that is wrong. However, by comparing the rate scalar of two different sound cards, we can determine difference in clock frequencies between the two sound cards.

The rate scalar value is used to ensure that on a long time average, a playthrough of buffers from one sound card does not progressively underrun or overrun an output sound card. In AFSoundcard, the rate scalar from the input sound card is passed to the -pushBuffers method when data is being pushed from an input soundcard to an output sound card. The value is used to adjust the varispeed Audio Unit in the output AFSoundcard.

- (Float64)rateScalar

Return Value

The rate scalar.



resamplingQuality

Returns the current resampling quality (see below for resampling rate).

The input AFSoundcard uses the AudioConverter routines in Core Audio to perform resampling. The resamplingQuality is a number between 0 and 4. The number corresponds respectively to the five AudioConverter qualities:


This method returns 0 for an input AFSoundcard, which uses the varispeed Audio Unit to perform resampling.

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

The data arrives from the sound card at the sampling rate (see below). The rate that buffers are sent to and taken from the delegate can resampled to a different rate. One reason to do this to ensure that the buffers work at a constant sampling rate even when some other process has changed the sound card's physical sampling rate.

If the resampling rate is set to 0.0, no resampling is done and the buffers are transferred at the sampling rate of the physical sound card.

With the output AFSoundcard, resampling is performed with the varispeed Audio Unit in Core Audio. With the input AFSoundcard, resampling is performed with the AudioConverter routines in Core Audio (see -resamplingQuality).

- (float)resamplingRate

Return Value

The current resampling rate (0.0 if no resampling).



samplingRate

Returns the current (hardware) sampling rate. The available sampling rates can be obtained from the current AFDevice (see -selectedDevice below).

- (float)samplingRate

Return Value

The current sound card sampling rate.



selectDevice:

Selects an AFDevice as the current device.

When an AFSoundcard is first initialized, the selected device is the default input or output device that is selected in the System Preferences Sound panel. You can get the NSArray of AFDevices with the -devices method.

- (AFDevice*)selectDevice:(AFDevice*)device

Parameters

device
Return Value

The selected AFDevice, or nil if the selection fails.



selectDeviceName:

Selects an AFDevice with the given name as the current device.

When an AFSoundcard is first initialized, the selected device is the default input or output device that is selected in the System Preferences Sound panel. The NSString name is a property of an AFDevice. You can get the NSArray of AFDevices with the -devices method.

- (AFDevice*)selectDeviceName:(NSString*)name

Parameters

name
Return Value

The selected AFDevice, or nil if the selection fails.



selectedDevice

Returns the current AFDevice that the receiver is connected to.

When an AFSoundcard is first initialized, the selected device is the default input or output device that is selected in the System Preferences Sound panel. The device can subsequently be changed with -selectDevice, -selectDeviceName or by selecting a menu item in an NSPopUpButton that is managed by -setManagedDeviceMenu.

- (AFDevice*)selectedDevice

Return Value

The current AFDevice.



setBufferLength:

Sets the buffer length.

- (void)setBufferLength:(int)length

Parameters

length


setChannelMask:

Sets the channel mask.

- (void)setChannelMask:(int)mask

Parameters

mask


setDelegate:

Sets receiver's delegate. The delegate should conform to the AFSoundcardDelegate protocol.

- (void)setDelegate:(id <AFSoundcardDelegate>)object

Parameters

object


setFormat:

Select the bit depth and number of channels of the physical device. The two values are part of the AFFormat structure.

Not all arbitrary bit depth/channels is available. To get an NSArray of all available formats, use the -formats call to the current AFDevice.

- (void)setFormat:(AFFormat*)format

Parameters

format


setManagedDeviceMenu:

Let the receiver manage the NSPopUpButton.

The receiver populates the menu of the PopUpButton with the device names that are available from Core Audio. When the user changes the device selection, the receiver sets up the proper Core Audio callbacks. When an external sound card is added or removed, the managed NSPopUpButton's menu is automatically updated. If the receiver's selected device is removed, the receiver changes to using the default device (as set in the System Preferences Sound panel) and update the NSPopUpButton's selection to reflect the change.

Pass nil as the argument if you no longer wish to let the receiver manage a previous popup button.

- (void)setManagedDeviceMenu:(NSPopUpButton*)popup

Parameters

popup


setManagedFormatMenu:

Let the receiver manage the NSPopUpButton.

The receiver populates and updates the menu of the PopUpButton with the formats (bit depth and number of channels) of the currently selected sound card. When the user changes the format selection of the popup button, the receiver sends the change to Core Audio. If another process changes the format of the sound card that is currently selected, the receiver automatically reselects the menu item.

Pass nil as the argument if you no longer wish to let the receiver manage a previous popup button.

- (void)setManagedFormatMenu:(NSPopUpButton*)popup

Parameters

popup


setManagedSamplingRateMenu:

Let the receiver manage the NSPopUpButton.

The receiver populates and updates the menu of the PopUpButton with the sampling rates of the currently selected sound card. When the user changes the sampling rate selection of the popup button, the receiver sends the change to Core Audio. If another process changes the sampling rate of the sound card that is currently selected, the receiver automatically reselects the menu item.

Pass nil as the argument if you no longer wish to let the receiver manage a previous popup button.

- (void)setManagedSamplingRateMenu:(NSPopUpButton*)popup

Parameters

popup


setManagedSourceMenu:

Let the receiver manage the NSPopUpButton.

The receiver populates and updates the menu of the PopUpButton with the source names of the currently selected sound card. When the user changes the source selection of the popup button, the receiver sends the change to Core Audio. If another process changes the source of the sound card that is currently selected, the receiver automatically reselects the menu item.

Pass nil as the argument if you no longer wish to let the receiver manage a previous popup button.

- (void)setManagedSourceMenu:(NSPopUpButton*)popup

Parameters

popup


setManagedVolumeSlider:channel:

Let the receiver manage the volume control NSSlider the requested channel.

A channel number of 0 is the Master volume control. Channel 1 is the first channel of the sound card, channel 2 is the second channel of the sound card, etc. Channel 1 is usually the left channel of a stereo sound card, and the channel 2 is the right channel of a stereo sound card.

The receiver sets the slider to the scalar volume of the channel of the currently selected sound card. When the user changes the slider, the receiver sends the change to Core Audio. If another process changes the volume of the sound card that is currently selected, the receiver automatically changes the slider's value.

The minValue of the slider has to be between 0 and 1.0, and the maxValue of the slider has to be between the minValue and 1.0.

The slider becomes disabled (grayed out in the UI) if the particular channel's volume is not controllable.

Pass nil as the argument if you no longer wish to let the receiver manage a previous popup button.

- (void)setManagedVolumeSlider:(NSSlider*)slider channel:(int)channel

Parameters

slider
channel



setResamplingQuality:

Sets the resampling quality of an input AFSoundcard. The default number is 3. This method has no effect on an output AFSoundcard.

- (void)setResamplingQuality:(int)resamplingQuality

Parameters

resamplingQuality


setResamplingRate:

Sets the resampling rate. (see also -setResamplingQuality).

- (void)setResamplingRate:(float)resamplingRate

Parameters

resamplingRate


setSamplingRate:

Sets the physical sampling rate of the sound card. The value has to one of the numbers from the NSArray -samplingRates of the AFDevice.

- (void)setSamplingRate:(float)samplingRate

Parameters

samplingRate


setSource:

Select the source. A list of sources can be obtained as an NSMenu from the current AFDevice.

- (void)setSource:(NSString*)source

Parameters

source


setVolume:channel:

Set the volume control of a particular channel of the selected sound card with a scalar value between 0 and 1.0.

Channel 0 is a master channel of the sound card, channel 1 is the first channel, channel 2 is the second channel, etc.

- (Boolean)setVolume:(float)scalar channel:(int)channel

Parameters

scalar
channel
Return Value

Returns true if successful. Returns false if there is no volume control for the channel.



source

Returns the name of the currently selected source, or nil if there is no source.

- (NSString*)source

Return Value

An NSString name of the source, or nil.



start

Start sampling.

With an input AFSoundcard, the delegate should start receiving the -inputReceivedFromSoundcard calls. With an output AFSoundcard, the delegate should start receiving the -outputNeededBySoundcard calls.

- (Boolean)start

Return Value

True if the start command is successful.



stop

Stop sampling.

With an input AFSoundcard, the delegate should stop receiving the -inputReceivedFromSoundcard calls. With an output AFSoundcard, the delegate should stop receiving the -outputNeededBySoundcard calls.

- (void)stop



volumeForChannel:

Returns a scalar volume control value between 0 and 1.0 of a particular channel of the selected sound card.

Channel 0 is a master channel of the sound card, channel 1 is the first channel, channel 2 is the second channel, etc.

- (float)volumeForChannel:(int)channel

Parameters

channel
Return Value

A float value between 0 and 1.0. Returns 0 if there is no volume control for the channel.

• Audio Library
• Programming Guide
• AFManager
• AFSoundcard
• AFSoundfile
• AFSoundcardDelegate
• AFDevice
• AFFormat
• AFList