Las aplicaciones emisoras de Google Cast controlan la reproducción en el dispositivo receptor enviando mensajes en formato JSON a la aplicación receptora. Del mismo modo, el receptor envía mensajes al remitente, también en formato JSON. Los mensajes pueden ser comandos del remitente que cambian el estado del reproductor, respuestas a esos comandos del receptor o estructuras de datos que describen el contenido multimedia para la aplicación del receptor.
De conformidad con las Condiciones del Servicio Adicionales para Desarrolladores del SDK de Google Cast, una aplicación de medios de Cast debe usar estos mensajes, tal como se definen aquí, para controlar la reproducción de medios en el receptor. De esta manera, la app de música tendrá una experiencia del usuario coherente en todas las plataformas y se garantizará que una aplicación de Cast admita casos de uso nuevos y futuros. Estas estructuras también admiten datos personalizados, cuando corresponde, y una aplicación puede definir sus propios mensajes para los comandos que no admite el SDK.
El espacio de nombres para los mensajes de reproducción de contenido multimedia se define como urn:x-cast:com.google.cast.media.
Nota: Los mensajes y las estructuras de esta especificación tienen un tamaño máximo implícito determinado por el tamaño máximo de un mensaje de transporte. No hay límite para los campos individuales. Actualmente, el tamaño máximo del mensaje de transporte es de 64 KB.
Estructuras de datos de espacios de nombres comunes
En un espacio de nombres común, se define un superconjunto de estructuras de datos que usan todos los artefactos del espacio de nombres de medios.
Imagen
Es la descripción de una imagen, que incluye una pequeña cantidad de metadatos para permitir que la aplicación emisora elija imágenes, según cómo las renderizará.
La altura y el ancho son opcionales en solo un elemento de un array de imágenes. Por ejemplo, si se devuelve un solo elemento, son opcionales; si se devuelven dos elementos, uno de ellos debe especificar una altura y un ancho, pero el remitente puede optar por la opción "predeterminada" si no le gusta la que se pasó con parámetros específicos.
| Nombre | Tipo | Descripción |
|---|---|---|
| url | URI | URI de la imagen |
| height | integer | opcional Altura de la imagen |
| width | integer | opcional Ancho de la imagen |
Volumen
Es el volumen de la transmisión de contenido multimedia. Se usa para los efectos de entrada y salida graduales en la transmisión de medios. (Nota: El volumen del sistema se cambia con las APIs del remitente). El volumen de la transmisión no se debe usar junto con el control deslizante o los botones de volumen para controlar el volumen del dispositivo. Se debe pasar al menos uno de los siguientes parámetros para cambiar el volumen de la transmisión.
| Nombre | Tipo | Descripción |
|---|---|---|
| level | doble | opcional Nivel de volumen actual de la transmisión como un valor entre 0.0 y 1.0, donde 1.0 es el volumen máximo. |
| Silenciado | booleano | opcional Indica si el dispositivo Cast está silenciado, independientemente del nivel de volumen. |
Estructuras de datos del espacio de nombres de medios
Estos mensajes describen el estado del reproductor multimedia. El espacio de nombres es urn:x-cast:com.google.cast.media.
MediaInformation
Esta estructura de datos describe un flujo de medios.
| Nombre | Tipo | Descripción |
|---|---|---|
| contentId | string | Es el identificador específico del servicio del contenido que cargó el reproductor multimedia. Es una cadena de formato libre y específica de la aplicación. En la mayoría de los casos, será la URL del contenido multimedia, pero el remitente puede optar por pasar una cadena que el receptor pueda interpretar correctamente. Longitud máxima: 1,000 |
| streamType | enum (string) |
Describe el tipo de artefacto de medios como uno de los siguientes:
|
| contentType | string | Tipo de contenido MIME del contenido multimedia que se reproduce |
| metadata | objeto | opcional Objeto de metadatos de medios, uno de los siguientes: |
| duración | doble | opcional Duración del stream que se está reproduciendo actualmente en segundos |
| customData | objeto | opcional Es un BLOB de datos específico de la aplicación que define la aplicación emisora o la aplicación receptora. |
GenericMediaMetadata
Describe un artefacto de medios genérico.
| Nombre | Tipo | Descripción |
|---|---|---|
| metadataType | integer | 0 (el único valor) |
| title | string | opcional Título descriptivo del contenido. El reproductor puede recuperar el título de forma independiente con content_id, o bien el remitente puede proporcionarlo en el mensaje Load. |
| subtitle | string | opcional Es el subtítulo descriptivo del contenido. El reproductor puede recuperar el título de forma independiente con content_id, o bien el remitente puede proporcionarlo en el mensaje Load. |
| imágenes | Image[] | opcional Es un array de URLs a una imagen asociada con el contenido. El remitente puede proporcionar el valor inicial del campo en el mensaje Load. Debe proporcionar los tamaños recomendados |
| releaseDate | cadena (ISO 8601) | Opcional Fecha y hora ISO 8601 en que se lanzó este contenido. El reproductor puede recuperar el título de forma independiente con content_id, o bien el remitente puede proporcionarlo en el mensaje Load. |
MovieMediaMetadata
Describe un artefacto de medios de una película.
| Nombre | Tipo | Descripción |
|---|---|---|
| metadataType | integer | 1 (el único valor) |
| title | string | opcional Título descriptivo del contenido. El reproductor puede recuperar el título de forma independiente con content_id, o bien el remitente puede proporcionarlo en el mensaje Load. |
| subtitle | string | opcional Es el subtítulo descriptivo del contenido. El reproductor puede recuperar el título de forma independiente con content_id, o bien el remitente puede proporcionarlo en el mensaje Load. |
| Studio | string | Opcional Es el estudio que lanzó el contenido. El reproductor puede recuperar el estudio de forma independiente con content_id, o bien el remitente puede proporcionarlo en el mensaje Load. |
| imágenes | Image[] | opcional Es un array de URLs a una imagen asociada con el contenido. El remitente puede proporcionar el valor inicial del campo en el mensaje Load. Debe proporcionar los tamaños recomendados |
| releaseDate | cadena (ISO 8601) | Opcional Fecha y hora ISO 8601 en que se lanzó este contenido. El reproductor puede recuperar el título de forma independiente con content_id, o bien el remitente puede proporcionarlo en el mensaje Load. |
TvShowMediaMetadata
Describe un artefacto de medios de un episodio de un programa de televisión.
| Nombre | Tipo | Descripción |
|---|---|---|
| metadataType | integer | 2 (el único valor) |
| seriesTitle | string | opcional Título descriptivo de la serie de TV. El reproductor puede recuperar el título de forma independiente con content_id, o bien el remitente puede proporcionarlo en el mensaje Load. |
| subtitle | string | opcional Subtítulo descriptivo del episodio de TV. El reproductor puede recuperar el título de forma independiente con content_id, o bien el remitente puede proporcionarlo en el mensaje Load. |
| temporada | integer | opcional Número de temporada del programa de TV |
| episodio | integer | opcional Número de episodio (en la temporada) del programa de TV |
| imágenes | Image[] | opcional Es un array de URLs a una imagen asociada con el contenido. El remitente puede proporcionar el valor inicial del campo en el mensaje Load. Debe proporcionar los tamaños recomendados |
| originalAirDate | cadena (ISO 8601) | Opcional Fecha y hora ISO 8601 en que se lanzó este episodio. El reproductor puede recuperar de forma independiente originalAirDate con content_id o el remitente puede proporcionarlo en el mensaje Load. |
MusicTrackMediaMetadata
Describe un artefacto de medios de pista musical.
| Nombre | Tipo | Descripción |
|---|---|---|
| metadataType | integer | 3 (el único valor) |
| albumName | string | opcional Álbum o colección del que se extrajo esta pista. El reproductor puede recuperar de forma independiente el valor de albumName con content_id, o bien el remitente puede proporcionarlo en el mensaje Load. |
| title | string | opcional Nombre de la pista (por ejemplo, título de la canción). El reproductor puede recuperar el título de forma independiente con content_id, o bien el remitente puede proporcionarlo en el mensaje Load. |
| albumArtist | string | Opcional Nombre del artista asociado al álbum en el que se incluye esta pista. El reproductor puede recuperar de forma independiente el álbumArtist con content_id o el remitente puede proporcionarlo en el mensaje Load. |
| artista | string | opcional Nombre del artista asociado con la pista de medios. El reproductor puede recuperar de forma independiente al artista con content_id, o bien el remitente puede proporcionarlo en el mensaje Load. |
| composer | string | opcional Nombre del compositor asociado con la pista de medios. El reproductor puede recuperar de forma independiente el compositor con content_id o el remitente puede proporcionarlo en el mensaje Load. |
| trackNumber | integer | opcional Número de la pista en el álbum |
| discNumber | integer | opcional Número del volumen (por ejemplo, un disco) del álbum |
| imágenes | Image[] | opcional Es un array de URLs a una imagen asociada con el contenido. El remitente puede proporcionar el valor inicial del campo en el mensaje Load. Debe proporcionar los tamaños recomendados |
| releaseDate | cadena (ISO 8601) | Opcional Fecha y hora ISO 8601 en que se lanzó este contenido. El reproductor puede recuperar de forma independiente releaseDate con content_id, o bien el remitente puede proporcionarlo en el mensaje Load. |
PhotoMediaMetadata
Describe un artefacto de medios fotográficos.
| Nombre | Tipo | Descripción |
|---|---|---|
| metadataType | integer | 4 (el único valor) |
| title | string | opcional Título de la fotografía. El reproductor puede recuperar el título de forma independiente con content_id, o bien el remitente puede proporcionarlo en el mensaje Load. |
| artista | string | opcional Nombre del fotógrafo. El reproductor puede recuperar de forma independiente al artista con content_id, o bien el remitente puede proporcionarlo en el mensaje Load. |
| ubicación | string | opcional Ubicación verbal en la que se tomó la fotografía, por ejemplo, "Madrid, España". El reproductor puede recuperar la ubicación de forma independiente con content_id o el remitente puede proporcionarla en el mensaje Load. |
| latitude | doble | opcional Valor de latitud geográfica para la ubicación en la que se tomó la fotografía. El reproductor puede recuperar la latitud de forma independiente con content_id o el remitente puede proporcionarla en el mensaje Load. |
| longitude | doble | opcional Valor de longitud geográfica para la ubicación en la que se tomó la fotografía. El reproductor puede recuperar la longitud de forma independiente con content_id, o bien el remitente puede proporcionarla en el mensaje Load. |
| width | integer | opcional Ancho de la fotografía en píxeles. El reproductor puede recuperar el ancho de forma independiente con content_id, o bien el remitente puede proporcionarlo en el mensaje Load. |
| height | integer | opcional Altura de la fotografía en píxeles. El reproductor puede recuperar la altura de forma independiente con content_id, o bien el remitente puede proporcionarla en el mensaje Load. |
| creationDateTime | cadena (ISO 8601) | Opcional Fecha y hora en formato ISO 8601 en que se tomó la fotografía. El reproductor puede recuperar de forma independiente creationDateTime con content_id o el remitente puede proporcionarlo en el mensaje Load. |
MediaStatus
Describe el estado actual del artefacto multimedia con respecto a la sesión.
| Nombre | Tipo | Descripción |
|---|---|---|
| mediaSessionId | integer | Es el ID único de la reproducción de esta sesión específica. El receptor establece este ID en LOAD y se puede usar para identificar una instancia específica de reproducción. Por ejemplo, dos reproducciones de "Wish you were here" dentro de la misma sesión tendrían cada una un mediaSessionId único. |
| media | MediaInformation | Opcional (para mensajes de estado) Es la descripción completa del contenido que se reproduce. Solo se devuelve en mensajes de estado si cambió MediaInformation. |
| playbackRate | float | Indica si el tiempo de los medios avanza y a qué velocidad. Esto es independiente del estado del reproductor, ya que el tiempo de los medios puede detenerse en cualquier estado. 1.0 es el tiempo normal y 0.5 es la cámara lenta. |
| playerState | enum (cadena) | Describe el estado del reproductor como uno de los siguientes:
|
| idleReason | enum (cadena) | opcional Si el playerState es IDLE y se conoce el motivo por el que se convirtió en IDLE, se proporciona esta propiedad. Si el reproductor está en IDLE porque acaba de iniciarse, no se proporcionará esta propiedad. Si el reproductor está en cualquier otro estado, no se debe proporcionar esta propiedad. Se aplican los siguientes valores:
|
| currentTime | doble | Es la posición actual del reproductor multimedia desde el inicio del contenido, en segundos. Si se trata de contenido de transmisión en vivo, este campo representa el tiempo en segundos desde el inicio del evento que el reproductor debe conocer. |
| supportedMediaCommands | flags | Marcas que describen qué comandos de contenido multimedia admite el reproductor de contenido multimedia:
Las combinaciones se describen como sumas; por ejemplo, Pausa + Búsqueda + Volumen de transmisión + Silencio == 15. |
| volumen | Volumen | Volumen de la transmisión |
| customData | objeto | opcional BLOB de datos específico de la aplicación definido por la aplicación receptora |
Comandos del remitente al receptor
Estos comandos controlan el reproductor de medios. Todos los objetos customData de los mensajes que se muestran a continuación deben ser opcionales (es decir, el receptor debe degradarse correctamente si no se pasan datos). Esto permitirá que las apps de control remoto genéricas funcionen correctamente.
Cargar
Carga contenido nuevo en el reproductor de contenido multimedia.
| Nombre | Tipo | Descripción |
|---|---|---|
| requestId | integer | ID de la solicitud, para correlacionar la solicitud y la respuesta |
| type | string | LOAD (único valor) |
| media | MediaInformation | Son los metadatos (incluido el contentId) del contenido multimedia que se cargará. |
| autoplay | booleano | opcional (el valor predeterminado es verdadero). Si se especifica el parámetro de reproducción automática, el reproductor de medios comenzará a reproducir el contenido cuando se cargue. Incluso si no se especifica la reproducción automática, la implementación del reproductor multimedia puede optar por comenzar la reproducción de inmediato. Si se inicia la reproducción, el estado del reproductor en la respuesta debe establecerse en BUFFERING; de lo contrario, debe establecerse en PAUSED. |
| currentTime | doble | opcional Segundos transcurridos desde el inicio del contenido. Si el contenido es en vivo y no se especifica la posición, la transmisión comenzará en la posición en vivo. |
| customData | objeto | Opcional BLOB de datos específico de la aplicación definido por la aplicación emisora |
| Respuesta | Activadores | Transmisiones | Errores |
|---|---|---|---|
| Ninguno | Cambio de estado del receptor | Un mensaje de cambio de estado del contenido multimedia | Estado del reproductor no válido Error de carga Carga cancelada |
Pausar
Pausa la reproducción del contenido actual. Activa una notificación de evento STATUS para todas las aplicaciones emisoras.
| Nombre | Tipo | Descripción |
|---|---|---|
| mediaSessionId | integer | ID de la sesión multimedia que se pausará |
| requestId | integer | ID de la solicitud, que se usa para correlacionar la solicitud y la respuesta |
| type | string | PAUSE (único valor) |
| customData | objeto | Opcional BLOB de datos específico de la aplicación definido por la aplicación emisora |
| Respuesta | Activadores | Transmisiones | Errores |
|---|---|---|---|
| Ninguno | Cambio de estado del receptor | Un mensaje de cambio de estado del contenido multimedia | Estado del reproductor no válido |
Seek
Establece la posición actual en la transmisión. Activa una notificación de evento STATUS para todas las aplicaciones emisoras. Si la posición proporcionada está fuera del rango de posiciones válidas para el contenido actual, el reproductor debe elegir una posición válida lo más cercana posible a la posición solicitada.
| Nombre | Tipo | Descripción |
|---|---|---|
| mediaSessionId | integer | ID de la sesión de medios en la que se establece la posición de la transmisión |
| requestId | integer | ID de la solicitud, para correlacionar la solicitud y la respuesta |
| type | string | SEEK (solo valor) |
| resumeState | enum (cadena) | opcional Si no se establece, el estado de reproducción no cambiará. Se aplican los siguientes valores:
|
| currentTime | doble | opcional Segundos transcurridos desde el inicio del contenido. Si el contenido es en vivo y no se especifica la posición, la transmisión comenzará en la posición en vivo. |
| customData | objeto | Opcional BLOB de datos específico de la aplicación definido por la aplicación emisora |
| Respuesta | Activadores | Transmisiones | Errores |
|---|---|---|---|
| Ninguno | Cambio de estado del receptor | Un mensaje de cambio de estado del contenido multimedia | Estado del reproductor no válido |
Detener
Detiene la reproducción del contenido actual. Activa una notificación de evento STATUS para todas las aplicaciones emisoras. Después de este comando, ya no se cargará el contenido y se invalidará el mediaSessionId.
| Nombre | Tipo | Descripción |
|---|---|---|
| mediaSessionId | integer | ID de la sesión de medios del contenido que se detendrá |
| requestId | integer | ID de la solicitud, para correlacionar la solicitud y la respuesta |
| type | string | STOP (único valor) |
| customData | objeto | Opcional BLOB de datos específico de la aplicación definido por la aplicación emisora |
| Respuesta | Activadores | Transmisiones | Errores |
|---|---|---|---|
| Ninguno | Cambio de estado del receptor | Un mensaje de cambio de estado del contenido multimedia | Estado del reproductor no válido |
Reproducir
Comienza la reproducción del contenido que se cargó con la llamada de carga. La reproducción continúa desde la posición de tiempo actual.
| Nombre | Tipo | Descripción |
|---|---|---|
| mediaSessionId | integer | ID de la sesión de medios para el contenido que se reproducirá |
| requestId | integer | ID de la solicitud, para correlacionar la solicitud y la respuesta |
| type | string | PLAY (único valor) |
| customData | objeto | Opcional BLOB de datos específico de la aplicación definido por la aplicación emisora |
| Respuesta | Activadores | Transmisiones | Errores |
|---|---|---|---|
| Ninguno | Cambio de estado del receptor | Un mensaje de cambio de estado del contenido multimedia | Estado del reproductor no válido |
Obtener estado
Recupera el estado del contenido multimedia.
| Nombre | Tipo | Descripción |
|---|---|---|
| mediaSessionId | integer | Opcional ID de la sesión multimedia del contenido multimedia para el que se debe devolver el estado. Si no se proporciona ninguno, se proporcionará el estado de todos los IDs de sesión de medios. |
| requestId | integer | ID de la solicitud, para correlacionar la solicitud y la respuesta |
| type | string | GET_STATUS (único valor) |
| customData | objeto | Opcional BLOB de datos específico de la aplicación definido por la aplicación emisora |
| Respuesta | Activadores | Transmisiones | Errores |
|---|---|---|---|
| Mensaje MediaStatus al remitente que lo solicitó | Ninguno | Ninguna | Ninguno |
SetVolume
Establece el volumen de la transmisión de medios. Se usa para los efectos de entrada y salida graduales en la transmisión de medios. (Nota: El volumen del receptor se cambia con el método setVolume del remitente web). El volumen de la transmisión no se debe usar junto con el control deslizante de volumen ni los botones de volumen para controlar el volumen del dispositivo. Un cambio en el volumen de la transmisión no activará ninguna IU en el receptor.
| Nombre | Tipo | Descripción |
|---|---|---|
| mediaSessionId | integer | ID de sesión de medios del contenido multimedia para el que se cambió el volumen de la transmisión |
| requestId | integer | ID de la solicitud, para correlacionar la solicitud y la respuesta |
| type | string | VOLUMEN (único valor) |
| volumen | Volumen | Volumen de la transmisión |
| customData | objeto | Opcional BLOB de datos específico de la aplicación definido por la aplicación emisora |
| Respuesta | Activadores | Transmisiones | Errores |
|---|---|---|---|
| Ninguno | Cambio de estado del receptor | Un mensaje de cambio de estado del contenido multimedia | Estado del reproductor no válido |
Mensajes del receptor al remitente
El receptor envía dos tipos de mensajes:
- Errores: Son mensajes de unidifusión que se envían cuando hay una respuesta de error a una solicitud del remitente.
- Estado: Mensajes de transmisión.
- Es la consecuencia de una acción iniciada por el remitente. Contendrá el requestId de la solicitud que causó el cambio.
- Espontáneo: Por ejemplo, debido a un cambio activado por la aplicación receptora. El RequestId será 0.
Error: Estado del reproductor no válido
Se envía cuando no se puede completar la solicitud del remitente porque el reproductor no está en un estado válido. Por ejemplo, si la aplicación aún no creó un elemento multimedia.
| Nombre | Tipo | Descripción |
|---|---|---|
| requestId | integer | ID de la solicitud que generó este error |
| type | string | INVALID_PLAYER_STATE (único valor) |
| customData | objeto | opcional BLOB de datos específico de la aplicación definido por la aplicación receptora |
Error: No se pudo cargar
Se envía cuando falla la solicitud de carga. El estado del reproductor será IDLE.
| Nombre | Tipo | Descripción |
|---|---|---|
| requestId | integer | ID de la solicitud que generó este error |
| type | string | LOAD_FAILED (único valor) |
| customData | objeto | opcional BLOB de datos específico de la aplicación definido por la aplicación receptora |
Error: Se canceló la carga
Se envía cuando se cancela la solicitud de carga (se recibió una segunda solicitud de carga).
| Nombre | Tipo | Descripción |
|---|---|---|
| requestId | integer | ID de la solicitud que generó este error |
| type | string | LOAD_CANCELLED (único valor) |
| customData | objeto | opcional BLOB de datos específico de la aplicación definido por la aplicación receptora |
Error: Solicitud no válida
Se envía cuando la solicitud no es válida (por ejemplo, un tipo de solicitud desconocido).
| Nombre | Tipo | Descripción |
|---|---|---|
| requestId | integer | ID de la solicitud que generó este error |
| type | string | INVALID_REQUEST (único valor) |
| reason | Enum (cadena) | Valores:
|
| customData | objeto | opcional BLOB de datos específico de la aplicación definido por la aplicación receptora |
Estado del contenido multimedia
Se envía después de un cambio de estado o después de una solicitud de estado de los medios. Solo se enviarán los objetos MediaStatus que cambiaron o se solicitaron.
| Nombre | Tipo | Descripción |
|---|---|---|
| requestId | integer | Es el ID que se usa para correlacionar esta respuesta de estado con la solicitud que la originó o 0 si el mensaje de estado es espontáneo (no se activó por una solicitud del remitente). Las aplicaciones de remitente generarán IDs de solicitud únicos seleccionando un número aleatorio y aumentándolo de forma continua (no usarán el 0). |
| type | string | MEDIA_STATUS (único valor) |
| estado | MediaStatus[] | Es un array de objetos Media Status. NOTA: El elemento multimedia en MediaStatus solo se devolverá si cambió. |
| customData | objeto | opcional BLOB de datos específico de la aplicación definido por la aplicación receptora |