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.

IToiAudioOutputService

IToiAudioOutputService 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 IToiAudioOutputService::TAudioConnectionDescriptor. IToiAudioOutputService::GetConnections returns a list of all available connections. IToiAudioOutputService also provides methods to control volume and mute state for connections that support them (this has replaced the previous IToiVolumeService).

For example on the VIP2060, KDDI HD box we have:

Outputs

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

Inputs

buffer[0]. This is the special PCM decoder owned by IToiAudioOverlayService for sound effects.
decoder[0]. This is the main audio decoder owned by the streamer to usually play transport stream audio.
I2S[0] This is the I2S input connected to the Onyx chip and the analog input. There is a hardware limitation which causes that these two cannot be active at the same time. There is a hardware switch between them, to control the switch the user must mute/unmute I2S[0]. When I2S[0] is umuted Onyx is active and when I2S[0] is muted analog input is activated instead.

IToiAudioOutputObserver

IToiAudioOutputObserver provides an interface that should be implemented by interested applications to get events when the volume of a connection, the mute state of connection and the HDMI sink connection of hdmi[0] changes. IToiAudioOutputObserver also tells interested applications if the audio format mapping configuration of the STB has changed.

IToiAudioOutputConfiguration

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

IToiAudioOutputConfiguration::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; TAudioFormatMapping::OutputFormatOptionList.

TAudioFormatMapping::ActiveOutputFormat is the current selected output format for the given TAudioFormatMapping::Inputformat (in the call to IToiAudioOutputConfiguration::GetFormatMapping).
TAudioFormatMapping::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.

IToiAudioOutputConfiguration also provides you with additional information about HDMI sinks that may be connected to hdmi[0]. IToiAudioOutputConfiguration::GetHdmiSinkFormatList gives you a list of audio formats that a connected HDMI sink claims to support through its EDID. This information can be used to select the appropriate audio format mapping for hdmi[0].

IToiAudioOutputConfigurationSession

IToiAudioOutputConfigurationSession inherits all the capabilities of IToiAudioOutputConfiguration. 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 IToiAudioOutputConfigurationSession::Apply to actually apply the changes or IToiAudioOutputConfigurationSession::Revert to cancel all the changes. One of these two must be called to close the transaction. No other transaction can be started until the currently active transaction is closed.

IToiAudioOutputConfigurationSession::SetFormatMapping can be used to, for some output connection and input format, set the output format.

IToiAudioOutputConfigurationSession::GetFormatMapping provides the current format setting inside the transaction not the one actually set for the STB which is provided by IToiAudioOutputConfiguration::GetFormatMapping.

Once the session is closed and if the format mapping has changed observers will be called with IToiAudioOutputObserver::OnConfigurationChanged. Also any call to IToiAudioOutputConfiguration 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 an 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.