Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Generazione automatica di immagini in tempo reale
<a name="s3-real-time-image-create"></a>

Amazon Kinesis Video Streams offre la capacità di transcodificare e distribuire immagini. Kinesis Video Streams estrae automaticamente le immagini dai dati video in tempo reale e le invia al bucket Amazon S3 specificato. L'implementazione dell'estrazione automatica delle immagini in tempo reale prevede i seguenti passaggi:
+ Creazione di un bucket S3 per ricevere le immagini generate.
+ Configurazione della proprietà [ImageGenerationConfiguration](API_ImageGenerationConfiguration.md)stream che indica a Kinesis Video Streams come creare le immagini e dove inviarle.
+ Aggiungi tag di generazione delle immagini: Kinesis Video Streams genera immagini solo utilizzando frammenti che hanno il tag di generazione dell'immagine. Questi tag vengono aggiunti durante il caricamento di video utilizzando l'SDK Kinesis Video Streams Producer insieme al metodo. `putKinesisVideoEventMetadata`

Le seguenti procedure forniscono istruzioni per completare ciascuno di questi passaggi.

Se utilizzi una chiave gestita dal cliente, assicurati che il ruolo che esegue le `PutMedia` chiamate (uploader) disponga delle seguenti autorizzazioni necessarie per crittografare e decrittografare i dati e per accedere al bucket Amazon S3.
+ `kms:Encrypt`
+ `kms:GenerateDataKey`
+ `kms:Decrypt`
+ `s3:PutObject`

