Le risposte multimediali consentono alle Azioni di riprodurre contenuti audio con una durata di riproduzione superiore al limite di 240 secondi di SSML. Le risposte multimediali funzionano sia su dispositivi di solo audio sia su dispositivi in grado di visualizzare contenuti visivi. Su un display, le risposte multimediali sono accompagnate da un componente visivo con controlli multimediali e (facoltativamente) un fermo immagine.
Quando definisci una risposta multimediale, utilizza un candidato con entrambe le funzionalità delle piattaforme RICH_RESPONSE
e LONG_FORM_AUDIO
in modo che l'Assistente Google restituisca la risposta multimediale solo sui dispositivi supportati. Puoi utilizzare
una sola risposta rich media per oggetto content
in un prompt.
L'audio per la riproduzione deve essere in un file MP3 formattato correttamente. I file MP3 devono essere ospitati su un server web ed essere disponibili pubblicamente tramite un URL HTTPS. Il live streaming è supportato solo per il formato MP3.
![Esempio di risposta multimediale su smart display](https://developers.google.cn/static/assistant/conversational/images/smart-display/media.png?authuser=5&hl=it)
Comportamento
![Esempio di risposta multimediale su uno smartphone](https://developers.google.cn/static/assistant/conversational/images/media.png?authuser=5&hl=it)
Il componente principale di una risposta multimediale è la scheda a traccia singola. La scheda consente all'utente di:
- Riproduci di nuovo gli ultimi 10 secondi
- Vai avanti di 30 secondi
- Visualizzare la durata totale dei contenuti multimediali
- Visualizzare un indicatore di avanzamento della riproduzione di contenuti multimediali
- Visualizzare il tempo di riproduzione trascorso
Le risposte multimediali supportano i seguenti controlli audio per le interazioni vocali, tutti gestiti dall'Assistente Google:
- "Hey Google, riproduci."
- "Hey Google, metti in pausa."
- "Hey Google, interrompi."
- "Hey Google, ricomincia da capo."
Gli utenti possono regolare il volume anche dicendo frasi come "Hey Google, alza il volume" o "Hey Google, imposta il volume al 50%". Gli intent nell'Azione hanno la precedenza se gestiscono frasi di addestramento simili. Consenti all'assistente di gestire queste richieste degli utenti, a meno che l'Azione non abbia un motivo specifico.
Comportamento sugli smartphone Android
Sui telefoni Android, i controlli multimediali sono disponibili anche quando il telefono è bloccato. I controlli multimediali vengono visualizzati anche nell'area di notifica e gli utenti possono visualizzare le risposte multimediali quando viene soddisfatta una delle seguenti condizioni:
- L'Assistente Google è in primo piano e lo schermo del telefono è attivo.
- L'utente esce dall'Assistente Google durante la riproduzione dell'audio e torna all'Assistente Google entro 10 minuti dal completamento della riproduzione. Quando torna all'Assistente Google, l'utente vede la scheda dei contenuti multimediali e i chip di suggerimenti.
Proprietà
Le risposte multimediali hanno le seguenti proprietà:
Proprietà | Tipo | Requisito | Descrizione |
---|---|---|---|
media_type |
MediaType |
Obbligatorie | Tipo multimediale della risposta fornita. Restituisci MEDIA_STATUS_ACK
quando confermi uno stato dei contenuti multimediali. |
start_offset |
stringa | Facoltativo | Cerca posizione per avviare la prima traccia multimediale. Specifica il valore in secondi, con i secondi frazionari espressi con un massimo di nove cifre decimali e termina con il suffisso "s". Ad esempio, 3 secondi e 1 nanosecondo sono espressi come "3,000000001s". |
optional_media_controls |
array di OptionalMediaControls |
Facoltativo | Attiva la proprietà di ricezione dei callback quando un utente modifica lo stato di riproduzione dei contenuti multimediali (ad esempio mettendo in pausa o interrompendo la riproduzione di contenuti multimediali). |
media_objects |
array di MediaObject |
Obbligatorie | Rappresenta gli oggetti multimediali da includere nel prompt. Quando riconosci uno stato dei contenuti multimediali con MEDIA_STATUS_ACK , non fornire oggetti multimediali. |
first_media_object_index |
numero intero | Facoltativo | Indice in base 0 del primo MediaObject in media_objects da riprodurre. Se non specificato, zero o fuori intervallo, la riproduzione inizia al primo MediaObject .
|
repeat_mode |
RepeatMode |
Facoltativo | Modalità di ripetizione per l'elenco di oggetti multimediali. |
Codice campione
YAML
candidates: - first_simple: variants: - speech: This is a media response. content: media: start_offset: 2.12345s optional_media_controls: - PAUSED - STOPPED media_objects: - name: Media name description: Media description url: 'https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3' image: large: url: 'https://storage.googleapis.com/automotive-media/album_art.jpg' alt: Jazz in Paris album art media_type: AUDIO
JSON
{ "candidates": [ { "first_simple": { "variants": [ { "speech": "This is a media response." } ] }, "content": { "media": { "start_offset": "2.12345s", "optional_media_controls": [ "PAUSED", "STOPPED" ], "media_objects": [ { "name": "Media name", "description": "Media description", "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3", "image": { "large": { "url": "https://storage.googleapis.com/automotive-media/album_art.jpg", "alt": "Jazz in Paris album art" } } } ], "media_type": "AUDIO" } } } ] }
Node.js
// Media response app.handle('media', (conv) => { conv.add('This is a media response'); conv.add(new Media({ mediaObjects: [ { name: 'Media name', description: 'Media description', url: 'https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3', image: { large: JAZZ_IN_PARIS_IMAGE, } } ], mediaType: 'AUDIO', optionalMediaControls: ['PAUSED', 'STOPPED'], startOffset: '2.12345s' })); });
JSON
{ "session": { "id": "session_id", "params": {}, "languageCode": "" }, "prompt": { "override": false, "content": { "media": { "mediaObjects": [ { "name": "Media name", "description": "Media description", "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3", "image": { "large": { "alt": "Jazz in Paris album art", "height": 0, "url": "https://storage.googleapis.com/automotive-media/album_art.jpg", "width": 0 } } } ], "mediaType": "AUDIO", "optionalMediaControls": [ "PAUSED", "STOPPED" ] } }, "firstSimple": { "speech": "This is a media response", "text": "This is a media response" } } }
Stato dei contenuti multimediali di ricezione
Durante o dopo la riproduzione di contenuti multimediali per un utente, l'Assistente Google può generare eventi relativi allo stato dei contenuti multimediali per indicare all'Azione l'avanzamento della riproduzione. Gestisci questi eventi di stato nel codice webhook per indirizzare in modo appropriato gli utenti quando mettono in pausa, interrompono o terminano la riproduzione di contenuti multimediali.
L'Assistente Google restituisce un evento di stato dal seguente elenco in base all'avanzamento della riproduzione dei contenuti multimediali e alle query degli utenti:
FINISHED
: l'utente ha completato la riproduzione di contenuti multimediali (o passa al contenuto multimediale successivo) e la transizione non corrisponde all'uscita di una conversazione. Questo stato è inoltre mappato all'intent di sistemaMEDIA_STATUS_FINISHED
.PAUSED
: l'utente ha messo in pausa la riproduzione di contenuti multimediali. Attiva la ricezione di questo evento di stato con la proprietàoptional_media_controls
. Questo stato è inoltre mappato all'intent di sistemaMEDIA_STATUS_PAUSED
.STOPPED
: l'utente ha interrotto o chiuso la riproduzione di contenuti multimediali. Attiva la ricezione di questo evento di stato con la proprietàoptional_media_controls
. Questo stato è inoltre mappato all'intent di sistemaMEDIA_STATUS_STOPPED
.FAILED
: riproduzione di contenuti multimediali non riuscita. Questo stato è inoltre mappato all'intent di sistemaMEDIA_STATUS_FAILED
.
Durante la riproduzione di contenuti multimediali, un utente potrebbe fornire una query che può essere interpretata come un evento sia di pausa che di interruzione di contenuti multimediali (ad esempio, "interruzione", "annullamento" o "uscita"). In questa
situazione, l'assistente fornisce l'intent del sistema actions.intent.CANCEL
per l'Azione, genera un evento dello stato dei contenuti multimediali con il valore di stato "INTERROMPITO" ed esce completamente dall'Azione.
Quando l'assistente genera un evento di stato dei contenuti multimediali con il valore di stato PAUSED
o STOPPED
, rispondi con una risposta multimediale che contiene solo un'accettazione (di tipo MEDIA_STATUS_ACK
).
Avanzamento contenuti multimediali
L'avanzamento attuale della riproduzione dei contenuti multimediali è disponibile nel campo context.media.progress
per le richieste di webhook. Puoi
utilizzare l'avanzamento dei contenuti multimediali come offset dell'ora di inizio per riprendere la riproduzione nel
punto in cui la riproduzione dei contenuti multimediali è terminata. Per applicare l'offset dell'ora di inizio a una risposta multimediale, utilizza la proprietà start_offset
.
Codice campione
Node.js
// Media status app.handle('media_status', (conv) => { const mediaStatus = conv.intent.params.MEDIA_STATUS.resolved; switch(mediaStatus) { case 'FINISHED': conv.add('Media has finished playing.'); break; case 'FAILED': conv.add('Media has failed.'); break; case 'PAUSED' || 'STOPPED': if (conv.request.context) { // Persist the media progress value const progress = conv.request.context.media.progress; } // Acknowledge pause/stop conv.add(new Media({ mediaType: 'MEDIA_STATUS_ACK' })); break; default: conv.add('Unknown media status received.'); } });
Restituire una playlist
Puoi aggiungere più di un file audio nella risposta per creare una playlist. Al termine della riproduzione della prima traccia, la traccia successiva viene riprodotta automaticamente e continua finché non viene riprodotta ogni traccia. Gli utenti possono anche premere il pulsante Avanti sullo schermo o dire "Avanti" o un'azione simile per passare alla traccia successiva.
Il pulsante Avanti è disattivato sull'ultima traccia della playlist. Tuttavia, se attivi la modalità loop, la playlist ricomincia dalla prima traccia. Per scoprire di più sulla modalità di loop, consulta Implementare la modalità di loop.
Per creare una playlist, includi più di un MediaObject
nell'array media_objects
. Il seguente snippet di codice mostra una richiesta che restituisce una playlist di tre tracce:
{ "candidates": [ { "content": { "media": { "media_objects": [ { "name": "1. Jazz in Paris", "description": "Song 1 of 3", "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3", "image": { "large": { "url": "https://storage.googleapis.com/automotive-media/album_art.jpg", "alt": "Album cover of an ocean view", "height": 1600, "width": 1056 } } }, { "name": "2. Jazz in Paris", "description": "Song 2 of 3", "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3", "image": { "large": { "url": "https://storage.googleapis.com/automotive-media/album_art.jpg", "alt": "Album cover of an ocean view", "height": 1600, "width": 1056 } } }, { "name": "3. Jazz in Paris", "description": "Song 3 of 3", "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3", "image": { "large": { "url": "https://storage.googleapis.com/automotive-media/album_art.jpg", "alt": "Album cover of an ocean view", "height": 1600, "width": 1056 } } } ], } } } ] }
Implementare la modalità di loop
La modalità loop ti consente di fornire una risposta audio che si ripete automaticamente. Potete usare questa modalità per ripetere una traccia o per riprodurre in loop una playlist. Se l'utente dice "Next" o qualcosa di simile per una singola traccia in loop, il brano ricomincia. Per le playlist in loop, un utente che dice "Avanti" avvia la traccia successiva della playlist.
Per implementare la modalità di loop, aggiungi il campo repeat_mode
al prompt e impostane il valore su ALL
. Questa aggiunta consente alla risposta multimediale di eseguire un loop all'inizio del primo oggetto multimediale quando viene raggiunta la fine dell'ultimo oggetto multimediale.
Il seguente snippet di codice mostra una richiesta che restituisce una traccia in loop:
{ "candidates": [ { "content": { "media": { "media_objects": [ { "name": "Jazz in Paris", "description": "Single song (repeated)", "url": "https://storage.googleapis.com/automotive-media/Jazz_In_Paris.mp3", "image": { "large": { "url": "https://storage.googleapis.com/automotive-media/album_art.jpg", "alt": "Album cover of an ocean view", "height": 1600, "width": 1056 } } } ], "repeat_mode": "ALL" } } } ] }