Controllo audio HAL

L'HAL di controllo audio è stato introdotto in Android 9 per supportare casi d'uso audio rilevanti per il settore automobilistico. A partire da Android 14, l'HAL di controllo audio supporta:

  • Dissolvenza ed equilibrio
  • Richiesta di focus audio HAL
  • Muting e ducking del dispositivo
  • Modifiche al guadagno del dispositivo audio
  • Modifiche alla configurazione della porta audio

La Figura 1 mostra una panoramica di alto livello dell'architettura del servizio audio per auto, in cui il servizio audio per auto comunica con l'HAL di controllo audio.

Configura l'audio multizona

Figura 1. Configurazione dell'audio multizona.

Dissolvenza e bilanciamento dell'audio

Controllo audio HIDL HAL versione 1 è stato introdotto in Android 9 per supportare la dissolvenza e il bilanciamento dell'audio nei casi di utilizzo automobilistico. Separato dagli effetti audio generici già forniti in Android, questo meccanismo consente alle app di sistema di impostare il bilanciamento dell'audio e la dissolvenza tramite le API 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 volta richiamate queste API, le rispettive API HAL di controllo audio vengono richiamate dal servizio audio dell'auto:

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);
}

L'API è disponibile su tutte le versioni dell'HAL di controllo audio, inclusa la nuova interfaccia AIDL HAL.

Richiesta di focus audio da HAL

AAOS, simile ad Android, si basa sulla partecipazione attiva delle app sul focus audio per gestire la riproduzione audio nelle auto. Le informazioni sul focus vengono utilizzate per gestire quali flussi controllare per volume e ducking. Pertanto, per espandere ulteriormente l'attenzione sull'audio e fornire una migliore integrazione dei suoni specifici dell'auto nell'esperienza Android, in Android 11 sono stati introdotti i seguenti attributi audio:

  • EMERGENCY
  • SAFETY
  • VEHICLE_STATUS
  • ANNOUNCEMENT

Oltre a questa modifica, è stato aggiunto un meccanismo per consentire ai suoni provenienti dall'esterno di Android di partecipare alle richieste di focus audio. Pertanto, è stato introdotto il controllo audio HIDL HAL versione 2 per consentire richieste di focus che provengono dall'esterno di 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);
}

Dove IFocusListener è definito come:

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);
}

Le API sopra riportate possono essere utilizzate rispettivamente per richiedere e abbandonare il focus audio dall'HAL. In risposta, il servizio audio dell'auto considera la richiesta di focus audio e inoltra i risultati in modo asincrono al metodo IAudioControl#onAudioFocusChange .

Questa API può essere utilizzata anche per monitorare le modifiche per la richiesta di focus audio che ha origine dall'HAL di controllo audio. In generale, qualsiasi richiesta di focus audio permanente dall'HAL è considerata attiva , il che differisce da una richiesta di focus audio da Android, in cui solo la riproduzione di una traccia audio attiva corrispondente è considerata attiva.

Migrare da HIDL a AIDL HAL di controllo audio

Con l'avvento di AIDL e la migrazione richiesta in Android 12 (per saperne di più, vedere AIDL per HAL ), l'HAL di controllo audio è stato migrato su AIDL. Per le API di controllo audio HIDL versione 2 esistenti, la migrazione ha richiesto aggiornamenti minori ai metodi esistenti:

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);
}

E il corrispondente IFocusListener :

       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);
}

Silenziamento del gruppo di volumi

Android 12 ha introdotto la disattivazione del gruppo di volume per consentire un controllo dell'audio più completo durante le interazioni audio dell'utente. Ciò consente all'HAL di controllo audio di ricevere eventi di silenziamento intercettati dal servizio audio dell'auto.

Per abilitare la funzione, gli OEM devono impostare la configurazione audioUseCarVolumeGroupMuting su true nel config.xml del servizio auto:

<!-- 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>

Prima di Android 13, la configurazione doveva essere sovrascritta con un overlay di risorse runtime per packages/services/Car/service/res/values/config.xml (per ulteriori informazioni, vedere Personalizzazione della build con overlay di risorse ). A partire da Android 13, puoi utilizzare gli overlay delle risorse di runtime per modificare un valore di configurazione. Per ulteriori informazioni, consulta Modificare il valore delle risorse di un'app in fase di esecuzione .

