Messages de lecture multimédia

Les applications émettrices Google Cast contrôlent la lecture sur le périphérique récepteur en envoyant des messages au format JSON à l'application destinataire. De même, le destinataire renvoie des messages à l'expéditeur, également au format JSON. Il peut s'agir de commandes envoyées par l'expéditeur qui modifient l'état du lecteur, de réponses à ces commandes du destinataire ou de structures de données décrivant les contenus multimédias de l'application réceptrice.

Conformément aux Conditions d'utilisation supplémentaires du SDK Google Cast pour les développeurs, une application multimédia Cast doit utiliser ces messages pour contrôler la lecture des contenus multimédias sur le récepteur. Cela permet à l'application multimédia d'offrir une expérience utilisateur cohérente sur toutes les plates-formes, et de s'assurer qu'une application Cast sera compatible avec les cas d'utilisation nouveaux et futurs. Ces structures sont également compatibles avec les données personnalisées, le cas échéant. Une application peut définir ses propres messages pour les commandes non compatibles avec le SDK.

L'espace de noms des messages de lecture de contenus multimédias est défini comme suit : urn:x-cast:com.google.cast.media.

Remarque:Les messages et les structures de cette spécification ont une taille maximale implicite 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 du message de transport est actuellement de 64 Ko.

Structures de données d'espace de noms communes

Un sur-ensemble de structures de données utilisées par tous les artefacts d'espace de noms multimédia est défini dans un espace de noms commun.

Image

Description d'une image, incluant une petite quantité de métadonnées pour permettre à l'application émettrice de choisir des images, en fonction de leur rendu.

La hauteur et la largeur sont facultatives pour un seul élément d'un tableau d'images. Par exemple, si un seul article est renvoyé, ces options sont facultatives. Si deux articles sont retournés, l'un d'eux doit spécifier une hauteur et une largeur. Toutefois, l'expéditeur peut choisir d'utiliser l'option "par défaut" si elle n'aime pas celle transmise avec des paramètres spécifiques.

Nom Type Description
url URI URI de l'image
hauteur integer (facultatif)  Hauteur de l'image
largeur integer (facultatif)  Largeur de l'image

Volume

Volume du flux multimédia. Utilisé pour les effets de fondu à l'ouverture et à la fermeture dans le flux multimédia. (Remarque: le volume système est modifié à l'aide des API émetteurs.) Le volume du flux ne doit pas être utilisé 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 Facultatif  : Niveau de volume actuel du flux, sous la forme d'une valeur comprise entre 0,0 et 1,0, où 1,0 correspond au volume maximal.
son coupé boolean facultatif  Indique si le son de l'appareil Cast est coupé, quel que soit le niveau de volume

Structures de données de l'espace de noms multimé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 au format libre spécifique à l'application. Dans la plupart des cas, il s'agit de l'URL de l'élément multimédia, mais l'expéditeur peut choisir de transmettre une chaîne que le destinataire pourra interpréter correctement. Longueur maximale: 1 000
streamType énumération
(chaîne)

Décrit le type d'artefact multimédia comme l'un des suivants:

  • AUCUN
  • BUFFER
  • EN DIRECT
contentType chaîne Type de contenu MIME du contenu multimédia en cours de lecture
metadata objet

Facultatif  : objet de métadonnées multimédia, soit l'un des éléments suivants :

durée 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 l'application destinataire

GenericMediaMetadata

Décrit un artefact multimédia générique.

Nom Type Description
metadataType integer 0  (la seule valeur)
title chaîne Facultatif  : titre descriptif du contenu. Le lecteur peut récupérer le titre indépendamment à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load (Charger)
sous-titre chaîne Facultatif  : Sous-titre descriptif du contenu. Le lecteur peut récupérer le titre indépendamment à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load (Charger)
images Image[] Facultatif  : tableau d'URL renvoyant vers une image associée au contenu. La valeur initiale du champ peut être fournie par l'expéditeur dans le message Load (Charger). Doit fournir des tailles recommandées
releaseDate chaîne (ISO 8601) Facultatif  : date et heure de mise en ligne de ce contenu selon la norme ISO 8601. Le lecteur peut récupérer le titre indépendamment à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load (Charger)

MovieMediaMetadata

Décrit un artefact multimédia de film.

Nom Type Description
metadataType integer 1  (la seule valeur)
title chaîne Facultatif  : titre descriptif du contenu. Le lecteur peut récupérer le titre indépendamment à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load (Charger)
sous-titre chaîne Facultatif  : Sous-titre descriptif du contenu. Le lecteur peut récupérer le titre indépendamment à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load (Charger)
studio chaîne Facultatif  : Studio ayant publié le contenu. Le lecteur peut récupérer Studio indépendamment à l'aide de content_id ou de celui fourni par l'expéditeur dans le message Load (Charger).
images Image[] Facultatif  : tableau d'URL renvoyant vers une image associée au contenu. La valeur initiale du champ peut être fournie par l'expéditeur dans le message Load (Charger). Doit fournir des tailles recommandées
releaseDate chaîne (ISO 8601) Facultatif  : date et heure de mise en ligne de ce contenu selon la norme ISO 8601. Le lecteur peut récupérer le titre indépendamment à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load (Charger)

TvShowMediaMetadata

Décrit un artefact multimédia d'épisode d'émission télévisée.

Nom Type Description
metadataType integer 2  (la seule valeur)
seriesTitle chaîne Facultatif  Titre descriptif de la série télévisée. Le lecteur peut récupérer le titre indépendamment à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load (Charger)
sous-titre chaîne Facultatif  : Sous-titre descriptif de l'épisode télévisé. Le lecteur peut récupérer le titre indépendamment à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load (Charger)
saison integer Facultatif  : Numéro de la saison de la série télévisée
épisode integer Facultatif  Numéro de l'épisode (dans la saison) de l'émission télévisée
images Image[] Facultatif  : tableau d'URL renvoyant vers une image associée au contenu. La valeur initiale du champ peut être fournie par l'expéditeur dans le message Load (Charger). Doit fournir des tailles recommandées
originalAirDate chaîne (ISO 8601) Facultatif  : date et heure de sortie de l'épisode selon la norme ISO 8601. Le lecteur peut récupérer l'originalAirDate à l'aide de content_id ou de le fournir par l'expéditeur dans le message Load (Charger).

MusicTrackMediaMetadata

Décrit un artefact multimédia de titre musical.

Nom Type Description
metadataType integer 3  (la seule valeur)
albumName chaîne facultatif  Album ou collection à partir duquel ce titre a été extrait. Le lecteur peut récupérer indépendamment albumName en utilisant 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). Le lecteur peut récupérer le titre indépendamment à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load (Charger)
albumArtist chaîne facultatif  : nom de l'artiste associé à l'album incluant ce titre. Le lecteur peut récupérer indépendamment la valeur albumArtist à l'aide de content_id ou elle peut être fournie par l'expéditeur dans le message Load (Charger).
artiste chaîne facultatif  : nom de l'artiste associé à la piste multimédia. Le lecteur peut récupérer indépendamment l'artiste à l'aide de content_id ou celui-ci peut être fourni par l'expéditeur dans le message Load (Charger).
composer chaîne facultatif  : nom du compositeur associé à la piste multimédia. Le lecteur peut récupérer indépendamment le composer à l'aide de content_id ou celui-ci peut être fourni par l'expéditeur dans le message Load (Charger).
trackNumber integer facultatif  : numéro du titre sur l'album
discNumber integer facultatif  numéro de volume (par exemple, un disque) de l'album ;
images Image[] Facultatif  : tableau d'URL renvoyant vers une image associée au contenu. La valeur initiale du champ peut être fournie par l'expéditeur dans le message Load (Charger). Doit fournir des tailles recommandées
releaseDate chaîne (ISO 8601) Facultatif  : date et heure de mise en ligne de ce contenu selon la norme ISO 8601. Le lecteur peut récupérer la date de sortie indépendamment à l'aide de content_id ou elle peut être fournie par l'expéditeur dans le message Load (Charger)

PhotoMediaMetadata

Décrit un artefact multimédia photographique.

Nom Type Description
metadataType integer 4  (la seule valeur)
title chaîne Facultatif  : Titre de la photo. Le lecteur peut récupérer le titre indépendamment à l'aide de content_id ou il peut être fourni par l'expéditeur dans le message Load (Charger)
artiste chaîne Facultatif  : Nom du photographe. Le lecteur peut récupérer indépendamment l'artiste à l'aide de content_id ou celui-ci peut être fourni par l'expéditeur dans le message Load (Charger).
position chaîne Facultatif  : Lieu de prise de vue oral où la photo a été prise (par exemple, "Madrid, Espagne"). Le lecteur peut récupérer indépendamment la position à l'aide de content_id ou de celle-ci peut être fournie par l'expéditeur dans le message Load (Charger)
latitude double Facultatif  : latitude géographique du lieu où la photo a été prise. Le lecteur peut récupérer indépendamment la latitude à l'aide de content_id ou elle peut être fournie par l'expéditeur dans le message Load (Charger)
longitude double Facultatif  : longitude géographique du lieu où la photo a été prise. Le lecteur peut récupérer indépendamment la longitude à l'aide de content_id ou celle-ci peut être fournie par l'expéditeur dans le message Load (Charger)
largeur integer Facultatif  : Largeur de la photo en pixels. Le lecteur peut récupérer indépendamment la largeur à l'aide de content_id ou celle-ci peut être fournie par l'expéditeur dans le message Load (Charger)
hauteur integer facultatif  : hauteur en pixels de la photo. Le lecteur peut récupérer indépendamment la hauteur à l'aide de content_id ou celle-ci peut être indiquée par l'expéditeur dans le message Load (Charger).
creationDateTime chaîne (ISO 8601) Facultatif  Date et heure ISO 8601 de la prise de vue. Le lecteur peut récupérer de manière indépendante la date et l'heure de création à l'aide de content_id, ou celles-ci peuvent être fournies par l'expéditeur dans le message Load (Charger).

MediaStatus

Décrit l'état actuel de l'artefact multimédia par rapport à la session.

