Messaggi multimediali per la riproduzione

Le applicazioni dei mittenti di Google Cast controllano la riproduzione sul dispositivo del destinatario inviando messaggi in formato JSON all'applicazione del ricevitore. Analogamente, il destinatario invia i messaggi al mittente, anche in formato JSON. I messaggi possono essere comandi del mittente che modificano lo stato del player, risposte a tali comandi dal ricevitore o strutture di dati che descrivono i contenuti multimediali per l'applicazione del destinatario.

In base ai Termini di servizio aggiuntivi per gli sviluppatori dell'SDK Google Cast, un'applicazione di trasmissione di contenuti multimediali deve usare questi messaggi come definiti qui per controllare la riproduzione dei contenuti multimediali sul ricevitore. L'app multimediale offre così un'esperienza utente coerente su più piattaforme e garantisce che l'applicazione Cast supporterà i casi d'uso nuovi e futuri. Queste strutture supportano anche i dati personalizzati, ove opportuno, e un'applicazione può definire i propri messaggi per i comandi non supportati dall'SDK.

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

Nota:i messaggi e le strutture di questa specifica hanno una dimensione massima implicita determinata dalle dimensioni massime di un messaggio di trasporto, non esiste un limite per i singoli campi. Al momento, le dimensioni massime per i messaggi di trasporto sono di 64 kByte.

Strutture di dati comuni dello spazio dei nomi

Un soprainsieme di strutture di dati utilizzato da tutti gli artefatti dello spazio dei nomi dei contenuti multimediali è definito in uno spazio dei nomi comune.

Immagine

È la descrizione di un'immagine, che include una piccola quantità di metadati per consentire all'applicazione del mittente di scegliere le immagini, a seconda di come verrà visualizzata.

L'altezza e la larghezza sono facoltative per un solo elemento in un array di immagini. Ad esempio, se c'è un solo articolo restituito, allora è facoltativo. Se ci sono due articoli restituiti, un articolo deve specificare altezza e larghezza, ma il mittente può scegliere di optare per l'opzione "predefinita" se non soddisfa il requisito con parametri specifici.

Nome Tipo Descrizione
URL URI URI dell'immagine
altezza integer (Facoltativo) Altezza dell'immagine
larghezza integer (Facoltativo) Larghezza dell'immagine

Volume

Il volume dello streaming multimediale. Utilizzato per effetti di dissolvenza in dissolvenza/sfumatura sullo streaming multimediale. Nota: il volume di sistema viene modificato utilizzando le API del mittente. Il volume del dispositivo non deve essere utilizzato insieme al dispositivo di scorrimento del volume o ai pulsanti del volume. Per modificare il volume del flusso, deve essere trasmesso almeno uno dei seguenti parametri.

Nome Tipo Descrizione
a livello double (Facoltativo) Livello attuale del volume dei flussi come valore compreso tra 0,0 e 1,0, dove 1,0 è il volume massimo.
audio disattivato boolean Facoltativo Che l'audio del dispositivo di trasmissione sia disattivato, indipendentemente dal livello del 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.

Informazioni sui contenuti multimediali

Questa struttura di dati descrive uno stream multimediale.

Nome Tipo Descrizione
ID contenuto string Identificatore specifico del servizio per i contenuti attualmente caricati dal media player. Si tratta di una stringa in formato libero e specifica per l'applicazione. Nella maggior parte dei casi, si tratta dell'URL dei contenuti multimediali, ma il mittente può scegliere di passare una stringa che il destinatario può interpretare correttamente. Lunghezza massima: 1000
Tipo di flusso enum
(stringa)

Descrive il tipo di elemento multimediale come uno dei seguenti:

  • NESSUNA
  • BUFFERED
  • IN DIRETTA
Tipo di contenuti string Tipo di contenuti MIME del contenuto multimediale riprodotto
metadati oggetto

Facoltativo: l'oggetto metadati multimediale, uno dei seguenti elementi:

durata double (Facoltativo) Durata dello stream attualmente in riproduzione in secondi
customData oggetto Facoltativo: blob di dati specifico dell'applicazione definito dall'applicazione del mittente o dall'applicazione del destinatario

MetadatiMediaGenerici

Descrive un elemento multimediale generico.

