本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 在 Kinesis Video Streams 中使用直播元数据
<a name="how-meta"></a>

你可以使用 Amazon Kinesis Video Streams 制作器 SDK 在 Kinesis 视频流中嵌入单个片段级别的元数据。Kinesis Video Streams 中的元数据是一个可变的键值对。您可以使用它来描述片段的内容，嵌入必须与实际片段一起传输的相关传感器读数，或者满足其他自定义需求。元数据作为 [GetMedia](API_dataplane_GetMedia.md) 或 [GetMediaForFragmentList](API_reader_GetMediaForFragmentList.md) API 操作的一部分提供。它与片段一起存储在直播的整个保留期内。您的消费应用程序可以使用基于元数据进行读取、处理和响应[使用解析器库观看摄像机的输出](parser-library.md)。

可通过以下两种模式在数据流片段中嵌入元数据：
+ **非持续** — 您可以根据已出现的业务特定标准，一次性或临时将元数据附加到流中的片段。例如，智能相机可以检测动作，并在将片段发送到其 Kinesis 视频流之前，向包含动作的相应片段添加元数据。您可以采用以下格式将元数据应用于片段：`Motion = true`。
+ **持续-您可以根据持续**需要将元数据附加到流中连续的片段。例如，智能相机将与其发送的所有片段关联的当前纬度和经度坐标发送到其 Kinesis 视频流。您可以采用以下格式将元数据应用于所有片段：`Lat = 47.608013N , Long = -122.335167W`。

您可以根据应用程序的需求，将这两种模式的元数据同时附加到同一个片段中。嵌入的元数据可能包括检测到的对象、跟踪的活动、GPS 坐标或者要与数据流中的片段关联的任何其他自定义数据。元数据编码为键值字符串对。

## 向 Kinesis 视频流添加元数据
<a name="how-meta-add"></a>

您添加到 Kinesis 视频流中的元数据将建模为 MKV 标签，这些标签以键值对的形式实现。

元数据可以是*临时的*，如用于标记数据流内的事件，也可以是*持久的*，如用于识别发生给定事件的片段。永久性元数据项将保留，并应用于每个连续的片段，直到它被取消。

**注意**  
使用添加的元数据项不同[上传到 Kinesis Video Streams](producer-sdk.md)于使用[TagStream](API_TagStream.md)[UntagStream](API_UntagStream.md)、和 APIs 实现的流级标记。[ListTagsForStream](API_ListTagsForStream.md)

### 流式传输元数据 API
<a name="how-meta-api"></a>

您可以在制作器 SDK 中使用以下操作来实现流式传输元数据。

**Topics**
+ [PIC](#how-meta-api-pic)
+ [C\+\+ 制作器 SD](#how-meta-api-cpp)
+ [Java 制作器 SD](#how-meta-api-java)
+ [永久和非持久元数据](#how-meta-api-persistence)

#### PIC
<a name="how-meta-api-pic"></a>

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

#### C\+\+ 制作器 SD
<a name="how-meta-api-cpp"></a>

```
/**
 * 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 制作器 SD
<a name="how-meta-api-java"></a>

您可以使用 Java 制作器 SDK `MediaSource` 通过以下方式向添加元数据`MediaSourceSink.onCodecPrivateData`：

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

#### 永久和非持久元数据
<a name="how-meta-api-persistence"></a>

对于非持久元数据，您可以添加多个具有相同*名称* 的元数据项目。Producer SDK 会收集元数据队列中的元数据项，直到它们被添加到下一个片段之前。在将元数据项目应用到数据流时，将清除元数据队列。要重复元数据，请再次调用 `putKinesisVideoFragmentMetadata` 或 `putFragmentMetadata`。

对于永久性元数据，Producer SDK 收集元数据队列中的元数据项的方式与非永久性元数据相同。但是，当元数据项被添加到下一个片段之前时，它们不会从队列中删除。

在将 `persistent` 设置为 `true` 时调用 `putKinesisVideoFragmentMetadata` 或 `putFragmentMetadata` 会出现以下行为：
+ 调用 API 会将元数据项目置于队列中。当项目位于队列中时，会将元数据作为 MKV 标签添加到每个片段中。
+ 使用与以前添加的元数据项目相同的*名称* 和不同的*值* 调用 API 将覆盖该项目。
+ 使用空*值* 调用 API 将从元数据队列中删除（取消）元数据项目。