可設定的音訊政策引擎

在 Android 14 中，Android Automotive 作業系統 (AAOS) 會在主要音訊區域內，利用可設定的音訊政策 (CAP) 引擎管理車輛音訊。具體來說，CAP 引擎可讓 AAOS 同時控制音訊路由和音量，或只控制其中一項。您可以使用下列標記控制行為：

• 使用 useCoreAudioVolume 旗標啟用 CAP 音量管理。如果這個值為 true，車輛音訊服務會使用音訊管理員 API 管理音量群組。

• 使用 useCoreAudioRouting 旗標啟用 CAP 音訊路徑管理。 如果這個值為 true，車輛音訊服務會使用可設定的音訊政策路由，管理音訊路由。

Android 預設也支援音訊政策引擎，形式為預設音訊政策引擎。

背景

CAP 引擎是以 Intel 的參數架構為基礎，這是一種以外掛程式和規則為基礎的架構，可處理參數。特別是針對 Android 音訊管理，CAP 引擎導入了定義 XML 檔案規則的功能，可指定下列項目：

• 音訊產品策略
• 音訊輸出裝置選取規則
• 音訊輸入裝置選取規則
• 管理音量和靜音的規則，以及音量表

Android 16 之前的 CAP 初始化

下圖概略說明 Android 6 以上版本可設定的音訊政策引擎設定管理：

圖 1. Android 6 以上版本可管理 CAP 引擎設定。

如圖所示，CAP 引擎設定是透過音訊政策服務，剖析 vendor 分割區中 audio_policy_engine_configuration.xml 檔案的資訊而取得。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 提供 buildStrategiesStructureFile.py 生成工具，可從可用的產品策略 XML 檔案生成資訊。這可透過 genrule default buildstrategiesstructurerule 參照，如下所示：

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

其中 audio_policy_engine_configuration_files 是音訊政策引擎設定檔。這個車輛範例會參照automotive 資料夾中的音訊政策設定檔。其他範例說明如何設定建構作業，將檔案推送至裝置的供應商分割區。

Android 15 以下版本的 CAP 設定檔

與結構類似，設定資訊 (代表參數的規則和值) 會在 ParameterFrameworkConfigurationPolicy.xml 檔案中參照為：

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

Android 也提供建構工具，可使用音訊政策引擎設定和參數架構檔案產生這項資訊。詳情請參閱「設定」一節。

AIDL 音訊 HAL CAP 初始化

從 Android 16 開始，AIDL Audio HAL API 定義會擴充音訊政策引擎設定 AudioHalCapConfiguration.aidl。下圖顯示 Android 16 的 CAP 引擎設定管理概要：

圖 3. Android 16 以上版本支援 CAP 引擎設定管理。

音訊政策服務會直接使用 AIDL Audio HAL API 取得 CAP 引擎資訊，而不是剖析裝置供應商分割區中的 XML 檔案資訊。

在此設定中，CAP 引擎仍會在音訊伺服器端載入參數架構的結構。

圖 4. CAP 引擎結構。

無論如何，設定都必須完整指定產品策略、量體群組和條件的相關資訊。

下圖概略說明音訊政策服務如何使用 AIDL 音訊 HAL API，取得 CAP 引擎設定：

圖 5.AIDL 音訊 HAL API。

在此設定中，音訊原則服務會從 AIDL 音訊 HAL 取得下列資訊：

• 設定
• 策略
• 合輯
• 條件
• 設定

預設 AIDL Audio 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 定義的產品策略

原始設備製造商可透過可設定的引擎變更產品策略定義。為持續支援這項功能，產品策略檔案 CapProductStrategies.xml 也提供 40 個可擴充的供應商產品策略，範圍從 vx_1000 到 vx_1039。所有供應商擴充功能都必須以 vx_ 前置字元開頭，後面接著代表 AIDL 音訊 HAL 產品策略定義中產品策略 ID 的數字。其餘定義 (例如音訊屬性群組、名稱) 則來自音訊 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音訊環境相符，但並非必要條件。對於使用 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> 標記)。

在建構中執行生成規則後，系統會生成包含所有網域的 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

這會顯示所有網域和設定，包括適用性條件。以下是 Cuttlefish 車用裝置的摘錄內容，使用藍牙 A2DP、匯流排裝置和預設設定。請參閱「設定」一節：

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

這個檔案會根據建構映像檔類型自動生成 (或使用其他檔案進行發布或偵錯，適用於舊版建構作業)。發布子版本會將 TuningAllowed 設為 false，且不含通訊端埠 (發布子版本禁止使用通訊端)。工程和 userdebug 建構作業會將其設為 true，並使用通訊端通訊埠。請注意，這是 audio_policy_pfw_toplevel 參照的檔案。遠端程序工具也必須包含在裝置的 make 或建構檔案中：

# 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 虛擬裝置，這個裝置是在這項變更中推出，可做為設定必要設定檔所需的檔案、建構規則和 make 檔案參考。這項功能適用於預設 AIDL 音訊 HAL 中提供的載入器。

情境 2：新裝置搭載 Android 16 以上版本，舊裝置使用 CAP

新裝置必須在 vendor 分割區啟動 Android 16 以上版本的程式碼。不過，由於 OEM 擁有可用的裝置 CAP 引擎設定，因此會想將其做為起點 (或完全重複使用)。與 Android 15 以下版本相比，CAP 設定的 AIDL 版本有所變更，因此供應商必須將現有設定轉換為 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 Audio HAL 和 CAP 的新裝置，而 CAP 由音訊架構載入。這個混合模式並非官方模式，但已納入 Android 16。請注意，這個模式不得用於在 Android 16 上發布新裝置，而是用於讓搭載 Android 15 供應商版本的現有裝置更新至 Android 16 (system 分區更新)。

音訊架構會探索 AIDL 音訊 HAL 音訊設定，但不含 CAP 設定。如果是 CAP 設定，音訊政策服務 (音訊架構) 會從 vendor 分區載入 CAP 設定。在這種情況下，PfW CAP 網域定義和裝置 CAP 設定都必須從 vendor 分區載入。

CAP 遷移摘要

下表摘要說明 CAP 設定的相容系統、供應商設定和需求：