可設定的音訊政策引擎

在 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 引擎設定管理。

如圖所示，音訊政策服務會剖析 vendor 分割區中的 audio_policy_engine_configuration.xml 檔案資訊，取得 CAP 引擎設定。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 是音訊政策引擎設定檔。這個汽車用範例會參照汽車資料夾中的音訊政策設定檔。其他範例則說明如何設定建構，以便將檔案推送至裝置的供應商分區。

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，這些 API 可供音訊政策服務用來取得 CAP 引擎設定：

圖 5.AIDL 音訊 HAL API。

在這個設定中，音訊政策服務會從 AIDL 音訊 HAL 取得下列資訊：

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

預設 AIDL Audio HAL 載入器

為了順利從 HIDL 轉換至 AIDL，預設音訊 AIDL Audio HAL 提供 XML CAP 引擎載入器。供應商可以使用這個載入器，方法是使用預設音訊 HAL 擴充音訊 HAL，或是參照 libaudioserviceexampleimpl 程式庫。

預設 AIDL 音訊 HAL 載入器會使用 audio_policy_engine_configuration.xml 取得下列資訊：

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

系統會從 PolicyConfigurableDomains.xml 檔案取得結構資訊。與先前機制的主要差異在於，結構資訊也是由 AIDL 音訊 HAL 取得，而非音訊政策服務的參數架構。

供應商可以使用 domaingeneratorpolicyrule 工具，根據音訊政策引擎設定的資訊產生可設定的網域。您可以參考汽車 Cuttlefish 虛擬裝置範例。

AIDL 設定中的結構

在 Android 16 以上版本中，音訊政策服務會透過讀取及剖析 ParameterFrameworkConfigurationCap.xml 檔案來取得結構資訊。具體來說，它會從結構描述檔案取得資訊：

<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_ 前置字元開頭，後面接上代表 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 的 OEM 主要工具之一，就是允許更彈性的音訊分組定義。

音量群組

此外，每個音訊屬性群組都必須有相關聯的音量群組。這個音量群組會與任何與音訊屬性群組相符的音訊串流建立關聯。「產品策略」部分的音樂產品策略範例包含「volume group」群組 media，而媒體「volume group」群組的定義如下：

<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

原始設備製造商必須允許在裝置中調整設定，才能使用這項工具。如要確認裝置是否允許調整，請使用下列指令：

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，但不含 Socket 埠 (發布子版本禁止使用 Socket)。工程和 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 政策，才能允許使用 Socket。這項做法僅適用於偵錯模式，因為發布模式明確禁止使用 Socket：

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 虛擬裝置，這是在這個變更中推出，可用於參照設定必要設定檔所需的必要檔案、建構規則和產生檔案。這項功能可搭配 預設 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 的新裝置，並由音訊架構載入。這項混合模式是非官方的，但已納入 Android 16。請注意，這個模式不得用於在 Android 16 上發布新裝置，而是用於讓搭載 Android 15 供應商的現有裝置更新至 Android 16 (system 分區更新)。

音訊架構會在沒有 CAP 設定的情況下，找出 AIDL 音訊 HAL 音訊設定。針對 CAP 設定，音訊政策服務 (音訊架構) 會改為從 vendor 區段載入 CAP 設定。在這種情況下，PfW CAP 網域定義和裝置 CAP 設定都必須從 vendor 分區載入。

CAP 遷移摘要

下表列出 CAP 設定的支援系統和供應商設定，以及相關需求：