本開發人員指南說明如何使用 Android Sender SDK 在您的 Android 傳送端應用程式新增 Google Cast 支援。
行動裝置或筆記型電腦是控製播放的傳送者，Google Cast 裝置則是在電視上顯示內容的接收器。
寄件者架構是指 Cast 類別程式庫二進位檔，以及傳送者在執行階段顯示的相關資源。傳送端應用程式或投放應用程式是指在傳送端上執行的應用程式。Web Receiver 應用程式是指在支援 Cast 裝置上執行的 HTML 應用程式。
傳送者架構使用非同步回呼設計，以通知傳送事件的應用程式，以及在 Cast 應用程式生命週期的不同狀態之間轉換。
應用程式流程
下列步驟說明傳送端 Android 應用程式的一般高階執行流程：
- Cast 架構會根據
Activity生命週期，自動啟動MediaRouter裝置探索。 - 當使用者按一下「投放」按鈕時，架構會顯示 Cast 對話方塊，以及找到的投放裝置清單。
- 使用者選取投放裝置時，架構會嘗試在 Cast 裝置上啟動 Web Receiver 應用程式。
- 架構會在傳送端應用程式中叫用回呼，確認 Web Receiver 應用程式已啟動。
- 這個架構會在傳送者和 Web 接收器應用程式之間建立通訊管道。
- 架構使用通訊管道來載入及控制網路接收器上的媒體播放。
- 此架構會同步處理傳送者和網路接收器之間的媒體播放狀態：當使用者做出傳送者 UI 動作時，架構會將這些媒體控制要求傳送給網路接收器，並在網路接收器傳送媒體狀態更新時，架構會更新傳送者 UI 的狀態。
- 當使用者按一下「投放」按鈕，與投放裝置中斷連線時，架構將會中斷傳送者應用程式與網路接收器的應用程式連線。
如需 Google Cast Android SDK 中所有類別、方法和事件的完整清單，請參閱 Android 適用的 Google Cast Sender API 參考資料。以下各節說明將投放內容新增至 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 版本設定應用程式主題。舉例來說，如果您不實作自己的主題，則應在指定目標為 Lollipop 之前的最低 Android SDK 版本時，使用 Theme.AppCompat 的變化版本。
<application
android:icon="@drawable/ic_launcher"
android:label="@string/app_name"
android:theme="@style/Theme.AppCompat" >
...
</application>
初始化 Cast Context
架構具有全域單例模式物件 CastContext，該物件會協調所有架構的互動。
您的應用程式必須實作 OptionsProvider 介面，以提供初始化 CastContext 單例模式所需的選項。OptionsProvider 提供 CastOptions 的執行個體，其中包含會影響架構行為的選項。其中最重要的是 Web Receiver 應用程式 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，會在首次可用接收器時，向使用者顯示這個檢視按鈕，提醒使用者註意「投放」按鈕。傳送者應用程式可以自訂標題文字的文字和位置。投放按鈕：如果系統發現支援應用程式的接收器，就會顯示「投放」按鈕。當使用者首次點選「投放」按鈕時，系統會顯示「投放」對話方塊，當中列出找到的裝置。如果使用者在裝置連線時按一下「投放」按鈕，系統會顯示目前的媒體中繼資料 (例如錄音室的名稱、錄音室名稱和縮圖)，或允許使用者與投放裝置中斷連線。
Mini Controller：當使用者投放內容，但從目前的內容頁面或展開控制器前往傳送端應用程式中的另一個畫面時，畫面底部會顯示迷你控制器，讓使用者查看目前投放媒體中繼資料及控製播放。
展開控制器：當使用者投放內容時，只要按一下媒體通知或迷你控制器，展開的控制器就會啟動，其中顯示目前正在播放的媒體中繼資料，並提供多個可控制媒體播放的按鈕。
通知：僅限 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 的參照，並在傳送端應用程式進入前景時啟動探索程序，並在傳送者應用程式進入背景時停止。
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 引進了 Cast 工作階段的概念，其中整合了連線至裝置、啟動 (或加入) 網路接收器應用程式、連線至該應用程式，以及初始化媒體控制管道的步驟。如要進一步瞭解 Cast 工作階段和網路接收器生命週期，請參閱網路接收器應用程式生命週期指南。
工作階段由 SessionManager 類別管理，應用程式可透過 CastContext.getSessionManager() 存取。個別工作階段會以 Session 類別的子類別表示。舉例來說，CastSession 代表有投放裝置的工作階段。應用程式可透過 SessionManager.getCurrentCastSession() 存取目前運作中的投放工作階段。
應用程式可以透過 SessionManagerListener 類別監控工作階段事件，例如建立、暫停、恢復和終止。在工作階段處於啟用狀態時，架構會自動嘗試從異常/突然終止而恢復運作。
系統會根據 MediaRouter 對話方塊的使用者手勢，自動建立工作階段並自動卸除。
如要進一步瞭解投放開始錯誤，應用程式可以使用 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 電視格式的類型，以及螢幕高度和寬度 (以像素為單位)。4K 格式的變體會以常數 HDR_TYPE_* 表示。
對多部裝置發出遠端控制通知
當使用者投放內容時，相同網路上的其他 Android 裝置會收到通知，要求他們控製播放內容。如果裝置收到這類通知，只要前往 Google 設定應用程式 > Google Cast >「顯示遙控器通知」，即可關閉該裝置的通知。(通知包括前往「設定」應用程式的捷徑)。詳情請參閱「投放遠端控制通知」。
新增迷你控制器
根據投放設計檢查清單，傳送者應用程式應提供稱為「迷你控制器」的永久控制項，當使用者離開目前的內容頁面，並前往傳送端應用程式的另一個部分時，這個控制項應會顯示。迷你控制器會對目前投放工作階段的使用者顯示可見的提醒。使用者只要輕觸迷你控制器，即可返回展開全螢幕展開的控制器檢視畫面。
這個架構提供自訂 View (MiniControllerFragment)，可加入要顯示迷你控制器的每個活動版面配置檔案底部。
<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 會自動在迷你控制器中顯示播放/暫停按鈕，而非播放/暫停按鈕。
如要設定此自訂檢視區塊的標題和副標題文字外觀，以及選擇按鈕，請參閱自訂 Mini 控制器。
新增展開的控制器
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 會自動在展開的控制器中顯示播放/暫停按鈕，而非播放/暫停按鈕。
如要使用主題設定外觀、選擇要顯示的按鈕，以及新增自訂按鈕，請參閱「自訂擴充控制器」。
音量控制
該架構會自動管理傳送者應用程式的磁碟區。此架構會自動同步處理傳送者和網路接收器應用程式，因此傳送者 UI 一律會回報網路接收器指定的磁碟區。
實體按鈕音量控制
在 Android 上，對於任何使用 Jelly Bean 以上版本的裝置，根據預設，傳送者裝置上的實體按鈕可用來變更網路接收器上的投放工作階段音量。
Jelly Bean 之前的實體按鈕音量控制
如要在搭載 Jelly Bean 之前的 Android 裝置上，使用實體音量鍵控制網路接收器裝置音量，傳送者應用程式應在其「Activity」中覆寫 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 生命週期階段決定最佳回應。應用程式可向使用者顯示錯誤對話方塊，或者可以決定拆除與網路接收器的連線。