可配置的音频政策引擎

在 Android 14 中，Android Automotive 操作系统 (AAOS) 利用可配置音频政策 (CAP) 引擎在主音频区内进行车载音频管理。具体而言，CAP 引擎允许 AAOS 仅控制音频路由、仅控制音频音量，或同时控制路由和音量。以下标志可用于控制行为：

• 使用 useCoreAudioVolume 标志启用 CAP 音量管理。当此值为 true 时，车载音频服务会使用音频管理器 API 来管理音量组。

• 使用 useCoreAudioRouting 标志启用 CAP 音频路由管理。 当此值为 true 时，车载音频服务会使用可配置音频政策路由来管理音频路由。

音频政策引擎在 Android 中也默认受支持，形式为 the 默认音频政策引擎。

背景

CAP 引擎基于 Intel 的 参数框架， 该框架基于插件和规则，用于处理各种参数。 对于 Android 音频管理，CAP 引擎引入了定义 XML 文件规则的功能，以指定以下内容：

• 音频产品策略
• 音频输出设备选择规则
• 音频输入设备选择规则
• 用于管理音量和静音以及音量表的规则

Android 16 之前的 CAP 初始化

下图简要概述了截至 Android 6 的可配置音频政策引擎配置管理：

图 1. 截至 Android 6 的 CAP 引擎配置管理。

如图所示，CAP 引擎配置由 音频政策服务 通过解析audio_policy_engine_configuration.xml 文件 中的信息来获取，该文件位于vendor分区中。CAP 引擎配置文件使用 audio_policy_engine_configuration.xsd 中定义的架构来获取所需信息。audio_policy_engine_configuration.xml 是汽车的示例。其他外形规格的类似示例位于 frameworks/av/services/audiopolicy/engineconfigurable/config/example/ 文件夹中。

下图更详细地展示了如何在音频政策服务中加载可配置音频政策引擎信息。在本例中，参数框架从 XML 文件加载结构和设置。

图 2. 在音频政策服务中加载的 CAP 信息。

Android 15 及更低版本中的 CAP 结构文件

如需获取结构和设置，音频政策服务 会读取 ParameterFrameworkConfigurationPolicy.xml 文件。这会通过结构说明文件位置引用结构信息：

<StructureDescriptionFileLocation Path="Structure/Policy/PolicyClass.xml"/>

这指向文件中的结构信息：

/vendor/etc/parameter-framework/Structure/Policy/PolicyClass.xml

Android 中提供了框架结构 Android 。结构信息需要产品策略结构 信息，因此 Android 提供了 buildStrategiesStructureFile.py 生成工具, 该工具可以从可用的产品策略 XML 文件生成信息。 这可以通过 genrule 默认 buildstrategiesstructurerule引用，如下所示：

genrule {
    name: "buildstrategiesstructure_gen",
    defaults: ["buildstrategiesstructurerule"],
    srcs: [
        ":audio_policy_engine_configuration_files",
    ],
}

其中，audio_policy_engine_configuration_files 是音频政策引擎配置文件。此 汽车示例 引用了 汽车文件夹中的音频政策配置文件。 其他示例 展示了如何配置 build 以将文件推送到设备的供应商 分区中。

Android 15 及更低版本中的 CAP 设置文件

与结构类似，表示参数规则和值的设置信息在 ParameterFrameworkConfigurationPolicy.xml 文件中引用，如下所示：

<SettingsConfiguration>
  <ConfigurableDomainsFileLocation Path="Settings/Policy/PolicyConfigurableDomains.xml"/>
</SettingsConfiguration>

Android 还提供了 build 工具，用于使用音频政策引擎配置和参数框架文件生成此信息。如需了解详情，请参阅 配置。

AIDL 音频 HAL CAP 初始化

从 Android 16 开始，AIDL 音频 HAL API 定义通过音频政策引擎配置 AudioHalCapConfiguration.aidl进行了扩展。 下图简要概述了截至 Android 16 的 CAP 引擎配置管理：

图 3. 截至 Android 16 的 CAP 引擎配置管理。

音频政策服务直接使用 AIDL 音频 HAL API 获取 CAP 引擎信息，而不是解析设备 供应商分区中 XML 文件中的信息。

在此配置中，参数框架的结构仍由音频服务器端的 CAP 引擎加载。

图 4. CAP 引擎结构。

在所有情况下，配置都必须完整指定与产品策略、音量组和条件相关的信息。

下图简要概述了音频政策服务用于获取 CAP 引擎配置的 AIDL 音频 HAL API：

图 5.AIDL 音频 HAL API。