Per ulteriori informazioni, consulta [Come posso iniziare a usare la crittografia lato server?](how-kms.md#getting-started-with-sse-akvs).

**Per configurare la destinazione delle immagini generate**

1. Crea un bucket di destinazione S3 in cui verranno inviate le immagini.

   Segui la [Guida per l'utente di Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) per creare un bucket Amazon S3.

   Prendi nota dell'URI del bucket, che ti servirà nel passaggio successivo per aggiornare la configurazione di generazione dell'immagine dello stream.

1. Verifica di averlo AWS CLI installato e configurato. Per ulteriori informazioni, consulta la [Guida per AWS Command Line Interface l'utente della versione 2](cli/latest/userguide/cli-chap-welcome.html).

1. Crea un nuovo file chiamato `update-image-generation-input.json` con il seguente contenuto come input. Aggiorna i valori segnaposto con i valori che desideri utilizzare. Per i valori massimi e minimi supportati, consulta l'[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. Aggiorna la configurazione di generazione dell'immagine dello stream utilizzando l'[UpdateImageGenerationConfiguration](API_UpdateImageGenerationConfiguration.md)API e allegando il file JSON come input, come mostrato nel comando seguente. Nota che il percorso del file punta al file nella directory corrente.

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

1. In caso di successo, viene restituita una risposta vuota e non viene stampato nulla nel terminale.
**Nota**  
È necessario almeno 1 minuto per avviare il flusso di lavoro di generazione delle immagini dopo l'aggiornamento della configurazione di generazione delle immagini. Attendi almeno 1 minuto prima di caricare il video sul tuo stream.

1. Verifica le impostazioni di configurazione. Usa AWS CLI per chiamare l'[DescribeImageGenerationConfiguration](API_DescribeImageGenerationConfiguration.md)API per il tuo stream.

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

Kinesis Video Streams genererà e distribuirà immagini solo per frammenti che hanno il tag di generazione dell'immagine. Tutti i metadati di frammento aggiuntivi forniti insieme ai tag di generazione di immagini Amazon S3 verranno salvati come metadati Amazon S3.

**Nota**  
I tag di generazione delle immagini si riferiscono ai tag dei metadati dei frammenti e non ai tag a livello di flusso.

**Importante**  
I tag di generazione delle immagini vengono conteggiati ai fini del limite dei tag framment-metadati. Per ulteriori informazioni, consulta [Quote dei servizi di metadati di streaming](limits.md#limits-streaming-metadata).

Di seguito è riportato un esempio di come appare la struttura dei tag dei metadati dei frammenti utilizzando l'utilità. `mkvinfo` Il tag di generazione dell'immagine è un semplice tag MKV con una chiave `AWS_KINESISVIDEO_IMAGE_GENERATION` e nessun valore. Per ulteriori informazioni, consultate [Esempio di tag video](https://www.matroska.org/technical/tagging-video-example.html) nella documentazione di 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
```

## Aggiungere tag di generazione di immagini ai frammenti
<a name="s3-adding-image-tags"></a>

Kinesis Video Streams genera e fornisce immagini solo per i frammenti che hanno il tag di generazione dell'immagine. Kinesis Video Streams riconosce questi tag MKV speciali e avvia il flusso di lavoro di generazione delle immagini in base alla configurazione di elaborazione delle immagini dello stream.

Quando si utilizza l'SDK di Kinesis Video Streams Producer per caricare contenuti multimediali, si `putKinesisVideoEventMetadata` utilizza il metodo per aggiungere il tag di generazione dell'immagine a ciascun frammento che si desidera taggare. Un nuovo frammento inizia quando `putFrame` viene chiamato con un riquadro contenente la bandiera. `keyframe`

Se stai caricando un video preregistrato, è possibile che venga caricato a una velocità diversa da quella con cui è stato registrato, a seconda della velocità della rete. Ti consigliamo di utilizzare il timestamp Producer per configurare la generazione di immagini se desideri generare immagini a intervalli regolari in base ai timestamp originali del video e di non utilizzare i timestamp del server generati in base alla frequenza con cui Amazon Kinesis Video Streams ha ricevuto il tuo video.

Per visualizzare un esempio completo di questo codice, consulta l'esempio di codice in. [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) 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);
```

Gli elementi del codice di esempio per l'impostazione dei frame di esempio sono spiegati come segue:

1. Ogni frammento deve terminare con la fine di fragment ()`eofr`. Questa istruzione dice che ogni volta che viene ricevuto un nuovo fotogramma chiave, che segnala l'inizio del fotogramma successivo, inserisci un `eofr` prima di aggiungere il fotogramma successivo allo stream.

1. Inserisci il frame corrente nello stream.

1. Aggiungi il tag di generazione dell'immagine. Il `putKinesisVideoEventMetadata` metodo può essere chiamato in qualsiasi momento dopo la `putFrame(keyFrame)` chiamata e prima del`putFrame(eofr)`. Deve essere chiamato al massimo una volta per frammento. Poiché ogni frammento avrà un solo fotogramma chiave, in questo momento lo chiamiamo per semplicità. Il valore restituito da `putKinesisVideoEventMetadata` viene controllato per un codice di successo (0).

1. Aggiungi altri metadati di frammento personalizzati, che Kinesis Video Streams trasformerà in metadati di oggetti Amazon S3.

1. Termina l'ultimo frammento di questa sessione di caricamento.

### Utilizzo degli esempi per aggiungere tag di generazione di immagini
<a name="use-samples-add-image-gen-tags"></a>

Puoi utilizzarlo `kvs_gstreamer_audio_video_sample` in C\$1\$1 Producer SDK se desideri un'opzione della riga di comando per aggiungere tag di generazione di immagini. Abilita questa funzionalità aggiungendo l'`-e both`argomento `-e image` or, come illustrato nell'esempio seguente.

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

Per ulteriori informazioni su questa applicazione di esempio, consulta [Amazon Kinesis Video Streams CPP GStreamer Producer, Plugin](https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp/blob/master/README.md) e JNI README in. GitHub

## Percorso dell'oggetto Amazon S3 (immagine)
<a name="s3-object-path"></a>

Il percorso dell'oggetto S3 descrive la posizione sul bucket S3 configurato in cui verrà consegnata l'immagine generata. Utilizza il seguente formato:

```
ImagePrefix_AccountID_StreamName_ImageTimecode_RandomID.file-extension
```

Gli elementi del percorso dell'oggetto sono definiti come segue:
+ `ImagePrefix`- Valore di `AWS_KINESISVIDEO_IMAGE_PREFIX` se presente.
+ `AccountID`- L' Account AWS ID con cui viene creato lo stream.
+ `StreamName`- Nome dello stream da cui viene generata l'immagine.
+ `ImageTimecode`- Codice temporale epoch (in millisecondi) nel frammento in cui viene generata l'immagine.
+ `RandomID`- GUID casuale.
+ `file-extension`- JPG o PNG in base al formato di immagine richiesto.

In questo esempio, il percorso dell'oggetto per le immagini generate sarà il seguente:

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

## Recupero dei metadati delle immagini
<a name="s3-object-metadata"></a>

Puoi utilizzare la console S3 o la CLI per recuperare i metadati per le immagini generate.

Kinesis Video Streams imposta il numero del frammento, il timestamp del produttore e del server e i metadati del tipo di contenuto dell'immagine generata, tutti formattati come metadati degli oggetti Amazon S3. Se sono presenti tag MKV aggiuntivi, tali tag verranno aggiunti anche come metadati di oggetti Amazon S3. L'esempio seguente mostra come utilizzare il comando API head-object di Amazon S3 per recuperare i metadati dell'oggetto. La risposta include i metadati creati da 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"
    }
}
```

Per ulteriori informazioni sui metadati degli oggetti S3, consulta. [https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)

## Raccomandazioni sugli URI di Amazon S3 per la protezione dal throttling
<a name="s3-uri-recommendations"></a>

Se scrivi migliaia di immagini su Amazon S3, c'è il rischio di limitazione. Per ulteriori informazioni, consulta [S3 Prefix](https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance.html) Put Request Limits.

Un prefisso Amazon S3 inizia con un limite PUT di 3.500 richieste PUT al secondo e aumenterà gradualmente nel tempo per creare prefissi unici. Evita di utilizzare date e orari come prefissi Amazon S3. I dati con codifica temporale influiranno su un prefisso alla volta e verranno inoltre modificati regolarmente, invalidando le scalabilità dei prefissi precedenti.

Per consentire una scalabilità Amazon S3 più rapida e coerente, consigliamo di aggiungere un prefisso casuale, ad esempio un codice esadecimale o un UUID, all'URI di destinazione di Amazon S3. Ad esempio, i prefissi di codice esadecimale suddivideranno naturalmente le richieste in modo casuale tra 16 prefissi diversi (un prefisso per ogni carattere esadecimale univoco), il che consentirà 56.000 richieste PUT al secondo dopo la scalabilità automatica di Amazon S3.

# Risoluzione dei problemi
<a name="s3-image-troubleshooting"></a>

## Immagini non inviate al bucket Amazon S3
<a name="s3-images-not-delivered"></a>

Per risolvere questo problema, ci sono alcune cose a cui prestare attenzione:

1. Autorizzazioni mancanti

1. La configurazione di generazione dell'immagine non è corretta

1. Il tag non è stato aggiunto al frammento

### Autorizzazioni mancanti
<a name="s3-missing-permissions"></a>

Se utilizzi una chiave KMS gestita dal cliente, assicurati che il ruolo che esegue le `PutMedia` chiamate (uploader) disponga delle autorizzazioni di crittografia e decrittografia appropriate e abbia accesso al bucket Amazon S3, come segue:
+ `kms:Encrypt`
+ `kms:GenerateDataKey`
+ `kms:Decrypt`
+ `s3:PutObject`

Per ulteriori informazioni, consulta [Come posso iniziare a usare la crittografia lato server?](how-kms.md#getting-started-with-sse-akvs).

### Verifica la destinazione
<a name="s3-verify-destination"></a>

Usa AWS CLI per chiamare l' DescribeImageGenerationConfiguration API per il tuo stream.

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

Controlla `DestinationConfig` la risposta e conferma che sia corretta.

### Verifica che il tag di generazione dell'immagine sia stato aggiunto al frammento
<a name="s3-verify-tag-added"></a>

1. Verifica che la `putKinesisVideoEventMetadata` chiamata sia andata a buon fine.

   Il `putKinesisVideoEventMetadata` metodo restituisce un codice di stato 0 in caso di successo. Si consiglia di controllare i valori restituiti dalle funzioni per 0. Se viene restituito un codice di stato diverso da zero, convertilo in esadecimale e controlla [Riferimento al codice di errore](producer-sdk-errors.md) per ulteriori informazioni.

   Assicurati di aver attivato i log degli errori e controlla i log per eventuali altri errori nell'applicazione. Esamina e confronta lo schema di chiamata all'invio dei frame della tua applicazione con l'implementazione consigliata:. [Aggiungere tag di generazione di immagini ai frammenti](s3-real-time-image-create.md#s3-adding-image-tags)

1. Verifica il file MKV generato localmente

   Verifica che Producer SDK o Sample Application abbiano aggiunto i tag correttamente.

   1. Imposta la variabile di ambiente `KVS_DEBUG_DUMP_DATA_FILE_DIR`. Se questo valore è impostato, Producer SDK scrive i file multimediali che avrebbe inviato a Kinesis Video Streams nella posizione specificata.

      ```
      export KVS_DEBUG_DUMP_DATA_FILE_DIR=/path/to/output/directory
      ```
**Nota**  
L'SDK non creerà una nuova directory se il percorso non esiste. Crea la cartella se necessario.

   1. Esegui nuovamente l'applicazione. Dovresti vedere `.mkv` i file scritti nella directory di output specificata.

   1. Verifica il contenuto per assicurarti che il tag sia presente utilizzando MKVTool Nix o altro software.

      1. Installa MKVTool Nix: `brew install mkvtoolnix`

      1. Esegui MKVTool Nix con uno dei `.mkv` file nella directory di output.

         ```
         mkvinfo -v ./path/to/video/file
         ```

      1. Controlla l'output di MKVTool Nix. Se il metodo `KinesisVideoStream::PutFragmentMetadata` producer SDK è stato richiamato correttamente, dovresti vedere il seguente tag MKV.

         ```
         |+ Tags
         | + Tag
         |  + Simple
         |   + Name: AWS_KINESISVIDEO_IMAGE_GENERATION
         ```
**Nota**  
I tag appartengono al Cluster precedente.

   1. Se il tag MKV non è presente, assicuratevi che il metodo `KinesisVideoStream::PutEventMetadata` producer SDK sia stato chiamato con l'`STREAM_EVENT_TYPE_IMAGE_GENERATION`argomento e che abbia restituito un codice di successo (0).