Integrate Cast Into Your Android App

This developer guide describes how to add Google Cast support to your Android sender app using the Android Sender SDK.

Note: We recommend that you try the following:

• Cast Android Sender codelab tutorial - Learn step-by-step how to enable an existing Android video app to use a Google Cast device to Cast videos to a TV.
• CastVideos-android sample app (GitHub) - Run, navigate, and view this reference sample app which complies with the UX Guidelines and Design Checklist.

The mobile device or laptop is the sender which controls the playback, and the Google Cast device is the Receiver which displays the content on the TV.

The sender framework refers to the Cast class library binary and associated resources present at runtime on the sender. The sender app or Cast app refers to an app also running on the sender. The Web Receiver app refers to the HTML application running on the Cast-enabled device.

The sender framework uses an asynchronous callback design to inform the sender app of events and to transition between various states of the Cast app life cycle.

App flow

The following steps describe the typical high-level execution flow for a sender Android app:

• The Cast framework automatically starts MediaRouter device discovery based on the Activity lifecycle.
• When the user clicks on the Cast button, the framework presents the Cast dialog with the list of discovered Cast devices.
• When the user selects a Cast device, the framework attempts to launch the Web Receiver app on the Cast device.
• The framework invokes callbacks in the sender app to confirm that the Web Receiver app was launched.
• The framework creates a communication channel between the sender and Web Receiver apps.
• The framework uses the communication channel to load and control media playback on the Web Receiver.
• The framework synchronizes the media playback state between sender and Web Receiver: when the user makes sender UI actions, the framework passes those media control requests to the Web Receiver, and when the Web Receiver sends media status updates, the framework updates the state of the sender UI.
• When the user clicks on the Cast button to disconnect from the Cast device, the framework will disconnect the sender app from the Web Receiver.

For a comprehensive list of all classes, methods and events in the Google Cast Android SDK, see the Google Cast Sender API Reference for Android. The following sections cover the steps for you to add Cast to your Android app.

Configure the Android manifest

Your app's AndroidManifest.xml file requires you to configure the following elements for the Cast SDK:

uses-sdk

Set the minimum and target Android API levels that the Cast SDK supports. Currently the minimum is API level 19 and the target is API level 28.

Note: This element specifies the API Level, not the version number of the SDK, despite "SdkVersion" appearing in the attribute names.

<uses-sdk
        android:minSdkVersion="19"
        android:targetSdkVersion="28" />

android:theme

Set your app's theme based on the minimum Android SDK version. For example, if you are not implementing your own theme, you should use a variant of Theme.AppCompat when targeting a minimum Android SDK version that is pre-Lollipop.

<application
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/Theme.AppCompat" >
       ...
</application>

Initialize the Cast Context

The framework has a global singleton object, the CastContext, that coordinates all the framework's interactions.

Your app must implement the OptionsProvider interface to supply options needed to initialize the CastContext singleton. OptionsProvider provides an instance of CastOptions which contains options that affect the behavior of the framework. The most important of these is the Web Receiver application ID, which is used to filter discovery results and to launch the Web Receiver app when a Cast session is started.

Kotlin

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
    }
}

Java

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;
    }
}

You must declare the fully qualified name of the implemented OptionsProvider as a metadata field in the AndroidManifest.xml file of the sender app:

<application>
    ...
    <meta-data
        android:name=
            "com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
        android:value="com.foo.CastOptionsProvider" />
</application>

CastContext is lazily initialized when the CastContext.getSharedInstance() is called.

Kotlin

class MyActivity : FragmentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        val castContext = CastContext.getSharedInstance(this)
    }
}

Java

public class MyActivity extends FragmentActivity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        CastContext castContext = CastContext.getSharedInstance(this);
    }
}

The Cast UX Widgets

The Cast framework provides the widgets that comply with the Cast Design Checklist:

• Introductory Overlay: The framework provides a custom View, IntroductoryOverlay, that is shown to the user to call attention to the Cast button the first time a receiver is available. The Sender app can customize the text and the position of the title text.

