# 動画ストリーム内にメタデータを埋め込む
Amazon Interactive Video Service (IVS) の時間指定メタデータは、Amazon IVS ストリームにメタデータを埋め込む方法を提供します。これにより、ストリームのレイテンシーや地理的位置にかかわらず、すべての視聴者が同時に動画ストリームでメタデータを受信できるようになります。
## 時間指定メタデータとは
*時間指定*メタデータは、タイムスタンプ付きのメタデータです。IVS API または IVS broadcast SDK を使用して、プログラムでストリームに挿入できます。Amazon IVS がストリームを処理するとき、時間指定メタデータはオーディオフレームおよび動画フレームと同期されます。再生中、ストリームのすべての視聴者は、ストリームに対してメタデータを同時に取得します。タイムコードはキューポイントとして機能します。キューポイントを使用すると、次のようなデータに基づいてアクションをトリガーできます。
+ スポーツストリームの選手統計を更新する。
+ ライブショッピングストリームの製品詳細を送信する。
+ ライブクイズストリームの質問を送信する。
Amazon IVS の時間指定メタデータは、動画セグメントに埋め込まれた ID3 タグを使用します。その結果、録画された動画でメタデータが利用可能になります。
## IAM アクセス許可のセットアップ
**前提条件:** [IVS 低レイテンシーストリーミングを開始する](getting-started.md)（IAM ユーザーの作成とアクセス許可の設定を含む）の手順を実行しておく必要があります。
次に、時間指定メタデータを使用するアクセス許可を IAM ユーザーに付与する必要があります。以下のステップに従ってください。
1. AWS マネジメントコンソールにサインインして、IAM コンソールを開きます。[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/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) を開始する を実行した際に CLI を取得していなかった場合は、今すぐ取得してください。詳細については、[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 Broadcast SDK の使用
IVS Broadcast SDK を使用して時間指定メタデータを帯域内に挿入できます。これは、メタデータをオーディオおよびビデオコンテンツと同期させるのに便利な場合があります。
+ Android — `BroadcastSession` クラスでは、`sendTimedMetadata` を使用してください。
+ iOS — `IVSBroadcastSession` クラスでは、`sendTimedMetadata` を使用してください。
## 時間指定メタデータの使用
Amazon IVS Player を使用して、動画ストリームに埋め込まれた時間指定メタデータを使用します。[IVS プレーヤー SDK](player.md) およびその他のプレイヤードキュメントを参照してください。
以下は、Amazon IVS Player SDK を使用してコンソールに受信したメタデータを印刷する例です。再生が、メタデータが埋め込まれたセグメントに到達すると、イベントがトリガーされます。(イベントは、ウェブ用が `TEXT_METADATA_CUE`、Android 用が `onCue()`、iOS 用が `player(_:didOutputCue:)` です)。このイベントを使用して、インタラクティブウィジェットの更新など、クライアントアプリケーション内の機能を開始できます。このイベントは、ライブコンテンツと録画コンテンツの両方に対してトリガーされます。
**Amazon IVS Player SDK for Web:**
```
const player = IVSPlayer.create();
player.addEventListener(IVSPlayer.PlayerEventType.TEXT_METADATA_CUE,
function (cue) {
console.log('Timed metadata: ', cue.text);
});
```
**Amazon IVS Player SDK for Android:**
```
@Override
public void onCue(@NonNull Cue cue) {
if(cue instanceof TextMetadataCue) {
Log.i("Timed Metadata: ", ((TextMetadataCue)cue).text);
}
}
```
**Amazon IVS Player SDK for iOS:**
```
func player(_ player: IVSPlayer, didOutputCue cue: IVSCue) {
if let textMetadataCue = cue as? IVSTextMetadataCue {
print("Timed Metadata: \(textMetadataCue.text)")
}
}
```
**注:** 時間指定メタデータは、Player 1.3.0 以降の iOS Safari および iOS Chrome でサポートされています。
### SEI データの消費
個々の参加者の記録を有効にして IVS リアルタイムステージを記録すると、SEI (補足拡張情報) ペイロードが保持され、`IVSPlayer.PlayerEventType.SEI` イベントとして公開されます。以下は、IVS ウェブプレイヤー 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 Broadcast SDK ガイド*」の「[補足拡張情報 (SEI)](https://docs.aws.amazon.com/ivs/latest/RealTimeUserGuide/web-publish-subscribe.html#web-publish-subscribe-sei-attributes)」を参照してください。
### サンプルデモ: クイズアプリ
インタラクティブなクイズアプリのコード例は、GitHub で入手できます。時間指定メタデータを介して JSON を使用し、クイズ UI を設定して質問と回答を表示します。回答は選択可能であり、選択が正しいかどうかが表示されます。
| Amazon IVS Player SDK プラットフォーム | サンプルのリポジトリ |
| --- | --- |
| 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. ストリームを表示するチャネルを選択し、そのチャネルの詳細ページに移動します。
ライブストリームは、詳細ページの**ライブストリーム**セクションで再生されています。
1. ウィンドウの下部にある [**Timed Metadata (時間指定メタデータ)**] を選択します。
プレイヤーの再生中に各時間指定メタデータイベントを受信すると、その値と受信時間が表示されます。
## 追加情報
Amazon IVS の時間指定メタデータの使用に関する 2 部構成のブログシリーズの最初の部分である、[Using Amazon Interactive Video Service Timed Metadata](https://aws.amazon.com/blogs/media/part-1-using-amazon-interactive-video-service-timed-metadata/) を参照してください。