Messaggi di riproduzione multimediale

Le applicazioni mittente di Google Cast controllano la riproduzione sul dispositivo del destinatario inviando messaggi in formato JSON all'applicazione del destinatario. Allo stesso modo, il destinatario invia i messaggi al mittente, anch'esso in JSON. I messaggi possono essere comandi del mittente che modificano lo stato del player, risposte a questi comandi dal destinatario o strutture di dati che descrivono i contenuti multimediali per l'applicazione del destinatario.

Nel rispetto dei Termini di servizio aggiuntivi per gli sviluppatori dell'SDK Google Cast, un'applicazione multimediale Cast deve utilizzare questi messaggi come definito qui per controllare la riproduzione di contenuti multimediali sul ricevitore. In questo modo l'app multimediale può avere un'esperienza utente coerente su tutte le piattaforme e garantisce che l'applicazione di trasmissione supporterà casi d'uso nuovi e futuri. Queste strutture supportano anche dati personalizzati, ove appropriato, e un'applicazione può definire i propri messaggi per i comandi non supportati dall'SDK.

Lo spazio dei nomi per i messaggi di riproduzione multimediale è definito come urn:x-cast:com.google.cast.media.

Nota: i messaggi e le strutture in questa specifica hanno una dimensione massima implicita determinata dalla dimensione massima di un messaggio di trasporto. Non esistono limiti per i singoli campi. Attualmente la dimensione massima del messaggio di trasporto è di 64 kB.

Strutture di dati comuni dello spazio dei nomi

Un soprainsieme di strutture di dati utilizzate da tutti gli artefatti dello spazio dei nomi multimediale viene definito in uno spazio dei nomi comune.

Immagine

Si tratta della descrizione di un'immagine, inclusa una piccola quantità di metadati per consentire all'applicazione del mittente di scegliere le immagini, a seconda di come le mostrerà.

Altezza e larghezza sono facoltative per un solo elemento in un array di immagini. Ad esempio, se viene restituito un singolo articolo, i dettagli sono facoltativi; se restituisci due articoli, un articolo deve specificare altezza e larghezza, ma il mittente può scegliere di scegliere l'opzione "predefinito" se non corrisponde a quello trasmesso con parametri specifici.

Nome Tipo Descrizione
url URI URI dell'immagine
altezza numero intero (Facoltativo)  Altezza dell'immagine
numero intero (Facoltativo)  Larghezza dell'immagine

Volume

Il volume dello stream multimediale. Utilizzato per gli effetti di dissolvenza in entrata e in uscita nello stream multimediale. Nota: il volume del sistema viene modificato utilizzando le API Sender. Il volume dello stream non deve essere utilizzato insieme al dispositivo di scorrimento del volume o ai pulsanti del volume per regolare il volume del dispositivo. Per modificare il volume del flusso, è necessario passare almeno uno dei seguenti parametri.

Nome Tipo Descrizione
livello double Facoltativo Livello di volume dello stream attuale come valore compreso tra 0,0 e 1,0, dove 1,0 è il volume massimo.
audio disattivato boolean (Facoltativo)  Indica se l'audio del dispositivo di trasmissione è disattivato, indipendentemente dal livello di volume

Strutture di dati dello spazio dei nomi multimediale

Questi messaggi descrivono lo stato del media player. Lo spazio dei nomi è urn:x-cast:com.google.cast.media.

MediaInformation

Questa struttura di dati descrive uno stream multimediale.

Nome Tipo Descrizione
contentId stringa Identificatore specifico del servizio dei contenuti attualmente caricati dal media player. Si tratta di una stringa in formato libero specifica per l'applicazione. Nella maggior parte dei casi, si tratterà dell'URL del contenuto multimediale, ma il mittente può scegliere di trasmettere una stringa che il destinatario potrà interpretare correttamente. Lunghezza massima: 1000
streamType enum
(stringa)

Descrive il tipo di artefatto multimediale come uno dei seguenti:

  • NESSUNA
  • BUFFERATO
  • IN DIRETTA
contentType stringa Tipo di contenuto MIME dei contenuti multimediali riprodotti
metadata oggetto

