Risposte multimediali

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
Figura 1. Esempio di risposta multimediale su smart display

Comportamento

Esempio di risposta multimediale su uno smartphone
Figura 2. Esempio di risposta multimediale su smartphone

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 sistema MEDIA_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 sistema MEDIA_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 sistema MEDIA_STATUS_STOPPED.
  • FAILED: riproduzione di contenuti multimediali non riuscita. Questo stato è inoltre mappato all'intent di sistema MEDIA_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"
        }
      }
    }
  ]
}