翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # 自動リアルタイムイメージ生成 Amazon Kinesis Video Streams は、イメージをトランスコードして配信する機能を提供します。Kinesis Video Streams は、動画データからリアルタイムで画像を自動的に抽出し、指定した Amazon S3 バケットに画像を配信します。リアルタイムの自動イメージ抽出を実装するには、次のステップを実行します。 + 生成されたイメージを受け取る S3 バケットを作成します。 + [ImageGenerationConfiguration](API_ImageGenerationConfiguration.md) ストリームプロパティを設定して、イメージの作成方法と送信先を Kinesis Video Streams に指示します。 + イメージ生成タグの追加 – Kinesis Video Streams は、イメージ生成タグを持つフラグメントのみを使用してイメージを生成します。これらのタグは、Kinesis Video Streams プロデューサー SDK と `putKinesisVideoEventMetadata`メソッドを使用してビデオをアップロードするときに追加されます。次の手順では、これらの各ステップを実行する手順を示します。カスタマーマネージドキーを使用している場合は、`PutMedia`呼び出しを実行するロール (アップローダー) に、データの暗号化と復号、および Amazon S3 バケットへのアクセスに必要な次のアクセス許可があることを確認します。 + `kms:Encrypt` + `kms:GenerateDataKey` + `kms:Decrypt` + `s3:PutObject` 詳細については、「[サーバー側の暗号化の使用開始方法](how-kms.md#getting-started-with-sse-akvs)」を参照してください。 **生成されたイメージの送信先を設定するには** 1. イメージが送信される S3 送信先バケットを作成します。 [Amazon S3 ユーザーガイド](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html)に従って Amazon S3 バケットを作成します。バケットの URI を書き留めます。これは、ストリームのイメージ生成設定を更新する次のステップで必要になります。 1. AWS CLI がインストールされ、設定されていることを確認します。詳細については、[AWS Command Line Interface 「バージョン 2 ユーザーガイド](cli/latest/userguide/cli-chap-welcome.html)」を参照してください。 1. 次のコンテンツを入力としてという名前`update-image-generation-input.json`の新しいファイルを作成します。プレースホルダー値を、使用する値で更新します。サポートされる最大値と最小値については、[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. 次のコマンドに示すように、[UpdateImageGenerationConfiguration](API_UpdateImageGenerationConfiguration.md)API を使用してストリームのイメージ生成設定を更新し、JSON ファイルを入力としてアタッチします。ファイルパスは、現在のディレクトリ内のファイルを指すことに注意してください。 ``` aws kinesisvideo update-image-generation-configuration \ --cli-input-json file://./update-image-generation-input.json ``` 1. 成功すると、空のレスポンスが返され、ターミナルに何も出力されません。 **注記** イメージ生成設定を更新してからイメージ生成ワークフローを開始するには、少なくとも 1 分かかります。少なくとも 1 分待ってから、ビデオをストリームにアップロードします。 1. 設定を確認します。 AWS CLI を使用して、ストリームの [DescribeImageGenerationConfiguration](API_DescribeImageGenerationConfiguration.md) API を呼び出します。 ``` aws kinesisvideo describe-image-generation-configuration \ --stream-name "demo-stream" ``` Kinesis Video Streams は、イメージ生成タグを持つフラグメントのイメージのみを生成して配信します。Amazon S3 イメージ生成タグとともに提供される追加のフラグメントメタデータは、Amazon S3 メタデータとして保存されます。 **注記** イメージ生成タグは、ストリームレベルのタグではなく、フラグメントメタデータタグを指します。 **重要** イメージ生成タグは、フラグメントメタデータタグの制限にカウントされます。詳細については、「[ストリーミングメタデータサービスクォータ](limits.md#limits-streaming-metadata)」を参照してください。以下は、 `mkvinfo`ユーティリティを使用したフラグメントメタデータタグ構造の例です。イメージ生成タグは、キーがで値`AWS_KINESISVIDEO_IMAGE_GENERATION`のない MKV シンプルタグです。詳細については、Matroska ドキュメントの[「ビデオタグの例](https://www.matroska.org/technical/tagging-video-example.html)」を参照してください。 ``` |+ 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 ``` ## フラグメントへのイメージ生成タグの追加 Kinesis Video Streams は、イメージ生成タグを持つフラグメントに対してのみイメージを生成および配信します。Kinesis Video Streams は、これらの特別な MKV タグを認識し、ストリームのイメージ処理設定に基づいてイメージ生成ワークフローを開始します。 Kinesis Video Streams プロデューサー SDK を使用してメディアをアップロードする場合、 `putKinesisVideoEventMetadata`メソッドを使用して、タグ付けする各フラグメントにイメージ生成タグを追加します。`keyframe` フラグを含むフレームで `putFrame`が呼び出されると、新しいフラグメントが開始されます。録画済みの動画をアップロードする場合、ネットワーク速度に応じて、録画された動画の速度とは異なる速度でアップロードされる可能性があります。ビデオの元のタイムスタンプに基づいて定期的にイメージを生成し、Amazon Kinesis Video Streams がビデオを受信したレートに基づいて生成されたサーバータイムスタンプを使用しない場合は、プロデューサータイムスタンプを使用してイメージ生成を設定することをお勧めします。このコードの完全な例を表示するには、GitHub の[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)コードサンプルを参照してください。 ``` // 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); ``` サンプルフレームを設定するためのサンプルコードの要素は、次のように説明されています。 1. 各フラグメントはフラグメントの末尾 () で終わる必要があります`eofr`。このステートメントでは、次のフレームの先頭を示す新しいキーフレームを受信するたびに、次のフレームをストリームに追加する`eofr`前にを配置します。 1. 現在のフレームをストリームに配置します。 1. イメージ生成タグを追加します。`putKinesisVideoEventMetadata` メソッドは、呼び出し後およびの前にいつでも`putFrame(keyFrame)`呼び出すことができます`putFrame(eofr)`。フラグメントごとに呼び出されるのは最大 1 回のみです。すべてのフラグメントにはキーフレームが 1 つしかないため、現時点ではわかりやすくするために呼び出されます。の戻り値は、成功コード (0) `putKinesisVideoEventMetadata`をチェックします。 1. Kinesis Video Streams が Amazon S3 オブジェクトメタデータに変換する他のカスタムフラグメントメタデータを追加します。 1. このアップロードセッションの最終フラグメントを終了します。 ### サンプルを使用して画像生成タグを追加するコマンドラインオプションでイメージ生成タグを追加する場合は、C\$1\$1 プロデューサー SDK `kvs_gstreamer_audio_video_sample`でを使用できます。次の例に示すように、 `-e image` または `-e both`引数を追加して、この機能を有効にします。 ``` ./kvs_gstreamer_audio_video_sample stream-name \ -f video-to-upload.mp4 \ -e both ``` このサンプルアプリケーションの詳細については、GitHub [の Amazon Kinesis Video Streams CPP プロデューサー、GStreamer プラグイン、JNI README](https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp/blob/master/README.md) を参照してください。 ## Amazon S3 オブジェクトパス (イメージ) S3 オブジェクトパスは、生成されたイメージが配信される設定済み S3 バケット上の場所を記述します。次の形式を使用します。 ``` ImagePrefix_AccountID_StreamName_ImageTimecode_RandomID.file-extension ``` オブジェクトパス要素は次のように定義されます。 + `ImagePrefix` - 存在する`AWS_KINESISVIDEO_IMAGE_PREFIX`場合はの値。 + `AccountID` - ストリームが作成される AWS アカウント ID。 + `StreamName` - イメージの生成元のストリームの名前。 + `ImageTimecode` - イメージが生成されるフラグメントのエポックタイムコード (ミリ秒単位）。 + `RandomID` - ランダム GUID。 + `file-extension` - リクエストされたイメージ形式に基づく JPG または PNG。この例では、生成されたイメージのオブジェクトパスは次のようになります。 ``` 111122223333_demo-stream_16907729324_f20f9add-75e7-4399-a30f-fc7aefb1bab7.jpg ``` ## イメージメタデータの取得 S3 コンソールまたは CLI を使用して、生成されたイメージのメタデータを取得できます。 Kinesis Video Streams は、生成されたイメージのフラグメント番号、プロデューサーとサーバーのタイムスタンプ、コンテンツタイプのメタデータを、すべて Amazon S3 オブジェクトメタデータとしてフォーマットして設定します。追加の MKV タグが存在する場合、それらのタグは Amazon S3 オブジェクトメタデータとしても追加されます。次の例は、Amazon S3 head-object API コマンドを使用してオブジェクトメタデータを取得する方法を示しています。レスポンスには、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" } } ``` S3 オブジェクトメタデータの詳細については、「」を参照してください[https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html)。 ## スロットリングから保護するための Amazon S3 URI の推奨事項 Amazon S3 に何千ものイメージを書き込むと、スロットリングのリスクがあります。詳細については、[S3 プレフィックスの Put リクエストの制限](https://docs.aws.amazon.com/AmazonS3/latest/userguide/optimizing-performance.html)」を参照してください。 Amazon S3 プレフィックスは、1 秒あたり 3,500 PUT リクエストの PUT 制限で始まり、一意のプレフィックスについては時間の経過とともに徐々に増加します。Amazon S3 プレフィックスとして日付と時刻を使用しないでください。タイムコード化されたデータは、一度に 1 つのプレフィックスに影響し、定期的に変更され、以前のプレフィックスのスケールアップが無効になります。高速で一貫性のある Amazon S3 スケーリングを有効にするには、16 進数コードや UUID などのランダムプレフィックスを Amazon S3 送信先 URI に追加することをお勧めします。たとえば、16 進コードプレフィックスは、リクエストを 16 の異なるプレフィックス (一意の 16 進文字ごとのプレフィックス) にランダムに分割します。これにより、Amazon S3 が自動スケーリングされた後、1 秒あたり 56,000 個の PUT リクエストが許可されます。 # トラブルシューティング ## Amazon S3 バケットに配信されないイメージこの問題のトラブルシューティングには、注意すべき点がいくつかあります。 1. アクセス許可がない 1. イメージ生成設定が正しくない 1. タグがフラグメントに追加されませんでした ### アクセス許可がないカスタマーマネージド KMS キーを使用している場合は、次のように、`PutMedia`呼び出しを実行するロール (アップローダー) に適切な暗号化および復号アクセス許可があり、Amazon S3 バケットにアクセスできることを確認します。 + `kms:Encrypt` + `kms:GenerateDataKey` + `kms:Decrypt` + `s3:PutObject` 詳細については、「[サーバー側の暗号化の使用開始方法](how-kms.md#getting-started-with-sse-akvs)」を参照してください。 ### 送信先を確認する AWS CLI を使用して、ストリームの DescribeImageGenerationConfiguration API を呼び出します。 ``` aws kinesisvideo describe-image-generation-configuration \ --stream-name "demo-stream" ``` レスポンス`DestinationConfig`のを確認し、正しく見えることを確認します。 ### イメージ生成タグがフラグメントに追加されていることを確認します。 1. `putKinesisVideoEventMetadata` 呼び出しが成功したことを確認します。 `putKinesisVideoEventMetadata` メソッドは、成功するとステータスコード 0 を返します。0 の関数の戻り値を確認することをお勧めします。0 以外のステータスコードが返された場合は、それを 16 進数に変換し、 [エラーコードのリファレンス](producer-sdk-errors.md)で詳細を確認してください。エラーログがオンになっていることを確認し、アプリケーション内の他のエラーがないかログを確認します。アプリケーションのフレーム送信呼び出しパターンを確認して、推奨される実装と比較します。 [フラグメントへのイメージ生成タグの追加](s3-real-time-image-create.md#s3-adding-image-tags) 1. ローカルで生成された MKV ファイルを検証するプロデューサー SDK またはサンプルアプリケーションがタグを正しく追加したことを確認します。 1. `KVS_DEBUG_DUMP_DATA_FILE_DIR` 環境変数を設定します。この値が設定されている場合、プロデューサー SDK は Kinesis Video Streams に送信したメディアファイルを指定された場所に書き込みます。 ``` export KVS_DEBUG_DUMP_DATA_FILE_DIR=/path/to/output/directory ``` **注記** パスが存在しない場合、SDK は新しいディレクトリを作成しません。必要に応じてフォルダを作成します。 1. アプリケーションを再度実行します。指定した出力ディレクトリに書き込まれる`.mkv`ファイルが表示されます。 1. MKVToolNix または他のソフトウェアを使用して、タグが存在することを確認します。 1. MKVToolNix をインストールします。 `brew install mkvtoolnix` 1. 出力ディレクトリのいずれかの`.mkv`ファイルを使用して MKVToolNix を実行します。 ``` mkvinfo -v ./path/to/video/file ``` 1. MKVToolNix 出力を確認します。プロ`KinesisVideoStream::PutFragmentMetadata`デューサー SDK メソッドが正しく呼び出された場合、次の MKV タグが表示されます。 ``` |+ Tags | + Tag | + Simple | + Name: AWS_KINESISVIDEO_IMAGE_GENERATION ``` **注記** タグは、その前のクラスターに属します。 1. MKV タグが存在しない場合は、プロ`KinesisVideoStream::PutEventMetadata`デューサー SDK メソッドが `STREAM_EVENT_TYPE_IMAGE_GENERATION`引数で呼び出され、成功 (0) コードを返したことを確認します。