Le app di sistema possono determinare se la funzionalità è abilitata utilizzando l'API CarAudioManager#isAudioFeatureEnabled . Il parametro passato deve essere la costante CarAudioManager.AUDIO_FEATURE_VOLUME_GROUP_MUTING . Il metodo restituisce true se la funzionalità è abilitata sul dispositivo, altrimenti false .

Oltre ad abilitare la funzionalità audioUseCarVolumeGroupMuting , l'HAL di controllo audio AIDL deve implementare il meccanismo di silenziamento del gruppo di volumi:

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);
}

Dove le informazioni sulla disattivazione dell'audio contengono le informazioni pertinenti sulla disattivazione dell'audio per il sistema 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;
}

AAOS dispone di due diversi meccanismi di muting, basati su:

  • Eventi chiave utilizzando l'audio KEYCODE_VOLUME_MUTE {:.external}.

  • Chiamate dirette al servizio audio dell'auto utilizzando l'API di disattivazione dell'audio del gestore audio dell'auto, CarAudioManager#setVolumeGroupMute .

Quando abilitati, entrambi i meccanismi attivano la disattivazione della chiamata all'HAL di controllo audio.

Ducking dell'audio dell'auto

Android 12 ha introdotto il ducking dell'audio per auto per ottimizzare il controllo della riproduzione simultanea di flussi audio. Ciò consente agli OEM di implementare il proprio comportamento di ducking in base alla configurazione audio fisica dell'auto e allo stato di riproduzione corrente, come determinato dal servizio audio dell'auto.

Il meccanismo di ducking si basa sulle modifiche dello stack di focus audio. Ogni volta che si verifica un cambio di focus (che si tratti di una richiesta di focus o di un abbandono del focus), l'HAL di controllo audio viene informato. Similmente al supporto per il silenziamento del gruppo di volumi dell'auto, il ducking dell'audio dell'auto può essere abilitato con il flag di configurazione 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>

Per abilitare la funzionalità, l'HAL di controllo audio AIDL deve implementare la logica pertinente con il segnale ricevuto dal servizio audio dell'auto:

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);
}

Le informazioni rilevanti sul sistema audio sono contenute nelle informazioni sul ducking 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;
}

Oltre alle informazioni sulla configurazione dell'audio dell'auto contenute negli indirizzi del dispositivo da (non)duck, le informazioni sul ducking contengono anche informazioni su quali utilizzi degli attributi audio sono focalizzati. Lo scopo di questi dati è quello di informare il sistema audio su quali utilizzi degli attributi audio sono attivi.

Ciò è necessario poiché, nella configurazione dell'audio dell'auto, è possibile assegnare più attributi audio a un singolo dispositivo e, senza le informazioni aggiuntive, non è chiaro quali utilizzi siano attivi.

Controllo audio AIDL HAL 2.0

Per aggiornare le API e facilitare nuove funzionalità, l'HAL di controllo audio AIDL è stato aggiornato alla versione 2.0 in Android 13:

  • Messa a fuoco audio con PlaybackTrackMetadata
  • L'audio ottiene la richiamata

I metadati di riproduzione sono definiti in android.hardware.audio.common come segue:

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

Tutte le altre funzionalità del controllo audio AIDL versione 1.0 sono rimaste e possono essere utilizzate. Un'eccezione riguarda il metodo di modifica del focus audio, come descritto in Sul metodo di modifica del focus audio .

Focus sul controllo audio con metadati della traccia di riproduzione

Per esporre più informazioni al sistema audio sotto l'HAL, gli aggiornamenti ora espongono PlaybackTrackMetadata . Nello specifico l'HAL del controllo audio è stato ampliato con una nuova modalità:

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);
}

Una modifica simile, corrispondente, viene apportata a 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);
}

Sul metodo di modifica del focus audio

Le operazioni di focus sopra riportate vengono eseguite allo stesso modo di quelle descritte in Richiesta di focus audio da HAL . Solo i metadati della traccia di riproduzione contengono più informazioni insieme agli utilizzi degli attributi audio. In generale, a meno che non siano necessarie informazioni aggiuntive fornite dai metadati della traccia di riproduzione, l'HAL di controllo Android aggiornato può continuare a utilizzare i metodi precedenti.

