Respostas de mídia

As respostas de mídia permitem que suas ações toquem conteúdo de áudio com uma duração de reprodução maior que o limite de 240 segundos de SSML. As respostas de mídia funcionam em dispositivos somente de áudio e que podem mostrar conteúdo visual. Em uma tela, as respostas de mídia são acompanhadas por um componente visual com controles de mídia e (opcionalmente) uma imagem estática.

Ao definir uma resposta de mídia, use um candidato com os recursos de plataforma RICH_RESPONSE e LONG_FORM_AUDIO para que o Google Assistente retorne a resposta avançada somente em dispositivos com suporte. Só é possível usar uma resposta avançada por objeto content em uma solicitação.

O áudio para reprodução deve estar em um arquivo MP3 formatado corretamente. Os arquivos MP3 precisam ser hospedados em um servidor da Web e estar disponíveis publicamente por meio de um URL HTTPS. A transmissão ao vivo só é compatível com o formato MP3.

Exemplo de resposta de mídia no smart display
Figura 1. Exemplo de resposta de mídia no smart display.

Comportamento

Exemplo de resposta de mídia em um smartphone
Figura 2. Exemplo de resposta de mídia no smartphone

O componente principal de uma resposta de mídia é o card de faixa única. Ele permite que o usuário faça o seguinte:

  • Tocar novamente os últimos 10 segundos
  • Avançar 30 segundos
  • Conferir a duração total do conteúdo de mídia
  • Ver um indicador de progresso para a reprodução de mídia
  • Conferir o tempo de reprodução decorrido

As respostas de mídia oferecem suporte aos seguintes controles de áudio para interações por voz, todos processados pelo Google Assistente:

  • "Ok Google, abrir."
  • "Ok Google, pausar."
  • "Ok Google, parar."
  • "Ok Google, começar de novo."

Os usuários também podem controlar o volume dizendo frases como "Ok Google, aumente o volume" ou "Ok Google, ajuste o volume para 50%". As intents na sua ação terão precedência se processarem frases de treinamento semelhantes. Permita que o Google Assistente lide com essas solicitações do usuário, a menos que sua ação tenha um motivo específico para isso.

Comportamento em smartphones Android

Em smartphones Android, os controles de mídia também ficam disponíveis enquanto o smartphone está bloqueado. Os controles de mídia também aparecem na área de notificação, e os usuários podem conferir as respostas da mídia quando alguma das seguintes condições é atendida:

  • O Google Assistente está em primeiro plano, e a tela do smartphone está ativada.
  • O usuário sai do Google Assistente enquanto o áudio está tocando e retorna ao Google Assistente em até 10 minutos após a conclusão da reprodução. Ao retornar ao Google Assistente, o usuário vê o card de mídia e os ícones de sugestão.

Propriedades

As respostas de mídia têm as seguintes propriedades:

Propriedade Tipo Requisito Descrição
media_type MediaType Obrigatório Tipo de mídia da resposta fornecida. Retorne MEDIA_STATUS_ACK ao confirmar um status de mídia.
start_offset string Opcional Procure a posição para iniciar a primeira faixa de mídia. Forneça o valor em segundos, com segundos fracionários expressos em no máximo nove casas decimais, e termine com o sufixo "s". Por exemplo, 3 segundos e 1 nanossegundo são expressos como "3,000000001s".
optional_media_controls matriz de OptionalMediaControls Opcional Propriedade de ativação para receber callbacks quando um usuário mudar o status de reprodução de mídia, por exemplo, pausando ou interrompendo a reprodução.
media_objects matriz de MediaObject Obrigatório Representa os objetos de mídia a serem incluídos no comando. Ao confirmar um status de mídia com MEDIA_STATUS_ACK, não forneça objetos de mídia.
first_media_object_index número inteiro Opcional Índice baseado em 0 do primeiro MediaObject em media_objects a ser reproduzido. Se não for especificado, zero ou fora dos limites, a reprodução vai começar na primeira MediaObject.
repeat_mode RepeatMode Opcional Modo de repetição para a lista de objetos de mídia.

