Setting up basic Google Cast Support

Overview

This article is designed to help developers seamlessly incorporate Google Cast functionality into their Android applications, enabling users to cast video and audio content from their Android devices to Google Cast-enabled devices, such as Chromecast. For more details on the Google Cast SDK please visit the official documentation.

The Player Android SDK has support for all essential casting-related features. For further information please refer to the CAF Support page.

To explore a comprehensive example of integrating Google Cast support with the Android Player SDK, please visit the public samples on GitHub.

This article aims to assist developers in effortlessly integrating Google Cast functionality into their Android applications. This integration enables users to cast video and audio content from their Android devices to Google Cast-enabled devices, like Chromecast. For more details on the Google Cast SDK, please visit the official documentation.

The Player Android SDK supports all essential casting-related features. For further information, please refer to the CAF Support page.

To discover a detailed example of how to integrate Google Cast support with the Android Player SDK, please visit the public samples.

Prerequisites

• Basic understanding of Android development with Kotlin
• Bitmovin Player Android SDK added to your project (see Getting Started guide)
• A Cast-enabled device available on your local network for testing purposes

Preparing your application

1. Adding the cast framework dependency

implementation("com.google.android.gms:play-services-cast-framework:$currentVersion")

implementation 'com.google.android.gms:play-services-cast-framework:$currentVersion'

Make sure to replace $currentVersion with the officially supported Cast SDK version for the current Bitmovin Android Player SDK version.

👍

Good to know

The officially supported Cast SDK version for the current Bitmovin Android Player SDK version can be found in the API reference.

When the officially supported Cast SDK version changes, this is announced in our release notes. If not stated otherwise, other Cast SDK versions are expected to be compatible but not officially supported.

We strongly recommend using the officially supported version to avoid potential issues.

2. Updating the manifest file

The following code declares the default ExpandedControllerActivity and BitmovinCastOptionsProvider in the Android manifest:

<activity
        android:name="com.bitmovin.player.casting.ExpandedControllerActivity"
        android:exported="true"
        android:label="@string/app_name"
        android:launchMode="singleTask"
        android:screenOrientation="portrait">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
        </intent-filter>
        <meta-data
            android:name="android.support.PARENT_ACTIVITY"
            android:value="com.package.of.parent.activity.MainActivity" />
</activity>

<meta-data
      android:name="com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
      android:value="com.bitmovin.player.casting.BitmovinCastOptionsProvider" />

3. Initializing the cast manager

BitmovinCastManger.initialize() has to be called before using any cast related features. We recommend calling it in the onCreate function of your application.

class SampleApplication : Application() {
    
    override fun onCreate() {
        super.onCreate()
        BitmovinCastManager.initialize()
    }
}

public class SampleApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        BitmovinCastManager.initialize();
    }
}

This call can be used to configure a custom Cast-Receiver application as well as a message namespace and a custom ExpandedControllerActivity.

In addition, each Activity that uses Cast related API's has to call the following function before using any cast related API, e.g. in the Activity.onCreate function:

BitmovinCastManager.updateContext(context)

BitmovinCastManager.updateContext(context);

Cast related functionality

When using the default Bitmovin Player UI, it features a Cast button that automatically appears once a Cast-enabled device is detected on the local network:

Clicking this button opens the Cast dialog, displaying a list of discovered Cast devices. For those utilizing a custom UI or initiating a cast session programmatically, the Player.castVideo function can be invoked to launch the cast dialog.

Upon selecting a Cast device, the Cast receiver app on that device starts, and the video is loaded. The Cast-enabled device will begin playback from the current local playback position, depending on the local playback state.

The presence of an active connection to a Cast-enabled device can be verified by calling the Player.isCasting function.

While casting, any calls to the Player API—such as selecting subtitles, seeking, or changing volume—affect remote rather than local playback. The API documentation will indicate if a particular function is not supported during casting.

A Cast session can be ended by clicking the Cast button again or by calling Player.castStop. This action brings up a dialog allowing the user to disconnect from the Cast-enabled device. The remote playback state, including playhead position and pause state, will transition back to the local player.

For transmitting additional information between a custom web Cast-Receiver implementation and the player, the BitmovinCastManager.sendMessage and BitmovinCastManager.addMessageReceivedCallback functions can be utilized. An overview of CAF Receiver apps is available here. Bitmovin also provides a basic example of a receiver app, which includes a simple HTML page with the video element and a reference to the Bitmovin SDK. This example is available on GitHub.

Configuring the Cast behaviour

The Cast functionality can be configured by passing a RemoteControlConfig as part of the PlayerConfig to the Player during its creation.

Events

During an active cast session, most events are emitted in the same manner as they are during local playback. However, there are several dedicated events that signify notable milestones in the casting lifecycle. Please refer to the corresponding API reference for a detailed description.

CastAvailable
CastStart
CastStarted
CastStopped
CastTimeUpdated
CastWaitingForDevice

Trouble shooting

For a comprehensive approach to troubleshooting, we highly recommend consulting our detailed guide on How to debug streams on Chromecast devices. Additionally, the publication of Info, Warning, and Error events can provide initial insights into any potential issues. For further details, please visit our documentation on Logging in the Android Player SDK.