Nom Type Description
mediaSessionId integer ID unique pour la lecture de cette session spécifique. Cet ID est défini par le récepteur au moment du chargement et peut être utilisé pour identifier une instance spécifique d'une lecture. Par exemple, deux lectures de la requête "Wish you were here" au cours d'une même session ont chacune un mediaSessionId unique.
media MediaInformation Facultatif (pour les messages d'état)  : description complète du contenu en cours de lecture. Ne être renvoyé dans un message d'état que si MediaInformation a été modifié.
playbackRate float Indique si l'heure du contenu multimédia est en cours, et à quelle fréquence. Ce paramètre est indépendant de l'état du lecteur, car l'heure du contenu multimédia peut s'arrêter dans n'importe quel état. 1,0 correspond au temps normal, 0,5 correspond au ralenti
playerState enum (chaîne)

Décrit l'état du lecteur comme l'un des suivants:

  • IDLE   Le lecteur n'a pas encore été chargé
  • PLAYING   : le lecteur lit activement du contenu.
  • BUFFERING   : le lecteur est en mode LECTURE, mais ne lit pas activement le contenu (l'heure actuelle ne change pas).
  • PAUSE   : Le lecteur est mis en pause
idleReason enum (chaîne)

facultatif  : si la valeur "playerState" est "IDLE" et que la raison pour laquelle elle est devenue "IDLE" est connue, cette propriété est fournie. Si le lecteur est "IDLE" parce qu'il vient de démarrer, cette propriété n'est pas fournie. Si le lecteur est dans un autre état, cette propriété ne doit pas être indiquée. Les valeurs suivantes s'appliquent:

  • CANCELLED   : un expéditeur a demandé l'arrêt de la lecture à l'aide de la commande STOP.
  • INTERRUPTED  Un expéditeur a demandé la lecture d'un autre contenu multimédia en utilisant la commande LOAD.
  • FINISHED  Lecture du contenu multimédia terminée
  • ERROR  Le contenu multimédia a été interrompu à cause d'une erreur (par exemple, si le lecteur n'a pas pu le télécharger en raison de problèmes de réseau).
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 la durée en secondes à partir du début de l'événement que le lecteur doit connaître.
supportedMediaCommands indicateurs

Indicateurs décrivant les commandes multimédias compatibles avec le lecteur multimédia:

  • 1  Mettre en pause
  • 2  Recherche
  • 4  Volume du flux
  • 8  Coupure du son du flux
  • 16  Avancer
  • 32  Reculer

Les combinaisons sont des additions, 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écepteur

Commandes de l'expéditeur au destinataire

Ces commandes contrôlent le lecteur multimédia. Tous les objets customData dans les messages ci-dessous doivent être facultatifs (c'est-à-dire que le destinataire doit se dégrader correctement si les données ne sont pas transmises). Les applications de télécommande générique pourront ainsi fonctionner correctement.

Charger

Charge le nouveau contenu dans le lecteur multimédia.

Nom Type Description
requestId integer ID de la requête, pour corréler la requête et la réponse
type chaîne CHARGER (uniquement la valeur)
media MediaInformation Métadonnées (y compris contentId) du média à charger
lecture automatique boolean

optional (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 une fois celui-ci chargé. Même si la lecture automatique n'est pas spécifiée, la mise en œuvre du lecteur multimédia peut décider 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. Sinon, il doit être mis en pause.

currentTime double Facultatif  : Nombre de secondes écoulées depuis le début du contenu. S'il s'agit d'un contenu en direct et que la position n'est pas spécifiée, le flux commencera à cette position.
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 Un message de changement de l'état du média État du lecteur non valide
Échec du chargement
Chargement annulé

Pause

Interrompt la lecture du contenu en cours. Déclenche une notification d'événement "STATUS" à toutes les applications émettrices.

Nom Type Description
mediaSessionId integer ID de la session multimédia à mettre en veille
requestId integer ID de la requête, à utiliser pour corréler la requête/réponse
type chaîne PAUSE (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 Un message de changement de l'état du média État du lecteur non valide

Recherche

Définit la position actuelle dans le flux. Déclenche une notification d'événement "STATUS" à toutes les applications émettrices. Si la position indiquée se situe en dehors de la plage de positions valides pour le contenu actuel, le lecteur doit sélectionner une position valide aussi proche que possible de la position demandée.

Nom Type Description
mediaSessionId integer ID de la session multimédia dans laquelle la position du flux est définie
requestId integer ID de la requête, pour corréler la requête et la réponse
type chaîne SEEK (valeur uniquement)
resumeState enum (chaîne)

optional  (facultatif) : si cette règle n'est pas configurée, l'état de la lecture ne change pas. Les valeurs suivantes s'appliquent :

  • PLAYBACK_START  Force le démarrage des contenus multimédias
  • PLAYBACK_PAUSE   Force la mise en pause des contenus multimédias
currentTime double Facultatif  : Nombre de secondes écoulées depuis le début du contenu. S'il s'agit d'un contenu en direct et que la position n'est pas spécifiée, le flux commencera à cette position.
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 Un message de changement de l'état du média État du lecteur non valide

Arrêter

Arrête la lecture du contenu en cours. Déclenche une notification d'événement "STATUS" à toutes les applications émettrices. Après cette commande, le contenu ne sera plus chargé et mediaSessionId n'est plus valide.

Nom Type Description
mediaSessionId integer ID de la session multimédia pour le contenu à arrêter
requestId integer ID de la requête, pour corréler 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 Un message de changement de l'état du média État du lecteur non valide

Joue

Démarre la lecture du contenu chargé avec l'appel de chargement. La lecture se poursuit à partir de la position actuelle.

Nom Type Description
mediaSessionId integer ID de la session multimédia pour le contenu à lire
requestId integer ID de la requête, pour corréler la requête et la réponse
type chaîne PLAY (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 Un message de changement de l'état du média État du lecteur non valide

Obtenir l'état

Récupère l'état du contenu multimédia.

Nom Type Description
mediaSessionId integer facultatif  : ID de session multimédia pour lequel l'état doit être renvoyé. Si aucun n'est défini, l'état de tous les ID de session multimédia est indiqué.
requestId integer ID de la requête, pour corréler la requête et la réponse
type chaîne GET_STATUS (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
MediaStatus à l'expéditeur à l'origine de la demande Aucun Aucun Aucun

SetVolume

Définit le volume du flux multimédia. Utilisé pour les effets de fondu à l'ouverture et à la fermeture dans le flux multimédia. (Remarque : le volume du récepteur est modifié à l'aide de la fonction setVolume de l'émetteur Web.) Le volume du flux ne doit pas être utilisé avec le curseur ou les boutons de volume pour contrôler le volume de l'appareil. Une modification du volume de flux ne déclenche aucune UI sur le récepteur.

Nom Type Description
mediaSessionId integer ID de session multimédia pour lequel le volume du flux est modifié
requestId integer ID de la requête, pour corréler 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 Un message de changement de l'état du média État du lecteur non valide

Messages du destinataire à l'expéditeur

Le destinataire envoie deux types de messages:

  • Erreurs: messages unicast envoyés en cas de réponse d'erreur à une requête de l'expéditeur.
  • État: annonces pour des messages.
    • Conséquences d'une action déclenchée par l'expéditeur. Contient le requestId de la requête à l'origine de la modification.
    • Spontanéité: par exemple, en raison d'une modification déclenchée par l'application destinataire. Le RequestId sera 0.

Erreur: État du lecteur non valide

Envoyé lorsque la requête de l'expéditeur ne peut pas être traitée, car l'état du lecteur n'est pas valide. C'est le cas, par exemple, si l'application n'a pas encore créé d'élément multimédia.

Nom Type Description
requestId integer ID de la requête qui a généré cette erreur
type chaîne INVALID_PLAYER_STATE (valeur uniquement)
customData objet Facultatif  Blob de données spécifique à l'application défini par l'application récepteur

Erreur: Échec du chargement

Envoyé lorsque la demande de chargement a échoué. L'état du lecteur sera "IDLE".

Nom Type Description
requestId integer ID de la requête qui a généré cette erreur
type chaîne LOAD_FAILED (valeur uniquement)
customData objet Facultatif  Blob de données spécifique à l'application défini par l'application récepteur

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 integer ID de la requête qui a généré cette erreur
type chaîne LOAD_CANCELLED (valeur seule)
customData objet Facultatif  Blob de données spécifique à l'application défini par l'application récepteur

Erreur: Demande non valide

Envoyé lorsque la requête n'est pas valide (type de requête inconnu, par exemple).

Nom Type Description
requestId integer ID de la requête qui a généré cette erreur
type chaîne INVALID_REQUEST (valeur uniquement)
raison Enum (chaîne)

Valeurs :

  • INVALID_COMMAND   La commande n'est pas compatible.
  • DUPLICATE_REQUESTID  L'ID de demande n'est pas unique (le destinataire traite une demande portant le même ID).
customData objet Facultatif  Blob de données spécifique à l'application défini par l'application récepteur

É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 qui ont été demandés seront envoyés.

Nom Type Description
requestId integer ID permettant de mettre en corrélation cette réponse d'état avec la requête qui en est à l'origine, ou 0 si le message d'état est spontané (non déclenché par une requête d'expéditeur). Les applications émettrices génèrent des ID de requête uniques en sélectionnant un nombre aléatoire et en l'augmentant continuellement (elles n'utilisent pas 0).
type chaîne MEDIA_STATUS (valeur uniquement)
état MediaStatus[] Tableau des objets Media Status (état du média). REMARQUE: L'élément media dans MediaStatus n'est renvoyé que s'il a été modifié.
customData objet Facultatif  Blob de données spécifique à l'application défini par l'application récepteur