Car audio configuration

In Android 10, car_audio_configuration.xml replaced car_volumes_groups.xml and IAudioControl.getBusForContext. The audio policy files, typically contained in the vendor partition, represent the audio hardware configuration of the board. All devices referenced in car_audio_configuration.xml must be defined in audio_policy_configuration.xml.

Figure 1 below illustrates a high-level overview of the car audio service architecture in which the car audio service reads the car audio configuration file to set up audio for the device.

Figure 1. Car audio architecture overview.

Place the car audio configuration file in vendor\etc\ or system\etc\ on the device, with the vendor\etc\ being the first place searched for the file by the car audio service. The car audio services reads car_audio_configuration.xml to determine the audio configuration.

Car audio zones:

• Each audio zone contains a unique audio zone ID.
• Each audio zone can be mapped to an occupant zone.

• The audio actions in each zone are independent of each other:

  • Audio focus
  • Audio routing
  • Audio ducking

• Car volume groups:

  • All audio devices that contain a volume group are controlled together with the same gain changes. The audio gain configuration for all devices in a group should be the same.

  • Audio context to audio devices mapping. Use this to construct an audio mix that maps audio usages to an output device.

  • All audio contexts should be represented within a zone. This allows for audio routing to be accurately set up for all audio attribute usages.

Audio contexts

To simplify the configuration of AAOS audio, similar usages have been grouped into CarAudioContexts. These audio contexts are used throughout CarAudioService to define routing, volume groups, audio focus, and ducking management. The static audio contexts in AAOS are listed below.

This table describes the mapping between audio contexts and usages. Highlighted rows are provided for a new system usage.

Enable AAOS routing

To use AAOS-based routing, you must set the audioUseDynamicRouting flag to true:

<resources>
    <bool name="audioUseDynamicRouting">true</bool>
</resources>

When false, routing and much of CarAudioService, is disabled and AAOS falls back to the default behavior of the AudioService.

Primary zone

By default, all audio is routed to the primary zone. Only one primary zone exists, which is indicated in the configuration by the attribute isPrimary="true". The primary zone is automatically assigned the Audiomanager.PRIMARY_AUDIO_ZONE.

Sample configuration (version 2)

For example, a vehicle may have two zones, a primary zone and a rear seat entertainment system. In this scenario, you can design a possible car_audio_configuration.xml version 2 as follows:

<audioZoneConfiguration version="2.0">
       <zone name="primary zone" isPrimary="true">
           <volumeGroups>
               <group>
                   <device address="bus0_media_out">
                       <context context="music"/>
                       <context context="announcement"/>
                   </device>
                   <device address="bus3_call_ring_out">
                       <context context="call_ring"/>
                   </device>
                   <device address="bus6_notification_out">
                       <context context="notification"/>
                   </device>
               </group>
               <group>
                   <device address="bus1_navigation_out">
                       <context context="navigation"/>
                   </device>
                   <device address="bus2_voice_command_out">
                       <context context="voice_command"/>
                   </device>
               </group>
               <group>
                   <device address="bus4_call_out">
                       <context context="call"/>
                   </device>
               </group>
               <group>
                   <device address="bus5_alarm_out">
                       <context context="alarm"/>
                   </device>
               </group>
               <group>
                   <device address="bus7_system_sound_out">
                       <context context="system_sound"/>
                       <context context="emergency"/>
                       <context context="safety"/>
                       <context context="vehicle_status"/>
                   </device>
               </group>
           </volumeGroups>
       </zone>
        <zone name="rear seat zone" audioZoneId="1">
           <volumeGroups>
               <group>
                   <device address="bus100_rear_seat">
                       <context context="music"/>
                       <context context="navigation"/>
                       <context context="voice_command"/>
                       <context context="call_ring"/>
                       <context context="call"/>
                       <context context="alarm"/>
                       <context context="notification"/>
                       <context context="system_sound"/>
                       <context context="emergency"/>
                       <context context="safety"/>
                       <context context="vehicle_status"/>
                       <context context="announcement"/>
                   </device>
               </group>
           </volumeGroups>
    </zones>
</audioZoneConfiguration>

In this example, the primary zone separates out some audio contexts to different devices. This enables the HAL to apply different post-processing effects and to mix the output on each device by using the vehicle's hardware. The devices have been arranged into several volume groups: media, navigation, calls, alarms, and system sounds. If the system is configured to useFixedVolume, then the volume levels for each group are passed to the HAL to apply to the output of these devices.

For the primary zone, we recommend that system sounds be separate from other sounds. This allows for vehicle sounds to be treated with a higher priority. The car audio service already makes these distinctions for vehicle sounds in terms of focus and ducking management. For example, an emergency sound focus request has higher priority than another focus request.

To keep things simple, in the secondary zone example all audio contexts are routed to a single device and one volume group.

Occupant zone audio configuration

In Android 11, car_audio_configuration.xml introduced two new fields, audioZoneId and occupantZoneId. You can use audioZoneId to control audio zone management. You can use occupantZoneId to configure routing based on user ID.

Revisiting the audio configuration above, but utilizing the new field for occupant zone id and audio zone id mapping, the new configuration without the volume group definitions can be set up as follows.

<audioZoneConfiguration version="2.0">
       <zone name="primary zone" isPrimary="true" occupantZoneId="0">
         ...
       </zone>
       <zone name="rear seat zone" audioZoneId="1" occupantZoneId="1">
         ...
       </zone>
    </zones>
</audioZoneConfiguration>

