Notice
Recent Posts
Recent Comments
Link
투케이2K
56. (Aws/Amazon) [Aws Kinesis Video Streams] Aws KVS PutMedia 비디오 스트림 전송 API 설명 정리 본문
Aws (Amazon)
56. (Aws/Amazon) [Aws Kinesis Video Streams] Aws KVS PutMedia 비디오 스트림 전송 API 설명 정리
투케이2K 2025. 5. 6. 12:42[개발 환경 설정]
개발 환경 : 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/
// --------------------------------------------------------------------------------------
반응형
'Aws (Amazon)' 카테고리의 다른 글
Comments