本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
在 Kinesis 视频直播中使用流媒体元数据
您可以使用Amazon Kinesis Video Streams s Producer SDK 在 Kinesis 视频流中嵌入单个片段级别的元数据。键值对中的值。您可以使用它来描述片段的内容，嵌入必须与实际片段一起传输的相关传感器读数，或者满足其他自定义需求。元数据作为 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 MediaSource Producer 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 视频流添加流媒体元数据：
-
您最多可在片段前附加 10 个元数据项目。
-
片段元数据名称 的最大长度可为 128 个字节。
-
片段元数据值 的最大长度可为 256 个字节。
-
片段元数据名称不能以字符串 “
AWS” 开头。如果添加此类元数据项目，则 PIC 中的putFragmentMetadata方法将返回STATUS_INVALID_METADATA_NAME错误（错误代码0x52000077）。然后，您的应用程序可以忽略该错误（PIC 不添加元数据项目）或响应该错误。