Se gli sviluppatori HAL decidono di non supportare IAudioControl#onAudioFocusChangeWithMetaData , il metodo dovrebbe restituire risultati con l'errore UNKNOWN_TRANSACTION come descritto Using Versioned Interface Methods .

Il servizio audio chiama prima onAudioFocusChangeWithMetaData e poi riprova con il metodo onAudioFocusChange se si verifica un errore UNKNOWN_TRANSACTION .

Ducking audio per auto con metadati della traccia di riproduzione

La versione 2.0 dell'HAL di controllo audio AIDL ha aggiunto i metadati della traccia di riproduzione alle informazioni sul ducking 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 è deprecato. Gli sviluppatori dovrebbero ora utilizzare playbackMetaDataHoldingFocus per determinare l'utilizzo degli attributi audio e altre informazioni sull'audio. Detto questo, il parametro usagesHoldingFocus contiene ancora le informazioni richieste finché questa opzione non verrà formalmente rimossa.

Richiamata del guadagno audio

Per rendere le modifiche audio sotto l'HAL più visibili all'AAOS in Android 13, abbiamo aggiunto un meccanismo che puoi utilizzare per comunicare le modifiche ai guadagni audio dal sistema audio dell'auto al servizio audio dell'auto. Il meccanismo espone le modifiche dell'indice del volume del guadagno audio con il rispettivo motivo per cui il guadagno è stato modificato:

  • Restrizioni bloccate o disattivate
  • Limitazioni restrizioni
  • Restrizioni di attenuazione

Queste modifiche espongono queste restrizioni dal livello inferiore dell'HAL al servizio audio dell'auto e, infine, a un'app dell'interfaccia utente del sistema per informare l'utente. L'ultima parte, l'esposizione a una possibile interfaccia utente di sistema, è stata ulteriormente ampliata in Android 14 per consentire alle app dell'interfaccia utente di sistema di ottenere più facilmente queste informazioni attraverso un meccanismo di callback delle informazioni sul gruppo di volumi.

L'API HAL del controllo audio registra il callback del guadagno come segue:

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 è definito come segue:

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);
}

Come evidenziato nella documentazione API, la richiamata del guadagno viene registrata dal servizio audio dell'auto all'HAL di controllo audio. Quando l'API viene richiamata dall'HAL di controllo audio, il servizio audio dell'auto risponde con un'azione corrispondente (come bloccare, limitare o attenuare l'indice di guadagno).

L'HAL determina quando viene richiamata l'API, principalmente per segnalare le modifiche allo stato dell'indice di guadagno. In conformità ai requisiti normativi, il sistema audio dell'auto dovrebbe intraprendere l'azione richiesta e utilizzare la richiamata per segnalare informazioni al servizio audio dell'auto per consentire il consumo da parte dell'utente. Ad esempio, per mostrare un'interfaccia utente all'utente.

Controllo audio AIDL HAL 3.0

La versione HAL del controllo audio Android 14 AIDL è stata aggiornata alla versione 3.0 per aggiornare le API e fornire funzionalità di indice di guadagno audio più robuste. L'API HAL di controllo audio consente al servizio audio di impostare e annullare l'impostazione di 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();
}

Il setModuleChangeCallback viene registrato dal servizio audio dell'auto all'avvio del servizio o durante il ripristino da un errore. Ad esempio, una notifica di morte del raccoglitore HAL di controllo audio ricevuta dal servizio audio dell'auto. L'implementazione dell'HAL del controllo audio dovrebbe sostituire qualsiasi callback di modifica del modulo esistente quando viene richiamata l'API.

Per l'API clearModuleChangeCallback , l'implementazione dovrebbe cancellare il callback esistente o non fare nulla se non ne esiste uno. È buona norma per l'implementazione del controllo audio registrare un osservatore della morte per la richiamata e quindi cancellare la richiamata se viene attivata la morte del raccoglitore.

IModuleChangeCallback è definito come segue:

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);
}

Quando la richiamata di modifica del modulo viene registrata dal servizio audio dell'auto, è pronta a ricevere le modifiche alla porta audio tramite l'API onAudioPortChanged . L'API può essere utilizzata per inizializzare i guadagni di volume per il sistema audio non appena viene registrata la richiamata. Per altre modifiche al guadagno dinamico, l'API può essere richiamata in qualsiasi momento. Vengono applicate le modifiche corrispondenti e il servizio audio dell'auto viene aggiornato di conseguenza.