支援投放功能的 Android TV 應用程式

1. 總覽

Google Cast 標誌

本程式碼研究室會說明如何修改現有的 Android TV 應用程式，以便支援現有 Cast 發送端應用程式的投放和通訊功能。

什麼是 Google Cast 和 Cast Connect？

使用者可以透過 Google Cast，將行動裝置中的內容投放到電視上。典型的 Google Cast 工作階段包含兩個元件：傳送器和接收器應用程式。傳送端應用程式 (例如行動應用程式或 Youtube.com 等網站) 會啟動及控制 Cast 接收端應用程式的播放作業。投放接收器應用程式是 HTML 5 應用程式，可在 Chromecast 和 Android TV 裝置上執行。

Cast 工作階段中的幾乎所有狀態都會儲存在接收器應用程式中。狀態更新時 (例如載入新的媒體項目)，系統會向所有傳送者廣播媒體狀態。這些廣播會包含 Cast 工作階段的目前狀態。傳送端應用程式會使用這項媒體狀態，在 UI 中顯示播放資訊。

Cast Connect 以這個基礎架構為基礎，Android TV 應用程式則做為接收器。Android TV 應用程式可透過 Cast Connect 程式庫接收訊息及播送媒體狀態，就像是 Cast 接收器應用程式一樣。

我們要建構什麼內容？

完成本程式碼實驗室後，您就能使用 Cast 發送端應用程式，將影片投放至 Android TV 應用程式。Android TV 應用程式也能透過 Cast 協定與發送端應用程式通訊。

課程內容

如何將 Cast Connect 程式庫新增至範例 ATV 應用程式。
如何連結 Cast 傳送器並啟動 Android TV 應用程式。
如何從 Cast 傳送端應用程式啟動 ATV 應用程式的媒體播放功能。
如何從 Android TV 應用程式將媒體狀態傳送至 Cast 發送端應用程式。

軟硬體需求

最新版 Android SDK。
最新版 Android Studio。具體來說，就是 Chipmunk | 2021.2.1 以上版本。
已啟用開發人員選項和 USB 偵錯的 Android TV 裝置。
已啟用開發人員選項和 USB 偵錯的 Android 手機。
USB 資料傳輸線，用於將 Android 手機和 Android TV 裝置連接至開發電腦。
具備使用 Kotlin 開發 Android 應用程式的基本知識。

2. 取得程式碼範例

您可以將所有範例程式碼下載到電腦...

並解壓縮下載的 ZIP 檔案。

3. 執行範例應用程式

首先，我們來看看完成的範例應用程式。Android TV 應用程式會使用 Leanback UI 和基本影片播放器。使用者可以從清單中選取影片，選取後影片就會在電視上播放。使用者也可以透過隨附的行動裝置傳送者應用程式，將影片投放到 Android TV 應用程式。

圖片：一系列影片縮圖 (其中一個已醒目顯示) 疊加在影片的全螢幕預覽畫面上；右上角顯示「Cast Connect」字樣

註冊開發人員裝置

如要為應用程式開發啟用 Cast Connect 功能，請在 Cast 開發人員控制台中，註冊要使用的 Android TV 裝置 Google Cast 序號。如要查看序號，請在 Android TV 上依序前往「設定」>「裝置偏好設定」>「Google Cast」>「序號」。請注意，這與實體裝置的序號不同，必須透過上述方法取得。

圖片：Android TV 螢幕顯示「Google Cast」畫面，以及版本號碼和序號

基於安全考量，如果沒有註冊，Cast Connect 只能用於從 Google Play 商店安裝的應用程式。開始註冊程序 15 分鐘後，重新啟動裝置。

安裝 Android 傳送端應用程式

如要測試從行動裝置傳送要求，我們在原始碼 ZIP 下載檔案中提供名為 Cast Videos 的簡單傳送端應用程式，做為 mobile-sender-0629.apk 檔案。我們會利用 ADB 安裝 APK。如果已安裝其他版本的 Cast Videos，請先從裝置上的所有設定檔解除安裝該版本，再繼續操作。

在 Android 手機上啟用開發人員選項和 USB 偵錯。
使用 USB 資料傳輸線將 Android 手機連接至開發電腦。
在 Android 手機上安裝 mobile-sender-0629.apk。

