As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Geração automatizada de imagens em tempo real
<a name="s3-real-time-image-create"></a>

O Amazon Kinesis Video Streams oferece a capacidade de transcodificar e entregar imagens. O Kinesis Video Streams extrai automaticamente imagens de dados de vídeo em tempo real e entrega as imagens para seu bucket Amazon S3 especificado. A implementação da extração automatizada de imagens em tempo real envolve as seguintes etapas:
+ Criação de um bucket S3 para receber as imagens geradas.
+ Configurar a propriedade de [ImageGenerationConfiguration](API_ImageGenerationConfiguration.md)stream que informa ao Kinesis Video Streams como criar as imagens e para onde enviá-las.
+ Adicione tags de geração de imagem — O Kinesis Video Streams gera imagens somente usando fragmentos que tenham a tag de geração de imagem. Essas tags são adicionadas ao fazer o upload do vídeo usando o SDK do Kinesis Video Streams Producer junto com o método. `putKinesisVideoEventMetadata`

Os procedimentos a seguir fornecem instruções para concluir cada uma dessas etapas.

Se você estiver usando uma chave gerenciada pelo cliente, certifique-se de que a função que executa as `PutMedia` chamadas (carregador) tenha as seguintes permissões que são necessárias para criptografar e descriptografar dados e para acessar o bucket do Amazon S3.
+ `kms:Encrypt`
+ `kms:GenerateDataKey`
+ `kms:Decrypt`
+ `s3:PutObject`