在此设置中，音频政策服务从 AIDL 音频 HAL 获取以下信息：

• 配置
• 策略
• 卷
• 条件
• 设置

默认 AIDL 音频 HAL 加载器

为了顺利从 HIDL 过渡到 AIDL，默认音频 AIDL 音频 HAL 提供了 XML CAP 引擎加载器。 供应商可以通过使用 默认音频 HAL 扩展其音频 HAL 或引用 libaudioserviceexampleimpl 库来直接使用此加载器。

默认 AIDL 音频 HAL 加载器使用 audio_policy_engine_configuration.xml 获取以下信息：

• 配置
• 策略
• 卷
• 条件

结构信息从 PolicyConfigurableDomains.xml 文件获取。与之前的机制的主要区别在于，结构信息也由 AIDL 音频 HAL 获取，而不是由音频政策服务中的参数框架获取。

供应商可以使用 domaingeneratorpolicyrule 工具，使用音频 政策引擎配置中的信息生成可配置网域。汽车 Cuttlefish 虚拟设备示例 可用作参考。

AIDL 配置中的结构

在 Android 16 及更高版本中，音频政策服务通过读取和解析 ParameterFrameworkConfigurationCap.xml [文件](https://cs.android.com/android/platform/superproject/+/android-latest-release:frameworks/av/services/audiopolicy/engineconfigurable/wrapper/ParameterManagerWrapper.cpp;l=71

) 获取结构信息。具体而言，它从结构说明文件获取信息：

<StructureDescriptionFileLocation Path="Structure/Policy/CapClass.xml"/>

框架会将所需文件以及所需信息放入 /etc/parameter-framework/ 文件夹中。

该结构表示应控制的参数，因此应在配置或网域中引用这些参数。为此，AIDL 引擎配置应使用预先确定的参数名称。对于产品 策略，结构在 CapProductStrategies.xml中配置。

默认产品策略

从 默认引擎 中提供的默认值开始， 产品策略以 STRATEGY_ 前缀开头：

• STRATEGY_PHONE
• STRATEGY_SONIFICATION
• STRATEGY_ENFORCED_AUDIBLE
• STRATEGY_ACCESSIBILITY
• STRATEGY_SONIFICATION_RESPECTFUL
• STRATEGY_MEDIA
• STRATEGY_DTMF
• STRATEGY_CALL_ASSISTANT
• STRATEGY_TRANSMITTED_THROUGH_SPEAKER

提供此格式是为了缓解使用默认策略的设备从 HIDL 过渡到 AIDL 的过程。此格式更改对用于配置引擎的现有文件（例如 PfW、XML）有一些影响。具体而言，所有产品策略引用都应 更改为使用新名称，例如 ：

OEM 定义的产品策略

可配置引擎允许 OEM 更改产品策略定义。为了继续支持此功能，产品策略文件 CapProductStrategies.xml 还提供了 40 个供应商可扩展的产品策略，范围从 vx_1000 到 vx_1039 。所有供应商扩展都必须以 vx_ 前缀开头，后跟一个 数字，该数字表示 产品策略 ID 在 AIDL 音频 HAL 产品策略定义中。其余定义 （例如音频属性组、名称）从 音频 HAL 引擎配置中的 AudioHALProductStrategy 对象获取。

与默认产品策略类似，供应商定义的 OEM 引用也必须在非 AIDL 配置和 AIDL 配置之间进行调整，例如：

产品策略

产品策略提供了一种自定义音频流分类和分组方式。这让您可以更灵活地配置音频设备，包括如何路由音频设备以及如何管理其音量。每个产品 策略都可以有一个或多个 音频属性 组，这些属性组用于标识应与该产品 策略关联的流。这些音频属性组允许采用更精细的方法对音频进行分类，并且可以是以下类型的组合：

• 用法类型 描述了播放声音的原因（即媒体、通知、通话）。
• 内容类型 类型描述了正在播放的内容（即音乐、语音、视频、 音效）。
• 标志类型 定义了与流相关的不同行为或请求。
• 标记类型支持 任何任意的供应商字符串值列表。
  • 每个字符串都必须以 VX_ 开头，后跟一个字母数字 字符串（例如 VX_OEM、VX_NAVIGATION）

<ProductStrategy name="music" id="1008">
    <AttributesGroup streamType="AUDIO_STREAM_MUSIC" volumeGroup="media">
        <Attributes> <Usage value="AUDIO_USAGE_MEDIA"/> </Attributes>
        <Attributes> <Usage value="AUDIO_USAGE_GAME"/> </Attributes>
        <!-- Default product strategy has empty attributes -->
        <Attributes></Attributes>
    </AttributesGroup>
