ARRIS Enterprises, Inc. Confidential Information

Audio Output Service

AudioOutput provides functionality to get information about existing audio outputs, to change the audio format mapping and volume control. Configuration changes are stored in flash.

ToiAudioOutputService

ToiAudioOutputService provides a way for applications to know what physical audio outputs the STB has. It also tells the user what different inputs are fed to the mixer. The characteristic of each connection is described by ToiAudioOutputServiceAudioConnectionDescriptor. ToiAudioOutputService::getConnections() returns a list of all available connections. ToiAudioOutputService also provides methods to control volume and mute state for connections that support them (this has replaced the previous ToiVolumeService).

For example, a box could have these outputs:

Outputs

analog[0]
spdif[0]
hdmi[0]

Inputs

buffer[0]. This is the memory buffer used for overlay of sound effects (if supported).
decoder[0]. This is the main audio decoder owned by the streamer to usually play transport stream audio.

ToiAudioOutputService Event Subscriptions

Event subscriptions are used by the applications to get events when the volume of a connection, and the mute state of connection changes. The events also tell interested applications if the audio format mapping configuration of the STB has changed. Event subscriptions are done using event listener registration

ToiAudioOutputConfiguration

ToiAudioOutputConfiguration provides an interface to read the current audio format mapping of the STB.

ToiAudioOutputConfiguration::getFormatMapping() tells the user that for some output connection and input format (fed to decoder[0]) what the current selected output format is and what other possible output formats that can be selected instead.

ToiAudioOutputConfigurationAudioFormatMapping::activeOutputFormat is the current selected output format for the given ToiAudioOutputConfigurationAudioFormatMapping::inputformat (in the call to ToiAudioOutputConfiguration::getFormatMapping()).
ToiAudioOutputConfigurationAudioFormatMapping::activeMixFlag tells you if the input format is decoded and mixed with the other inputs (buffer[0] and I2S[0] or I2S[1]) or if it's not mixed and is simply pass-through.

ToiAudioOutputConfigurationSession

ToiAudioOutputConfigurationSession inherits all the capabilities of ToiAudioOutputConfiguration. It also adds support for setting the STB's audio format mapping.

A session is a transaction object, it is possible to do several Get/Set calls in the transaction and when done the user must either call ToiAudioOutputConfigurationSession::apply() to actually apply the changes or ToiAudioOutputConfigurationSession::revert() to revert the configuration session to the state it had when it was created. The reverted configuration is not applied until ToiAudioOutputConfigurationSession::apply() is called. ToiAudioOutputConfigurationSession::releaseInstance() must be called to close the transaction. No other transaction can be started until the currently active transaction is closed.

ToiAudioOutputConfigurationSession::setFormatMapping() can be used to, for some output connection and input format, set the output format.

ToiAudioOutputConfigurationSession::getFormatMapping() provides the current format setting inside the transaction not the one actually set for the STB which is provided by ToiAudioOutputConfiguration::getFormatMapping().

Once the session is closed and if the format mapping has changed the event ToiAudioOutputConfigurationChangedEvent will be triggered. Also any call to ToiAudioOutputConfiguration will reflect any changes.

The NULL output format explained

Due to hardware limitations some output format combinations are not valid. The AUDIO_OUTPUT_NULL format can be used as an intermediate step to break deadlocks/limitations. Note that NULL should only be used inside a transaction to "unlock" available output formats. If you actively choose NULL and commit the transaction (apply()) you will get an undefined behavior, and may consequently get audio.

NULL is also used to describe that some format is not available on some output, for example if you don't have the AAC decoder license then AAC->NULL is the only available option on ANALOG.

Here is an example for the VIP19xx series where HDMI, SPDIF and ANALOG limit each other.

Suppose you have AC3 as an input format and all three outputs set to PCM_2CH (stereo) and want to set AC3 on HDMI and SPDIF (pass through). Setting the HDMI output mapping as AC3->AC3 will only be valid after changing the SPDIF from AC3->PCM_2CH to AC3->NULL. Then you are able to change HDMI from AC3->PCM to AC3->AC3 and finally you can set SPDIF to AC3->AC3.

If you want to see all possible input/output format combinations for all outputs then you can use the Reset function, that is mapping all input formats to NULL (*->NULL) on all outputs.