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:
|
| 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:
|
| 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:
|
| 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:
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:
|
| 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:
|
| 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 |