# Audio Devices 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](https://developers.google.com/cast/docs/audio#sender-apis) 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](https://developers.google.com/cast/docs/audio#memory), below. - Run as expected on a Cast for audio device as well as a regular Chromecast. > [!WARNING] > **Warning:** Do not send a video stream to an audio-only device; doing so may cause the application to fail. ### 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()`](https://developers.google.com/cast/docs/reference/receiver/cast.receiver.CastReceiverManager#getDeviceCapabilities) when the Web Receiver app is loaded. See [Device capabilities](https://developers.google.com/cast/docs/custom_receiver#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](https://developers.google.com/cast/docs/design_checklist/sender#sender-control-volume). See the following device capabilities APIs for senders: - Android: [CastDevice.hasCapabilities](https://developers.google.com/android/reference/com/google/android/gms/cast/CastDevice#hasCapabilities(int%5B%5D)) - iOS: [deviceCapabilities](https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_device#ac9462ff1c1707daa727573b385eb5be3) - Chrome: [chrome.cast.Capability](https://developers.google.com/cast/docs/reference/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](https://developers.google.com/cast/docs/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](https://developers.google.com/cast/docs/design_checklist/sender#sender-control-volume) in the [Design Checklist](https://developers.google.com/cast/docs/design_checklist) - [Android sender volume](https://developers.google.com/cast/docs/android_sender_advanced#how_volume_control_works) - [iOS sender volume](https://developers.google.com/cast/docs/ios_sender_advanced#how_volume_control_works) - [Web sender volume](https://developers.google.com/cast/docs/web_sender/advanced#volume_control) ### 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](https://developers.google.com/cast/docs/reference/messages), to [control playback](https://developers.google.com/cast/docs/reference/messages#MediaComm) 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](https://developers.google.com/cast/docs/reference/messages#MediaMess) 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** [`MediaMetadata`](https://developers.google.com/android/reference/com/google/android/gms/cast/MediaMetadata) with[`MEDIA_TYPE_MUSIC_TRACK`](https://developers.google.com/android/reference/com/google/android/gms/cast/MediaMetadata#MEDIA_TYPE_MUSIC_TRACK) and: - [`MediaMetadata.KEY_TITLE`](https://developers.google.com/android/reference/com/google/android/gms/cast/MediaMetadata#KEY_TITLE) - [`MediaMetadata.KEY_ALBUM_TITLE`](https://developers.google.com/android/reference/com/google/android/gms/cast/MediaMetadata#KEY_ALBUM_TITLE) - [`MediaMetadata.KEY_ARTIST`](https://developers.google.com/android/reference/com/google/android/gms/cast/MediaMetadata#KEY_ARTIST) - [`MediaMetadata.KEY_ALBUM_ARTIST`](https://developers.google.com/android/reference/com/google/android/gms/cast/MediaMetadata#KEY_ALBUM_ARTIST) - **iOS** [`GCKMediaMetadata`](https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_media_metadata) with [`GCKMediaMetadataType`](https://developers.google.com/cast/docs/reference/ios/g_c_k_media_metadata_8h#a24f7de80a98dfc6f8626c01167a97a6a) `GCKMediaMetadataTypeMusicTrack` and: - [`kGCKMetadataKeyTitle`](https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_media_metadata#a81f7e3af3ad677f2f85efcbba6858ee1) - [`kGCKMetadataKeyAlbumTitle`](https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_media_metadata#aa2630f2bd7678f6720fbcf55c70ba396) - [`kGCKMetadataKeyArtist`](https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_media_metadata#add8dff190276b3453a1915e364de1129) - [`kGCKMetadataKeyAlbumArtist`](https://developers.google.com/cast/docs/reference/ios/interface_g_c_k_media_metadata#afc826de43f90a116f6d6b66460ccd4c7) - **Chrome** [`MediaInfo`](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.MediaInfo) with [`MusicTrackMediaMetadata`](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.MusicTrackMediaMetadata) and: - [`MusicTrackMediaMetadata.title`](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.MusicTrackMediaMetadata#title) - [`MusicTrackMediaMetadata.albumName`](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.MusicTrackMediaMetadata#albumName) - [`MusicTrackMediaMetadata.artist`](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.MusicTrackMediaMetadata#artist) - [`MusicTrackMediaMetadata.albumArtist`](https://developers.google.com/cast/docs/reference/chrome/chrome.cast.media.MusicTrackMediaMetadata#albumArtist) 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](https://cast.google.com/publish). - See [Devices](https://developers.google.com/cast/docs/registration#RegisterDevice) 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](https://developers.google.com/cast/docs/registration#RegisterApp). > [!IMPORTANT] > **Note:** Your app must use device filtering by appID in order for it to properly show or hide audio-only devices according to your registration status. See the following documentation about adding filter criteria to your app: > > - Android: [Configure device discovery](https://developers.google.com/cast/docs/android_sender_integrate#configure_device_discovery) > - iOS: [Configure device discovery](https://developers.google.com/cast/docs/ios_sender_integrate#configure_device_discovery) > - Web: [Initialization](https://developers.google.com/cast/docs/web_sender/integrate#initialization) 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. > [!NOTE] > **Note:** Some currently-registered Music \& Audio applications may have been enabled with support for Google Cast for Audio automatically when this feature was launched. Review your app's settings in the [Google Cast SDK Developer Console](https://cast.google.com/publish) to be sure it is represented appropriately. ## 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 any of the GC4A 2.0 devices listed here. GC4A 2.0 does not support Chrome Remote Debugger. If you want to debug your app, Google recommends using the [Cast Debug Logger](https://developers.google.com/cast/docs/debugging/cast_debug_logger). #### Available GC4A 2.0 Devices This is a non-comprehensive list of GC4A 2.0 devices: - Bose: Wifi Speaker and Smart Soundbars - JBL: Charge 5 Wi-Fi / Boombox 3 Wi-Fi / Authentics 200, 300, and 500 - Samsung: Music Frame / Soundbars - LG: Soundbars S90TY/SG10TY/SE70Q/S80Q/S90Q - Bang \& Olufsen Beosound 2 / Beocore Connect - Sonoro Maestro 2 / Meisterstruck 2 - Cambridge Audio MXN10 - KEF LS60 / LSX II - Teufel Motiv Home - Nordic Argon Audio - WiiM CI MOD S / Ultra ### 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 - DRM (com.widevine.alpha \& org.w3.clearkey) - Only software decryption (`SW_SECURE_CRYPTO`) is supported - Subtle Crypto only supports `AES-CBC` decryption GC4A 2.0 does **not** support: - Dynamic module import (to be added in 2024) - CSS - IFrame - TextTracks ### Identification While Cast Receiver applications are expected to be universal for all cast devices, it can sometimes be helpful to identify which device you are running on. GC4A 2.0 Devices can be identified using the user agent string. - All Cast devices contain `CrKey/` and a version. Ex: `CrKey/1.68.000001`. - GC4A 2.0 devices contain `Castlite/` and a version. Ex: `Castlite/1.0`. ### Contact Please contact [gc4a-support-external@google.com](mailto:gc4a-support-external@google.com) if you need help setting up for testing, or are unable to use a Bose speaker.