Syntax of the audio policy configuration file

The audio policy configuration file has a specific syntax.

The general syntax is as follows:

The value sections you can have are:

[audio_type] section

The order that you define your audio types, using the [audio_type] section defines when one audio streams ducks another. For each audio_type section, you must use the following key-value pairs to describe the audio type. Every required key must defined in the audio type section with valid values.
CAUTION:
If you leave any of the required key-value pairs out of an [audio_type] section, the file is invalid and io-audio fails to start.
Below are the required key-value pairs for each audio type you define:
Key: (Required) name
A string that specifies the name of the audio type. For example, phone or ringtone.
Key: (Required)prio
The priority directive of the audio type defined as a String value. These are the valid values:
  • same–The audio type has the same priority as previous audio type. If all the audio_types have the prio key set to same then, all audio types are at the same priority (including the first entry). An entry needs to define prio=decr for the priority to change.
  • decr–The priority of the audio type is one lower than the previously defined audio type.

    The first entry you define has the highest priority and forces any lower priority audio streams to duck (lower their volume).

Key: (Required) duck_same_prio_policy
The ducking policy of the same priority type that's defined as a String value. Any audio types with the same priority must be configured to have policy. Don't have different policies configured for audio types with the same priority. These are the valid values:
  • last_wins–The last added stream ducks previous added audio streams with the same priority.
  • first_wins–The first added stream ducks other audio streams with the same priority.
  • mix–The added audio stream ducks specific channels of other streams with the same priority. When you use this policy for audio types with the same priority, those streams are ducked according to the duck_same_prio_percent setting. If there are multiple settings for the same channel, then the strictest configuration applies. To understand how this key and duck_same_prio_policy duck_same_prio_percent, see the “Understanding the mix policy with multiple audio types with the same priority.”
CAUTION:
Don't set this duck_same_prio_policy pair to mix if you want to use enable preemption_by_same. If you do, io-audio fails to start.
Key: (Required) duck_same_prio_percent
Integer or String:Integer
The ducking percentage to apply to audio types with the same priority. The value can be specified as an Integer or comma delimited String:Integer key-value pair. You can specify either a single percentage value or percentage values for multiple channels from 0 to 7.

A single percentage value that specifies a value between 0 or 100 for audio types at the same priority. This value specifies the percentage of the volume to duck for all channels of the active streams that are at the same priority level. So for example, if you specify a value of 50, it means to duck 50% (or adjust to 50% of current volume level). This means if you specify 100, it effectively means play 100% of the volume level or effectively don't perform ducking. Alternatively, you can use the string noducking, which is the same as setting the value to 100. Example: duck_same_prio_percent=50. To understand how this works, see the “Understanding the mix policy with multiple audio types with the same priority.” section.

To specify percentage values for multiple channels, use this syntax to specify the channel and the percentage to duck, with each channel delimited by a comma (,): chX:ducking_percentage, chX:ducking_percentage where X represents the channel number. It's important to mention that if you don't specify a percentage for an active channel, ducking defaults to 100 (or no ducking).

For example, the following specifies that channel 0 adjusts to 50% of its volume level, channel 1 adjusts to 80% of its volume level, and since channel 2 isn't specified in the key-value pair, ducking isn't applied on it (effectively 100): duck_same_prio_percent=ch0:50, ch1:80

Key: (Required) duck_lower_prio_percent
Integer or String:Integer
The ducking percentage to apply to audio types with a lower priority. The value can be specified as an Integer value or multiple comma delimited String:Integer key-value pairs. You can specify either a single percentage value or percentage values for multiple channels from 0 to 7.

A single percentage value that specifies a value between 0 or 100 for audio types with a lower priority. This value specifies the percentage of the volume to duck for all channels of the active streams that are at the same priority level. So for example, if you specify a value of 50, it means to duck 50% (or adjust to 50% of current volume level). This means if you specify 100, it effectively means play 100% of the volume level or effectively don't perform ducking. Alternatively, you can use the string noducking, which is the same as setting the value to 100. For example: duck_lower_prio_percent=50.

To specify percentage values for multiple channels, use this syntax to specify the channel and the percentage to duck, with each channel delimited by a comma (,): chX:ducking_percentage, chX:ducking_percentage where X represents the channel number. It's important to mention that if you don't specify a percentage for an active channel, ducking defaults to 100 (or no ducking).

