201. (Aws/Amazon) [Aws Kinesis Video Streams] GetClip API 설명 정리 - KVS 영상 중 특정 시간 범위 잘라서 MP4 파일로 저장

---

[개발 환경 설정]

​

개발 환경 : Aws / Amazon Web Services

​

제 목 : [Aws Kinesis Video Streams] GetClip API 설명 정리 - KVS 영상 중 특정 시간 범위 잘라서 MP4 파일로 저장

​

 

---

[설명 정리]

​

// --------------------------------------------------------------------------------------
[개발 및 환경]
// --------------------------------------------------------------------------------------

- 인프라 : Aws / Amazon Web Services


- 기술 구분 : Aws / Aws Kinesis Video Streams / HLS / GetClip


- 사전) 👉 비디오 스트림 간략 설명 정리 : 

  >> 비디오 스트림은 라이브 비디오 및 기타 시간이 인코딩된 데이터를 캡처하고, 선택적으로 저장하고, 실시간, 배치 혹은 애드혹 형식으로 데이터의 소비를 가능하게 할 수 있도록 해 주는 리소스입니다

  >> 일반적인 구성에서는 Kinesis 비디오 스트림은 데이터를 푸시해 주는 생산자가 하나만 있습니다 (실시간 스트리밍 데이터를 밀어 넣어주는 하드웨어 기기)


- 사전) 👉 HLS 개념 설명 : 

  >> HTTP 라이브 스트리밍으로 인터넷을 통해 소비자에게 미디어 콘텐츠를 제공하는 데 사용되는 스트리밍 프로토콜입니다

  >> HLS 는 Apple 장치에서 지원하는 유일한 형식입니다

  >> 미디어는 h.264 또는 h.265 인코딩된 비디오를 포함해야 하며 AAC 인코딩된 오디오는 선택 사항입니다

  >> 미디어 타입 유효한 값의 예로는 "video/h264" 및 "video/h264,audio/aac" 가 있습니다

// --------------------------------------------------------------------------------------






// --------------------------------------------------------------------------------------
[설 명] 
// --------------------------------------------------------------------------------------

1. ✅ GetClip API 는 Kinesis Video Streams (KVS) 에 저장 (아카이브) 된 영상 중, 특정 시간 범위를 잘라 MP4 파일로 내려받는 API 입니다.


2. GetClip API 간단 Request , Response 예시 : 

  >> HLS 로 “재생” 하던 영상과 동일한 소스 스트림에서 👉 원하는 시간 구간만 클립(MP4) 형태로 추출할 수 있습니다.

  >> 입력 :

    - 스트림 이름 또는 ARN
    - 시작/종료 타임스탬프

  >> 출력 :

    - 표준 MP4 파일(binary payload)


3. ✅ HLS 스트리밍과 GetClip 의 관계 정리

----------------------------------------------------------------------------
항목       |      HLS (GetHLSStreamingSessionURL)     |      GetClip
----------------------------------------------------------------------------
목적       |          실시간/재생용 스트리밍            |     파일 추출
----------------------------------------------------------------------------
결과물     |           m3u8 + ts fragment              |    MP4 단일 파일
----------------------------------------------------------------------------
사용 시점  |         브라우저 / 플레이어 재생            |  S3 저장, 백업, 증적
----------------------------------------------------------------------------
데이터 소스 |          동일한 KVS 아카이브               |       동일
----------------------------------------------------------------------------

카메라 → Kinesis Video Stream
          ├─ GetHLSStreamingSessionURL (시청)
          └─ GetClip (MP4 파일 추출 → S3 업로드)


5. ✅ GetClip API 호출 제약 조건 정리 : 

  >> GetClip API 를 호출하기 위해서는 GetDataEndpoint 호출 (필수) 이 필요합니다.

    - 반환된 endpoint에 대해 GetClip을 호출해야 합니다.

  >> GetClip 은 HLS 보다 엄격한 제약이 있습니다.

  >> 스트림 조건 :

    - 보존 기간(DataRetentionInHours) > 0
    - 비디오 : H.264 (AVC) 또는 H.265 (HEVC)
    - 오디오 : AAC 또는 G.711
    - Clip 전체 구간 동안 코덱/트랙 구성 불변
    - 중간에 해상도/프레임/오디오 타입 변경 ❌


