Audio Player/Recorder

Ultimedia Services Version 2 for AIX: Programmer's Guide and Reference

Audio Player/Recorder

Ultimedia Services provides a consistent set of methods for reading and writing audio files. It also provides a consistent interface that supports different formats. The audio player/recorder reads three types of audio files: WAVE RIFF, SND, and raw. Waveform audio files (WAVE files) and SND files contain attributes inside the files; raw audio files have no attributes. Example programs for using the audio player/recorder are in the /UMS/install directory.

To learn more about the audio player/recorder, see:

For introductory information, see Programming with Media Handler Objects.

Audio Player Methods

Audio player methods include player controls, media play and record controls, audio device controls, media attribute controls, and media monitoring controls.

Player Controls

Player controls include:

open	Opens the audio device.
close	Closes the audio device.
load	Loads a file.
info	Returns file name and device alias.
save	Saves a file.
get_state	Returns current player state.

Media Play and Record Controls

Media play and record controls include:

get_repeat	Returns the state of repeat setting.
get_time_format	Returns the current time format setting.
play	Plays media from current position to end of file.
play_to	Similar to play but stops at given position.
record	Records audio data using file access key of New, Append, Overwrite, or Insert.
pause	Pauses play or record.
resume	Resumes play or record.
seek	Seeks to location in file.
cue	Cues media for play.
stop	Stops play or record.
set_time_format	Sets the time format to milliseconds, bytes, or samples.
set_repeat	Enables or disables repeated play.

Audio Device Controls

Audio device controls include:

get_volume	Returns the current volume setting.
get_balance	Returns the current balance setting.
get_monitoring	Returns the state of monitor setting.
enable_input	Specifies an input connection to enable on the audio device.
enable_output	Specifies an output connection to enable on the audio device.
disable_input	Specifies an input connection to disable on the audio device.
input_enabled	Queries whether an input connection is enabled.
output_enabled	Queries whether an input connection is enabled.
get_audio_device_class	Returns the specific object class name of the audio device object.
get_audio_device_pathname	Returns the device pathname for the audio device.
get_audio_device_inout_aliases	Returns the configuration file aliases under which the audio device lists available input and output connections.
get_audio_device_master_exec	Returns a pathname of an executable that is to be used to control the audio device master settings.
enable_audio_master_settings	Sets the audio device to participate in the device settings established through the audio device master executable.
disable_audio_master_settings	Sets the audio device to not participate in the device setting established through the audio device master executable.
get_audio_master_settings	Queries whether master setting is enabled or disabled on the audio device.
set_volume	Sets volume.
set_balance	Sets balance.
set_monitoring	Enables or disables monitoring of recording.

Media Attribute Controls

Media attribute controls include:

set_bits_per_sample	Sets number of bits per sample.
set_number_of_channels	Sets mono or stereo.
set_audio_format_type	Sets audio data format. This must be a value supported by the audio device, such as PCM, A-law, or mu-law.
set_byte_order	Sets byte order to either most-significant byte first (MSB or Motorola) or least-significant byte first (LSB or Intel).
set_number_format	Sets byte format to unsigned, signed, or twos complement.
set_samples_second	Sets the sample rate.
get_current_position	Returns the current position in the media.
get_length	Returns the data length of the media.
get_file_format	Returns the file format.
get_bits_per_sample	Returns the bits per sample attribute.
get_number_format	Returns the attribute setting for the audio data number format as signed, unsigned, or twos complement.
get_audio_format_type	Returns the string value defining the format type of the audio data. Possible values include PCM, mu-law, and A-law.
get_number_of_channels	Returns the number of channels of audio data.
get_samples_second	Returns the samples per second attribute for the audio data.
get_byte_order	Returns the current setting for the data byte order (most-significant byte first or least-significant byte first).

Media Monitoring Controls

Media monitoring controls include:

get_event_mask	Returns the current event mask. The event mask specifies which events are to be returned.
set_cuepoint	Sets or clears one of 20 possible cuepoints.
set_position_advise	Sets position-advise event interval.
set_event_mask	Specifies which events to return.
get_event	Gets the next event.
event_pending	Determines whether event is available.
get_event_handle	Returns file descriptor for event communication.

