音訊功能

Android TV 裝置可同時連接多個音訊輸出裝置，例如電視喇叭、HDMI 連接的家庭劇院、藍牙耳機等。這些音訊輸出裝置可支援不同的音訊功能，例如編碼 (Dolby Digital+、DTS 和 PCM)、取樣率和頻道。舉例來說，透過 HDMI 連接的電視支援多種編碼，而連接的藍牙耳機通常只支援 PCM。

可用的音訊裝置清單和已轉送的音訊裝置，也可以透過熱插 HDMI 裝置、連接或斷開藍牙耳機，或是使用者變更音訊設定來變更。即使應用程式正在播放媒體，音訊輸出功能仍可能變更，因此應用程式需要妥善調整這些變更，並繼續在新的路由音訊裝置及其功能上播放內容。輸出錯誤的音訊格式可能會導致錯誤或沒有聲音播放。

應用程式可輸出多種編碼的相同內容，根據音訊裝置功能為使用者提供最佳音訊體驗。舉例來說，如果電視支援 Dolby Digital，系統會播放 Dolby Digital 編碼音訊串流，如果不支援 Dolby Digital，則會選擇更廣泛支援的 PCM 音訊串流。如要查看用於將音訊串流轉換為 PCM 的內建 Android 解碼器清單，請參閱「支援的媒體格式」。

在播放時，串流應用程式應使用輸出音訊裝置支援的最佳 AudioFormat 建立 AudioTrack。

使用正確的格式建立曲目

應用程式應建立 AudioTrack、開始播放，並呼叫 getRoutedDevice()，以判斷要從哪個預設音訊裝置播放音訊。例如，這可以是安全的短暫靜音 PCM 編碼音軌，僅用於判斷路由裝置及其音訊功能。

取得支援的編碼

使用 getAudioProfiles() (API 級別 31 以上) 或 getEncodings() (API 級別 23 以上)，判斷預設音訊裝置支援的音訊格式。

查看支援的音訊設定檔和格式

使用 AudioProfile (API 級別 31 以上) 或 isDirectPlaybackSupported() (API 級別 29 以上)，檢查格式、頻道數量和取樣率的支援組合。

部分 Android 裝置可支援輸出音訊裝置支援的編碼以外的編碼。這些額外格式應透過 isDirectPlaybackSupported() 偵測。在這些情況下，音訊資料會重新編碼為輸出音訊裝置支援的格式。使用 isDirectPlaybackSupported() 檢查所需格式的支援情形，即使該格式不在 getEncodings() 傳回的清單中也一樣。

注意： 在 API 級別 33 以下，isDirectPlaybackSupported() 會考量所有可用的音訊輸出路徑，即使目前未經路由也一樣。舉例來說，請想想當你同時連接支援直接播放的 HDMI 和不支援的藍牙耳機時，會發生什麼情況。在此情況下，即使音訊可能只會在藍牙耳機上播放，且建立直接 AudioTrack 失敗，函式仍會傳回 true。您可以設定 FLAG_HW_AV_SYNC，建立直接的 AudioTrack。針對 API 級別 33 以上版本，這項設定只會考量目前有效的音訊路由。

預期性音訊路徑

Android 13 (API 級別 33) 推出了預測音訊路由功能。您可以預先考量裝置音訊屬性支援情形，並為有效音訊裝置準備音軌。您可以使用 getDirectPlaybackSupport() 檢查目前已重新導向音訊裝置是否支援指定格式和屬性的直接播放功能：

Kotlin

val format = AudioFormat.Builder()
    .setEncoding(AudioFormat.ENCODING_E_AC3)
    .setChannelMask(AudioFormat.CHANNEL_OUT_5POINT1)
    .setSampleRate(48000)
    .build()
val attributes = AudioAttributes.Builder()
    .setUsage(AudioAttributes.USAGE_MEDIA)
    .build()

if (AudioManager.getDirectPlaybackSupport(format, attributes) !=
    AudioManager.DIRECT_PLAYBACK_NOT_SUPPORTED
) {
    // The format and attributes are supported for direct playback
    // on the currently active routed audio path
} else {
    // The format and attributes are NOT supported for direct playback
    // on the currently active routed audio path
}

Java

AudioFormat format = new AudioFormat.Builder()
        .setEncoding(AudioFormat.ENCODING_E_AC3)
        .setChannelMask(AudioFormat.CHANNEL_OUT_5POINT1)
        .setSampleRate(48000)
        .build();
AudioAttributes attributes = new AudioAttributes.Builder()
        .setUsage(AudioAttributes.USAGE_MEDIA)
        .build();

if (AudioManager.getDirectPlaybackSupport(format, attributes) !=
        AudioManager.DIRECT_PLAYBACK_NOT_SUPPORTED) {
    // The format and attributes are supported for direct playback
    // on the currently active routed audio path
} else {
    // The format and attributes are NOT supported for direct playback
    // on the currently active routed audio path
}

或者，您也可以查詢哪些設定檔支援透過目前已重新導向的音訊裝置直接播放媒體。這會排除任何不支援或會由 Android 架構轉碼的設定檔，例如：

Kotlin