The configuration above defines a mapping for primary zone to occupant zone 0 and audioZoneId 1 to occupantZoneId 1. In general, any mapping between occupant zone and audio zone can be configured. However, the mapping must be one-to-one. The rules that defined the two new fields are listed below.

• audioZoneId for the primary zone is always PRIMARY_AUDIO_ZONE id. If isPrimary="true" is defined, then audioZoneIdis not needed.

• audioZoneId and occupantZoneId numbers can't be repeated.

• audioZoneId and occupantZoneId can only have a one-to-one mapping.

Android 14 car audio configuration

In Android 14, AAOS introduced the OEM plugin service, which allows you to more actively manage audio behavior overseen by the car audio service. Along with the new plugin services, the following changes are added to the car audio configuration file:

• OEM defined car audio context
• Non-primary zone dynamic configurations

OEM-defined car audio context

To enable a flexible audio configuration, in Android 14, car audio service allows for the audio usages to be grouped differently than the static Audio contexts defined above. This OEM-defined context can be defined in the car_audio_configuration.xml version 3 file.

Instead the currently defined static audio contexts are used. The general format of the OEM-defined car audio context is shown below.

The OEM contexts each require a name along with a list of audio attributes usage that are assigned to the context. In the example above, two contexts are defined:

<carAudioConfiguration version="3">
    <oemContexts>
        <oemContext name="media">
            <audioAttributes>
                <usage value="AUDIO_USAGE_MEDIA" />
    <usage value="AUDIO_USAGE_UNKNOWN"/>
            </audioAttributes>
        </oemContext>
        <oemContext name="game">
            <audioAttributes>
                <usage value="AUDIO_USAGE_GAME" />
            </audioAttributes>
        </oemContext>
...

• media context contains AUDIO_USAGE_MEDIA and AUDIO_USAGE_UNKNOWN
• game context contains only AUDIO_USAGE_GAME

The context must be defined at the top of the car_audio_configuration.xml file. When the OEM contexts are defined, the rest of car audio configuration can proceed as before. The following rules apply to the car audio context:

• OEM context definitions are optional. The static Audio context is used instead.

• Don't repeat contexts names.

• Don't assign audio attribute usage to multiple contexts.

• All audio usages defined in AudioAttributes should be used to construct the context.

Strictly speaking, the android.audio.policy.configuration.V7_0.AudioUsage string representation of the audio usage must be used for the OEM audio context definition. In the future, newer audio attribute usages will be assigned to the most appropriate context to reduce error while migrating from one Android version to another.

While the OEM-defined context was introduced to further expand the OEM plugin audio service, it can still be used without the OEM plugin service. The audio behavior resembles that of the static audio service:

• Audio focus interactions. Audio attribute is used to determine the best matching behavior as set up by the audio focus interaction matrix. For details, see Audio focus.

• Audio volume control audio attribute is used to determine the best matching:

  • Volume group based on the OEM-defined context.
  • Priority from the static volume list configured.

• Audio ducking behavior:

  • Audio attribute usage for the current audio focus is used to map to the output audio device information as defined in the car audio configuration file.

  • Audio attribute is used to map the corresponding static context to duck, based on the static audio ducking matrix.

Dynamic audio zones configurations

In Android 14, to accommodate a dynamic audio zones configuration, the car audio configuration schema for defining audio zones is also updated to version 3. The new schema requires a configuration be set up for each zone.

<carAudioConfiguration version="3">
    <!-- optional OEM context -->
    <oemContexts>
      <oemContext name="media">
        <audioAttributes>
          <usage value="AUDIO_USAGE_MEDIA" />
          <usage value="AUDIO_USAGE_UNKNOWN"/>
        </audioAttributes>
      </oemContext>
      <oemContext name="game">
        <audioAttributes>
          <usage value="AUDIO_USAGE_GAME" />
        </audioAttributes>
      </oemContext>
...
    </oemContexts>
  <zones>
    <zone name="primary zone" isPrimary="true" occupantZoneId="0">
      <zoneConfigs>
        <zoneConfig name="primary zone config 0" isDefault="true">
          <volumeGroups>
            <group>
              <device address="bus0_media_out">
                <context context="media"/>
            <context context="game"/>
                <context context="announcement"/>
              </device>
              <device address="bus6_notification_out">
                <context context="notification"/>
              </device>
            </group>
  ...
      </zoneConfigs>
    </zone
  </zones>

To learn more, see the version 3 file defined in device/generic/car/emulator/audio/car_audio_configuration.xml. Starting in Android 14, the primary zone can have only one (1) configuration. Non-primary zones can have multiple configurations. The following rules apply to car audio configurations:

• The primary audio zone can have only one configuration.

• Non-primary audio zones can have multiple configurations.

• Name must be unique for each audio zone and audio zone configuration.

• Within an audio zone, audio configurations may differ:

  • Volume groups set-up need not be the same.
  • Audio context assignment need not be the same.

• Audio output device names should be unique across zones or configurations. A device name should appear only once in an audio configuration or zones.

• Audio devices belonging to the same volume group should have the same audio gain configurations.

• All audio contexts (OEM or static) must be assigned for each audio configuration.

Forward compatibility

Though the new versions of the car_audio_configuration.xml introduce new features in each update, you can still use older files in newer versions of AAOS. OEMs updating to new versions of Android can re-use the car_audio_configuration.xml file.

To use a new feature that requires new information contained in the car_audio_configuration.xml, the version must be updated. Attempting to use an older version of a file with information not supported in that file version throws an IllegalStateException when the car service is started. The exception message contains the relevant information about which information is used and which minimum version is required.