6. GetClip API 호출 Request 전문 : 

  POST /getClip HTTP/1.1
  Content-type: application/json

  {
    "ClipFragmentSelector": { 
        "FragmentSelectorType": "string", // "SERVER_TIMESTAMP" || PRODUCER_TIMESTAMP
        "TimestampRange": { // 👉 원하는 영상 구간
          "EndTimestamp": number, // 1700000000
          "StartTimestamp": number // 1700000300
        }
    },
    "StreamARN": "string", // 👉 StreamARN | StreamName 둘 중 하나는 반드시 필요
    "StreamName": "string" // 👉 StreamARN | StreamName 둘 중 하나는 반드시 필요
  }


6. GetClip API 호출 Response 전문 : 

  HTTP/1.1 200
  Content-Type: ContentType

  Body: MP4 바이너리 데이터
  Header:

  Content-Type: video/mp4

  ⚠️ 제한 사항 : 최대 100MB 또는 200 fragments 까지만 반환


7. ✅ HLS → GetClip → S3 활용 시나리오

  >> 관제 시스템에서 이벤트 발생 시점 ±30초 영상 저장

  >> 사용자 신고 → 해당 구간 영상 MP4로 S3 보관

    - GetClip 호출
    - 응답 Payload(바이너리 스트림) 수신
    - 그대로 S3 PutObject Body에 전달
    - Content-Type: video/mp4 설정

  >> 법적 증빙, 감사 로그용 영상 백업

  >> ML 후 처리용 영상 추출


8. ✅ 간략 ListFragments 및 GetClip 사용 흐름 예시 첨부

[디바이스(Camera)]
    └─ PutMedia →
        [Kinesis Video Streams]
            ├─ (실시간 재생) → HLS
            ├─ (이벤트 발생) → Lambda 트리거
            │        ├─ ListFragments (검증)
            │        ├─ GetClip (영상 추출)
            │        └─ S3 업로드
            └─ 저장 (fragment)

// --------------------------------------------------------------------------------------






// --------------------------------------------------------------------------------------
[참고 사이트]
// --------------------------------------------------------------------------------------

▶️ 143. (TWOK/LOGIC) [android] Aws Kvs HLS PutMedia 스트리밍 동영상 업로드 로직 정리 - DataEndpoint, MKV , AWS4Signer

https://kkh0977.tistory.com/8013

https://blog.naver.com/kkh0977/223875616765?trackingCode=blog_bloghome_searchlist


▶️ 145. (TWOK/LOGIC) [Aws] Aws Kvs HLS 디바이스 카메라 라이브 스트리밍 정보 PutMedia 업로드 방법 로직 정리

https://kkh0977.tistory.com/8086

https://blog.naver.com/kkh0977/223911555706?trackingCode=blog_bloghome_searchlist


▶️ 146. (TWOK/LOGIC) [Aws] Kvs HLS 라이브 스트리밍 로컬 PC에서 업로드 하기 위한 프로세스 로직 정리 - aws , ffmpeg , gstreamer 사용

https://kkh0977.tistory.com/8099

https://blog.naver.com/kkh0977/223918332596?trackingCode=blog_bloghome_searchlist


▶️ 147. (TWOK/LOGIC) [android] 안드로이드 휴대폰 실시간 카메라 스트림 영상을 마스터 역할로 Aws Kvs HLS 라이브 스트리밍 업로드 로직 정리

https://kkh0977.tistory.com/8250

https://blog.naver.com/kkh0977/223996783911?trackingCode=blog_bloghome_searchlist


▶️ 153. (TWOK/LOGIC) [Aws] 자바스크립트 Aws Kvs HLS 비디오 라이브 스트리밍 뷰어 Viewer 영상 재생 방법 정리

https://kkh0977.tistory.com/8405

https://blog.naver.com/kkh0977/224079078341?trackingCode=blog_bloghome_searchlist


▶️ AWS : GetClip 설명

https://docs.aws.amazon.com/ko_kr/kinesisvideostreams/latest/dg/API_reader_GetClip.html

// --------------------------------------------------------------------------------------

 

---

[참고 사이트]

​

https://kkh0977.tistory.com/8013

143. (TWOK/LOGIC) [android] Aws Kvs HLS PutMedia 스트리밍 동영상 업로드 로직 정리 - DataEndpoint, MKV , AWS4Signer

---