private fun findBestAudioFormat(audioAttributes: AudioAttributes): AudioFormat {
    val preferredFormats = listOf(
        AudioFormat.ENCODING_E_AC3,
        AudioFormat.ENCODING_AC3,
        AudioFormat.ENCODING_PCM_16BIT,
        AudioFormat.ENCODING_DEFAULT
    )
    val audioProfiles = audioManager.getDirectProfilesForAttributes(audioAttributes)
    val bestAudioProfile = preferredFormats.firstNotNullOf { format ->
        audioProfiles.firstOrNull { it.format == format }
    }
    val sampleRate = findBestSampleRate(bestAudioProfile)
    val channelMask = findBestChannelMask(bestAudioProfile)
    return AudioFormat.Builder()
        .setEncoding(bestAudioProfile.format)
        .setSampleRate(sampleRate)
        .setChannelMask(channelMask)
        .build()
}

Java

private AudioFormat findBestAudioFormat(AudioAttributes audioAttributes) {
    Stream<Integer> preferredFormats = Stream.<Integer>builder()
            .add(AudioFormat.ENCODING_E_AC3)
            .add(AudioFormat.ENCODING_AC3)
            .add(AudioFormat.ENCODING_PCM_16BIT)
            .add(AudioFormat.ENCODING_DEFAULT)
            .build();
    Stream<AudioProfile> audioProfiles =
            audioManager.getDirectProfilesForAttributes(audioAttributes).stream();
    AudioProfile bestAudioProfile = (AudioProfile) preferredFormats.map(format ->
            audioProfiles.filter(profile -> profile.getFormat() == format)
                    .findFirst()
                    .orElseThrow(NoSuchElementException::new)
    );
    Integer sampleRate = findBestSampleRate(bestAudioProfile);
    Integer channelMask = findBestChannelMask(bestAudioProfile);
    return new AudioFormat.Builder()
            .setEncoding(bestAudioProfile.getFormat())
            .setSampleRate(sampleRate)
            .setChannelMask(channelMask)
            .build();
}

在這個範例中，preferredFormats 是 AudioFormat 例項的清單。清單會依偏好順序排列，最優先的項目會列在最前面，最不優先的項目則列在最後。getDirectProfilesForAttributes() 會傳回目前已路由音訊裝置的支援 AudioProfile 物件清單，並提供 AudioAttributes。系統會重複執行偏好 AudioFormat 項目的清單，直到找到相符的支援 AudioProfile 為止。這個 AudioProfile 會儲存為 bestAudioProfile。最佳的取樣率和通道遮罩會根據 bestAudioProfile 決定。最後，系統會建立適當的 AudioFormat 例項。

建立音軌

應用程式應使用這項資訊，為預設音訊裝置支援的最高品質 AudioFormat (且可用於所選內容) 建立 AudioTrack。

攔截音訊裝置變更

如要攔截並回應音訊裝置變更，應用程式應：

• 如果 API 級別等於或大於 24，請新增 OnRoutingChangedListener 來監控音訊裝置變更 (HDMI、藍牙等)。
• 針對 API 級別 23，請註冊 AudioDeviceCallback，以便接收可用音訊裝置清單中的變更。
• 針對 API 級別 21 和 22，監控 HDMI 插頭事件，並使用廣播的額外資料。
• 由於尚未支援 AudioDeviceCallback，因此請註冊 BroadcastReceiver 來監控 API 23 以下裝置的 BluetoothDevice 狀態變更。

當系統偵測到 AudioTrack 的音訊裝置變更時，應用程式應檢查更新的音訊功能，並視需要使用不同的 AudioFormat 重新建立 AudioTrack。如果現在支援更高品質的編碼，或先前使用的編碼不再支援，請執行這項操作。

注意： 如果以不再支援的格式將資料寫入 AudioTrack，可能會觸發架構中的錯誤 (例如「Error -32 during AudioTrack native read」)。即使在呼叫變更音訊路由回呼之前，也可能發生這種情況。攔截這些事件，並根據新路由至裝置的功能重新建立 AudioTrack。

程式碼範例

Kotlin

// audioPlayer is a wrapper around an AudioTrack
// which calls a callback for an AudioTrack write error
audioPlayer.addAudioTrackWriteErrorListener {
    // error code can be checked here,
    // in case of write error try to recreate the audio track
    restartAudioTrack(findDefaultAudioDeviceInfo())
}

audioPlayer.audioTrack.addOnRoutingChangedListener({ audioRouting ->
    audioRouting?.routedDevice?.let { audioDeviceInfo ->
        // use the updated audio routed device to determine
        // what audio format should be used
        if (needsAudioFormatChange(audioDeviceInfo)) {
            restartAudioTrack(audioDeviceInfo)
        }
    }
}, handler)

Java

// audioPlayer is a wrapper around an AudioTrack
// which calls a callback for an AudioTrack write error
audioPlayer.addAudioTrackWriteErrorListener(new AudioTrackPlayer.AudioTrackWriteError() {
    @Override
    public void audioTrackWriteError(int errorCode) {
        // error code can be checked here,
        // in case of write error try to recreate the audio track
        restartAudioTrack(findDefaultAudioDeviceInfo());
    }
});

audioPlayer.getAudioTrack().addOnRoutingChangedListener(new AudioRouting.OnRoutingChangedListener() {
    @Override
    public void onRoutingChanged(AudioRouting audioRouting) {
        if (audioRouting != null && audioRouting.getRoutedDevice() != null) {
            AudioDeviceInfo audioDeviceInfo = audioRouting.getRoutedDevice();
            // use the updated audio routed device to determine
            // what audio format should be used
            if (needsAudioFormatChange(audioDeviceInfo)) {
                restartAudioTrack(audioDeviceInfo);
            }
        }
    }
}, handler);