使用媒體工作階段

媒體工作階段提供了一種與音訊或影片播放器互動的通用方式。向 Android 通知應用程式正在播放媒體,即可將播放控制項委派給應用程式。整合媒體工作階段可讓應用程式對外宣傳媒體播放,以及從外部來源接收播放指令。這些來源可以是實體按鈕 (例如耳機或電視遙控器上的播放按鈕),或間接指令 (例如向 Google 助理下達「暫停」指令)。接著,媒體工作階段會將這些指令委派給應用程式,讓應用程式顯示在媒體播放器上,因為指令的來源為媒體播放器。

媒體工作階段會與管理的播放器同時運作。您應針對擁有媒體工作階段及其相關播放器的活動或服務的 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());

如需完整範例,請參閱 Universal Music Player

你可以使用 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

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

媒體工作階段回呼方法的實作取決於應用程式的結構。請參閱個別頁面,瞭解如何在音訊應用程式影片應用程式中使用回呼,瞭解如何為每種應用程式實作回呼。