56. (Aws/Amazon) [Aws Kinesis Video Streams] Aws KVS PutMedia 비디오 스트림 전송 API 설명 정리

---

[개발 환경 설정]

​

개발 환경 : Aws / Amazon Web Services

​

 

---

[설명 정리]

​

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

- 인프라 : Aws / Amazon Web Services

- 기술 구분 : Aws / Kinesis Video Streams / KVS / 비디오 스트림

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






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

1. Aws KVS 비디오 스트림 설명 : 

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


  >> 비디오 스트림에 데이터를 저장하도록 선택하면 Kinesis Video Streams가 데이터를 암호화하고 저장된 데이터에 시간 기반 인덱스를 생성합니다


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


  >> Kinesis 비디오 스트림은 비디오 스트림의 콘텐츠를 처리하는 여러 소비 애플리케이션을 가질 수 있습니다




2. Aws PutMedia 설명 : 

  >> PutMedia API 를 사용하여 미디어 데이터를 Kinesis 비디오 스트림으로 전송합니다

    - 먼저 GetDataEndpointAPI 를 호출하여 엔드포인트를 가져와야 합니다 (Credential EndPoint)

    - 가져온 엔드포인트 정보를 사용해 PutMedia API 호출 시 사용합니다

    - GetDataEndpointAPI 를 호출하여 엔드포인트 정보를 가져오기 위해서는 IAM 계정에 할당 된 AccessKey , SecretKey 정보가 필요합니다


  >> PutMedia API 를 사용하여 데이터를 전송 옵션

    - 실시간으로 미디어 데이터 전송 (카메라는 프레임을 생성하는 동시에 실시간으로 전송할 수 있습니다. 이러한 방식은 비디오 녹화와 유선으로 전송되는 데이터 사이의 지연 시간을 최소화합니다.)

    - 미디어 데이터를 오프라인으로 일괄 전송 (바디캠은 몇 시간 동안 영상을 녹화하여 기기에 저장할 수 있습니다. 나중에 카메라를 도킹 포트에 연결하면 카메라가 PutMedia 세션을 시작하여 Kinesis 비디오 스트림으로 데이터를 전송할 수 있습니다.)


  >> PutMedia API 를 사용 시 고려 사항

    - streamName 또는 streamARN 둘 중 하나만 지정해야 하며 둘 다 지정할 수는 없습니다.

    - 콘솔이나 HLS 를 통해 미디어를 재생하려면 각 프래그먼트의 트랙 1에 h.264로 인코딩된 비디오가 포함되어야합니다

    - 프래그먼트 메타데이터의 CodecID 는 "V_MPEG/ISO/AVC" 여야 하며, 프래그먼트 메타데이터에는 AVCC 형식의 h.264 코덱 개인 데이터가 포함되어야 합니다

    - PutMediaAPI 를 사용할 때는 HTTP 청크 전송 인코딩을 사용하여 지속 연결을 통해 프래그먼트를 지속적으로 전송하십시오


  >> PutMedia API 를 사용 시 제한 사항

    - 클라이언트는 PutMedia 스트림당 초당 최대 5번을 호출할 수 있습니다.

    - 클라이언트는 스트림당 초당 최대 5개의 조각을 보낼 수 있습니다.

    - Kinesis Video Streams 는 세션 중 최대 12.5MB/초 또는 100 Mbps 의 속도로 미디어 데이터를 읽습니다 


  >> PutMedia API 사용 요청 구문 예시 

    POST /putMedia HTTP/1.1  ------------->  GetDataEndpointAPI 를 호출하여 얻은 엔드포인트 주소 (Credential EndPoint)

    x-amzn-stream-name: StreamName  -------------->  HTTP 헤더로 전달합니다 (Kinesis 비디오 스트림의 이름)
    x-amzn-stream-arn: StreamARN  -------------->  HTTP 헤더로 전달합니다 (Kinesis 비디오 스트림의 Amazon 리소스 이름(ARN))
    x-amzn-fragment-timecode-type: FragmentTimecodeType  -------------->  HTTP 헤더로 전달합니다 (수신된 조각 계산 / ABSOLUTE | RELATIVE)
    x-amzn-producer-start-timestamp: ProducerStartTimestamp  -------------->  HTTP 헤더로 전달합니다 (미디어를 녹화하기 시작한 프로듀서 타임스탬프)

    Payload  -------------->  Kinesis 비디오 스트림에 기록할 미디어 콘텐츠 전송


  >> PutMedia API 에러 응답 코드 정리

    - HTTP 상태 코드 : 400 - 클라이언트 제한 초과 예외 : 허용된 클라이언트 호출 한도를 초과하여 Kinesis Video Streams에서 요청을 제한했습니다. 나중에 호출해 보세요.

    - HTTP 상태 코드 : 400 - 연결 제한 초과 예외 : 허용된 클라이언트 연결 한도를 초과했기 때문에 Kinesis Video Streams에서 요청이 제한되었습니다.

    - HTTP 상태 코드 : 400 - InvalidArgumentException : 입력 매개변수의 값이 잘못되었습니다.

    - HTTP 상태 코드 : 400 - InvalidEndpointException : 호출자가 잘못된 엔드포인트를 사용하여 스트림에 데이터를 썼습니다. 이러한 예외가 발생하면 사용자는 GetDataEndpoint로 APIName설정된 엔드포인트를 호출 PUT_MEDIA하고 응답의 엔드포인트를 사용하여 다음 PutMedia호출을 실행해야 합니다.

    - HTTP 상태 코드 : 401 - 권한이 없음 예외 : 호출자가 주어진 스트림에서 작업을 수행할 권한이 없거나 토큰이 만료되었습니다.

    - HTTP 상태 코드 : 404 - 리소스가 발견되지 않음 : 상태 코드: 404, 해당 이름의 스트림이 존재하지 않습니다.


  >> PutMedia API AckEventType, Error 필드 오류 정리

    - 4000 - STREAM_READ_ERROR - 데이터 스트림을 읽는 중 오류가 발생했습니다.

    - 4001 - MAX_FRAGMENT_SIZE_REACHED - 조각 크기가 허용되는 최대 한도인 50MB보다 큽니다.

    - 4002 - MAX_FRAGMENT_DURATION_REACHED - 조각 지속 시간이 허용된 최대 한도보다 깁니다.

    - 4003 - MAX_CONNECTION_DURATION_REACHED - 연결 기간이 허용되는 최대 임계값보다 큽니다.

    - 4004 - FRAGMENT_TIMECODE_LESSER_THAN_PREVIOUS - 프래그먼트 타임코드가 이전 타임코드보다 작습니다( PutMedia호출 내에서 프래그먼트를 순서 없이 보낼 수 없습니다).

    - 4005 - MORE_THAN_ALLOWED_TRACKS_FOUND - MKV에서 두 개 이상의 트랙이 발견되었습니다. (더 이상 사용되지 않음)

    - 4006 - INVALID_MKV_DATA - 입력 스트림을 유효한 MKV 형식으로 구문 분석하는 데 실패했습니다.

    - 4007 - INVALID_PRODUCER_TIMESTAMP - 잘못된 프로듀서 타임스탬프입니다.

    - 4008 - STREAM_NOT_ACTIVE - 스트림이 더 이상 존재하지 않습니다(삭제됨).

    - 4009 - FRAGMENT_METADATA_LIMIT_REACHED - 조각 메타데이터 제한에 도달했습니다. 개발자 가이드의 제한 섹션을 참조하세요.

    - 4010 - TRACK_NUMBER_MISMATCH - MKV 프레임의 트랙 번호가 MKV 헤더의 트랙과 일치하지 않습니다.

    - 4011 - FRAMES_MISSING_FOR_TRACK - 해당 조각에는 MKV 헤더의 트랙 중 하나 이상에 대한 프레임이 포함되어 있지 않습니다.

    - 4012 - INVALID_FRAGMENT_METADATA - 조각 메타데이터 이름은 문자열로 시작할 수 없습니다 AWS_.

    - 4500 - KMS_KEY_ACCESS_DENIED - 스트림의 지정된 KMS 키에 대한 액세스가 거부되었습니다.

    - 4501 - KMS_KEY_DISABLED - 스트림의 지정된 KMS 키가 비활성화되었습니다.

    - 4502 - KMS_KEY_VALIDATION_ERROR - 스트림의 지정된 KMS 키가 유효성 검사에 실패했습니다.

    - 4503 - KMS_KEY_UNAVAILABLE - 스트림의 지정된 KMS 키를 사용할 수 없습니다.

    - 4504 - KMS_KEY_INVALID_USAGE - 스트림에 지정된 KMS 키가 잘못 사용되었습니다.

    - 4505 - KMS_KEY_INVALID_STATE - 스트림의 지정된 KMS 키가 잘못된 상태입니다.

    - 4506 - KMS_KEY_NOT_FOUND - 스트림의 지정된 KMS 키를 찾을 수 없습니다.

    - 5000 - INTERNAL_ERROR - 내부 서비스 오류.

    - 5001 - ARCHIVAL_ERROR - Kinesis 비디오 스트림이 데이터 저장소에 조각을 유지하지 못했습니다.

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






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

[Aws PutMedia 설명]

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


[임시 보안 자격 증명 요청]

https://docs.aws.amazon.com/ko_kr/IAM/latest/UserGuide/id_credentials_temp_request.html


[kvs (Kinesis Video Streams) , HLS (HTTP 라이브 스트리밍) 설명 및 정리]

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


[AWS 사이트 주요 질문 정리 사이트]

https://aws.amazon.com/ko/kinesis/video-streams/faqs/

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

 

---

[참고 사이트]

​

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

PutMedia - Amazon Kinesis Video Streams

---