• Cast Button: The Cast button is visible when a receiver is discovered that supports your app. When the user first clicks on the Cast button, a Cast dialog is displayed which lists the discovered devices. When the user clicks on the Cast button while the device is connected, it displays the current media metadata (such as title, name of the recording studio and a thumbnail image) or allows the user to disconnect from the Cast device.

• Mini Controller: When the user is casting content and has navigated away from the current content page or expanded controller to another screen in the sender app, the mini controller is displayed at the bottom of the screen to allow the user to see the currently casting media metadata and to control the playback.

• Expanded Controller: When the user is casting content, if they click on the media notification or mini controller, the expanded controller launches, which displays the currently playing media metadata and provides several buttons to control the media playback.

• Notification: Android only. When the user is casting content and navigates away from the sender app, a media notification is displayed that shows the currently casting media metadata and playback controls.

• Lock Screen: Android only. When the user is casting content and navigates (or the device times out) to the lock screen, a media lock screen control is displayed that shows the currently casting media metadata and playback controls.

The following guide includes descriptions of how to add these widgets to your app.

Add a Cast Button

The Android MediaRouter APIs are designed to enable media display and playback on secondary devices. Android apps that use the MediaRouter API should include a Cast button as part of their user interface, to allow users to select a media route to play media on a secondary device such as a Cast device.

The framework makes adding a MediaRouteButton as a Cast button very easy. You should first add a menu item or a MediaRouteButton in the xml file that defines your menu, and use CastButtonFactory to wire it up with the framework.

// 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" />

Kotlin

// 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
}

Java

// 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;
}

Then, if your Activity inherits from FragmentActivity, you can add a MediaRouteButton to your layout.

// 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>

Kotlin

// 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)
}

Java

// 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);
}

To set the appearance of the Cast button using a theme, see Customize Cast Button.

Configure device discovery

Device discovery is completely managed by the CastContext. When initializing the CastContext, the sender app specifies the Web Receiver application ID, and can optionally request namespace filtering by setting supportedNamespaces in CastOptions. CastContext holds a reference to the MediaRouter internally, and will start the discovery process when the sender app enters the foreground, and stop when the sender app enters background.

Kotlin

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
    }
}

Java

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;
    }
}

How session management works

The Cast SDK introduces the concept of a Cast session, the establishment of which combines the steps of connecting to a device, launching (or joining) a Web Receiver app, connecting to that app, and initializing a media control channel. See the Web Receiver Application life cycle guide for more information about Cast sessions and the Web Receiver life cycle.

Sessions are managed by the class SessionManager, which your app can access via CastContext.getSessionManager(). Individual sessions are represented by subclasses of the class Session. For example, CastSession represents sessions with Cast devices. Your app can access the currently active Cast session via SessionManager.getCurrentCastSession().

Your app can use the SessionManagerListener class to monitor session events, such as creation, suspension, resumption, and termination. The framework automatically attempts to resume from an abnormal/abrupt termination while a session was active.

Sessions are created and torn down automatically in response to user gestures from the MediaRouter dialogs.

If you need to be aware of the state changes for the session, you can implement a SessionManagerListener. This example listens to the availability of a CastSession in an Activity.

Kotlin

class MyActivity : Activity() {
    private var mCastSession: CastSession? = null
    private lateinit var mSessionManager: SessionManager
    private val mSessionManagerListener: SessionManagerListener<CastSession> =
        SessionManagerListenerImpl()

    private inner class SessionManagerListenerImpl : SessionManagerListener<CastSession?> {
        override fun onSessionStarted(session: CastSession?, sessionId: String) {
            invalidateOptionsMenu()
        }

        override fun onSessionResumed(session: CastSession?, wasSuspended: Boolean) {
            invalidateOptionsMenu()
        }

        override fun onSessionEnded(session: CastSession?, error: Int) {
            finish()
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        mSessionManager = CastContext.getSharedInstance(this).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
    }
}

Java

public class MyActivity extends Activity {
    private CastSession mCastSession;
    private SessionManager mSessionManager;
    private SessionManagerListener<CastSession> mSessionManagerListener =
            new SessionManagerListenerImpl();

