綜合音訊裝置轉送

合併的音訊裝置轉送功能可為多個音訊裝置新增串流音訊的支援。有了這項功能，具有特殊權限的應用程式即可透過系統 API，以特定策略選取多個偏好裝置。應用程式可以使用這項功能提供的公用 API，更準確地探索音訊裝置的功能。針對 Android 11 以下版本，音訊架構實作僅支援同時連線的多個相同類型音訊裝置 (例如 2 個藍牙 A2DP 耳機)。預設的音訊路由規則也不允許使用者針對特定用途選取多個相同類型的裝置。

從 Android 12 開始，為了支援新的用途，例如音訊廣播、多點投放至一組 BLE 音訊耳機，或同時選取多個 USB 音效卡，我們將移除相關限制。不支援同時轉送至多個 USB 裝置。

從 Android 14 開始，USB 架構支援轉送到多個 USB 裝置，但前提是 USB 裝置屬於不同的音訊裝置類型，核心和供應商也會支援同時連接多個 USB 裝置。

本頁面說明如何實作支援串流音訊至多個音訊裝置的功能，以及如何驗證您實作的這項功能。

注意： 這項功能的實作內容僅在 AOSP 中。部分測試位於 GTS 中，而非 AOSP。

支援將音訊串流至多部音訊裝置

Android 12 有兩組 API 可支援這項功能：

• 系統 API 會處理策略的多個偏好裝置。
• 供應商在音訊 HAL 中實作的 HIDL 介面會回報裝置功能。

以下各節將詳細說明這些 API。

處理多個偏好裝置，制定策略

音訊政策管理工具提供系統 API，可更妥善地支援同時將音訊串流傳輸至多個音訊裝置。這些系統 API 可讓您為特定策略設定、取得及移除多個偏好裝置。在 Android 12 之前，這項功能僅支援單一裝置。

音訊政策管理工具引入了「使用中的媒體裝置」概念，用來描述最有可能用於媒體播放的裝置。連接可拆卸式裝置時，可能必須開啟可將音訊 HAL 輸出串流路由至此裝置的串流，並對支援的屬性進行探測。

注意： 如果系統支援動態音訊設定檔，但並非所有有效音軌都重新導向，則系統不會在裝置連線時立即重新開啟輸出串流，而是在一段時間後 (所有音軌都處於非活動狀態時) 才會重新開啟。

開啟輸出串流時，必須指定音訊裝置。在這個情境中，當輸出串流開啟時，所使用的裝置即為有效媒體裝置。

活動媒體裝置的選取項目可能會因實際連線或斷線的裝置而異。Audio Policy Manager 會使用下列一系列規則來選擇有效的媒體裝置：

1. 如果所有偏好的媒體裝置都有可用，則全部都會選為使用中的裝置。
2. 否則，系統會選擇最近連結的可移除裝置。
3. 如果沒有連接任何卸除式裝置，系統會套用選擇輸出裝置的預設音訊政策規則，並套用至使用中的裝置。

輸出串流必須符合下列條件，才能重新開啟並路由至有效裝置，以便為播放選取最佳設定：

• 輸出串流必須支援有效裝置。
• 輸出串流必須支援動態設定檔。
• 輸出串流目前不得導向至有效裝置。

為了套用新的裝置選項，如果輸出串流處於閒置狀態，Audio Policy Manager 會在裝置連線時關閉及重新開啟輸出串流，或是在輸出串流進入待機狀態時延遲。

Audio Policy Manager 提供下列系統 API 清單(如 AudioManager.java 中所定義)：

• setPreferredDeviceForStrategy

  針對特定策略設定音訊路由的偏好裝置。請注意，裝置在設定偏好裝置時可能無法使用，但一旦上市即可使用。

• removePreferredDeviceForStrategy

  移除先前使用 setPreferredDeviceForStrategy 或 setPreferredDevicesForStrategy 設定的偏好音訊裝置。

• getPreferredDeviceForStrategy

  傳回先前使用 setPreferredDeviceForStrategy 或 setPreferredDevicesForStrategy 設定的音訊策略偏好裝置。

• setPreferredDevicesForStrategy

  設定特定策略的偏好裝置。

• getPreferredDevicesForStrategy

  傳回先前透過 setPreferredDeviceForStrategy 或 setPreferredDevicesForStrategy 設定的音訊策略所用的偏好裝置。

• OnPreferredDevicesForStrategyChangedListener

  定義介面，用於通知偏好音訊裝置的變更，這些裝置是針對特定音訊策略設定的。

• addOnPreferredDevicesForStrategyChangedListener

  新增監聽器，以便在策略偏好的音訊裝置發生變更時收到通知。

• removeOnPreferredDevicesForStrategyChangedListener

  移除先前新增的策略偏好音訊裝置變更事件監聽器。

回報裝置功能

供應商會在 Audio HAL 實作中，實作支援回報裝置功能的 API。本節將說明用於回報裝置功能的資料類型和方法，並列出 audio HIDL HAL V7 中為了支援多個裝置而進行的部分變更。

資料類型

在音訊 HIDL HAL V7 中，系統會使用 AudioProfile 和 AudioTransport 結構回報裝置功能。AudioTransport 結構描述音訊端口的功能，其中 AudioProfile 為已知音訊格式，而原始硬體描述項則為平台不支援的格式。AudioProfile 結構體包含音訊格式、設定檔支援的取樣率，以及頻道遮罩清單，如 types.hal 中的以下程式碼區塊所示：