終端機視窗的圖片，顯示執行 adb install 指令來安裝 mobile-sender.apk

你可以在 Android 手機上找到 Cast Videos 發送端應用程式。

圖片：Android 手機螢幕上執行的 Cast Videos 傳送端應用程式

安裝 Android TV 應用程式

以下說明如何在 Android Studio 中開啟及執行完成的範例應用程式：

在歡迎畫面中選取「Import Project」，或依序選取「File」>「New」>「Import Project...」選單選項。
從範例程式碼資料夾選取 app-done 目錄，然後按一下「確定」。
依序點選「File」> 「Sync Project with Gradle Files」。
在 Android TV 裝置上啟用開發人員選項和 USB 偵錯。
使用 ADB 連線至 Android TV 裝置，裝置應會顯示在 Android Studio 中。
按一下「Run」按鈕，幾秒後應該會看到名為「Cast Connect Codelab」的 Android TV 應用程式。

搭配 Android TV 應用程式使用 Cast Connect

前往 Android TV 主畫面。
在 Android 手機上開啟 Cast Videos 發送端應用程式。按一下「投放」按鈕，然後選取 Apple TV 裝置。
ATV 會啟動 Cast Connect Codelab ATV 應用程式，傳送器中的「投放」按鈕會顯示已連線。
在 Apple TV 應用程式中選取影片，影片就會開始在 Apple TV 上播放。
在手機上，傳送端應用程式底部現在會顯示迷你控制器。你可以使用播放/暫停按鈕控制播放。
選取手機中的影片並播放。ATV 會開始播放影片，行動裝置傳送端則會顯示展開的遙控器。
鎖定手機，解鎖後螢幕鎖定畫面會顯示通知，方便你控制媒體播放或停止投放。

圖片：Android 手機螢幕的一部分，迷你播放器正在播放影片

4. 準備啟動專案

我們已驗證完成的應用程式是否整合 Cast Connect，現在需要為您下載的開始應用程式新增 Cast Connect 支援。現在您可以使用 Android Studio，以入門專案為基礎進行建構：

在歡迎畫面中選取「Import Project」，或依序選取「File」>「New」>「Import Project...」選單選項。
從範例程式碼資料夾選取 app-start 目錄，然後按一下「確定」。
依序點選「File」> 「Sync Project with Gradle Files」。
選取 Android TV 裝置，然後按一下「Run」按鈕，執行應用程式並探索 UI。

圖片：一系列影片縮圖 (其中一個已醒目顯示) 疊加在影片的全螢幕預覽畫面上；右上角顯示「Cast Connect」字樣

應用程式設計

應用程式會提供影片清單供使用者瀏覽。使用者可以選取要在 Android TV 上播放的影片。這個應用程式包含兩個主要活動：MainActivity 和 PlaybackActivity。

MainActivity

這項活動包含一個片段 (MainFragment)。影片清單和相關聯的中繼資料會在 MovieList 類別中設定，並呼叫 setupMovies() 方法來建構 Movie 物件清單。

Movie 物件代表影片實體，包含標題、說明、圖片縮圖和影片網址。每個 Movie 物件都會繫結至 CardPresenter，以顯示影片縮圖、標題和工作室，並傳遞至 ArrayObjectAdapter。

選取項目時，對應的 Movie 物件會傳遞至 PlaybackActivity。

PlaybackActivity

這項活動包含一個 Fragment (PlaybackVideoFragment)，其中會代管 VideoView 和 ExoPlayer、一些媒體控制項，以及顯示所選影片說明的文字區域，並允許使用者在 Android TV 上播放影片。使用者可以透過遙控器播放/暫停或跳轉影片。

Cast Connect 的先決條件

Cast Connect 使用新版 Google Play 服務，因此您必須更新 Android TV 應用程式，才能使用 AndroidX 命名空間。

如要在 Android TV 應用程式中支援 Cast Connect，您必須建立並支援媒體工作階段中的事件。Cast Connect 程式庫會根據媒體工作階段的狀態產生媒體狀態。當媒體工作階段收到來自傳送者的特定訊息 (例如暫停) 時，Cast Connect 程式庫也會使用媒體工作階段發出信號。

