Kinesis Video Streams でのストリーミングメタデータの使用

Amazon Kinesis Video Streams プロデューサー SDK を使うと、個々のフラグメントレベルでメタデータを Kinesis のビデオストリーム に埋め込むことができます。Kinesis Video Streams 内のメタデータは、変更可能なキーバリューのペアです。フラグメントのコンテンツを記述したり、実際のフラグメントと一緒に転送する必要がある関連するセンサーの読み取り値を埋め込んだり、その他のカスタムニーズを満たすために使用できます。メタデータは GetMedia またはGetMediaForFragmentList API オペレーションの一部として使用できます。ストリームの保存期間中は、フラグメントと一緒に保存されます。コンシューマーアプリケーションでは、を使用してメタデータを読み取り、処理し、それに基づいて対応できます。Kinesis ビデオストリームパーサーライブラリ

メタデータをストリーム内のフラグメントを埋め込むモードは 2 つあります。

• 非永続的 — 発生したビジネス固有の基準に基づいて、ストリーム内のフラグメントに 1 回限りまたはアドホックにメタデータを添付できます。一例として、動きを検出して、Kinesis のビデオストリームに送信する前にその動きを含む対応フラグメントにメタデータを追加するスマートカメラがあります。フラグメントには、以下の形式でメタデータを適用できます。Motion = true

• 永続的 — 必要に応じてストリーム内の連続するフラグメントにメタデータを添付できます。一例として、Kinesis のビデオストリームに送信するすべてのフラグメントに関連付けられた現在の緯度と経度の座標を送信するスマートカメラがあります。すべてのフラグメントには、以下の形式でメタデータを適用できます。Lat = 47.608013N , Long = -122.335167W

アプリケーションのニーズに基づいて、同一のフラグメントに対して同時にこのモードの両方でメタデータを付け加えられます。埋め込まれたメタデータには、検出されたオブジェクト、トラッキングされたアクティビティ、GPS 座標、またはその他のカスタムデータで、ストリームのフラグメントと関連付けるものが含まれる場合があります。メタデータはキーと値の文字列ペアとしてエンコードされます。

Kinesis ビデオストリームへのメタデータの追加

Kinesis のビデオストリームに追加するメタデータは MKV タグとしてモデル化され、キーバリューのペアとして実装されます。

メタデータは、ストリーム内のイベントをマークするなどの一時的なもの、またはあるイベントが発生したフラグメントを識別するなどの永続的なもののいずれかです。永続メタデータ項目はキャンセルされるまで残り、連続する各フラグメントに適用されます。

注記

プロデューサーライブラリ を使用して追加されたメタデータ項目は、TagStream、UntagStream、およびListTagsForStreamを使って実装されたストリームレベルのタグ付け API とは異なります。

ストリーミングメタデータ API

メタデータストリーミングを実装するために、プロデューサー SDK で以下のオペレーションを利用できます。

PIC

PUBLIC_API STATUS putKinesisVideoFragmentMetadata(STREAM_HANDLE streamHandle, 
    PCHAR name, 
    PCHAR value, 
    BOOL persistent);

C++ プロデューサー SDK

/**
 * Appends a "tag" or metadata - a key/value string pair into the stream.
 */
bool putFragmentMetadata(const std::string& name, const std::string& value, bool persistent = true);

Java プロデューサー SDK

Java Producer SDK MediaSource を使用して、にメタデータを追加できますMediaSourceSink.onCodecPrivateData。

void onFragmentMetadata(final @Nonnull String metadataName, final @Nonnull String metadataValue, final boolean persistent)
throws KinesisVideoException;

永続メタデータと非永続メタデータ

非永続メタデータでは、同一の名前を使ったメタデータ項目を複数追加できます。プロデューサー SDK は、次のフラグメントにメタデータ項目が先頭に追加されるまで、メタデータキュー内でメタデータ項目を収集します。メタデータキューはストリームにメタデータ項目が適用されるとクリアされます。メタデータを繰り返すには、putKinesisVideoFragmentMetadata または putFragmentMetadata を再度呼び出します。

永続的なメタデータでは、プロデューサー SDK は、非永続メタデータと同様な方法で、メタデータキュー内のメタデータ項目を収集します。ただし、メタデータ項目が次のフラグメントの前に追加されても、キューからは削除されません。

putKinesisVideoFragmentMetadata または putFragmentMetadata で persistent を true に設定して呼び出すと、以下のような動作になります。

• API を呼び出すと、キューにメタデータ項目が追加されます。メタデータは、メタデータ項目がキュー内にある間に、フラグメントごとに MKV タグとして追加されます。

• 同一の名前で、以前に追加されたメタデータ項目と異なる値で API を呼び出すと、その項目は上書きされます。

• 空の値で API を呼び出すと、メタデータキューからそのメタデータ項目は削除 (キャンセル) されます。

Kinesis ビデオストリームに埋め込まれたメタデータの消費

Kinesis のビデオストリーム内のメタデータを使用するには、MkvTagProcessor の実装を使用します。

public interface MkvTagProcessor {
        default void process(MkvTag mkvTag, Optional<FragmentMetadata> currentFragmentMetadata) {
            throw new NotImplementedException("Default FragmentMetadataVisitor.MkvTagProcessor");
        }
        default void clear() {
            throw new NotImplementedException("Default FragmentMetadataVisitor.MkvTagProcessor");
	    }
    }
}

このインターフェイスは、Kinesis ビデオストリームパーサーライブラリ の FragmentMetadataVisitor クラスにあります。

FragmentMetadataVisitor クラスには MkvTagProcessor の実装が含まれます。

public static final class BasicMkvTagProcessor implements FragmentMetadataVisitor.MkvTagProcessor {
    @Getter
    private List<MkvTag> tags = new ArrayList<>();

    @Override
    public void process(MkvTag mkvTag, Optional<FragmentMetadata> currentFragmentMetadata) {
        tags.add(mkvTag);
    }
    
    @Override
    public void clear() {
        tags.clear();
	}
}

KinesisVideoRendererExample クラスには、BasicMkvTagProcessor の使用例があります。以下の例では、BasicMkvTagProcessor があるアプリケーションの MediaProcessingArguments に追加されます。

if (renderFragmentMetadata) {
    getMediaProcessingArguments = KinesisVideoRendererExample.GetMediaProcessingArguments.create(
        Optional.of(new FragmentMetadataVisitor.BasicMkvTagProcessor()));

BasicMkvTagProcessor.process メソッドは、フラグメントのメタデータが到着すると呼び出されます。蓄積されたメタデータは GetTags を使って取得できます。1 つのメタデータ項目を取得するには、clearまず呼び出して収集したメタデータを消去し、次にメタデータ項目を再度取得します。

ストリーミングメタデータの制限

Kinesis ビデオストリームへのストリーミングメタデータの追加に適用される制限の詳細については、を参照してくださいフラグメントメタデータのクォータ。