UMSMix Object

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

UMSMix Object

The UMSMix object is a base class with most methods implemented. Specific mix implementations should inherit from the Mix base class. The standard Mix subclass provided is the UMSMixPCM16 object class. A UMSMixPCM16 object uses the standard interface defined in UMSMix.idl to take any two audio streams as input and output a 16-bit linear PCM stream in twos complement, MSB format. If the two streams are monophonic, the output is mono. If either stream or both are stereophonic, the output is stereo.

The two input streams to the Mix object can be any supported format (ADPCM is not supported at this time) and any rate. The highest rate is used in the output stream.

The UMSMix object is meant to serve as a template for specific mixer objects and should not be used for mixing itself. There are no mixing algorithms contained in the base class. UMS provides the UMSMixPCM16 object to perform the actual mixing. New applications of mixing can be accomplished by inheriting from the UMSMix base class.

To learn more about the UMSMix object, see:

For introductory information, see Audio Mix Objects.

Enumeration Lists

To avoid name collisions, integer values have been defined as enumeration lists. The enumeration lists defined in the UMSMix base class are:

enum ReturnCode {
   Success, 
   Failure, 
   InvalidArgument, 
   StorageAllocationFailure,
   UnsupportedFormat, 
   NotInitialized, 
   SettingsChanged,
   NeedSettings, 
   DontFilter, 
   InvalidSampleRate
    };

enum AudioFormat {
   UNSET, 
   PCM16, 
   PCM8, 
   ALAW, 
   MULAW 
   };

enum State {
   Uninitialized, 
   Initialized, 
   Changed
   };

enum ByteOrder {
   MSB, 
   LSB
   };

Note: Note that only the ReturnCode type is essential to you. The others are most likely to be used by a Mix subclass.

Method Descriptions

ReturnCode calculate_output_size (in long in_stream1_size, in long in_stream2_size, inout long output_size)

Description

This method outputs the minimum size that an output buffer needs to be to hold the data created by mixing the two input streams. The initialize method needs to be called with the proper settings before this method can be invoked. The method returns a NotInitialized value if the initialize method was not called. If any key settings such as sample rate, audio format, bits-per-sample, or number of channels are changed prior to calling initialize again, this method fails with a SettingsChanged return code.

Arguments

in long in_stream1_size	Size in bytes of the first input stream.
in long in_stream2_size	Size in bytes of the second input stream.
inout long output_size	Return value of the minimum output buffer size in bytes.

Return Values

Success

NotInitialized

SettingsChanged

InvalidArgument

Failure

ReturnCode set_input_format (in long stream_number, in string format)

Description

This method sets the audio format of an input stream. The format is a string value. The case does not matter. The current supported values for the format are PCM, A_LAW, and MU_LAW.

Arguments

in long stream_number	Input stream 1 or 2. Each stream has attributes.
in string format	PCM, MU_LAW, or A_LAW. Case-insensitive audio format.

Return Values

Success

UnsupportedFormat

ReturnCode get_input_format (in long stream_number, out string format)

Description

Given the stream number, this method returns the audio format as a string.

Arguments

in long stream_number	Input stream 1 or 2. Each stream has attributes.
out string format	PCM, MU_LAW, or A_LAW. Case insensitive audio format.

Return Values

Success

InvalidArgument

ReturnCode set_input_bits_per_sample (in long stream_number, in long bps)

Description

This method sets the bits-per-sample value for a given steam. The only legal values for bits-per-sample are 8 and 16.

Arguments

in long stream_number	Input stream 1 or 2. Each stream has attributes.
in long bps	The bits-per-sample value.

Return Values

Success

InvalidArgument

ReturnCode get_input_bits_per_sample (in long stream_number, inout long bps)

Description

This method returns the bits-per-sample value given a stream number.

Arguments

in long stream_number	Input stream 1 or 2. Each stream has attributes.
inout long bps	The bits-per-sample value.

Return Values

Success

InvalidArgument

ReturnCode set_input_samples_per_second (in long stream_number, in long sps)

Description

This method sets the samples per second value for a given stream. The Mix object accepts any positive, nonzero value for this argument. The audio device or filter has to catch and adjust values that are not exact rates.

