搭配 Kinesis 視訊串流使用串流中繼資料

您可以使用 Amazon Kinesis Video Streams 製作者開發套件，在 Kinesis 視訊串流中的個別片段層級內嵌中繼資料。Kinesis Video Streams 中的中繼資料是可變的索引鍵值配對。您可以使用它來描述片段的內容，嵌入必須與實際片段一起傳輸的相關傳感器讀數，或者滿足其他自定義需求。中繼資料提供為 GetMedia 或 GetMediaForFragmentList API 操作的一部分。在流保留期的整個持續時間內，它與片段一起存儲。您的使用應用程式可以讀取、處理和回應，根據中繼資料，使用Kinesis 視頻流解析器庫.

中繼資料可以用兩種模式內嵌於串流中的片段：

• 非持續性 — 您可以根據已發生的業務特定條件，在串流中的片段上單次或特定基礎上，將中繼資料附加到串流中的片段。例如，智慧型攝影機會偵測動作並將中繼資料新增至包含動作的對應片段，然後再將片段傳送至 Kinesis 視訊串流。您可以將中繼資料套用至下列格式的片段中：Motion = true。

• 持續性 — 您可以根據持續需求，將中繼資料附加至串流中連續的連續片段。例如，智慧型攝影機會傳送與傳送至 Kinesis 視訊串流的所有片段相關聯的目前經緯度座標。您可以將中繼資料套用至所有下列格式的片段中：Lat = 47.608013N , Long = -122.335167W

您可以根據應用程式的需求，同時在同一片段附加兩種模式的中繼資料。內嵌的中繼資料可能包括偵測到的物件、追蹤活動、GPS 座標等任何您欲附加至串流片段的自訂資料。中繼資料是以鍵值字串對編碼。

將中繼資料新增至 Kinesis 視訊串流

您新增至 Kinesis 視訊串流的中繼資料會建模為 MKV 標籤，並以索引鍵值配對的方式實作。

中繼資料可以是暫時性，例如標記串流內的事件，或持久性，例如識別指定事件發生的片段。持續性中繼資料項目會保留，並套用至每個連續片段，直到取消為止。

注意

使用 Producer 資料庫 新增的中繼資料項目不同於以 TagStream、UntagStream、ListTagsForStream 執行的串流層級標記 API。

串流中繼資料 API

您可以使用下列製作者開發套件中的操作來執行串流中繼資料。

PIC

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

C++ 製作者開發套件

/**
 * 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 製作者開發套件

您可以使用 Java 生產者 SDK，將元數據添加到MediaSource使用MediaSourceSink.onCodecPrivateData：

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

持續性和非永久性中繼資

對於非持久性中繼資料，您可以新增數個相同​名稱​的中繼資料項目。在中繼資料項目附加至下一個片段前，製作者開發套件會搜集中繼資料佇列中的所有中繼資料項目。中繼資料項目套用至串流後，中繼資料佇列將清空。若要重複中繼資料，請再次呼叫 putKinesisVideoFragmentMetadata 或 putFragmentMetadata。

對於持久的中繼資料，製作者開發套件將比照非持久中繼資料，收集中繼資料佇列中的所有中繼資料項目。但是，當中繼資料項目附加到下一個片段前面時，不會從佇列中移除。

呼叫 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​ 擷取累積的中繼資料。若要擷取單一中繼資料項目，clear請先呼叫清除收集的中繼資料，然後再次擷取中繼資料項目。

串流元數據限制

如片段元數據配額需將串流中繼資料新增至 Kinesis 視訊串流的限制的詳細資訊，請參閱