5. 設定 Cast 支援功能

依附元件

更新應用程式的 build.gradle 檔案，加入必要的程式庫依附元件：

dependencies {
    ....

    // Cast Connect libraries
    implementation 'com.google.android.gms:play-services-cast-tv:20.0.0'
    implementation 'com.google.android.gms:play-services-cast:21.1.0'
}

同步處理專案，確認專案建構時不會發生錯誤。

初始化

CastReceiverContext 是單例物件，用於協調所有 Cast 互動。您必須實作 ReceiverOptionsProvider 介面，在初始化 CastReceiverContext 時提供 CastReceiverOptions。

建立 CastReceiverOptionsProvider.kt 檔案，並將下列類別新增至專案：

package com.google.sample.cast.castconnect

import android.content.Context
import com.google.android.gms.cast.tv.ReceiverOptionsProvider
import com.google.android.gms.cast.tv.CastReceiverOptions

class CastReceiverOptionsProvider : ReceiverOptionsProvider {
    override fun getOptions(context: Context): CastReceiverOptions {
        return CastReceiverOptions.Builder(context)
                .setStatusText("Cast Connect Codelab")
                .build()
    }
}

然後在應用程式 AndroidManifest.xml 檔案的 <application> 標記中指定接收器選項供應商：

<application>
  ...
  <meta-data
    android:name="com.google.android.gms.cast.tv.RECEIVER_OPTIONS_PROVIDER_CLASS_NAME"
    android:value="com.google.sample.cast.castconnect.CastReceiverOptionsProvider" />
</application>

如要從 Cast 傳送器連線至 ATV 應用程式，請選取要啟動的活動。在本程式碼研究室中，我們會在啟動 Google Cast 工作階段時啟動應用程式的 MainActivity。在 AndroidManifest.xml 檔案中，於 MainActivity 中新增啟動意圖篩選器。

<activity android:name=".MainActivity">
  ...
  <intent-filter>
    <action android:name="com.google.android.gms.cast.tv.action.LAUNCH" />
    <category android:name="android.intent.category.DEFAULT" />
  </intent-filter>
</activity>

Cast 接收端情境生命週期

應用程式啟動時，您應啟動 CastReceiverContext；應用程式移至背景時，則應停止 CastReceiverContext。建議使用 androidx.lifecycle 程式庫中的 LifecycleObserver，管理 CastReceiverContext.start() 和 CastReceiverContext.stop() 的呼叫作業

開啟 MyApplication.kt 檔案，並在應用程式的 onCreate 方法中呼叫 initInstance()，初始化 Cast 內容。在 AppLifeCycleObserver 類別中，應用程式恢復時會 start()，暫停時則會 stop()：CastReceiverContext

package com.google.sample.cast.castconnect

import com.google.android.gms.cast.tv.CastReceiverContext
...

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        CastReceiverContext.initInstance(this)
        ProcessLifecycleOwner.get().lifecycle.addObserver(AppLifecycleObserver())
    }

    class AppLifecycleObserver : DefaultLifecycleObserver {
        override fun onResume(owner: LifecycleOwner) {
            Log.d(LOG_TAG, "onResume")
            CastReceiverContext.getInstance().start()
        }

        override fun onPause(owner: LifecycleOwner) {
            Log.d(LOG_TAG, "onPause")
            CastReceiverContext.getInstance().stop()
        }
    }
}

將 MediaSession 連線至 MediaManager

MediaManager 是 CastReceiverContext 單例項的屬性，可管理媒體狀態、處理載入意圖、將傳送者的媒體命名空間訊息轉換為媒體指令，並將媒體狀態傳送回傳送者。

建立 MediaSession 時，您也需要向 MediaManager 提供目前的 MediaSession 權杖，讓 MediaManager 知道要將指令傳送至何處，以及如何擷取媒體播放狀態。在 PlaybackVideoFragment.kt 檔案中，請務必先初始化 MediaSession，再將權杖設為 MediaManager。

import com.google.android.gms.cast.tv.CastReceiverContext
import com.google.android.gms.cast.tv.media.MediaManager
...

class PlaybackVideoFragment : VideoSupportFragment() {
    private var castReceiverContext: CastReceiverContext? = null
    ...

