Aggiungere tag di generazione di immagini ai frammenti Percorso dell'oggetto Amazon S3 (immagine)Recupero dei metadati delle immagini Raccomandazioni sugli URI di Amazon S3 per la protezione dal throttling

Generazione automatica di immagini in tempo reale

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à ImageGenerationConfigurationstream 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?.

Per configurare la destinazione delle immagini generate

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

Segui la Guida per l'utente di Amazon S3 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.
Verifica di averlo AWS CLI installato e configurato. Per ulteriori informazioni, consulta la Guida per AWS Command Line Interface l'utente della versione 2.

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'UpdateImageGenerationConfigurationAPI.


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

Aggiorna la configurazione di generazione dell'immagine dello stream utilizzando l'UpdateImageGenerationConfigurationAPI 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
```
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.
Verifica le impostazioni di configurazione. Usa AWS CLI per chiamare l'DescribeImageGenerationConfigurationAPI 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.

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

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. VideoOnlyRealtimeStreamingSample 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:

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.
Inserisci il frame corrente nello stream.
Aggiungi il tag di generazione dell'immagine. Il putKinesisVideoEventMetadata metodo può essere chiamato in qualsiasi momento dopo la putFrame(keyFrame) chiamata e prima delputFrame(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).
Aggiungi altri metadati di frammento personalizzati, che Kinesis Video Streams trasformerà in metadati di oggetti Amazon S3.
Termina l'ultimo frammento di questa sessione di caricamento.

Utilizzo degli esempi per aggiungere tag di generazione di immagini

Puoi utilizzarlo kvs_gstreamer_audio_video_sample in C++ Producer SDK se desideri un'opzione della riga di comando per aggiungere tag di generazione di immagini. Abilita questa funzionalità aggiungendo l'-e bothargomento -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 e JNI README in. GitHub

Percorso dell'oggetto Amazon S3 (immagine)

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

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

Raccomandazioni sugli URI di Amazon S3 per la protezione dal throttling

Se scrivi migliaia di immagini su Amazon S3, c'è il rischio di limitazione. Per ulteriori informazioni, consulta S3 Prefix 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.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Estrai immagini dai flussi video

Risoluzione dei problemi