本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
在 Kinesis Video Streams 中使用流式传输元数据
你可以使用 Amazon Kinesis Video Streams Producer SDK 在 Kinesis 视频流中嵌入单个片段级别的元数据。Kinesis Video Streams 中的元数据是一个可变的键值对。您可以使用它来描述片段的内容，嵌入必须与实际片段一起传输的相关传感器读数，或者满足其他自定义需求。元数据作为 GetMedia 或 GetMediaForFragmentList API 操作的一部分提供。在直播的整个保留期内，它与片段一起存储。您的消费应用程序可以使用基于元数据进行读取、处理和响应Kinesis 视频流解析器库。
可通过以下两种模式在数据流片段中嵌入元数据：
-
非持续 — 您可以根据已出现的业务特定标准，一次性或临时将元数据附加到流中的片段。例如，智能相机可以检测动作，并在将片段发送到其 Kinesis 视频流之前，向包含动作的相应片段添加元数据。您可以采用以下格式将元数据应用于片段：
Motion = true。 -
持续-您可以根据持续需要将元数据附加到流中连续的片段。例如，智能相机将与其发送的所有片段关联的当前纬度和经度坐标发送到其 Kinesis 视频流。您可以采用以下格式将元数据应用于所有片段：
Lat = 47.608013N , Long = -122.335167W。
您可以根据应用程序的需求，将这两种模式的元数据同时附加到同一个片段中。嵌入的元数据可能包括检测到的对象、跟踪的活动、GPS 坐标或者要与数据流中的片段关联的任何其他自定义数据。元数据编码为键值字符串对。
向 Kinesis 视频流添加元数据
您添加到 Kinesis 视频流中的元数据将建模为 MKV 标签，这些标签以键值对的形式实现。
元数据可以是临时的，如用于标记数据流内的事件，也可以是持久的，如用于识别发生给定事件的片段。永久性元数据项将保留，并应用于每个连续的片段，直到它被取消。
注意
使用创建者库添加的元数据项目不同于使用 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 Prod MediaSource ucer SDK 通过以下方式向添加元数据MediaSourceSink.onCodecPrivateData：
void onFragmentMetadata(final @Nonnull String metadataName, final @Nonnull String metadataValue, final boolean persistent) throws KinesisVideoException;
永久和非持久元数据
对于非持久元数据，您可以添加多个具有相同名称 的元数据项目。创建者开发工具包一直收集元数据队列中的元数据项目，直到将这些项目附加到下一个片段之前。在将元数据项目应用到数据流时，将清除元数据队列。要重复元数据，请再次调用 putKinesisVideoFragmentMetadata 或 putFragmentMetadata。
对于持久元数据，创建者开发工具包将按照处理非持久元数据的相同方式收集元数据队列中的元数据项目。但是，当元数据项被添加到下一个片段之前时，它们不会从队列中删除。
在将 persistent 设置为 true 时调用 putKinesisVideoFragmentMetadata 或 putFragmentMetadata 会出现以下行为：
-
调用 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 视频流添加直播元数据所适用的限制的更多信息，请参阅