本開發人員指南說明如何使用 Android Sender SDK,將 Google Cast 支援新增至 Android 傳送端應用程式。
行動裝置或筆記型電腦是控製播放的傳送端,Google Cast 裝置則是用來在電視上顯示內容的接收器。
「傳送者架構」是指傳送者執行階段顯示的 Cast 類別程式庫二進位檔和相關資源。「傳送者應用程式」或「Cast 應用程式」是指也在傳送端上執行的應用程式。網頁接收端應用程式是指在支援 Cast 裝置上執行的 HTML 應用程式。
傳送端架構採用非同步回呼設計,向傳送端應用程式通知事件,並在 Cast 應用程式生命週期的不同狀態之間進行轉換。
應用程式流程
下列步驟說明傳送方 Android 應用程式的一般高階執行流程:
- Cast 架構會根據
Activity
生命週期,自動啟動MediaRouter
裝置探索。 - 當使用者按一下「投放」按鈕時,架構會顯示「投放」對話方塊,其中列出已偵測到的投放裝置。
- 使用者選取投放裝置時,架構會嘗試在投放裝置上啟動 Web Receiver 應用程式。
- 該架構會在傳送端應用程式中叫用回呼,以確認 Web Receiver 應用程式已啟動。
- 這個架構會在傳送端和 Web 接收器應用程式之間建立通訊管道。
- 該架構使用通訊管道,在網路接收端載入及控制媒體播放。
- 該架構會在傳送端和網路接收器之間同步處理媒體播放狀態:當使用者提出傳送者 UI 動作時,架構會將這些媒體控制要求傳遞給網路接收器,而網路接收器傳送媒體狀態更新時,架構就會更新傳送端 UI 的狀態。
- 當使用者點選「投放」按鈕與投放裝置中斷連線時,架構會中斷傳送端應用程式與網路接收器的連線。
如需 Google Cast Android SDK 中所有類別、方法和事件的完整清單,請參閱 Android 適用的 Google Cast Sender API 參考資料。以下各節將說明將 Cast 新增至 Android 應用程式的步驟。
設定 Android 資訊清單
您必須為應用程式的 AndroidManifest.xml 檔案設定 Cast SDK 的下列元素:
uses-sdk
設定 Cast SDK 支援的最低和目標 Android API 級別。目前最低版本為 API 級別 21,目標為 API 級別 28。
<uses-sdk
android:minSdkVersion="21"
android:targetSdkVersion="28" />
android:theme
請依據最低 Android SDK 版本設定應用程式主題。舉例來說,如果您不實作自己的主題,則指定最低 Android SDK 版本為 Lollipop 時,則應使用 Theme.AppCompat
的變化版本。
<application
android:icon="@drawable/ic_launcher"
android:label="@string/app_name"
android:theme="@style/Theme.AppCompat" >
...
</application>
初始化 Cast 結構定義
這個架構有一個全域單例模式物件 CastContext
,可協調所有架構的互動。
您的應用程式必須實作 OptionsProvider
介面,才能提供初始化 CastContext
單例模式所需的選項。OptionsProvider
提供 CastOptions
的執行個體,其中包含會影響架構行為的選項。其中最重要的是網路接收器應用程式 ID,可用於篩選探索結果,並在啟動投放工作階段時啟動網路接收器應用程式。
class CastOptionsProvider : OptionsProvider { override fun getCastOptions(context: Context): CastOptions { return Builder() .setReceiverApplicationId(context.getString(R.string.app_id)) .build() } override fun getAdditionalSessionProviders(context: Context): List<SessionProvider>? { return null } }
public class CastOptionsProvider implements OptionsProvider { @Override public CastOptions getCastOptions(Context context) { CastOptions castOptions = new CastOptions.Builder() .setReceiverApplicationId(context.getString(R.string.app_id)) .build(); return castOptions; } @Override public List<SessionProvider> getAdditionalSessionProviders(Context context) { return null; } }
您必須在傳送端應用程式的 AndroidManifest.xml 檔案中,將所實作 OptionsProvider
的完整名稱宣告為中繼資料欄位:
<application>
...
<meta-data
android:name=
"com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
android:value="com.foo.CastOptionsProvider" />
</application>
呼叫 CastContext.getSharedInstance()
時,CastContext
會延遲初始化。
class MyActivity : FragmentActivity() { override fun onCreate(savedInstanceState: Bundle?) { val castContext = CastContext.getSharedInstance(this) } }
public class MyActivity extends FragmentActivity { @Override public void onCreate(Bundle savedInstanceState) { CastContext castContext = CastContext.getSharedInstance(this); } }
Cast 使用者體驗小工具
Cast 架構提供符合 Cast 設計檢查清單的小工具:
簡介重疊:這個架構提供自訂檢視畫面
IntroductoryOverlay
,會在接收器首次可用時,向使用者顯示這個檢視畫面,以提醒他們注意「投放」按鈕。寄件者應用程式可以自訂標題文字的文字和位置。投放按鈕:無論投放裝置為何,「投放」按鈕都會顯示。 當使用者首次點選「投放」按鈕時,系統會顯示「投放」對話方塊,當中列出探索到的裝置。如果使用者在裝置連線後按一下「投放」按鈕,就會顯示目前的媒體中繼資料 (例如標題、錄音工作室的名稱和縮圖),或允許使用者中斷與投放裝置的連線。「投放按鈕」有時也稱為「投放圖示」。
小控制器:當使用者投放內容,並離開目前內容頁面或展開控制器前往傳送端應用程式的其他畫面時,螢幕底部會顯示迷你控制器,讓使用者查看目前投放的媒體中繼資料並控製播放內容。
展開控制器:當使用者投放內容時,只要按一下媒體通知或迷你控制器,即可啟動展開的控制器,顯示目前正在播放的媒體中繼資料,並提供多個按鈕可控制媒體播放。
通知:僅限 Android 裝置。當使用者投放內容,並離開傳送者應用程式時,系統會顯示媒體通知,說明目前正在投放的媒體中繼資料和播放控制項。
螢幕鎖定畫面:僅限 Android 裝置。當使用者投放內容,並導覽 (或裝置逾時) 至螢幕鎖定畫面時,系統會顯示媒體螢幕鎖定控制項,當中顯示目前的投放媒體中繼資料和播放控制項。
以下指南將說明如何將這些小工具新增至應用程式。
新增「投放」按鈕
Android MediaRouter
API 的設計宗旨是在次要裝置上啟用媒體顯示和播放功能。使用 MediaRouter
API 的 Android 應用程式應在使用者介面中加入「投放」按鈕,讓使用者選取媒體路徑,在次要裝置 (例如投放裝置) 上播放媒體。
這個架構可讓您輕鬆將 MediaRouteButton
新增為 Cast button
。請先在定義選單的 XML 檔案中新增選單項目或 MediaRouteButton
,並使用 CastButtonFactory
將選單項目和架構搭配使用。
// To add a Cast button, add the following snippet.
// menu.xml
<item
android:id="@+id/media_route_menu_item"
android:title="@string/media_route_menu_title"
app:actionProviderClass="androidx.mediarouter.app.MediaRouteActionProvider"
app:showAsAction="always" />
// Then override the onCreateOptionMenu() for each of your activities. // MyActivity.kt override fun onCreateOptionsMenu(menu: Menu): Boolean { super.onCreateOptionsMenu(menu) menuInflater.inflate(R.menu.main, menu) CastButtonFactory.setUpMediaRouteButton( applicationContext, menu, R.id.media_route_menu_item ) return true }
// Then override the onCreateOptionMenu() for each of your activities. // MyActivity.java @Override public boolean onCreateOptionsMenu(Menu menu) { super.onCreateOptionsMenu(menu); getMenuInflater().inflate(R.menu.main, menu); CastButtonFactory.setUpMediaRouteButton(getApplicationContext(), menu, R.id.media_route_menu_item); return true; }
接著,如果 Activity
沿用自 FragmentActivity
,您可以在版面配置中加入 MediaRouteButton
。
// activity_layout.xml
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:gravity="center_vertical"
android:orientation="horizontal" >
<androidx.mediarouter.app.MediaRouteButton
android:id="@+id/media_route_button"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_weight="1"
android:mediaRouteTypes="user"
android:visibility="gone" />
</LinearLayout>
// MyActivity.kt override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_layout) mMediaRouteButton = findViewById<View>(R.id.media_route_button) as MediaRouteButton CastButtonFactory.setUpMediaRouteButton(applicationContext, mMediaRouteButton) mCastContext = CastContext.getSharedInstance(this) }
// MyActivity.java @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_layout); mMediaRouteButton = (MediaRouteButton) findViewById(R.id.media_route_button); CastButtonFactory.setUpMediaRouteButton(getApplicationContext(), mMediaRouteButton); mCastContext = CastContext.getSharedInstance(this); }
如要使用主題設定「投放」按鈕的外觀,請參閱自訂「投放按鈕」。
設定裝置探索功能
裝置探索功能完全由 CastContext
管理。初始化 CastContext 時,傳送端應用程式會指定網路接收器應用程式 ID,且您可以視需要在 CastOptions
中設定 supportedNamespaces
,以要求命名空間篩選。CastContext
會在內部保留對 MediaRouter
的參照,並在下列情況啟動探索程序:
- 根據經過特別設計的演算法,可平衡裝置探索延遲時間和電池用量,在傳送端應用程式進入前景時,系統有時會自動啟動探索功能。
- 「投放」對話方塊已開啟。
- Cast SDK 正嘗試復原投放工作階段。
當投放對話方塊關閉,或傳送者應用程式進入背景時,探索程序就會停止。
class CastOptionsProvider : OptionsProvider { companion object { const val CUSTOM_NAMESPACE = "urn:x-cast:custom_namespace" } override fun getCastOptions(appContext: Context): CastOptions { val supportedNamespaces: MutableList<String> = ArrayList() supportedNamespaces.add(CUSTOM_NAMESPACE) return CastOptions.Builder() .setReceiverApplicationId(context.getString(R.string.app_id)) .setSupportedNamespaces(supportedNamespaces) .build() } override fun getAdditionalSessionProviders(context: Context): List<SessionProvider>? { return null } }
class CastOptionsProvider implements OptionsProvider { public static final String CUSTOM_NAMESPACE = "urn:x-cast:custom_namespace"; @Override public CastOptions getCastOptions(Context appContext) { List<String> supportedNamespaces = new ArrayList<>(); supportedNamespaces.add(CUSTOM_NAMESPACE); CastOptions castOptions = new CastOptions.Builder() .setReceiverApplicationId(context.getString(R.string.app_id)) .setSupportedNamespaces(supportedNamespaces) .build(); return castOptions; } @Override public List<SessionProvider> getAdditionalSessionProviders(Context context) { return null; } }
工作階段管理的運作方式
Cast SDK 介紹投放工作階段的概念,其建立方式結合了連線至裝置、啟動 (或加入) 網路接收器應用程式、連線至該應用程式,以及初始化媒體控制管道的步驟。如要進一步瞭解投放工作階段和網路接收器的生命週期,請參閱網路接收器應用程式生命週期指南。
工作階段由 SessionManager
類別管理,應用程式可透過 CastContext.getSessionManager()
存取。個別工作階段是以 Session
類別的子類別表示。舉例來說,CastSession
代表有投放裝置的工作階段。應用程式可透過 SessionManager.getCurrentCastSession()
存取目前執行中的投放工作階段。
應用程式可以使用 SessionManagerListener
類別監控工作階段事件,例如建立、暫停、恢復和終止。這個架構會在工作階段處於執行狀態時,自動嘗試從異常/突然終止的終止作業繼續執行。
為回應來自 MediaRouter
對話方塊的使用者手勢,系統會建立並刪除工作階段。
如要進一步瞭解 Cast 啟動錯誤,應用程式可以使用 CastContext#getCastReasonCodeForCastStatusCode(int)
將工作階段啟動錯誤轉換為 CastReasonCodes
。請注意,部分工作階段啟動錯誤 (例如 CastReasonCodes#CAST_CANCELLED
) 是正常的行為,不應記錄為錯誤。
如果您需要瞭解工作階段的狀態變更,您可以實作 SessionManagerListener
。這個範例會監聽 Activity
中的 CastSession
的可用性。
class MyActivity : Activity() { private var mCastSession: CastSession? = null private lateinit var mCastContext: CastContext private lateinit var mSessionManager: SessionManager private val mSessionManagerListener: SessionManagerListener<CastSession> = SessionManagerListenerImpl() private inner class SessionManagerListenerImpl : SessionManagerListener<CastSession?> { override fun onSessionStarting(session: CastSession?) {} override fun onSessionStarted(session: CastSession?, sessionId: String) { invalidateOptionsMenu() } override fun onSessionStartFailed(session: CastSession?, error: Int) { val castReasonCode = mCastContext.getCastReasonCodeForCastStatusCode(error) // Handle error } override fun onSessionSuspended(session: CastSession?, reason Int) {} override fun onSessionResuming(session: CastSession?, sessionId: String) {} override fun onSessionResumed(session: CastSession?, wasSuspended: Boolean) { invalidateOptionsMenu() } override fun onSessionResumeFailed(session: CastSession?, error: Int) {} override fun onSessionEnding(session: CastSession?) {} override fun onSessionEnded(session: CastSession?, error: Int) { finish() } } override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) mCastContext = CastContext.getSharedInstance(this) mSessionManager = mCastContext.sessionManager } override fun onResume() { super.onResume() mCastSession = mSessionManager.currentCastSession mSessionManager.addSessionManagerListener(mSessionManagerListener, CastSession::class.java) } override fun onPause() { super.onPause() mSessionManager.removeSessionManagerListener(mSessionManagerListener, CastSession::class.java) mCastSession = null } }
public class MyActivity extends Activity { private CastContext mCastContext; private CastSession mCastSession; private SessionManager mSessionManager; private SessionManagerListener<CastSession> mSessionManagerListener = new SessionManagerListenerImpl(); private class SessionManagerListenerImpl implements SessionManagerListener<CastSession> { @Override public void onSessionStarting(CastSession session) {} @Override public void onSessionStarted(CastSession session, String sessionId) { invalidateOptionsMenu(); } @Override public void onSessionStartFailed(CastSession session, int error) { int castReasonCode = mCastContext.getCastReasonCodeForCastStatusCode(error); // Handle error } @Override public void onSessionSuspended(CastSession session, int reason) {} @Override public void onSessionResuming(CastSession session, String sessionId) {} @Override public void onSessionResumed(CastSession session, boolean wasSuspended) { invalidateOptionsMenu(); } @Override public void onSessionResumeFailed(CastSession session, int error) {} @Override public void onSessionEnding(CastSession session) {} @Override public void onSessionEnded(CastSession session, int error) { finish(); } } @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); mCastContext = CastContext.getSharedInstance(this); mSessionManager = mCastContext.getSessionManager(); } @Override protected void onResume() { super.onResume(); mCastSession = mSessionManager.getCurrentCastSession(); mSessionManager.addSessionManagerListener(mSessionManagerListener, CastSession.class); } @Override protected void onPause() { super.onPause(); mSessionManager.removeSessionManagerListener(mSessionManagerListener, CastSession.class); mCastSession = null; } }
變更串流裝置
保留工作階段狀態是串流傳輸的基礎,可讓使用者透過語音指令、Google Home 應用程式或智慧螢幕在不同裝置上移動現有音訊和影片串流。在一部裝置 (來源) 上停止播放媒體,並在另一部裝置 (目的地) 上繼續播放。凡是裝有最新韌體的投放裝置,都可以做為串流傳輸的來源或目的地。
如要在串流傳輸或擴充期間取得新的目的地裝置,請使用 CastSession#addCastListener
註冊 Cast.Listener
。然後在 onDeviceNameChanged
回呼期間呼叫 CastSession#getCastDevice()
。
詳情請參閱在網路接收器上進行串流傳輸。
自動重新連線
該架構提供 ReconnectionService
,可讓傳送端應用程式啟用,以便在許多細微的情況下處理重新連線,例如:
- 在 Wi-Fi 連線暫時中斷的情況下復原
- 從裝置睡眠狀態復原
- 從背景執行復原程序
- 在應用程式當機時復原
這項服務預設為開啟,您可以在 CastOptions.Builder
中關閉。
如果您在 Gradle 檔案中啟用自動合併功能,這項服務可自動併入應用程式的資訊清單。
架構會在有媒體工作階段時啟動服務,並在媒體工作階段結束時停止服務。
媒體控制的運作方式
Cast 架構淘汰 Cast 2.x 中的 RemoteMediaPlayer
類別,改用新的 RemoteMediaClient
類別,以便在一組更方便的 API 中提供相同功能,無需傳入 GoogleApiClient。
當應用程式使用支援媒體命名空間的網路接收端應用程式建立 CastSession
時,該架構會自動建立 RemoteMediaClient
的執行個體;應用程式可透過在 CastSession
執行個體上呼叫 getRemoteMediaClient()
方法存取該執行個體。
向網路接收器發出要求的所有 RemoteMediaClient
方法都會傳回可用於追蹤該要求的 PendingResult 物件。
RemoteMediaClient
的例項應可由應用程式的多個部分共用,並且確實包含架構的部分內部元件,例如永久的迷你控制器和通知服務。為此,這個執行個體支援註冊多個 RemoteMediaClient.Listener
例項。
設定媒體中繼資料
MediaMetadata
類別代表您要投放的媒體項目相關資訊。以下範例會建立新的電影 MediaMetadata 執行個體,並設定標題、副標題和兩張圖片。
val movieMetadata = MediaMetadata(MediaMetadata.MEDIA_TYPE_MOVIE) movieMetadata.putString(MediaMetadata.KEY_TITLE, mSelectedMedia.getTitle()) movieMetadata.putString(MediaMetadata.KEY_SUBTITLE, mSelectedMedia.getStudio()) movieMetadata.addImage(WebImage(Uri.parse(mSelectedMedia.getImage(0)))) movieMetadata.addImage(WebImage(Uri.parse(mSelectedMedia.getImage(1))))
MediaMetadata movieMetadata = new MediaMetadata(MediaMetadata.MEDIA_TYPE_MOVIE); movieMetadata.putString(MediaMetadata.KEY_TITLE, mSelectedMedia.getTitle()); movieMetadata.putString(MediaMetadata.KEY_SUBTITLE, mSelectedMedia.getStudio()); movieMetadata.addImage(new WebImage(Uri.parse(mSelectedMedia.getImage(0)))); movieMetadata.addImage(new WebImage(Uri.parse(mSelectedMedia.getImage(1))));
如要瞭解如何使用含有媒體中繼資料的圖片,請參閱圖片選取一節。
載入媒體
應用程式可以載入媒體項目,如以下程式碼所示。首先,使用 MediaInfo.Builder
搭配媒體的中繼資料,建構 MediaInfo
執行個體。從目前的 CastSession
取得 RemoteMediaClient
,然後將 MediaInfo
載入該 RemoteMediaClient
。使用 RemoteMediaClient
播放、暫停,或以其他方式控制在網路接收器執行的媒體播放器應用程式。
val mediaInfo = MediaInfo.Builder(mSelectedMedia.getUrl()) .setStreamType(MediaInfo.STREAM_TYPE_BUFFERED) .setContentType("videos/mp4") .setMetadata(movieMetadata) .setStreamDuration(mSelectedMedia.getDuration() * 1000) .build() val remoteMediaClient = mCastSession.getRemoteMediaClient() remoteMediaClient.load(MediaLoadRequestData.Builder().setMediaInfo(mediaInfo).build())
MediaInfo mediaInfo = new MediaInfo.Builder(mSelectedMedia.getUrl()) .setStreamType(MediaInfo.STREAM_TYPE_BUFFERED) .setContentType("videos/mp4") .setMetadata(movieMetadata) .setStreamDuration(mSelectedMedia.getDuration() * 1000) .build(); RemoteMediaClient remoteMediaClient = mCastSession.getRemoteMediaClient(); remoteMediaClient.load(new MediaLoadRequestData.Builder().setMediaInfo(mediaInfo).build());
另請參閱「使用媒體曲目」一節。
4K 影片格式
如要檢查媒體的影片格式,請使用 MediaStatus 中的 getVideoInfo()
取得目前的 VideoInfo
例項。這個執行個體包含 HDR TV 格式的類型,以及螢幕高度和寬度 (以像素為單位)。4K 格式的變化版本會以常數 HDR_TYPE_*
表示。
對多部裝置發送遠端控制通知
使用者投放內容時,相同網路的其他 Android 裝置會收到也會收到通知,允許他們控製播放作業。如果使用者的裝置收到這類通知,可以前往 Google 的「設定」應用程式 > Google Cast >「顯示遠端控制通知」,在該裝置上關閉通知。(通知中會包含「設定」應用程式的捷徑)。詳情請參閱「投放遠端控制通知」。
新增迷你控制器
根據「Cast 設計檢查清單」,傳送者應用程式應提供一個永久控制項 (稱為小控制器),當使用者從目前內容頁面離開傳送端應用程式的其他部分時,這個控制項應會顯示。這個小控制器會向目前投放工作階段的使用者顯示提醒。使用者只要輕觸迷你控制器,即可返回 Cast 全螢幕展開控制器檢視畫面。
這個架構提供自訂 View (MinControllerFragment),您可以將其新增至每個活動的版面配置檔案底部,以便顯示迷你控制器。
<fragment
android:id="@+id/castMiniController"
android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:layout_alignParentBottom="true"
android:visibility="gone"
class="com.google.android.gms.cast.framework.media.widget.MiniControllerFragment" />
在傳送端應用程式播放影片或音訊直播時,SDK 會自動顯示播放/停止按鈕,取代迷你控制器中的播放/暫停按鈕。
如要設定這個自訂檢視區塊的標題和副標題文字外觀,以及選擇按鈕,請參閱「自訂迷你控制器」。
新增展開控制器
Google Cast 設計檢查清單要求傳送者應用程式必須為正在投放的媒體提供展開控制器。展開的控制器是全螢幕的迷你控制器。
Cast SDK 為展開的控制器提供稱為 ExpandedControllerActivity
的小工具。這是一個抽象類別,您必須建立子類別,才能新增「投放」按鈕。
首先,請為展開的控制器建立新的選單資源檔案,以提供「投放」按鈕:
<menu xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto">
<item
android:id="@+id/media_route_menu_item"
android:title="@string/media_route_menu_title"
app:actionProviderClass="androidx.mediarouter.app.MediaRouteActionProvider"
app:showAsAction="always"/>
</menu>
建立可擴充 ExpandedControllerActivity
的新類別。
class ExpandedControlsActivity : ExpandedControllerActivity() { override fun onCreateOptionsMenu(menu: Menu): Boolean { super.onCreateOptionsMenu(menu) menuInflater.inflate(R.menu.expanded_controller, menu) CastButtonFactory.setUpMediaRouteButton(this, menu, R.id.media_route_menu_item) return true } }
public class ExpandedControlsActivity extends ExpandedControllerActivity { @Override public boolean onCreateOptionsMenu(Menu menu) { super.onCreateOptionsMenu(menu); getMenuInflater().inflate(R.menu.expanded_controller, menu); CastButtonFactory.setUpMediaRouteButton(this, menu, R.id.media_route_menu_item); return true; } }
現在,請在 application
標記的應用程式資訊清單中宣告新活動:
<application>
...
<activity
android:name=".expandedcontrols.ExpandedControlsActivity"
android:label="@string/app_name"
android:launchMode="singleTask"
android:theme="@style/Theme.CastVideosDark"
android:screenOrientation="portrait"
android:parentActivityName="com.google.sample.cast.refplayer.VideoBrowserActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN"/>
</intent-filter>
</activity>
...
</application>
編輯 CastOptionsProvider
並變更 NotificationOptions
和 CastMediaOptions
,將目標活動設為新活動:
override fun getCastOptions(context: Context): CastOptions? { val notificationOptions = NotificationOptions.Builder() .setTargetActivityClassName(ExpandedControlsActivity::class.java.name) .build() val mediaOptions = CastMediaOptions.Builder() .setNotificationOptions(notificationOptions) .setExpandedControllerActivityClassName(ExpandedControlsActivity::class.java.name) .build() return CastOptions.Builder() .setReceiverApplicationId(context.getString(R.string.app_id)) .setCastMediaOptions(mediaOptions) .build() }
public CastOptions getCastOptions(Context context) { NotificationOptions notificationOptions = new NotificationOptions.Builder() .setTargetActivityClassName(ExpandedControlsActivity.class.getName()) .build(); CastMediaOptions mediaOptions = new CastMediaOptions.Builder() .setNotificationOptions(notificationOptions) .setExpandedControllerActivityClassName(ExpandedControlsActivity.class.getName()) .build(); return new CastOptions.Builder() .setReceiverApplicationId(context.getString(R.string.app_id)) .setCastMediaOptions(mediaOptions) .build(); }
更新 LocalPlayerActivity
loadRemoteMedia
方法,以便在載入遠端媒體時顯示新活動:
private fun loadRemoteMedia(position: Int, autoPlay: Boolean) { val remoteMediaClient = mCastSession?.remoteMediaClient ?: return remoteMediaClient.registerCallback(object : RemoteMediaClient.Callback() { override fun onStatusUpdated() { val intent = Intent(this@LocalPlayerActivity, ExpandedControlsActivity::class.java) startActivity(intent) remoteMediaClient.unregisterCallback(this) } }) remoteMediaClient.load( MediaLoadRequestData.Builder() .setMediaInfo(mSelectedMedia) .setAutoplay(autoPlay) .setCurrentTime(position.toLong()).build() ) }
private void loadRemoteMedia(int position, boolean autoPlay) { if (mCastSession == null) { return; } final RemoteMediaClient remoteMediaClient = mCastSession.getRemoteMediaClient(); if (remoteMediaClient == null) { return; } remoteMediaClient.registerCallback(new RemoteMediaClient.Callback() { @Override public void onStatusUpdated() { Intent intent = new Intent(LocalPlayerActivity.this, ExpandedControlsActivity.class); startActivity(intent); remoteMediaClient.unregisterCallback(this); } }); remoteMediaClient.load(new MediaLoadRequestData.Builder() .setMediaInfo(mSelectedMedia) .setAutoplay(autoPlay) .setCurrentTime(position).build()); }
在傳送端應用程式播放影片或音訊直播時,SDK 會自動顯示播放/停止按鈕,用來取代展開式控制器中的播放/暫停按鈕。
如要使用主題設定外觀,請選擇要顯示的按鈕,並新增自訂按鈕,請參閱「自訂展開控制器」。
音量控制
架構會自動管理傳送端應用程式的磁碟區。架構會自動同步處理傳送者與 Web Receiver 應用程式,因此傳送方 UI 一律會回報網路接收器指定的音量。
實體按鈕音量控制
在 Android 上,預設情況下,傳送端裝置上的實體按鈕可用於變更網路接收器上的投放工作階段音量 (如果裝置使用 Jell Bean 以上版本)。
Jelly Bean 之前實體按鈕的音量控制
如要在搭載 Jelly Bean 之前版本的 Android 裝置上,使用實體音量鍵控制網路接收器裝置音量,傳送方應用程式應在活動中覆寫 dispatchKeyEvent
並呼叫 CastContext.onDispatchVolumeKeyEventBeforeJellyBean()
:
class MyActivity : FragmentActivity() { override fun dispatchKeyEvent(event: KeyEvent): Boolean { return (CastContext.getSharedInstance(this) .onDispatchVolumeKeyEventBeforeJellyBean(event) || super.dispatchKeyEvent(event)) } }
class MyActivity extends FragmentActivity { @Override public boolean dispatchKeyEvent(KeyEvent event) { return CastContext.getSharedInstance(this) .onDispatchVolumeKeyEventBeforeJellyBean(event) || super.dispatchKeyEvent(event); } }
在通知和螢幕鎖定畫面中加入媒體控制項
在 Android 上,Google Cast 設計檢查清單要求傳送者應用程式在通知和螢幕鎖定畫面中實作媒體控制項 (傳送者正在投放,但傳送方應用程式沒有焦點)。這個架構提供 MediaNotificationService
和 MediaIntentReceiver
,協助傳送端應用程式在通知和螢幕鎖定畫面中建構媒體控制項。
MediaNotificationService
會在傳送者投放時執行,並顯示通知,內含圖片縮圖以及目前投放項目的相關資訊、播放/暫停按鈕,以及停止按鈕。
MediaIntentReceiver
是 BroadcastReceiver
,負責處理通知中的使用者動作。
應用程式可透過 NotificationOptions
,設定螢幕鎖定畫面上的通知和媒體控制項。您的應用程式可設定通知要顯示哪些控制項按鈕,以及使用者輕觸通知時要開啟哪個 Activity
。如果未明確提供動作,系統會使用 MediaIntentReceiver.ACTION_TOGGLE_PLAYBACK
和 MediaIntentReceiver.ACTION_STOP_CASTING
預設值。
// Example showing 4 buttons: "rewind", "play/pause", "forward" and "stop casting". val buttonActions: MutableList<String> = ArrayList() buttonActions.add(MediaIntentReceiver.ACTION_REWIND) buttonActions.add(MediaIntentReceiver.ACTION_TOGGLE_PLAYBACK) buttonActions.add(MediaIntentReceiver.ACTION_FORWARD) buttonActions.add(MediaIntentReceiver.ACTION_STOP_CASTING) // Showing "play/pause" and "stop casting" in the compat view of the notification. val compatButtonActionsIndices = intArrayOf(1, 3) // Builds a notification with the above actions. Each tap on the "rewind" and "forward" buttons skips 30 seconds. // Tapping on the notification opens an Activity with class VideoBrowserActivity. val notificationOptions = NotificationOptions.Builder() .setActions(buttonActions, compatButtonActionsIndices) .setSkipStepMs(30 * DateUtils.SECOND_IN_MILLIS) .setTargetActivityClassName(VideoBrowserActivity::class.java.name) .build()
// Example showing 4 buttons: "rewind", "play/pause", "forward" and "stop casting". List<String> buttonActions = new ArrayList<>(); buttonActions.add(MediaIntentReceiver.ACTION_REWIND); buttonActions.add(MediaIntentReceiver.ACTION_TOGGLE_PLAYBACK); buttonActions.add(MediaIntentReceiver.ACTION_FORWARD); buttonActions.add(MediaIntentReceiver.ACTION_STOP_CASTING); // Showing "play/pause" and "stop casting" in the compat view of the notification. int[] compatButtonActionsIndices = new int[]{1, 3}; // Builds a notification with the above actions. Each tap on the "rewind" and "forward" buttons skips 30 seconds. // Tapping on the notification opens an Activity with class VideoBrowserActivity. NotificationOptions notificationOptions = new NotificationOptions.Builder() .setActions(buttonActions, compatButtonActionsIndices) .setSkipStepMs(30 * DateUtils.SECOND_IN_MILLIS) .setTargetActivityClassName(VideoBrowserActivity.class.getName()) .build();
根據預設,在通知和螢幕鎖定畫面中顯示媒體控制項會開啟,如要停用該控制項,您可以呼叫 CastMediaOptions.Builder
中含有空值的 setNotificationOptions
。目前螢幕鎖定功能會在啟用通知功能的情況下開啟。
// ... continue with the NotificationOptions built above val mediaOptions = CastMediaOptions.Builder() .setNotificationOptions(notificationOptions) .build() val castOptions: CastOptions = Builder() .setReceiverApplicationId(context.getString(R.string.app_id)) .setCastMediaOptions(mediaOptions) .build()
// ... continue with the NotificationOptions built above CastMediaOptions mediaOptions = new CastMediaOptions.Builder() .setNotificationOptions(notificationOptions) .build(); CastOptions castOptions = new CastOptions.Builder() .setReceiverApplicationId(context.getString(R.string.app_id)) .setCastMediaOptions(mediaOptions) .build();
在傳送端應用程式播放影片或音訊直播活動時,SDK 會自動顯示播放/停止按鈕來取代通知控制項上的播放/暫停按鈕,而非螢幕鎖定控制選項。
注意:如要在 Lollipop 之前版本的裝置上顯示螢幕鎖定控制項,RemoteMediaClient
會自動代替您要求音訊焦點。
處理錯誤
傳送端應用程式必須處理所有錯誤回呼,並決定 Cast 生命週期中每個階段的最佳回應,這點十分重要。應用程式可以向使用者顯示錯誤對話方塊,或是決定要拆卸與網路接收器的連線。