AIDL and HIDL Audio HAL comparison

Starting with Android 14, partners and SoC vendors are encouraged to replace the current HIDL HAL implementation with an AIDL HAL implementation.

To facilitate a smooth transition from HIDL Audio HAL to an AIDL Audio HAL, some of the key differences are highlighted on this page. This page also shows the mapping between the AIDL and HIDL interfaces for the Audio HAL.

Difference between AIDL and HIDL Audio HAL implementation

The main differences between the HIDL structure and the AIDL structure are as follows:

  • In AIDL Audio Core HAL, the IConfig interface is introduced as a replacement for the system-wide parameters in XML files in HIDL HAL. The framework reads these parameters from the Core HAL instead of the vendor configuration file. As an example, the list of surround formats that are surfaced for user control is provided by the IConfig.getSurroundSoundConfig method in the Core HAL.

    In AIDL Audio Effects HAL, the effectProxy logic defined in XML files in HIDL Effects HAL is moved to the audio framework. The audio framework queries all effect instances in the system using IFactory.queryEffects, and all effect processings using IFactory.queryProcessing.

  • To avoid confusion with use of the term device for audio device types, IDevice in HIDL Audio HAL is renamed to IModule in the AIDL Audio HAL.

  • The AIDL Audio HAL replaces IPrimaryDevice. The framework sends updates about the current audio mode and screen rotation to every IModule instance. A dedicated IBluetooth interface handles parameters related to Bluetooth synchronous connection oriented (BT SCO) and Hands-Free Profile (HFP). A dedicated ITelephony interface provides telephony-specific controls. You can retrieve instances of both of these interfaces from the primary instance of the IModule interface. See the comparison tables on Core HAL and Feature-related functionality for more information.

  • IDevicesFactory is removed in AIDL Audio HAL to avoid redundancy. HAL modules (that is, IModule interface instances) are now registered directly with the Service Manager using the names of the module instances, such as bluetooth or r_submix. The only exception is the primary module which registers under the instance name default.

AIDL and HIDL Audio HAL mapping

The tables in the following sections show the mapping between the HIDL and AIDL Audio HAL interfaces. See Audio HAL for more information on the directory structure.

Core HAL

All HIDL interfaces are within the android.hardware.audio@N.M package, where N.M denotes the Major.Minor version. All AIDL interfaces are within the android.hardware.audio.core package.

HIDL API interfaces and configuration files AIDL API interfaces
IDevicesFactory Registration of IModule with ServiceManager.
IDevice IModule
IPrimaryDevice ITelephony
IBluetooth
IStream
IStreamIn
IStreamOut		 StreamDescriptor
IStreamIn
IStreamCommon
IStreamOut
audio_policy_configuration.xml
audio_policy_engine_configuration.xml		 IConfig
IModule
Configurable Audio Policy files Use the HIDL implementation for Android 14.

Audio ports, dynamic profiles, routes and patches

In this table, elements of XML files are designated using angle brackets.

HIDL API interface methods and configuration files elements AIDL API interface methods
<attachedDevices>
<defaultOutputDevice>
<mixPorts>
<devicePorts>		 IModule.getAudioPorts
IDevice.getAudioPort
IDevice.setConnectedState		 IModule.getAudioPort
IModule.connectExternalDevice
IModule.disconnectExternalDevice
IStream.getSupportedProfiles IModule.connectExternalDevice
<routes> IModule.getAudioRoutes
IDevice.createAudioPatch
IDevice.updateAudioPatch
IDevice.releaseAudioPatch
IStream.getDevices
IStream.setDevices
Specification of the device in IDevice.openInputStream
IDevice.openOutputStream		 IModule.setAudioPatch
IModule.setAudioPortConfig
IModule.resetAudioPatch

Audio port configurations and streams

HIDL API interface methods AIDL API interface methods
IStream.getAudioProperties
IStream.setAudioProperties
IStreamIn.getAudioSource		 IModule.getAudioPortConfigs
IModule.setAudioPortConfig
IDevice.openInputStream
IDevice.openOutputStream
IStreamIn.prepareForReading
IStreamOut.prepareForWriting
IStream.createMmapBuffer		 IModule.openInputStream
IModule.openOutputStream
IStream.close IStreamCommon.close
IStreamIn.updateSinkMetadata
IStreamOut.updateSourceMetadata		 IStreamIn.updateMetadata
IStreamOut.updateMetadata
IStream.standby StreamDescriptor.Command.standby
IStream.pause
IStream.resume		 StreamDescriptor.Command.pause
.start
IStream.start
IStream.stop
(MMAP Streams)		 StreamDescriptor.Command.start or .burst
.pause (input) and/or .flush (output)
IStreamOut.drain
IStreamOut.flush		 StreamDescriptor.Command.drain
.flush
IStreamOut.setCallback
IStreamOut.clearCallback		 IModule.openOutputStream
IStreamCommon.close
IStreamOut.getPresentationPosition and IStreamIn.getCapturePosition
IStreamOut.getLatency
IStream.getMmapPosition
IStreamIn.getInputFramesLost		 StreamDescriptor.Reply.observable
StreamDescriptor.Reply.latencyMs
StreamDescriptor.Reply.hardware
StreamDescriptor.Reply.xrunFrames
IDevice.getInputBufferSize
IStreamOut.getLatency
IStream.getBufferSize
IStream.getFrameSize
IStream.getFrameCount		 IModule.setAudioPatch, nominal latency, and minimal buffer size are part of the AudioPatch structure returned by the HAL. Actual buffer size in frames is part of the StreamDescriptor structure, together with frame size in bytes. Buffer size in bytes can be calculated by multiplying these two numbers.

Audio Effects connection

HIDL API interface methods AIDL API interface methods
IDevice.addDeviceEffect
IDevice.removeDeviceEffect		 IModule.addDeviceEffect
IModule.removeDeviceEffect
IStream.addEffect
IStream.removeEffect		 IStreamCommon.addEffect
IStreamCommon.removeEffect

System-wide configuration

System-wide configuration that was previously defined in audio policy XML configuration files (namely, audio_policy_configuration.xml and audio_policy_engine_configuration.xml) must be provided through IConfig. However, to ease the transition to AIDL, vendors still have the option of using the same XML files they previously used to set system-wide configuration. The reference implementation for IConfig contains the code necessary for representing information from the XML file using AIDL data types, which facilitates conversion from XML to AIDL.

HIDL configuration file elements AIDL API interface methods
<globalConfiguration>
<speaker_drc_enabled>1

<call_screen_mode_supported>
<engine_library>		 Separated into two different methods:
ITelephony.getSupportedAudioModes
IConfig.getEngineConfig
<volumes>, OR
<volumeGroups>, <ProductStrategies> 		IConfig.getEngineConfig
<surroundSound> IConfig.getSurroundSoundConfig

  1. speaker_drc_enabled is removed from the configuration file as this configuration item isn't used within the system. All devices must have DRC enabled. 

Feature-related functionality

HIDL API interface methods AIDL API interface
IDevice.setMasterVolume
IDevice.getMasterVolume
IDevice.setMicMute
IDevice.getMicMute
IDevice.setMasterMute
IDevice.getMasterMute		 IModule.\*
IPrimaryDevice.getTtyMode
IPrimaryDevice.setTtyMode
IPrimaryDevice.getHacEnabled
IPrimaryDevice.setHacEnabled
IPrimaryDevice.setVoiceVolume		 ITelephony.TelecomConfig.\*
IPrimaryDevice.setBtScoHeadsetDebugName
IPrimaryDevice.getBtScoNrecEnabled
IPrimaryDevice.setBtScoNrecEnabled
IPrimaryDevice.getBtScoWidebandEnabled
IPrimaryDevice.setBtScoWidebandEnabled,
IPrimaryDevice.getBtHfpEnabled
IPrimaryDevice.setBtHfpEnabled
IPrimaryDevice.setBtHfpSampleRate
IPrimaryDevice.setBtHfpVolume		 IBluetooth.ScoConfig.\*
IBluetooth.HfpConfig.\*
IPrimaryDevice.setMode
IPrimaryDevice.updateRotation		 ITelephony.switchAudioMode
IModule.updateAudioMode
IModule.updateScreenRotation
IDevice.setScreenState
IDevice.getMicrophones		 IModule.updateScreenState
IModule.getMicrophones
IDevice.getHwAvSync
IStream.setHwAvSync		 IModule.generateHwAvSyncId
IStreamCommon.updateHwAvSyncId
IStreamIn.setGain
IStreamIn.setMicrophoneDirection
IStreamIn.setMicrophoneFieldDimension		 IStreamIn.setHwGain
IStreamIn.setMicrophoneDirection
IStreamIn.setMicrophoneFieldDimension
IStreamOut.getDualMonoMode
IStreamOut.setDualMonoMode
IStreamOut.getPlaybackRateParameters
IStreamOut.setPlaybackRateParameters
IStreamOut.selectPresentation
IStreamOut.getAudioDescriptionMixLevel
IStreamOut.setAudioDescriptionMixLevel
IStreamOut.setLatencyMode
IStreamOut.getRecommendedLatencyModes		 IStreamOut.\*
IStreamOut.setEventCallback
IStreamOut.setLatencyModeCallback		 IModule.openOutputStream (callbacks are combined into IStreamOutEventCallback)
IDevice.get/setParameters
IStream.get/setParameters		 IModule.get/setVendorParameters
IStreamCommon.get/setVendorParameters

Obsolete methods

HIDL API interface methods Comments
IDevice.initCheck
IDevice.close		 The HAL module publishes itself with the ServiceManager only on successful initialization. At that point, it is considered to be permanent and can't be closed.
IDevice.supportsAudioPatches
IStreamOut.supportsPauseAndResume
IStreamOut.supportsDrain		 Support for patches, pause, resume and drain is mandatory.
IStreamOut.getRenderPosition
IStreamOut.getNextWriteTimestamp		 Obsolete.

