Le applicazioni mittenti Google Cast controllano la riproduzione sul dispositivo ricevitore inviando messaggi in formato JSON all'applicazione ricevitore. Allo stesso modo, il destinatario invia messaggi al mittente, anche in formato JSON. I messaggi possono essere comandi del mittente che modificano lo stato del player, risposte a questi comandi del destinatario 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 multimediale Cast deve utilizzare questi messaggi come definiti qui per controllare la riproduzione dei contenuti multimediali sul ricevitore. In questo modo, l'app multimediale offre un'esperienza utente coerente su tutte le piattaforme e garantisce che un'applicazione Cast supporti casi d'uso nuovi e futuri. Queste strutture supportano anche dati personalizzati, se 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 dei contenuti multimediali è 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 esiste un limite per i singoli campi. La dimensione massima del messaggio di trasporto è attualmente di 64 kB.
Strutture di dati dello spazio dei nomi comuni
Un superset di strutture di dati utilizzate da tutti gli artefatti dello spazio dei nomi dei media è definito in uno spazio dei nomi comune.
Immagine
Si tratta della descrizione di un'immagine, inclusi alcuni metadati per consentire all'applicazione mittente di scegliere le immagini, a seconda di come le visualizzerà.
L'altezza e la larghezza sono facoltative solo per un elemento in un array di immagini. Ad esempio, se viene restituito un solo elemento, questi sono facoltativi; se vengono restituiti due elementi, uno deve specificare un'altezza e una larghezza, ma il mittente può scegliere l'opzione "predefinita" se non gli piace quella passata con parametri specifici.
| Nome | Tipo | Descrizione |
|---|---|---|
| url | URI | URI dell'immagine |
| height | integer | (facoltativo) Altezza dell'immagine |
| width | integer | (facoltativo) Larghezza dell'immagine |
Volume
Il volume del flusso multimediale. Utilizzato per gli effetti di dissolvenza in entrata/uscita sul flusso multimediale. (Nota: il volume di sistema viene modificato utilizzando le API del mittente.) Il volume dello stream non deve essere utilizzato insieme al cursore del volume o ai tasti del volume per controllare il volume del dispositivo. Per modificare il volume dello stream, è necessario passare almeno uno dei seguenti parametri.
| Nome | Tipo | Descrizione |
|---|---|---|
| level | doppia | (facoltativo) Livello di volume attuale dello stream come valore compreso tra 0,0 e 1,0, dove 1,0 è il volume massimo. |
| audio disattivato | booleano | Facoltativo Indica se l'audio del dispositivo di trasmissione è disattivato, indipendentemente dal livello del volume |
Strutture di dati dello spazio dei nomi dei media
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 lettore multimediale. Si tratta di una stringa in formato libero e specifica per l'applicazione. Nella maggior parte dei casi, si tratta dell'URL del media, ma il mittente può scegliere di trasmettere una stringa che il destinatario può interpretare correttamente. Lunghezza massima: 1000 caratteri |
| streamType | enum (string) |
Descrive il tipo di artefatto multimediale come uno dei seguenti:
|
| contentType | stringa | Tipo di contenuto MIME del media in riproduzione |
| metadata | oggetto | optional L'oggetto dei metadati dei contenuti multimediali, uno dei seguenti: |
| duration | doppia | (facoltativo) Durata dello stream attualmente in riproduzione in secondi |
| customData | oggetto | (Facoltativo) Blob di dati specifico dell'applicazione definito dall'applicazione mittente o ricevente |
GenericMediaMetadata
Descrive un artefatto multimediale generico.
| Nome | Tipo | Descrizione |
|---|---|---|
| metadataType | integer | 0 (l'unico valore) |
| title | stringa | (facoltativo) Titolo descrittivo dei contenuti. Il player può recuperare autonomamente il titolo utilizzando content_id oppure può riceverlo dal mittente nel messaggio Load. |
| subtitle | stringa | (facoltativo) Sottotitolo descrittivo dei contenuti. Il player può recuperare autonomamente il titolo utilizzando content_id oppure può riceverlo dal mittente nel messaggio Load. |
| immagini | Image[] | Facoltativo . Array di URL di un'immagine associata ai contenuti. Il valore iniziale del campo può essere fornito dal mittente nel messaggio Carica. Devono fornire le dimensioni consigliate |
| releaseDate | stringa (ISO 8601) | Facoltativo Data e ora ISO 8601 in cui sono stati rilasciati questi contenuti. Il player può recuperare autonomamente il titolo utilizzando content_id oppure può riceverlo dal mittente nel messaggio Load. |
MovieMediaMetadata
Descrive un artefatto multimediale di un film.
| Nome | Tipo | Descrizione |
|---|---|---|
| metadataType | integer | 1 (l'unico valore) |
| title | stringa | (facoltativo) Titolo descrittivo dei contenuti. Il player può recuperare autonomamente il titolo utilizzando content_id oppure può riceverlo dal mittente nel messaggio Load. |
| subtitle | stringa | (facoltativo) Sottotitolo descrittivo dei contenuti. Il player può recuperare autonomamente il titolo utilizzando content_id oppure può riceverlo dal mittente nel messaggio Load. |
| studio | stringa | (Facoltativo) Studio che ha pubblicato i contenuti. Il player può recuperare in modo indipendente lo studio utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load |
| immagini | Image[] | Facoltativo . Array di URL di un'immagine associata ai contenuti. Il valore iniziale del campo può essere fornito dal mittente nel messaggio Carica. Devono fornire le dimensioni consigliate |
| releaseDate | stringa (ISO 8601) | Facoltativo Data e ora ISO 8601 in cui sono stati rilasciati questi contenuti. Il player può recuperare autonomamente il titolo utilizzando content_id oppure può riceverlo dal mittente nel messaggio Load. |
TvShowMediaMetadata
Descrive un artefatto multimediale di una puntata di un programma televisivo.
| Nome | Tipo | Descrizione |
|---|---|---|
| metadataType | integer | 2 (l'unico valore) |
| seriesTitle | stringa | facoltativo Titolo descrittivo della serie TV. Il player può recuperare autonomamente il titolo utilizzando content_id oppure può riceverlo dal mittente nel messaggio Load. |
| subtitle | stringa | Facoltativo Sottotitolo descrittivo dell'episodio della serie TV. Il player può recuperare autonomamente il titolo utilizzando content_id oppure può riceverlo dal mittente nel messaggio Load. |
| season | integer | Facoltativo Numero della stagione della serie TV |
| episodio | integer | Facoltativo Numero dell'episodio (nella stagione) della serie TV |
| immagini | Image[] | Facoltativo . Array di URL di un'immagine associata ai contenuti. Il valore iniziale del campo può essere fornito dal mittente nel messaggio Carica. Devono fornire le dimensioni consigliate |
| originalAirDate | stringa (ISO 8601) | Facoltativo : data e ora ISO 8601 in cui è stata pubblicata la puntata. Il player può recuperare in modo indipendente originalAirDate utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load |
MusicTrackMediaMetadata
Descrive un artefatto multimediale di una traccia musicale.
| Nome | Tipo | Descrizione |
|---|---|---|
| metadataType | integer | 3 (l'unico valore) |
| albumName | stringa | Facoltativo Album o raccolta da cui è tratta questa traccia. Il player può recuperare in modo indipendente albumName utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load. |
| title | stringa | facoltativo Nome della traccia (ad esempio, titolo del brano). Il player può recuperare autonomamente il titolo utilizzando content_id oppure può riceverlo dal mittente nel messaggio Load. |
| albumArtist | stringa | Facoltativo Nome dell'artista associato all'album che include questa traccia. Il lettore può recuperare in modo indipendente l'albumArtist utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load |
| artista | stringa | (Facoltativo) Nome dell'artista associato alla traccia multimediale. Il lettore può recuperare l'artista in modo indipendente utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load |
| composer | stringa | Facoltativo Nome del compositore associato alla traccia multimediale. Il player può recuperare in modo indipendente il compositore utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load. |
| trackNumber | integer | Facoltativo Numero della traccia nell'album |
| discNumber | integer | Facoltativo Numero del volume (ad esempio, un disco) dell'album |
| immagini | Image[] | Facoltativo . Array di URL di un'immagine associata ai contenuti. Il valore iniziale del campo può essere fornito dal mittente nel messaggio Carica. Devono fornire le dimensioni consigliate |
| releaseDate | stringa (ISO 8601) | Facoltativo Data e ora ISO 8601 in cui sono stati rilasciati questi contenuti. Il player può recuperare in modo indipendente releaseDate utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load |
PhotoMediaMetadata
Descrive un artefatto multimediale fotografico.
| Nome | Tipo | Descrizione |
|---|---|---|
| metadataType | integer | 4 (l'unico valore) |
| title | stringa | Facoltativo Titolo della fotografia. Il player può recuperare autonomamente il titolo utilizzando content_id oppure può riceverlo dal mittente nel messaggio Load. |
| artista | stringa | (Facoltativo) Nome del fotografo. Il lettore può recuperare l'artista in modo indipendente utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load |
| località | stringa | Facoltativo Posizione verbale in cui è stata scattata la fotografia, ad esempio "Madrid, Spagna". Il player può recuperare in modo indipendente la posizione utilizzando content_id oppure può essere fornita dal mittente nel messaggio Load. |
| latitude | doppia | Facoltativo Valore della latitudine geografica della posizione in cui è stata scattata la fotografia. Il player può recuperare autonomamente la latitudine utilizzando content_id oppure può essere fornita dal mittente nel messaggio Load. |
| longitude | doppia | (Facoltativo) Valore della longitudine geografica della località in cui è stata scattata la fotografia. Il player può recuperare autonomamente la longitudine utilizzando content_id oppure può essere fornita dal mittente nel messaggio Load. |
| width | integer | (facoltativo) Larghezza in pixel della fotografia. Il player può recuperare in modo indipendente la larghezza utilizzando content_id oppure può essere fornita dal mittente nel messaggio Load. |
| height | integer | (Facoltativo) Altezza in pixel della fotografia. Il player può recuperare autonomamente l'altezza utilizzando content_id oppure può essere fornita dal mittente nel messaggio Load. |
| creationDateTime | stringa (ISO 8601) | Facoltativo Data e ora ISO 8601 in cui è stata scattata la fotografia. Il player può recuperare in modo indipendente creationDateTime utilizzando content_id oppure può essere fornito dal mittente nel messaggio Load |
MediaStatus
Descrive lo stato attuale dell'artefatto multimediale rispetto alla sessione.
| Nome | Tipo | Descrizione |
|---|---|---|
| mediaSessionId | integer | ID univoco per la riproduzione di questa sessione specifica. Questo ID viene impostato dal destinatario al caricamento e può essere utilizzato per identificare un'istanza specifica di una riproduzione. Ad esempio, due riproduzioni di "Wish you were here" all'interno della stessa sessione avranno ciascuna un mediaSessionId univoco. |
| media | MediaInformation | (facoltativo, per i messaggi di stato) Descrizione completa dei contenuti in riproduzione. Vengono restituiti nei messaggi di stato solo se MediaInformation è stato modificato. |
| playbackRate | float | Indica se il tempo di riproduzione dei contenuti multimediali sta avanzando e a quale velocità. Questo è indipendente dallo stato del player, poiché il tempo dei contenuti multimediali può arrestarsi in qualsiasi stato. 1.0 è la velocità normale, 0.5 è la modalità Slow Motion |
| playerState | enum (stringa) | Descrive lo stato del giocatore come uno dei seguenti:
|
| idleReason | enum (stringa) | Facoltativo Se playerState è IDLE e il motivo per cui è diventato IDLE è noto, viene fornita questa proprietà. Se il player è IDLE perché è appena stato avviato, questa proprietà non verrà fornita; se il player si trova in un altro stato, questa proprietà non deve essere fornita. Si applicano i seguenti valori:
|
| currentTime | doppia | La posizione attuale del media player dall'inizio dei contenuti, in secondi. Se si tratta di contenuti di un live streaming, questo campo rappresenta il tempo in secondi dall'inizio dell'evento che deve essere noto al giocatore. |
| supportedMediaCommands | bandiere | Flag che descrivono i comandi multimediali supportati dal lettore multimediale:
Le combinazioni sono descritte come somme; ad esempio, Pausa+Cerca+Volume streaming+Muto == 15. |
| volume | Volume | Volume dello stream |
| customData | oggetto | Facoltativo Blob di dati specifico dell'applicazione definito dall'applicazione destinataria |
Comandi dal mittente al destinatario
Questi comandi controllano il lettore multimediale. Tutti gli oggetti customData nei messaggi riportati di seguito devono essere facoltativi (ovvero il destinatario deve eseguire il degrado in modo appropriato se i dati non vengono trasmessi). In questo modo, le app di controllo remoto generiche funzioneranno correttamente.
Carica
Carica nuovi contenuti nel media player.
| Nome | Tipo | Descrizione |
|---|---|---|
| requestId | integer | ID della richiesta, per correlare richiesta e risposta |
| type | stringa | LOAD (solo valore) |
| media | MediaInformation | Metadati (incluso contentId) del media da caricare |
| autoplay | booleano | (facoltativo) (il valore predefinito è true) Se viene specificato il parametro di riproduzione automatica, il lettore multimediale inizierà a riprodurre i contenuti al caricamento. Anche se la riproduzione automatica non è specificata, l'implementazione del media player potrebbe scegliere di iniziare la riproduzione immediatamente. Se la riproduzione viene avviata, lo stato del player nella risposta deve essere impostato su BUFFERING, altrimenti deve essere impostato su PAUSED |
| currentTime | doppia | (Facoltativo) secondi trascorsi dall'inizio dei contenuti. Se i contenuti sono live e la posizione non è specificata, lo stream inizierà dalla posizione live. |
| customData | oggetto | (Facoltativo) Blob di dati specifico dell'applicazione definito dall'applicazione mittente |
| Risposta | Trigger | Trasmissione | Errori |
|---|---|---|---|
| Nessuno | Modifica dello stato del destinatario | Un messaggio Modifica dello stato dei contenuti multimediali | Invalid Player State Load Failed Load Cancelled |
Metti in pausa
Mette in pausa la riproduzione dei contenuti correnti. Attiva una notifica di evento STATUS per tutte le applicazioni mittenti.
| Nome | Tipo | Descrizione |
|---|---|---|
| mediaSessionId | integer | ID della sessione multimediale da mettere in pausa |
| requestId | integer | ID della richiesta, da utilizzare per correlare richiesta/risposta |
| type | stringa | PAUSE (unico valore) |
| customData | oggetto | (Facoltativo) Blob di dati specifico dell'applicazione definito dall'applicazione mittente |
| Risposta | Trigger | Trasmissione | Errori |
|---|---|---|---|
| Nessuno | Modifica dello stato del destinatario | Un messaggio di modifica dello stato dei contenuti multimediali | Invalid Player State |
Cerca
Imposta la posizione corrente nello stream. Attiva una notifica di evento STATUS per tutte le applicazioni mittenti. Se la posizione fornita non rientra nell'intervallo di posizioni valide per i contenuti attuali, il player deve scegliere una posizione valida il più vicina possibile a quella richiesta.
| Nome | Tipo | Descrizione |
|---|---|---|
| mediaSessionId | integer | ID della sessione multimediale in cui è impostata la posizione dello stream |
| requestId | integer | ID della richiesta, per correlare richiesta e risposta |
| type | stringa | SEEK (solo valore) |
| resumeState | enum (stringa) | Facoltativo Se non è impostato, lo stato di riproduzione non cambierà. Si applicano i seguenti valori:
|
| currentTime | doppia | (Facoltativo) secondi trascorsi dall'inizio dei contenuti. Se i contenuti sono live e la posizione non è specificata, lo stream inizierà dalla posizione live. |
| customData | oggetto | (Facoltativo) Blob di dati specifico dell'applicazione definito dall'applicazione mittente |
| Risposta | Trigger | Trasmissione | Errori |
|---|---|---|---|
| Nessuno | Modifica dello stato del destinatario | Un messaggio Modifica dello stato dei contenuti multimediali | Invalid Player State |
Interrompi
Interrompe la riproduzione dei contenuti correnti. Attiva una notifica di evento STATUS per tutte le applicazioni mittenti. Dopo questo comando, i contenuti non verranno più caricati e mediaSessionId verrà invalidato.
| Nome | Tipo | Descrizione |
|---|---|---|
| mediaSessionId | integer | ID della sessione multimediale per l'interruzione dei contenuti |
| requestId | integer | ID della richiesta, per correlare richiesta e risposta |
| type | stringa | STOP (solo valore) |
| customData | oggetto | (Facoltativo) Blob di dati specifico dell'applicazione definito dall'applicazione mittente |
| Risposta | Trigger | Trasmissione | Errori |
|---|---|---|---|
| Nessuno | Modifica dello stato del destinatario | Un messaggio Modifica dello stato dei contenuti multimediali | Invalid Player State |
Riproduci
Avvia la riproduzione dei contenuti caricati con la chiamata di caricamento, la riproduzione continua dalla posizione temporale corrente.
| Nome | Tipo | Descrizione |
|---|---|---|
| mediaSessionId | integer | ID della sessione multimediale per i contenuti da riprodurre |
| requestId | integer | ID della richiesta, per correlare richiesta e risposta |
| type | stringa | PLAY (unico valore) |
| customData | oggetto | (Facoltativo) Blob di dati specifico dell'applicazione definito dall'applicazione mittente |
| Risposta | Trigger | Trasmissione | Errori |
|---|---|---|---|
| Nessuno | Modifica dello stato del destinatario | Un messaggio Modifica dello stato dei contenuti multimediali | Invalid Player State |
Ottieni stato
Recupera lo stato dei contenuti multimediali.
| Nome | Tipo | Descrizione |
|---|---|---|
| mediaSessionId | integer | (Facoltativo) ID sessione multimediale del media per cui deve essere restituito lo stato. Se non viene fornito alcun valore, verrà fornito lo stato di tutti gli ID sessione media. |
| requestId | integer | ID della richiesta, per correlare richiesta e risposta |
| type | stringa | GET_STATUS (unico valore) |
| customData | oggetto | (Facoltativo) Blob di dati specifico dell'applicazione definito dall'applicazione mittente |
| Risposta | Trigger | Trasmissione | Errori |
|---|---|---|---|
| Messaggio MediaStatus al mittente che lo ha richiesto | Nessuno | Nessuno | Nessuno |
SetVolume
Imposta il volume dello stream multimediale. Utilizzato per gli effetti di dissolvenza in entrata/uscita sul flusso multimediale. (Nota: il volume del ricevitore viene modificato utilizzando il mittente web setVolume.) Il volume dello stream non deve essere utilizzato insieme al cursore del volume o ai tasti del volume per controllare il volume del dispositivo. Una modifica del volume dello stream non attiverà alcuna UI sul ricevitore.
| Nome | Tipo | Descrizione |
|---|---|---|
| mediaSessionId | integer | ID sessione contenuti multimediali dei contenuti multimediali per cui viene modificato il volume dello stream |
| requestId | integer | ID della richiesta, per correlare richiesta e risposta |
| type | stringa | VOLUME (solo valore) |
| volume | Volume | Volume dello stream |
| customData | oggetto | (Facoltativo) Blob di dati specifico dell'applicazione definito dall'applicazione mittente |
| Risposta | Trigger | Trasmissione | Errori |
|---|---|---|---|
| Nessuno | Modifica dello stato del destinatario | Un messaggio Modifica dello stato dei contenuti multimediali | Invalid Player State |
Messaggi dal destinatario al mittente
Il destinatario invia due tipi di messaggi:
- Errori: messaggi unicast inviati quando viene restituita una risposta di errore a una richiesta del mittente.
- Stato: trasmetti messaggi.
- Conseguenza di un'azione avviata dal mittente. Contiene l'ID richiesta della richiesta che ha causato la modifica.
- Spontaneo: ad esempio, a causa di una modifica attivata dall'applicazione ricevitore. RequestId sarà 0.
Errore: stato del giocatore non valido
Inviato quando la richiesta del mittente non può essere soddisfatta perché il player non si trova in uno stato valido. Ad esempio, se l'applicazione non ha ancora creato un elemento multimediale.
| Nome | Tipo | Descrizione |
|---|---|---|
| requestId | integer | ID della richiesta che ha generato questo errore |
| type | stringa | INVALID_PLAYER_STATE (unico valore) |
| customData | oggetto | Facoltativo Blob di dati specifico dell'applicazione definito dall'applicazione destinataria |
Errore: caricamento non riuscito
Inviata quando la richiesta di caricamento non è riuscita. Lo stato del player sarà IDLE.
| Nome | Tipo | Descrizione |
|---|---|---|
| requestId | integer | ID della richiesta che ha generato questo errore |
| type | stringa | LOAD_FAILED (solo valore) |
| customData | oggetto | Facoltativo Blob di dati specifico dell'applicazione definito dall'applicazione destinataria |
Errore: caricamento annullato
Inviato quando la richiesta di caricamento è stata annullata (è stata ricevuta una seconda richiesta di caricamento).
| Nome | Tipo | Descrizione |
|---|---|---|
| requestId | integer | ID della richiesta che ha generato questo errore |
| type | stringa | LOAD_CANCELLED (unico valore) |
| customData | oggetto | Facoltativo Blob di dati specifico dell'applicazione definito dall'applicazione destinataria |
Errore: richiesta non valida
Inviato quando la richiesta non è valida (ad esempio, un tipo di richiesta sconosciuto).
| Nome | Tipo | Descrizione |
|---|---|---|
| requestId | integer | ID della richiesta che ha generato questo errore |
| type | stringa | INVALID_REQUEST (unico valore) |
| motivo | Enum (stringa) | Valori:
|
| customData | oggetto | Facoltativo Blob di dati specifico dell'applicazione definito dall'applicazione destinataria |
Stato dei contenuti multimediali
Inviato dopo una modifica dello stato o dopo una richiesta di stato dei contenuti multimediali. Verranno inviati solo gli oggetti MediaStatus modificati o richiesti.
| Nome | Tipo | Descrizione |
|---|---|---|
| requestId | integer | ID utilizzato per correlare questa risposta di stato alla richiesta che l'ha generata o 0 se il messaggio di stato è spontaneo (non attivato da una richiesta del mittente). Le applicazioni mittenti genereranno ID richiesta univoci selezionando un numero casuale e aumentandolo continuamente (non utilizzeranno lo zero). |
| type | stringa | MEDIA_STATUS (unico valore) |
| status | 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 dell'applicazione definito dall'applicazione destinataria |