Facoltativo L'oggetto metadati multimediali, uno dei seguenti:

durata double Facoltativo  Durata dello stream in riproduzione in secondi
customData oggetto Facoltativo Blob di dati specifico per l'applicazione definito dall'applicazione del mittente o dell'applicazione del destinatario

GenericMediaMetadata

Descrive un artefatto multimediale generico.

Nome Tipo Descrizione
metadataType numero intero 0  (l'unico valore)
title stringa Facoltativo Titolo descrittivo dei contenuti. Il player può recuperare in modo indipendente il titolo utilizzando content_id o può essere fornito dal mittente nel messaggio Carica
sottotitolo stringa Facoltativo Sottotitolo descrittivo dei contenuti. Il player può recuperare in modo indipendente il titolo utilizzando content_id o può essere fornito dal mittente nel messaggio Carica
immagini Immagine[] Facoltativo Array di URL di un'immagine associata ai contenuti. Il valore iniziale del campo può essere fornito dal mittente nel messaggio Carica. Deve indicare le dimensioni consigliate
releaseDate stringa (ISO 8601) (Facoltativo)  Data e ora di pubblicazione dei contenuti ISO 8601. Il player può recuperare in modo indipendente il titolo utilizzando content_id o può essere fornito dal mittente nel messaggio Carica

MovieMediaMetadata

Descrive un artefatto multimediale cinematografico.

Nome Tipo Descrizione
metadataType numero intero 1  (l'unico valore)
title stringa Facoltativo Titolo descrittivo dei contenuti. Il player può recuperare in modo indipendente il titolo utilizzando content_id o può essere fornito dal mittente nel messaggio Carica
sottotitolo stringa Facoltativo Sottotitolo descrittivo dei contenuti. Il player può recuperare in modo indipendente il titolo utilizzando content_id o può essere fornito dal mittente nel messaggio Carica
studio stringa (facoltativo) Studio che ha rilasciato i contenuti. Il player può recuperare Studio in modo indipendente utilizzando content_id o può essere fornito dal mittente nel messaggio Carica
immagini Immagine[] Facoltativo Array di URL di un'immagine associata ai contenuti. Il valore iniziale del campo può essere fornito dal mittente nel messaggio Carica. Deve indicare le dimensioni consigliate
releaseDate stringa (ISO 8601) (Facoltativo)  Data e ora di pubblicazione dei contenuti ISO 8601. Il player può recuperare in modo indipendente il titolo utilizzando content_id o può essere fornito dal mittente nel messaggio Carica

TvShowMediaMetadata

Descrive il manufatto multimediale relativo all'episodio di un programma televisivo.

Nome Tipo Descrizione
metadataType numero intero 2  (l'unico valore)
seriesTitle stringa Facoltativo Titolo descrittivo della serie TV. Il player può recuperare in modo indipendente il titolo utilizzando content_id o può essere fornito dal mittente nel messaggio Carica
sottotitolo stringa Facoltativo  Sottotitolo descrittivo della puntata TV. Il player può recuperare in modo indipendente il titolo utilizzando content_id o può essere fornito dal mittente nel messaggio Carica
stagione numero intero Facoltativo Numero della stagione del programma televisivo
episodio numero intero Facoltativo  Numero della puntata (nella stagione) del programma televisivo
immagini Immagine[] Facoltativo Array di URL di un'immagine associata ai contenuti. Il valore iniziale del campo può essere fornito dal mittente nel messaggio Carica. Deve indicare le dimensioni consigliate
originalAirDate stringa (ISO 8601) Facoltativo : data e ora di pubblicazione della puntata ISO 8601. Il player può recuperare in modo indipendente originalAirDate utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load (Carica)

MusicTrackMediaMetadata

Descrive un artefatto multimediale di una traccia musicale.

Nome Tipo Descrizione
metadataType numero intero 3  (l'unico valore)
albumName stringa Facoltativo L'album o la raccolta da cui è stata tratta la traccia. Il player può recuperare in modo indipendente albumName utilizzando content_id o può essere fornito dal mittente nel messaggio Carica
title stringa Facoltativo : il nome della traccia (ad esempio, titolo del brano). Il player può recuperare in modo indipendente il titolo utilizzando content_id o può essere fornito dal mittente nel messaggio Carica
albumArtist stringa Facoltativo Il nome dell'artista associato all'album che contiene la traccia. Il player può recuperare in modo indipendente albumArtist utilizzando content_id o può essere fornito dal mittente nel messaggio Carica
artista stringa Facoltativo : il nome dell'artista associato alla traccia multimediale. Il player può recuperare in modo indipendente l'artista utilizzando content_id o può essere fornito dal mittente nel messaggio Carica
composer stringa Facoltativo: nome del compositore associato alla traccia multimediale. Il player può recuperare in modo indipendente il compositore utilizzando content_id o può essere fornito dal mittente nel messaggio Carica.
trackNumber numero intero Facoltativo Numero della traccia dell'album
discNumber numero intero Facoltativo Numero del volume (ad esempio, un disco) dell'album
immagini Immagine[] Facoltativo Array di URL di un'immagine associata ai contenuti. Il valore iniziale del campo può essere fornito dal mittente nel messaggio Carica. Deve indicare le dimensioni consigliate
releaseDate stringa (ISO 8601) (Facoltativo)  Data e ora di pubblicazione dei contenuti ISO 8601. Il player può recuperare in modo indipendente la data di rilascio utilizzando content_id o può essere fornita dal mittente nel messaggio Carica.

PhotoMediaMetadata

Descrive un artefatto di supporto fotografico.

Nome Tipo Descrizione
metadataType numero intero 4  (l'unico valore)
title stringa Facoltativo Titolo della fotografia. Il player può recuperare in modo indipendente il titolo utilizzando content_id o può essere fornito dal mittente nel messaggio Carica
artista stringa Facoltativo Il nome del fotografo. Il player può recuperare in modo indipendente l'artista utilizzando content_id o può essere fornito dal mittente nel messaggio Carica
località stringa Facoltativo Il luogo a cui è stata scattata la foto a voce, ad esempio "Madrid, Spagna". Il player può recuperare la posizione in modo indipendente utilizzando content_id o può essere fornita dal mittente nel messaggio Carica
latitude double Facoltativo Il valore della latitudine geografica per la località in cui è stata scattata la fotografia. Il player può recuperare in modo indipendente la latitudine utilizzando content_id o può essere fornita dal mittente nel messaggio Carica
longitude double Facoltativo Valore della longitudine geografica per la località in cui è stata scattata la fotografia. Il player può recuperare la longitudine in modo indipendente utilizzando content_id o può essere fornita dal mittente nel messaggio Carica
numero intero Facoltativo La larghezza in pixel della fotografia. Il player può recuperare in modo indipendente la larghezza utilizzando content_id o può essere fornita dal mittente nel messaggio Carica.
altezza numero intero Facoltativo L'altezza in pixel della fotografia. Il player può recuperare l'altezza in modo indipendente utilizzando content_id o può essere fornita dal mittente nel messaggio Carica.
creationDateTime stringa (ISO 8601) Facoltativo La data e l'ora in cui è stata scattata la foto ISO 8601. Il player può recuperare in modo indipendente CreationDateTime utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load (Carica)

MediaStatus

Descrive lo stato attuale dell'artefatto multimediale rispetto alla sessione.

Nome Tipo Descrizione
mediaSessionId numero intero ID univoco per la riproduzione di questa sessione specifica. Questo ID viene impostato dal ricevitore su LOAD e può essere utilizzato per identificare un'istanza specifica di una riproduzione. Ad esempio, due riproduzioni di "Ti piacerebbe essere qui" nella stessa sessione avrebbero ciascuna un mediaSessionId univoco.
contenuti multimediali MediaInformation Facoltativo (per i messaggi di stato)  Descrizione completa dei contenuti in riproduzione. Deve essere restituito in un messaggio di stato solo se il valore MediaInformation è cambiato.
playbackRate float Indica se il tempo di ascolto è in corso e a quale velocità. Questa opzione è indipendente dallo stato del player, poiché il momento multimediale può interrompersi in qualsiasi stato. 1,0 è tempo normale, 0,5 è slow motion
playerState enum (stringa)

Descrive lo stato del player in uno dei seguenti modi:

  • Inattivo  Il player non è stato ancora caricato.
  • IN RIPRODUZIONE  Il giocatore sta riproducendo attivamente contenuti.
  • BUFFERING   Il player è in modalità RIPRODUZIONE, ma non sta riproducendo attivamente contenuti (currentTime non cambia)
  • IN PAUSA  Il player è in pausa
idleReason enum (stringa)

facoltativo Se il playerState è IDLE e il motivo per cui è diventato IDLE è noto, viene indicata questa proprietà. Se il player è INATTIVO perché è appena iniziato, questa proprietà non viene fornita; se il player è in un altro stato, questa proprietà non deve essere fornita. Si applicano i seguenti valori:

  • CANCELLED  Un mittente ha richiesto di interrompere la riproduzione utilizzando il comando STOP
  • INTERRUPTED  Un mittente ha richiesto la riproduzione di un contenuto multimediale diverso utilizzando il comando LOAD
  • FINISHED  La riproduzione dei contenuti multimediali è stata completata
  • ERROR  L'elemento multimediale è stato interrotto a causa di un errore; ad esempio, se il player non ha potuto scaricare i contenuti multimediali a causa di problemi di rete.
currentTime double La posizione corrente in secondi del media player dall'inizio dei contenuti. Se si tratta di contenuti in live streaming, questo campo rappresenta il tempo in secondi che deve trascorrere dall'inizio dell'evento al player.
supportedMediaCommands flags

Flag che descrivono i comandi multimediali supportati dal media player:

  • 1  Metti in pausa
  • 2  Ricerca
  • 4  Volume dello stream
  • 8  Disattiva audio dello streaming
  • 16  Vai avanti
  • 32  Vai indietro

Le combinazioni sono descritte come sommatori; ad esempio, Pausa+Ricerca+Volume dello stream+Disattiva audio == 15.

volume Volume Volume dello stream
customData oggetto Facoltativo Blob di dati specifico per l'applicazione definito dall'applicazione ricevente

Comandi dal mittente al destinatario

Questi comandi controllano il media player. Tutti gli oggetti customData nei messaggi in basso devono essere facoltativi (ad esempio, il livello di qualità del destinatario dovrebbe essere corretto se i dati non vengono passati). In questo modo le app generiche di controllo remoto funzioneranno correttamente.

Carica

Carica nuovi contenuti nel media player.

Nome Tipo Descrizione
requestId numero intero ID della richiesta, per correlare la richiesta e la risposta
type stringa LOAD (solo valore)
contenuti multimediali MediaInformation Metadati (incluso contentId) dei contenuti multimediali da caricare
riproduzione automatica boolean

facoltativo (l'impostazione predefinita è true) Se viene specificato il parametro di riproduzione automatica, il media player inizierà a riprodurre i contenuti quando vengono caricati. Anche se la riproduzione automatica non è specificata, l'implementazione del media player potrebbe scegliere di avviare immediatamente la riproduzione. Se viene avviata la riproduzione, lo stato del player nella risposta deve essere impostato su BUFFERING, altrimenti deve essere impostato su PAUSE

currentTime double Facoltativo Secondi dall'inizio dei contenuti. Se i contenuti sono contenuti dal vivo e la posizione non è specificata, lo stream inizierà dalla posizione dal vivo
customData oggetto Facoltativo Blob di dati specifico per l'applicazione definito dall'applicazione del mittente
Risposta Trigger Trasmissione Errori
Nessuno Modifica dello stato del ricevitore Un messaggio di modifica dello stato dei contenuti multimediali Stato del player non valido
Caricamento non riuscito
Caricamento annullato

Metti in pausa

Mette in pausa la riproduzione dei contenuti correnti. Attiva una notifica di evento STATUS a tutte le applicazioni del mittente.

Nome Tipo Descrizione
mediaSessionId numero intero ID della sessione multimediale da mettere in pausa
requestId numero intero ID della richiesta, da utilizzare per correlare richiesta/risposta
type stringa PAUSE (solo valore)
customData oggetto Facoltativo Blob di dati specifico per l'applicazione definito dall'applicazione del mittente
Risposta Trigger Trasmissione Errori
Nessuno Modifica dello stato del ricevitore Un messaggio di modifica dello stato dei contenuti multimediali Stato del player non valido

Ricerca

Imposta la posizione corrente nello stream. Attiva una notifica di evento STATUS a tutte le applicazioni del mittente. Se la posizione fornita non rientra nell'intervallo di posizioni valide per i contenuti correnti, il player deve scegliere una posizione valida il più vicina possibile alla posizione richiesta.

Nome Tipo Descrizione
mediaSessionId numero intero ID della sessione multimediale in cui è impostata la posizione dello stream.
requestId numero intero ID della richiesta, per correlare la richiesta e la risposta
type stringa SEEK (solo valore)
resumeState enum (stringa)

Facoltativo Se non viene impostata, lo stato di riproduzione non cambierà. Si applicano i seguenti valori:

  • PLAYBACK_START  Forza l'avvio dei contenuti multimediali
  • PLAYBACK_PAUSE  Forza la messa in pausa dei contenuti multimediali
currentTime double Facoltativo Secondi dall'inizio dei contenuti. Se i contenuti sono contenuti dal vivo e la posizione non è specificata, lo stream inizierà dalla posizione dal vivo
customData oggetto Facoltativo Blob di dati specifico per l'applicazione definito dall'applicazione del mittente
Risposta Trigger Trasmissione Errori
Nessuno Modifica dello stato del ricevitore Un messaggio di modifica dello stato dei contenuti multimediali Stato del player non valido

Interrompi

Interrompe la riproduzione dei contenuti correnti. Attiva una notifica di evento STATUS a tutte le applicazioni del mittente. Dopo questo comando, i contenuti non verranno più caricati e il mediaSessionId verrà invalidato.

Nome Tipo Descrizione
mediaSessionId numero intero ID della sessione multimediale per i contenuti da interrompere
requestId numero intero ID della richiesta, per correlare la richiesta e la risposta
type stringa STOP (solo valore)
customData oggetto Facoltativo Blob di dati specifico per l'applicazione definito dall'applicazione del mittente
Risposta Trigger Trasmissione Errori
Nessuno Modifica dello stato del ricevitore Un messaggio di modifica dello stato dei contenuti multimediali Stato del player non valido

Gioca

Avvia la riproduzione dei contenuti caricati con la chiamata di caricamento, la riproduzione continua dalla posizione temporale corrente.

Nome Tipo Descrizione
mediaSessionId numero intero ID della sessione multimediale per i contenuti da riprodurre.
requestId numero intero ID della richiesta, per correlare la richiesta e la risposta
type stringa PLAY (solo valore)
customData oggetto Facoltativo Blob di dati specifico per l'applicazione definito dall'applicazione del mittente
Risposta Trigger Trasmissione Errori
Nessuno Modifica dello stato del ricevitore Un messaggio di modifica dello stato dei contenuti multimediali Stato del player non valido

Ottieni stato

Recupera lo stato dei contenuti multimediali.

Nome Tipo Descrizione
mediaSessionId numero intero Facoltativo L'ID della sessione multimediale dei contenuti multimediali per cui deve essere restituito lo stato dei contenuti multimediali. Se non viene specificato alcun ID, verrà fornito lo stato di tutti gli ID sessione multimediale.
requestId numero intero ID della richiesta, per correlare la richiesta e la risposta
type stringa GET_STATUS (solo valore)
customData oggetto Facoltativo Blob di dati specifico per l'applicazione definito dall'applicazione del mittente
Risposta Trigger Trasmissione Errori
Messaggio MediaStatus il mittente che lo ha richiesto Nessuno Nessuno Nessuno

SetVolume

Imposta il volume dello stream multimediale. Utilizzato per gli effetti di dissolvenza in entrata e in uscita nello stream multimediale. Nota: il volume del destinatario viene modificato utilizzando il valore setVolume del web mittente. Il volume dello stream non deve essere utilizzato insieme al dispositivo di scorrimento del volume o ai pulsanti del volume per regolare il volume del dispositivo. Una modifica del volume del flusso di dati non attiverà alcuna UI sul destinatario.

Nome Tipo Descrizione
mediaSessionId numero intero L'ID sessione multimediale dei contenuti multimediali per i quali viene modificato il volume dello streaming.
requestId numero intero ID della richiesta, per correlare la richiesta e la risposta
type stringa VOLUME (solo valore)
volume Volume Volume dello stream
customData oggetto Facoltativo Blob di dati specifico per l'applicazione definito dall'applicazione del mittente
Risposta Trigger Trasmissione Errori
Nessuno Modifica dello stato del ricevitore Un messaggio di modifica dello stato dei contenuti multimediali Stato del player non valido

Messaggi dal destinatario al mittente

Il destinatario invia due tipi di messaggi:

  • Errori: messaggi Unicast inviati quando si verifica una risposta di errore alla richiesta di un mittente.
  • Stato: trasmetti messaggi.
    • Conseguenza di un'azione avviata dal mittente. Contiene l'ID richiesta della richiesta che ha causato la modifica.
    • Spontanea: ad esempio, a causa di una modifica attivata dall'applicazione destinatario. Il valore dell'ID richiesta sarà 0.

Errore: stato del player non valido

Inviato quando la richiesta del mittente non può essere soddisfatta perché il player non è in uno stato valido. ad esempio se l'applicazione non ha ancora creato un elemento multimediale.

Nome Tipo Descrizione
requestId numero intero ID della richiesta che ha generato questo errore
type stringa INVALID_PLAYER_STATE (solo valore)
customData oggetto Facoltativo Blob di dati specifico per l'applicazione definito dall'applicazione ricevente

Errore: caricamento non riuscito

Inviato quando la richiesta di caricamento non è andata a buon fine. Lo stato del player sarà INATTIVO.

Nome Tipo Descrizione
requestId numero intero ID della richiesta che ha generato questo errore
type stringa LOAD_FAILED (solo valore)
customData oggetto Facoltativo Blob di dati specifico per l'applicazione definito dall'applicazione ricevente

Errore: caricamento annullato

Inviato quando la richiesta di caricamento è stata annullata (è stata ricevuta una seconda richiesta di caricamento).

Nome Tipo Descrizione
requestId numero intero ID della richiesta che ha generato questo errore
type stringa LOAD_CANCELLED (unico valore)
customData oggetto Facoltativo Blob di dati specifico per l'applicazione definito dall'applicazione ricevente

Errore: richiesta non valida

Inviato quando la richiesta non è valida (ad esempio un tipo di richiesta sconosciuto).

Nome Tipo Descrizione
requestId numero intero ID della richiesta che ha generato questo errore
type stringa INVALID_REQUEST (solo valore)
motivo Enum (stringa)

Valori:

  • INVALID_COMMAND  Il comando non è supportato
  • DUPLICATE_REQUESTID  L'ID richiesta non è univoco (il destinatario sta elaborando una richiesta con lo stesso ID)
customData oggetto Facoltativo Blob di dati specifico per l'applicazione definito dall'applicazione ricevente

Stato dei contenuti multimediali

Inviato dopo un cambio di stato o dopo una richiesta di stato dei contenuti multimediali. Verranno inviati solo gli oggetti MediaStatus che sono stati modificati o che sono stati richiesti.

Nome Tipo Descrizione
requestId numero intero ID utilizzato per associare questa risposta di stato alla richiesta che l'ha originata oppure 0 se il messaggio di stato è spontaneo (non attivato da una richiesta del mittente). Le applicazioni dei mittenti generano ID richiesta univoci selezionando un numero casuale e aumentandolo continuamente (non utilizzeranno 0).
type stringa MEDIA_STATUS (solo valore)
stato MediaStatus[] Array di oggetti Media Status. NOTA: l'elemento multimediale in MediaStatus verrà restituito solo se è stato modificato.
customData oggetto Facoltativo Blob di dati specifico per l'applicazione definito dall'applicazione ricevente