Nome Tipo Descrizione
metadati integer 0 (l'unico valore)
title string (Facoltativo) Titolo descrittivo dei contenuti. Il player può recuperare il titolo in modo indipendente utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load.
sottotitolo string (Facoltativo) Sottotitolo descrittivo dei contenuti. Il player può recuperare il titolo in modo indipendente utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load.
immagini Immagine[] (Facoltativo) Array di URL a un'immagine associata ai contenuti. Il valore iniziale del campo può essere fornito dal mittente nel messaggio Carica. Dovrebbe fornire le dimensioni consigliate
releaseDate stringa (ISO 8601) (Facoltativo) Data e ora ISO 8601 di rilascio dei contenuti. Il player può recuperare il titolo in modo indipendente utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load.

Metadati MediaMedia

Descrive l'elemento multimediale di un film.

Nome Tipo Descrizione
metadati integer 1 (l'unico valore)
title string (Facoltativo) Titolo descrittivo dei contenuti. Il player può recuperare il titolo in modo indipendente utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load.
sottotitolo string (Facoltativo) Sottotitolo descrittivo dei contenuti. Il player può recuperare il titolo in modo indipendente utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load.
studio string Facoltativo: Studio che ha pubblicato i contenuti. Il player può recuperare lo studio in modo indipendente utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load.
immagini Immagine[] (Facoltativo) Array di URL a un'immagine associata ai contenuti. Il valore iniziale del campo può essere fornito dal mittente nel messaggio Carica. Dovrebbe fornire le dimensioni consigliate
releaseDate stringa (ISO 8601) (Facoltativo) Data e ora ISO 8601 di rilascio dei contenuti. Il player può recuperare il titolo in modo indipendente utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load.

TvShowMediaMetadata

Descrive un elemento multimediale della puntata di un programma TV.

Nome Tipo Descrizione
metadati integer 2 (l'unico valore)
titolo serie string (Facoltativo) Titolo descrittivo della serie TV. Il player può recuperare il titolo in modo indipendente utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load.
sottotitolo string Facoltativo: sottotitolo descrittivo della puntata TV. Il player può recuperare il titolo in modo indipendente utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load.
stagione integer (Facoltativo) Numero di stagione della serie TV
episodio integer Facoltativo Numero della puntata (nella stagione) del programma TV
immagini Immagine[] (Facoltativo) Array di URL a un'immagine associata ai contenuti. Il valore iniziale del campo può essere fornito dal mittente nel messaggio Carica. Dovrebbe fornire le dimensioni consigliate
originaleAirDate stringa (ISO 8601) (Facoltativo) Data e ora ISO 8601 di pubblicazione della puntata. Il player può recuperare in modo originale originAirDate utilizzando content_id o può essere fornito dal mittente nel messaggio Carica

Metadati multimediale traccia musicale

Descrive un elemento multimediale della traccia musicale.

Nome Tipo Descrizione
metadati integer 3 (l'unico valore)
nomealbum string (Facoltativo) Album o raccolta da cui viene tratta questa traccia. Il player può recuperare l'albumName in modo indipendente utilizzando content_id o può essere fornito dal mittente nel messaggio Load.
title string (Facoltativo) Nome della traccia (ad esempio, titolo del brano). Il player può recuperare il titolo in modo indipendente utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load.
albumArtist string (Facoltativo) Nome dell'artista associato all'album in cui è presente questa traccia. Il player può recuperare in modo indipendente albumArtist utilizzando content_id oppure può essere fornito dal mittente nel messaggio Carica
artista string Facoltativo: nome dell'artista associato alla traccia multimediale. Il player può recuperare l'artista in modo indipendente utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load.
compositore string Facoltativo Il nome del compositore associato alla traccia multimediale. Il player può recuperare il compositore in modo indipendente utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load.
NumeroTraccia integer facoltativo Numero della traccia dell'album
Numero disco integer (Facoltativo) Il numero del volume (ad esempio, un disco) dell'album
immagini Immagine[] (Facoltativo) Array di URL a un'immagine associata ai contenuti. Il valore iniziale del campo può essere fornito dal mittente nel messaggio Carica. Dovrebbe fornire le dimensioni consigliate
releaseDate stringa (ISO 8601) (Facoltativo) Data e ora ISO 8601 di rilascio dei contenuti. Il player può recuperare in modo indipendente releaseDate utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load.

Metadati fotomedia

Descrive un elemento multimediale fotografico.

Nome Tipo Descrizione
metadati integer 4 (l'unico valore)
title string (Facoltativo) Titolo della foto. Il player può recuperare il titolo in modo indipendente utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load.
artista string (Facoltativo) Nome del fotografo. Il player può recuperare l'artista in modo indipendente utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load.
località string (Facoltativo) Posizione verbale in cui è stata scattata la foto, ad esempio "Madrid, Spagna". Il player può recuperare la posizione in modo indipendente utilizzando content_id o può essere fornita dal mittente nel messaggio Load.
latitude double (Facoltativo) Il valore della latitudine geografica per il luogo in cui è stata scattata la foto. Il player può recuperare in modo indipendente la latitudine utilizzando content_id o può essere fornito dal mittente nel messaggio Carica
longitude double (Facoltativo) Valore geografico della longitudine della località in cui è stata scattata la foto. Il player può recuperare in modo indipendente la longitudine utilizzando content_id o può essere fornito dal mittente nel messaggio Carica
larghezza integer (Facoltativo) Larghezza in pixel della fotografia. Il player può recuperare la larghezza in modo indipendente utilizzando content_id o può essere fornito dal mittente nel messaggio Load.
altezza integer (Facoltativo) Altezza in pixel della fotografia. Il player può recuperare l'altezza in modo indipendente utilizzando content_id o può essere fornito dal mittente nel messaggio Load.
creationDateTime stringa (ISO 8601) (Facoltativo) Data e ora ISO 8601 in cui è stata scattata la foto. Il player può recuperare il valore createDateTime in modo indipendente utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load.

Stato dei contenuti multimediali

Descrive lo stato corrente dell'elemento multimediale in relazione alla sessione.

Nome Tipo Descrizione
ID sessione multimediale integer ID univoco per la riproduzione di questa sessione specifica. Questo ID viene impostato dal ricevitore in corrispondenza di LOAD e può essere utilizzato per identificare un'istanza specifica di una riproduzione. Ad esempio, due riproduzioni di "Vorresti essere qui" all'interno della stessa sessione, avrebbero ciascuna un valore MediaSessionId univoco.
contenuti multimediali Informazioni multimediali (Facoltativo per i messaggi di stato) Descrizione completa dei contenuti riprodotti. Vengono restituiti solo in messaggi di stato se l'elemento MediaInformation è cambiato.
percentuale di riproduzione numero in virgola mobile Indica se il tempo multimediale è in corso e a quale frequenza. Questo è indipendente dallo stato del player, poiché il tempo di visualizzazione del contenuto può essere interrotto in qualsiasi stato. 1,0 è il tempo normale, 0,5 è in slow motion
StatoGiocatore enum (stringa)

Descrive lo stato del player come una delle seguenti:

  • INATTIVO Il player non è stato ancora caricato
  • IN RIPRODUZIONE Il player sta riproducendo attivamente i contenuti
  • BUFFERING Il player è in modalità PLAY, ma non sta riproducendo contenuti (il momento corrente non cambia)
  • IN PAUSA Il player è in pausa
Motivo_inattivo enum (stringa)

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

  • ANNULLATO Un mittente ha richiesto di interrompere la riproduzione usando il comando STOP
  • INTERRUTTO Un mittente ha richiesto la riproduzione di un contenuto multimediale diverso utilizzando il comando LOAD.
  • TERMINATO La riproduzione dei contenuti multimediali è stata completata
  • ERROR Il contenuto multimediale è stato interrotto a causa di un errore, ad esempio se il player non può scaricare i contenuti multimediali a causa di problemi di rete.
currentTime double La posizione attuale del lettore multimediale dall'inizio dei contenuti, in secondi. Se si tratta di un contenuto in live streaming, questo campo rappresenta il tempo in secondi dall'inizio dell'evento, che dovrebbe essere noto al player.
supportedMediaCommands flags

Contrassegni che descrivono i comandi multimediali supportati dal lettore multimediale:

  • 1 Metti in pausa
  • 2 Cerca
  • 4 Volume stream
  • 8 Disattivare lo streaming
  • 16 Vai avanti
  • 32 Vai indietro

Le combinazioni sono descritte come sommazioni; ad esempio, Metti in pausa + Cerca + Stream + + Audio = 15.

volume Volume Volume stream
customData oggetto Facoltativo: blob di dati specifico dell'applicazione definito dall'applicazione del destinatario

Comandi dal mittente al destinatario

Questi comandi controllano il media player. Tutti gli oggetti customData nei messaggi di seguito devono essere facoltativi (ad esempio, se i dati non vengono trasmessi correttamente, il destinatario deve eseguire correttamente la riduzione). In questo modo le app di controllo remoto generico funzionano correttamente.

Carica

Carica nuovi contenuti nel lettore multimediale.

Nome Tipo Descrizione
ID richiesta integer ID della richiesta per correlarla.
type string CARICA(solo valore)
contenuti multimediali Informazioni multimediali Metadati (incluso contentId) dei contenuti multimediali da caricare
riproduzione automatica boolean

facoltativo (default è vero) Se il parametro di riproduzione automatica viene specificato, il media player inizia a riprodurre i contenuti dopo il caricamento. Anche se la riproduzione automatica non è specificata, l'implementazione del media player potrebbe scegliere di iniziare immediatamente la riproduzione. Se la riproduzione è iniziata, 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 pubblicati e la posizione non è specificata, lo stream inizierà dalla posizione in diretta
customData oggetto Facoltativo: blob di dati specifico dell'applicazione definito dall'applicazione del mittente
Risposta Trigger Trasmissioni Errori
Nessuno Modifica dello stato del destinatario Un messaggio Modifica stato multimediale Stato del player non valido
Caricamento non riuscito
Caricamento annullato

Pausa

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

Nome Tipo Descrizione
ID sessione multimediale integer ID della sessione multimediale da mettere in pausa
ID richiesta integer ID della richiesta, da utilizzare per correlare richiesta/risposta
type string PAUSA (solo valore)
customData oggetto Facoltativo: blob di dati specifico dell'applicazione definito dall'applicazione del mittente
Risposta Trigger Trasmissioni Errori
Nessuno Modifica dello stato del destinatario Un messaggio Modifica stato multimediale Stato del player non valido

Ricerca

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

Nome Tipo Descrizione
ID sessione multimediale integer ID della sessione multimediale in cui è impostata la posizione dello stream
ID richiesta integer ID della richiesta per correlarla.
type string CERCA (solo valore)
resumeState enum (stringa)

(Facoltativo)Se non è impostato, lo stato della riproduzione non cambierà; si applicano i seguenti valori:

  • PLAYBACK_START Forza l'avvio dei contenuti multimediali
  • PLAYBACK_PAUSE Forza la pausa dei contenuti multimediali
currentTime double (Facoltativo) Secondi dall'inizio dei contenuti. Se i contenuti sono pubblicati e la posizione non è specificata, lo stream inizierà dalla posizione in diretta
customData oggetto Facoltativo: blob di dati specifico dell'applicazione definito dall'applicazione del mittente
Risposta Trigger Trasmissioni Errori
Nessuno Modifica dello stato del destinatario Un messaggio Modifica stato multimediale Stato del player non valido

Arresta

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 l'elemento mediaSessionId verrà invalidato.

Nome Tipo Descrizione
ID sessione multimediale integer ID della sessione multimediale per l'interruzione dei contenuti
ID richiesta integer ID della richiesta per correlarla.
type string STOP (solo valore)
customData oggetto Facoltativo: blob di dati specifico dell'applicazione definito dall'applicazione del mittente
Risposta Trigger Trasmissioni Errori
Nessuno Modifica dello stato del destinatario Un messaggio Modifica stato multimediale Stato del player non valido

Riproduci

Consente di avviare la riproduzione dei contenuti caricati con la chiamata di caricamento, mentre la riproduzione della riproduzione continua dalla posizione attuale.

Nome Tipo Descrizione
ID sessione multimediale integer ID della sessione multimediale per la riproduzione dei contenuti
ID richiesta integer ID della richiesta per correlarla.
type string PLAY (solo valore)
customData oggetto Facoltativo: blob di dati specifico dell'applicazione definito dall'applicazione del mittente
Risposta Trigger Trasmissioni Errori
Nessuno Modifica dello stato del destinatario Un messaggio Modifica stato multimediale Stato del player non valido

Ottieni stato

Recupera lo stato dei contenuti multimediali.

Nome Tipo Descrizione
ID sessione multimediale integer Facoltativo: ID sessione multimediale del supporto per il quale restituire lo stato dei contenuti multimediali. Se non ne viene specificato nessuno, verrà indicato lo stato per tutti gli ID sessione multimediale.
ID richiesta integer ID della richiesta per correlarla.
type string GET_STATUS (solo valore)
customData oggetto Facoltativo: blob di dati specifico dell'applicazione definito dall'applicazione del mittente
Risposta Trigger Trasmissioni Errori
Messaggio MediaStatus per il mittente che lo ha richiesto Nessuno Nessuno Nessuno

Imposta volume

Imposta il volume dello stream multimediale. Utilizzato per effetti di dissolvenza in dissolvenza/sfumatura sullo streaming multimediale. (Nota: il volume del destinatario viene modificato utilizzando il mittente web setVolume.) Il volume del flusso non deve essere utilizzato in combinazione con il dispositivo di scorrimento del volume o con i pulsanti del volume per controllare il volume del dispositivo. Una variazione del volume del flusso non attiverà alcuna UI sul ricevitore.

Nome Tipo Descrizione
ID sessione multimediale integer ID sessione multimediale dei contenuti multimediali per i quali viene modificato il volume dello stream
ID richiesta integer ID della richiesta per correlarla.
type string VOLUME (solo valore)
volume Volume Volume stream
customData oggetto Facoltativo: blob di dati specifico dell'applicazione definito dall'applicazione del mittente
Risposta Trigger Trasmissioni Errori
Nessuno Modifica dello stato del destinatario Un messaggio Modifica stato multimediale Stato del player non valido

Messaggi dal destinatario al mittente

Il destinatario invia due tipi di messaggi:

  • Errori: messaggi Unicast inviati quando è presente una risposta di errore a una richiesta del mittente.
  • Stato: trasmetti messaggi.
    • Il risultato di un'azione avviata dal mittente. Contiene il valore requestId della richiesta che ha causato la modifica.
    • Spontanea: ad esempio, a causa di una modifica attivata dall'applicazione del destinatario. L'ID richiesta sarà 0.

Errore: stato del player non valido

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

Nome Tipo Descrizione
ID richiesta integer ID della richiesta che ha generato questo errore
type string INVALID_PLAYER_STATE (solo valore)
customData oggetto Facoltativo: blob di dati specifico dell'applicazione definito dall'applicazione del destinatario

Errore: caricamento non riuscito

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

Nome Tipo Descrizione
ID richiesta integer ID della richiesta che ha generato questo errore
type string LOAD_FAILED (solo valore)
customData oggetto Facoltativo: blob di dati specifico dell'applicazione definito dall'applicazione del destinatario

Errore: caricamento annullato

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

Nome Tipo Descrizione
ID richiesta integer ID della richiesta che ha generato questo errore
type string LOAD_CANCELLED (solo valore)
customData oggetto Facoltativo: blob di dati specifico dell'applicazione definito dall'applicazione del destinatario

Errore: richiesta non valida

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

Nome Tipo Descrizione
ID richiesta integer ID della richiesta che ha generato questo errore
type string 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 dell'applicazione definito dall'applicazione del destinatario

Stato dei contenuti multimediali

Inviato dopo una modifica dello stato o dopo una richiesta di stato multimediale. Verranno inviati solo gli oggetti MediaStatus che sono stati modificati o richiesti.

Nome Tipo Descrizione
ID richiesta integer ID utilizzato per mettere in correlazione questa risposta di stato con la richiesta che l'ha generata oppure con 0 se il messaggio di stato è spontaneo (non attivato da una richiesta del mittente). Le applicazioni del mittente generano ID di richiesta univoci selezionando un numero casuale e aumentandolo continuamente (non useranno 0).
type string MEDIA_STATUS(solo valore)
stato Stato dei contenuti multimediali[] Array di oggetti Media Status. NOTA: l'elemento multimediale in MediaStatus viene restituito solo se è cambiato.
customData oggetto Facoltativo: blob di dati specifico dell'applicazione definito dall'applicazione del destinatario