For example, the following specifies that channel 0 adjusts to 50% of its volume level, channel 1 adjusts to 80% of its volume level, and since channel 2 isn't specified in the key-value pair, iducking isn't applied on it (effectively 100): duck_same_prio_percent=ch0:50,ch1:80

Key: (Optional) preemption_by_higher
String (pause or suspend)
(Optional) When the audio type is ducked to a volume level of zero or ducked 100% by an audio type with the higher priority, the audio stream suspends playing. If there are multiple higher priority audio types, the ducking of volume levels are cumulative. The status of the audio type channel moves to SND_PCM_STATUS_SUSPENDED state. WHen the audio stream is no longer ducked to a volume of zero, you can specify the behavior that occurs as one of the following:
  • pause – Transition to the PAUSE (SND_PCM_STATUS_PAUSED) when the system clears the SUSPENDED state. The audio stream is now paused and the snd_pcm_*_resume() is required to resume playing of the audio stream.
  • suspend – Automatically resume playing the audio stream. No additional calls are require to move to the RUNNING (SND_PCM_STATUS_RUNNING) state.
When this key-value pair isn't specified for the audio type, audio streams belonging the audio type are muted and remain in the RUNNING (SND_PCM_STATUS_RUNNING)state.
Key: (Optional) preemption_by_same
String (pause or suspend)
(Optional) When the audio type is ducked to a volume level of zero (or ducked to zero) by an audio type with the same priority, the audio stream suspends playing. If there are multiple higher priority audio types, the ducking of volume levels are cumulative. With this setting, since the priorities are the same, different APIs modify which same priority audio type is relevant. For more information about how this works, see the Understanding preemption section in this chapter.
  • pause – Transition to the PAUSE (SND_PCM_STATUS_PAUSED) when the system clears the SUSPENDED state. The audio stream is now paused and the snd_pcm_*_resume() is required to resume playing of the audio stream.
  • suspend – Automatically resume playing the audio stream. No additional calls are require to move to the RUNNING (SND_PCM_STATUS_RUNNING) state.
When this key-value pair isn't specified for the audio type, audio streams belonging the audio type are muted and remain in the RUNNING (SND_PCM_STATUS_RUNNING)state.
CAUTION:
You should not enable this setting if you set the duck_same_prior_policy to mix. If you do, io-audio fails to start because it's an invalid configuration.

(Optional) [vol_ramp] section

This section permits you to define volume ramping for audio management scenarios based on specific names. The name and duration are required key-value pairs and profile is optional. If you don't define ramping for an audio management scenario, the default duration is 20 milliseconds with a linear volume ramp (i.e., 100:100).

For each volume ramp ([vol_ramp]) section, you can use the following key-value pairs to describe the audio type.