Para obter mais informações, consulte [Como começo a usar a criptografia no lado do servidor?](how-kms.md#getting-started-with-sse-akvs).

**Para configurar o destino das imagens geradas**

1. Crie um bucket de destino S3 para o qual as imagens serão enviadas.

   Siga o [Guia do usuário do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) para criar um bucket do Amazon S3.

   Observe o URI do bucket, que você precisará na próxima etapa ao atualizar a configuração de geração de imagem do stream.

1. Verifique se você tem o AWS CLI instalado e configurado. Para obter mais informações, consulte o [Guia AWS Command Line Interface do usuário da versão 2](cli/latest/userguide/cli-chap-welcome.html).

1. Crie um novo arquivo chamado `update-image-generation-input.json` com o seguinte conteúdo como entrada. Atualize os valores do espaço reservado com os valores que você deseja usar. Para ver os valores máximos e mínimos suportados, consulte a [UpdateImageGenerationConfiguration](API_UpdateImageGenerationConfiguration.md)API.

   ```
   {
      "StreamName": "{{demo-stream}}",
      "ImageGenerationConfiguration": {
         "Status": "ENABLED",
         "DestinationConfig": {
            "DestinationRegion": "{{us-east-1}}",
            "Uri": "s3://{{my-bucket-name}}"
         },
         "SamplingInterval": 200,
         "ImageSelectorType": "PRODUCER_TIMESTAMP",
         "Format": "JPEG",
         "FormatConfig": {
            "JPEGQuality": "80"
         },
         "WidthPixels": 320,
         "HeightPixels": 240
      }
   }
   ```

1. Atualize a configuração de geração de imagem do stream usando a [UpdateImageGenerationConfiguration](API_UpdateImageGenerationConfiguration.md) API e anexando o arquivo JSON como entrada, conforme mostrado no comando a seguir. Observe que o caminho do arquivo aponta para o arquivo no diretório atual.

   ```
   aws kinesisvideo update-image-generation-configuration \
     --cli-input-json file://./update-image-generation-input.json
   ```

1. Em caso de sucesso, uma resposta vazia é retornada e nada é impresso em seu terminal.
**nota**  
É necessário pelo menos 1 minuto para iniciar o fluxo de trabalho de geração de imagem depois de atualizar a configuração de geração de imagem. Espere pelo menos 1 minuto antes de enviar o vídeo para sua transmissão.

1. Verifique as configurações. Use o AWS CLI para chamar a [DescribeImageGenerationConfiguration](API_DescribeImageGenerationConfiguration.md) API do seu stream.

   ```
   aws kinesisvideo describe-image-generation-configuration \
     --stream-name "{{demo-stream}}"
   ```

O Kinesis Video Streams só gerará e entregará imagens para fragmentos que tenham a tag de geração de imagem. Todos os metadados de fragmentos adicionais fornecidos junto com as tags de geração de imagem do Amazon S3 serão salvos como metadados do Amazon S3.

**nota**  
As tags de geração de imagem se referem a tags de metadados de fragmento e não a tags de nível de stream.

**Importante**  
As tags de geração de imagem contam para o limite de tags de metadados de fragmento. Para obter mais informações, consulte [Cotas do serviço de metadados de streaming](limits.md#limits-streaming-metadata).

Veja a seguir um exemplo de como é a estrutura das tags de metadados do fragmento usando o `mkvinfo` utilitário. A tag de geração de imagem é uma tag simples MKV com uma chave de `AWS_KINESISVIDEO_IMAGE_GENERATION` e nenhum valor. Para obter mais informações, consulte [Exemplo de tags de vídeo](https://www.matroska.org/technical/tagging-video-example.html) na documentação do Matroska.

```
|+ Tags
| + Tag
|  // MANDATORY: Predefined MKV tag to trigger image generation for the fragment
|  + Simple
|   + Name: AWS_KINESISVIDEO_IMAGE_GENERATION

|  // OPTIONAL: S3 prefix which will be set as prefix for generated image.
|  + Simple
|   + Name: AWS_KINESISVIDEO_IMAGE_PREFIX 
|   + String: {{image_prefix_in_s3}} // 256 bytes max

| // OPTIONAL: Key value pairs that will be persisted as S3 Image object metadata.
|  + Simple
|   + Name: {{CUSTOM_KEY_1}} // Max 128 bytes
|   + String: {{CUSTOM_VALUE_1}} // Max 256 bytes
|  + Simple
|   + Name: {{CUSTOM_KEY_2}} // Max 128 bytes
|   + String: {{CUSTOM_VALUE_2}} // Max 256 bytes
```

## Adicionar tags de geração de imagens a fragmentos
<a name="s3-adding-image-tags"></a>

O Kinesis Video Streams gera e entrega imagens somente para fragmentos que têm a tag de geração de imagem. O Kinesis Video Streams reconhece essas tags MKV especiais e inicia o fluxo de trabalho de geração de imagens com base na configuração de processamento de imagem do stream.

Ao usar o SDK do Kinesis Video Streams Producer para fazer upload de mídia, você `putKinesisVideoEventMetadata` usa o método para adicionar a tag de geração de imagem a cada fragmento que você deseja marcar. Um novo fragmento começa quando `putFrame` é chamado com um quadro contendo o `keyframe` sinalizador.

Se você estiver enviando um vídeo pré-gravado, ele poderá ser carregado em uma taxa diferente da taxa em que foi gravado, dependendo da velocidade da sua rede. Recomendamos que você use o timestamp Producer para configurar a geração de imagens se quiser gerar imagens em intervalos regulares com base nos timestamps originais do vídeo, e não usar os timestamps do servidor gerados com base na taxa na qual o Amazon Kinesis Video Streams recebeu seu vídeo.

Para ver um exemplo completo desse código, consulte o exemplo [https://github.com/awslabs/amazon-kinesis-video-streams-producer-c/blob/master/samples/KvsVideoOnlyRealtimeStreamingSample.c](https://github.com/awslabs/amazon-kinesis-video-streams-producer-c/blob/master/samples/KvsVideoOnlyRealtimeStreamingSample.c)de código em GitHub.

```
// Setup sample frame
MEMSET(frameBuffer, 0x00, frameSize);
frame.frameData = frameBuffer;
frame.version = FRAME_CURRENT_VERSION;
frame.trackId = DEFAULT_VIDEO_TRACK_ID;
frame.duration = HUNDREDS_OF_NANOS_IN_A_SECOND / DEFAULT_FPS_VALUE;
frame.decodingTs = defaultGetTime(); // current time
frame.presentationTs = frame.decodingTs;

Frame eofr = EOFR_FRAME_INITIALIZER;

while(defaultGetTime() > streamStopTime) {
    frame.index = frameIndex;
    frame.flags = fileIndex % DEFAULT_KEY_FRAME_INTERVAL == 0 ? FRAME_FLAG_KEY_FRAME : FRAME_FLAG_NONE;
    frame.size = SIZEOF(frameBuffer);

    CHK_STATUS(readFrameData(&frame, frameFilePath));

    // 1. End the previous fragment
    if (frame.flags == FRAME_FLAG_KEY_FRAME && !firstFrame) {
        putKinesisVideoFrame(streamHandle, &eofr);
    }

    // 2. putFrame call
    CHK_STATUS(putKinesisVideoFrame(streamHandle, &frame));

    if (frame.flags == FRAME_FLAG_KEY_FRAME) {
        // 3. Adding the image generation tag
        CHK_STATUS(putKinesisVideoEventMetadata(streamHandle, STREAM_EVENT_TYPE_IMAGE_GENERATION, NULL);)

        // 4. Adding fragment metadata
        for (n = 1; n <= 5; n++) {
            SNPRINTF(metadataKey, METADATA_MAX_KEY_LENGTH, "SAMPLE_KEY_%d", n);
            SNPRINTF(metadataValue, METADATA_MAX_VALUE_LENGTH, "SAMPLE_VALUE_%d", frame.index + n);
            CHK_STATUS(putKinesisVideoFragmentMetadata(streamHandle, metadataKey, metadataValue, FALSE));
        }
    }
    defaultThreadSleep(frame.duration);

    frame.decodingTs += frame.duration;
    frame.presentationTs = frame.decodingTs;
    frameIndex++;
    fileIndex++;
    fileIndex = fileIndex % NUMBER_OF_FRAME_FILES;
    firstFrame = TRUE;
}

// 5. End the final fragment
putKinesisVideoFrame(streamHandle, &eofr);
```

Os elementos do código de exemplo para configurar quadros de amostra são explicados a seguir:

1. Cada fragmento precisa terminar com o final de fragment ()`eofr`. Essa declaração diz que sempre que um novo quadro-chave for recebido, o que sinaliza o início do próximo quadro, coloque um `eofr` antes de adicionar o próximo quadro ao fluxo.

1. Coloque o quadro atual no fluxo.

1. Adicione a tag de geração de imagem. O `putKinesisVideoEventMetadata` método pode ser chamado a qualquer momento após a `putFrame(keyFrame)` chamada e antes do`putFrame(eofr)`. Ele só deve ser chamado no máximo uma vez por fragmento. Como cada fragmento terá apenas um quadro-chave, chamamos isso neste momento para simplificar. O valor de retorno de `putKinesisVideoEventMetadata` é verificado quanto a um código de sucesso (0).

1. Adicione outros metadados de fragmentos personalizados, que o Kinesis Video Streams transformará em metadados de objetos do Amazon S3.

1. Finalize o fragmento final nesta sessão de upload.

### Usando as amostras para adicionar tags de geração de imagens
<a name="use-samples-add-image-gen-tags"></a>

Você pode usar o `kvs_gstreamer_audio_video_sample` no C\+\+ Producer SDK se quiser uma opção de linha de comando para adicionar tags de geração de imagem. Ative esse recurso adicionando o `-e both` argumento `-e image` ou, conforme mostrado no exemplo a seguir.

```
./kvs_gstreamer_audio_video_sample {{stream-name}} \
  -f {{video-to-upload.mp4}} \
  -e both
```

Para obter mais informações sobre esse aplicativo de amostra, consulte o [Amazon Kinesis Video Streams CPP GStreamer Producer, o plug-in e o JNI README](https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp/blob/master/README.md) em. GitHub

## Caminho do objeto Amazon S3 (imagem)
<a name="s3-object-path"></a>

O caminho do objeto do S3 descreve a localização no bucket configurado do S3 onde a imagem gerada será entregue. Ele usa o seguinte formato:

```
{{ImagePrefix}}_{{AccountID}}_{{StreamName}}_{{ImageTimecode}}_{{RandomID}}.{{file-extension}}
```

Os elementos do caminho do objeto são definidos da seguinte forma:
+ `ImagePrefix`- Valor de, `AWS_KINESISVIDEO_IMAGE_PREFIX` se presente.
+ `AccountID`- O Conta da AWS ID sob o qual o fluxo é criado.
+ `StreamName`- Nome do fluxo a partir do qual a imagem é gerada.
+ `ImageTimecode`- Timecode de época (em milissegundos) no fragmento no qual a imagem é gerada.
+ `RandomID`- GUID aleatório.
+ `file-extension`- JPG ou PNG com base no formato de imagem solicitado.

Neste exemplo, o caminho do objeto para as imagens geradas terá a seguinte aparência:

```
111122223333_demo-stream_16907729324_f20f9add-75e7-4399-a30f-fc7aefb1bab7.jpg
```

## Recuperação de metadados de imagem
<a name="s3-object-metadata"></a>

Você pode usar o console do S3 ou a CLI para recuperar os metadados das imagens geradas.

O Kinesis Video Streams define o número do fragmento, a data e hora do produtor e do servidor e os metadados do tipo de conteúdo da imagem gerada, todos formatados como metadados de objetos do Amazon S3. Se alguma tag MKV adicional estiver presente, essas tags também serão adicionadas como metadados de objetos do Amazon S3. O exemplo a seguir mostra como usar o comando da API head-object do Amazon S3 para recuperar os metadados do objeto. A resposta inclui os metadados criados pelo Kinesis Video Streams.

```
aws s3api head-object --bucket {{my-bucket-name}} --key {{111122223333}}_{{demo-stream}}_1690707290324_f20f9add-7e57-4399-a30f-fc7aefb1bab7.jpg
{
    "AcceptRanges": "bytes",
    "LastModified": "2023-07-30T08:54:51+00:00",
    "ContentLength": 22693,
    "ETag": "\"63e03cb6d57f77e2db984c1d344b1083\"",
    "ContentType": "image/jpeg",
    "ServerSideEncryption": "AES256",
    "Metadata": {
        "aws_kinesisvideo_producer_timestamp": "1690707290324",
        "aws_kinesisvideo_server_timestamp": "1690707289209",
        "aws_kinesisvideo_fragment_number": "91343852333182036507421233921329142742245756394"
    }
}
```

Para obter mais informações sobre metadados de objetos do S3, consulte. [https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)

## Recomendações de URI do Amazon S3 para proteção contra limitação
<a name="s3-uri-recommendations"></a>

Se você gravar milhares de imagens no Amazon S3, há o risco de limitação. Para obter mais informações, consulte [S3 Prefix Put Request Limits](https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance.html).

Um prefixo do Amazon S3 começa com um limite PUT de 3.500 solicitações PUT por segundo e aumentará gradualmente com o tempo para prefixos exclusivos. Evite usar datas e horários como prefixos do Amazon S3. Os dados codificados por tempo afetarão um prefixo por vez e também mudarão regularmente, invalidando os aumentos de prefixo anteriores.

Para permitir uma escalabilidade mais rápida e consistente do Amazon S3, recomendamos adicionar um prefixo aleatório, como um código hexadecimal ou UUID ao URI de destino do Amazon S3. Por exemplo, prefixos de código hexadecimal naturalmente dividirão suas solicitações aleatoriamente entre 16 prefixos diferentes (um prefixo para cada caractere hexadecimal exclusivo), o que permitirá 56.000 solicitações PUT por segundo após a escalabilidade automática do Amazon S3.