The UMSAudioDevice object is a base class. Specific audio device implementations inherit their interface from this class. Ultimedia Services player objects and applications achieve device independence by accessing the audio device through the methods of the base class (without needing to know the base class object implementations).
A metaclass is provided with a method to construct a specific audio device based on an audio alias and data specified by you in the configuration file. This allows an application to be ported to a new audio device by altering the data under the audio alias in the configuration file. This is the preferred construction technique for applications. Alternatively, a specific audio device object can be constructed by the standard ObjectNameNew method.
To learn more about the UMSAudioDevice object, see:
For introductory information, see Audio Device Objects.
To avoid name collision on defines, integer values have been captured as enumeration lists. The set of valid values from an enumerated list can vary with the application. The detailed method descriptions describe the valid or possible values for the specific use. The enumerated lists defined for this object follow.
enum ReturnCode {
Success,
Failure,
InvalidParam,
DeviceNotAvail,
NoDevice,
IncompatibleSettings,
NotOpen,
NotReady,
SettingsChanged,
MemoryError,
UnderRun,
OverRun,
DeviceError,
Interrupted,
NotSupported,
Preempted
};
enum State {
Notinitializationd,
Stopped,
Playing,
Recording,
Paused_Play,
Paused_Record
};
UMSAudioDevice defines the following constant:
#define UMSAudioDevice_BlockingIO 0x00000001
This method closes the previously opened track.
This method is only supported if the object is a shared audio device and the share mode is preempt_return. The method registers a signal with the shared server. If the device is preempted by another process, the application that enables notification waits for the registered signal before attempting to perform I/O methods. This saves the application from having to poll the device.
This method is only supported if the object is a shared audio device. The method clears the notification signal if it exists in the server.
The current format setting is returned as a string. If this request is issued after a set, but before an initialization method call, the value that are applied at initialization is returned.
| out string audio_format | The string value representing the current audio setting. |
The current setting of bits_per_sample is returned. If this request is issued after a set, but before an initialization method call, the value that are applied at initialization is returned.
The current sample rate in samples per second is returned. If this request is issued after a set, but before an initialization method call, the value that are applied at initialization is returned.
This method returns the current state of the audio device.
| inout State state | The state is a value from the State enumeration list which can have values of Notinitializationd, Stopped, Playing, Recording, Paused_Play, or Paused_Record. |
This method initializes the audio device's audio parameters. This includes sample rate, bits per sample, connectors, audio format, number of channels, byte order, and number format. The current setting for these parameters are applied when the initialization method is called. The supported method of altering these parameters is to stop, play, or record; set the parameters; and initialize prior to starting a play or record. Results of attempting to alter parameters during play or record are indeterminate.
This method opens an available track on the specified device. If an available track is not found then the method returns NotAvail. The modes currently defined are PLAY and RECORD. A UMSAudioDevice object permits only one open track even though the underlying real device can support multiple open tracks, concurrent plays, and records. Concurrent use of tracks within an application requires the use of multiple UMSAudioDevices.
This method pauses the audio device. This is done as quickly as possible within the latency of the particular device. Play or record can be continued by the resume method.
This method attempts to read the specified number of audio samples from the audio device. The actual number of samples read is returned in the samples_read parameter. This method sample bounds the amount of data read so that incomplete samples cannot be read. The read can be terminated if opened without the UMSAudioDevice_BlockingIO flag, in which case the ReturnCode is set to Interrupted. The read can also terminate if the device is being shared and is preempted, in which case the ReturnCode is Preempted.
This method resumes playing or recording of audio data when it has been paused.
This method sets the audio format to be used for play or record. Each specific audio device implementation advertises the formats that it supports as properties under its formats_alias in the configuration file. All devices are required to support PCM, A_LAW and MU_LAW. The setting takes effect at the next initialization.
| in string fmt | A string specifying the desired audio format. |
This method sets the number of audio channels for play or record. Mono is specified with a value of 1 and stereo is specified with a value of 2. The setting takes effect on the next initialization.
| in long channels | The number of channels for play or record. A value of 1 specifies mono, and a value of 2 specifies stereo. |
This method sets the number of bits per sample. The setting takes effect at the next initialization.
| in long bits | The current sample rate in samples per second. If this request is issued after a set, but before an initialization method call, the value that are applied at initialization is returned. |
This method sets the sample rate on the audio device. The rate parameter is the desired sample rate and the set_rate parameter is the actual sample rate that was set. Sample rates are set to the closest sample rate supported by the device. The setting takes affect at the next initialization.
| in long rate | The requested sample rate in samples per second. |
| inout long set_rate | The sample rate chosen by the device in response to the request. |
This method starts the processing of data in the audio device. For example, this method starts playing data that has been or are written to the device, or it starts recording.
This method stops the audio device. The difference between stop and pause is that pause preserves buffered data and can be resumed, while stop terminates play or record and discards buffered data.
This method attempts to write the specified number of samples to the audio device. The actual number of bytes written is returned in the samples_written parameter. This method sample bounds the amount of data written so that incomplete samples cannot be written. The write can be terminated if opened without the UMSAudioDevice_BlockingIO flag, in which case the ReturnCode is set to Interrupted. The write can also terminate if the device is being shared and is preempted, in which case the ReturnCode is preempted.
The current setting of number_of_channels is returned. If this request is issued after a set, but before an initialization method call, the value that are applied at initialization is returned.
| inout long channels | The value of the current setting for number of channels. |
This method sets the time format that are used by the object. This effects the time values that are used in the methods read_buff_size, write_buff_size, read_buff_remain, write_buff_remain, read_buff_used, write_buff_used, and get_position. The value takes effect immediately. The time format can have values of UMSAudioTime::Bytes, UMSAudioTime::Samples and UMSAudioTime::Msecs.
| in UMSAudioTypes::TimeFormat time_format | The specified time format to use. |
This method returns the current time format being used by the object.
| inout UMSAudioTypes::TimeFormat time_format | The current time format to use. |
This method sets the byte order for the data played or captured. Values of MSB and LSB are supported. The setting takes effect at the next initialization.
| in string byte_order | The desired byte order as a string value of MSB or LSB. |
This method returns the byte order setting as a string value. If this request is issued after a set, but before an initialization method call, the value that are applied at initialization is returned.
| out string byte_order | The byte order setting as a string value of MSB or LSB. |
This method sets the number format for the data played or captured. Values of SIGNED, UNSIGNED, and TWOS_COMPLEMENT can be supported by the specific object. The setting takes effect on the next initialization.
| in string number_format | The desired number format as a string value. |
This method returns the number format setting as a string value. If this request is issued after a set, but before an initialization method call, the value that are applied at initialization is returned.
| out string number_format | The number format setting as a string value. |
This method enables a given input connector and sets the left and right gain on the input if the device supports individual gain. This method can be called multiple times to enable several inputs. If the device does not support multiple inputs then the last valid input specified takes effect on the next initialization. The actual gain value used for each channel are returned in the associated parameter. The settings take effect on the next initialization. Specific devices advertise their input and output connection capability in the configuration file. The valid range of left_gain and right_gain is from 0 to 100. Zero indicating maintaining of current gain value; 100 meaning increasing to maximum gain value.
This method disables a previously enabled input. The settings take effect on the next initialization.
| in string input | The input connection to be disabled. |
This method returns a Boolean into the enabled parameter which states whether the input is currently enabled.
| in string input | The input connection being queried. |
| inout boolean enabled | returned as True if the input is enabled |
This method enables a given output connector and sets the left and right gain on the output if the device supports individual gain. This method can be called multiple times to enable several outputs. If the device does not support multiple inputs then the last valid output specified takes effect on the next initialization. The actual gain value used for each channel is returned in the associated parameter. The settings take effect on the next initialization. Specific devices advertise their input and output connection capability in the configuration file. (Note that left_gain and right_gain are not supported in this release.)
This method disables a previously enabled output. The settings take effect on the next initialization.
| in string output | The output connection to be disabled. |
This method returns a Boolean into the enabled parameter which states whether the output is currently enabled or not.
| in string output | The output connection being queried. |
| inout boolean enabled | Returned as True if the output is enabled. |
This method enables or disables monitoring during a record. This setting takes effect immediately.
| in boolean monitor | True to enable monitoring. |
This method returns the current state of the monitoring flag in the monitor parameter. TRUE means monitoring is enabled, and FALSE means monitoring is disabled.
| inout boolean monitor | True if monitoring is enabled. |
This method changes the volume. This setting takes effect immediately.
| in long volume | The desired volume setting. Valid range is 0 through 100. |
This method returns the current volume level in the parameter volume.
| inout long volume | The current value for volume is returned. The volume range is 0 through 100. |
This method sets the balance. Valid values are -100 to 100. -100 is full left and 100 is full right. 0 is balanced in the center. The new setting takes effect immediately.
| in long balance | The desired balance value. |
This method returns the current balance setting in the parameter balance.
| inout long balance | The current balance value. |
This method returns the size of the read buffer for this device. The size is returned in units of the current time format: bytes, samples or milliseconds. Underrun and Overrun conditions are returned as ReturnCodes and the size of the read buffer is returned in the buff_size parameter. Knowledge of the read buffer size can help an application determine how frequently reads must be performed to prevent overruns.
| inout long buff_size | The size of the read buffer. |
This method returns the size of the write buffer for this device. The size is returned in units of the current time format. Underrun and Overrun conditions are returned as ReturnCodes, and the size of the write buffer is returned in the buff_size parameter. Knowledge of the write buffer size can help an application determine how frequently writes must be performed to prevent underruns.
| inout long buff_size | The size of the write buffer. |
This method returns the amount of space available in the read buffer. The size is returned in units of the current time format. Underrun and Overrun conditions are returned as ReturnCodes and the amount of space remaining in the read buffer are returned in the remain parameter. This allows an application to observe how much data space remains.
| inout long remain | The amount of buffer space that is unused is returned in units of the current time format. |
This method returns the amount of space available in the write buffer. The size is returned in units of the current time format. Underrun and Overrun conditions are returned as ReturnCodes and the amount of space remaining in the write buffer is returned in the remain parameter. This allows an application to observe how much data can be written to the device without incurring a block.
This method returns the amount of data in the read buffer. The amount of data in the buffer is returned in units of the current time format. Underrun and Overrun conditions are returned as ReturnCodes, and the amount of data in the read buffer is returned in the used parameter.
| inout long used | The amount of data in the read buffer in units of the current time format. |
This method returns the amount of data in the write buffer. The amount of data in the buffer is returned in units of the current time format. Underrun and Overrun conditions are returned as ReturnCodes, and the amount of data in the write buffer are returned in the used parameter. This is similar to the write_buff_remain method but queries the buffer in terms of how much data remains to play.
| inout long used | The amount of data in the write buffer in units of the current time format. |
This method returns the amount of data processed since the last start. The amount of data processed is returned in units of the current time format. Underrun and Overrun conditions are returned as ReturnCodes and the amount of data processed are returned in the position parameter.
| inout long position | The elapsed audio time since the last play returned in units of the current time format. |
This method forces the device to play the data remaining in the devices buffer. If there is not enough data in the device play buffer for the device to play, then this method pads the data in the play buffer so that it can be played. If the block parameter is TRUE, the method blocks until all of the remaining data has been played. This block is interruptible by a signal. It can also be preempted if the device is being shared.
| in boolean block | Specifies whether the application desires to block on this method until play is complete. |
This method saves the current settings of the device into a sequence and returns the sequence to the caller. This sequence can latter be used with the restore_state method to restore all of the settings to the device. The settings are returned in the sequence pointed to by the state_buff parameter. The caller is responsible for freeing the memory contained in the state_buff sequence. This is useful when constructing a shared device object from the device. The device state can be saved during preemption.
| out UMSAudioTypes::Buffer state_buff | A sequence is returned that contains the data representing the device state. |
This method restores all of the audio device's settings that were previously saved using the save_state method.
| in UMSAudioTypes::Buffer state_buff | A sequence is supplied that contains the data representing the device state to be restored. |
This method presents device specific capabilities shared for all invocations of a device. If you enable master setting mode, you share in this configuration of the device. Each device can enforce rules based on current state and as to when the master_setting mode can be entered or exited. Some devices cannot support master setting, in which case a NotSupported ReturnCode is returned. Some methods on a device cannot be available on a device if they conflict with the master_setting mode; for example, the selection of input and output connections established via the master setting mode.
Devices supporting this method attempts to disable the master setting mode. If the method is not supported by the device a NotSupported value is returned. If the device cannot be acquired with master setting disabled, a value of Failure is returned.
This method returns a string which contains the full path of the device that this object is currently using, such as /dev/acpa0.
| out string device_pathname | A string is returned containing the device pathname. |
This method returns the path to an executable that, when executed, provides an interface that you can use to adjust the audio device's master settings. This is most likely a graphical user interface to the device specific master settings available for the device. This executable is advertised in the configuration file and therefore can be replaced by any executable desired.
| out string exec_pathname | The pathname to the executable registered in the configuration file for the specific device is returned. |
This method provides a pragmatic interface to dynamically alter the shared mode for play. The default shared mode for play is statically specified for the audio alias in the configuration file. The only valid play share mode in this release is mix. The share mode has no effect unless a shared device is being used (requested in the configuration file for the alias). NotSupported is returned if the device is not a shared device.
| in string play_share_mode | The requested play_share_mode. |
This method provides a pragmatic interface to dynamically alter the shared mode for record. The default shared mode for record is statically specified for the audio alias in the configuration file. The valid record share modes in this release are preempt_block and preempt_return. A pre-empted read returns with a ReturnCode value of Preempted if the the mode is preempt_return versus blocking for mode preempt_block when the client is preempted waiting for the device. The shared mode has no effect unless a shared device is being used (requested in the configuration file for the alias). NotSupported is returned if the device is not a shared device.
| in string record_share_mode | The requested record_share_mode. |
This method returns the current play_share_mode. NotSupported is returned if the device is not a shared device.
| out string play_share_mode | A string is returned that contains the current play_share_mode. NotSupported is returned if the device is not a shared device. |
This method returns the current record_share_mode. NotSupported is returned if the device is not a shared device.
| out string record_share_mode | A string is returned that contains the current record_share_mode. NotSupported is returned if the device is not a shared device. |
This methods is only supported on devices that allow a variable DMA buffer size. The size of the DMA buffer must be 2048 or smaller. On other devices, the NotSupported code is returned. This method affects the audio latency by varying the amount of data that the device transfers in one DMA operation. For example, if the DMA buffer size is 2048 bytes and the application requests a read of 128 bytes, the device does not return control on a blocking input/output until 2048 bytes are actually read. If, in this example, the data rate is 8000 samples/sec, 8 bit samples, mono, there is approximately a 1/4 second delay every read. In this case, the method is used to lower this latency to an imperceptible amount (the tradeoff is a larger load on the processor). A separate DMA buffer exists for record and play, so you can use this method on any supported audio device object. The object iteself knows whether it is a record object or a play object. Any change takes effect on the next _initialize call.
| in long bytes | The desired DMA buffer size in bytes. This parameter is device dependent. |
| out long bytes_ret | The actual size that the DMA buffer is set to on the next inititalize. |
This method is only supported on devices that allow a variable DMA buffer size. On other devices, the NotSupported code is returned. This method returns the current value of the DMA buffer size for the given object on supported devices. If the object was opened for record, the record transfer size is returned. Otherwise, the play transfer size is returned.
| out long bytes | The amount of bytes to which the buffer is set. This paramter is device dependent. |
This method is only supported on devices that allow a variable DMA buffer size. On other devices, the NotSupported code is returned. This method affects how much data is buffered for reads and writes in the kernel. This method helps to alleviate device overruns due to system performance when reading by allowing the buffer to fill; it also helps to alleviate device underruns due to system performace when writing by causing the buffer to drain. The size is given in the current time format, which is either Msecs, Bytes, or Samples. Separate buffers exist for read (record) and write (play) operations and there buffers can be different sizes. The call takes effect immediately, so you must issue it after the initialize. The device resets these values to the default whenever a new intitialize is performed, so the application must reissue the call whenever it issues an intitialize.
| in long buffer size | The size of the audio buffer in the current time format. |
| out long size_ret | The actual size to which the audio buffer was set. |
For introductory information, see Audio Device Objects.