Understanding audio ducking

When audio ducking is enabled, all audio streams adhere to an audio ducking policy that's defined in the audio policy configuration file.

Each audio stream on the system should have a corresponding audio type defined in the audio policy configuration file. Calls to snd_pcm_*_params() with an audio type that doesn't match a defined audio type fail with EINVAL. If you call snd_pcm_*_params() and do not provide an audio type, then the default type is assigned. The first audio type that's defined at the top of the file has the highest priority and the last audio type defined in the file has the lowest priority. You can also configure audio types that have the same priority.

If multiple audio streams play concurrently, the higher-priority audio type listed in the audio policy configuration file applies ducking, which lowers the volume of the lower priority audio type. For example, if you receive a voice call while music is playing and the audio type of the call has a higher priority than the music audio type, the music is ducked so that the voice call is heard more clearly. The voice call is ducking the music and the music is ducked.

If audio streams are in the same PCM link group, audio concurrency management policies treat them as a single audio stream. Ducking and other policies are not applied between members of the same PCM link group.

Using audio ducking

To enable ducking, you create an audio policy configuration file that follows the rules defined in the “Syntax of the audio policy configuration file” section in this chapter.

Note: Ducking is not available if you disable the software mixer (by specifying disable_sw_mixer option when you run io-audio). For more information, see the disable_sw_mixer option in the entry for io_audio in the Utilities Reference.

To enable ducking, you specify the location of audio policy configuration file using the policy_conf key in the [AUDIOMGMT] section of the audio configuration file.

For more information about the audio configuration file, see “Audio configuration file” in the entry for io_audio in the Utilities Reference.

Manually enabling ducking using APIs

Audio concurrency management evaluates ducking whenever an audio stream transitions into or out of the RUNNING state. However, if the stream is in the PREPARED state (call snd_pcm_*_prepare()), you can use the snd_pcm_channel_audio_ducking() function to make audio concurrency management apply ducking polices to an audio stream as if it was RUNNING, regardless of its current state.

You can call snd_pcm_channel_audio_ducking() to manually duck an audio stream only after a transition to the PREPARED state, but you can call it to cancel manual ducking at any time.

Manual ducking remains active until you use snd_pcm_channel_audio_ducking() to cancel it or reset the parameters using snd_pcm_plugin_params().

Ducking and AFMs

Audio ducking works differently for AFMs depending on the configuration:

If the audio configuration file routes the AFM playback audio through the main (media) path in the PCM software mixer value (i.e., sw_mixer_route is main), the AFM audio can duck and be ducked by other audio.
If the audio configuration file routes the AFM playback audio through the AFM mixer path, it is never ducked (sw_mixer_route is afm by default). However, only certain AFMs, such as the Bridge and Voice AFMs, duck other audio streams. See “AMP and audio concurrency management” in “QSA with QNX Acoustics Management Platform”.