# 비디오 스트림에 메타데이터를 포함하기
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 Management Console에 로그인하여 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)에서 IAM 콘솔을 엽니다.
1. [정책 생성] **창에서 [정책 검토]**]를 선택합니다. 정책에 [이름]을 지정한 후 [정책 생성]을 선택합니다.
1. 해당 사용자 [**요약**] 창의 [**권한**] 탭에서 오른쪽의 [**인라인 정책 추가**]를 선택합니다.
1. [**JSON**] 탭에서 다음 BLOB에 붙여넣습니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ivs:PutMetadata"
],
"Resource": "arn:aws:ivs:*:*:channel/*"
}
]
}
```
------
1. [**정책 생성**] 창에서 [**정책 검토**]를 선택합니다. 정책에 [**이름**]을 지정한 후 [**정책 생성**]을 선택합니다.
1. 새 정책 이름이 표시되는 사용자 [**요약**] 창으로 돌아갑니다.
## 시한 메타데이터 삽입
지정된 채널의 활성 스트림에만 시한 메타데이터를 삽입할 수 있습니다.
### 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 Broadcast SDK 사용
IVS Broadcast SDK를 사용하여 대역 내에서 시한 메타데이터를 삽입할 수 있습니다. 이는 메타데이터를 오디오 및 비디오 콘텐츠와 동기화하는 데 유용할 수 있습니다.
+ Android - `BroadcastSession` 클래스에서 `sendTimedMetadata`를 사용합니다.
+ iOS - `IVSBroadcastSession` 클래스에서 `sendTimedMetadata`를 사용합니다.
## 시한 메타데이터 사용
Amazon IVS 플레이어를 사용하여 비디오 스트림에 포함된 시한 메타데이터를 사용합니다. [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)")
}
}
```
**참고:** 시한 메타데이터는 iOS Safari 및 iOS Chrome의 플레이어 1.3.0 이상에서 지원됩니다.
### 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 플랫폼 | 샘플 리포지토리 |
| --- | --- |
| 웹 | [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. 왼쪽 상단에서 햄버거 아이콘을 선택하여 탐색 창을 연 다음 [**라이브 채널**]을 선택합니다.
1. 스트림을 보려는 채널을 선택하여 해당 채널의 세부 정보 페이지로 이동합니다.
라이브 스트림이 페이지의 [**라이브 스트림**] 섹션에서 재생됩니다.
1. 창 하단에서 [**시한 메타데이터**]를 선택합니다.
플레이어가 재생 중인 동안 개별 시한 메타데이터 이벤트가 수신되면 해당 값과 수신된 시간이 표시됩니다.
## 자세한 정보
Amazon IVS 시한 메타데이터 사용에 대해 두 부분으로 구성된 블로그 시리즈 중 첫 번째인 [Amazon Interactive Video Service 시한 메타데이터 사용](https://aws.amazon.com/blogs/media/part-1-using-amazon-interactive-video-service-timed-metadata/)을 참조하세요.