/**
* Configurations supported for a certain audio format.
*/
struct AudioProfile {
   AudioFormat format;
   /** List of the sample rates (in Hz) supported by the profile. */
   vec<uint32_t> sampleRates;
   /** List of channel masks supported by the profile. */
   vec<AudioChannelMask> channelMasks;
};

在音訊 HIDL HAL V7 中，AudioPort 資料類型會使用 AudioTransport 和 AudioProfile 結構定義，以便描述裝置的功能。

注意： 在 Android 12 之前，SDK API AudioDeviceInfo 結構體會以扁平化陣列格式描述音訊功能，例如取樣率、格式和通道遮罩，但這類格式與取樣率和通道遮罩之間並未有明確的關聯。AudioProfile 已取代上述定義的

音訊 HAL 方法

音訊政策管理工具會使用下列方法查詢裝置的功能：

• getParameters:這是用來擷取供應商專屬參數值的一般方法，例如支援的音訊格式及其相應的取樣率。
• getAudioPort:傳回指定音訊埠的支援屬性清單 (例如取樣率、格式、管道遮罩、增益控制器)。

以下來自 IDevice.hal 的程式碼，顯示 getAudioPort 方法的介面：

   /**
    * Returns the list of supported attributes for a given audio port.
    *
    * As input, 'port' contains the information (type, role, address etc...)
    * needed by the HAL to identify the port.
    *
    * As output, 'resultPort' contains possible attributes (sampling rates,
    * formats, channel masks, gain controllers...) for this port.
    *
    * @param port port identifier.
    * @return retval operation completion status.
    * @return resultPort port descriptor with all parameters filled up.
    */
   getAudioPort(AudioPort port)
           generates (Result retval, AudioPort resultPort);

舊版 API 異動

為了支援多個音訊設定檔，舊版 API 3.2 版新增了名為 audio_port_v7 的新結構。詳情請參閱原始碼。

由於新增了 audio_port_v7，舊版 API 3.2 版新增了名為 get_audio_port_v7 的新 API，以使用 audio_port_v7 結構查詢裝置功能。

以下是 audio.h 的程式碼，顯示 get_audio_port_v7 API 的定義：

/**
 * Fills the list of supported attributes for a given audio port.
 * As input, "port" contains the information (type, role, address etc...)
 * needed by the HAL to identify the port.
 * As output, "port" contains possible attributes (sampling rates,
 * formats, channel masks, gain controllers...) for this port. The
 * possible attributes are saved as audio profiles, which contains audio
 * format and the supported sampling rates and channel masks.
 */
 int (*get_audio_port_v7)(struct audio_hw_device *dev,
                          struct audio_port_v7 *port);

注意： 只有在音訊 HAL 的 7 以上版本和舊版 API 的 3.2 以上版本時，getAudioPort 才會呼叫 get_audio_port_v7 API。如果是音訊 HIDL HAL 6 以下版本或 3.2 以下的舊版 API，getAudioPort 會改為呼叫 get_audio_port API 來查詢裝置功能。

當舊版 API 低於 3.2，且 HIDL HAL 版本為 7 以上版本時，必須將舊版 get_audio_port API 的資料填入新的 AudioPort 格式。在此情況下，系統會假設所有傳回的格式支援 get_audio_port 回報的取樣率和頻道遮罩，使 get_audio_port 值能直接對應至新的 AudioPort 結構。

API 實作範例

本節將說明幾個測試套件，其中包含使用前面各節所述 API 的方法。請參考這些方法，瞭解這些 API 的實作和使用方式。

setPreferredDevicesForStrategy、getPreferredDevicesForStrategy、removePreferredDeviceForStrategy 和 OnPreferredDevicesForStrategyChangedListener 系統 API 的使用方式範例，可參考 GTS 中的 PreferredDeviceRoutingTest 方法。

如要查看 AudioDeviceInfo 中使用中的新結構範例，請參閱位於 CTS 的 AudioManagerTest#testGetDevices 方法。

注意： 此實作項目的 CTS 程式碼會隨 Android 12 版本發布。

get_audio_port_v7 的實作範例位於 audio_hal.c，其中顯示如何查詢多部裝置的功能。

驗證

本節提供 CTS 和 GTS (Google 行動服務測試套件) 對 Audio Manager 進行驗證的相關資訊。

注意： GTS 是封閉式的，相較於 CTS，對慣用裝置 API 具有更完整的測試。如要增加測試涵蓋率，請一併執行 CTS 測試。

CTS 測試

CTS 測試位於 android.media.cts.AudioManagerTest。

以下列出可用的 Audio Manager 測試：

• AudioManagerTest#testGetDevices

  驗證音訊裝置的精確功能。它也會驗證 AudioDeviceInfo 結構中傳回的音訊設定檔是否保留舊版扁平陣列格式的內容，但採用新的 AudioProfile 格式。

  注意： 呼叫 AudioDeviceInfo#getAudioProfiles() 中傳回的 AudioProfile 陣列必須包含與對 AudioDeviceInfo#getEncodings()、AudioDeviceInfo#getSampleRates() 和 AudioDeviceInfo#getChannelMasks() 呼叫的整併陣列相同的內容。

• AudioManagerTest#testPreferredDevicesForStrategy 和 AudioManagerTest#testPreferredDeviceForCapturePreset

  確認用於策略的偏好裝置，並成功擷取預設的相關 API 測試。

GTS 測試

GTS 測試位於 com.google.android.gts.audioservice.AudioServiceHostTest 中。

如要驗證偏好裝置的 API 是否可用於策略，並正確擷取預設作業，請執行 AudioServiceHostTest#testPreferredDeviceRouting 和 AudioServiceHostTest#testPreferredDeviceRoutingForCapturePreset 測試。