本頁面由 Cloud Translation API 翻譯而成。

啟用播放控制項

如要在 Android Auto 和 Android Automotive OS (AAOS) 中啟用媒體播放功能，請註冊媒體工作階段並處理其回呼方法，藉此實作播放控制項。本頁面說明如何：

在媒體瀏覽器服務中註冊 MediaSessionCompat 物件。
實作 MediaSessionCompat.Callback 方法，回應使用者的播放要求。
設定標準和自訂播放動作。
設定媒體工作階段的初始播放狀態。
新增圖示來指出音訊格式。
從目前播放的媒體項目建立連結。

Android Auto 和 AAOS 可透過服務的 MediaSessionCompat 傳送播放控制指令。您必須註冊工作階段，並實作相關回呼方法。

註冊媒體工作階段

在媒體瀏覽器服務的 onCreate 方法中，建立 MediaSessionCompat 的例項，然後呼叫 setSessionToken 註冊媒體工作階段。這個程式碼片段說明如何建立及註冊媒體工作階段：

Kotlin

override fun onCreate() {
    super.onCreate()
    ...
    // Start a new MediaSession.
    val session = MediaSessionCompat(this, "session tag").apply {
        // Set a callback object that implements MediaSession.Callback
        // to handle play control requests.
        setCallback(MyMediaSessionCallback())
    }
    sessionToken = session.sessionToken
    ...
}

Java

public void onCreate() {
    super.onCreate();
    ...
    // Start a new MediaSession.
    MediaSessionCompat session = new MediaSessionCompat(this, "session tag");
    setSessionToken(session.getSessionToken());

    // Set a callback object that implements MediaSession.Callback
    // to handle play control requests.
    session.setCallback(new MyMediaSessionCallback());
    ...
}

建立媒體工作階段物件時，您必須設定使用的回呼物件，以便處理播放控制項請求。透過為您的應用程式提供 MediaSessionCompat.Callback 類別實作，建立此回呼物件。下一節將討論如何實作此物件。

實作播放指令

當使用者透過應用程式提出媒體項目播放要求時，Android Automotive OS 和 Android Auto 就會使用應用程式 MediaSessionCompat 物件所提供的 MediaSessionCompat.Callback 類別，系統會從應用程式的媒體瀏覽器服務取得該物件。當使用者想要控制內容播放 (例如暫停播放或跳至下一首曲目) 時，Android Auto 和 Android Automotive OS 會叫用其中一個回呼物件的方法。

如要處理內容播放，您的應用程式必須擴充抽象 MediaSessionCompat.Callback 類別，並實作應用程式支援的方法。

針對應用程式提供的內容類型，實作下列每個有意義的回呼方法：

onPrepare: 媒體來源變更時，AAOS 會叫用這個方法。
onPlay: 使用者選擇播放而沒有選擇特定項目時叫用。應用程式必須播放預設內容；如果透過 onPause 暫停播放，應用程式會繼續播放。

注意： 當 Android Automotive OS 或 Android Auto 連線至媒體瀏覽器服務時，您的應用程式不得自動開始播放音樂。詳情請參閱「設定初始播放狀態」。
onPlayFromMediaId: 使用者選擇播放特定項目時叫用。該方法會接收媒體瀏覽器服務指派給內容階層中媒體項目的 ID。
onPlayFromSearch: 使用者從搜尋查詢中選擇播放時叫用。應用程式必須根據傳入的搜尋字串選擇適當的選項。
onPause: 使用者選擇暫停播放時叫用。
onSkipToNext: 使用者選擇跳至下一個項目時叫用。
onSkipToPrevious: 使用者選擇跳至上一個項目時叫用。
onStop: 使用者選擇停止播放時叫用。在應用程式中覆寫這些方法，以提供所選結果。如果應用程式不支援某個方法的功能，就不需要實作該方法。舉例來說，如果應用程式提供直播功能 (例如直播體育賽事)，就不需要實作 onSkipToNext。請改用 onSkipToNext 的預設實作。

應用程式不需要任何特殊邏輯就能透過車輛音響播放內容。應用程式收到播放內容的要求時，應照常透過使用者的手機音響或耳機播放內容。Android Auto 和 AAOS 會自動將音訊內容傳送至車輛的系統，以便透過車輛音響播放。

如要進一步瞭解如何播放音訊內容，請參閱「MediaPlayer 總覽」、「音訊應用程式總覽」和「ExoPlayer 總覽」。

設定標準播放動作

Android Auto 和 AAOS 會根據 PlaybackStateCompat 物件中啟用的動作顯示播放控制項。根據預設，應用程式必須支援下列動作：

如果與應用程式內容相關，您的應用程式可能還支持下列動作：

此外，您也可以選擇建立向使用者顯示的播放佇列。如要這麼做，請呼叫 setQueue 和 setQueueTitle 方法，啟用 ACTION_SKIP_TO_QUEUE_ITEM 動作，並定義回呼 onSkipToQueueItem。

此外，新增對「聽聲辨曲」圖示的支援，這個指標表示正在播放的內容。如要這麼做，請呼叫 setActiveQueueItemId 方法，並傳遞佇列中播放項目的 ID。每當有佇列變更時，您都必須更新 setActiveQueueItemId。

Android Auto 和 AAOS 會顯示每個已啟用動作以及播放佇列的按鈕。使用者點選這些按鈕後，系統會從 MediaSessionCompat.Callback 叫用對應的回呼。

保留未使用的空間

Android Auto 和 AAOS 會在 ACTION_SKIP_TO_PREVIOUS 和 ACTION_SKIP_TO_NEXT 動作的使用者介面保留空間。如果您的應用程式不支援其中一項功能，Android Auto 和 AAOS 會在該空間顯示您建立的任何自訂動作。

