# 将元数据嵌入视频流中
Amazon Interactive Video Service (IVS) 定时元数据提供了一种在 Amazon IVS 视频流中嵌入元数据的方法。可确保所有观众在视频流中同时接收元数据，而不考虑视频流延迟或地理位置。
## 什么是定时元数据？
*定时*元数据是带有时间戳的元数据。可使用 IVS API 或 IVS 广播 SDK 以编程方式将其插入流中。Amazon IVS 处理流时，定时元数据与音频和视频帧同步。在播放过程中，视频流的所有观众可同时获取视频流相关的元数据。时间码作为提示点，可用于根据数据触发操作，如下所示：
+ 更新体育赛事的球员统计信息。
+ 发送实时购物流的产品详细信息。
+ 发送实时测验流的问题。
Amazon IVS 定时元数据使用嵌入在视频段中的 ID3 标签。因此，可以在录制的视频中使用。
## 设置 IAM 权限
**先决条件：**继续操作之前，您应已完成 [IVS 低延迟流式传输入门](getting-started.md)（包括创建 IAM 用户和设置权限）。
接下来，您必须授予 IAM 用户使用定时元数据的权限。按照以下步骤进行操作：
1. 登录 Amazon 管理控制台，并通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 在导航窗格中，选择 **Users**（用户），然后选择所需的用户（在创建亚马逊云科技账户时指定的用户名）。
1. 在用户 **Summary (摘要)** 窗口中的 **Permissions (权限)** 选项卡上，选择 **Add inline policy (添加内联策略)**（右侧）。
1. 在 **JSON** 选项卡上，粘贴以下 Blob：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ivs:PutMetadata"
],
"Resource": "arn:aws:ivs:*:*:channel/*"
}
]
}
```
------
1. 仍在 **Create Policy (创建策略)** 窗口中，选择 **Review Policy (查看策略)**。为策略指定一个 **Name** (名称)，然后选择 **Create Policy (创建策略)**。
1. 您将返回用户 **Summary** (摘要) 窗口，其中显示新的策略名称。
## 插入定时元数据
只能将定时元数据插入到指定通道上的活动流中。
### 使用 Amazon CLI
对于测试，添加定时元数据的最简单方法是使用 Amazon CLI。使用 Amazon CLI，需要首先在计算机上下载并配置 CLI。按照 [IVS 低延迟流式传输入门](getting-started.md) 逐步进行操作时，您可能已完成如上操作； 如果没有，请立即执行。有关详细信息，请参阅 [Amazon 命令行界面用户指南](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)。
有了 CLI 后：
1. 运行 `put-metadata` 命令并传入通道 ARN 和元数据：
```
aws ivs put-metadata --channel-arn --metadata
```
例如：
```
aws ivs put-metadata --channel-arn arn:aws:ivs:us-west-2:465369119046:channel/GbiYJna5hFoC --metadata '{"question": "What does IVS stand for?", "correctIndex": 0, "answers": ["interactive video service", "interesting video service", "ingenious video service"]}'
```
1. Amazon IVS 检查视频流是否为实时。如果视频流不是实时的，则会出现错误；否则，CLI 返回时不会出现错误，并将元数据（文本 blob）插入到视频流中。这种情况会尽快发生。无法保证何时发生；但所有观众都会在流视频中的同一点看到元数据。
### 使用 Amazon IVS API
要以编程方式插入定时元数据，请使用 [PutMetadata](https://docs.aws.amazon.com/ivs/latest/LowLatencyAPIReference/API_PutMetadata.html) API 操作。
以下是 HTTP 请求示例：
```
POST /PutMetadata HTTP/1.1
{
"channelArn": "my_channel",
"metadata": "{\"question\": \"What does IVS stand for?\", \"correctIndex\": 0, \"answers\": [\"interactive video service\", \"interesting video service\", \"ingenious video service\"]}"
}
```
### 使用 IVS 广播 SDK
您可以使用 IVS 广播 SDK 在带内插入定时元数据。这可能有助于将元数据与音频和视频内容同步。
+ Android – 在 `BroadcastSession` 类中，请使用 `sendTimedMetadata`。
+ iOS – 在 `IVSBroadcastSession` 类中，请使用 `sendTimedMetadata`。
## 使用定时元数据
借助 Amazon IVS 播放器，使用嵌入在视频流中的定时元数据。请参阅 [IVS 播放器开发工具包](player.md) 和文档的其余部分。
以下是使用 Amazon IVS 播放器软件开发工具包将接收到的任何元数据打印到控制台的示例代码段。播放包含嵌入元数据的片段时，都会触发一个事件。（Web 的事件是 `TEXT_METADATA_CUE`，Android 是 `onCue()`，iOS 是 `player(_:didOutputCue:)`。） 您可以使用此事件在客户端应用程序中启动功能，例如更新交互式小部件。直播和录制内容都会触发此事件。
**适用于 Web 的 Amazon IVS 播放器开发工具包：**
```
const player = IVSPlayer.create();
player.addEventListener(IVSPlayer.PlayerEventType.TEXT_METADATA_CUE,
function (cue) {
console.log('Timed metadata: ', cue.text);
});
```
**适用于 Android 的 Amazon IVS 播放器开发工具包：**
```
@Override
public void onCue(@NonNull Cue cue) {
if(cue instanceof TextMetadataCue) {
Log.i("Timed Metadata: ", ((TextMetadataCue)cue).text);
}
}
```
**适用于 iOS 的 Amazon IVS 播放器开发工具包：**
```
func player(_ player: IVSPlayer, didOutputCue cue: IVSCue) {
if let textMetadataCue = cue as? IVSTextMetadataCue {
print("Timed Metadata: \(textMetadataCue.text)")
}
}
```
**注意：**在播放器 1.3.0 及以上版本中，iOS Safari 和 iOS Chrome 支持定时元数据。
### 使用 SEI 数据
在启用单个参与者录制的情况下录制 IVS 实时舞台时，将会保留补充增强信息（SEI）有效载荷并将其发布为 `IVSPlayer.PlayerEventType.SEI` 事件。以下是使用 IVS Web 播放器 SDK 时将 SEI 数据打印到控制台的示例片段：
```
const player = IVSPlayer.create();
player.addEventListener(IVSPlayer.MetadataEventType.SEI, (event) => {
const data = new TextDecoder().decode(event.data);
const message = JSON.parse(data);
console.log(message);
});
```
**注意：**有关 SEI 的更多信息，请参阅《IVS Web 广播 SDK 指南》中有关实时直播的[补充增强信息（SEI）](https://docs.aws.amazon.com/ivs/latest/RealTimeUserGuide/web-publish-subscribe.html#web-publish-subscribe-sei-attributes)**。
### 示例演示：测验应用程序
GitHub 上提供了交互式测验应用程序的代码示例。我们通过定时元数据使用 JSON 填充测验用户界面来显示问题和答案。答案是可选的，并显示选择是否正确。
| Amazon IVS 播放器软件开发工具包平台 | 示例代码库 |
| --- | --- |
| Web | [https://github.com/aws-samples/amazon-ivs-basic-web-sample](https://github.com/aws-samples/amazon-ivs-basic-web-sample)在此存储库中，请参阅[测验演示](https://github.com/aws-samples/amazon-ivs-basic-web-sample/tree/master/simple-quiz)（和[实际演示](https://codepen.io/amazon-ivs/pen/XWmjEKN)）。 |
| Android | [https://github.com/aws-samples/amazon-ivs-player-android-sample](https://github.com/aws-samples/amazon-ivs-player-android-sample)在此存储库中，请参阅[测验演示](https://github.com/aws-samples/amazon-ivs-player-android-sample/tree/master/quizdemo)。 |
| iOS | [https://github.com/aws-samples/amazon-ivs-player-ios-sample](https://github.com/aws-samples/amazon-ivs-player-ios-sample)在此存储库中，请参阅[测验演示](https://github.com/aws-samples/amazon-ivs-player-ios-sample/tree/master/QuizDemo)。 |
## 查看定时元数据
如需要，您可以在控制台中查看嵌入在实时流中的定时元数据：
1. 打开 [Amazon IVS 控制台](https://console.aws.amazon.com/ivs)。
1. 在左上角选择汉堡包图标以打开导航窗格，然后选择 **Live channels (实时通道)**。
1. 选择要查看其流的通道，以转到该通道的详细信息页面。
此实时流正在该页面的 **Live stream (实时流)** 部分播放。
1. 在窗口底部，选择 **Timed Metadata** (定时元数据)。
播放器播放时，收到每个时间元数据事件时，会显示其值和收到的时间。
## 了解更多信息
请参阅 [Using Amazon Interactive Video Service Timed Metadata](https://aws.amazon.com/blogs/media/part-1-using-amazon-interactive-video-service-timed-metadata/)（使用 Amazon Interactive Video Service 定时元数据），这是关于使用 Amazon IVS 定时元数据的两部分博客系列中的第一部分。