Overview of Matter Casting
Matter casting enables customers to cast content from iOS and Android apps to Fire TV, Echo Show, and other TVs that support Matter Casting. Customers can browse for content or begin watching content on their phone and cast it to their compatible Fire TV device or Echo Show device. Matter Casting supports media and device controls such as play. pause, navigation, skip forward, back, and volume for customers to control the viewing experience on TVs directly from their phone. Matter Casting also works with your app that runs on Fire TV or Echo Show devices. If your Fire TV app is not already installed, Matter Casting can assist with the installation of your app on a Fire TV or an Echo Show device.
Matter Casting is part of the Matter standard published by the Connectivity Standards Alliance (CSA). It is built around a shared belief that smart home devices should be secure, reliable, and seamless to use. By using Internet Protocol (IP), Matter enables communication across smart home devices, phone app, and cloud services. Fire TV and Echo devices implement Matter Casting as defined in the Matter specification 1.3.
Prerequisites
- Development environment for Android and iOS, preferably with ADB access. Ideally including an IDE and simulator. For example, a Fire TV device running pre-Matter software or a non-Amazon Android TV. This environment allows you to compile, deploy, and debug the sample Matter platform app and content app for Android.
- Access to the source code of your Fire TV and iOS / Android mobile app.
- A Fire TV device that supports Matter Casting. This includes most devices that run Fire OS 7 or higher. Check with your Amazon contact for a list of supported device.
- Download the latest Matter specification from the CSA's website as a point of reference. We recommend downloading the Core, Device Library, and Application Cluster specification. Matter Casting is defined in the Media section in the Application Cluster specification.
Key concepts and terminology
The following are key Matter concepts and terminology relevant to supporting Matter Casting in your content and client app. Refer to the official Matter documentation for more information. Additional open source sample apps are available in Matter's Github repository. The official Matter specification is available on the Connectivity Standards Alliance page.
Casting video player, client, and clusters
In the context of Matter, a video player endpoint (a casting video player or a basic video player) represents a device that is able to play media to a physical output or to a display screen which is part of the device. Fire TV and Echo Show devices are casting video players (player). Your phone Android or iOS app is the casting client (client) of a casting video player and controls the player itself (such as changing the Fire TV's output volume) or specific app (content app) running on the player. For the purposes of this documentation, we will refer to your phone app as the client and your Fire TV app as the content app.
Terminology commonly used in this documentation
Summary of terminology
| Term | Definition |
|---|---|
| Player | Casting video player. |
| Client | Android or iOS app. |
| Content app | Fire TV app. |
| Fabric | Devices or apps in a network that share the same security domain. |
| Commissioning | The process of a client joining the fabric. |
| Commissioner | The player that a customer casts to. |
| Commissionee | The client that discovers players on the network. |
| The message that the client sends to the player. | Casting video player. |
| Validating the identity of the client, by determining the client vendor, and determining which content apps the client is authorized to cast content to. | Casting video player. |
| Information provided for the player to validate the identity of the client and determine which content apps should be granted access. | Casting video player. |
See below for a more thorough description of each.
Player and content apps expose Clusters that provide commands to control behavior from the client. These clusters define what features and experiences you want to support for casting. For example, your content app can define support for D-pad navigation (keypad input cluster), playback controls (media playback), or user login (account login). Fire TV supports the following video player and content app clusters.
| Cluster Name | Target | Description |
|---|---|---|
| On / Off | Video player | Turn Fire TV on or off. |
| Account login | Content app | Commands enabling the user to log into their account. |
| Application launcher | Content app | Interface to launch an app or app install flow on a video player device. |
| Keypad input | Content app | Controls a video player or a content app using action commands such as UP, DOWN, and SELECT. |
| Media playback | Content app | Controlls media playback (PLAY, PAUSE, etc) on a video player device. |
| Target navigator | Content app | Interface for UX navigation within a set of targets. |
Commissioning and obtaining a passcode
Before a client can communicate with the player and its content apps, both need to be part of the same network and the client must join the player’s Matter fabric. In Matter, fabric refers to a set of devices or apps in a network that share the same security domain. The process of a client joining the fabric is referred to as commissioning in Matter. Commissioning occurs once when the customer casts to a player (Commissioner) for the first time.
During commissioning, the client (Commissionee) first discovers players on the network using DNS-SD and presents the resulting list of casting targets to the user. Once the user selects a target player, the client sends a message to the player to request commissioning. This message is called a User Directed Commissioning (UDC) request. This message can contain information about the client, information about how it would like to be commissioned (whether and how to display a passcode entry dialog), and information about the content app it would like to cast to. The player then checks if it has a content app corresponding to information in the UDC request, attempts to obtain a passcode and discriminator for the commissioning session, which can be provided by a content app or input by the user. The passcode is an 8-digit numeric code required to establish a secure connection between the player and the client. Once the player and the client have established a secure connection using the passcode, the player and client exchange a series of messages to commission the client onto the player’s Matter Fabric. Included in this message exchange process is Product Attestation where the client provides its Device Attestation Certificate (DAC). The DAC allows the player to validate the identity of the client (determine the vendor of the client) and use it to determine which content apps the client is authorized to cast content to (which content apps have granted access to the given vendor).
Fire TV supports two methods to obtain the passcode.
Method 1: Manual Entry into the client (Recommended)
When a client connects for the first time to a player, if the corresponding content app does not support the Account Login cluster, or if the GetSetupPIN command does not return a passcode, the user will need to manually enter the passcode into the client. In this scenario, the player (Fire TV) will generate and display a 4-6 digit passcode and display it, instructing the user to enter the passcode into the client. After the user enters the passcode in the client, the client will send a UDC message to the player indicating that it’s ready for commissioning. The player will then commission the client into its fabric. This manual entry into client method works whether the content app is installed on the player or not.
Method 2: Through the content app
When a client connects for the first time to a player, the player identifies the content app corresponding to the client using information provided in the UDC message. The player will then check if the identified content app implements the Account Login cluster by reading the static_matter_cluster file and attempt to use it to obtain the passcode. The Account Login cluster is used for communication between the player and the content app for commissioning. The player invokes the GetSetupPIN command on the content app to request a commissioning passcode, and invokes the login and logout commands to indicate when access from a client is added or removed from the content app. The GetSetupPIN command includes a TempAccountIdentifier argument which is a token (Rotating ID) passed from the client in the UDC message. The content app will typically use its own cloud service to obtain the passcode by matching the TempAccountIdentifier value passed by the client through the UDC command. In this case, the client directly uploads its passcode and the same TempAccountIdentifier value to the cloud service so the cloud service can relay the passcode to the content app. Using the content app method to obtain the passcode allows the player to commission the client without any manual entry of a code by the user.
App attestation
Matter Casting requires that the client provides attestation information to the player. This attestation information makes it possible for the player to validate the client identity and determine which content apps should be granted access. Each content app includes information in its Android manifest file which designates clients that will be granted access. The player uses this information to match a content app with one or more clients. Attestation in Matter is done using a Device or Product Attestation Certificate (DAC), and a Certification Declaration (CD). See Device Attestation Certificate and Certification Declaration for more details.
Additional resources
- The client SDK for iOS and Android can be built from the source using the code found on Matter’s Github repo.
- The source code for a sample content app running on the player can be found on Matter’s Github repo at content-app.
Related topics
Last updated: Jan 26, 2024