HAL de controle de áudio

A HAL de controle de áudio foi introduzida no Android 9 para oferecer suporte a casos de uso de áudio relevantes para o setor automotivo. A partir do Android 14, a HAL de controle de áudio oferece suporte a:

• Desvanecimento e equilíbrio
• Solicitação de seleção de áudio HAL
• Silenciamento e redução de volume do dispositivo
• Mudanças no ganho do dispositivo de áudio
• Mudanças na configuração da porta de áudio

A Figura 1 mostra uma visão geral de alto nível da arquitetura do serviço de áudio do carro, em que o serviço de áudio do carro se comunica com o HAL de controle de áudio.

Figura 1. Configurar o áudio de várias zonas.

Esmaecer e equilibrar áudio

A versão 1 da HAL de controle de áudio HIDL foi introduzida no Android 9 para oferecer suporte ao fade e ao equilíbrio de áudio em casos de uso automotivo. Separado dos efeitos de áudio genéricos já fornecidos no Android, esse mecanismo permite que os apps do sistema definam o equilíbrio do áudio e o desbotamento nas APIs 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);
}

Depois que essas APIs são chamadas, as respectivas APIs HAL de controle de áudio são chamadas do serviço de áudio do carro:

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

A API está disponível em todas as versões do HAL de controle de áudio, incluindo a nova interface HAL do AIDL.

Solicitação de seleção de áudio da HAL

O AAOS, assim como o Android, depende da participação ativa de apps no foco de áudio para gerenciar a reprodução de áudio em carros. As informações de foco são usadas para gerenciar quais fluxos controlar para volume e muting. Para ampliar ainda mais o foco no áudio e oferecer uma melhor integração de sons específicos do carro à experiência do Android, os seguintes atributos de áudio foram introduzidos no Android 11:

• EMERGENCY
• SAFETY
• VEHICLE_STATUS
• ANNOUNCEMENT

Além dessa mudança, um mecanismo foi adicionado para que sons originados fora do Android participem de solicitações de foco de áudio. Assim, a versão 2 da HAL de controle de áudio HIDL foi introduzida para permitir solicitações de foco originadas fora do 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);
}

Em que IFocusListener é definido como:

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

As APIs acima podem ser usadas para solicitar e abandonar o foco de áudio do HAL, respectivamente. Em resposta, o serviço de áudio do carro considera a solicitação de foco de áudio e encaminha os resultados de forma assíncrona para o método IAudioControl#onAudioFocusChange.

Essa API também pode ser usada para monitorar mudanças na solicitação de foco de áudio que origina do HAL de controle de áudio. Em geral, qualquer solicitação de foco de áudio do HAL é considerada ativa, o que é diferente de uma solicitação de foco de áudio do Android, em que apenas uma reprodução de faixa de áudio ativa correspondente é considerada ativa.

Migrar a HAL de controle de áudio de HIDL para AIDL

Com o advento da AIDL e a migração necessária no Android 12 (para saber mais, consulte AIDL para HALs), a HAL de controle de áudio foi migrada para a AIDL. Para as APIs de controle de áudio HIDL versão 2, a migração exigiu pequenas atualizações nos métodos atuais:

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 o IFocusListener correspondente:

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

Observação: as mudanças nas APIs atuais são em grande parte sintáticas devido às diferenças entre AIDL e HIDL. O comportamento e a resposta reais no serviço de áudio do carro entre HIDL e AIDL são os mesmos. Portanto, a menos que recursos mais recentes sejam necessários, os OEMs podem continuar usando a versão 2 do HAL de controle de áudio. Para conferir os recursos mais recentes introduzidos com a migração da AIDL, consulte a próxima seção.

Desativação do som do grupo de volumes

O Android 12 introduziu o silenciamento de grupo de volume para permitir um controle de silenciamento mais abrangente durante as interações de áudio do usuário. Isso permite que o HAL de controle de áudio receba eventos de silenciamento interceptados pelo serviço de áudio do carro.

Para ativar o recurso, os OEMs precisam definir a configuração audioUseCarVolumeGroupMuting como true no serviço de carro 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 do Android 13, a configuração precisava ser substituída por uma sobreposição de recurso de execução para packages/services/Car/service/res/values/config.xml. Para saber mais, consulte Como personalizar o build com sobreposições de recursos. No Android 13, é possível usar sobreposições de recursos de execução para mudar um valor de configuração. Para saber mais, consulte Mudar o valor dos recursos de um app no momento da execução.