Arguments

in long stream_number	Input stream 1 or 2. Each stream has attributes.
in long sps	The samples per second value.

Return Values

Success

InvalidArgument

ReturnCode get_input_samples_per_second (in long stream_number, inout long sps)

Description

This method returns the samples per second value for a given stream.

Arguments

in long stream_number	Input stream 1 or 2. Each stream has attributes.
inout long sps	The bits-per-sample value.

Return Values

Success

InvalidArgument

ReturnCode set_input_number_of_channels (in long stream_number, in long chan)

Description

This method sets the number of channels used in a given stream. If either one or both of the streams is stereo, the result of the mix is stereo. Legal values for the channel argument are 1 and 2.

Arguments

in long stream_number	Input stream 1 or 2. Each stream has attributes.
in long chan	The number of channels used. Must be 1 or 2.

Return Values

Success

InvalidArgument

ReturnCode get_input_number_of_channels (in long stream_number, inout long chan)

Description

This method returns the number of channels set for a given stream number.

Arguments

in long stream_number	Input stream 1 or 2. Each stream has attributes.
inout long chan	Value for the number of channels.

Return Values

Success

InvalidArgument

ReturnCode mixer (in sequence<octet> input_stream1, in sequence<octet> input_stream2, inout sequence<octet> output_stream)

Description

This method mixes the two audio streams together to form an output stream. The mix object must have been initialized before the call to this method is made. If any key settings have been changed, the SettingsChanged code is returned and the mix is not done. Any filtering of the data required to do the mix is done inside this call.

Arguments

in sequence<octet> input_stream1	Sequence containing the length of audio stream 1 and the data buffer.
in sequence<octet> input_stream2	Sequence containing the length of audio stream 2 and the data buffer.
inout sequence<octet> output_stream	Sequence containing a data buffer and a maximum length. The results of the mix are put into the buffer. The number of elements is in the _length portion of the sequence.

Return Values

Success

NonInitialized

SettingsChanged

Failure

ReturnCode set_input_volume (in long stream_number, in long volume)

Description

This method sets the volume for a given stream. The volume can be set at any time and an initialize does not have to be done for the volume change to take effect. Volume can be set between mixer calls. Volume is a value between 1 and 100.

Arguments

in long stream_number	Input stream 1 or 2. Each stream has attributes.
in long volume	Value for the volume.

Return Values

Success

InvalidArgument

ReturnCode get_input_volume (in long stream_number, inout long volume)

Description

This method returns the volume for a given stream.

Arguments

in long stream_number	Input stream 1 or 2. Each stream has attributes.
inout long volume	Value for the volume.

Return Values

Success

InvalidArgument

ReturnCode initialize ()

Description

This method causes all of the settings to take effect. It also causes up to two chains of filters to be constructed depending on the format or rate of the input streams. The types of filters and the target output stream depends on the actual implementation of a UMSMix subclass. The supplied class, UMSMixPCM16 always produces an output stream of 16 bit linear PCM data at the highest rate given. Low-quality, high-performance filters are used to do the rate conversion. A subclass supplied by you can have different characteristics. This method must be called before calculating the output size and before mixing.

Return Values

Success

NeedSettings

InvalidSampleRate

ReturnCode set_input_byte_order (in long stream_number, in long byte_order)

Description

This method sets the byte order. Valid byte orders are 1 for MSB and 2 for LSB. The ByteOrder enumerated type can be used for convenience. For the UMSMixPCM16 supplied class, this call is only necessary if an input stream is already in PCM16 format, but has an LSB byte order. The mixer needs to know this so that the order can be reversed, since that particular mixer always outputs PCM16, MSB.

Arguments

in long stream_number	Input stream 1 or 2. Each stream has attributes.
in long byte_order	Byte order of the stream.

Return Values

Success

InvalidArgument

ReturnCode get_input_byte_order (in long stream_number, inout long byte_order)

Description

This method returns the byte order for a given stream.

Arguments

in long stream_number	Input stream 1 or 2. Each stream has attributes.
inout long byte_order	Byte order of a stream.

For introductory information, see Audio Mix Objects.