기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 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) 및 [ListTagsForStream](API_ListTagsForStream.md)와(과) 함께 실행되는 스트림 수준 태깅 API와는 구별됩니다.

### 스트리밍 메타데이터 API
<a name="how-meta-api"></a>

생산자 SDK에서 다음 작업을 사용하여 스트리밍 메타데이터를 구현할 수 있습니다.

**Topics**
+ [PIC](#how-meta-api-pic)
+ [C\$1\$1 생산자 SDK](#how-meta-api-cpp)
+ [Java 생산자 SDK](#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\$1\$1 생산자 SDK
<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 생산자 SDK
<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>

비지속성 메타데이터의 경우, 여러 메타데이터 항목을 동일한 *이름*으로 추가할 수 있습니다. 생산자 SDK는 메타데이터 항목이 다음 조각 앞에 추가될 때까지 메타데이터 대기열에서 메타데이터 항목을 수집합니다. 메타데이터 항목이 스트림에 적용됨에 따라 메타데이터 대기열은 삭제됩니다. 메타데이터를 반복하려면 `putKinesisVideoFragmentMetadata` 또는 `putFragmentMetadata`를 다시 호출합니다.

영구 메타데이터의 경우 생산자 SDK는 비영구 메타데이터와 동일한 방식으로 메타데이터 대기열에 메타데이터 항목을 수집합니다. 그러나 메타데이터 항목은 다음 조각 앞에 추가될 때 대기열에서 제거되지 않습니다.

`true`로 설정된 `persistent`로 `putKinesisVideoFragmentMetadata` 또는 `putFragmentMetadata`를 호출하면 다음과 같은 동작으로 이어집니다.
+ API를 호출하면 메타데이터 항목을 대기열로 가져갑니다. 메타데이터는 해당 항목이 대기열에 있는 동안 MKV 태그로 모든 조각에 추가됩니다.
+ 같은 *이름*과 다른 *값*으로 API를 이전에 추가된 메타데이터 항목으로서 호출하면 해당 항목을 덮어쓰기합니다.
+ API를 비어 있는 *값*으로 호출하면 메타데이터 대기열에서 메타데이터 항목을 제거(취소)합니다.