Exemplo de código

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"
    }
  }
}

Recebendo status de mídia

Durante ou após a reprodução de mídia para um usuário, o Google Assistente pode gerar eventos de status de mídia para informar sua ação sobre o progresso da reprodução. Processe esses eventos de status no código do webhook para rotear os usuários adequadamente quando eles pausarem, interromperem ou finalizarem a reprodução de mídia.

O Google Assistente retorna um evento de status da lista a seguir com base no progresso da reprodução de mídia e nas consultas do usuário:

  • FINISHED:o usuário concluiu a reprodução de mídia (ou pula para a próxima parte) e a transição não é para uma saída de conversa. Esse status também é mapeado para a intent do sistema MEDIA_STATUS_FINISHED.
  • PAUSED:o usuário pausou a reprodução de mídia. Ative o recebimento desse evento de status com a propriedade optional_media_controls. Esse status também é mapeado para a intent do sistema MEDIA_STATUS_PAUSED.
  • STOPPED:o usuário interrompeu ou saiu da reprodução de mídia. Ative o recebimento desse evento de status com a propriedade optional_media_controls. Esse status também é associado à intent do sistema MEDIA_STATUS_STOPPED.
  • FAILED:falha ao abrir a mídia. Esse status também é mapeado para a intent do sistema MEDIA_STATUS_FAILED.

Durante a reprodução de mídia, um usuário pode fornecer uma consulta que pode ser interpretada como um evento de pausa e interrupção de mídia (como "parar", "cancelar" ou "sair"). Nessa situação, o Google Assistente fornece a intent do sistema actions.intent.CANCEL para sua Ação, gera um evento de status de mídia com o valor de status "STOPPED" e saia completamente da ação.

Quando o Google Assistente gerar um evento de status de mídia com o valor de status PAUSED ou STOPPED, responda com uma resposta de mídia que contenha apenas uma confirmação (do tipo MEDIA_STATUS_ACK).

Progresso da mídia

O progresso atual da reprodução de mídia está disponível no campo context.media.progress para solicitações de webhook. É possível usar o progresso da mídia como um ajuste de horário de início para retomar a reprodução no ponto em que ela terminou. Para aplicar o ajuste de horário de início a uma resposta de mídia, use a propriedade start_offset.

Exemplo de código

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.');
  }
});

Retornar uma playlist

Você pode adicionar mais de um arquivo de áudio na sua resposta para criar uma playlist. Quando a primeira faixa termina de ser reproduzida, a próxima faixa é reproduzida automaticamente, e isso continua até que cada faixa seja reproduzida. Os usuários também podem pressionar o botão Next na tela ou dizer "Next" (avançar) ou algo semelhante para pular para a próxima faixa.

O botão Próxima fica desativado na última faixa da playlist. No entanto, se você ativar o modo de looping, a playlist começará novamente a partir da primeira faixa. Para saber mais sobre o modo de looping, consulte Implementar o modo de looping.

Para criar uma playlist, inclua mais de um MediaObject na matriz media_objects. O snippet de código a seguir mostra uma solicitação que retorna uma playlist de três faixas:

{
  "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
                }
              }
            }
          ],
        }
      }
    }
  ]
}

Implementar o modo de repetição

O modo de loop permite fornecer uma resposta de áudio que se repete automaticamente. Você pode usar esse modo para repetir uma única faixa ou repetir uma playlist. Se o usuário disser "Next" ou algo semelhante para uma única faixa em loop, a música vai começar novamente. Para playlists em loop, um usuário que diz "Next" inicia a próxima faixa da playlist.

Para implementar o modo de looping, adicione o campo repeat_mode ao comando e defina o valor dele como ALL. Essa adição permite que a resposta de mídia faça um loop para o início do primeiro objeto de mídia quando o fim do último objeto de mídia for alcançado.

O snippet de código a seguir mostra um comando que retorna uma faixa em repetição:

{
  "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"
        }
      }
    }
  ]
}