File Formats

Supported file formats include WAVE, SND, and raw formats. The SND format supported is commonly referred to as the NeXT/Sun SND format. Both the WAVE and SND file formats contain headers prior to the audio data, which describe how the samples were encoded. Raw files do not contain this information. The encoding of the samples is typically preselected depending on the device used to record the samples. To play raw files, set the following attributes:

set_samples_second	Sets sampling rate.
set_bits_per_sample	Sets number of bits in each sample.
set_number_of_channels	Sets number of channels.
set_audio_format_type	Sets audio compression method used.
set_byte_order	Sets byte order of each sample.
set_number_format	Sets format of each byte.

The play/record capabilities for the WAV, SND, and raw formats are dependent on the specific audio device used by the player.

Playing an Audio File

To play an audio file, do the following:

Initialize the SOM environment.
Create an instance of an UMSAudioPlayer object.
Open (using the open method) an audio device using an alias that is defined in the configuration file. (The configuration object uses this alias to determine which device to open.)
Load the file (using the load method). If the file format is something other than raw, the attributes are set from the file header information.
Play the file (using the play method).
Wait for the PlayComplete event to signal when the audio player/recorder is finished playing the file.

Recording an Audio File

The audio player/recorder object uses the record method to create a new audio file or modify an existing audio files. The record method allows audio data to be inserted into either a blank file or a loaded file without destroying the old audio data, to overwrite the previous audio data to and from specific locations, or to be appended to the end of the file. When recording into an already loaded file, the original file is not changed until you save the file.

When recording new audio data into an already loaded file, set the RecordFlag parameter to UMSAudioPlayer_Insert and specify a from position. The from position tells the audio player/recorder where to begin inserting the recorded data (the from position is interpreted in the current time format (set_time_format)). The to position is not used with this option.

When recording new audio data over existing data, set the RecordFlag parameter to UMSAudioPlayer_Overwrite and specify both the to and the from positions. The audio player/recorder discards the old audio data between the positions and inserts the recorded data at the from position. (The new data can be larger or smaller than the original length between the to and from positions.) Both positions are interpreted in the current time format (set_time_format).

When recording data at the end of the file, set the RecordFlag parameter to UMSAudioPlayer_Append. Both the to and from positions are ignored in this case. When creating a new audio file, set the RecordFlag parameter to UMSAudioPlayer_New. The to and from locations are ignored because they are only used when modifying an existing file. You also have to specify how the samples are to be encoded by setting the audio attributes for sampling rate (set_samples_second), number of bits in each sample (set_bits_sample), number of channels (set_mode), audio compression method (set_audio_format), byte order of each sample (set_byte_order), and number format of each byte (set_number_format).

To record audio data, do the following:

Initialize the SOM environment.
Create an instance of an UMSAudioPlayer object.
Open (using the open method) an audio device using an alias which is defined in the configuration file. The configuration object uses this alias to determine which device to open.
Set up the file. If creating a new file, set audio attributes for encoding the audio samples. If recording into an existing file, load the file (using the load method).
Specify the source of the recorded data using enable_input or the audio master setting.
Issue the record method with the appropriate position information and RecordFlag value.
When finished recording, stop the audio player/recorder (using the stop method).
Save the file (using the save method). You must request that it be saved to avoid losing any changes.

Inputs and Outputs

The set of inputs and outputs available for a device is device-specific. An application can determine programmatically the set of inputs acceptable to the device in use. The get_audio_device_inout_aliases method returns the audio inputs alias and the audio outputs alias. UMSConfig objects can also be used to extract the acceptable inputs and outputs for the device.

Saving Audio Files

If you record data, you must save the file or lose your changes when you close the audio player/recorder.

When saving the file, you have several choices with the file_alias. The file_alias can be either a null string or one of the supported aliases listed in the configuration file. The supported aliases include SND, WAVE, and RAW. Using a null string lets the audio player/recorder choose the file_alias. If recording into a loaded file, the file_alias used to save the file is the same.

For introductory information, see Programming with Media Handler Objects.