-
Notifications
You must be signed in to change notification settings - Fork 37
Chromecast Implementation Documentation WIP
This page will be used to document the different aspects of how the Chromecast Device works and what is needed to create an implementation
Chromecasts use a number of services and mechanisms to make them function. The following is needed for a functioning implementation of a Chromecast:
- DIAL and mDNS Discovery protocols
- Webserver running on port 8008 with Websocket support
- HTTP client to retrieve receiver app information
- A Web Browser Implementation to run the apps
- An implementation of "casts://" protocol running on port 8009
Two protocols are implemented on Chromecast to support discovery, the first is an implementation of the DIAL Protocol over SSDP. This is the primary system used for the old v1 of Google Cast SDK. The second protocol implemented is an mDNS server. This is the primary way of discovering a Chromecast that supports the v2 API.
More information on this protocol can be found here
Chromecasts respond to the following search queries: urn:dial-multiscreen-org:service:dial:1, urn:dial-multiscreen-org:device:dial:1, ssdp:all, upnp:rootdevice, and uuid:{uuid} where {uuid} is the Chromecast's UUID. A response to one of these requests should be the following HTTP response and sent via unicast back to the query sender:
HTTP/1.1 200 OK
CACHE-CONTROL: max-age=1800
DATE: {currentDate}
EXT:
LOCATION: http://{localIP}:8008/ssdp/device-desc.xml
OPT: "http://schemas.upnp.org/upnp/1/0/"; ns=01
01-NLS: baed804a-1dd1-11b2-8973-d7a6784427e5
SERVER: Linux/3.8.13, UPnP/1.0, Portable SDK for UPnP devices/1.6.18
X-User-Agent: redsonic
ST: {ST}
USN: uuid:{uuid}::{ST}
BOOTID.UPNP.ORG: 7339
CONFIGID.UPNP.ORG: 7339
Where {uuid} is the Chromecast's uuid, {currentDate} is the current date, {localIP} is the local IP address of the Chromecast on the network, and {ST} is the search term used.
Additionally, on the Chromecast's webserver the following should be returned at the url /ssdp/device-desc.xml:
<?xml version="1.0"?>
<root xmlns="urn:schemas-upnp-org:device-1-0">
<specVersion>
<major>1</major>
<minor>0</minor>
</specVersion>
<URLBase>http://{localIP}:8008</URLBase>
<device>
<deviceType>urn:dial-multiscreen-org:device:dial:1</deviceType>
<friendlyName>{friendlyName}</friendlyName>
<manufacturer>Google Inc.</manufacturer>
<modelName>Eureka Dongle</modelName>
<UDN>uuid:{uuid}</UDN>
<iconList>
<icon>
<mimetype>image/png</mimetype>
<width>98</width>
<height>55</height>
<depth>32</depth>
<url>/setup/icon.png</url>
</icon>
</iconList>
<serviceList>
<service>
<serviceType>urn:dial-multiscreen-org:service:dial:1</serviceType>
<serviceId>urn:dial-multiscreen-org:serviceId:dial</serviceId>
<controlURL>/ssdp/notfound</controlURL>
<eventSubURL>/ssdp/notfound</eventSubURL>
<SCPDURL>/ssdp/notfound</SCPDURL>
</service>
</serviceList>
</device>
</root>
Where {uuid} is the Chromecast's UUID, {friendlyName} is the display name of the chromecast, and {localIP} is the local IP address of the chromecast on the network. Additionally, requests to /ssdp/notfound should return a 404 error.
More information on this protocol can be found here
Chromecasts run mDNS Servers to allow for discovery of their v2 API services. They respond to PTR requests for the domain _googlecast._tcp.local. The following records should be returned by the server in an authoritative response:
Answer Records:
One PTR record for name _googlecast._tcp.local with domain name specified as {friendlyName}._googlecast._tcp.local where {friendlyName} is the display name of the Chromecast.
Additional Records:
One TXT record for name {friendlyName}._googlecast._tcp.local with the following texts associated with it: id={uuidNoHyphens}, ve=02, md=Chromecast, and ic=/setup/icon.png. Where {friendlyName} is the display name of the Chromecast and {uuidNoHyphens} is the UUID of the Chromecast with the hyphens removed.
One SRV record for name {friendlyName}._googlecast._tcp.local with priority of 0, weight of 0, port of 8009, and target name of {friendlyName}.local. Where {friendlyName} is the display name of the Chromecast.
One A record for the name {friendlyName}.local with the address of {localIP}. Where {friendlyName} is the display name of the Chromecast and {localIP} is the ip address of the Chromecast on the network.
Two NSEC records, the first for the name {friendlyName}._googlecast._tcp.local with types TXT and SRV, the second for name {friendlyName}.local with type A. Where {friendlyName} is the display name of the Chromecast
In older versions of the Chromecast firmware, the applist was obtained from:
https://clients3.google.com/cast/chromecast/device/config
However, the applist in current Chromecasts is obtained from here instead:
https://clients3.google.com/cast/chromecast/device/baseconfig
These two URLs will output JSON in the format of the App List
Individual app configurations are obtained from this url:
https://clients3.google.com/cast/chromecast/device/app?a={appid}
Where {appid} is the id of the app, and the output of this is JSON in the format of a receiver app defintion.
Each of these requests return JSON with ")]}'\n" prepended to it.
An app list is given in the following JSON format:
{
"applications":<array of reciever apps>,
"enabled_app_ids": <array of receiver app ids>,
"configuration": <object detailing additional configuration details>
}
applications is an array of receiver app defintions. enabled_app_ids is an array of strings, each one is an app id that should be visible and can have its receiver app defintion loaded on demand. The configuration field so far has always been this:
{
"idle_screen_app":<app id>
}
Where idle_screen_app is the app ID of the default app to show when no other app is loaded. So far this has always been: 00000000-0000-0000-0000-000000000000
The receiver app definition has many optional fields and the meaning of all of them is not yet known, and some may no longer used:
{
"use_channel":<boolean>
"allow_empty_post_data":<boolean>
"app_id":<string>
"url":<url-string>
"dial_enabled":<boolean>
"allow_restart":<boolean>
"dial_info":<string>
"command_line":<string>
"uses_ipc":<boolean>
"display_name":<string>
}
The app_id field is required for all chromecast apps. Each app must also either have url or command_line and dial_info. url is the URL to load in the browser to run the app, and command_line is a command that is executed to run the app if it is a separate executable. The only known receiver app to used command_line is the Netflix app. All receiver apps made after the initial release of the Google Cast SDK.
A special url is used for the homescreen and it starts with chrome://home this is used to load the homescreen app, it used to load a specified URL but it is now hardcoded to be: