Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

# Extrahieren Sie Bilder aus Videostreams
<a name="images"></a>

Sie können Amazon Kinesis Video Streams APIs verwenden, SDKs um On-Demand-Bildextraktion und automatische Bildextraktion in Echtzeit aus Ihren Kinesis-Videostreams durchzuführen. Sie können diese Bilder für erweiterte Wiedergabeanwendungen wie Miniaturansichten oder erweitertes Scrubbing oder für die Verwendung in Workflows für maschinelles Lernen verwenden.

Kinesis Video Streams unterstützt das Extrahieren von Bildern aus Videostreams auf zwei Arten:
+ **[Bildgenerierung auf Abruf](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_reader_GetImages.html)** — Verwenden Sie die `GetImages` API, um ein einzelnes Bild oder mehrere Bilder aus in Kinesis Video Streams gespeicherten Videos zu extrahieren.
+ **[Automatisierte Bilderzeugung in Echtzeit](s3-real-time-image-create.md)**- Konfigurieren Sie Kinesis Video Streams so, dass automatisch Bilder aus Videodaten in Echtzeit extrahiert werden, basierend auf Fragment-Tags aus dem Video, während es aufgenommen wird, und die Bilder an einen S3-Bucket übertragen.

# Automatisierte Bilderzeugung in Echtzeit
<a name="s3-real-time-image-create"></a>

Amazon Kinesis Video Streams bietet die Möglichkeit, Bilder zu transkodieren und bereitzustellen. Kinesis Video Streams extrahiert automatisch Bilder aus Videodaten in Echtzeit und übermittelt die Bilder an Ihren angegebenen Amazon S3 S3-Bucket. Die Implementierung der automatisierten Bildextraktion in Echtzeit umfasst die folgenden Schritte:
+ Erstellen eines S3-Buckets für den Empfang der generierten Bilder.
+ Konfiguration der [ImageGenerationConfiguration](API_ImageGenerationConfiguration.md)Stream-Eigenschaft, die Kinesis Video Streams mitteilt, wie die Bilder erstellt und wohin sie gesendet werden sollen.
+ Bilderzeugungs-Tags hinzufügen — Kinesis Video Streams generiert nur Bilder mithilfe von Fragmenten, die über das Bilderzeugungs-Tag verfügen. Diese Tags werden beim Hochladen von Videos mit dem Kinesis Video Streams Producer SDK zusammen mit der `putKinesisVideoEventMetadata` Methode hinzugefügt.

Die folgenden Verfahren enthalten Anweisungen zum Ausführen der einzelnen Schritte.

Wenn Sie einen vom Kunden verwalteten Schlüssel verwenden, stellen Sie sicher, dass die Rolle, die die `PutMedia` Aufrufe ausführt (Uploader), über die folgenden Berechtigungen verfügt, die für das Verschlüsseln und Entschlüsseln von Daten und für den Zugriff auf den Amazon S3 S3-Bucket erforderlich sind.
+ `kms:Encrypt`
+ `kms:GenerateDataKey`
+ `kms:Decrypt`
+ `s3:PutObject`