Key: (Required) name
String(ducking, pause-resume, volume_mute)
This is a profile name that represents the scenario when ramping occurs. You can use one of these predefined names:
  • ducking — This name corresponds to any changes that are made due to ducking policies being used.
  • pause_resume — This name corresponds when the audio stream is paused or resumed using API calls.
  • volume_mute — This corresponds to when volume changes are made, including muting using the mixer. You can override this behavior using API calls (e.g., snd_mixer_group_write() and the change_duration member in the snd_mixer_group_t. If API calls don't specify the duration, it treated as a zero and the duration configured for this scenario is used for volume ramping.
Key: (Required) duration
Integer
An integer that represents the number of milliseconds to ramp to the specified volume, called ramp duration. This is the time it takes for the sum of all ramp segments to complete. For ducking and pause_resume scenarios, this parameter indicates the duration to complete ramping. The value specified here is used if the duration isn't specified
Key: (Optional) profile
Integer:Integer(sample percentage, volume increase percentage)
When specified, the number of sample pairs (comma-delimited pairs) represent the number of ramp segments. Each ramp segment indicates a percentage of the sample (duration) and the percentage of the volume delta. The sum of the percentage values for the ramp samples and volume increment values must equal to 100.
For example:
profile=20:10,60:80,20:10
In the example above, there are three ramp segments, which creates a non-linear volume ramp. The segments mean:
  • For 20% of the sample (duration), increase the volume by 10% of the volume delta
  • remaining 60% of the sample, increase the volume by 80% of the volume delta
  • For the remaining 20% of the sample, increase to the remaining volume delta
Notice that the sum of the percentage samples(duration) values, 20 + 60 + 20 is 100; likewise, the sum of percentage values to increment the volume by, 10 + 80 + 10 is also 100.

Example of an audio policy configuration file

[audio_type] # section defining an audio type
name=voice                                  # Audio type name string
prio=same                                   # Priority directive of the audio type,
                                            # possible value is "same" or "decr"
duck_same_prio_policy=last_wins             # Ducking policy of the same priority type,
                                            # Possible values are "last_wins", 
                                            # "first_wins", or "mix"
duck_same_prio_percent=0                    # Ducking percentage applied to same
                                            # priority audio types
duck_lower_prio_percent=0                   # Ducking percentage applied to lower
                                            # priority audio types

[audio_type]
name=ringtone
prio=decr                                   # Priority of the audio type is decreased
                                            # by one from previous audio type
duck_same_prio_policy=last_wins             # Last active audio stream that can duck
                                            # previous audio streams of same priority
duck_same_prio_percent=50                   # all channels of active streams at the
                                            # same priority level are ducked to 50 percent
duck_lower_prio_percent=50                  # all channels of active streams at lower
                                            # priority levels are ducked to 50 percent

[audio_type]
name=nav
prio=decr
duck_same_prio_policy=last_wins
duck_same_prio_percent=ch0:50,ch1:100       # Channel/Voice 0 ducked to 50 percent,
                                            # Channel/Voice 1 remains at 100 percent
duck_lower_prio_percent=ch0:50,ch1:100      # Ducking values will default to 100
                                            # (no ducking) for channels not listed

[audio_type]
name=tts_front
prio=decr
duck_same_prio_policy=last_wins
duck_same_prio_percent=80
duck_lower_prio_percent=80

[audio_type]
name=tts_back
prio=same                                   # Priority of the audio type is the
                                            # same as the previously defined type
duck_same_prio_policy=last_wins
duck_same_prio_percent=0
duck_lower_prio_percent=50

# To allow games and media to play concurrently define the game type one above
# media with duck_lower_prio_percent=100/noducking
# Note: This means that if there are other lower priority types
#defined they will also not be ducked by the game type.

[audio_type]
name=game
prio=decr
duck_same_prio_policy=mix                   # Mix audio streams at same priority with
                                            # the below ducking configuration
duck_same_prio_percent=100                  # 100 percent
duck_lower_prio_percent=noducking

# Live media is not pausable, 
# so preemption is not enabled
[audio_type]
name=live_multimedia
prio=decr
duck_same_prio_policy=last_wins
duck_same_prio_percent=0
duck_lower_prio_percent=70

# The only difference between the live_multimedia and multimedia types
# is that multimedia can be paused so that preemption is enabled
[audio_type]
name=multimedia
prio=same
duck_same_prio_policy=last_wins
duck_same_prio_percent=0
duck_lower_prio_percent=70
preemption_by_higher=suspend                # Audio stream will be suspended when
                                            # ducked to 0 percent by higher priority types
preemption_by_same=pause                    # Audio stream will be paused when
                                            # ducked to 0 percent by same priroity types

[audio_type]
name=default
prio=decr
duck_same_prio_policy=mix                   # Mix audio streams at same priority
                                            # with the below ducking configuration
duck_same_prio_percent=100                  # 100 percent of volume (no ducking)
duck_lower_prio_percent=noducking
preemption_by_higher=suspend                # Audio stream is suspended when
                                            # ducked to 0 percent by higher priority
                                            # types
[vol_ramp]
name=volume_mute                            # When mixer API calls are made,
                                            # such as snd_pcm_mixer_write()
duration=20                                 # Ramp in the span of 20 milliseconds
profile=20:10,60:80,20:10                   # Defined are three linear segments.
                                            # Segment 1, specifies 20% of the duration and increase the
                                            # volume by 10% of the volume ramp. Segment 2, species
                                            # 60% of the duration and 80% of the volume increase, and
                                            # segment 3, specifies the remaining 20% duration
                                            # and to increase the volume by the remaining 10%

[vol_ramp]
name=pause_resume                           # Whenever the user calls snd_pcm_*_resume() or
                                            # snd_pcm_*_pause()
duration=30                                 # duration of 30 milliseconds
                                            # No profile key-value is specified, so
                                            # it's a linear ramp

[vol_ramp]
name=ducking                                # When ducking policies and preemption is used
duration=60                                 # Ramp time is 60 milliseconds