Syntax of the audio policy configuration file

The audio policy configuration file has a specific syntax.

The general syntax is as follows:

Tip: If you have Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed, you can have more than one audio policy configuration file. The individual audio policy configuration files can have different audio types and policies.

The valid 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 stream ducks another. For each audio_type section, you must use the following key-value pairs to describe the audio type. Every required key must be 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 the duck_same_prio_policy duck_same_prio_percent values interact, see Understanding the mix policy when using multiple audio types with the same priority.”
    Note: All audio types with the same priority level and that have duck_same_prio_policy=mix must have the same values set for the duck_lower_prio_percent.
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 to not 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 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 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, ducking isn't applied on it (effectively 100): duck_same_prio_percent=ch0:50,ch1:80

Key: (Optional) preemption_by_higher
String (pause or suspend)
Tip: If you have Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed, you can't use this key. Use the preemptable key instead.
(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 the SUSPENDED (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 PAUSED (SND_PCM_STATUS_PAUSED) state when the system clears the SUSPENDED state. The audio stream is now paused, and you must call snd_pcm_*_resume() 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)
Tip: If you have Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed, you can't use this key. Use the preemptable key instead.
(Optional) When the audio type is ducked to a volume level of 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) state when the system clears the SUSPENDED state. The audio stream is now paused, and you must call snd_pcm_*_resume() 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.
Key: (Optional) preemptable
String (true, true:suspend, or false)
Tip: If you have Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed, you must use this key instead of the preemption_by_higher or the preemption_by_same keys.
(Optional) This key specifies whether the audio type can be preempted by audio management. The default behavior when this key isn't specified is false. You can specify one of the following values for this key:
  • false — Indicates to audio management that this audio stream can't be preempted. You can still however, explicitly call APIs to transition to the PAUSED state.

    It's important to remember that when the audio stream is ducked to zero, the audio stream remains in the RUNNING (SND_PCM_STATUS_RUNNING) state while muted.

  • true — Indicates to audio management that the audio type can preempted. This depends on the value of the transient key. If transient is set to true for the preempting audio stream, then the audio stream moves to the SUSPENDED state when preemption occurs and when preemption is lifted (no longer ducked to zero), the audio stream transitions back to its previous state. If transient is set to false for the preempting audio stream, then the audio stream transitions to the SUSPENDED state and when preemption is lifted, the audio stream transitions to the PAUSED state. Because your audio stream is in the PAUSED state, you must call snd_pcm_*_resume() to resume playing.
  • true:suspend — Indicates to audio management that the audio type can be preempted, but is limited to transitioning to the SUSPENDED state and then back to its original state. It's important to mention that audio management won't transition the audio stream to the PAUSED state.This setting is useful for audio types where you don't want to call snd_pcm_*_resume() to resume playing the audio stream.
Key: (Optional) transient
Boolean (true or false)
Tip: If you have Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed, you can use this key with the preemptable key.
(Optional) This key specifies the transition to occur to the preemptable audio type. When set to true (default), the audio type can cause a preemptable audio type to move to the SUSPENDED state and when preemption is lifted, the audio stream transitions back to its original state. When set to false, this audio type can cause a preemptable audio type to move to the SUSPENDED state and when preemption is lifted, it moves to the PAUSED state. This means that the user must call snd_pcm_*_resume() to resume playing the audio stream. It's important to mention that when this key is set to false, but the preemptable key is set to true:suspend, the audio stream that was preempted will move back to its original state when preemption is lifted (no longer ducked to zero).
Note: Audio types of the same priority level and with the duck_same_prio_prority set to mix must have the same setting for this key, otherwise an error occurs when loading the audio policy configuration file.

(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's treated as a zero, and the duration configured for this scenario is used for volume ramping.
Key: (Required) duration
Integer
This number 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) represents 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 create a non-linear volume ramp. The segments mean:
  • For the first 20% of the sample (duration), increase the volume by 10% of the volume delta.
  • For the next 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

Tip: If you have Audio component BuildID 594—January 17, 2018 (7.0.594.S201801171044) or a later update installed, this example shows you how to use the preemptable and transient keys.
[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
transient=false                             # Cause lower preemptable types to suspend

[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
preemptable=true:suspend                    # Suspend only if preempted or ducked to 0
# 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
preemptable=true                             #pause or suspend when preempted

[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
preemptable=true: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
            

Example of an audio policy configuration file

Note: The following example uses the preemption_by_higher and preemption_by_same keys. This example is valid for updates previous to BuildID 594—January 17, 2018 (7.0.594.S201801171044).
[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