202. (Aws/Amazon) [Aws Kinesis Video Streams] ListFragments API 설명 정리 - KVS에 저장된 영상 조각 (fragment) 조회

---

[개발 환경 설정]

​

개발 환경 : Aws / Amazon Web Services

​

제 목 : [Aws Kinesis Video Streams] ListFragments API 설명 정리 - KVS에 저장된 영상 조각 (fragment) 조회

​

 

---

[설명 정리]

​

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

- 인프라 : Aws / Amazon Web Services


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


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

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

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


- 사전) 👉 HLS 개념 설명 : 

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

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

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

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

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






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

1. ✅ ListFragments API 는 KVS 에 저장된 영상을 “구성하는 조각 (fragment)” 목록을 조회하는 API 입니다.

  >> 특정 스트림 , 특정 시간 범위 에 대해 👉 Fragment 메타 데이터 리스트만 반환합니다.

  >> 👉 ListFragments 는 HLS 에서 보이는 영상의 “원본 조각 인덱스”를 제공한다고 보면 됩니다.
  
  >> ListFragments 과 GetClip 비교

    - GetClip : 영상 파일 추출
    - ListFragments : 영상 조각 목록 조회 역할


2. Fragment 설명 정리 : 

  >> KVS 에서 영상은 하나의 파일이 아니라 연속된 Fragment (조각) 형태로 저장됩니다.

    - 👉 쉽게 말하면 : [Fragment1] [Fragment2] [Fragment3] ... 이걸 모아서 HLS → 재생

  >> Fragment 객체에는 아래와 같은 정보가 있습니다 :

    - FragmentNumber : 조각 ID
    - ProducerTimestamp : 카메라 기준 시간
    - ServerTimestamp : AWS 수신 시간
    - FragmentLengthInMilliseconds : 길이
    - FragmentSizeInBytes : 크기


3. ✅ ListFragments 의 역할 : 

  >> 특정 시간 구간의 fragment 목록 조회 : 

    - 이 시간에 영상이 있는지 확인
    - fragment 개수 확인

  >> 실제 영상 추출 전 사전 탐색 : 

    - GetClip 호출 전에 범위 검증
    - 또는 fragment 단위 처리

  >> GetMediaForFragmentList 와 연동 : 

    - fragment 번호 리스트 → 실제 영상 데이터 가져오기


4. ✅ ListFragments API 호출 제약 조건 정리 : 

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

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

  >> ListFragments 는 즉시 일관성 보장을 안합니다.

    - fragment 가 저장됐다고 해도 바로 조회 안 될 수 있음
    - 하지만, 일반적으로 1초 내 조회 가능


5. ListFragments API 호출 Request 전문 :

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

  {
    "FragmentSelector": { 
        "FragmentSelectorType": "string", // "SERVER_TIMESTAMP" || PRODUCER_TIMESTAMP
        "TimestampRange": { // 👉 시작 ~ 종료 시간 범위 : 해당 범위에 포함된 fragment 만 반환
          "EndTimestamp": number,
          "StartTimestamp": number
        }
    },
    "MaxResults": number, // 한번에 가져올 fragment 수 : 기본 100, 최대 1000
    "NextToken": "string", // fragment가 많으면 여러 번 호출 필요 : 이전 호출 결과의 NextToken 사용
    "StreamARN": "string", // 👉 StreamARN | StreamName 둘 중 하나는 반드시 필요
    "StreamName": "string" // 👉 StreamARN | StreamName 둘 중 하나는 반드시 필요
  }


6. ListFragments API 호출 Response 전문 :

  HTTP/1.1 200
  Content-type: application/json

  {
    "Fragments": [ 
        { 
          "FragmentLengthInMilliseconds": number,
          "FragmentNumber": "string",
          "FragmentSizeInBytes": number,
          "ProducerTimestamp": number,
          "ServerTimestamp": number
        }
    ],
    "NextToken": "string"
  }


7. ListFragments 가 사용 되는 케이스 정리 : 

  >> 특정 시간에 영상이 존재하는지 확인

  >> 영상 길이나 fragment 수 확인

  >> 비용 최적화 (GetClip 호출 전에 필터)

  >> fragment 기반 처리 (AI, 분석, 분할 업로드)


8. ✅ GetClip vs ListFragments 요약 정리

----------------------------------------------------------------
항목       |       ListFragments       |      GetClip
----------------------------------------------------------------
역할       |    fragment 목록 조회      |   MP4 클립 추출
----------------------------------------------------------------
반환       |      metadata(JSON)       |    바이너리 MP4
----------------------------------------------------------------
데이터     |      없음 (메타데이터만)    |     실제 영상
----------------------------------------------------------------
사용 시점  |          사전 탐색         |      결과 생성
----------------------------------------------------------------
S3 업로드  |           직접 X           |    App에서 업로드
----------------------------------------------------------------


9. ✅ 간략 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 : ListFragments 설명

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

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

 

---

[참고 사이트]

​

https://kkh0977.tistory.com/8086

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

---