HAL de control de audio

El HAL de control de audio se introdujo en Android 9 para admitir casos de uso de audio relevantes para la industria automotriz. A partir de Android 14, la HAL de control de audio admite lo siguiente:

• Balance y fundido
• Solicitud de foco de audio de HAL
• Silenciamiento y reducción del volumen del dispositivo
• Cambios en la ganancia del dispositivo de audio
• Cambios en la configuración del puerto de audio

En la figura 1, se muestra una descripción general de alto nivel de la arquitectura del servicio de audio para automóviles, en la que el servicio de audio para automóviles se comunica con el HAL de control de audio.

Figura 1: Configura el audio multizona.

Atenuación y balance de audio

La versión 1 de la HAL de control de audio HIDL se introdujo en Android 9 para admitir la atenuación y el balance de audio en casos de uso automotriz. Además de los efectos de audio genéricos que ya se proporcionan en Android, este mecanismo permite que las apps del sistema establezcan el balance de audio y la atenuación a través de las APIs de CarAudioManager:

class CarAudioManager {
       /**
       *   Adjust the relative volume in the front vs back of the vehicle cabin.
       *
       *   @param value in the range -1.0 to 1.0 for fully toward the back through
       *   fully toward the front. 0.0 means evenly balanced.
       */
       @SystemApi
       @RequiresPermission(Car.PERMISSION_CAR_CONTROL_AUDIO_VOLUME)
       public void setFadeTowardFront(float value);

       /**
       *   Adjust the relative volume on the left vs right side of the vehicle cabin.
       *
       *   @param value in the range -1.0 to 1.0 for fully toward the left through
       *   fully toward the right. 0.0 means evenly balanced.
       */
       @SystemApi
       @RequiresPermission(Car.PERMISSION_CAR_CONTROL_AUDIO_VOLUME)
       public void setBalanceTowardRight(float value);
}

Una vez que se llaman a estas APIs, se llaman a las respectivas APIs de HAL de control de audio desde el servicio de audio del automóvil:

interface IAudioControl {
       /**
       *   Control the right/left balance setting of the car speakers.
       */
       oneway setBalanceTowardRight(float value);

       /**
       *   Control the fore/aft fade setting of the car speakers.
       */
       oneway setFadeTowardFront(float value);
}

La API está disponible en todas las versiones del HAL de control de audio, incluida la nueva interfaz de HAL de AIDL.

Solicitud de foco de audio de HAL

AAOS, al igual que Android, se basa en la participación activa de las apps en el enfoque de audio para administrar la reproducción de audio en los automóviles. La información de enfoque se usa para administrar las transmisiones que se controlarán para el volumen y la atenuación. Por lo tanto, para expandir aún más el enfoque de audio y brindar una mejor integración de los sonidos específicos del automóvil en la experiencia de Android, se introdujeron los siguientes atributos de audio en Android 11:

• EMERGENCY
• SAFETY
• VEHICLE_STATUS
• ANNOUNCEMENT

Además de este cambio, se agregó un mecanismo para que los sonidos que se originan fuera de Android participen en las solicitudes de enfoque de audio. Por lo tanto, se introdujo la versión 2 de la HAL de control de audio HIDL para permitir solicitudes de enfoque que se originen fuera de Android:

interface IAudioControl {
       /**
       *   Registers focus listener to be used by HAL for requesting and
       *   abandoning audio focus.
       *   @param listener the listener interface
       *   @return closeHandle A handle to unregister observer.
       */
       registerFocusListener(IFocusListener listener)
       generates (ICloseHandle closeHandle);

       /**
       *   Notifies HAL of changes in audio focus status for focuses requested
       *   or abandoned by the HAL.
       *
       *   @param usage The audio usage associated with the focus change
       *   @param zoneId The identifier for the audio zone that the HAL is
       *   playing the stream in
       *   @param focusChange the AudioFocusChange that has occurred
       */
       oneway onAudioFocusChange(bitfield<AudioUsage> usage, int32_t zoneId,
       bitfield<AudioFocusChange> focusChange);
}

En el ejemplo anterior, IFocusListener se define de la siguiente manera:

