Google Cast for audio devices support only audio playback. This guide describes how to optimize Cast applications for audio-only devices and take advantage of the reduced demands on memory, CPU, and network bandwidth utilization.
An app that supports Google Cast for audio must take the following into consideration:
- Google Cast for audio devices do not display video or graphics. However, many audio devices have a display for showing metadata, such as playback state (playing or paused) and progress. Your application must not display such critical user information only on the receiver; critical information, and most of the user interface, must be shown on the sender.
- To run Web Receiver applications properly, Google Cast for audio devices must still render graphics, even though they are not displayed. Since devices might not support hardware-accelerated graphics operations, receiver applications should avoid using graphics-intensive operations such as color gradients, rotation, alpha blending, and re-drawing large objects like progress bars more than once per second.
- Google Cast for audio devices only support Widevine for Digital Rights Management (DRM) protected content.
- For most Google Cast for audio devices, the sender application controls the full volume range of the device (a speaker, for example), not just the volume of the audio source input to the TV, as with a Chromecast device.
- In addition to controlling playback with the sender device (a phone, for example), the app may have to provide for controlling playback with the device's own controllers such as a remote control, on-device buttons, or an external remote application.
- A Google Cast for audio device may support displaying content metadata with a small LCD screen, HDMI output (for soundbars or audio-video receivers), or an external remote application, depending on the specific device UI.
Development
The first step in developing a Cast application to support Google Cast for audio is to develop a Cast application for audio-video, and make sure that it runs on a Chromecast. This document assumes you have developed and tested such an app.
An app may support both audio-video and audio-only devices. It needs to know when it is casting to one versus the other and take measures to ensure the best user experience under the given scenario.
For example, dual video and audio apps (like local/NAS file playback applications) should enable casting to audio-only devices in order to support playing audio files, but the app should not allow the user to send video files to the audio-only device. The app can use the device capabilities APIs for senders described below to determine the content appropriate for the device.
To support Google Cast for audio, your app must do the following:
Support audio-only: streaming music and audio files, radio, etc. The media streamed to the Web Receiver app must not be a video stream. Also, avoid streaming graphics and images to improve application launch time and memory usage. See Memory usage guidelines, below.
Run as expected on a Cast for audio device as well as a regular Chromecast.
Device capabilities
Your app can know whether it is running on an audio-only device by virtue of the device capabilities APIs, available from the device itself or through the sender or receiver APIs.
Device HTTP header
The CAST-DEVICE-CAPABILITIES HTTP header provided by the Cast device during
application launch describes the device capabilities. The device sends a request
with this header to the server hosting the Web Receiver app. The header for an
audio-only device describes the device capabilities with
CAST-DEVICE-CAPABILITIES: {"display_supported":false}.
When your server receives the request from the device, you can use the information in this header to redirect the request to the Web Receiver app which is optimized for audio devices.
Web Receiver API
You can get the same device capabilities object by calling CastReceiverManager.getDeviceCapabilities()
when the Web Receiver app is loaded.
See Device capabilities for more information.
Sender APIs
Each of the Cast sender APIs has the device capabilities information as well. These let your sender app determine which kind of media to send to the receiver. If your app supports both audio and video, it can avoid sending video content to audio-only devices. Also, your app can control the volume using the method most appropriate for the device, as described in the Design Checklist. See the following device capabilities APIs for senders:
- Android: CastDevice.hasCapabilities
- iOS: deviceCapabilities
- Chrome: chrome.cast.Capability
Memory usage guidelines
Web Receiver apps running on audio devices must manage memory usage as follows:
- Avoid downloading or using any image or graphics assets, to reduce memory footprint and shorten the time until playback starts.
- When using Media Source Extensions (MSE), applications must limit the stream buffer to 2MB. If using the Media Player Library (MPL), the application's stream buffer size is already defined by MPL.
- When using HTMLMediaElement, the application's stream buffer size is defined by Chrome based on the stream rate. Limit the audio bitrate to 2 megabits per second, which supports all codecs described in Supported Media (up to 48KHz/16bit).
Volume control
For most Google Cast for audio devices, the sender application controls the device's full volume range, not just the audio source input volume, as with a Chromecast device. This means the volume change increments must be smaller for audio-only applications. See the following documents for guidelines on providing volume control in your app:
- Sender volume controls in the Design Checklist
- Android sender volume
- iOS sender volume
- Web sender volume
Device controls
Google Cast for audio devices may have their own playback controls (such as
buttons, remotes). These use the media playback messages defined for the
urn:x-cast:com.google.cast.media namespace, as described in
Media Playback Messages, to control playback
on the receiver application. Your receiver application must support
these media playback messages to support the device's playback controls.
Also, your sender app should support the Messages from receiver to sender so that if the user changes the media state with the device controls, your sender app can receive a status message from the receiver and update the UI accordingly.
Device display
A Google Cast for audio device may have an LCD screen on the device or a device-specific control application that displays media metadata. Your receiver app must provide this metadata for all audio tracks and ensure it is in sync with the content currently playing to ensure the metadata displays appropriately on the display. If the application is using custom metadata, it must also provide the standard audio metadata (track name, artist name, album title, etc.) as described for each platform below.
The receiver gets the metadata from the sender when it loads the media. In your sender app, with the command to load the media on the receiver, you must specify the fields described below so that the metadata will display on the Google Cast for audio device. Use the following APIs:
Android
MediaMetadatawithMEDIA_TYPE_MUSIC_TRACKand:iOS
GCKMediaMetadatawithGCKMediaMetadataTypeGCKMediaMetadataTypeMusicTrackand:Chrome
MediaInfowithMusicTrackMediaMetadataand:
If the Cast app manages a media queue on the receiver or in the cloud, the
Web Receiver must broadcast any media status updates using the
urn:x-cast:com.google.cast.media namespace so that all senders will be
synchronized.
Registration
You must register your Google Cast for audio device for testing and register your app to support Google Cast for audio devices, by using the Google Cast SDK Developer Console.
- See Devices for more information about registering devices.
- You must check the Supports casting to audio-only devices checkbox when registering your application to allow your app to discover Google Cast for audio devices. See Register your application.
For unpublished apps, such as those used for testing, you must also select the option to support audio-only devices in order for the app to discover audio-only devices.
Google Cast for Audio 2.0
Google Cast for Audio (GC4A) 2.0 is the next generation Cast audio platform designed to target low memory devices, to expand the ecosystem of devices that can stream your content. Because GC4A 2.0 targets audio platforms, the web API set is reduced to align with displayless devices. GC4A 2.0 is rolling out to new and existing speakers that support cast.
Testing and Debugging
As all supported speakers will be transitioning to GC4A 2.0, it's important that audio app developers test their apps on GC4A 2.0. You can test your Cast app for GC4A 2.0 on a production Bose Wi-Fi speakers, JBL Charge 5 Wi-Fi, JBL Authentics, Cambridge Audio, Teuful Motiv Home, LG 2024 Soundbars.
GC4A 2.0 does not support Chrome Remote Debugger. If you want to debug your app, Google recommends using the Cast Debug Logger.
Recommended Basic Test Cases
Testing of all the app features on GC4A 2.0 is recommended. Be sure to include testing of playing all media types (podcasts, streams, etc), pausing, scrubbing, skipping, changing playlists, stopping, and reconnecting Cast.
Supported APIs
GC4A 2.0 supports the following APIs:
- HTML
- JavaScript ECMA 6
- DOMParser
- XMLSerializer
- Document and subclasses
- DocumentFragment
- HTMLMediaElement & HTMLAudioElement
- HTMLVideoElement (can only play Audio content)
- HTMLScriptElement
- HTMLBaseElement
- HTMLTemplateElement
- Custom Elements
- Shadow DOM
- Script modules / async / deferred
- Fetch / XHR
- WebSocket
- MessagePort
- Cookies
- MSE (Media Source Extensions)
- EME (Encrypted Media Extensions)
- Local / Session Storage
GC4A 2.0 does not support:
- Dynamic module import (to be added in 2024)
- CSS
- IFrame
- TextTracks
Contact
Please contact gc4a-support-external@google.com if you need help setting up for testing, or are unable to use a Bose speaker.