Vendor extensions

In the HIDL API, vendor extensions are implemented using the getParameters or setParameters methods from the IDevice and IStream interfaces. These methods accept arbitrary strings. In the AIDL API, there are corresponding methods, such as getVendorParameters or setVendorParameters, which take arbitrary Parcelable instances by using encapsulation within ParcelableHolders.

Other changes

Other general changes are as follows:

  • To improve the testability of HAL APIs, in the AIDL version, we introduce debugging options that are used by VTS tests and are available through the ModuleDebug parcelable. These options instruct the HAL to emulate certain functionality (for example, connection of external devices), which otherwise requires manual intervention and use of external testing equipment.

  • When the framework or the VTS test sets the sys.audio.restart.hal system property to 1, HAL services must restart. The audioserver.rc file handles the restart. While implementing the HAL, use the appropriate HAL service name listed in the audioserver.rc file. In Android 14, the name vendor.audio-hal-aidl is added specifically for the AIDL version of the HAL.

Effects HAL

All HIDL interfaces are within the android.hardware.audio.effect@N.M* package, where N.M is the Major.Minor version. All AIDL interfaces are within the android.hardware.audio.effect package.

HIDL API interfaces and configuration files AIDL API interfaces
IEffectsFactory IFactory
IEffect IEffect
audio_effects.xml IEffect

Effect Factory

HIDL API interfaces
(android.hardware.audio.effect@X.X)		 AIDL API interfaces
(android.hardware.audio.effect)
IEffectsFactory.getAllDescriptors IFactory.queryEffects with null UUID parameter
IEffectsFactory.getDescriptor IFactory.queryEffects with UUID parameter
IEffectsFactory.createEffect IFactory.createEffect
audio_effects.xml IFactory.queryProcessing
IFactory.queryEffects

Effect interfaces

HIDL API interfaces
(android.hardware.audio.effect@X.X)		 AIDL API interfaces
(android.hardware.audio.effect)
IEffect.init IEffect.open
IEffect.setConfig IEffect.setParameter
IEffect.enable IEffect.command(CommandId::START)
IEffect.disable IEffect.command(CommandId::STOP)
IEffect.reset IEffect.command(CommandId::RESET)
IEffect.getDescriptor IEffect.getDescriptor
IEffect.command Map to IEffect.command,
IEffect.setParameter, or
IEffect.getParameter based on the type of legacy HIDL command
N/A IEffect.getState
IEffect.setParameter IEffect.setParameter
IEffect.getParameter IEffect.getParameter

Effect Commands

HIDL API interfaces
(android.hardware.audio.effect@X.X)		 AIDL API interfaces
(android.hardware.audio.effect)
EFFECT_CMD_INIT IEffect.open
EFFECT_CMD_RESET CommandId.RESET
EFFECT_CMD_ENABLE IEffect.command(CommandId::START)
EFFECT_CMD_DISABLE IEffect.command(CommandId::STOP)
EFFECT_CMD_SET_PARAM_DEFERRED Deprecated in Effects AIDL HAL
EFFECT_CMD_SET_PARAM_COMMIT Deprecated in Effects AIDL HAL
EFFECT_CMD_SET_CONFIG
EFFECT_CMD_SET_PARAM
EFFECT_CMD_SET_DEVICE
EFFECT_CMD_SET_VOLUME
EFFECT_CMD_SET_AUDIO_MODE
EFFECT_CMD_SET_CONFIG_REVERSE
EFFECT_CMD_SET_INPUT_DEVICE
EFFECT_CMD_SET_FEATURE_CONFIG
EFFECT_CMD_SET_AUDIO_SOURCE		 IEffect.setParameter
EFFECT_CMD_GET_PARAM
EFFECT_CMD_GET_CONFIG
EFFECT_CMD_GET_CONFIG_REVERSE
EFFECT_CMD_GET_FEATURE_SUPPORTED_CONFIGS
EFFECT_CMD_GET_FEATURE_CONFIG
VISUALIZER_CMD_MEASURE
EFFECT_CMD_FIRST_PROPRIETARY
(same as VISUALIZER_CMD_CAPTURE)		 IEffect.getParameter
EFFECT_CMD_OFFLOAD Deprecated.
In AIDL, offload and non-offload mode switches are handled in the framework.
EFFECT_CMD_DUMP Handled by the built-in binder transaction AIBinder_dump.

Common Effect parameters definition

HIDL definition
(android.hardware.audio.effect@X.X)		 AIDL definition
Types.hal Flags.aidl
Parameter.aidl

Specific Effects definition

HIDL API interfaces
(android.hardware.audio.effect@X.X)		 AIDL API interfaces
(android.hardware.audio.effect)
I$EffectType$.hal $EffectType$.aidl