Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Pembuatan gambar real-time otomatis
<a name="s3-real-time-image-create"></a>

Amazon Kinesis Video Streams menawarkan kemampuan untuk mentranskode dan mengirimkan gambar. Kinesis Video Streams secara otomatis mengekstrak gambar dari data video secara real-time, dan mengirimkan gambar ke bucket Amazon S3 yang Anda tentukan. Menerapkan ekstraksi gambar otomatis secara real-time melibatkan langkah-langkah berikut:
+ Membuat bucket S3 untuk menerima gambar yang dihasilkan.
+ Mengkonfigurasi properti [ImageGenerationConfiguration](https://docs.aws.amazon.com/kinesisvideostreams/latest/APIReference/API_ImageGenerationConfiguration.html)stream yang memberi tahu Kinesis Video Streams cara membuat gambar dan ke mana mengirimnya.
+ Tambahkan tag pembuatan gambar — Kinesis Video Streams hanya menghasilkan gambar menggunakan fragmen yang memiliki tag pembuatan gambar. Tag ini ditambahkan saat mengunggah video menggunakan Kinesis Video Streams Producer SDK beserta metodenya. `putKinesisVideoEventMetadata`

Prosedur berikut memberikan instruksi untuk menyelesaikan setiap langkah ini.

Jika Anda menggunakan kunci yang dikelola pelanggan, pastikan peran yang melakukan `PutMedia` panggilan (pengunggah) memiliki izin berikut yang diperlukan untuk mengenkripsi dan mendekripsi data, serta untuk akses ke bucket Amazon S3.
+ `kms:Encrypt`
+ `kms:GenerateDataKey`
+ `kms:Decrypt`
+ `s3:PutObject`

Untuk informasi selengkapnya, lihat [Bagaimana cara memulai dengan enkripsi sisi server?](how-kms.md#getting-started-with-sse-akvs).

**Untuk mengonfigurasi tujuan gambar yang dihasilkan**

1. Buat bucket tujuan S3 tempat gambar akan dikirim.

   Ikuti [Panduan Pengguna Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) untuk membuat bucket Amazon S3.

   Perhatikan URI bucket, yang akan Anda perlukan di langkah berikutnya saat memperbarui konfigurasi pembuatan gambar stream.

1. Verifikasi bahwa Anda telah AWS CLI menginstal dan mengkonfigurasi. Untuk informasi selengkapnya, lihat [Panduan AWS Command Line Interface Pengguna untuk Versi 2](cli/latest/userguide/cli-chap-welcome.html).

1. Buat file baru yang disebut `update-image-generation-input.json` dengan konten berikut sebagai input. Perbarui nilai placeholder dengan nilai yang ingin Anda gunakan. Untuk nilai maksimum dan minimum yang didukung, lihat [UpdateImageGenerationConfiguration](https://docs.aws.amazon.com/kinesisvideostreams/latest/APIReference/API_UpdateImageGenerationConfiguration.html)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. Perbarui konfigurasi pembuatan gambar stream menggunakan [UpdateImageGenerationConfiguration](https://docs.aws.amazon.com/kinesisvideostreams/latest/APIReference/API_UpdateImageGenerationConfiguration.html)API dan melampirkan file JSON sebagai input, seperti yang ditunjukkan pada perintah berikut. Perhatikan bahwa jalur file menunjuk ke file di direktori saat ini.

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

1. Setelah berhasil, respons kosong dikembalikan dan tidak ada yang dicetak di terminal Anda.
**catatan**  
Dibutuhkan setidaknya 1 menit untuk memulai alur kerja pembuatan gambar setelah memperbarui konfigurasi pembuatan gambar. Tunggu setidaknya 1 menit sebelum mengunggah video ke streaming Anda.

1. Verifikasi pengaturan konfigurasi. Gunakan AWS CLI untuk memanggil [DescribeImageGenerationConfiguration](https://docs.aws.amazon.com/kinesisvideostreams/latest/APIReference/API_DescribeImageGenerationConfiguration.html)API untuk streaming Anda.

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

Kinesis Video Streams hanya akan menghasilkan dan mengirimkan gambar untuk fragmen yang memiliki tag pembuatan gambar. Setiap metadata fragmen tambahan yang disediakan bersama dengan tag pembuatan gambar Amazon S3 akan disimpan sebagai metadata Amazon S3.

**catatan**  
Tag pembuatan gambar mengacu pada tag fragmen-metadata dan bukan tag tingkat aliran.

**penting**  
Tag pembuatan gambar dihitung terhadap batas tag fragmen-metadata. Untuk informasi selengkapnya, lihat [Kuota layanan metadata streaming](limits.md#limits-streaming-metadata).

Berikut ini adalah contoh dari apa struktur tag metadata fragmen terlihat seperti menggunakan utilitas. `mkvinfo` Tag pembuatan gambar adalah tag sederhana MKV dengan kunci `AWS_KINESISVIDEO_IMAGE_GENERATION` dan tanpa nilai. Untuk informasi selengkapnya, lihat [Contoh Tag Video](https://www.matroska.org/technical/tagging-video-example.html) dalam dokumentasi 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
```

## Menambahkan tag pembuatan gambar ke fragmen
<a name="s3-adding-image-tags"></a>

Kinesis Video Streams menghasilkan dan mengirimkan gambar hanya untuk fragmen yang memiliki tag pembuatan gambar. Kinesis Video Streams mengenali tag MKV khusus ini dan memulai alur kerja pembuatan gambar berdasarkan konfigurasi pemrosesan gambar aliran.

Saat menggunakan Kinesis Video Streams Producer SDK untuk mengunggah media, Anda `putKinesisVideoEventMetadata` menggunakan metode untuk menambahkan tag pembuatan gambar ke setiap fragmen yang ingin Anda tag. Sebuah fragmen baru dimulai ketika `putFrame` dipanggil dengan bingkai yang berisi `keyframe` bendera.

Jika Anda mengunggah video yang direkam sebelumnya, video tersebut mungkin diunggah dengan kecepatan yang berbeda dari kecepatan perekaman, tergantung pada kecepatan jaringan Anda. Kami menyarankan Anda menggunakan stempel waktu Produser untuk mengonfigurasi pembuatan gambar jika Anda ingin menghasilkan gambar secara berkala berdasarkan stempel waktu asli video, dan tidak menggunakan stempel waktu server yang dihasilkan berdasarkan kecepatan di mana Amazon Kinesis Video Streams menerima video Anda.

Untuk melihat contoh lengkap kode ini, lihat contoh [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)kode di 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);
```

Elemen-elemen kode contoh untuk menyiapkan bingkai sampel dijelaskan sebagai berikut:

1. Setiap fragmen harus diakhiri dengan akhir fragmen ()`eofr`. Pernyataan ini mengatakan setiap kali keyframe baru diterima, yang menandakan awal frame berikutnya, letakkan `eofr` sebelum menambahkan frame berikutnya ke dalam aliran.

1. Masukkan bingkai saat ini ke dalam aliran.

1. Tambahkan tag pembuatan gambar. `putKinesisVideoEventMetadata`Metode ini dapat dipanggil kapan saja setelah `putFrame(keyFrame)` panggilan dan sebelum panggilan`putFrame(eofr)`. Itu hanya harus dipanggil paling banyak sekali per fragmen. Karena setiap fragmen hanya akan memiliki satu keyframe, kami menyebutnya saat ini untuk kesederhanaan. Nilai pengembalian untuk `putKinesisVideoEventMetadata` diperiksa untuk kode sukses (0).

1. Tambahkan metadata fragmen khusus lainnya, yang akan diubah oleh Kinesis Video Streams menjadi metadata objek Amazon S3.

1. Akhiri fragmen terakhir dalam sesi pengunggahan ini.

### Menggunakan sampel untuk menambahkan tag pembuatan gambar
<a name="use-samples-add-image-gen-tags"></a>

Anda dapat menggunakan C\+\+ Producer SDK jika Anda menginginkan opsi baris perintah untuk menambahkan tag pembuatan gambar. `kvs_gstreamer_audio_video_sample` Aktifkan fitur ini dengan menambahkan `-e both` argumen `-e image` atau, seperti yang ditunjukkan pada contoh berikut.

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

Untuk informasi selengkapnya tentang contoh aplikasi ini, lihat [Produser CPP Amazon Kinesis Video Streams, Plugin GStreamer,](https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp/blob/master/README.md) dan JNI README di. GitHub

## Jalur objek Amazon S3 (gambar)
<a name="s3-object-path"></a>

Jalur objek S3 menjelaskan lokasi pada bucket S3 yang dikonfigurasi tempat gambar yang dihasilkan akan dikirimkan. Ini menggunakan format berikut:

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

Elemen jalur objek didefinisikan sebagai berikut:
+ `ImagePrefix`- Nilai `AWS_KINESISVIDEO_IMAGE_PREFIX` jika ada.
+ `AccountID`- Akun AWS ID di mana aliran dibuat.
+ `StreamName`- Nama aliran dari mana gambar dihasilkan.
+ `ImageTimecode`- Kode waktu Epoch (dalam milidetik) dalam fragmen tempat gambar dihasilkan.
+ `RandomID`- GUID Acak.
+ `file-extension`- JPG atau PNG berdasarkan format gambar yang diminta.

Dalam contoh ini, jalur objek untuk gambar yang dihasilkan akan terlihat sebagai berikut:

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

## Mengambil metadata gambar
<a name="s3-object-metadata"></a>

Anda dapat menggunakan konsol S3 atau CLI untuk mengambil metadata untuk gambar yang dihasilkan.

Kinesis Video Streams menyetel nomor fragmen, stempel waktu produsen dan server, serta metadata tipe konten gambar yang dihasilkan, semuanya diformat sebagai metadata objek Amazon S3. Jika ada tag MKV tambahan yang ada, tag tersebut juga akan ditambahkan sebagai metadata objek Amazon S3. Contoh berikut menunjukkan cara menggunakan perintah API head-object Amazon S3 untuk mengambil metadata objek. Responsnya mencakup metadata yang dibuat oleh 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"
    }
}
```

Untuk informasi selengkapnya tentang metadata objek S3, lihat. [https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)

## Rekomendasi URI Amazon S3 untuk melindungi dari pelambatan
<a name="s3-uri-recommendations"></a>

Jika Anda menulis ribuan gambar ke Amazon S3, ada risiko pelambatan. Untuk informasi selengkapnya, lihat [Awalan S3 Menempatkan Batas Permintaan](https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance.html).

Awalan Amazon S3 dimulai dengan batas PUT 3.500 permintaan PUT per detik, dan secara bertahap akan meningkat seiring waktu untuk awalan unik. Hindari menggunakan tanggal dan waktu sebagai awalan Amazon S3. Data kode waktu akan berdampak pada satu awalan pada satu waktu, dan juga akan berubah secara teratur, membatalkan peningkatan skala awalan sebelumnya.

Untuk mengaktifkan penskalaan Amazon S3 yang lebih cepat dan konsisten, sebaiknya tambahkan awalan acak, seperti kode hex atau UUID ke URI Tujuan Amazon S3. Misalnya, awalan kode hex secara alami akan membagi permintaan Anda secara acak di antara 16 awalan yang berbeda (awalan untuk setiap karakter hex unik), yang akan memungkinkan 56.000 permintaan PUT per detik setelah Amazon S3 diskalakan secara otomatis.