本指南將說明 Wear OS 應用程式如何使用慣用的 Android API 播放音訊。
偵測音訊裝置
Wear OS 應用程式必須先偵測穿戴式裝置是否有合適的音訊輸出裝置。 開發人員可以預期穿戴式裝置擁有以下任一種可用音訊輸出裝置:
AudioDeviceInfo.TYPE_BUILTIN_SPEAKER
: 裝置有內建喇叭AudioDeviceInfo.TYPE_BLUETOOTH_A2DP
:表示已與藍牙耳機配對及連線AudioDeviceInfo.TYPE_BLE_BROADCAST
:表示已與藍牙低功耗 (BLE) 廣播群組裝置配對及連線AudioDeviceInfo.TYPE_BLE_HEADSET
:表示已與 BLE 耳機配對及連線AudioDeviceInfo.TYPE_BLE_SPEAKER
:表示已與 BLE 喇叭配對及連線
在以下範例中,應用程式會使用 getDevices()
方法搭配 FEATURE_AUDIO_OUTPUT
的值,列舉所有音訊輸出裝置。
AudioManager audioManager = (AudioManager) context.getSystemService(Context.AUDIO_SERVICE); fun audioOutputAvailable(type: Int): Boolean { if (!packageManager.hasSystemFeature(PackageManager.FEATURE_AUDIO_OUTPUT)) { return false } return audioManager.getDevices(AudioManager.GET_DEVICES_OUTPUTS).any { it.type == type } } // True if the device has a speaker audioOutputAvailable(AudioDeviceInfo.TYPE_BUILTIN_SPEAKER) // True if a Bluetooth headset is paired and connected audioOutputAvailable(AudioDeviceInfo.TYPE_BLUETOOTH_A2DP) // True if a BLE broadcast group device is paired and connected audioOutputAvailable(AudioDeviceInfo.TYPE_BLE_BROADCAST) // True if a BLE headset is paired and connected audioOutputAvailable(AudioDeviceInfo.TYPE_BLE_HEADSET) // True if a BLE speaker is paired and connected audioOutputAvailable(AudioDeviceInfo.TYPE_BLE_SPEAKER)
為提供最佳使用者體驗,應用程式務必只在藍牙耳機或喇叭與手錶連線時播放媒體。
選擇慣用的音訊輸出裝置
根據應用程式的用途,以及音訊對應用程式核心體驗的重要性,選擇您希望使用者與應用程式音訊輸出內容的互動方式。
允許使用者選擇媒體輸出裝置
從 Wear OS 5 開始,系統會提供 UI 讓使用者選擇 裝置應播放媒體,並顯示目前播放媒體的相關資訊 內容。
如果應用程式偵測到你需要已連線的藍牙耳機
讓使用者在搭載 Wear OS 5 以上版本的裝置上播放音訊
使用者直接切換至媒體輸出端切換器在不支援
媒體輸出切換器,請叫用 ACTION_BLUETOOTH_SETTINGS
意圖
動作,可將使用者導向系統設定中的「藍牙」頁面。
launchOutputSelection()
方法 (Horologist 程式庫的一部分)
,示範如何讓使用者選擇媒體輸出裝置。
藍牙耳機
與裝置上隨時可用的內建喇叭不同,藍牙耳機在應用程式執行期間可能會是配對或取消配對狀態。如果應用程式需要耳機才能繼續操作,
註冊回呼以偵測
使用者的藍牙耳機
registerAudioDeviceCallback
:
audioManager.registerAudioDeviceCallback(object : AudioDeviceCallback() { override fun onAudioDevicesAdded(addedDevices: Array<out AudioDeviceInfo>?) { super.onAudioDevicesAdded(addedDevices) if (audioOutputAvailable(AudioDeviceInfo.TYPE_BLUETOOTH_A2DP) || audioOutputAvailable(AudioDeviceInfo.TYPE_BLE_BROADCAST) || audioOutputAvailable(AudioDeviceInfo.TYPE_BLE_HEADSET) || audioOutputAvailable(AudioDeviceInfo.TYPE_BLE_SPEAKER)) { // A Bluetooth or BLE device is connected and available for playback. } } override fun onAudioDevicesRemoved(removedDevices: Array<out AudioDeviceInfo>?) { super.onAudioDevicesRemoved(removedDevices) if (!(audioOutputAvailable(AudioDeviceInfo.TYPE_BLUETOOTH_A2DP)) && !(audioOutputAvailable(AudioDeviceInfo.TYPE_BLE_BROADCAST)) && !(audioOutputAvailable(AudioDeviceInfo.TYPE_BLE_HEADSET)) && !(audioOutputAvailable(AudioDeviceInfo.TYPE_BLE_SPEAKER))) { // No Bluetooth or BLE devices are connected anymore. } } }, null)
如果應用程式在需要輸出音訊時偵測到沒有已連線的藍牙耳機,建議您不要顯示錯誤訊息,而是直接將使用者帶往藍牙設定,方便使用者連接耳機。傳送具有 ACTION_BLUETOOTH_SETTINGS
的意圖即可達到此效果:
val intent = with (Intent(Settings.ACTION_BLUETOOTH_SETTINGS)) { addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK) putExtra("EXTRA_CONNECTION_ONLY", true) putExtra("EXTRA_CLOSE_ON_CONNECT", true) putExtra("android.bluetooth.devicepicker.extra.FILTER_TYPE", 1) } startActivity(intent)
喇叭
多數 Wear OS 裝置都有配備喇叭。如果應用程式提供整合音效的非媒體用途,建議使用喇叭提供其他面向的使用者互動體驗。舉例來說,配備喇叭的 Wear OS 裝置可能會觸發時鐘或計時器鬧鐘,並在完成時發出語音通知,而健身應用程式則可利用喇叭提供運動相關指示。
注意:喇叭並非專為聆聽媒體內容的用途設計,因此無法提供最佳體驗。
詳情請參閱 WearSpeakerSample。
播放音訊
偵測到並選擇合適的音訊輸出裝置後,Wear OS 播放音訊的程序和行動裝置及其他裝置相同。詳情請參閱「MediaPlayer 總覽」一文。如要以更簡單的方式存取其他進階功能,例如串流及下載媒體,請使用 ExoPlayer。請務必採用音訊應用程式的最佳做法,例如管理音訊焦點
防止意外透過喇叭播放媒體
媒體應用程式可以按照下列指引,確保應用程式不會意外透過手錶內建喇叭播放媒體內容。指引內容會因應用程式使用的播放器而有所不同。
ExoPlayer
如果應用程式使用 ExoPlayer:
建構 ExoPlayer 例項時,呼叫 setSuppressPlaybackOnUnsuitableOutput(true):
ExoPlayer exoplayer = ExoPlayer.Builder(context) .setAudioAttributes(...) .setSuppressPlaybackWhenUnsuitableOutput(true) // ... .build()
-
註冊 WearUnsuitableOutputPlaybackSuppressionResolverListener 做為 ExoPlayer 例項的事件監聽器,因應播放抑制事件:
exoPlayer.addListener(WearUnsuitableOutputPlaybackSuppressionResolverListener(context))
Horologist Media Toolkit
Horologist Media Toolkit 已包含相關邏輯,可防止透過手錶內建喇叭意外播放媒體。
其他媒體播放器
- 確保只有在合適的輸出裝置 (例如耳機或一組外接喇叭) 已連線至手錶時,才會開始播放媒體音訊。以下是媒體應用程式適用的輸出裝置清單:
- 如果 AudioManager 通知應用程式,外部音訊輸出裝置已與手錶中斷連線,請暫停播放。
- 如果使用者嘗試播放媒體,但尚未連接外部音訊裝置,請提示使用者連線這類裝置與手錶。