    private fun initializePlayer() {
        if (mPlayer == null) {
            ...
            mMediaSession = MediaSessionCompat(getContext(), LOG_TAG)
            ...
            castReceiverContext = CastReceiverContext.getInstance()
            if (castReceiverContext != null) {
                val mediaManager: MediaManager = castReceiverContext!!.getMediaManager()
                mediaManager.setSessionCompatToken(mMediaSession!!.getSessionToken())
            }

        }
    }
}

如果因播放閒置而釋放 MediaSession，請在 MediaManager 上設定空值符記：

private fun releasePlayer() {
    mMediaSession?.release()
    castReceiverContext?.mediaManager?.setSessionCompatToken(null)
    ...
}

執行範例應用程式

按一下「Run」 Android Studio 的「Run」按鈕，為指向右方的綠色三角形按鈕，將應用程式部署至 Android TV 裝置，然後關閉應用程式並返回 Android TV 主畫面。在傳送者裝置上，按一下「投放」按鈕「投放」按鈕圖示，然後選取 Android TV 裝置。你會看到 ATV 裝置啟動 ATV 應用程式，且「投放」按鈕狀態為已連線。

6. 正在載入媒體

載入指令會透過意圖傳送，並使用您在開發人員控制台中定義的套件名稱。您需要在 Android TV 應用程式中加入下列預先定義的意圖篩選器，指定接收這項意圖的目標活動。在 AndroidManifest.xml 檔案中，將載入意圖篩選器新增至 PlayerActivity：

<activity android:name="com.google.sample.cast.castconnect.PlaybackActivity"
          android:launchMode="singleTask"
          android:exported="true">
  <intent-filter>
     <action android:name="com.google.android.gms.cast.tv.action.LOAD"/>
     <category android:name="android.intent.category.DEFAULT" />
  </intent-filter>
</activity>

在 Android TV 上處理載入要求

現在活動已設定為接收含有載入要求的意圖，我們需要處理這項要求。

應用程式會在活動啟動時呼叫名為 processIntent 的私有方法。這個方法包含處理傳入意圖的邏輯。如要處理載入要求，我們會修改這個方法，並呼叫 MediaManager 例項的 onNewIntent 方法，傳送要進一步處理的意圖。如果 MediaManager 偵測到意圖是載入要求，就會從意圖中擷取 MediaLoadRequestData 物件，並叫用 MediaLoadCommandCallback.onLoad()。修改 PlaybackVideoFragment.kt 檔案中的 processIntent 方法，處理包含載入要求意圖：

fun processIntent(intent: Intent?) {
    val mediaManager: MediaManager = CastReceiverContext.getInstance().getMediaManager()
    // Pass intent to Cast SDK
    if (mediaManager.onNewIntent(intent)) {
        return
    }

    // Clears all overrides in the modifier.
    mediaManager.getMediaStatusModifier().clear()

    // If the SDK doesn't recognize the intent, handle the intent with your own logic.
    ...
}

接下來，我們會擴充抽象類別 MediaLoadCommandCallback，覆寫 MediaManager 呼叫的 onLoad() 方法。這個方法會接收載入要求的資料，並轉換為 Movie 物件。轉換完成後，電影會透過本機播放器播放。接著，MediaManager 會更新為 MediaLoadRequest，並將 MediaStatus 廣播至已連線的傳送者。在 PlaybackVideoFragment.kt 檔案中建立名為 MyMediaLoadCommandCallback 的巢狀私有類別：

import com.google.android.gms.cast.MediaLoadRequestData
import com.google.android.gms.cast.MediaInfo
import com.google.android.gms.cast.MediaMetadata
import com.google.android.gms.cast.MediaError
import com.google.android.gms.cast.tv.media.MediaException
import com.google.android.gms.cast.tv.media.MediaCommandCallback
import com.google.android.gms.cast.tv.media.QueueUpdateRequestData
import com.google.android.gms.cast.tv.media.MediaLoadCommandCallback
import com.google.android.gms.tasks.Task
import com.google.android.gms.tasks.Tasks
import android.widget.Toast
...

