Audio Output Service

The Audio Output Service provides functionality to get information about the set-top box hardware audio output devices, to change the audio format mappings and to control the volume.

Configuration changes are stored in the STB flash memory.

ToiAudioOutputService

The 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 ToiAudioConnectionDescriptor. ToiAudioOutputService.getConnections() returns a list of all available connections.

For example, a set-top box could have these inputs and outputs:

Inputs

• One connection of type AUDIO_CONNECTION_TYPE_BUFFER, which is the memory buffer used for overlay of sound effects (if supported).
• One connection of type AUDIO_CONNECTION_TYPE_DECODER, which is the main audio decoder owned by the streamer to usually play transport stream audio.

Outputs

• One connection of type AUDIO_CONNECTION_TYPE_HDMI.
• One connection of type AUDIO_CONNECTION_TYPE_SPDIF.
• One connection of type AUDIO_CONNECTION_TYPE_ANALOG.

The ToiAudioOutputService also provides methods to control volume and mute state for connections that support these options.

ToiAudioOutputService Event Subscriptions

Event subscriptions are used by the applications to receive events when the volume of a connection, or the mute state of a connection changes. The events also tell interested applications if the audio format mapping configuration of the STB has changed. Event subscriptions are done using the addEventListener() function.

ToiAudioOutputConfiguration

A ToiAudioOutputConfiguration provides an interface to get and set the current audio format mappings used by 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.

The activeOutputFormat is the current selected output format for the given inputFormat (in the call to ToiAudioOutputConfiguration.getFormatMapping()).

The 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

A ToiAudioOutputConfigurationSession inherits all the capabilities 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 within the transaction, and when ready you 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 set the output format for each input format (MPEG2, AC3, AAC, etc) on specified output connection (HDMI, SPDIF or analog).

ToiAudioOutputConfigurationSession.getFormatMapping() provides the current format setting inside the transaction, which may be different with the one actually set for the STB (provided by ToiAudioOutputConfiguration.getFormatMapping()).

The event ToiAudioOutputConfigurationChangedEvent will be triggered once changes are applied during a session. Also new configuration can be got by calling methods of interface ToiAudioOutputConfiguration.

The NULL output format explained

The AUDIO_FORMAT_NULL is 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.

Also, on some box models, some output format combinations are not valid due to hardware limitations. The NULL format can be used as an intermediate step to break deadlocks/limitations.

For example, suppose on one kind of box model, setting the HDMI output mapping as AC3->AC3 and the SPDIF output mapping as AC3->PCM_2CH is not valid combination. Now 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). You should firstly change 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.

Note that in this case, the NULL output format should only be used inside a transaction to "unlock" available output formats. If you actively choose output format as NULL and commit the transaction (apply()) you will get an undefined behavior, and may consequently get audio. If you want to see all possible input/output format combinations for all outputs then you can use the ToiAudioOutputConfigurationSession.resetFormatMapping() function, that is mapping all input formats to NULL on all outputs.

See also: TOI Audio Output Service Interface.