Os apps do sistema podem determinar se o recurso está ativado usando a API CarAudioManager#isAudioFeatureEnabled. O parâmetro transmitido precisa ser a constante CarAudioManager.AUDIO_FEATURE_VOLUME_GROUP_MUTING. O método retorna true se o recurso estiver ativado no dispositivo. Caso contrário, ele retornará false.

Além de ativar o recurso audioUseCarVolumeGroupMuting, o HAL de controle de áudio AIDL precisa implementar o mecanismo de silenciamento do grupo de volume:

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

Onde as informações de desativação do som contêm as informações pertinentes para o sistema de áudio:

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

Observação: as informações transmitidas são baseadas na configuração de cada grupo de volume, conforme definido em car_audio_configuration.xml. Especificamente, para cada endereço de dispositivo definido para a configuração do grupo de volume de áudio do carro.

O AAOS tem dois mecanismos diferentes para silenciar, com base em:

• Eventos principais usando o áudio KEYCODE_VOLUME_MUTE.

• Chamadas diretas para o serviço de áudio do carro usando a API de silenciamento do gerenciador de áudio do carro, CarAudioManager#setVolumeGroupMute.

Quando ativado, ambos os mecanismos acionam o silenciamento de uma chamada para o HAL de controle de áudio.

Redução de áudio do carro

O Android 12 introduziu o recurso de redução de áudio do carro para otimizar o controle da reprodução simultânea de streams de áudio. Isso permite que os OEMs implementem o próprio comportamento de redução com base na configuração de áudio físico de um carro e no estado de reprodução atual, conforme determinado pelo serviço de áudio do carro.

O mecanismo de redução de volume é baseado nas mudanças da pilha de foco de áudio. Sempre que uma mudança de foco ocorre (seja uma solicitação de foco ou de abandono de foco), o HAL de controle de áudio é informado. Assim como o suporte ao silenciamento do grupo de volume do carro, o ducking de áudio do carro pode ser ativado com a flag de configuração 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 ativar o recurso, a HAL de controle de áudio AIDL precisa implementar a lógica relevante com o sinal recebido do serviço de áudio do carro:

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

As informações relevantes do sistema de áudio estão contidas nas informações de abatimento de áudio:

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

Além das informações de configuração de áudio do carro contidas nos endereços do dispositivo para (des)ativar, as informações de redução de som também contêm informações sobre quais usos de atributo de áudio estão segurando o foco. O objetivo desses dados é informar ao sistema de áudio quais usos de atributos de áudio estão ativos.

Isso é necessário porque, na configuração de áudio do carro, vários atributos de áudio podem ser atribuídos a um único dispositivo e, sem as informações extras, não fica claro quais usos estão ativos.

Observação: o sinal de redução de volume tem a função de informar o sistema de áudio do carro sobre mudanças de redução de volume. Detalhes específicos de rampas de redução ou comportamento de redução real na presença de sons de áudio gerados abaixo do carro (provavelmente pelos componentes do outro carro) não são impostos. Para sons de segurança, recomendamos que os sons do sistema de áudio de um carro tenham prioridade. Portanto, o ocultamento deve ser usado como uma recomendação, e não como uma regra. A sugestão de redução de áudio, combinada com a solicitação de foco de áudio do HAL, gera um bom sinal, que inclui sons gerados abaixo do HAL pelos sistemas de um carro.

HAL 2.0 de controle de áudio AIDL

Para atualizar APIs e facilitar novas funcionalidades, o HAL de controle de áudio AIDL foi atualizado para a versão 2.0 no Android 13:

• Seleção de áudio com PlaybackTrackMetadata
• Callback de ganhos de áudio

Os metadados de reprodução são definidos em android.hardware.audio.common da seguinte maneira:

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

Todas as outras funcionalidades da versão 1.0 do controle de áudio AIDL foram mantidas e podem ser usadas. Uma exceção pertence ao método de mudança de foco de áudio, conforme descrito em No método de mudança de foco de áudio.

Foco do controle de áudio com metadados da faixa de reprodução

Para expor mais informações ao sistema de áudio abaixo do HAL, as atualizações agora expõem PlaybackTrackMetadata. Especificamente, a HAL de controle de áudio foi expandida com um novo método:

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

Uma mudança semelhante e correspondente é feita em 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);
}

No método de mudança de seleção de áudio