interface IFocusListener {
       /**
       *   Called whenever HAL is requesting focus as it is starting to play
       *   audio of a given usage in a specified zone.
       *
       *   @param usage The audio usage associated with the focus request
       *    {@code AttributeUsage}
       *   @param zoneId The identifier for the audio zone where the HAL is
       *    requesting focus
       *   @param focusGain The AudioFocusChange associated with this request.
       */
       oneway requestAudioFocus(bitfield<AudioUsage> usage,
       int32_t zoneId, bitfield<AudioFocusChange> focusGain);
       /**
       *   Called whenever HAL is abandoning focus as it is finished playing audio
       *   of a given usage in a specific zone.
       *
       *   @param usage The audio usage for which the HAL is abandoning focus
       *    {@code AttributeUsage}
       *   @param zoneId The identifier for the audio zone that the HAL
       *    abandoning focus
       */
       oneway abandonAudioFocus(bitfield<AudioUsage> usage, int32_t zoneId);
}

Las APIs anteriores se pueden usar para solicitar y abandonar el foco de audio desde el HAL, respectivamente. En respuesta, el servicio de audio para automóviles considera la solicitud de enfoque de audio y reenvía los resultados de forma asíncrona al método IAudioControl#onAudioFocusChange.

Esta API también se puede usar para supervisar los cambios de la solicitud de foco de audio que se origina en el HAL de control de audio. En general, cualquier solicitud de foco de audio permanente del HAL se considera activa, lo que difiere de una solicitud de foco de audio de Android, en la que solo se considera activa la reproducción de una pista de audio activa correspondiente.

Migra HIDL al HAL de control de audio AIDL

Con el advenimiento del AIDL y la migración obligatoria en Android 12 (para obtener más información, consulta AIDL para HAL), la HAL de control de audio se migró a AIDL. Para las APIs existentes de la versión 2 del control de audio HIDL, la migración requirió actualizaciones menores a los métodos existentes:

interface IAudioControl {
       /**
       *   Notifies HAL of changes in audio focus status for focuses requested
       *   or abandoned by the HAL.
       *
       *   @param usage The audio usage associated with the focus change
       *        {@code AttributeUsage}. See {@code audioUsage} in
       *        audio_policy_configuration.xsd for the list of allowed values.
       *   @param zoneId The identifier for the audio zone that the HAL is
       *        playing the stream in
       *   @param focusChange the AudioFocusChange that has occurred.
       */
       oneway void onAudioFocusChange(in String usage, in int zoneId,
              in AudioFocusChange focusChange);
       /**
       *   Registers focus listener to be used by HAL for requesting and
       *   abandoning audio focus.
       *   @param listener the listener interface.
       */
       oneway void registerFocusListener(in IFocusListener listener);
       /**
       *   Control the right/left balance setting of the car speakers.
       */
       oneway void setBalanceTowardRight(in float value);
       /**
       *   Control the fore/aft fade setting of the car speakers.
       */
       oneway void setFadeTowardFront(in float value);
}

Y el IFocusListener correspondiente:

       interface IFocusListener {
       /**
       *   Called whenever HAL is abandoning focus as it is finished playing audio
       *   of a given usage in a specific zone.
       *
       *   @param usage The audio usage for which the HAL is abandoning focus
       *        {@code AttributeUsage}. See {@code audioUsage} in
       *        audio_policy_configuration.xsd for the list of allowed values.
       *   @param zoneId The identifier for the audio zone that the HAL
       *        abandoning focus
       */
       oneway void abandonAudioFocus(in String usage, in int zoneId);
       /**
       *   Called whenever HAL is requesting focus as it is starting to play audio
       *        of a given usage in a specified zone.
       *
       *   @param usage The audio usage associated with the focus request
       *        {@code AttributeUsage}. See {@code audioUsage} in
       *        audio_policy_configuration.xsd for the list of allowed values.
       *   @param zoneId The identifier for the audio zone where the HAL is
       *        requesting focus
       *   @param focusGain The AudioFocusChange associated with this request.
       */
       oneway void requestAudioFocus(in String usage, in int zoneId,
              in AudioFocusChange focusGain);
}

Nota: Los cambios en las APIs existentes son en gran medida sintácticos debido a las diferencias entre AIDL y HIDL. El comportamiento y la respuesta reales en el servicio de audio para vehículos entre HIDL y AIDL son los mismos. Por lo tanto, a menos que se necesiten funciones más nuevas, los OEMs pueden seguir usando la versión 2 del HAL de control de audio. Para conocer las funciones más recientes que se introdujeron con la migración de AIDL, consulta la siguiente sección.

