Como inserir metadados em um stream de vídeo

Os metadados cronometrados do Amazon Interactive Video Service (IVS) fornecem uma maneira de incorporar metadados em uma transmissão do Amazon IVS. Ele garante que todos os visualizadores recebam os metadados ao mesmo tempo no stream de vídeo, independentemente da latência ou da localização geográfica do stream.

O que são metadados cronometrados?

Metadados cronometrados são aqueles com carimbos de data/hora. Eles podem ser inseridos em um stream de forma programática, usando a API do IVS ou o SDK de Transmissão do IVS. Quando o Amazon IVS processa um stream, os metadados cronometrados são sincronizados com os quadros de áudio e vídeo. Durante a reprodução, todos os visualizadores do stream obtêm os metadados ao mesmo tempo em relação ao stream. O código de tempo serve como um ponto de sinalização, que pode ser usado para acionar uma ação com base nos dados, como o seguinte:

• Atualizando estatísticas do player para um stream de esportes.

• Enviando detalhes do produto para um stream de compras ao vivo.

• Enviando perguntas para um stream de perguntas ao vivo.

Os metadados cronometrados do Amazon IVS usam tags ID3 incorporadas nos segmentos de vídeo. Como resultado, eles estão disponíveis no vídeo gravado.

Configurar permissões do IAM

Pré-requisito: antes de prosseguir, você deve ter passado por Conceitos básicos do streaming de baixa latência do IVS (incluindo a criação de um usuário do IAM e a configuração de permissões).

Em seguida, você deve dar permissão ao usuário do IAM para usar metadados cronometrados. Siga estas etapas:

1. Faça login no Console de Gerenciamento da AWS e abra o console do IAM em https://console.aws.amazon.com/iam/.

2. No painel de navegação, selecioneUsers (Usuários) e, em seguida, escolha o usuário desejado (o nome de usuário especificado ao criar uma conta da AWS).

3. Na janela Summary (Resumo) do usuário, na guia Permissions (Permissões), escolha Add inline policy (Adicionar política em linha) (no lado direito).

4. Na guia JSON, cole neste blob:

   {
      "Version": "2012-10-17",
      "Statement": [
         {
           "Effect": "Allow",
           "Action": [
             "ivs:PutMetadata"
           ],
           "Resource": "arn:aws:ivs:*:*:channel/*"
         }
      ]
   }

5. Ainda na janela Create Policy (Criar política), selecione Review Policy (Revisar política). Forneça um nome para a política e, em seguida, selecione Create Policy (Criar política).

6. Você voltou à janela Summary (Resumo), mostrando o nome da nova política.

Inserir metadados cronometrados

Você pode inserir metadados cronometrados somente em um stream ativo em um canal especificado.

Usar a AWS CLI

Para testes, a maneira mais fácil de adicionar metadados cronometrados é com a AWS CLI. O uso da AWS CLI requer que você primeiro faça o download e configure a CLI em sua máquina. Você pode já ter feito isso quando você passou por Conceitos básicos do streaming de baixa latência do IVS; se não, faça isso agora. Para obter mais detalhes, consulte o Guia do usuário da Interface de Linhas de Comando da AWS.

Depois de ter a CLI:

1. Execute o comando put-metadata e informe o ARN do canal e seus metadados:

   aws ivs put-metadata --channel-arn <your-channel-arn> --metadata <your-metadata>

   Por exemplo:

   aws ivs put-metadata --channel-arn arn:aws:ivs:us-west-2:465369119046:channel/GbiYJna5hFoC --metadata '{"question": "What does IVS stand for?", "correctIndex": 0, "answers": ["interactive video service", "interesting video service", "ingenious video service"]}'

2. O Amazon IVS verifica se o stream está ativo. Se o stream não estiver ativo, você receberá um erro; caso contrário, a CLI retornará sem um erro e os metadados (blob de texto) serão inseridos no stream. Isso acontece o mais rápido possível. Não há garantia de quando isso ocorre; no entanto, todos os visualizadores veem os metadados no mesmo ponto do stream.

Usando a API do Amazon IVS

Para inserir programaticamente metadados cronometrados, use o endpoint da API PutMetadata.

