Enable casting to Chromecast devices (Android v3)

The Google Cast framework enables a viewer to stream video and audio content to a compatible TV or sound system. By enabling the Google Cast framework in your app, a viewer can use a cast button to stream your content to a Chromecast-enabled device on a shared network connection.

🚧

• The JWP SDK supports casting to the Default Media Receiver and to Styled Media Receivers.

• Custom receivers are not officially supported. However, if the video playback implements the same interface used in the Default Media Receiver, you may be able to initiate a casting session with a custom receiver.

• To specify a receiver, specify a media receiver app ID when initializing the CastManager.

The following sections explain how to enable the Google Cast framework for your Android app:

• Add SDK dependencies for Google Cast
• Configure your app for Google Cast
• Add a cast button

After completing the steps in each section, a viewer with be able to begin a casting session from your app.

📘

You can also refer to our JWP SDK for Android - Chromecast Demo. This application contains an example implementation of Chromecast using the JWP SDK for Android.

You can clone the repository into your Android Studio workspace: git clone [email protected]:jwplayer/jwplayer-android-best-practice-apps.git.

Add SDK dependency for Google Cast

To use the Google Cast framework, you must add a dependency to your app. You can use Maven or manually add the dependency.

Use Maven

1. In Android Studio, open the build.gradle file for your app.
2. Add the com.longtailvideo.jwplayer:jwplayer-chromecast:x.x.x dependency. Be sure the version number of the module (x.x.x) matches the version number you use for the jwplayer-core and jwplayer-common dependencies.
3. Sync Gradle.

dependencies {
    ...
    implementation 'com.longtailvideo.jwplayer:jwplayer-chromecast:x.x.x'
}

Manually add the .aar dependency

1. In Android Studio, open your app.
2. Click File > New > New Module... > Import .JAR / .AAR Package.
3. Click Next.
4. Select jwplayer-chromecast:x.x.x.aar from your computer.
5. Click Finish.
6. Click File > Project Structure... > Modules > App > Dependencies.
7. Click the plus sign in the main panel.
8. Select Module dependency.
9. Select jwplayer-chromecast:x.x.x.
10. Click OK.

Configure your app for Google Cast

Now that you have added the Google Cast dependency, you must configure your app:

1. Implement the OptionsProvider interface. This interface supplies options needed to initialize CastContext. CastContext is a global singleton object that coordinates all interactions of the framework.
   
   This interface creates an instance of LaunchOptions that defines how the receiver application is launched. For example, setLanguage() allows you to set the language to be used by the receiver application.
   
   This interface also creates an instance of CastOptions that defines the behavior of the framework. For example, setReceiverApplicationId() allows you to filter discovery results and to launch the receiver app when a cast session starts.

public class CastOptionsProvider implements OptionsProvider {

    @Override
    public CastOptions getCastOptions(Context context) {
        LaunchOptions launchOptions = new LaunchOptions.Builder()
            .setLocale(Locale.US)
           .build();
            
        CastOptions castOptions = new CastOptions.Builder()
            .setReceiverApplicationId(context.getString(R.string.app_id))
            .setLaunchOptions(launchOptions);
            .build();

        return castOptions;
    }

    @Override
    public List<SessionProvider> getAdditionalSessionProviders(Context context) {
        return null;
    }
}

2. In the AndroidManifest.xml of the sender app, use a <meta-data/> element to declare the fully-qualified name of the implemented OptionsProvider.

<application>
    ...
    <meta-data
        android:name="{options_provider_class_name}"
        android:value="com.foo.CastOptionsProvider" />

</application>

3. Get a reference to your CastContext within the casting activity.

public class CastActivity extends AppCompatActivity {

    @Override
    public void onCreate() {
        ...
        CastContext castContext = CastContext.getSharedInstance(this);
    }
}

Add a cast button

The MediaRouteButton allows your viewers to select a Chromecast-enabled device. During the cast session, the MediaRouteButton provides a customizable dialog that allows your viewers to play, pause, or stop a casting session.

To add a cast button to your app, use the following steps:

1. Add a menu item or a MediaRouteButton in the .xml file that defines your menu.
2. Use CastButtonFactory to wire it up with the framework.

The following sections illustrate two approaches to complete the previous steps.

Approach 1: Add a MediaRouteButton to the ActionBar

// 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="android.support.v7.app.MediaRouteActionProvider"
    app:showAsAction="always" />

// Then override the onCreateOptionMenu() for each of your activities.
// CastActivity.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;
}

Approach 2: Add a MediaRouteButton to the layout of an Activity

As mentioned above, if you use this approach, you should include the MediaRouteButton in the layout of the Activity since the ActionBar is usually hidden when in fullscreen mode. This allows your viewers to begin a casting session when in fullscreen mode.

1. Add a MediaRouteButton to the layout of an Activity.

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

    <android.support.v7.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>

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

2. Add a menu item to menu_main.xml to add the MediaRouteButton to the ActionBar.

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

3. In the Activity, override onCreateOptionsMenu().

@Override
public boolean onCreateOptionsMenu(Menu menu) {
        // Inflate the menu
    getMenuInflater().inflate(R.menu.menu_jwplayerview, menu);

    // Register the MediaRouterButton
    CastButtonFactory.setUpMediaRouteButton(getApplicationContext(), menu, R.id.media_route_menu_item);
    return true;
}

Next step

Add JWPlayerFragment, JWPlayerSupportFragment, or JWPlayerView to an activity. Be sure that the activity is a descendant of FragmentActivity of the android.support.v4 support library.

Additional resources

Visit Google Cast to discover additional feature and customization options.

FAQ