IntroductionHow to update an SDK?THEOplayer 5.0 - Native Mobile iOS/tvOS and Android SDKs
Getting started on Web (Extended)Getting started with the new Web UIGetting started on WebAPI examplesHow to implement Keyboard HotkeysHow to embed an iframeHow to implement a seamless transition between videos?How to work around browser cache with new THEOplayer SDK libraries?How to customise quality selection & labels (MP4)How to get frame-accurate currentTime display in the UI Control barHow to play an LCEVC source with THEOplayerHow to use WebXR with THEOplayerHow to use THEOplayer as a JavaScript module
Android legacy (4.12.x)
Getting started on Legacy Android SDK (4.12.x)Legacy Android SDK (4.12.x) customizationHow to couple the native MediaRouteButton to THEOplayerHow to enable experimental native rendering on AndroidHow to do offline Playback with AES-128 Encrypted Streams on Android
Getting started with the Android UIGetting started on AndroidAndroid Feature IntegrationsMigration from THEOplayer Android/AndroidTV/FireTV SDK 4.x to THEOplayer Android SDK 5.0
iOS legacy (4.12.x)
Getting started on iOSiOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x) CustomizationMy app does not want to build for the app storeHow to bypass copy() not working in Safari consoleHow to couple the native GCKUICastButton to THEOplayeriOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x) Touch-events (gestures)Building for iOS Simulator, but the linked and embedded framework THEOplayerSDK.framework was built for iOS + iOS SimulatorHow to implement custom local network access (LNA) interstitial dialog for Chromecast
Getting started guide for THEOplayer iOS/tvOS SDK 5.0THEOplayer iOS/tvOS 5.0 Feature IntegrationsMigration from THEOplayer iOS and tvOS SDK 4.x to THEOplayer iOS/tvOS SDK 5.0+
Android TV Legacy (4.12.x)
Getting started on Android TV Legacy (4.12.x)
Getting started on tvOS
Getting started on ChromecastChromecast Application Customization
Getting Started on webOS
Getting started on TizenInstalling the Tizen developer toolsSetting up a Tizen device for debuggingDeploying a test app on a physical Tizen deviceDeploying a test app on a Tizen emulator
Getting Started on Roku
Fire TV Legacy (4.12.x)
Getting started on Fire TV Legacy (4.12.x)

Chromecast Application Customization

This article provides information on how to customize the look and feel of a Chromecast Sender application or a Chromecast Receiver Application. Casting approaches

The following topics are discussed:

  1. Background

    1. Google, Chromecast and THEOplayer
    2. Sender application vs Receiver application
  2. Customizing a Sender Application

    1. Default UI
    2. Chromeless UI
    3. Altering Default UI
  3. Customizing a Receiver application

    1. Default Receiver application
    2. Custom Receiver application with THEOplayer Chromecast SDK
    3. Custom Receiver application without THEOplayer Chromecast SDK
  4. Conclusion
  5. Notes
  6. Resources


This section provides background information on Google, THEOplayer SDKs, Sender apps and Receiver apps. Feel free to skip directly to the sections on Customizing a Sender Application or Customizing a Receiver application if you are already familiar with these background topics.

Google, Chromecast and THEOplayer

Google's point of entry to Chromecast is located at https://developers.google.com/cast/docs/developers. In this article, they write about sender applications and their three Cast APIs, and about receiver applications and their four options.

Sender applications

Google describes three Cast APIs: the Android API, the iOS API and the Chrome API. The THEOplayer SDKs integrate these Cast APIs and expose a wrapper API for developers to use instead.

  1. The THEOplayer Android SDK implements the Android API.
  2. The THEOplayer iOS SDK implements the iOS API.
  3. The THEOplayer Web SDK implements the Chrome API.

Receiver applications

Google describes four types of receiver applications:

  1. Default Media Receiver
  2. Styled Media Receiver
  3. Custom Receiver
  4. Android TV Receiver

The THEOplayer Chromecast Receiver SDK fits in the category of a "Custom Receiver". You integrate this THEOplayer SDK in your HTML5 Chromecast Receiver application.

Sender application vs Receiver application

When talking about customizing a Chromecast application, one needs to make a distinction between customizing a Sender application versus a Receiver application.

A Chromecast Sender application is the application on a "sender device" (e.g. smartphone, browser, ...) which initiates the Chromecast session. You use the Sender application to start (and stop) Chromecast playback, to pause the video or to mute it, to seek to a different position in the scrub bar, and so on. The unique UI components related to Chromecast in a Sender application are limited to a Chromecast button which starts/stops a Chromecast session. The default controls (e.g. play, pause, scrub bar) are used to control the Receiver application.

In a Sender application, you use either the THEOplayer Web, iOS or Android SDK.