</ProductStrategy>

此摘录展示了汽车模拟器中使用的产品策略示例。 它包含两个音频属性，分别是音频用法媒体和游戏。 此产品策略与车载音频服务中使用的 MUSIC 音频上下文匹配，但没有此类匹配要求。OEM 将 CAP 与 Android 结合使用的一个主要实用程序是允许更灵活的音频分组定义。

音量组

此外，每个音频属性组都必须具有关联的音量组。 此音量组与任何匹配属于音频属性组的音频属性的流相关联。产品策略部分中的示例音乐产品策略在 产品策略部分中具有音量 组 media，媒体音量组的定义如下：

<volumeGroup>
    <name>media</name>
    <indexMin>0</indexMin>
    <indexMax>40</indexMax>
    <volume deviceCategory="DEVICE_CATEGORY_SPEAKER">
        <point>0,-2400</point>
        <point>33,-1600</point>
        <point>66,-800</point>
        <point>100,0</point>
    </volume>
</volumeGroup>

在此定义中，音量组包含：

• 组名称
• 组最小索引
• 组最大索引
• 音量组曲线

音量组曲线包含音量组索引和音量增益（以毫贝为单位）之间的点状映射。提供的点用于在管理音量时线性插值最佳匹配增益。每个音量组曲线都与 设备类型类别 （例如耳机、扬声器、外部媒体）相关联。

音量组管理属于音频属性组的流的音量。例如，当包含音乐或游戏音频属性的流启动时，系统会使用媒体音量组的上次设置的音量索引。在这种情况下，系统会根据所选设备选择相应的设备类别曲线，并在流启动时设置相应的增益。

配置

在 CAP 引擎中，配置用于定义确定音频行为方式的条件或规则。这些配置在运行时进行评估，以根据音频系统的当前状态选择要应用的相应规则。

如图 5 所示，该 API 包含多个网域，每个网域的目标是将逻辑拆分为较小的路由问题来解决（例如设备 1、设备 2）。

每个网域都有配置，每个配置都有一组规则。规则基于 AudioPolicyManager 提供的条件建立：

• 音频模式
• 可用的输入和输出设备
• 可用的输入和输出设备地址
• 使用此优惠，
  • 媒体
  • 通信
  • 录制
  • 码头
  • 系统
  • HDMI 系统音频
  • 编码环绕声
  • 振动铃声

每个网域都包含配置，这些配置决定了应影响行为的规则。请注意，配置顺序很重要，务必确保配置按所需顺序排列。验证配置的规则后，系统会选择该配置。

以下代码展示了参数框架文件的摘录示例，该文件可用于生成配置可配置网域所需的 XML 文件：

supDomain: DeviceForProductStrategies
  supDomain: Music
    domain: SelectedDevice
      conf: BluetoothA2dp
        ForceUseForMedia IsNot NO_BT_A2DP
        ForceUseForCommunication IsNot BT_SCO
        AvailableOutputDevices Includes BLUETOOTH_A2DP
        component:/Policy/policy/product_strategies/vx_1000/selected_output_devices/mask
          bluetooth_a2dp = 1
          bus = 0
      conf: Bus
        AvailableOutputDevices Includes Bus
        AvailableOutputDevicesAddresses Includes BUS00_MEDIA
        component: /Policy/policy/product_strategies/vx_1000/selected_output_devices/mask
          bluetooth_a2dp = 0
          bus = 1
      conf: Default
        component: /Policy/policy/product_strategies/vx_1000/selected_output_devices/mask
          bluetooth_a2dp = 0
          bus = 0

网域 DeviceForProductStrategies 定义了在处理产品策略设备选择时应如何应用不同的规则。蓝色部分描述了应考虑的规则，绿色部分是应用的配置。此特定示例包含以下配置：

• 为音乐产品策略选择蓝牙 A2DP 设备（ID 1000，vx_1000）
  • 如果用于媒体，则不排除 A2DP
  • 如果用于通信，则不是 BT SCO
  • 如果有可用设备，则包含 BT A2DP
• 选择总线设备
  • 如果有可用总线设备
  • 如果地址为 BUS00_MEDIA
• 否则，选择默认输出设备

如需生成相应的可配置政策引擎 XML 文件，请通过 构建系统运行 参数框架 (PFW) 文件 ，方法是按照以下步骤定义构建规则：

