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](API_ImageGenerationConfiguration.md)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](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. Perbarui konfigurasi pembuatan gambar stream menggunakan [UpdateImageGenerationConfiguration](API_UpdateImageGenerationConfiguration.md) 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](API_DescribeImageGenerationConfiguration.md) 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\$1\$1 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 [Amazon Kinesis Video Streams CPP GStreamer Producer, Plugin](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.

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

## Gambar tidak dikirim ke bucket Amazon S3
<a name="s3-images-not-delivered"></a>

Untuk mengatasi masalah ini, ada beberapa hal yang harus diwaspadai:

1. Izin tidak ada

1. Konfigurasi pembuatan gambar salah

1. Tag tidak ditambahkan ke fragmen

### Izin tidak ada
<a name="s3-missing-permissions"></a>

Jika Anda menggunakan kunci KMS yang dikelola pelanggan, pastikan peran yang melakukan `PutMedia` panggilan (pengunggah) memiliki izin enkripsi dan dekripsi yang sesuai, serta memiliki akses ke bucket Amazon S3, sebagai berikut:
+ `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).

### Verifikasi tujuan
<a name="s3-verify-destination"></a>

Gunakan AWS CLI untuk memanggil DescribeImageGenerationConfiguration API untuk streaming Anda.

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

Tinjau `DestinationConfig` dalam respons dan konfirmasikan itu terlihat benar.

### Verifikasi bahwa tag pembuatan gambar telah ditambahkan ke fragmen
<a name="s3-verify-tag-added"></a>

1. Periksa apakah `putKinesisVideoEventMetadata` panggilan berhasil.

   `putKinesisVideoEventMetadata`Metode mengembalikan kode status 0 setelah berhasil. Kami merekomendasikan untuk memeriksa nilai pengembalian fungsi untuk 0. Jika kode status bukan nol dikembalikan, ubah menjadi hex dan periksa [Referensi kode kesalahan](producer-sdk-errors.md) untuk informasi lebih lanjut.

   Pastikan Anda mengaktifkan log kesalahan dan tinjau log untuk kesalahan lain dalam aplikasi. Tinjau dan bandingkan pola panggilan pengiriman bingkai aplikasi Anda dengan implementasi yang disarankan:[Menambahkan tag pembuatan gambar ke fragmen](s3-real-time-image-create.md#s3-adding-image-tags).

1. Verifikasi file MKV yang dihasilkan secara lokal

   Konfirmasikan bahwa Producer SDK atau Sample Application menambahkan tag dengan benar.

   1. Mengatur variabel `KVS_DEBUG_DUMP_DATA_FILE_DIR` lingkungan. Jika nilai ini disetel, Producer SDK akan menulis file media yang akan dikirim ke Kinesis Video Streams ke lokasi yang ditentukan.

      ```
      export KVS_DEBUG_DUMP_DATA_FILE_DIR=/path/to/output/directory
      ```
**catatan**  
SDK tidak akan membuat direktori baru jika jalur tidak ada. Buat folder jika perlu.

   1. Jalankan aplikasi lagi. Anda akan melihat `.mkv` file yang ditulis ke direktori output yang ditentukan.

   1. Verifikasi konten untuk memastikan tag hadir menggunakan MKVTool Nix, atau perangkat lunak lain.

      1. Instal MKVTool Nix: `brew install mkvtoolnix`

      1. Jalankan MKVTool Nix dengan salah satu `.mkv` file di direktori output.

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

      1. Tinjau output MKVTool Nix. Jika metode SDK `KinesisVideoStream::PutFragmentMetadata` produsen dipanggil dengan benar, Anda akan melihat tag MKV berikut.

         ```
         |+ Tags
         | + Tag
         |  + Simple
         |   + Name: AWS_KINESISVIDEO_IMAGE_GENERATION
         ```
**catatan**  
Tag milik Cluster sebelumnya.

   1. Jika tag MKV tidak ada, pastikan bahwa metode SDK `KinesisVideoStream::PutEventMetadata` produsen telah dipanggil dengan `STREAM_EVENT_TYPE_IMAGE_GENERATION` argumen, dan bahwa itu mengembalikan kode sukses (0).