A Chromecast Receiver application is the application which is loaded on your Chromecast-enabled device (e.g. Chromecast Ultra, Android TV, ...). The UI of a Receiver application is typically quite simple:

  1. When a video is playing, the video is playing fullscreen without any elements overlaying it.
  2. When a video is paused, there is timeline indicating the playhead position and an element (e.g. a pause button) indicating that the playback is paused. Sometimes, when a video is paused, a poster image (i.e. thumbnail) and some text are shown to describe the active content.
  3. When an app and/or stream starts to load, you might see a brand logo and/or a spinning wheel.

In a Receiver application, you use the THEOplayer Chromecast Receiver SDK.

Customizing a Sender application

If you are using the THEOplayer Web, iOS or Android SDK in your Sender application, confirm that the chromecast module is enabled for your SDK. This feature exposes a Chromecast API you can benefit from. Additionally, ensure that you include the Chromecast library.

Please refer to "Connecting from custom Sender applications" if you are not using THEOplayer's chromecast feature.

Generally speaking, there are three types of user interfaces:

  1. Default UI: you use THEOplayer's default UI, and you're happy with it.
  2. Chromeless UI: you've build a Chromeless UI from scratch on top of THEOplayer.
  3. Altering Default UI: you use THEOplayer's default UI, but you've changed some things around. (e.g. different colors, a new button, ....)

Default UI

THEOplayer automatically inserts a Chromecast button in its default video player UI if you are using THEOplayer's default UI. Chromecast button The UI of this button changes when the Chromecast state changes. Please see below if you want to alter this default UI.

Chromeless UI

You are in charge of all UI components if you are using THEOplayer's Chromeless UI. Typically, you want to insert a Chromecast button, and connect that button with our Cast API to start (e.g. player.cast.chromecast.start()) and stop (player.cast.chromecast.stop()) a Chromecast session. Additionally, you might want to change the appearance of this button when the state of your casting session transitions (e.g. player.cast.chromecast.addEventListener('statechange', function() {...});).

Familiarize yourself with the above APIs if you want to change the appearance of your Chromeless UI and its relation to Chromecast.

Altering Default UI

If you are using THEOplayer's default UI, but want to use your own button instead, then you can hide THEO's default button, and insert a new one instead. You also need to use our Cast API described in the above "Chromeless UI" section.

Customizing a Receiver application

Three Receiver application set-ups are common:

  1. You connect with THEOplayer's default Receiver application.
  2. You connect with a custom Receiver application powered by the THEOplayer Chromecast Receiver SDK.
  3. You connect with a custom Receiver application which doesn't contain any THEOplayer SDK or code.

You can provide Chromecast metadata in all three set-ups. Providing Chromecast metadata will make your Receiver application show relevant info (e.g. a title, a thumbnail, ...) when your application is buffering or paused.

Default Receiver application

If you are connected to THEOplayer's default Receiver application, you cannot modify its appearance.

If you want to change the UI, you need to connect your sender application with a different Receiver application ID.

Custom Receiver application with THEOplayer Chromecast SDK

You can build a custom Receiver application by using our Chromecast Receiver SDK. Once you went through its Getting Started Guide, you'll notice that the UI is similar to the default UI. However, through this approach, you have the option to alter the UI as described by the Getting Started Guide.

Custom Receiver application without THEOplayer Chromecast SDK

You can connect your sender application with a custom Receiver application which does not use the THEOplayer Chromecast SDK. Naturally, you're responsibile for the look and feel of this custom Receiver application.


Identify whether you want to adjust the UI and UX of the Sender application or the Receiver application.

  • If it's the Sender application, determine whether you are changing a Sender app which leverages the THEOplayer Web, iOS or Android SDK to enable casting.
  • If it's the Receiver application, determine whether you are changing our default Receiver application, a custom Receiver application using the THEOplayer Chromecast SDK or 3) a custom Receiver application which is not using the THEOplayer Chromecast.

Then, decide which states and which components you want to customize. Finally, identify which THEOplayer APIs are relevant for your use-cases.


  • Google describes their Chromecast UX guideliness at https://developers.google.com/cast/docs/ux_guidelines/.
  • This article is currently categorized under the "Getting Started" guides of our Chromecast SDK, which is also known as our Chromecast Receiver SDK. Naturally: you leverage a Chromecast Receiver SDK in a Chromecast Receiver application. In result, this categorization might be confusing to some readers, because we have discussed concepts and APIs which relate to a Sender application. However, we do feel that it's valuable to discuss the bigger picture surrounding a Chromecast Receiver SDK, and that includes its relationship with a Sender application, and how to customize both.


Make sure to follow us on GitHub!
Copyright © 2022. All Rights Reserved.
New York