Silenciamiento del grupo de volúmenes

Android 12 introdujo el silenciamiento de grupos de volumen para permitir un control de silenciamiento más completo durante las interacciones de audio del usuario. Esto permite que el HAL de control de audio reciba eventos de silenciamiento como los interceptados por el servicio de audio del automóvil.

Para habilitar la función, los OEMs deben establecer la configuración de audioUseCarVolumeGroupMuting en true en el servicio de automóviles config.xml:

<!-- Configuration to enable muting of individual volume groups.
If this is set to false, muting of individual volume groups is disabled,
instead muting will toggle master mute. If this is set to true, car volume
group muting is enabled and each individual volume group can be muted separately. -->
<bool name="audioUseCarVolumeGroupMuting">true</bool>

Antes de Android 13, la configuración se debía reemplazar con una superposición de recursos de tiempo de ejecución para packages/services/Car/service/res/values/config.xml (para obtener más información, consulta Cómo personalizar la compilación con superposiciones de recursos). A partir de Android 13, puedes usar superposiciones de recursos de tiempo de ejecución para cambiar un valor de configuración. Para obtener más información, consulta Cómo cambiar el valor de los recursos de una app en el tiempo de ejecución.

Las apps del sistema pueden determinar si la función está habilitada con la API de CarAudioManager#isAudioFeatureEnabled. El parámetro que se pasa debe ser la constante CarAudioManager.AUDIO_FEATURE_VOLUME_GROUP_MUTING. El método muestra true si la función está habilitada en el dispositivo; de lo contrario, muestra false.

Además de habilitar la función audioUseCarVolumeGroupMuting, el HAL de control de audio de AIDL debe implementar el mecanismo de silenciamiento del grupo de volumen:

interface IAudioControl {
       /**
       *   Notifies HAL of changes in output devices that the HAL should apply
       *   muting to.
       *
       *   This will be called in response to changes in audio mute state for each
       *   volume group and will include a {@link MutingInfo} object per audio
       *   zone that experienced a mute state event.
       *
       *   @param mutingInfos an array of {@link MutingInfo} objects for the audio
       *   zones where audio mute state has changed.
       */
       oneway void onDevicesToMuteChange(in MutingInfo[] mutingInfos);
}

Donde la información de silenciamiento contiene la información de silenciamiento pertinente para el sistema de audio:

parcelable MutingInfo {
       /**
       *   ID of the associated audio zone
       */
       int zoneId;
       /**
       *   List of addresses for audio output devices that should be muted.
       */
       String[] deviceAddressesToMute;
       /**
       *   List of addresses for audio output devices that were previously be
       *   muted and should now be unmuted.
       */
       String[] deviceAddressesToUnmute;
}

Nota: La información que se pasa se basa en la configuración de cada grupo de volumen, como se define en car_audio_configuration.xml. Específicamente, para cada dirección de dispositivo definida para la configuración del grupo de volumen de audio del automóvil.

AAOS tiene dos mecanismos diferentes para silenciar, según lo siguiente:

• Eventos de teclas que usan el audio KEYCODE_VOLUME_MUTE.

• Llamadas directas al servicio de audio del automóvil con la API de silenciamiento del administrador de audio del automóvil, CarAudioManager#setVolumeGroupMute.

Cuando se habilitan, ambos mecanismos activan una llamada de silenciamiento en el HAL de control de audio.

Autosilenciado de audio del automóvil

Android 12 introdujo la atenuación de audio en el automóvil para optimizar el control de la reproducción simultánea de transmisiones de audio. Esto permite a los OEMs implementar su propio comportamiento de atenuación según la configuración de audio física de un automóvil y el estado de reproducción actual, según lo determine el servicio de audio del automóvil.

El mecanismo de atenuación se basa en los cambios de la pila de enfoque de audio. Cada vez que se produce un cambio de enfoque (ya sea una solicitud de enfoque o un abandono de enfoque), se informa al HAL de control de audio. Al igual que la compatibilidad con la silenciación del grupo de volumen del automóvil, se puede habilitar la atenuación de audio del automóvil con el parámetro de configuración audioUseHalDuckingSignals:

<!-- Configuration to enable IAudioControl#onDevicesToDuckChange API to
inform HAL when to duck. If this is set to true, the API will receive signals
indicating which output devices to duck as well as what usages are currently
holding focus. If set to false, the API will not be called. -->
<bool name="audioUseHalDuckingSignals">true</bool>

Para habilitar la función, el HAL de control de audio AIDL debe implementar la lógica relevante con la señal recibida del servicio de audio del automóvil:

interface IAudioControl {
       /**
       *   Notifies HAL of changes in output devices that the HAL should apply
       *   ducking to.
       *
       *   This will be called in response to changes in audio focus, and will
       *   include a {@link DuckingInfo} object per audio zone that experienced
       *   a change in audo focus.
       *
       *   @param duckingInfos an array of {@link DuckingInfo} objects for the
       *   audio zones where audio focus has changed.
       */
       oneway void onDevicesToDuckChange(in DuckingInfo[] duckingInfos);
}

La información relevante del sistema de audio se encuentra en la información de atenuación de audio:

parcelable DuckingInfo {
       /**
       *   ID of the associated audio zone
       */
       int zoneId;
       /**
       *   List of addresses for audio output devices that should be ducked.
       */
       String[] deviceAddressesToDuck;
       /**
       *   List of addresses for audio output devices that were previously be
       *   ducked and should now be unducked.
       */
       String[] deviceAddressesToUnduck;
       /**
       *   List of usages currently holding focus for this audio zone.
       */
       String[] usagesHoldingFocus;
}

Además de la información de configuración de audio del automóvil contenida en las direcciones del dispositivo para activar o desactivar la función de silenciamiento, la información de silenciamiento también contiene información sobre qué usos de atributos de audio mantienen el enfoque. El objetivo de estos datos es informar al sistema de audio qué usos de atributos de audio están activos.

Esto es obligatorio porque, en la configuración de audio del automóvil, se pueden asignar varios atributos de audio a un solo dispositivo y, sin la información adicional, no está claro qué usos están activos.

Nota: La función de la señal de atenuación es informar al sistema de audio del automóvil sobre los cambios de atenuación. No se imponen detalles específicos de las rampa de atenuación ni el comportamiento de atenuación real en presencia de sonidos de audio generados debajo del automóvil (presumiblemente por los componentes del otro automóvil). En el caso de los sonidos de seguridad, te recomendamos que los sonidos del sistema de audio del automóvil tengan una prioridad más alta. Por lo tanto, la atenuación debe usarse como una recomendación y no como una regla. La indicación de atenuación de audio, junto con la solicitud de enfoque de audio del HAL, genera una buena señal, que incluye los sonidos que los sistemas de un automóvil generan debajo del HAL.

HAL de control de audio de AIDL 2.0

Para actualizar las APIs y facilitar nuevas funciones, el HAL de control de audio AIDL se actualizó a la versión 2.0 en Android 13:

• Foco de audio con PlaybackTrackMetadata
• Devolución de llamada de ganancias de audio

Los metadatos de reproducción se definen en android.hardware.audio.common de la siguiente manera:

parcelable PlaybackTrackMetadata {
       AudioUsage usage = INVALID;
       AudioContentType contentType = UNKNOWN;
       float gain;
       AudioChannelLayout channelMask;
       AudioDevice sourceDevice;
       String[] tags;
}

Todas las demás funciones de la versión 1.0 del control de audio de AIDL se mantuvieron y se pueden usar. Una excepción se relaciona con el método de cambio de foco de audio, como se describe en On audio focus change method.

Enfoque del control de audio con metadatos de la pista de reproducción

Para exponer más información al sistema de audio debajo del HAL, las actualizaciones ahora exponen PlaybackTrackMetadata. Específicamente, la HAL de control de audio se expandió con un método nuevo:

interface IAudioControl {
       /**
       *   Notifies HAL of changes in audio focus status for focuses requested
       *   or abandoned by the HAL.
       *
       *   The HAL is not required to wait for a callback of AUDIOFOCUS_GAIN
       *   before playing audio, nor is it required to stop playing audio in the
       *   event of a AUDIOFOCUS_LOSS callback is received.
       *
       *   @param playbackMetaData The output stream metadata associated with
       *    the focus request
       *   @param zoneId The identifier for the audio zone that the HAL is
       *    playing the stream in
       *   @param focusChange the AudioFocusChange that has occurred.
       */
       oneway void onAudioFocusChangeWithMetaData(
       in PlaybackTrackMetadata playbackMetaData, in int zoneId,
       in AudioFocusChange focusChange);
}

Se realiza un cambio similar y correspondiente en IFocusListener:

       /**
       *   Called to indicate that the audio output stream associated with
       *   {@link android.hardware.audio.common.PlaybackTrackMetadata} is
       *   abandoning focus as playback has stopped.
       *
       *   @param playbackMetaData The output stream metadata associated with
       *    the focus request
       *   @param zoneId The identifier for the audio zone that the HAL
       *    abandoning focus
       */
       oneway void abandonAudioFocusWithMetaData(
       in PlaybackTrackMetadata playbackMetaData, in int zoneId);
       /**
       *   Called to indicate that the audio output stream associated with
       *   {@link android.hardware.audio.common.PlaybackTrackMetadata} has taken
       *   the focus as playback is starting for the corresponding stream.
       *
       *   @param playbackMetaData The output stream metadata associated with
       *    the focus request
       *   @param zoneId The identifier for the audio zone that the HAL
       *    abandoning focus
       *   @param focusGain The focus type requested.
       */
       oneway void requestAudioFocusWithMetaData(
       in PlaybackTrackMetadata playbackMetaData, in int zoneId,
       in AudioFocusChange focusGain);
}

Método de cambio de foco de audio

Las operaciones de enfoque anteriores se realizan de la misma manera que las que se describen en Solicitud de enfoque de audio desde HAL. Solo los metadatos de la pista de reproducción tienen más información junto con los usos de los atributos de audio. En general, a menos que se necesite la información adicional que proporcionan los metadatos de la pista de reproducción, el HAL de control de Android actualizado puede seguir usando los métodos anteriores.

Si los desarrolladores de HAL deciden no admitir IAudioControl#onAudioFocusChangeWithMetaData, el método debe mostrar resultados con el error UNKNOWN_TRANSACTION, como se describe en Cómo usar métodos de interfaz con versión.

El servicio de audio primero llama a onAudioFocusChangeWithMetaData y, luego, vuelve a intentarlo con el método onAudioFocusChange si se produce un error de UNKNOWN_TRANSACTION.

Atenuación del audio del automóvil con metadatos de la pista de reproducción

La versión 2.0 del HAL de control de audio AIDL agregó los metadatos de la pista de reproducción a la información de atenuación de audio:

parcelable DuckingInfo {
       /**
       *   ID of the associated audio zone
       */
       int zoneId;
       /**
       *   List of addresses for audio output devices that should be ducked.
       */
       String[] deviceAddressesToDuck;
       /**
       *   List of addresses for audio output devices that were previously be
       *   ducked and should now be unducked.
       */
       String[] deviceAddressesToUnduck;
       /**
       *   List of usages currently holding focus for this audio zone.
       */
       String[] usagesHoldingFocus;
       /**
       *   List of output stream metadata associated with the current focus
       *   holder for this audio zone
       */
       @nullable PlaybackTrackMetadata[] playbackMetaDataHoldingFocus;
}

usagesHoldingFocus ya no está disponible. Ahora, los desarrolladores deben usar playbackMetaDataHoldingFocus para determinar el uso del atributo de audio y otra información de audio. Dicho esto, el parámetro usagesHoldingFocus aún contiene la información requerida hasta que se quite formalmente esta opción.

Devolución de llamada de ganancia de audio

Para que los cambios de audio debajo de la HAL sean más visibles para el AAOS en Android 13, agregamos un mecanismo que puedes usar para comunicar los cambios de ganancia de audio del sistema de audio del automóvil al servicio de audio del automóvil. El mecanismo expone los cambios en el índice de volumen de ganancia de audio con un motivo correspondiente por el que se cambió la ganancia:

• Restricciones bloqueadas o silenciadas
• Limitaciones y restricciones
• Restricciones de atenuación