As operações de foco acima funcionam da mesma maneira que as descritas em Solicitação de foco de áudio do HAL. Apenas os metadados da faixa de reprodução têm mais informações, além dos usos dos atributos de áudio. Em geral, a menos que as informações extras fornecidas pelos metadados da faixa de reprodução sejam necessárias, o HAL de controle do Android atualizado pode continuar usando métodos anteriores.

Se os desenvolvedores do HAL decidirem não oferecer suporte a IAudioControl#onAudioFocusChangeWithMetaData, o método precisará retornar resultados com o erro UNKNOWN_TRANSACTION, conforme descrito em Usar métodos de interface versãoada.

O serviço de áudio primeiro chama onAudioFocusChangeWithMetaData e depois tenta novamente com o método onAudioFocusChange se uma falha UNKNOWN_TRANSACTION ocorrer.

O áudio do carro é silenciado com metadados da faixa de reprodução

A versão 2.0 da HAL de controle de áudio da AIDL adicionou os metadados da faixa de reprodução às informações de abatimento de áudio:

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

O uso de usagesHoldingFocus foi descontinuado. Os desenvolvedores agora precisam usar playbackMetaDataHoldingFocus para determinar o uso do atributo de áudio e outras informações de áudio. No entanto, o parâmetro usagesHoldingFocus ainda contém as informações necessárias até que essa opção seja formalmente removida.

Callback de ganho de áudio

Para tornar as mudanças de áudio abaixo da HAL mais visíveis para o AAOS no Android 13, adicionamos um mecanismo que pode ser usado para comunicar as mudanças de ganho de áudio do sistema de áudio do carro para o serviço de áudio do carro. O mecanismo expõe mudanças no índice de ganho de volume de áudio com um motivo respectivo:

• Restrições bloqueadas ou silenciadas
• Limitações
• Restrições de atenuação

Essas mudanças expõem essas restrições abaixo do HAL ao serviço de áudio do carro e, por fim, a um app de interface do sistema para informar o usuário. A parte mais recente, a exposição a uma possível interface do sistema, foi expandida no Android 14 para permitir que os apps da interface do sistema recebam essas informações com mais facilidade por um mecanismo de callback de informações do grupo de volume.

A API HAL de controle de áudio registra o callback de ganho da seguinte maneira:

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

O IAudioGainCallback é definido da seguinte maneira:

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

Conforme destacado na documentação da API, o callback de ganho é registrado pelo serviço de áudio do carro para o HAL de controle de áudio. Quando a API é chamada pelo HAL de controle de áudio, o serviço de áudio do carro responde com uma ação correspondente (como bloquear, limitar ou atenuar o índice de ganho) .

O HAL determina quando a API é chamada, principalmente para informar mudanças no status do índice de ganho. Específico para os requisitos de regulamentação, o sistema de áudio do carro precisa realizar a ação necessária e usar o callback para informar informações ao serviço de áudio do carro para permitir o consumo do usuário. Por exemplo, para mostrar uma interface ao usuário.

HAL 3.0 de controle de áudio AIDL

A versão HAL de controle de áudio AIDL do Android 14 foi atualizada para a versão 3.0 para oferecer APIs mais robustas que oferecem uma funcionalidade de índice de ganho de áudio mais robusta. A API HAL de controle de áudio permite que o serviço de áudio defina e remova um 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();
}

O setModuleChangeCallback é registrado pelo serviço de áudio do carro quando o serviço é iniciado ou quando se recupera de um erro. Por exemplo, uma notificação de morte de vinculação de HAL de controle de áudio recebida pelo serviço de áudio do carro. A implementação do HAL de controle de áudio precisa substituir qualquer callback de mudança de módulo quando a API for chamada.

Para a API clearModuleChangeCallback, a implementação precisa limpar o callback atual ou não fazer nada se ele não existir. É uma prática recomendada que a implementação de controle de áudio registre um observador de interrupção para o callback e limpe o callback se a interrupção no binder for acionada.

IModuleChangeCallback é definido da seguinte maneira:

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 o callback de mudança de módulo é registrado pelo serviço de áudio do carro, ele fica pronto para receber mudanças de porta de áudio pela API onAudioPortChanged. A API pode ser usada para inicializar ganhos de volume para o sistema de áudio assim que o callback for registrado. Para outras mudanças de ganho dinâmico, a API pode ser chamada a qualquer momento. As mudanças correspondentes são aplicadas, e o serviço de áudio do carro é atualizado conforme necessário.