    private class SessionManagerListenerImpl implements SessionManagerListener<CastSession> {
        @Override
        public void onSessionStarted(CastSession session, String sessionId) {
            invalidateOptionsMenu();
        }
        @Override
        public void onSessionResumed(CastSession session, boolean wasSuspended) {
            invalidateOptionsMenu();
        }
        @Override
        public void onSessionEnded(CastSession session, int error) {
            finish();
        }
    }

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        mSessionManager = CastContext.getSharedInstance(this).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;
    }
}

Stream transfer

Preserving session state is the basis of stream transfer, where users can move existing audio and video streams across devices using voice commands, Google Home App, or smart displays. Media stops playing on one device (the source) and continues on another (the destination). Any Cast device with the latest firmware can serve as sources or destinations in a stream transfer.

To get the new destination device during the stream transfer, call CastSession#getCastDevice() during the onSessionResumed callback.

See Stream transfer on Web Receiver for more information.

Automatic reconnection

The framework provides a ReconnectionService which can be enabled by the sender app to handle reconnection in many subtle corner cases, such as:

• Recover from a temporary loss of WiFi
• Recover from device sleep
• Recover from backgrounding the app
• Recover if the app crashed

This service is turned on by default, and can be turned off in CastOptions.Builder.

This service can be automatically merged into your app's manifest if auto-merge is enabled in your gradle file.

The framework will start the service when there is a media session, and stop it when the media session ends.

How Media Control works

The Cast framework deprecates the RemoteMediaPlayer class from Cast 2.x in favor of a new class RemoteMediaClient, which provides the same functionality in a set of more convenient APIs, and avoids having to pass in a GoogleApiClient.

When your app establishes a CastSession with a Web Receiver app that supports the media namespace, an instance of RemoteMediaClient will automatically be created by the framework; your app can access it by calling getRemoteMediaClient() method on the CastSession instance.

All methods of RemoteMediaClient that issue requests to the Web Receiver will return a PendingResult object that can be used to track that request.

It is expected that the instance of RemoteMediaClient may be shared by multiple parts of your app, and indeed some internal components of the framework, such as the persistent mini controllers and the notification service. To that end, this instance supports registration of multiple instances of RemoteMediaClient.Listener.

Set media metadata

The MediaMetadata class represents the information about a media item you want to Cast. The following example creates a new MediaMetadata instance of a movie and sets the title, subtitle and two images.

Kotlin

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))))

Java

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))));

See Image Selection on the use of images with media metadata.

Load media

Your app can load a media item, as shown in the following code. First use MediaInfo.Builder with the media's metadata to build a MediaInfo instance. Get the RemoteMediaClient from the current CastSession, then load the MediaInfo into that RemoteMediaClient. Use RemoteMediaClient to play, pause, and otherwise control a media player app running on the Web Receiver.

Kotlin

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())

Java

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());

Also see the section on using media tracks.

4K video format

To check what video format your media is, use getVideoInfo() in MediaStatus to get the current instance of VideoInfo. This instance contains the type of HDR TV format and the display height and width in pixels. Variants of 4K format are indicated by constants HDR_TYPE_*.

Remote control notifications to multiple devices

When a user is casting, other Android devices on the same network will get a notification to also let them control the playback. Anyone whose device receives such notifications can turn them off for that device in the Settings app at Google > Google Cast > Show remote control notifications. (The notifications include a shortcut to the Settings app.) For more detail, see Cast remote control notifications.

Add mini controller

According to the Cast Design Checklist, a sender app should provide a persistent control known as the mini controller that should appear when the user navigates away from the current content page to another part of the sender app. The mini controller provides a visible reminder to the user of the current Cast session. By tapping on the mini controller, the user can return to the Cast full-screen expanded controller view.

The framework provides a custom View, MiniControllerFragment, which you can add to the bottom of the layout file of each activity in which you want to show the mini controller.

<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" />

When your sender app is playing a video or audio live stream, the SDK automatically displays a play/stop button in place of the play/pause button in the mini controller.