Estos cambios exponen estas restricciones desde debajo del HAL al servicio de audio para automóviles y, por último, a una app de IU del sistema para informar al usuario. La última parte, la exposición a una posible IU del sistema, se expandió aún más en Android 14 para permitir que las apps de la IU del sistema obtengan esta información con mayor facilidad a través de un mecanismo de devolución de llamada de información del grupo de volumen.

La API de HAL de control de audio registra la devolución de llamada de ganancia de la siguiente manera:

interface IAudioControl {
       /**
       *   Registers callback to be used by HAL for reporting unexpected gain(s)
       *    changed and the reason(s) why.
       *
       *   @param callback The {@link IAudioGainCallback}.
       */
       oneway void registerGainCallback(in IAudioGainCallback callback);
}

IAudioGainCallback se define de la siguiente manera:

interface IAudioGainCallback {
       /**
       *   Used to indicate that one or more audio device port gains have changed,
       *   i.e. initiated by HAL, not by CarAudioService.
       *   This is the counter part of the
       *   {@link onDevicesToDuckChange}, {@link onDevicesToMuteChange} and,
       *   {@link setAudioDeviceGainsChanged} APIs.
       *
       *   @param reasons List of reasons that triggered the given gains changed.
       *   @param gains List of gains affected by the change.
       */
       void onAudioDeviceGainsChanged(in Reasons[] reasons,
       in AudioGainConfigInfo[] gains);
}

Como se destaca en la documentación de la API, el servicio de audio del automóvil registra la devolución de llamada de ganancia en el HAL de control de audio. Cuando se llama a la API desde el HAL de control de audio, el servicio de audio para vehículos responde con una acción correspondiente (como bloquear, limitar o atenuar el índice de ganancia) .

El HAL determina cuándo se llama a la API, principalmente para informar cambios en el estado del índice de ganancia. En particular, en relación con los requisitos reglamentarios, el sistema de audio del automóvil debe realizar la acción requerida y usar la devolución de llamada para informar información al servicio de audio del automóvil y permitir el consumo del usuario. Por ejemplo, para mostrarle una IU al usuario.

HAL de control de audio AIDL 3.0

La versión de HAL de control de audio AIDL de Android 14 se actualiza a la versión 3.0 para actualizar las APIs y proporcionar una funcionalidad de índice de ganancia de audio más sólida. La API de HAL de control de audio permite que el servicio de audio establezca y desestablezca un IModuleChangeCallback:

interface IAudioControl {
       /**
       *   Sets callback with HAL for notifying changes to hardware module
       *   (that is: {@link android.hardware.audio.core.IModule}) configurations.
       *
       *   @param callback The {@link IModuleChangeCallback} interface to use
       *    use when new updates are available for
       */
       void setModuleChangeCallback(in IModuleChangeCallback callback);
       /**
       *   Clears module change callback
       */
       void clearModuleChangeCallback();
}

El servicio de audio para automóviles registra el setModuleChangeCallback cuando se inicia el servicio o cuando se recupera de un error. Por ejemplo, una notificación de error de Binder de HAL de control de audio que recibe el servicio de audio del automóvil. La implementación de HAL de control de audio debe reemplazar cualquier devolución de llamada de cambio de módulo existente cuando se llame a la API.

En el caso de la API de clearModuleChangeCallback, la implementación debe borrar la devolución de llamada existente o no hacer nada si no existe una. Se recomienda que la implementación del control de audio registre un observador de cierre para la devolución de llamada y, luego, borre la devolución de llamada si se activa el cierre de Binder.

IModuleChangeCallback se define de la siguiente manera:

oneway interface IModuleChangeCallback {
       /**
       *   Used to indicate that one or more {@link AudioPort} configs have
       *   changed. Implementations MUST return at least one AudioPort.
       *
       *   @param audioPorts list of {@link AudioPort} that are updated
       */
       void onAudioPortsChanged(in AudioPort[] audioPorts);
}

Cuando el servicio de audio del automóvil registra la devolución de llamada de cambio de módulo, está listo para recibir cambios de puerto de audio a través de la API de onAudioPortChanged. La API se puede usar para inicializar los aumentos de volumen del sistema de audio en cuanto se registra la devolución de llamada. Para otros cambios de ganancia dinámica, se puede llamar a la API en cualquier momento. Se aplican los cambios correspondientes y se actualiza el servicio de audio del automóvil según corresponda.