Weitere Informationen finden Sie unter [Wie fange ich mit der serverseitigen Verschlüsselung an?](how-kms.md#getting-started-with-sse-akvs).

**Um das Ziel der generierten Bilder zu konfigurieren**

1. Erstellen Sie einen S3-Ziel-Bucket, in den die Bilder gesendet werden.

   Folgen Sie dem [Amazon S3 S3-Benutzerhandbuch](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html), um einen Amazon S3 S3-Bucket zu erstellen.

   Notieren Sie sich die URI des Buckets, die Sie im nächsten Schritt benötigen, wenn Sie die Konfiguration der Image-Generierung des Streams aktualisieren.

1. Stellen Sie sicher, dass Sie das AWS CLI installiert und konfiguriert haben. Weitere Informationen finden Sie im [AWS Command Line Interface Benutzerhandbuch für Version 2.](cli/latest/userguide/cli-chap-welcome.html)

1. Erstellen Sie eine neue Datei namens `update-image-generation-input.json` mit dem folgenden Inhalt als Eingabe. Aktualisieren Sie die Platzhalterwerte mit den Werten, die Sie verwenden möchten. Die unterstützten Höchst- und Mindestwerte finden Sie in der [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. Aktualisieren Sie die Konfiguration der Bildgenerierung des Streams mithilfe der [UpdateImageGenerationConfiguration](API_UpdateImageGenerationConfiguration.md) API und hängen Sie die JSON-Datei als Eingabe an, wie im folgenden Befehl gezeigt. Beachten Sie, dass der Dateipfad auf die Datei im aktuellen Verzeichnis verweist.

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

1. Bei Erfolg wird eine leere Antwort zurückgegeben und nichts wird in Ihrem Terminal gedruckt.
**Anmerkung**  
Nach der Aktualisierung der Konfiguration für die Bilderzeugung dauert es mindestens 1 Minute, bis der Workflow zur Bildgenerierung gestartet ist. Warten Sie mindestens 1 Minute, bevor Sie ein Video in Ihren Stream hochladen.

1. Überprüfen Sie die Konfigurationseinstellungen. Verwenden Sie die AWS CLI , um die [DescribeImageGenerationConfiguration](API_DescribeImageGenerationConfiguration.md) API für Ihren Stream aufzurufen.

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

Kinesis Video Streams generiert und liefert nur Bilder für Fragmente, die über das Bilderzeugungs-Tag verfügen. Alle zusätzlichen Fragment-Metadaten, die zusammen mit den Amazon S3 S3-Bildgenerierungs-Tags bereitgestellt werden, werden als Amazon S3 S3-Metadaten gespeichert.

**Anmerkung**  
Tags zur Bilderzeugung beziehen sich auf Tags mit Fragment-Metadaten und nicht auf Tags auf Stream-Ebene.

**Wichtig**  
Tags zur Bilderzeugung werden auf das Limit für Fragment-Metadaten-Tags angerechnet. Weitere Informationen finden Sie unter [Kontingente für Streaming-Metadaten](limits.md#limits-streaming-metadata).

Im Folgenden finden Sie ein Beispiel dafür, wie die Struktur der Fragment-Metadaten-Tags mithilfe des `mkvinfo` Dienstprogramms aussieht. Das Tag zur Bilderzeugung ist ein einfaches MKV-Tag mit einem Schlüssel von `AWS_KINESISVIDEO_IMAGE_GENERATION` und ohne Wert. Weitere Informationen finden Sie unter [Beispiel für Video-Tags](https://www.matroska.org/technical/tagging-video-example.html) in der Matroska-Dokumentation.

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

## Hinzufügen von Tags zur Bilderzeugung zu Fragmenten
<a name="s3-adding-image-tags"></a>

Kinesis Video Streams generiert und liefert Bilder nur für Fragmente, die über das Bilderzeugungs-Tag verfügen. Kinesis Video Streams erkennt diese speziellen MKV-Tags und leitet den Bildgenerierungs-Workflow auf der Grundlage der Bildverarbeitungskonfiguration des Streams ein.

Wenn Sie das Kinesis Video Streams Producer SDK zum Hochladen von Medien verwenden, verwenden Sie die `putKinesisVideoEventMetadata` Methode, um jedem Fragment, das Sie taggen möchten, das Tag zur Bilderzeugung hinzuzufügen. Ein neues Fragment beginnt beim `putFrame` Aufruf mit einem Frame, der das `keyframe` Flag enthält.

Wenn Sie ein aufgezeichnetes Video hochladen, wird es je nach Netzwerkgeschwindigkeit möglicherweise mit einer anderen Geschwindigkeit hochgeladen als die Geschwindigkeit, mit der es aufgenommen wurde. Wir empfehlen, den Producer-Zeitstempel zur Konfiguration der Bilderzeugung zu verwenden, wenn Sie Bilder in regelmäßigen Abständen auf der Grundlage der ursprünglichen Zeitstempel des Videos generieren möchten und nicht die Serverzeitstempel verwenden möchten, die auf der Rate basieren, mit der Amazon Kinesis Video Streams Ihr Video empfangen hat.

Ein vollständiges Beispiel für diesen Code finden Sie im Codebeispiel unter [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);
```

Die Elemente des Beispielcodes für die Einrichtung von Beispielrahmen werden wie folgt erklärt:

1. Jedes Fragment muss mit dem Ende von fragment (`eofr`) enden. Diese Anweisung besagt, dass jedes Mal, wenn ein neuer Keyframe empfangen wird, der den Beginn des nächsten Frames signalisiert, ein gesetzt wird, `eofr` bevor der nächste Frame zum Stream hinzugefügt wird.

1. Fügt den aktuellen Frame in den Stream ein.

1. Fügen Sie das Tag zur Bilderzeugung hinzu. Die `putKinesisVideoEventMetadata` Methode kann jederzeit nach dem `putFrame(keyFrame)` Aufruf und vor dem aufgerufen werden`putFrame(eofr)`. Sie darf pro Fragment höchstens einmal aufgerufen werden. Da jedes Fragment nur einen Keyframe haben wird, nennen wir es zu diesem Zeitpunkt der Einfachheit halber. Der `putKinesisVideoEventMetadata` Rückgabewert für wird auf einen Erfolgscode (0) überprüft.

1. Fügen Sie weitere benutzerdefinierte Fragment-Metadaten hinzu, die Kinesis Video Streams in Amazon S3 S3-Objektmetadaten umwandelt.

1. Beenden Sie das letzte Fragment in dieser Upload-Sitzung.

### Verwenden Sie die Beispiele, um Tags zur Bilderzeugung hinzuzufügen
<a name="use-samples-add-image-gen-tags"></a>

Sie können das `kvs_gstreamer_audio_video_sample` im C\$1\$1 Producer SDK enthaltene verwenden, wenn Sie eine Befehlszeilenoption zum Hinzufügen von Tags zur Bildgenerierung verwenden möchten. Aktivieren Sie diese Funktion, indem Sie entweder das `-e both` Argument `-e image` oder hinzufügen, wie im folgenden Beispiel gezeigt.

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

Weitere Informationen zu dieser Beispielanwendung finden Sie in den [Amazon Kinesis Video Streams CPP Producer, GStreamer Plugin und JNI](https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp/blob/master/README.md) README unter. GitHub

## Amazon S3 S3-Objektpfad (Bild)
<a name="s3-object-path"></a>

Der S3-Objektpfad beschreibt den Speicherort im konfigurierten S3-Bucket, an den das generierte Bild geliefert wird. Es verwendet das folgende Format:

```
ImagePrefix_AccountID_StreamName_ImageTimecode_RandomID.file-extension
```

Die Objektpfadelemente sind wie folgt definiert:
+ `ImagePrefix`- Wert von`AWS_KINESISVIDEO_IMAGE_PREFIX`, falls vorhanden.
+ `AccountID`- Die AWS-Konto ID, unter der der Stream erstellt wird.
+ `StreamName`- Name des Streams, aus dem das Bild generiert wird.
+ `ImageTimecode`- Epochen-Timecode (in Millisekunden) in dem Fragment, in dem das Bild generiert wird.
+ `RandomID`- Zufällige GUID.
+ `file-extension`- JPG oder PNG basierend auf dem angeforderten Bildformat.

In diesem Beispiel sieht der Objektpfad für die generierten Bilder wie folgt aus:

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

## Bildmetadaten werden abgerufen
<a name="s3-object-metadata"></a>

Sie können die S3-Konsole oder CLI verwenden, um die Metadaten für die generierten Bilder abzurufen.

Kinesis Video Streams legt die Fragmentnummer, den Produzenten- und Serverzeitstempel sowie die Inhaltstyp-Metadaten des generierten Bildes fest, die alle als Amazon S3 S3-Objektmetadaten formatiert sind. Wenn zusätzliche MKV-Tags vorhanden sind, werden diese Tags auch als Amazon S3 S3-Objektmetadaten hinzugefügt. Das folgende Beispiel zeigt, wie Sie den Amazon S3 S3-Head-Object-API-Befehl verwenden, um die Objektmetadaten abzurufen. Die Antwort enthält die von Kinesis Video Streams erstellten Metadaten.

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

Weitere Informationen zu S3-Objektmetadaten finden Sie unter[https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html).

## Amazon S3 S3-URI-Empfehlungen zum Schutz vor Drosselung
<a name="s3-uri-recommendations"></a>

Wenn Sie Tausende von Bildern auf Amazon S3 schreiben, besteht die Gefahr einer Drosselung. Weitere Informationen finden Sie unter Grenzwerte für [S3-Präfix-Put-Anfragen](https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance.html).

Ein Amazon S3 S3-Präfix beginnt mit einem PUT-Limit von 3.500 PUT-Anfragen pro Sekunde und wird im Laufe der Zeit für eindeutige Präfixe schrittweise erhöht. Vermeiden Sie die Verwendung von Datum und Uhrzeit als Amazon S3 S3-Präfixe. Zeitkodierte Daten wirken sich jeweils auf ein Präfix aus und ändern sich zudem regelmäßig, wodurch frühere Präfix-Skalierungen ungültig werden.

Um eine schnellere, konsistente Amazon S3-Skalierung zu ermöglichen, empfehlen wir, der Amazon S3-Ziel-URI ein zufälliges Präfix wie einen Hex-Code oder eine UUID hinzuzufügen. Hex-Code-Präfixe teilen Ihre Anfragen beispielsweise nach dem Zufallsprinzip auf 16 verschiedene Präfixe auf (ein Präfix für jedes eindeutige Hex-Zeichen), was 56.000 PUT-Anfragen pro Sekunde ermöglicht, nachdem Amazon S3 automatisch skaliert hat.

# Fehlerbehebung
<a name="s3-image-troubleshooting"></a>

## Bilder wurden nicht an den Amazon S3 S3-Bucket geliefert
<a name="s3-images-not-delivered"></a>

Um dieses Problem zu beheben, gibt es einige Dinge, auf die Sie achten sollten:

1. Fehlende Berechtigungen

1. Die Konfiguration der Image-Generierung ist falsch

1. Das Tag wurde dem Fragment nicht hinzugefügt

### Fehlende Berechtigungen
<a name="s3-missing-permissions"></a>

Wenn Sie einen vom Kunden verwalteten KMS-Schlüssel verwenden, stellen Sie sicher, dass die Rolle, die die `PutMedia` Aufrufe ausführt (Uploader), über die entsprechenden Verschlüsselungs- und Entschlüsselungsberechtigungen verfügt und Zugriff auf den Amazon S3 S3-Bucket hat, und zwar wie folgt:
+ `kms:Encrypt`
+ `kms:GenerateDataKey`
+ `kms:Decrypt`
+ `s3:PutObject`

Weitere Informationen finden Sie unter [Wie fange ich mit der serverseitigen Verschlüsselung an?](how-kms.md#getting-started-with-sse-akvs).

### Überprüfen Sie das Ziel
<a name="s3-verify-destination"></a>

Verwenden Sie die AWS CLI , um die DescribeImageGenerationConfiguration API für Ihren Stream aufzurufen.

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

Überprüfe das `DestinationConfig` in der Antwort und vergewissere dich, dass es korrekt aussieht.

### Stellen Sie sicher, dass das Tag zur Bilderzeugung dem Fragment hinzugefügt wurde
<a name="s3-verify-tag-added"></a>

1. Vergewissern Sie sich, dass der `putKinesisVideoEventMetadata` Anruf erfolgreich war.

   Die `putKinesisVideoEventMetadata` Methode gibt bei Erfolg den Statuscode 0 zurück. Wir empfehlen, die Rückgabewerte der Funktionen auf 0 zu überprüfen. Wenn ein Statuscode ungleich Null zurückgegeben wird, konvertieren Sie ihn in einen Hexadezimalwert und suchen Sie [Fehlercodereferenz](producer-sdk-errors.md) nach weiteren Informationen.

   Stellen Sie sicher, dass Sie die Fehlerprotokolle aktiviert haben, und überprüfen Sie die Protokolle auf andere Fehler in der Anwendung. Überprüfen Sie das Aufrufmuster für die Frame-Einreichung Ihrer Anwendung und vergleichen Sie es mit der empfohlenen Implementierung:[Hinzufügen von Tags zur Bilderzeugung zu Fragmenten](s3-real-time-image-create.md#s3-adding-image-tags).

1. Überprüfen Sie die lokal generierte MKV-Datei

   Vergewissern Sie sich, dass das Producer-SDK oder die Beispielanwendung die Tags korrekt angehängt hat.

   1. Legen Sie die `KVS_DEBUG_DUMP_DATA_FILE_DIR`-Umgebungsvariable fest. Wenn dieser Wert festgelegt ist, schreibt das Producer-SDK die Mediendateien, die es an Kinesis Video Streams gesendet hätte, an den angegebenen Speicherort.

      ```
      export KVS_DEBUG_DUMP_DATA_FILE_DIR=/path/to/output/directory
      ```
**Anmerkung**  
Das SDK erstellt kein neues Verzeichnis, wenn der Pfad nicht existiert. Erstellen Sie den Ordner, falls erforderlich.

   1. Führen Sie die Anwendung erneut aus. Sie sollten sehen, dass `.mkv` Dateien in das angegebene Ausgabeverzeichnis geschrieben werden.

   1. Überprüfen Sie den Inhalt, um sicherzustellen, dass das Tag vorhanden ist, indem Sie MKVTool Nix oder eine andere Software verwenden.

      1. Installieren Sie MKVTool Nix: `brew install mkvtoolnix`

      1. Führen Sie MKVTool Nix mit einer der `.mkv` Dateien im Ausgabeverzeichnis aus.

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

      1. Überprüfen Sie die MKVTool Nix-Ausgabe. Wenn die `KinesisVideoStream::PutFragmentMetadata` Producer-SDK-Methode korrekt aufgerufen wurde, sollte das folgende MKV-Tag angezeigt werden.

         ```
         |+ Tags
         | + Tag
         |  + Simple
         |   + Name: AWS_KINESISVIDEO_IMAGE_GENERATION
         ```
**Anmerkung**  
Die Tags gehören zum Cluster davor.

   1. Wenn das MKV-Tag nicht vorhanden ist, stellen Sie sicher, dass die `KinesisVideoStream::PutEventMetadata` Producer-SDK-Methode mit dem `STREAM_EVENT_TYPE_IMAGE_GENERATION` Argument aufgerufen wurde und dass sie einen Erfolgscode (0) zurückgegeben hat.