private inner class MyMediaLoadCommandCallback :  MediaLoadCommandCallback() {
    override fun onLoad(
        senderId: String?, mediaLoadRequestData: MediaLoadRequestData): Task<MediaLoadRequestData> {
        Toast.makeText(activity, "onLoad()", Toast.LENGTH_SHORT).show()
        return if (mediaLoadRequestData == null) {
            // Throw MediaException to indicate load failure.
            Tasks.forException(MediaException(
                MediaError.Builder()
                    .setDetailedErrorCode(MediaError.DetailedErrorCode.LOAD_FAILED)
                    .setReason(MediaError.ERROR_REASON_INVALID_REQUEST)
                    .build()))
        } else Tasks.call {
            play(convertLoadRequestToMovie(mediaLoadRequestData)!!)
            // Update media metadata and state
            val mediaManager = castReceiverContext!!.mediaManager
            mediaManager.setDataFromLoad(mediaLoadRequestData)
            mediaLoadRequestData
        }
    }
}

private fun convertLoadRequestToMovie(mediaLoadRequestData: MediaLoadRequestData?): Movie? {
    if (mediaLoadRequestData == null) {
        return null
    }
    val mediaInfo: MediaInfo = mediaLoadRequestData.getMediaInfo() ?: return null
    var videoUrl: String = mediaInfo.getContentId()
    if (mediaInfo.getContentUrl() != null) {
        videoUrl = mediaInfo.getContentUrl()
    }
    val metadata: MediaMetadata = mediaInfo.getMetadata()
    val movie = Movie()
    movie.videoUrl = videoUrl
    movie.title = metadata?.getString(MediaMetadata.KEY_TITLE)
    movie.description = metadata?.getString(MediaMetadata.KEY_SUBTITLE)
    if(metadata?.hasImages() == true) {
        movie.cardImageUrl = metadata.images[0].url.toString()
    }
    return movie
}

現在已定義 Callback，我們需要向 MediaManager 註冊。回呼必須在呼叫 MediaManager.onNewIntent() 之前註冊。在初始化播放器時新增 setMediaLoadCommandCallback：

private fun initializePlayer() {
    if (mPlayer == null) {
        ...
        mMediaSession = MediaSessionCompat(getContext(), LOG_TAG)
        ...
        castReceiverContext = CastReceiverContext.getInstance()
        if (castReceiverContext != null) {
            val mediaManager: MediaManager = castReceiverContext.getMediaManager()
            mediaManager.setSessionCompatToken(mMediaSession.getSessionToken())
            mediaManager.setMediaLoadCommandCallback(MyMediaLoadCommandCallback())
        }
    }
}

執行範例應用程式

按一下「Run」 Android Studio 的「Run」按鈕，為指向右方的綠色三角形按鈕，將應用程式部署至 Android TV 裝置。在傳送者裝置上，按一下「投放」按鈕「投放」按鈕圖示，然後選取 Android TV 裝置。ATV 裝置會啟動 ATV 應用程式。在行動裝置上選取影片，ATV 就會開始播放。檢查手機是否收到通知，並顯示播放控制選項。嘗試使用控制選項，例如暫停，ATV 裝置上的影片應該會暫停。

7. 支援 Cast 控制指令

目前的應用程式現在支援與媒體工作階段相容的基本指令，例如播放、暫停和搜尋。不過，媒體工作階段不支援部分 Cast 控制指令。如要支援這些 Cast 控制指令，請註冊 MediaCommandCallback。

在初始化播放器時，使用 setMediaCommandCallback 將 MyMediaCommandCallback 新增至 MediaManager 執行個體：

private fun initializePlayer() {
    ...
    castReceiverContext = CastReceiverContext.getInstance()
    if (castReceiverContext != null) {
        val mediaManager = castReceiverContext!!.mediaManager
        ...
        mediaManager.setMediaCommandCallback(MyMediaCommandCallback())
    }
}

建立 MyMediaCommandCallback 類別來覆寫方法 (例如 onQueueUpdate())，以支援這些 Cast 控制指令：

