音訊功能

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

可用音訊裝置和已轉送音訊裝置的清單也可能因熱插電 HDMI 裝置、連接或拔除藍牙耳機，或使用者變更音訊設定而有所變更。由於音訊輸出功能可能會變更，即使應用程式正在播放媒體，應用程式也必須妥善因應這些變更，並在新的已轉送音訊裝置及其功能上繼續播放。輸出不正確的音訊格式可能會導致錯誤或無法播放音效。

應用程式可以透過多種編碼輸出相同的內容，並根據音訊裝置功能為使用者提供最佳音訊體驗。舉例來說，當電視支援 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() 會考量所有可用的音訊輸出路徑，包括目前未轉送的路徑。舉例來說，假設您同時連接兩個支援直接播放且不支援直接播放的藍牙耳機，會發生什麼情況。在這裡，函式會傳回 true，即使音訊可能只能在藍牙耳機上播放，且直接建立 AudioTrack 失敗。您可以設定 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() 會透過提供的 AudioAttributes 傳回目前轉送音訊裝置的支援的 AudioProfile 物件清單。偏好的 AudioFormat 項目清單會疊代，直到找到相符的 AudioProfile 為止。這個 AudioProfile 會儲存為 bestAudioProfile。最佳取樣率和頻道遮罩取決於 bestAudioProfile。 最後，系統會建立適當的 AudioFormat 執行個體。

建立音軌

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

攔截音訊裝置變更

如要攔截音訊裝置變更並做出回應，應用程式應符合以下條件：

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

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

注意： 如果使用不再支援的格式將資料寫入 AudioTrack，可能會觸發架構的錯誤 (例如「AudioTrack 原生讀取期間發生錯誤 -32」)。即使在呼叫變更音訊轉送回呼前，也可能會發生這類錯誤。請攔截這些 API，並根據新轉送至裝置的功能重新建立 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);