Commandes audio HAL

Les commandes audio HAL ont été introduites dans Android 9 pour prendre en charge les cas d'utilisation audio dans le secteur automobile. À partir d'Android 14. La commande HAL des commandes audio est compatible avec:

• Fondu et équilibre
• Requête de ciblage audio HAL
• Désactivation et diminution du son de l'appareil
• Modifications du gain de l'appareil audio
• Modifications de la configuration du port audio

La figure 1 présente une vue d'ensemble de l'architecture d'un service audio pour voiture, en que le service audio de la voiture communique avec la commande audio HAL.

Figure 1 : Configurez l'audio multizone.

Fondu et équilibre audio

La version 1 de HAL des commandes audio HIDL a été introduite dans Android 9 pour prendre en charge les fondus et l'équilibre audio en voiture cas d'utilisation. Outre les effets audio génériques déjà fournis sur Android, cette mécanisme permettant aux applications système de régler la balance audio et de faire un fondu 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);
}

Une fois ces API appelées, les API HAL de contrôle audio respectives sont appelées depuis le service audio de la voiture:

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 est disponible dans toutes les versions de la commande audio HAL, y compris la nouvelle Interface HAL AIDL.

Requête de focus audio de HAL

AAOS, comme Android, repose sur la participation active des applications sur l'audio. gérer la lecture audio dans les voitures. Les informations sur l'accent sont utilisées pour gérer qui permet de contrôler le volume et la diminution du volume. Par conséquent, pour développer davantage l'accent sur l'audio et pour assurer une meilleure intégration des sons propres à la voiture dans l'expérience Android, les attributs audio suivants ont été introduits dans Android 11:

• EMERGENCY
• SAFETY
• VEHICLE_STATUS
• ANNOUNCEMENT

Par ailleurs, nous avons ajouté un mécanisme pour les sons provenant en dehors d'Android pour participer aux demandes de ciblage audio. Ainsi, l'audio HIDL de contrôle HAL version 2 a été introduit pour permettre les requêtes de focus qui proviennent en dehors d'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);
}

Où IFocusListener est défini comme suit:

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

Les API ci-dessus peuvent être utilisées pour demander et abandonner la priorité audio à partir du HAL, respectivement. En réponse, le service audio de la voiture considère et transmet les résultats de manière asynchrone au IAudioControl#onAudioFocusChange.

Cette API peut également servir à surveiller les modifications apportées à la requête de priorité audio provient du HAL de commande audio. En général, toute mise au point audio debout de la requête HAL est considérée comme active, ce qui diffère de la priorité audio requête Android, pour laquelle seule la lecture d'une piste audio active correspondante est considérée comme active.

Migrer HIDL vers le HAL des commandes audio AIDL

Avec l'avènement d'AIDL et la migration requise dans Android 12 (pour en savoir plus, voir AIDL pour HAL), la commande audio HAL était migrés vers AIDL. Pour les API HIDL Audio Control version 2 existantes, la migration a nécessité des mises à jour mineures des méthodes existantes:

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

Et le IFocusListener correspondant:

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

Remarque :Les modifications apportées aux API existantes sont principalement syntaxiques en raison des différences entre AIDL et HIDL. Comportement et réponse réels dans le service audio de la voiture entre HIDL et AIDL sont identiques. À moins que des fonctionnalités plus récentes ne soient nécessaires, les OEM peuvent continuer à utiliser la version 2 de la commande audio HAL. Pour les fonctionnalités plus récentes la migration vers AIDL, consultez la section suivante.

Couper le son du groupe de volumes

Android 12 a introduit la coupure du son des groupes de volumes pour permettre une commande de coupure du son plus complète pendant les interactions audio de l'utilisateur. Ce permet au HAL de commande audio de recevoir les événements de coupure du son tels qu'ils ont été interceptés par la voiture service audio.

Pour activer cette fonctionnalité, les OEM doivent définir la configuration audioUseCarVolumeGroupMuting à true dans le service automobile 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>

Avant Android 13, la configuration devait être écrasée avec une superposition de ressources d'exécution packages/services/Car/service/res/values/config.xml (pour en savoir plus, consultez Personnaliser la compilation à l'aide d'une ressource superpositions). Depuis Android 13, vous pouvez utiliser les superpositions de ressources d'exécution pour modifier la valeur de configuration. Pour en savoir plus, consultez la section Modifier la valeur des ressources d'une application. lors de l'exécution.