private inner class MyMediaCommandCallback : MediaCommandCallback() {
    override fun onQueueUpdate(
        senderId: String?,
        queueUpdateRequestData: QueueUpdateRequestData
    ): Task<Void> {
        Toast.makeText(getActivity(), "onQueueUpdate()", Toast.LENGTH_SHORT).show()
        // Queue Prev / Next
        if (queueUpdateRequestData.getJump() != null) {
            Toast.makeText(
                getActivity(),
                "onQueueUpdate(): Jump = " + queueUpdateRequestData.getJump(),
                Toast.LENGTH_SHORT
            ).show()
        }
        return super.onQueueUpdate(senderId, queueUpdateRequestData)
    }
}

8. 使用媒體狀態

修改媒體狀態

Cast Connect 會從媒體工作階段取得基本媒體狀態。如要支援進階功能，Android TV 應用程式可以透過 MediaStatusModifier 指定及覆寫其他狀態屬性。MediaStatusModifier一律會對你在 CastReceiverContext 中設定的 MediaSession 執行作業。

舉例來說，如要在觸發 onLoad 回呼時指定 setMediaCommandSupported，請使用下列程式碼：

import com.google.android.gms.cast.MediaStatus
...
private class MyMediaLoadCommandCallback : MediaLoadCommandCallback() {
    fun onLoad(
        senderId: String?,
        mediaLoadRequestData: MediaLoadRequestData
    ): Task<MediaLoadRequestData> {
        Toast.makeText(getActivity(), "onLoad()", Toast.LENGTH_SHORT).show()
        ...
        return Tasks.call({
            play(convertLoadRequestToMovie(mediaLoadRequestData)!!)
            ...
            // Use MediaStatusModifier to provide additional information for Cast senders.
            mediaManager.getMediaStatusModifier()
                .setMediaCommandSupported(MediaStatus.COMMAND_QUEUE_NEXT, true)
                .setIsPlayingAd(false)
            mediaManager.broadcastMediaStatus()
            // Return the resolved MediaLoadRequestData to indicate load success.
            mediaLoadRequestData
        })
    }
}

在傳送 MediaStatus 前攔截

與 Web 接收器 SDK 的 MessageInterceptor 類似，您可以在 MediaManager 中指定 MediaStatusWriter，在 MediaStatus 播送至已連線的傳送器之前，對其進行額外修改。

舉例來說，您可以在傳送給行動裝置寄件者之前，在 MediaStatus 中設定自訂資料：

import com.google.android.gms.cast.tv.media.MediaManager.MediaStatusInterceptor
import com.google.android.gms.cast.tv.media.MediaStatusWriter
import org.json.JSONObject
import org.json.JSONException
...

private fun initializePlayer() {
    if (mPlayer == null) {
        ...
        if (castReceiverContext != null) {
            ...
            val mediaManager: MediaManager = castReceiverContext.getMediaManager()
            ...
            // Use MediaStatusInterceptor to process the MediaStatus before sending out.
            mediaManager.setMediaStatusInterceptor(
                MediaStatusInterceptor { mediaStatusWriter: MediaStatusWriter ->
                    try {
                        mediaStatusWriter.setCustomData(JSONObject("{myData: 'CustomData'}"))
                    } catch (e: JSONException) {
                        Log.e(LOG_TAG,e.message,e);
                    }
            })
        }
    }
}

9. 恭喜

您現在已瞭解如何使用 Cast Connect 程式庫，為 Android TV 應用程式啟用 Cast 功能。

詳情請參閱開發人員指南：/cast/docs/android_tv_receiver。

支援投放功能的 Android TV 應用程式 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

1. 總覽

什麼是 Google Cast 和 Cast Connect？

我們要建構什麼內容？

課程內容

軟硬體需求

2. 取得程式碼範例

3. 執行範例應用程式

註冊開發人員裝置

安裝 Android 傳送端應用程式

安裝 Android TV 應用程式

搭配 Android TV 應用程式使用 Cast Connect

4. 準備啟動專案

應用程式設計

MainActivity

PlaybackActivity

Cast Connect 的先決條件

5. 設定 Cast 支援功能

依附元件

初始化

Cast 接收端情境生命週期

將 MediaSession 連線至 MediaManager

執行範例應用程式

6. 正在載入媒體

在 Android TV 上處理載入要求

執行範例應用程式

7. 支援 Cast 控制指令

8. 使用媒體狀態

修改媒體狀態

在傳送 MediaStatus 前攔截

9. 恭喜

支援投放功能的 Android TV 應用程式