# 在影片串流中內嵌中繼資料
Amazon Interactive Video Service (IVS) 定時中繼資料提供在 Amazon IVS 串流中內嵌中繼資料的方法。無論串流延遲或地理位置為何，都能確保所有觀眾同時在影片串流中收到中繼資料。
## 定時中繼資料是什麼？
*定時*中繼資料是帶有時間戳記的中繼資料。可以使用 IVS API 或 IVS 廣播 SDK 以程式設計方式將其插入串流中。當 Amazon IVS 處理串流時，定時中繼資料會與音訊和影片影格同步。在播放期間，串流的所有觀眾都會同時取得與串流有關的中繼資料。時間碼做為提示點，可用來根據資料觸發動作，如下所示：
+ 更新運動串流的球員統計資料。
+ 傳送即時購物串流的產品詳細資訊。
+ 傳送即時測驗串流的問題。
Amazon IVS 定時中繼資料使用內嵌於影片區段中的 ID3 標籤。因此，可以在錄製的影片中使用它們。
## 設定 IAM 許可
**必要條件：**在繼續進行之前，您應該先完成 [開始使用 IVS 低延遲串流](getting-started.md) (包括建立 IAM 使用者和設定許可)。
接下來，您必須授予 IAM 使用者許可，以便使用定時中繼資料。請遵循下列步驟：
1. 登入 AWS 管理主控台，然後前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。
1. 在導覽窗格中，選擇 **Users** (使用者)，然後選擇所需的使用者 (您在建立 AWS 帳戶時指定的使用者名稱)。
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** (摘要) 視窗，會顯示新的政策名稱。
## 插入定時中繼資料
您只能將定時中繼資料插入指定頻道上作用中的串流。
### 使用 AWS CLI
對於測試，新增定時中繼資料的最簡單方法是使用 AWS CLI。使用 AWS CLI 要求您先在機器上下載並設定 CLI。當您完成 [開始使用 IVS 低延遲串流](getting-started.md) 後可能已經完成它；如果沒有，現在就完成。如需詳細資訊，請參閱 [AWS 命令列界面使用者指南](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 播放器 SDK](player.md) 和播放器文件的其餘部分。
以下是範例程式碼片段，它們會列印使用 Amazon IVS 播放器開發套件的主控台接收的任何中繼資料。每當播放到達含有內嵌中繼資料的區段時，就會觸發事件。(本次事件為適用於 Web 的 `TEXT_METADATA_CUE`、適用於 Android 的 `onCue()`，以及適用於 iOS 的 `player(_:didOutputCue:)`。) 您可以使用此事件來啟動用戶端應用程式中的功能，例如更新互動式 Widget。即時和錄製的內容都會觸發此事件。
**適用於 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 來填入測驗 UI 以顯示問題和答案。答案是可選的，並顯示選擇是否正確。
| 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** (定時中繼資料)。
播放器正在播放時，當接收到每個定時中繼資料事件時，會顯示其值和接收時間。
## 如需詳細資訊
請參閱[使用 Amazon Interactive Video Service 定時中繼資料](https://aws.amazon.com/blogs/media/part-1-using-amazon-interactive-video-service-timed-metadata/)，這是關於使用 Amazon IVS 定時中繼資料的兩部分部落格系列的第一部分。