Developing Chromecast Ready Application for Android Platform

06 Mar 2014
Chromecast app development tutorial by Lemberg Android developers.

1.What is Chromecast and how does it work?

Chromecast, latest Google’s gadget allows users to stream media from their smartphones to TV.

This 2.83-inch and $35 device was announced on July 24, 2013 and was named Time's 2013 Gadget of the Year. Basically, it’s a screen sharing technology that allows content streaming from phone, tablet or laptop to large display device like TV.

After initial release Chromacast SDK was in a beta stage, and that  was limiting usage of the device. But on February 3, 2014 Google released final SDK version.

Now, the number of apps that supports Chromecast  is rapidly growing, so we decided to describe our experience of developing a Chromecast ready application for Android. This article covers the topic of developing an Android Chromecast-ready application: below you’ll find some notes, comments and advice for the developers, as well as code samples and source code of the app built by Lemberg’s team.

How does it work?

Chromecast device is running special version of Chrome browser, that can run special Web applications (named “Receiver” application). These applications goals are to deliver media content to Chromecast users. But Chromecast devices have no direct controls, so obviously some external stuff should be used and, as noted earlier, it can be either mobile app or Web app (named “Sender” application).

So, with a help of sender applications you can control a Chromecast device. But in what way?

This can be done through common WiFi network - i.e. both Sender and Receiver applications should be connected to the same WiFi network. This channel is bidirectional so “sender” app can receive events from “receiver” application. For example, “sender” app can issue a command to play some media stream, while “Receiver” application will notify “Sender” app about playing status and position.

2. Application development

In general, Chromecast application development involves development of sender and Receiver applications. As was noted earlier, sender app can be either mobile app or web app, although it is not restricted to that. Receiver app is a special form of web app which is capable of running on a Chromecast device.

In this article, we will describe a development of general Chromecast application which will allow messages exchange between sender and receiver parts. The app we have developed can be used as a skeleton for further development.

But before we begin we need to setup Chromecast device and register our application.

2.1. Chromecast setup

Setup procedure is described here.

2.2. Registering an application

You need to register your application in order to get application ID (which will be used in both “sender” and “receiver” applications).

Registration procedure is described here link.

2.3. Developing “Sender” application

In this article, we will cover the process of “sender” application development. However, in order to operate, “Sender” application requires “Receiver” app to be built. So we can check the results only after developing a “Receiver” app.

Also, developing a “sender” application for Android is described here.

In our case, “Sender” application is an Android app which uses set of technologies and libraries to communicate with “Receiver” application.

2.3.1. Prerequisites:

2.3.2. Steps for creating a skeleton

Create empty Android application and add the following libraries as dependencies:

  • android-sdk\extras\android\support\v7\appcompat
  • android-sdk\extras\android\support\v7\mediarouter
  • android-sdk\extras\google\google_play_services\libproject\google-play-services_lib

Specify minimum Android version:

Now create an activity which extends ActionBarActivity.

2.3.3. Implementation

There are several key states in application functionality:

  • Device discovery
  • Managing application session
  • Messages exchange between Sender application and Receiver application

Lets describe all stages in detail:

1) Device discovery:

Device discovery can be launched by pressing the “Cast” button. There are several ways to show this button, but we will use MediaRouter ActionBar provider.

Add the following menu item to your menu:

The following fields are involved in the process:

Initialize mediaRouter and mediaRouteSelector in your onCreate method:

Configure your action provider:

and manage your callback in onStart and onStop methods:

APP_ID is a string identifier obtained during application registration in chapter 2.2

Now connect Android device to the same WiFi network as Chromecast device is, and launch the application (note that receiver application should be already available. It is very simple in our case so you can use it from provided sources. We will return to it back soon).

If all requirements are met “cast” icon will appear in a top right corner. Pressing it will open dialog with a list of available devices allowing you to connect to one of them. After connecting the icon will become “blue”, indicating that connection is established. Clicking it once again will open another dialog which will allow you to change sound “volume” on Chromecast device and to disconnect from it:

Connecting Chromecast device. Chromecast Android tutorial by Lemberg

2) Managing application session:

To manage application session, we will introduce a bunch of fields and methods:

as well as several listeners:

Now, if you launch the application and connect to Chromecast, “Receiver” application will be activated and you will see some debug information. Lets expose message exchange subject.

3) Messages exchange between Sender application and Receiver application.

Outgoing message exchange is done with a help of the following method:

private void sendMessage(String message)
{
   if (apiClient != null)
   {
       try
       {
           Cast.CastApi.sendMessage(apiClient, NAMESPACE, message)
                   .setResultCallback(new ResultCallback<Status>()
                   {
                       @Override
                       public void onResult(Status result)
                       {
                           if (!result.isSuccess())
                           {
                               Log.e(TAG, "Sending message failed");
                           }
                       }
                   });
       }
       catch (Exception e)
       {
           Log.e(TAG, "Exception while sending message", e);
       }
   }
}

In our case, NAMESPACE is a string constant equal to "urn:x-cast:com.ls.cast.sample". It is used to distinguish our message channel from the others. The same constant should be used in a Receiver application.

To handle incoming messages we need to register Cast.MessageReceivedCallback instance as a message receiver. We will do this in a connectionResultCallback:

@Override
public void onResult(Cast.ApplicationConnectionResult result)
{
   Status status = result.getStatus();
   if (status.isSuccess())
   {
       applicationStarted = true;

       try
       {
           Cast.CastApi.setMessageReceivedCallbacks(apiClient, NAMESPACE, incomingMsgHandler);
       }
       catch (IOException e)
       {
           Log.e(TAG, "Exception while creating channel", e);
       }
   }
}

public final Cast.MessageReceivedCallback incomingMsgHandler = new Cast.MessageReceivedCallback()
{
   @Override
   public void onMessageReceived(CastDevice castDevice, String namespace, String message)
   {
   }
};

And the last thing we need to do is to perform an actual exchange. In our demo application we created simple layout which allows to show incoming and send outgoing messages. You can check a source code in the attachment.

2.4. Developing “Receiver” application

“Receiver” application is a special form of Web application that can run on a Chromecast device.

The app goal is to display useful information for user and allow user to interact with this information through “Sender” application.

First task of displaying information is usual for web app and can be very diverse: it can be either media application like YouTube or some sort of media players, or it can be some UI heavy app like Google Maps with additional layers, or it can be simple HTML page displaying some statistics.

As for the second task - interoperability between Receiver application and Sender application - Chromecast SDK provides JavaScript library for this. This will allow you to exchange with string messages in any direction. Lets cover this topic.

First of all, keep in mind  that you have to register your app as described in paragraph 2.2. In this case, you will be asked to provide an URL. This URL will be used for storing your Receiver application. Receiver app development will consist of following stages:

1) creating application locally;

2) making it accessible through provided URL;

3) activating app and debugging it using special URL. To activate the application you should simply launch your Sender app and connect to the device. To debug “Receiver” application you need to launch the following URL in a Web browser on your PC: http://{chromecast_ip}:9222/ ,  where CHROMECAST_IP is IP address of your Chromecast device. To obtain IP address of your Chromecast device you should launch Chromecast setup utility either for PC or for Mobile. Note that device used for configuration should have direct WiFi connection with Chromecast device (so your PC should have a WiFi adapter if you choose it for configuring):

Chromecast device sharing settings. Chromecast Android tutorial by Lemberg

Also note that “Send this Chromecast’s serial number when checking for updates” should be enabled to allow debugging. After connecting your browser in order to find IP address you will see the following:

Inspectable WebContents. Chromecast Chrome screen.

Highlighted link refers to running application. If you click on it, new page with Chrome Developer tools will open. Don’t stray it with your local Developer tools - actually it is remote and belongs to your Chromecast device:

Chrome Developer tools page. Chromecast app development.

At last,  we are now ready for the application development.

First of all, we need to include Receiver application SDK:

<script src="https://www.gstatic.com/cast/sdk/libs/receiver/2.0.0/cast_receiver.js">

After that, we need to cast.receiver.CastReceiverManager instance, attach onSenderConnected, onSenderDisconnected and onMessage listeners and start message exchange. We can do this in onLoad listener:

To handle incoming messages the following method will be used:

To send outgoing messages the following method will be used:

Note that several Sender applications can connect to a Receiver app simultaneously. Therefore, we use broadcast method which will send a message to all connected senders.

In our demo application we broadcast a message by timer hit for demonstrative purposes.

And a few more notes. Default text in Receiver application is black, so probably you will need to override it via CSS. Also note that Chromecast screen resolution is 1280x720 pixels.

Hurray! We have created custom Sender and Receiver applications that allow to exchange messages in both directions. This should be enough to understand and use full power of Chromecast device.

And here you can download the source file.

For more on developing apps for connected devices check out our experience page Apps for Connected Devices.

SEE ALSO: