使用媒體工作階段

媒體工作階段提供一種與音訊或視訊互動的方式廣告。告知 Android 應用程式正在播放媒體，您授予應用程式控制項的權限整合媒體工作階段後應用程式，用於在外部宣傳媒體及接收播放指令從外部來源擷取這些來源可以是實體按鈕 (例如播放按鈕) 或間接指令 (例如指示「暫停」這類工作。接著，媒體工作階段會委派這些來源在應用程式中套用這些指令並在指令的來源位置公開透明

媒體工作階段會與管理的播放器一起運作。應建立並在活動的 onCreate() 方法中初始化媒體工作階段，或是服務，以及擁有該媒體工作階段的播放器。

初始化媒體工作階段

新建立的媒體工作階段沒有任何功能。如要初始化工作階段，請執行下列步驟：

設定旗標，讓媒體工作階段接收來自媒體控制器和媒體按鈕的回呼。
建立並初始化 PlaybackStateCompat 的執行個體，並指派給工作階段。播放狀態在整個工作階段期間都會改變，因此建議快取 PlaybackStateCompat.Builder 以重複使用。
建立 MediaSessionCompat.Callback 的執行個體並指派給工作階段 (如要進一步瞭解回呼，請參閱下方說明)。

您應在以下項目的 onCreate() 方法中建立並初始化媒體工作階段：活動或擁有該工作階段的「服務」。

為確保媒體按鈕正常運作當應用程式剛初始化 (或停止) 時，其 PlaybackState 必須包含與媒體按鈕傳送的意圖相符的播放動作。這是為何 ACTION_PLAY 在和初始化。詳情請參閱回應媒體按鈕。

維持播放狀態和中繼資料

有兩個類別，用來代表媒體工作階段的狀態。

PlaybackStateCompat 類別可說明播放器目前的運作狀態。這類功能包括：

傳輸狀態 (播放器是否正在播放/暫停/緩衝處理等。請參閱 getState())
錯誤代碼和選用的錯誤訊息 (如適用)。(請參閱 getErrorCode() 以及下方的狀態和錯誤)。
播放器位置
目前狀態可處理的有效控制器動作

MediaMetadataCompat 類別可說明播放的內容：

演出者、專輯及曲目的名稱
音軌時間長度
要在螢幕鎖定畫面上顯示的專輯圖片。此圖片是點陣圖，大小上限為 320x320dp (如果較大，則會縮小)。
指向較大圖片版本的 ContentUris 例項

播放器狀態和中繼資料可能會在媒體工作階段的生命週期內改變。每次狀態或中繼資料變更時，您必須為每個類別 (PlaybackStateCompat.Builder() 或 MediaMetadataCompat.Builder()) 使用對應的建構工具，然後透過呼叫方式將新的例項傳遞至媒體工作階段 setPlaybackState()或 setMetaData()。為了減少這些常用作業的整體記憶體消耗量，建議您建立一次建構工具，並在整個工作階段期間重複使用。

狀態和錯誤

請注意，PlaybackState 物件包含個別 工作階段的播放狀態 (getState()) 並視需要顯示相關的錯誤代碼 (getErrorCode())。錯誤可能是嚴重或不嚴重的錯誤：

每當播放中斷時，您都會產生嚴重錯誤：將將狀態傳輸至 STATE_ERROR，並指定與 setErrorMessage(int, CharSequence) 相關聯的錯誤。只要錯誤導致播放內容遭錯誤封鎖，PlaybackState 應能繼續回報 STATE_ERROR 和錯誤。

如果應用程式無法處理要求，但可以繼續播放，就會發生一般錯誤：傳輸仍維持在「正常」狀態 (例如 STATE_PLAYING)，但 PlaybackState 仍保留錯誤代碼。舉例來說，如果正在播放最後一首歌，且使用者要求跳到下一首歌，播放可以繼續，但您應以錯誤代碼 ERROR_CODE_END_OF_QUEUE 建立新的 PlaybackState，並然後呼叫 setPlaybackState()。附加至工作階段的媒體控制器會收到回呼 onPlaybackStateChanged()，並向使用者說明情況。一次非嚴重錯誤應只回報一次。下次工作階段更新 PlaybackState 時，並未再次設定相同的非重大錯誤 (除非回應新的要求時發生錯誤)。

媒體工作階段螢幕鎖定畫面

從 Android 4.0 (API 級別 14) 開始，系統可以存取媒體工作階段的播放狀態和中繼資料螢幕鎖定畫面會顯示媒體控制項的方式和圖片。行為會因為 Android 版本。

專輯封面

在 Android 4.0 (API 級別 14) 至 Android 10 (API 級別 29) 中，背景螢幕鎖定畫面會顯示專輯圖片，但僅限媒體工作階段中繼資料會包含背景點陣圖。

傳輸控制項

在 Android 4.0 (API 級別 14) 至 Android 4.4 (API 級別 19) 中，當媒體工作階段處於啟用狀態，且媒體工作階段中繼資料含有背景點陣圖時，螢幕鎖定畫面會自動顯示傳輸控制項。

在 Android 5.0 (API 級別 21) 以上版本中，系統未提供傳輸功能。建議您改用 MediaStyle 通知即可顯示傳輸控制項。

新增自訂動作

媒體應用程式可定義自訂動作；例如：表示喜歡、喜歡或倒轉 30 秒。自訂動作應實作全新的行為。正確做法未使用自訂動作取代其中一項標準傳輸控制動作 PlaybackStateCompat

使用 addCustomAction() 新增自訂動作。以下範例說明如何新增「喜歡」動作的控制項：

Kotlin

stateBuilder.addCustomAction(
        PlaybackStateCompat.CustomAction.Builder(
                CUSTOM_ACTION_THUMBS_UP,
                resources.getString(R.string.thumbs_up),
                thumbsUpIcon
        ).run {
            setExtras(customActionExtras)
            build()
        }
)

Java

stateBuilder.addCustomAction(new PlaybackStateCompat.CustomAction.Builder(
    CUSTOM_ACTION_THUMBS_UP, resources.getString(R.string.thumbs_up), thumbsUpIcon)
    .setExtras(customActionExtras)
    .build());

如需完整範例，請參閱通用音樂播放器。

您使用「onCustomAction()」回應動作。

Kotlin

override fun onCustomAction(action: String, extras: Bundle?) {
    when(action) {
        CUSTOM_ACTION_THUMBS_UP -> {
            ...
        }
    }
}

Java

@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
    if (CUSTOM_ACTION_THUMBS_UP.equals(action)) {
        ...
    }
}

另請參閱通用音樂播放器。

媒體工作階段回呼

主要媒體工作階段回呼方法為 onPlay()、onPause() 和 onStop()。請在這裡新增用來控製播放器的程式碼。

由於您在執行階段 (在 onCreate() 中) 將工作階段的回呼例項化及設定，因此應用程式可以定義使用不同的播放器的替代回呼，並根據裝置和/或系統層級選擇適當的回呼/播放器組合。您可以變更播放器，而不變更應用程式的其餘部分。舉例來說，您可以在 Android 4.1 (API 級別 16) 以上版本中執行 ExoPlayer，並在舊版系統中使用 MediaPlayer。

除了控製播放器及管理媒體工作階段狀態轉換外，回呼也會啟用及停用應用程式功能，並控制與其他應用程式和裝置硬體互動的方式。(請參閱控制音訊輸出)。

媒體工作階段回呼方法的實作方式取決於應用程式的結構。請參閱其他頁面，瞭解如何在網頁中使用回呼：音訊應用程式和影片應用程式說明如何為各種應用程式實作回呼。