To set the text appearance of the title and subtitle of this custom view, and to choose buttons, see Customize Mini Controller.

Add expanded controller

The Google Cast Design Checklist requires that a sender app provide an expanded controller for the media being Cast. The expanded controller is a full screen version of the mini controller.

The Cast SDK provides a widget for the expanded controller called ExpandedControllerActivity. This is an abstract class you have to subclass to add a Cast button.

First, create a new menu resource file for the expanded controller to provide the Cast button:

<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>

Create a new class that extends ExpandedControllerActivity.

Kotlin

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
    }
}

Java

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;
    }
}

Now declare your new activity in the app manifest within the application tag:

<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>

Edit the CastOptionsProvider and change NotificationOptions and CastMediaOptions to set the target activity to your new activity:

Kotlin

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()
}

Java

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();
}

Update the LocalPlayerActivity loadRemoteMedia method to display your new activity when the remote media is loaded:

Kotlin

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()
    )
}

Java

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());
}

When your sender app is playing a video or audio live stream, the SDK automatically displays a play/stop button in place of the play/pause button in the expanded controller.

To set the appearance using themes, choose which buttons to display, and add custom buttons, see Customize Expanded Controller.

Volume control

The framework automatically manages the volume for the sender app. The framework automatically synchronizes the sender and Web Receiver apps so that the sender UI always reports the volume specified by the Web Receiver.

Physical button volume control

On Android, the physical buttons on the sender device can be used to change the volume of the Cast session on the Web Receiver by default for any device using Jelly Bean or newer.

Physical button volume control prior to Jelly Bean

To use the physical volume keys to control the Web Receiver device volume on Android devices older than Jelly Bean, the sender app should override dispatchKeyEvent in their Activities, and call CastContext.onDispatchVolumeKeyEventBeforeJellyBean():

Kotlin

class MyActivity : FragmentActivity() {
    override fun dispatchKeyEvent(event: KeyEvent): Boolean {
        return (CastContext.getSharedInstance(this)
            .onDispatchVolumeKeyEventBeforeJellyBean(event)
                || super.dispatchKeyEvent(event))
    }
}

Java

class MyActivity extends FragmentActivity {
    @Override
    public boolean dispatchKeyEvent(KeyEvent event) {
        return CastContext.getSharedInstance(this)
            .onDispatchVolumeKeyEventBeforeJellyBean(event)
            || super.dispatchKeyEvent(event);
    }
}

Add media controls to notification and lock screen

On Android only, the Google Cast Design Checklist requires a sender app to implement media controls in a notification and in the lock screen, where the sender is casting but the sender app does not have focus. The framework provides MediaNotificationService and MediaIntentReceiver to help the sender app build media controls in a notification and in the lock screen.

MediaNotificationService runs when the sender is casting, and will show a notification with image thumbnail and information about the current casting item, a play/pause button and a stop button.

MediaIntentReceiver is a BroadcastReceiver that handles user actions from the notification.

Your app can configure notification and media control from lock screen through NotificationOptions. Your app can configure what control buttons to show in the notification, and which Activity to open when the notification is tapped by the user. If actions are not explicitly provided, the default values, MediaIntentReceiver.ACTION_TOGGLE_PLAYBACK and MediaIntentReceiver.ACTION_STOP_CASTING will be used.

Kotlin

// 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()

Java

// 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();

Showing media controls from notification and lock screen are turned on by default, and can disabled by calling setNotificationOptions with null in CastMediaOptions.Builder. Currently, the lock screen feature is turned on as long as notification is turned on.

Kotlin

// ... 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()

Java

// ... 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();

When your sender app is playing a video or audio live stream, the SDK automatically displays a play/stop button in place of the play/pause button on the notification control but not the lock screen control.

Note: To display lock screen controls on pre-Lollipop devices, RemoteMediaClient will automatically request audio focus on your behalf.

Handle errors

It is very important for sender apps to handle all error callbacks and decide the best response for each stage of the Cast life cycle. The app can display error dialogs to the user or it can decide to tear down the connection to the Web Receiver.