如果您不想讓自訂動作填入這些空間，可加以保留，這樣一來，Android Auto 和 AAOS 就會在應用程式無法支援對應的函式時將空間留白。

如要執行此動作，請使用其他套件組合呼叫 setExtras 方法，其中包含與保留函式對應的常數。SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_NEXT 對應於 ACTION_SKIP_TO_NEXT，SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_PREV 則對應於 ACTION_SKIP_TO_PREVIOUS。在套裝組合中使用這些常數做為索引鍵，並使用布林值 true 做為值。

設定初始播放狀態

當 Android Auto 和 AAOS 與您的媒體瀏覽器服務通訊時，媒體工作階段會使用 PlaybackStateCompat 傳送內容播放狀態。

當 AAOS 或 Android Auto 連線至媒體瀏覽器服務時，您的應用程式不應自動開始播放音樂。請改為依照 Android Auto 和 AAOS 根據車輛狀態或使用者動作來繼續或開始播放內容。

為達成這項目標，請將媒體工作階段的初始 PlaybackStateCompat 設定為 STATE_STOPPED、STATE_PAUSED、STATE_NONE 或 STATE_ERROR。

Android Auto 和 AAOS 中的媒體工作階段只會在行車期間持續顯示，因此使用者經常啟動及停止這些工作階段。如果希望在每次行車時提供無縫接軌的體驗，請追蹤使用者先前的工作階段狀態。這樣一來，當媒體應用程式收到繼續要求後，使用者就能自動接續先前中斷的體驗，例如上次播放的媒體項目、PlaybackStateCompat 和待播清單。

新增自訂播放動作

您可以新增自訂播放動作，顯示媒體應用程式支援的其他動作。如果空間允許 (且您未保留)，Android 就會將自訂動作新增至傳輸控制選項中。否則，自訂動作會顯示在溢位選單中。Android 會按照您新增至 PlaybackStateCompat 的順序顯示自訂動作。

使用自訂動作來提供與標準動作不同的行為。請勿使用這些屬性來取代或重複標準動作。

如要新增自訂動作，請使用 PlaybackStateCompat.Builder 類別中的 addCustomAction 方法。這個程式碼片段示範如何將自訂動作新增至「啟動廣播頻道」：

Kotlin

val customActionExtras = Bundle()
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO)

stateBuilder.addCustomAction(
    PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon // or R.drawable.media3_icon_radio
    ).run {
        setExtras(customActionExtras)
        build()
    }
)

Java

Bundle customActionExtras = new Bundle();
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO);

stateBuilder.addCustomAction(
    new PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon) // or R.drawable.media3_icon_radio
    .setExtras(customActionExtras)
    .build());

如需此方法的詳細範例，請參閱 GitHub 上的通用 Android 音樂播放器範例應用程式中的 setCustomAction 方法。建立自訂動作後，媒體工作階段可能會覆寫 onCustomAction 方法，以回應該動作。

這個程式碼片段說明應用程式如何回應「啟動廣播頻道」動作：

Kotlin

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

Java

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

詳情請參閱 GitHub 上通用 Android 音樂播放器範例應用程式中的 onCustomAction 方法。

建立自訂動作的圖示

您建立的每項自訂動作都必須具備圖示。

如果該圖示的說明符合其中一個 CommandButton.ICON_ 常數，請為自訂動作的 extras 設定 EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT 鍵的整數值。在支援的系統上，這麼做會覆寫傳遞至 CustomAction.Builder 的圖示資源，讓系統元件能一致地算繪動作和其他播放動作。

您也必須指定圖示資源。車用應用程式可以在多種螢幕尺寸以不同密度執行，因此您提供的圖示必須是向量可繪項目。使用向量可繪項目縮放素材資源，不會流失細節。向量可繪項目可在解析度較低時，將邊緣與邊角對齊像素邊界。

如果自訂動作會記錄狀態 (例如切換開啟或關閉播放設定)，請為不同狀態提供不同的圖示，讓使用者可在選取動作時看到狀態變更。

為已停用的動作提供替代圖示樣式

如果目前的情境無法使用自訂動作，請將自訂動作圖示換成標示動作已停用的替代圖示。

指出音訊格式

如要指出播放的媒體使用特殊的音訊格式，您可以指定在支援這項功能的車上顯示相應圖示。您可以在當前播放媒體項目 (傳遞至 MediaSession.setMetadata) 的 extras 套件中設定 KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI 和 KEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI。為了配合不同版面配置，請設定所有 extras。

此外，您可以設定 KEY_IMMERSIVE_AUDIO extra，向車輛原始設備製造商 (OEM) 告知這是沉浸式音訊。如此一來，OEM 就能判斷套用音效是否會對沉浸式內容造成干擾，據此謹慎做出決定。

從目前播放的項目新增連結

您可以設定播放中的媒體項目，將其副標題和/或說明設為其他媒體項目的連結。這麼做可讓使用者快速跳到相關項目；例如，使用者可以跳到同一藝人的其他歌曲，或是 Podcast 的其他集數。如果汽車支援這項功能，使用者就能輕觸連結來瀏覽相關內容。

如要新增連結，請設定 KEY_SUBTITLE_LINK_MEDIA_ID 中繼資料 (從副標題連結) 或 KEY_DESCRIPTION_LINK_MEDIA_ID (從說明連結)。詳情請參閱這些中繼資料欄位的參考說明文件。

啟用播放控制項 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

註冊媒體工作階段

Kotlin

Java

實作播放指令

設定標準播放動作

保留未使用的空間

設定初始播放狀態

新增自訂播放動作

Kotlin

Java

Kotlin

Java

建立自訂動作的圖示

為已停用的動作提供替代圖示樣式

指出音訊格式

從目前播放的項目新增連結

啟用播放控制項