Les applications système peuvent déterminer si la fonctionnalité est activée à l'aide des API CarAudioManager#isAudioFeatureEnabled. Le paramètre transmis doit être Constante CarAudioManager.AUDIO_FEATURE_VOLUME_GROUP_MUTING. La méthode renvoie true si la fonctionnalité est activée sur l'appareil, sinon false.

En plus d'activer la fonctionnalité audioUseCarVolumeGroupMuting, AIDL Le système HAL de commande audio doit implémenter le mécanisme de coupure du son du groupe de volumes:

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

Lorsque les informations de coupure du son contiennent les informations pertinentes pour la coupure du son du système 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;
}

Remarque :Les informations transmises sont basées sur la configuration de chaque groupe de volumes, défini dans car_audio_configuration.xml. Plus précisément, pour chaque adresse d'appareil défini pour la configuration du groupe de volumes audio de la voiture.

AAOS dispose de deux mécanismes de masquage différents, basés sur les éléments suivants:

• Événements clés utilisant l'audio KEYCODE_VOLUME_MUTE :

• Appels directs au service audio de la voiture à l'aide de l'API de coupure du son de Car Audio Manager CarAudioManager#setVolumeGroupMute

Lorsqu'ils sont activés, les deux mécanismes déclenchent une coupure du son des appels dans l'HAL de la commande audio.

Atténuation audio de la voiture

Android 12 a introduit l'atténuation du volume de l'audio de la voiture pour optimiser le contrôle des simultanés la lecture de flux audio. Cela permet aux OEM d'implémenter leur propre atténuation comportement basé sur la configuration audio physique de la voiture et sur la lecture actuelle tel que déterminé par le service audio de la voiture.

Le mécanisme d'atténuation est basé sur les modifications de la pile de focus audio. Chaque fois qu'un (qu'il s'agisse d'une requête ou d'un abandon de focus), l'audio le contrôle HAL est informé. Semblable à la fonctionnalité de coupure du son des groupes de volumes de la voiture, La diminution de l'audio peut être activée avec l'indicateur de configuration 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>

Pour activer cette fonctionnalité, le HAL de commande audio AIDL doit implémenter la avec le signal reçu du service audio de la voiture:

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

Les informations pertinentes du système audio sont contenues dans la fonctionnalité d'atténuation du son. informations:

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

Hormis les informations de configuration audio du véhicule contenues dans les adresses des appareils à (un)duck, les informations d'atténuation contiennent également des informations sur le type de contenu audio des attributs sont ciblés. Ces données ont pour but de renseigner d'un système audio dont les utilisations des attributs audio sont actives.

Cette étape est obligatoire, car dans la configuration audio de la voiture, plusieurs peuvent être attribués à un seul appareil et, il est difficile de savoir quelles utilisations sont actives.

Remarque :Le signal d'atténuation sert à informer le système audio de la voiture. sur l'atténuation des modifications. Détails spécifiques à l'atténuation des rampes ou de la diminution réelle en présence de sons sonores générés sous la voiture (probablement par composants de l'autre voiture) ne sont pas imposés. Pour les sons de sécurité, nous vous recommandons que les sons du système audio d'une voiture ont une priorité plus élevée. Par conséquent, la diminution doivent être utilisés comme des recommandations et non comme des règles. Le signal d'atténuation audio, associé à la requête de focus audio du HAL, génère un bon signal, qui comprend les sons générés sous le HAL par les systèmes d'une voiture.

Commandes audio AIDL HAL 2.0

Pour mettre à jour les API et proposer de nouvelles fonctionnalités, le HAL des commandes audio AIDL a été mis à jour vers la version 2.0 sous Android 13:

• Priorité audio avec PlaybackTrackMetadata
• Rappel des gains audio

Les métadonnées de lecture sont définies dans android.hardware.audio.common comme suit:

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

Toutes les autres fonctionnalités de la version 1.0 du contrôle audio AIDL sont restées et peuvent être utilisé. Une exception concerne la méthode de changement de focus audio, En cas de méthode de changement de focus audio :

Priorité aux commandes audio avec les métadonnées de la piste de lecture

Pour fournir plus d'informations au système audio sous le HAL, les mises à jour exposent désormais PlaybackTrackMetadata Plus précisément, la commande audio HAL a été enrichie d'une nouvelle méthode:

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

Une modification similaire est apportée à 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);
}

Lors de la méthode de changement de focus audio

