The Android 10 release includes a significant refactoring of the audio
policy manager to provide more flexibility to support complex automotive use cases:
OEM-specific routing strategies.
Customizable volume groups for groups of legacy stream types using the same volume curves.
Routing strategies declared by the audio policy engine instead of being hard coded.
Volume curves and groups managed by the audio policy engine.
Internal refactoring preparing for a future split between common code and configurable code
and offering richer audio device management. For example, the use of all device properties not just
its type in policy rules.
Android 7.0 introduced a audio policy configuration file format (XML) for
describing your audio topology.
Previous Android releases required using
device/<company>/<device>/audio/audio_policy.conf
to declare the audio devices present on your product (you can see an example of
this file for the Galaxy Nexus audio hardware in
device/samsung/tuna/audio/audio_policy.conf). However, CONF is a
simple, proprietary format that is too limited to describe complex topologies for
verticals like televisions and automobiles.
Android 7.0 deprecated audio_policy.conf and added support
for defining an audio topology using an XML file format that's more
human-readable, has a wide range of editing and parsing tools, and is flexible
enough to describe complex audio topologies. Android 7.0 uses the
USE_XML_AUDIO_POLICY_CONF build flag for choosing the XML
format of config files.
Advantages of the XML format
As in the CONF file, the XML file enables defining the number and types
of output and input stream profiles, devices usable for playback and capture, and
audio attributes. In addition, the XML format offers the following enhancements:
In Android 10, more than one active recording app is
allowed simultaneously.
Recording start is never rejected due to a concurrency situation.
The registerAudioRecordingCallback(AudioManager.AudioRecordingCallback cb)
callback notifies clients of capture path changes.
In the following situations, a client gets silent audio samples:
A privacy-sensitive use case (for example, VOICE_COMMUNICATION) is active.
The client doesn't have a foreground service or foreground UI.
Specials roles are recognized by the policy:
Accessibility service: Can record even if a privacy-sensitive use case is active.
Assistant: Considered privacy sensitive if the UI is on top.
Audio profiles have a structure similar to HDMI simple audio descriptors, enabling a different
set of sampling rates/channel masks for each audio format.
There are explicit definitions for all possible connections between devices and streams.
Previously, an implicit rule made it possible to connect all devices attached to the same HAL
module, preventing the audio policy from controlling connections requested with audio patch
APIs. In the XML format, the topology description defines connection limitations.
Support for includes avoids repeating standard A2DP, USB, or reroute submit
definitions.
Volume curves are customizable. Previously, volume tables were hardcoded. In the XML
format, volume tables are described and can be customized.
The template at
frameworks/av/services/audiopolicy/config/audio_policy_configuration.xml
shows many of these features in use.
File format and location
The new audio policy configuration file is
audio_policy_configuration.xml and is located in
/system/etc. The following examples show a simple audio policy configuration in the
XML file format for Android 12 and for the versions below
Android 12.
The top-level structure contains modules that correspond to each audio HAL
hardware module, where each module has a list of mix ports, device ports, and
routes:
Mix ports describe the possible config profiles for streams
that can be opened at the audio HAL for playback and capture.
Device ports describe the devices that can be attached with
their type (and optionally address and audio properties, if relevant).
Routes is separated from the mix port descriptor,
enabling the description of routes from device to device or stream to device.
Volume tables are simple lists of points defining the curve used to translate
from a UI index to a volume in dB. A separate include file provides default
curves, but each curve for a given use case and device category can be
overwritten.
The XML Inclusions (XInclude) method can be used to include audio policy
configuration information located in other XML files. All included files must
follow the structure described above with the following restrictions:
Files can contain only top-level elements.
Files can't contain XInclude elements.
Use includes to avoid copying standard Android Open Source Project (AOSP)
audio HAL module configurations information to all audio policy configuration
files (which is prone to errors). A standard audio policy configuration XML file
is provided for the following audio HALs:
AudioPolicyManager.cpp is split into several modules
to make it easy to maintain and configure. The organization of
frameworks/av/services/audiopolicy includes the
following modules.
Module
Description
/managerdefault
Includes the generic interfaces and behavior implementation common to all
apps. Similar to AudioPolicyManager.cpp with engine
functionality and common concepts abstracted away.
/common
Defines base classes (for example, data structures for input output audio stream
profiles, audio device descriptors, audio patches, and audio ports). This was previously
defined inside AudioPolicyManager.cpp.
/engine
Implements the rules that define which device and volumes should be used for
a given use case. It implements a standard interface with the generic part, such
as to get the appropriate device for a given playback or capture use case, or to
set connected devices or external state (that is, a call state of forced usage) that
can alter the routing decision.
Policy engine implementation that relies on Parameter Framework (see below).
Configuration is based on the Parameter Framework and where the policy is
defined by XML files.
/enginedefault
Policy engine implementation based on previous Android Audio Policy Manager
implementations. This is the default and includes hard-coded rules that
correspond to Nexus and AOSP implementations.
/service
Includes binder interfaces, threading, and locking implementation with
the interface to the rest of the framework.
Configuration using Parameter Framework
Audio policy code is organized to make it easy to understand and
maintain while also supporting an audio policy defined entirely by configuration
files. The organization and audio policy design is based on Intel's Parameter
Framework, a plugin-based and rule-based framework for handling parameters.
Using the configurable audio policy enables vendors OEMs to:
Describe a system's structure and its parameters in XML.
Write (in C++) or reuse a backend (plugin) for accessing described
parameters.
Define (in XML or in a domain-specific language) conditions/rules upon which
a given parameter must take a given value.
AOSP includes an example of an audio policy configuration file that uses the Parameter
Framework at Frameworks/av/services/audiopolicy/engineconfigurable/parameter-framework/example/Settings/PolicyConfigurableDomains.xml. For
details, refer to Intel documentation on the
Parameter Framework.
In Android 10 or lower, the configurable audio policy
is selected using the build option USE_CONFIGURABLE_AUDIO_POLICY.
In Android 11 or higher, the version of the audio policy
engine is selected in the audio_policy_configuration.xml file.
To select the configurable audio policy engine, set the value of the engine_library
attribute of the globalConfiguration element to configurable
as in the following example:
Android 6.0 introduced a public Enumeration and Selection API that sits on
top of the audio patch/audio port infrastructure and allows app
developers to indicate a preference for a specific device output or input for
connected audio records or tracks.
In Android 7.0, the Enumeration and Selection API is verified by CTS tests
and is extended to include routing for native C/C++ (OpenSL ES) audio streams.
The routing of native streams continues to be done in Java, with the addition of
an AudioRouting interface that supersedes, combines, and deprecates
the explicit routing methods that were specific to the AudioTrack and
AudioRecord classes.
For details on the Enumeration and Selection API, refer to
Android
configuration interfaces and OpenSLES_AndroidConfiguration.h.
For details on audio routing, refer to
AudioRouting.
Multi-channel support
If your hardware and driver supports multichannel audio via HDMI, you can
output the audio stream directly to the audio hardware (this bypasses the
AudioFlinger mixer so it doesn't get downmixed to two channels.) The audio HAL
must expose whether an output stream profile supports multichannel audio
capabilities. If the HAL exposes its capabilities, the default policy manager
allows multichannel playback over HDMI. For implementation details, see
device/samsung/tuna/audio/audio_hw.c.
To specify that your product contains a multichannel audio output, edit the
audio policy configuration file to describe the multichannel output for your
product. The following example from
frameworks/av/services/audiopolicy/config/primary_audio_policy_configuration_tv.xml
shows a dynamic channel mask, which means that the audio policy manager queries the channel
masks supported by the HDMI sink after connection.
You can also specify a static channel mask such as
AUDIO_CHANNEL_OUT_5POINT1. AudioFlinger's mixer downmixes the
content to stereo automatically when sent to an audio device that doesn't
support multichannel audio.
Media codecs
Ensure that the audio codecs your hardware and drivers support are properly
declared for your product. For details, see
Exposing Codecs to the
Framework.
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