Veja um exemplo de solicitação HTTP:

POST /PutMetadata HTTP/1.1
{
    "channelArn": "my_channel",
    "metadata": "{\"question\": \"What does IVS stand for?\", \"correctIndex\": 0, \"answers\": [\"interactive video service\", \"interesting video service\", \"ingenious video service\"]}"
}

Usar o SDK de Transmissão do IVS

Você pode inserir metadados sincronizados inband usando o SDK de Transmissão do IVS. Isso pode ser útil para sincronizar os metadados com o conteúdo de áudio e vídeo.

• Android: na classe BroadcastSession, use sendTimedMetadata.

• iOS: na classe IVSBroadcastSession, use sendTimedMetadata.

Consumir metadados cronometrados

Use o Player do Amazon IVS para consumir metadados cronometrados incorporados em um stream de vídeo. Consulte SDK do Amazon IVS Player e o resto da documentação do Player.

Veja abaixo trechos de exemplo que imprimem quaisquer metadados recebidos no console usando o SDK do Player do Amazon IVS. Um evento é acionado sempre que a reprodução atinge um segmento com metadados incorporados. (O evento é TEXT_METADATA_CUE para Web, onCue() para Android, e player(_:didOutputCue:) para iOS.) Você pode usar esse evento para iniciar a funcionalidade em sua aplicação cliente, como atualizar um widget interativo. Este evento é acionado para conteúdo ao vivo e gravado.

SDK do Amazon IVS Player para Web:

const player = IVSPlayer.create();
player.addEventListener(IVSPlayer.PlayerEventType.TEXT_METADATA_CUE,
    function (cue) {
  console.log('Timed metadata: ', cue.text);
});

SDK do Amazon IVS Player para Android:

@Override
public void onCue(@NonNull Cue cue) {
  if(cue instanceof TextMetadataCue) {
    Log.i("Timed Metadata: ", ((TextMetadataCue)cue).text);
  }
}

SDK do Amazon IVS Player para iOS:

func player(_ player: IVSPlayer, didOutputCue cue: IVSCue) {
  if let textMetadataCue = cue as? IVSTextMetadataCue {
    print("Timed Metadata: \(textMetadataCue.text)")
  }
}

Observação: metadados cronometrados são compatíveis com iOS Safari e iOS Chrome no Player 1.3.0 e posteriores.

Amostra de demonstração: aplicação de teste

Exemplos de código de uma aplicação de teste interativo estão disponíveis no GitHub. Usamos JSON por meio de metadados cronometrados para preencher uma interface do usuário do teste para exibir perguntas e respostas. As respostas são selecionáveis e revelam se a seleção está correta.

Plataforma SDK do Player do Amazon IVS	Repositório de amostras
Web	https://github.com/aws-samples/amazon-ivs-basic-web-sample Dentro deste repositório, consulte a demonstração de teste (e demonstração ao vivo).
Android	https://github.com/aws-samples/amazon-ivs-player-android-sample Dentro deste repositório, consulte a demonstração de teste.
iOS	https://github.com/aws-samples/amazon-ivs-player-ios-sample Dentro deste repositório, consulte a demonstração de teste.

Exibir metadados cronometrados

Se desejar, você pode visualizar os metadados cronometrados incorporados em sua transmissão ao vivo, no console:

1. Abra o console do Amazon IVS.

2. No canto superior esquerdo, selecione o ícone de hambúrguer para abrir o painel de navegação e, em seguida, selecione Live channels (Canais ao vivo).

3. Escolha o canal com o stream que você gostaria de assistir para direcioná-lo a uma página de detalhes desse canal.

   O stream ao vivo está sendo reproduzido na seção Live stream (Stream ao vivo) da página.

4. Na parte inferior da janela, selecioneTimed Metadados (Metadados cronometrados).

   Enquanto o player estiver em reprodução, conforme cada evento de metadados cronometrado é recebido, seu valor e tempo recebidos são exibidos.

Para obter mais informações

Consulte Como usar metadados cronometrados do Amazon Interactive Video Service, a primeira de uma série de blogs de duas partes sobre o uso de metadados cronometrados do Amazon IVS.