# 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](getting-started.md) (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/](https://console.aws.amazon.com/iam/). 1. No painel de navegação, selecione**Users** (Usuários) e, em seguida, escolha o usuário desejado (o nome de usuário especificado ao criar uma conta da AWS). 1. Na janela **Summary** (Resumo) do usuário, na guia **Permissions** (Permissões), escolha **Add inline policy** (Adicionar política em linha) (no lado direito). 1. Na guia **JSON**, cole neste blob: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ivs:PutMetadata" ], "Resource": "arn:aws:ivs:*:*:channel/*" } ] } ``` ------ 1. 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). 1. 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](getting-started.md); 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](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html). 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 --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"]}' ``` 1. 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 a operação da API [PutMetadata](https://docs.aws.amazon.com/ivs/latest/LowLatencyAPIReference/API_PutMetadata.html). 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 IVS Player](player.md) 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. ### Consumir dados de SEI Quando os estágios em tempo real do IVS são gravados com a gravação de participantes individuais ativada, as cargas úteis de Informações complementares aprimoradas (SEI) são retidas e publicadas como eventos `IVSPlayer.PlayerEventType.SEI`. Abaixo está um exemplo de trecho que imprime dados de SEI no console ao usar o SDK do IVS web player: ``` const player = IVSPlayer.create(); player.addEventListener(IVSPlayer.MetadataEventType.SEI, (event) => { const data = new TextDecoder().decode(event.data); const message = JSON.parse(data); console.log(message); }); ``` **Observação:** para obter mais informações sobre SEI, consulte [Informações complementares aprimoradas (SEI)](https://docs.aws.amazon.com/ivs/latest/RealTimeUserGuide/web-publish-subscribe.html#web-publish-subscribe-sei-attributes) no *Guia do SDK de Transmissão para Web do IVS* para streaming em tempo real. ### 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](https://github.com/aws-samples/amazon-ivs-basic-web-sample)Dentro deste repositório, consulte a [demonstração de teste](https://github.com/aws-samples/amazon-ivs-basic-web-sample/tree/master/simple-quiz) (e [demonstração ao vivo](https://codepen.io/amazon-ivs/pen/XWmjEKN)). | | Android | [https://github.com/aws-samples/amazon-ivs-player-android-sample](https://github.com/aws-samples/amazon-ivs-player-android-sample)Dentro deste repositório, consulte a [demonstração de teste](https://github.com/aws-samples/amazon-ivs-player-android-sample/tree/master/quizdemo). | | iOS | [https://github.com/aws-samples/amazon-ivs-player-ios-sample](https://github.com/aws-samples/amazon-ivs-player-ios-sample)Dentro deste repositório, consulte a [demonstração de teste](https://github.com/aws-samples/amazon-ivs-player-ios-sample/tree/master/QuizDemo). | ## 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](https://console.aws.amazon.com/ivs). 1. 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). 1. 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. 1. Na parte inferior da janela, selecione**Timed 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](https://aws.amazon.com/blogs/media/part-1-using-amazon-interactive-video-service-timed-metadata/), a primeira de uma série de blogs de duas partes sobre o uso de metadados cronometrados do Amazon IVS.