Las respuestas multimedia permiten que las acciones reproduzcan contenido de audio con una duración de reproducción mayor que el límite de 240 segundos de SSML. Las respuestas multimedia funcionan tanto en dispositivos de solo audio como en dispositivos que pueden mostrar contenido visual. En una pantalla, las respuestas multimedia van acompañadas de un componente visual con controles multimedia y (opcionalmente) una imagen fija.
Cuando definas una respuesta multimedia, usa un candidato con las capacidades de superficie RICH_RESPONSE
y LONG_FORM_AUDIO
para que Asistente de Google solo muestre la respuesta enriquecida en los dispositivos compatibles. Solo puedes usar una respuesta enriquecida por objeto content
en un mensaje.
El audio que se reproduzca debe estar en un archivo MP3 con el formato correcto. Los archivos MP3 deben estar alojados en un servidor web y estar disponibles de forma pública a través de una URL HTTPS. La transmisión en vivo solo es compatible con el formato MP3.
Comportamiento
El componente principal de una respuesta multimedia es la tarjeta de una sola pista. La tarjeta le permite al usuario hacer lo siguiente:
- Volver a reproducir los últimos 10 segundos
- Avanzar 30 segundos
- Cómo ver la longitud total del contenido multimedia
- Cómo ver un indicador de progreso de la reproducción de contenido multimedia
- Cómo ver el tiempo de reproducción transcurrido
Las respuestas multimedia admiten los siguientes controles de audio para las interacciones de voz, que Asistente de Google controla:
- "Hey Google, reproduce".
- “Hey Google, pausa”.
- “Hey Google, detente”.
- “Hey Google, vuelve a empezar”.
Para controlar el volumen, los usuarios también pueden decir frases como "Hey Google, sube el volumen" o "Hey Google, sube el volumen al 50%". Los intents de tu acción tienen prioridad si manejan frases de entrenamiento similares. Permite que Asistente controle estas solicitudes de los usuarios, a menos que tu Acción tenga un motivo específico para hacerlo.
Comportamiento en teléfonos Android
En los teléfonos Android, los controles multimedia también están disponibles mientras el teléfono está bloqueado. Los controles multimedia también aparecen en el área de notificaciones, y los usuarios pueden ver las respuestas multimedia cuando se cumple alguna de las siguientes condiciones:
- Asistente de Google está en primer plano y la pantalla del teléfono está encendida.
- El usuario sale de Asistente de Google mientras se reproduce el audio y regresa a Asistente 10 minutos después de que se completa la reproducción. Cuando regresa a Asistente de Google, el usuario ve la tarjeta multimedia y los chips de sugerencias.
Propiedades
Las respuestas multimedia tienen las siguientes propiedades:
Propiedad | Tipo | Requisito | Descripción |
---|---|---|---|
media_type |
MediaType |
Obligatorias | Es el tipo de medio de la respuesta proporcionada. Se muestra MEDIA_STATUS_ACK cuando se reconoce un estado de contenido multimedia. |
start_offset |
cadena | Opcional | Busca la posición para iniciar la primera pista multimedia. Proporciona el valor en segundos, con fracciones de segundos expresadas en no más de nueve decimales y termina con el sufijo “s”. Por ejemplo, 3 segundos y 1 nanosegundo se expresa como "3.000000001s". |
optional_media_controls |
array de OptionalMediaControls |
Opcional | Propiedad de aceptación para recibir devoluciones de llamada cuando un usuario cambia su estado de reproducción de contenido multimedia (por ejemplo, pausando o deteniendo la reproducción de contenido multimedia) |
media_objects |
array de MediaObject |
Obligatorias | Representa los objetos multimedia que se incluirán en la instrucción. Cuando reconozcas un estado multimedia con MEDIA_STATUS_ACK , no proporciones objetos multimedia. |
first_media_object_index |
integer | Opcional | Índice basado en 0 de la primera MediaObject en media_objects que se reproducirá. Si no se especifica, la reproducción comienza en el primer MediaObject o fuera de los límites.
|
repeat_mode |
RepeatMode |
Opcional | Modo de repetición para la lista de objetos multimedia |
Código de muestra
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" } } }
Recibiendo estado del contenido multimedia
Durante o después de la reproducción de contenido multimedia para un usuario, Asistente de Google puede generar eventos de estado del contenido multimedia para informar a tu Acción sobre el progreso de la reproducción. Controla estos eventos de estado en tu código de webhook para enrutar de forma adecuada a los usuarios cuando pausan, detienen o finalizan la reproducción de contenido multimedia.
Asistente de Google muestra un evento de estado de la siguiente lista según el progreso de la reproducción de contenido multimedia y las consultas de los usuarios:
FINISHED
: El usuario completó la reproducción de contenido multimedia (o omite el contenido siguiente) y la transición no es al final de una conversación. Este estado también se asigna al intent del sistemaMEDIA_STATUS_FINISHED
.PAUSED
: El usuario pausó la reproducción de contenido multimedia. Habilita la recepción de este evento de estado con la propiedadoptional_media_controls
. Este estado también se asigna al intent del sistemaMEDIA_STATUS_PAUSED
.STOPPED
: El usuario detuvo o salió de la reproducción de contenido multimedia. Habilita la recepción de este evento de estado con la propiedadoptional_media_controls
. Este estado también se asigna al intent del sistemaMEDIA_STATUS_STOPPED
.FAILED
: No se pudo reproducir el contenido multimedia. Este estado también se asigna al intent del sistemaMEDIA_STATUS_FAILED
.
Durante la reproducción de contenido multimedia, un usuario puede proporcionar una consulta que se pueda interpretar como un evento de pausa y de detención de contenido multimedia (como "detener", "cancelar" o "salir"). En ese caso, Asistente proporciona el intent del sistema actions.intent.CANCEL
a tu acción, genera un evento de estado de contenido multimedia con el valor de estado "STOPPED" y cierra la acción por completo.
Cuando Asistente genere un evento de estado de contenido multimedia con el valor de estado PAUSED
o STOPPED
, responde con una respuesta multimedia que contenga solo una confirmación (del tipo MEDIA_STATUS_ACK
).
Progreso de contenido multimedia
El progreso actual de la reproducción de contenido multimedia está disponible en el campo context.media.progress
para las solicitudes de webhook. Puedes usar el progreso del contenido multimedia como una compensación de hora de inicio para reanudar la reproducción desde el punto en que finalizó. Para aplicar la compensación de hora de inicio a una respuesta multimedia, usa la propiedad start_offset
.
Código de muestra
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.'); } });
Cómo devolver una playlist
Puedes agregar más de un archivo de audio en tu respuesta para crear una playlist. Cuando se termina de reproducir la primera pista, se reproduce la siguiente pista automáticamente, y este proceso continúa hasta que se reproduce cada pista. Los usuarios también pueden presionar el botón Siguiente en la pantalla, o decir "Siguiente" o algo similar para pasar a la siguiente pista.
El botón Siguiente está inhabilitado en la última pista de la playlist. Sin embargo, si habilitas el modo de repetición, la lista de reproducción comenzará de nuevo desde la primera pista. Para obtener más información sobre el modo de bucle, consulta Cómo implementar el modo de bucle.
Para crear una lista de reproducción, incluye más de un MediaObject
en la matriz media_objects
. En el siguiente fragmento de código, se muestra un mensaje que muestra una lista de reproducción de tres pistas:
{ "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 } } } ], } } } ] }
Implementa el modo de bucle
El modo de bucle te permite proporcionar una respuesta de audio que se repite automáticamente. Puedes usar este modo para repetir una sola pista o hacer un bucle a lo largo de una lista de reproducción. Si el usuario dice "Next" o algo similar para una sola pista en bucle, la canción comenzará de nuevo. Para las listas de reproducción repetitivas, un usuario que dice "Next" inicia la siguiente pista de la lista de reproducción.
Para implementar el modo de bucle, agrega el campo repeat_mode
a tu instrucción y establece su valor en ALL
. Esta adición permite que tu respuesta multimedia se repita indefinidamente al comienzo del primer objeto multimedia cuando se alcanza el final del último.
En el siguiente fragmento de código se muestra un mensaje que muestra una pista en bucle:
{ "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" } } } ] }