Les opérations de sélection ci-dessus fonctionnent de la même manière que celles décrites dans la section requête de focus HAL. Seules les métadonnées de la piste de lecture ainsi que les utilisations des attributs audio. En général, à moins que les caractères les informations fournies par les métadonnées des pistes de lecture sont nécessaires, l'application Android le contrôle HAL peut continuer à utiliser les méthodes précédentes.

Si les développeurs HAL décident de ne pas IAudioControl#onAudioFocusChangeWithMetaData : la méthode doit renvoyer des résultats. avec l'erreur UNKNOWN_TRANSACTION, comme décrit dans la section Utilisation d'une interface avec gestion des versions Méthodes.

Le service audio appelle d'abord onAudioFocusChangeWithMetaData, puis puis effectue une nouvelle tentative avec la méthode onAudioFocusChange si une UNKNOWN_TRANSACTION d'échecs.

Diminution du volume du son de la voiture avec les métadonnées du titre de lecture

La version 2.0 de la commande audio AIDL HAL a ajouté les métadonnées de la piste de lecture à les informations de diminution du volume:

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

Abandon de usagesHoldingFocus. Les développeurs doivent maintenant utiliser playbackMetaDataHoldingFocus pour déterminer l'utilisation de l'attribut audio et d'autres des informations audio. Cela dit, le paramètre usagesHoldingFocus contient toujours les informations requises jusqu'à ce que cette option soit officiellement supprimée.

Rappel de gain audio

Pour améliorer la visibilité des modifications audio sous le HAL pour l'AAOS sur Android 13, nous avons ajouté un mécanisme que vous pouvez utiliser pour communiquer l'audio obtient les changements du système audio de la voiture vers le service audio de la voiture. La expose les modifications de l'index de volume de gain audio avec un motif respectif le gain a été modifié:

• Restrictions bloquées ou ignorées
• Restrictions liées aux limitations
• Restrictions d'atténuation

Ces modifications exposent ces restrictions du niveau inférieur au HAL au un service audio pour voiture et, enfin, à une application d'UI du système pour informer l'utilisateur. La dernière partie, l'exposition à une interface utilisateur système, a été élargie dans Android 14 permet aux applications d'UI du système d'obtenir plus facilement ces informations via un mécanisme de rappel des informations de groupe de volumes.

L'API HAL de commande audio enregistre le rappel de gain comme suit:

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

Le IAudioGainCallback est défini comme suit:

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

Comme indiqué dans la documentation de l'API, le rappel de gain est enregistré par l'API service audio pour voiture au HAL de commande audio. Lorsque l'API est appelée depuis la de commande audio HAL, le service audio de la voiture répond avec l'action correspondante (par exemple, bloquer, limiter ou atténuer l'indice de gain) .

Le HAL détermine quand l'API est appelée, principalement pour signaler les modifications apportées au l'état de l'index. Système audio de la voiture spécifique aux exigences réglementaires doit effectuer l'action requise et utiliser le rappel pour transmettre les informations à le service audio de la voiture pour permettre la consommation par les utilisateurs. Par exemple, pour afficher une UI pour l'utilisateur.

Commandes audio AIDL HAL 3.0

La version HAL des commandes audio AIDL d'Android 14 est mis à jour vers la version 3.0 pour mettre à jour les API et fournir un gain audio plus puissant. la fonctionnalité d'index. L'API HAL de commande audio permet au service audio définissez et annulez la définition d'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();
}

Le setModuleChangeCallback est enregistré par le service audio de la voiture lorsque le démarre le service ou lors d'une récupération à la suite d'une erreur. Par exemple, une commande audio Notification de décès de la liaison HAL reçue par le service audio de la voiture. Audio l'implémentation du contrôle HAL doit remplacer tout rappel de modification de module existant lorsque l'API est appelée.

Pour l'API clearModuleChangeCallback, l'implémentation doit effacer le rappel existant ou ne rien faire s'il n'en existe pas. C’est une bonne pratique pour l'implémentation de la commande audio pour enregistrer un observateur de la mort pour le rappel ; puis d'effacer le rappel si l'arrêt de la liaison est déclenché.

IModuleChangeCallback est défini comme suit:

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

Lorsque le rappel de changement de module est enregistré par le service audio de la voiture, il est prêt à recevoir les modifications du port audio via l'API onAudioPortChanged. La L'API peut être utilisée pour initialiser les gains de volume pour le système audio dès que est enregistré. Pour les autres modifications de gain dynamique, l'API peut être appelée à tout moment. Les modifications correspondantes sont appliquées et le service audio de la voiture est mis à jour. en conséquence.