Les applications émettrices Google Cast contrôlent la lecture sur l'appareil récepteur en envoyant des messages au format JSON à l'application réceptrice. De même, le récepteur renvoie des messages à l'expéditeur, également au format JSON. Les messages peuvent être des commandes de l'expéditeur qui modifient l'état du lecteur, des réponses à ces commandes du récepteur ou des structures de données qui décrivent le contenu multimédia pour l'application réceptrice.
Conformément aux Conditions d'utilisation supplémentaires du SDK Google Cast pour les développeurs, une application Cast de contenu multimédia doit utiliser les messages définis ici pour contrôler la lecture du contenu multimédia sur le récepteur. Cela permet à l'application multimédia d'offrir une expérience utilisateur cohérente sur toutes les plates-formes et garantit qu'une application Cast prendra en charge les cas d'utilisation nouveaux et futurs. Ces structures sont également compatibles avec les données personnalisées, le cas échéant, et une application peut définir ses propres messages pour les commandes non prises en charge par le SDK.
L'espace de noms des messages de lecture multimédia est défini comme urn:x-cast:com.google.cast.media.
Remarque : La taille maximale des messages et des structures de cette spécification est implicite et déterminée par la taille maximale d'un message de transport. Il n'y a pas de limite pour les champs individuels. La taille maximale des messages de transport est actuellement de 64 Ko.
Structures de données d'espace de noms courantes
Un sur-ensemble de structures de données utilisées par tous les artefacts de l'espace de noms média est défini dans un espace de noms commun.
Image
Il s'agit de la description d'une image, y compris d'une petite quantité de métadonnées pour permettre à l'application émettrice de choisir des images en fonction de la façon dont elle les affichera.
La hauteur et la largeur ne sont facultatives que pour un seul élément dans un tableau d'images. Par exemple, si un seul élément est renvoyé, il est facultatif. Si deux éléments sont renvoyés, l'un d'eux doit spécifier une hauteur et une largeur, mais l'expéditeur peut choisir l'option "par défaut" s'il n'aime pas celle transmise avec des paramètres spécifiques.
| Nom | Type | Description |
|---|---|---|
| url | URI | URI de l'image |
| hauteur | entier | optional : hauteur de l'image. |
| largeur | entier | optional Largeur de l'image |
Volume
Volume du flux multimédia. Utilisé pour les effets de fondu en entrée/sortie sur le flux multimédia. (Remarque : Le volume du système est modifié à l'aide des API de l'expéditeur.) Le volume du flux ne doit pas être utilisé conjointement avec le curseur ou les boutons de volume pour contrôler le volume de l'appareil. Au moins l'un des paramètres suivants doit être transmis pour modifier le volume du flux.
| Nom | Type | Description |
|---|---|---|
| niveau | double | optional Niveau de volume actuel du flux sous forme de valeur comprise entre 0,0 et 1,0, où 1,0 correspond au volume maximal. |
| désactivé | booléen | facultatif : indique si le son de l'appareil Cast est coupé, indépendamment du niveau de volume. |
Structures de données de l'espace de noms média
Ces messages décrivent l'état du lecteur multimédia. L'espace de noms est urn:x-cast:com.google.cast.media.
MediaInformation
Cette structure de données décrit un flux multimédia.
| Nom | Type | Description |
|---|---|---|
| contentId | chaîne | Identifiant spécifique au service du contenu actuellement chargé par le lecteur multimédia. Il s'agit d'une chaîne de format libre spécifique à l'application. Dans la plupart des cas, il s'agit de l'URL du contenu multimédia, mais l'expéditeur peut choisir de transmettre une chaîne que le destinataire peut interpréter correctement. Longueur maximale : 1 000 |
| streamType | enum (string) |
Décrit le type d'artefact multimédia comme l'un des suivants :
|
| contentType | chaîne | Type de contenu MIME du contenu multimédia en cours de lecture |
| metadata | objet | facultatif : objet de métadonnées multimédias, l'un des suivants : |
| duration | double | facultatif : durée du flux en cours de lecture (en secondes) |
| customData | objet | facultatif : blob de données spécifique à l'application, défini par l'application émettrice ou réceptrice |
GenericMediaMetadata
Décrit un artefact multimédia générique.
| Nom | Type | Description |
|---|---|---|
| metadataType | entier | 0 (la seule valeur) |
| title | chaîne | facultatif : titre descriptif du contenu. Le lecteur peut récupérer le titre de manière indépendante à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load. |
| subtitle | chaîne | optional Sous-titre descriptif du contenu. Le lecteur peut récupérer le titre de manière indépendante à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load. |
| images | Image[] | facultatif : tableau d'URL d'une image associée au contenu. La valeur initiale du champ peut être fournie par l'expéditeur dans le message Load. Doit fournir les tailles recommandées |
| releaseDate | Chaîne (ISO 8601) | facultatif : date et heure de publication de ce contenu au format ISO 8601. Le lecteur peut récupérer le titre de manière indépendante à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load. |
MovieMediaMetadata
Décrit un artefact multimédia de film.
| Nom | Type | Description |
|---|---|---|
| metadataType | entier | 1 (la seule valeur) |
| title | chaîne | facultatif : titre descriptif du contenu. Le lecteur peut récupérer le titre de manière indépendante à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load. |
| subtitle | chaîne | optional Sous-titre descriptif du contenu. Le lecteur peut récupérer le titre de manière indépendante à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load. |
| studio | chaîne | optional Studio qui a publié le contenu. Le lecteur peut récupérer le studio de manière indépendante à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load. |
| images | Image[] | facultatif : tableau d'URL d'une image associée au contenu. La valeur initiale du champ peut être fournie par l'expéditeur dans le message Load. Doit fournir les tailles recommandées |
| releaseDate | Chaîne (ISO 8601) | facultatif : date et heure de publication de ce contenu au format ISO 8601. Le lecteur peut récupérer le titre de manière indépendante à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load. |
TvShowMediaMetadata
Décrit un artefact multimédia d'épisode de série télévisée.
| Nom | Type | Description |
|---|---|---|
| metadataType | entier | 2 (la seule valeur) |
| seriesTitle | chaîne | facultatif : titre descriptif de la série TV. Le lecteur peut récupérer le titre de manière indépendante à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load. |
| subtitle | chaîne | facultatif : sous-titre descriptif de l'épisode de série TV. Le lecteur peut récupérer le titre de manière indépendante à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load. |
| season | entier | facultatif : numéro de la saison de la série TV |
| épisode | entier | Facultatif : numéro de l'épisode (dans la saison) de la série TV |
| images | Image[] | facultatif : tableau d'URL d'une image associée au contenu. La valeur initiale du champ peut être fournie par l'expéditeur dans le message Load. Doit fournir les tailles recommandées |
| originalAirDate | Chaîne (ISO 8601) | Facultatif : date et heure de sortie de cet épisode au format ISO 8601. Le lecteur peut récupérer indépendamment la date de diffusion d'origine à l'aide de content_id ou elle peut être fournie par l'expéditeur dans le message Load. |
MusicTrackMediaMetadata
Décrit un artefact multimédia de titre musical.
| Nom | Type | Description |
|---|---|---|
| metadataType | entier | 3 (la seule valeur) |
| albumName | chaîne | facultatif : album ou collection dont est extrait ce titre. Le lecteur peut récupérer indépendamment albumName à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load. |
| title | chaîne | facultatif : nom de la piste (par exemple, titre du morceau). Le lecteur peut récupérer le titre de manière indépendante à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load. |
| albumArtist | chaîne | Facultatif : nom de l'artiste associé à l'album contenant ce titre. Le lecteur peut récupérer indépendamment l'albumArtist à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load. |
| artiste | chaîne | Facultatif : nom de l'artiste associé à la piste multimédia. Le lecteur peut récupérer l'artiste de manière indépendante à l'aide de content_id ou l'expéditeur peut le fournir dans le message Load. |
| composer | chaîne | facultatif : nom du compositeur associé à la piste multimédia. Le lecteur peut récupérer le compositeur de manière indépendante à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load. |
| trackNumber | entier | facultatif : numéro de la piste sur l'album. |
| discNumber | entier | facultatif : numéro du volume (par exemple, un disque) de l'album. |
| images | Image[] | facultatif : tableau d'URL d'une image associée au contenu. La valeur initiale du champ peut être fournie par l'expéditeur dans le message Load. Doit fournir les tailles recommandées |
| releaseDate | Chaîne (ISO 8601) | facultatif : date et heure de publication de ce contenu au format ISO 8601. Le lecteur peut récupérer indépendamment la date de sortie à l'aide de content_id ou celle-ci peut être fournie par l'expéditeur dans le message Load. |
PhotoMediaMetadata
Décrit un artefact de contenu multimédia photographique.
| Nom | Type | Description |
|---|---|---|
| metadataType | entier | 4 (la seule valeur) |
| title | chaîne | facultatif : titre de la photographie. Le lecteur peut récupérer le titre de manière indépendante à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load. |
| artiste | chaîne | facultatif : nom du photographe. Le lecteur peut récupérer l'artiste de manière indépendante à l'aide de content_id ou l'expéditeur peut le fournir dans le message Load. |
| position | chaîne | facultatif Lieu verbal où la photo a été prise (par exemple, "Madrid, Espagne"). Le lecteur peut récupérer la position de manière indépendante à l'aide de content_id ou elle peut être fournie par l'expéditeur dans le message Load. |
| latitude | double | facultatif : valeur de latitude géographique du lieu où la photo a été prise. Le lecteur peut récupérer la latitude de manière indépendante à l'aide de content_id ou elle peut être fournie par l'expéditeur dans le message Load. |
| longitude | double | Facultatif : valeur de longitude géographique du lieu où la photo a été prise. Le lecteur peut récupérer la longitude de manière indépendante à l'aide de content_id ou elle peut être fournie par l'expéditeur dans le message Load. |
| largeur | entier | facultatif : largeur de la photo en pixels. Le lecteur peut récupérer la largeur de manière indépendante à l'aide de content_id ou elle peut être fournie par l'expéditeur dans le message Load. |
| hauteur | entier | facultatif : hauteur de la photo en pixels. Le lecteur peut récupérer la hauteur de manière indépendante à l'aide de content_id ou elle peut être fournie par l'expéditeur dans le message Load. |
| creationDateTime | Chaîne (ISO 8601) | Facultatif : date et heure ISO 8601 auxquelles cette photo a été prise. Le lecteur peut récupérer indépendamment creationDateTime à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load. |
MediaStatus
Décrit l'état actuel de l'artefact multimédia par rapport à la session.
| Nom | Type | Description |
|---|---|---|
| mediaSessionId | entier | ID unique pour la lecture de cette session spécifique. Cet ID est défini par le récepteur lors du chargement et peut être utilisé pour identifier une instance spécifique d'une lecture. Par exemple, deux lectures de "Wish you were here" au cours d'une même session auront chacune un mediaSessionId unique. |
| media | MediaInformation | facultatif (pour les messages d'état) : description complète du contenu en cours de lecture. Ne sera renvoyé dans un message d'état que si MediaInformation a changé. |
| playbackRate | float | Indique si le temps média progresse et à quelle vitesse. Cela est indépendant de l'état du lecteur, car le temps média peut s'arrêter dans n'importe quel état. 1.0 : vitesse normale, 0.5 : ralenti |
| playerState | enum (chaîne) | Décrit l'état du lecteur (l'une des valeurs suivantes) :
|
| idleReason | enum (chaîne) | facultatif : cette propriété est fournie si l'état du lecteur est IDLE et que la raison pour laquelle il est passé à l'état IDLE est connue. Si le lecteur est IDLE parce qu'il vient de démarrer, cette propriété ne sera pas fournie. Si le lecteur est dans un autre état, cette propriété ne doit pas être fournie. Les valeurs suivantes s'appliquent :
|
| currentTime | double | Position actuelle du lecteur multimédia depuis le début du contenu, en secondes. S'il s'agit d'un contenu de diffusion en direct, ce champ représente le temps en secondes depuis le début de l'événement qui doit être connu du lecteur. |
| supportedMediaCommands | flags | Indicateurs décrivant les commandes multimédias compatibles avec le lecteur multimédia :
Les combinaisons sont décrites sous forme de sommes. Par exemple, Pause+Seek+StreamVolume+Mute == 15. |
| volume | Volume | Volume du flux |
| customData | objet | facultatif : blob de données spécifique à l'application, défini par l'application réceptrice. |
Commandes de l'expéditeur au destinataire
Ces commandes contrôlent le lecteur multimédia. Tous les objets customData des messages ci-dessous doivent être facultatifs (c'est-à-dire que le récepteur doit se dégrader correctement si les données ne sont pas transmises). Cela permettra aux applications de télécommande génériques de fonctionner correctement.
Charger
Charge un nouveau contenu dans le lecteur multimédia.
| Nom | Type | Description |
|---|---|---|
| requestId | entier | ID de la requête, pour mettre en corrélation la requête et la réponse |
| type | chaîne | LOAD (valeur unique) |
| media | MediaInformation | Métadonnées (y compris contentId) du contenu multimédia à charger |
| autoplay | booléen | facultatif (la valeur par défaut est "true"). Si le paramètre de lecture automatique est spécifié, le lecteur multimédia commence à lire le contenu lorsqu'il est chargé. Même si la lecture automatique n'est pas spécifiée, l'implémentation du lecteur multimédia peut choisir de lancer la lecture immédiatement. Si la lecture est lancée, l'état du lecteur dans la réponse doit être défini sur "BUFFERING" (MISE EN MÉMOIRE TAMPON). Sinon, il doit être défini sur "PAUSED" (EN PAUSE). |
| currentTime | double | facultatif : nombre de secondes écoulées depuis le début du contenu. Si le contenu est un contenu en direct et que la position n'est pas spécifiée, le flux commencera à la position en direct. |
| customData | objet | facultatif : blob de données spécifique à l'application, défini par l'application émettrice |
| Réponse | Déclencheurs | Diffusions | Erreurs |
|---|---|---|---|
| Aucun | Changement d'état du récepteur | Message de modification de l'état d'un contenu multimédia | État du lecteur non valide Échec du chargement Chargement annulé |
Pause
Met en pause la lecture du contenu actuel. Déclenche une notification d'événement STATUS pour toutes les applications émettrices.
| Nom | Type | Description |
|---|---|---|
| mediaSessionId | entier | ID de la session multimédia à mettre en pause |
| requestId | entier | ID de la requête, à utiliser pour mettre en corrélation la requête et la réponse |
| type | chaîne | PAUSE (seule valeur possible) |
| customData | objet | facultatif : blob de données spécifique à l'application, défini par l'application émettrice |
| Réponse | Déclencheurs | Diffusions | Erreurs |
|---|---|---|---|
| Aucun | Changement d'état du récepteur | Message de modification de l'état d'un contenu multimédia | État du lecteur non valide |
Chercher
Définit la position actuelle dans le flux. Déclenche une notification d'événement STATUS pour toutes les applications émettrices. Si la position fournie est en dehors de la plage de positions valides pour le contenu actuel, le lecteur doit choisir une position valide aussi proche que possible de la position demandée.
| Nom | Type | Description |
|---|---|---|
| mediaSessionId | entier | ID de la session média dans laquelle la position du flux est définie |
| requestId | entier | ID de la requête, pour mettre en corrélation la requête et la réponse |
| type | chaîne | SEEK (valeur unique) |
| resumeState | enum (chaîne) | facultatif : si cette valeur n'est pas définie, l'état de lecture ne changera pas. Les valeurs suivantes s'appliquent :
|
| currentTime | double | facultatif : nombre de secondes écoulées depuis le début du contenu. Si le contenu est un contenu en direct et que la position n'est pas spécifiée, le flux commencera à la position en direct. |
| customData | objet | facultatif : blob de données spécifique à l'application, défini par l'application émettrice |
| Réponse | Déclencheurs | Diffusions | Erreurs |
|---|---|---|---|
| Aucun | Changement d'état du récepteur | Message de modification de l'état d'un contenu multimédia | État du lecteur non valide |
Arrêter
Arrête la lecture du contenu actuel. Déclenche une notification d'événement STATUS pour toutes les applications émettrices. Après cette commande, le contenu ne sera plus chargé et le mediaSessionId sera invalidé.
| Nom | Type | Description |
|---|---|---|
| mediaSessionId | entier | ID de la session multimédia pour le contenu à arrêter |
| requestId | entier | ID de la requête, pour mettre en corrélation la requête et la réponse |
| type | chaîne | STOP (valeur uniquement) |
| customData | objet | facultatif : blob de données spécifique à l'application, défini par l'application émettrice |
| Réponse | Déclencheurs | Diffusions | Erreurs |
|---|---|---|---|
| Aucun | Changement d'état du récepteur | Message de modification de l'état d'un contenu multimédia | État du lecteur non valide |
Lire
Lance la lecture du contenu qui a été chargé avec l'appel de chargement. La lecture reprend à partir de la position temporelle actuelle.
| Nom | Type | Description |
|---|---|---|
| mediaSessionId | entier | ID de la session média pour le contenu à lire |
| requestId | entier | ID de la requête, pour mettre en corrélation la requête et la réponse |
| type | chaîne | PLAY (seule valeur) |
| customData | objet | facultatif : blob de données spécifique à l'application, défini par l'application émettrice |
| Réponse | Déclencheurs | Diffusions | Erreurs |
|---|---|---|---|
| Aucun | Changement d'état du récepteur | Message de modification de l'état d'un contenu multimédia | État du lecteur non valide |
Obtenir l'état
Récupère l'état du contenu multimédia.
| Nom | Type | Description |
|---|---|---|
| mediaSessionId | entier | facultatif : ID de session multimédia du contenu multimédia pour lequel l'état du contenu multimédia doit être renvoyé. Si aucun n'est fourni, l'état de tous les ID de session média sera fourni. |
| requestId | entier | ID de la requête, pour mettre en corrélation la requête et la réponse |
| type | chaîne | GET_STATUS (seule valeur) |
| customData | objet | facultatif : blob de données spécifique à l'application, défini par l'application émettrice |
| Réponse | Déclencheurs | Diffusions | Erreurs |
|---|---|---|---|
| Message MediaStatus à l'expéditeur qui l'a demandé | Aucun | Aucune | Aucun |
SetVolume
Définit le volume du flux multimédia. Utilisé pour les effets de fondu en entrée/sortie sur le flux multimédia. (Remarque : Le volume du récepteur est modifié à l'aide de l'expéditeur Web setVolume.) Le volume du flux ne doit pas être utilisé conjointement avec le curseur de volume ou les boutons de volume pour contrôler le volume de l'appareil. Une modification du volume du flux ne déclenchera aucune interface utilisateur sur le récepteur.
| Nom | Type | Description |
|---|---|---|
| mediaSessionId | entier | ID de session multimédia du contenu multimédia dont le volume du flux a été modifié |
| requestId | entier | ID de la requête, pour mettre en corrélation la requête et la réponse |
| type | chaîne | VOLUME (valeur uniquement) |
| volume | Volume | Volume du flux |
| customData | objet | facultatif : blob de données spécifique à l'application, défini par l'application émettrice |
| Réponse | Déclencheurs | Diffusions | Erreurs |
|---|---|---|---|
| Aucun | Changement d'état du récepteur | Message de modification de l'état d'un contenu multimédia | État du lecteur non valide |
Messages du destinataire à l'expéditeur
Le récepteur envoie deux types de messages :
- Erreurs : messages de monodiffusion envoyés en cas de réponse d'erreur à une demande de l'expéditeur.
- État : Messages diffusés.
- Conséquence d'une action initiée par l'expéditeur. Contiendra le requestID de la requête à l'origine de la modification.
- Spontanée : par exemple, en raison d'un changement déclenché par l'application réceptrice. RequestId sera défini sur 0.
Erreur : État du lecteur non valide
Envoyé lorsque la requête de l'expéditeur ne peut pas être traitée, car le lecteur n'est pas dans un état valide. Par exemple, si l'application n'a pas encore créé d'élément multimédia.
| Nom | Type | Description |
|---|---|---|
| requestId | entier | ID de la requête qui a généré cette erreur |
| type | chaîne | INVALID_PLAYER_STATE (seule valeur) |
| customData | objet | facultatif : blob de données spécifique à l'application, défini par l'application réceptrice |
Erreur : Échec du chargement
Envoyé lorsque la demande de chargement a échoué. L'état du lecteur sera IDLE.
| Nom | Type | Description |
|---|---|---|
| requestId | entier | ID de la requête qui a généré cette erreur |
| type | chaîne | LOAD_FAILED (seule valeur) |
| customData | objet | facultatif : blob de données spécifique à l'application, défini par l'application réceptrice. |
Erreur : Chargement annulé
Envoyé lorsque la demande de chargement a été annulée (une deuxième demande de chargement a été reçue).
| Nom | Type | Description |
|---|---|---|
| requestId | entier | ID de la requête qui a généré cette erreur |
| type | chaîne | LOAD_CANCELLED (seule valeur) |
| customData | objet | facultatif : blob de données spécifique à l'application, défini par l'application réceptrice. |
Erreur : Requête non valide
Envoyé lorsque la requête n'est pas valide (type de requête inconnu, par exemple).
| Nom | Type | Description |
|---|---|---|
| requestId | entier | ID de la requête qui a généré cette erreur |
| type | chaîne | INVALID_REQUEST (valeur uniquement) |
| reason | Enum (chaîne) | Valeurs :
|
| customData | objet | facultatif : blob de données spécifique à l'application, défini par l'application réceptrice. |
État du contenu multimédia
Envoyé après un changement d'état ou après une demande d'état du contenu multimédia. Seuls les objets MediaStatus qui ont été modifiés ou demandés seront envoyés.
| Nom | Type | Description |
|---|---|---|
| requestId | entier | ID utilisé pour corréler cette réponse d'état avec la requête qui l'a générée, ou 0 si le message d'état est spontané (non déclenché par une requête de l'expéditeur). Les applications expéditrices génèrent des ID de requête uniques en sélectionnant un nombre aléatoire et en l'incrémentant en continu (elles n'utilisent pas 0). |
| type | chaîne | MEDIA_STATUS (seule valeur) |
| état | MediaStatus[] | Tableau d'objets MediaStatus. REMARQUE : L'élément multimédia dans MediaStatus ne sera renvoyé que s'il a été modifié. |
| customData | objet | facultatif : blob de données spécifique à l'application, défini par l'application réceptrice. |