Respuestas multimedia

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.

Ejemplo de respuesta multimedia en una pantalla inteligente
Figura 1. Ejemplo de una respuesta multimedia en una pantalla inteligente

Comportamiento

Ejemplo de una respuesta de los medios de comunicación en un smartphone
Figura 2: Ejemplo de una respuesta multimedia en un smartphone

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 sistema MEDIA_STATUS_FINISHED.
  • PAUSED: El usuario pausó la reproducción de contenido multimedia. Habilita la recepción de este evento de estado con la propiedad optional_media_controls. Este estado también se asigna al intent del sistema MEDIA_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 propiedad optional_media_controls. Este estado también se asigna al intent del sistema MEDIA_STATUS_STOPPED.
  • FAILED: No se pudo reproducir el contenido multimedia. Este estado también se asigna al intent del sistema MEDIA_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"
        }
      }
    }
  ]
}