Android's audio Hardware Abstraction Layer (HAL) connects the higher-level,
audio-specific framework APIs in
android.media
to the underlying audio drivers and hardware. The Audio HAL defines the standard
interface that audio services call into. It must be implemented for the audio
hardware to function correctly.
This page gives an overview of the audio HAL and provides details of its API and implementation requirements.
Audio HAL interface
The audio HAL interface is defined using HIDL
in .hal
files and XSD
schemas for the configuration files, shown as follows.
Figure 1. Audio HAL interface
Configuration files
Audio policy and audio effects XML configuration files are considered to be part of the Audio HAL interface. These files must conform to their schemas, and the conformance is verified by VTS tests.
As part of implementing the audio HAL, you must create an
audio policy configuration file
that describes the audio topology. Audio HAL capabilities must be declared in
the audio_policy_configuration.xml
file for the framework to use them.
Audio HAL API
The audio HAL contains the following APIs:
- Core HAL
- Effects HAL
- Common HAL
Each of these APIs is described in the following sections.
Core HAL
The Core HAL is the main API used by AudioFlinger to play audio and control the audio routing. Some of the key interfaces are as follows:
IDeviceFactory.hal
is the entry point into the API.IDevice.hal
andIPrimaryDevice.hal
contain methods such assetMasterVolume
oropenInputStream
.- Streams are unidirectional and are used by AudioFlinger to send or receive
audio to and from the HAL through
IStream.hal
,IStreamOut.hal
, andIStreamIn.hal
.
The following table lists the location of useful Core HAL components.
Core HAL component | Location |
---|---|
Latest version of API | /hardware/interfaces/audio/6.0
|
Types specific to the latest Core HAL API | /hardware/interfaces/audio/6.0/types.hal
|
Audio policy configuration file XSD schema | /hardware/interfaces/audio/6.0/config/audio_policy_configuration.xsd
|
The default implementation of the Core HAL API (/hardware/interfaces/audio/core/all-versions/default/
)
is a wrapper around pre-Treble HAL implementation using
legacy shared libraries.
The default implementation can also be considered as a reference when
implementing new versions of audio HALs that interact with kernel drivers
directly.
Effects HAL
The Effects HAL API is used by the effects framework to control audio effects. You can also configure preprocessing effects such as automatic gain control and noise suppression through the Effects HAL API.
The following table lists the location of useful Effects HAL components.
Effects HAL component | Location |
---|---|
Latest version of API | /hardware/interfaces/audio/effect/6.0/
|
Effect configuration file XSD schema | /hardware/interfaces/audio/effect/6.0/xml/audio_effects_conf.xsd
|
For more information, see a sample implementation of the
Effects HAL API (/hardware/interfaces/audio/effect/all-versions/default/
) and the
Audio Effects
section.
Common HAL
The Common HAL is a library of common data types used by the Core and Effects HAL APIs. It has no interfaces and no associated VTS tests as it only defines data structures. The Common HAL API contains the following:
- Definitions (
/hardware/interfaces/audio/common/6.0/types.hal
) shared by the Core and Effect APIs - Utilities (
/hardware/interfaces/audio/common/all-versions
) used to help coding against HIDL APIs for implementations, clients and tests
Requirements
In addition to implementing the audio HAL and creating the audio policy configuration file, the following HAL requirements must be adhered to:
- If capture for Sound Trigger (capture from hotword DSP buffer) is supported by one input profile, the implementation must support the number of active streams on this profile corresponding to the number of concurrent sessions supported by Sound Trigger HAL.
- Concurrency of voice call TX and capture from the application processor as detailed on the Concurrent capture page.
Updates to the Audio HAL V7
In order to address backward compatibility issues, Stable AIDL is mandatory for all HAL changes starting Android 13. To support and enhance AIDL adoption in Android 13 and higher, the Audio HAL V7 does the following:
- Unifies the data models used by the framework and HAL.
- Minimizes the duplication between HIDL data types (enums) and the XML schema used for audio policy configuration.
Specifically, changes are made in the following areas in audio HAL V7:
These changes are discussed in more detail in their respective sections.
Enumerations
Starting in Audio HAL V7, enumerated types used in the Audio Policy Configuration file are only defined in the XSD schema and not in the HIDL.
In audio HAL V6, values of enum types (like AudioFormat
) in types.hal
are
also defined in the audio policy configuration file XSD schema, creating a
duplication. To avoid this in V7, the enum types are changed to string
and
all the possible enumeration values are listed in the XSD schema instead.
See Figure 2 for a comparison of some of the changes to the
AudioFormat
enum type in V7.
Figure 2. Comparison of some of the changes to the AudioFormat enum
Refer to the following list for the enum types that have been converted to
String
:
AudioChannelMask
AudioContentType
AudioDevice
: vendor-extensibleAudioFormat
: vendor-extensibleAudioGainMode
AudioSource
AudioStreamType
AudioUsage
Pass string enum values
String values are used for transferring information as enumeration values across the HAL interface boundary. Both the framework and the HAL wrapper use integer enum values for implementing business logic and employ the conversion approach depicted in figure 3.
Figure 3. Passing string enum values
As an example, to pass a value of audio format type from the framework to the vendor:
- The enum value of
AudioFormat
is converted to a string value inlibaudiohal
and is passed to the HAL. - On the HAL side, the default wrapper converts the string to an enum value, which is passed to the legacy HAL.
XML schema changes
Having complete lists of enum values in the XML schema definition (XSD) allows for better audio policy configuration XML file validation by VTS. Changes are made in the audio policy configuration file used with HAL V7 to comply with XSD.
In V7, a standard ␣
(space) character is used to delimit value lists in
attributes (like sampling rates, channel masks and flags), instead of the ,
(comma) and |
(vertical bar) symbols used in V6 and below. As seen in the
following example, a space is used to delimit the list of values for
channelMasks
:
<profile channelMasks="AUDIO_CHANNEL_OUT_STEREO AUDIO_CHANNEL_OUT_MONO" … />
To make the symbol changes, use an automatic conversion script called
update_audio_policy_config.sh
. See the following command to convert a V6
audio policy config file to a V7 version for the Pixel 5 (Redfin) device:
hardware/interfaces/audio/7.0/config/update_audio_policy_config.sh \
device/google/redfin/audio/audio_policy_configuration.xml 6.0
Data types
Some data structures are redefined in V7 in order to minimize duplicate definitions. Repeated tuples of data items are grouped together into reusable structures. These data structures use the latest HIDL features like safe unions.
For example, in V6 and below, a triple of <format, sampling rate, channel mask>
is used often in the HIDL interfaces and types. To remove this redundancy, in
V7, the AudioConfigBase
data type and other data types are defined as follows:
AudioConfigBase := <format, sampling rate, channel mask>
AudioConfigBaseOptional := <[fmt], [sampl. rate], [chan. mask]>
used by
AudioConfig
,AudioOffloadInfo
,AudioPortConfig
AudioProfile := <format, {sampling rates}, {channel masks}>
replaces loose collections in
AudioPort/PortConfig
AudioPortExtendedInfo := device | mix | session
replaces unions in
AudioPort/PortConfig
Vendor tags
In addition to device types and formats, vendors can add custom tags for audio track metadata.
For playback and recording track metadata, vendors can pass their own tags, which are used to add attributes to audio I/O streams, from the apps to the HAL.
Vendor tags for playback track metadata are added as seen in the following example:
struct PlaybackTrackMetadata {
…
/** Tags from AudioTrack audio attributes */
vec<AudioTag> tags;
};
The RecordTrackMetadata
structure is implemented in a similar fashion by
adding tags specific for the recording track metadata.
Vendor extensions namespacing
Starting in HAL V7, vendor extensions require an additional {vendor}
prefix
that isn't required in V6. For the {vendor}
prefix to be valid, it must be
three or more alphanumeric characters.
Use the following format in V7:
VX_{vendor}_{letters/numbers}
The following are some examples of valid V7 vendor extensions:
- VX_GOOGLE_VR
- VX_QCI_AMBIENT_MIC
Version information
The following table lists the HAL version number for each Android release.
Android version | HAL version |
---|---|
Android 13 | 7.1 |
Android 12 | 7.0 |
Android 11 | 6.0 |
Android 10 | 5.0 |
Android 9 | 4.0 |
Android 8 | 2.0 |