1. 在 Android.bp 文件中，为该文件创建一个文件组：

   filegroup {
       name: ":device_for_product_strategies.pfw",
       srcs: ["engine/parameter-framework/Settings/device_for_product_strategyies.pfw"],
   }
   

2. 将该文件添加到其他 PfW 文件（如果有）。

   filegroup {
       name: "edd_files",
       srcs: [
           ":device_for_input_source.pfw",
           ":volumes.pfw",
           ":device_for_product_strategyies.pfw",
       ],
   }
   

3. 创建相应的网域生成规则：

   genrule {
       name: "domaingeneratorpolicyrule_gen",
       defaults: ["domaingeneratorpolicyrule"],
       srcs: [
           ":audio_policy_engine_criterion_types",
           ":audio_policy_pfw_structure_files",
           ":audio_policy_pfw_toplevel",
           ":edd_files",
       ],
   }
   

   其中，domaingeneratorpolicyrule 是框架提供的 生成 规则 ，用于生成 PolicyConfigurableDomains.xml 文件。网域生成规则中包含的其他源文件 (scrs) 如下所示：

   来源	说明
   audio_policy_pfw_toplevel	顶级参数框架配置文件。
   audio_policy_pfw_structure_files	网域生成结构文件，用于生成配置文件。
   audio_policy_engine_criterion_types	条件类型 XML 文件，描述了生成期间使用的条件。
   edd_files	单个网域文件列表（每个文件都包含一个 <ConfigurableDomain> 标记）。

在 build 中运行生成规则后，系统会生成包含所有网域的 PolicyConfigurableDomains.xml。以下内容展示了使用规则 PfW 示例生成的文件的摘录：

---ConfigurableDomain Name="DeviceForProductStrategies.Music.SelectedDevice"---
<Configurations>
  <Configuration Name="BluetoothA2dp">
    <CompoundRule Type="All">
      <SelectionCriterionRule SelectionCriterion="ForceUseForMedia" MatchesWhen="IsNot" Value="NO_BT_A2DP"/>
      <SelectionCriterionRule SelectionCriterion="ForceUseForCommunication" MatchesWhen="IsNot" Value="BT_SCO"/>
      <SelectionCriterionRule SelectionCriterion="AvailableOutputDevices" MatchesWhen="Includes" Value="BLUETOOTH_A2DP"/>
    </CompoundRule>
  </Configuration>
  <Configuration Name="Bus">
    <CompoundRule Type="All">
      <SelectionCriterionRule SelectionCriterion="AvailableOutputDevices" MatchesWhen="Includes" Value="BUS"/>
      <SelectionCriterionRule SelectionCriterion="AvailableOutputDevicesAddresses" MatchesWhen="Includes" Value="BUS00_MEDIA"/>
    </CompoundRule>
  </Configuration>
  <Configuration Name="Default">
    <CompoundRule Type="All"/>
  </Configuration>
</Configurations>

CAP 调试

您可以使用 remote-process 转储 CAP 配置：

adb root && adb remount
adb shell remote-process unix:///dev/socket/audioserver/policy_debug dumpDomains

这会显示所有网域和配置，包括适用性条件。 以下内容展示了使用蓝牙 A2DP、总线设备和默认配置的 Cuttlefish 汽车设备的摘录。请参阅配置：

- ConfigurableDomain: DeviceForProductStrategies.Music.SelectedDevice =
 {Sequence aware: no, Last applied configuration: Bus}
  - Configuration: BluetoothA2dp
    - CompoundRule = All
      - SelectionCriterionRule = ForceUseForMedia IsNot NO_BT_A2DP
      - SelectionCriterionRule = ForceUseForCommunication IsNot BT_SCO
      - SelectionCriterionRule = AvailableOutputDevices Includes BLUETOOTH_A2DP
  - Configuration: Bus
    - CompoundRule = All
      - SelectionCriterionRule = AvailableOutputDevices Includes BUS
      - SelectionCriterionRule = AvailableOutputDevicesAddresses Includes BUS00_MEDIA_CARD_0_DEV_0
  - Configuration: Default
    - CompoundRule = All

如需详细了解可用于调试 CAP 参数框架的其他命令，请使用此工具：

adb shell remote-process unix:///dev/socket/audioserver/policy_debug help

如需使用该工具，OEM 制造商必须允许在设备中进行调优。如需验证设备是否允许调优，请使用以下命令：

adb shell cat /system/etc/parameter-framework/ParameterFrameworkConfigurationCap.xml

在 Android 15 及更低版本中，该文件可能有所不同，因此请使用以下命令：

adb shell cat /system/etc/parameter-framework/ParameterFrameworkConfigurationPolicy.xml

该文件应包含 TuningAllowed="true" 以及相应的 服务器端口：

<?xml version="1.0" encoding="UTF-8"?>
<ParameterFrameworkConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    SystemClassName="Policy" TuningAllowed="true" ServerPort="unix:///dev/socket/audioserver/policy_debug">
    <SubsystemPlugins>
        <Location Folder="">
            <Plugin Name="libpolicy-subsystem.so"/>
        </Location>
    </SubsystemPlugins>
    <StructureDescriptionFileLocation Path="Structure/Policy/CapClass.xml"/>
</ParameterFrameworkConfiguration>

此文件是 根据 build 映像的类型自动生成的 （或者，对于旧版 build，发布或调试使用不同的文件）。发布 build 会将 TuningAllowed 设置为 false，且不使用套接字端口（发布 build 中禁止使用套接字）。工程 build 和 userdebug build 会将其设置为 true，并使用套接字端口。请注意，这是 audio_policy_pfw_toplevel 引用的文件。remote-process 工具 还必须包含在设备的 make 或 build 文件中：

# Tool used for debug Parameter Framework (only for eng and userdebug builds)
PRODUCT_PACKAGES_DEBUG += remote-process

还必须包含允许套接字的相应 SELinux 政策 。这仅适用于调试模式，因为发布模式明确禁止使用套接字：

BOARD_SEPOLICY_DIRS += frameworks/av/services/audiopolicy/engineconfigurable/sepolicy

Android 16 中的 CAP 迁移

鉴于 AIDL 音频 HAL CAP 引擎和之前版本带来的重大变化，您应考虑各种设备过渡场景。本部分介绍了最突出的过渡场景，并为启用 CAP 引擎配置的工作提供了建议。

场景 1：新设备使用 Android 16 或更高版本，没有设备 CAP 配置的先前来源

新设备必须在 vendor 分区上使用 Android 16 或更高版本的代码启动。这意味着，它必须通过 AIDL 音频 HAL 接口公开可配置音频政策引擎配置。设备 CAP 引擎配置应从示例中复制。vendor 分区上不应有 PfW CAP 网域定义。

用于该设备的系统映像是 Android 16 或更高版本。音频服务框架通过 AIDL 音频 HAL 接口发现 CAP 配置，因此它使用系统映像中的 PfW CAP 网域定义初始化 PfW，并加载通过 AIDL 收到的设备 CAP 配置。

如需查看示例，请参阅此 更改中引入的汽车 Cuttlefish 虚拟设备，该设备可用于引用设置所需配置文件所需的必要文件、build 规则和 make 文件。这适用于 默认 AIDL 音频 HAL 中提供的加载器。

场景 2：新设备使用 Android 16 或更高版本，来自使用 CAP 的先前设备

新设备必须在 vendor 分区上使用 Android 16 或更高版本的代码启动。但是，由于 OEM 具有可用的设备 CAP 引擎配置，因此 OEM 希望将其用作起点（或完全重复使用）。与 Android 15 及更低版本相比，AIDL 版本的 CAP 配置有一些变化，因此供应商必须将现有配置转换为 AIDL。如需了解 Android 16 及更低版本之间的变化，请参阅 产品策略中的讨论，了解所需的变化。 一般来说，音频框架以与场景 1 相同的方式发现和加载 CAP 配置。

场景 3：现有设备使用 CAP，仅将系统分区更新到 Android 16

在此场景中，vendor 分区包含 Android 15 及更低版本的设备 CAP 配置以及 PfW CAP 网域定义。vendor 分区未更改，因此仍使用 HIDL HAL。框架遵循 Android 15 及更低版本的场景，并从 vendor 分区加载所有与 CAP 相关的配置。

场景 4：现有设备在 Android 15 上发布，使用 CAP

Android 15 上的 AIDL 不支持 CAP，因此一些供应商发布了使用 AIDL 音频 HAL 和 CAP 的新设备，这些设备由音频框架加载。此混合模式是非官方的，但包含在 Android 16 中。请注意，此模式不得用于在 Android 16 上发布新设备，而是用于将具有 Android 15 供应商的现有设备更新到 Android 16（system 分区更新）。

音频框架发现 AIDL 音频 HAL 音频配置，但不包含 CAP 配置。对于 CAP 配置，音频政策服务（音频框架）会回退到从 vendor 分区加载 CAP 配置。在这种情况下，PfW CAP 网域定义和设备 CAP 配置都必须从 vendor 分区加载。

CAP 迁移摘要

下表总结了与 CAP 配置兼容的系统和供应商配置以及要求：