As users connect their televisions, home theater systems and music players with wireless technologies, they want to be able to play content from Android apps on these larger, louder devices. Enabling this kind of playback can turn your one-device, one-user app into a shared experience that delights and inspires multiple users.
The Android media router APIs are designed to enable media display and playback on these secondary devices. There are two main approaches you can use to play content using these APIs:
This guide explains how your app can deliver media to secondary playback devices using either of these approaches.
The media router APIs enable a broad range of media output to playback equipment connected to Android devices through wireless and wired means. To enable these connections, the media router framework abstracts the logical paths for audio and video output for an Android device. This architecture allows your app to quickly channel media content to connected playback devices such as home theaters and sound systems that provide Android media route support.
In order to use this framework within your app, you must get an instance of the {@link android.support.v7.media.MediaRouter} framework object and attach a {@link android.support.v7.media.MediaRouter.Callback} object to listen for events in available media routes. Content channelled through a media route passes through the route's associated {@link android.support.v7.media.MediaRouteProvider} (except in a few special cases, such as a Bluetooth output device). The following diagram provides a high-level view of the classes your app can use to play content with the media router framework.
Figure 1. Overview of key media router classes used by apps.
Manufacturers of media playback hardware that is not supported by the media router framework
can add support for their devices by implementing a
{@link android.support.v7.media.MediaRouteProvider} and distributing it as an application.
For more information on implementing a media route provider, see the {@link
android.support.v7.media.MediaRouteProvider} reference documentation and the v7-mediarouter
support library sample {@code
The media router APIs are provided as part of the Android Support Library version 18 and higher, in the v7-mediarouter support library. Specifically, you should use the classes in the {@link android.support.v7.media} package for media router functions. These APIs are compatible with devices running Android 2.1 (API level 7) and higher.
Caution: There is another set of media router APIs provided in the {@link android.media} that have been superseded by the v7-mediarouter support library. You should not use the {@link android.media} classes for media router functions.
In order to use the {@link android.support.v7.media} media router classes, you must add the v7-mediarouter support library package to your app development project. For more information on adding support libraries to your app development project, see Support Library Setup.
Android apps that implement the media router 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 output device. The media router framework provides a standard interface for the button, which you should use to help users recognize and use the feature in your app. Figure 2 illustrates how the Cast button should appear in an app.
Figure 2. A Cast button shown on the right side of the action bar.
Caution: When implementing an activity that provides a media router interface you must extend either {@link android.support.v7.app.ActionBarActivity} or {@link android.support.v4.app.FragmentActivity} from the Android Support Library, even if your {@code android:minSdkVersion} is API 11 or higher.
The recommended way to implement the Cast button user interface is to extend your activity from {@link android.support.v7.app.ActionBarActivity} and use the {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method to add an options menu. The Cast button must use the {@link android.support.v7.app.MediaRouteActionProvider} class as its action:
<?xml version="1.0" encoding="utf-8"?>
<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="android.support.v7.app.MediaRouteActionProvider"
app:showAsAction="always"
/>
</menu>
For more information about implementing the action bar in your app, see the Action Bar developer guide.
Once you have added the Cast button to your user interface, you must attach a media route selector object. Building a selector is discussed in the next section.
If you do not want a menu in your action bar, you can also add a Cast button to your app using {@link android.support.v7.app.MediaRouteButton}. If you choose this approach, you should add this button to your app's action bar according to the Google Cast Design Checklist. You must also attach a media route selector to the button using the {@link android.support.v7.app.MediaRouteButton#setRouteSelector setRouteSelector()} method.
For guidelines on incorporating the Cast button into your application, review the Google Cast Design Checklist.
When a user presses the Cast button, the media router framework looks for available media routes and presents a list of choices to the user, as shown in figure 3.
Figure 3. A list of available media routes, shown after pressing the Cast button.
The types of media routes that appear on this list—Remote Playback, Secondary Output or others—are defined by your app.You define these type by creating a {@link android.support.v7.media.MediaRouteSelector}, which accepts {@link android.support.v7.media.MediaControlIntent} objects provided by the framework and other media route providers created by you or other developers. The framework-provided route categories are as follows:
When creating a {@link android.support.v7.media.MediaRouteSelector} object, use the {@link android.support.v7.media.MediaRouteSelector.Builder} class to create the object and set the media playback categories (control categories), as shown in the following code sample:
public class MediaRouterPlaybackActivity extends ActionBarActivity {
private MediaRouteSelector mSelector;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// Create a route selector for the type of routes your app supports.
mSelector = new MediaRouteSelector.Builder()
// These are the framework-supported intents
.addControlCategory(MediaControlIntent.CATEGORY_LIVE_AUDIO)
.addControlCategory(MediaControlIntent.CATEGORY_LIVE_VIDEO)
.addControlCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)
.build();
}
}
The media router framework uses this selector object to provide an interface for selecting media routes that your app supports, as shown in figure 3. Once you have defined this selector, you attach it to the {@link android.support.v7.app.MediaRouteActionProvider} object associated with the Cast menu item, as shown in the following code sample:
@Override
public boolean onCreateOptionsMenu(Menu menu) {
super.onCreateOptionsMenu(menu);
// Inflate the menu and configure the media router action provider.
getMenuInflater().inflate(R.menu.sample_media_router_menu, menu);
// Attach the MediaRouteSelector to the menu item
MenuItem mediaRouteMenuItem = menu.findItem(R.id.media_route_menu_item);
MediaRouteActionProvider mediaRouteActionProvider =
(MediaRouteActionProvider)MenuItemCompat.getActionProvider(
mediaRouteMenuItem);
mediaRouteActionProvider.setRouteSelector(mSelector);
// Return true to show the menu.
return true;
}
Once you have made these changes to your app, you might expect the Cast button to appear in your activity. Alas, it does not (unless your device is already paired with a Wireless Display). In most cases, you must also connect with the media route framework, which is discussed in the next section.
In order to connect to a media route selected by the user, your app must obtain the {@link android.support.v7.media.MediaRouter} framework object and then attach a {@link android.support.v7.media.MediaRouter.Callback} object. The callback object receives messages from the media router framework when a route is selected, changed, or disconnected by the user.
To obtain an instance of the {@link android.support.v7.media.MediaRouter} framework object, call {@link android.support.v7.media.MediaRouter#getInstance MediaRouter.getInstance()} from the {@link android.app.Activity#onCreate onCreate()} method of an activity that supports the media router API.
Note: The {@link android.support.v7.media.MediaRouter} object is a singleton that is maintained by the framework. However, once your application obtains an instance of the object you must retain that instance until your application terminates to prevent it from being garbage collected.
The media router framework communicates with an app through a callback object that you attach to the {@link android.support.v7.media.MediaRouter} framework object. An app that uses the media router framework must extend the {@link android.support.v7.media.MediaRouter.Callback} object in order to receive messages when a media route is connected.
There are several methods in the callback that you can override to receive information about media router events. At minimum, your implementation of the {@link android.support.v7.media.MediaRouter.Callback} class should override the following methods:
The methods of your {@link android.support.v7.media.MediaRouter.Callback} implementation are the first opportunity to determine if the connected route is a remote playback device, such as Chromecast, or a secondary output device, such as a Wireless Display device. If your app supports both device types, then your implementation should branch here, as shown in this sample code:
private final MediaRouter.Callback mMediaRouterCallback =
new MediaRouter.Callback() {
@Override
public void onRouteSelected(MediaRouter router, RouteInfo route) {
Log.d(TAG, "onRouteSelected: route=" + route);
if (route.supportsControlCategory(
MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)){
// remote playback device
updateRemotePlayer(route);
} else {
// secondary output device
updatePresentation(route);
}
}
@Override
public void onRouteUnselected(MediaRouter router, RouteInfo route) {
Log.d(TAG, "onRouteUnselected: route=" + route);
if (route.supportsControlCategory(
MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)){
// remote playback device
updateRemotePlayer(route);
} else {
// secondary output device
updatePresentation(route);
}
}
@Override
public void onRoutePresentationDisplayChanged(
MediaRouter router, RouteInfo route) {
Log.d(TAG, "onRoutePresentationDisplayChanged: route=" + route);
if (route.supportsControlCategory(
MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)){
// remote playback device
updateRemotePlayer(route);
} else {
// secondary output device
updatePresentation(route);
}
}
}
After defining your callback object for the media router, you still need to attach it to the main media router framework object. The next section discusses the appropriate way to attach your callbacks for media routes.
Since media routes are a shared interface, your app must attach and detach your {@link android.support.v7.media.MediaRouter.Callback} object as your app starts up and shuts down. To accomplish this, you must add and remove your app's callback object from the media router framework as part of your app's activity lifecycle. This approach allows other apps to make use of media route outputs while your app is in the background or not running.
Note: If you are writing a music playback app and want to allow music to play while your app is in the background, you must build a {@link android.app.Service} for playback and connect that service and it's lifecycle to the media router framework.
The following code sample demonstrates how to use the lifecycle methods to appropriately add and remove your app's media router callback object:
public class MediaRouterPlaybackActivity extends ActionBarActivity {
private MediaRouter mMediaRouter;
private MediaRouteSelector mSelector;
private Callback mMediaRouterCallback;
// your app works with so the framework can discover them.
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// Get the media router service.
mMediaRouter = MediaRouter.getInstance(this);
...
}
// Add the callback on start to tell the media router what kinds of routes
// your app works with so the framework can discover them.
@Override
public void onStart() {
mMediaRouter.addCallback(mSelector, mMediaRouterCallback,
MediaRouter.CALLBACK_FLAG_REQUEST_DISCOVERY);
super.onStart();
}
// Remove the selector on stop to tell the media router that it no longer
// needs to discover routes for your app.
@Override
public void onStop() {
mMediaRouter.removeCallback(mMediaRouterCallback);
super.onStop();
}
...
}
You should add and remove the media router callback only in the {@link android.app.Activity#onStart onStart()} and {@link android.app.Activity#onStop onStop()} lifecycle methods. Do not include these calls in the {@link android.app.Activity#onResume onResume()} or {@link android.app.Activity#onPause onPause()} methods.
Note: The media route framework also provides a {@link android.support.v7.app.MediaRouteDiscoveryFragment} class, which takes care of adding and removing the callback for an activity.
Now when you run your application, you should see a Cast button appear in your activity. When you touch the button, a route selection dialog appears as shown in figure 3, allowing your user to select an available media route. Make sure you have a supported device available on your local network when testing this interface.
Note: In order for Wireless Display routes to show up in the media route selection dialog, users must enable this option in the Settings app. The option is under the Display category and is called Cast screen on Android 4.4 (KitKat) and higher devices. For more information on enabling this feature see this Wireless display support page.
The remote playback approach sends control commands to a secondary device to initiate playback and to control playback that is in progress (pause, rewind, fast-forward, volume up and down). Using this approach, the receiving device (such as a Chromecast) is responsible for retrieving and rendering content.
When your app supports this type of media route, you must create a {@link android.support.v7.media.RemotePlaybackClient} object using a remote playback {@link android.support.v7.media.MediaRouter.RouteInfo} object received through your app's {@link android.support.v7.media.MediaRouter.Callback} object. The following sample code demonstrates a controller method that creates a new remote playback client and sends it a video for playback:
private void updateRemotePlayer(RouteInfo route) {
// Changed route: tear down previous client
if (mRoute != null && mRemotePlaybackClient != null) {
mRemotePlaybackClient.release();
mRemotePlaybackClient = null;
}
// Save new route
mRoute = route;
// Attach new playback client
mRemotePlaybackClient = new RemotePlaybackClient(this, mRoute);
// Send file for playback
mRemotePlaybackClient.play(Uri.parse(
"http://archive.org/download/Sintel/sintel-2048-stereo_512kb.mp4"),
"video/mp4", null, 0, null, new ItemActionCallback() {
@Override
public void onResult(Bundle data, String sessionId,
MediaSessionStatus sessionStatus,
String itemId, MediaItemStatus itemStatus) {
logStatus("play: succeeded for item " + itemId);
}
@Override
public void onError(String error, int code, Bundle data) {
logStatus("play: failed - error:"+ code +" - "+ error);
}
});
}
}
The {@link android.support.v7.media.RemotePlaybackClient} class provides additional methods for managing content playback. Here are a few of the key playback methods from the {@link android.support.v7.media.RemotePlaybackClient} class:
You can use these methods to attach actions to playback controls you provide in your app. Most of these methods also allow you to include a callback object so you can monitor the progress of the playback task or control request.
The {@link android.support.v7.media.RemotePlaybackClient} class also supports queueing of
multiple media items for playback and management of the media queue. For a comprehensive sample
implementation of these features, see {@code SampleMediaRouterActivity} and its associated
classes in the v7 mediarouter support library sample
{@code
For additional information on using the Google Cast API for Chromecast devices, see the Google Cast developer documentation.
The secondary output approach sends prepared media content to a connected secondary device for playback. Secondary devices can include televisions or wireless sound systems and can be attached through wireless protocols or wires, such as an HDMI cable. With this approach, your app is responsible for processing media content for playback (downloading, decoding, synchronization of audio and video tracks), while the secondary device only outputs the content in its final form.
Note: Using the secondary output display routes with the media router framework requires classes that are available only in Android 4.2 (API level 17) and higher, specifically the {@link android.app.Presentation} class. If you are building an app that supports both remote playback and secondary output devices, you must include checks that disable this code below the supported Android version level.
When using a secondary output display with the media router framework, you create a {@link android.app.Presentation} object that contains the content you want to show on that display. The {@link android.app.Presentation} is extended from the {@link android.app.Dialog} class, so can add layouts and views to a {@link android.app.Presentation}.
You should be aware that the {@link android.app.Presentation} object has its own {@link android.content.Context} and {@link android.content.res.Resources}, separate from the app activity that created the object. Having a secondary context is required, because the content of the {@link android.app.Presentation} is drawn on a display that is separate from your app's display on the local Android device. Specifically, the secondary display needs a separate context because it may need to load resources based on its specific screen metrics.
The following code sample shows a minimal implementation of a {@link android.app.Presentation} object, including a {@link android.opengl.GLSurfaceView} object.
public class SamplePresentation extends Presentation {
public SamplePresentation(Context outerContext, Display display) {
super(outerContext, display);
}
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Notice that we get resources from the context of the Presentation
Resources resources = getContext().getResources();
// Inflate a layout.
setContentView(R.layout.presentation_with_media_router_content);
// Add presentation content here:
// Set up a surface view for visual interest
mSurfaceView = (GLSurfaceView)findViewById(R.id.surface_view);
mSurfaceView.setRenderer(new CubeRenderer(false));
}
}
In order to display a {@link android.app.Presentation} object, you should write a controller layer that handles responses to the messages received by the {@link android.support.v7.media.MediaRouter.Callback} object and manages the creation and removal of the {@link android.app.Presentation} object. The controller layer should also handle attaching presentations to a selected {@link android.view.Display} object, which represents the separate physical display device chosen by the user. The controller layer can simply be a method in the activity that supports a secondary display.
The following code sample shows a controller layer for a {@link android.app.Presentation} implemented as a single method. This method handles dismissing invalid presentations when a {@link android.view.Display} is unselected or disconnected, and creates the {@link android.app.Presentation} object when a display device is connected.
private void updatePresentation(RouteInfo route) {
// Get its Display if a valid route has been selected
Display selectedDisplay = null;
if (route != null) {
selectedDisplay = route.getPresentationDisplay();
}
// Dismiss the current presentation if the display has changed or no new
// route has been selected
if (mPresentation != null && mPresentation.getDisplay() != selectedDisplay) {
mPresentation.dismiss();
mPresentation = null;
}
// Show a new presentation if the previous one has been dismissed and a
// route has been selected.
if (mPresentation == null && selectedDisplay != null) {
// Initialize a new Presentation for the Display
mPresentation = new SamplePresentation(this, selectedDisplay);
mPresentation.setOnDismissListener(
new DialogInterface.OnDismissListener() {
// Listen for presentation dismissal and then remove it
@Override
public void onDismiss(DialogInterface dialog) {
if (dialog == mPresentation) {
mPresentation = null;
}
}
});
// Try to show the presentation, this might fail if the display has
// gone away in the meantime
try {
mPresentation.show();
} catch (WindowManager.InvalidDisplayException ex) {
// Couldn't show presentation - display was already removed
mPresentation = null;
}
}
}
Note: When the a user connects to a Wireless Display, the media router framework automatically provides a notification that it is displaying screen content on a connected device.