Live Screenshot

라이브 스트림에서 정지 이미지 스냅샷을 캡처하여 오브젝트 스토리지로 바로 전달할 수 있습니다 — 일정에 따라, 모든 스트림마다 혹은 필요할 때마다 가능합니다. Live Screenshot API는 비디오 썸네일, 라이브 미리보기, 콘텐츠 모더레이션 샘플링, 규정 준수 아카이빙과 같은 일반적인 워크플로우를 지원합니다.

API는 세 가지로 조합 가능한 계층으로 구성되어 있습니다:

1. Templates — 스크린샷이 어떻게 캡처되는지 정의합니다 — 포맷, 스토리지, 세그먼트, 콜백 등.
2. Rules — 캡처가 언제 발생할지 정의합니다 — 템플릿을 Domain, 앱 또는 스트림에 바인딩합니다.
3. Real-Time Controls — 활성화된 어떤 스트림에서든 임시로 캡처를 트리거합니다.

템플릿은 기반입니다. Rules와 Real-Time Controls는 모두 templateId로 템플릿을 참조하므로, 최초의 API 호출은 항상 템플릿을 생성하는 것이 됩니다.

모든 스크린샷 API는 5분당 사용자별 300회 요청의 공통 Rate Limit이 적용됩니다.

스크린샷 템플릿 생성(템플릿 API)

스크린샷 파라미터 템플릿은 캡처가 어떻게 동작할지 정의합니다: 출력 이미지 형식(JPG, PNG, BMP), 샘플링 간격, Object Storage 저장 위치, 파일명 지정 규칙, 그리고 완료 알림을 받을 콜백 URL 등이 이에 포함됩니다.

모든 스크린샷(자동/수동) 요청에는 templateId가 반드시 필요하므로, 템플릿 생성이 항상 첫 번째 단계가 됩니다.

경고: 현재 활성화된 규칙에서 참조되고 있는 템플릿은 삭제할 수 없습니다. 모든 규칙에서 해당 템플릿을 제거한 후 삭제해 주세요.

자동 스크린샷 규칙 설정 (Rule API)

템플릿이 생성되면, 스크린샷 규칙을 통해 자동으로 적용됩니다. 규칙은 하나 이상의 라이브 스트림에 templateId를 연결하여, 해당 스트림이 시작되면 별도의 조작 없이 자동으로 캡처가 시작됩니다.

Stream은 세 가지 수준의 구체성으로 지정할 수 있습니다:

• Delivery Domain — 해당 Domain 내의 모든 Stream에 적용됩니다.
• Application Name — 특정 Application Path의 모든 Stream에 적용됩니다.
• Stream Name — 특정 Stream에만 적용됩니다.

시스템은 Longest Match 원칙에 따라 규칙을 적용합니다. 즉, 특정 Stream Name을 대상으로 하는 규칙이 Domain 수준의 더 넓은 규칙보다 우선순위를 갖습니다. 이를 통해 전체에 적용되는 기본 규칙을 설정하되, 필요시 개별 Stream에 대해 동작을 변경할 수 있습니다.

경고: 규칙이 현재 스크린샷 캡처 중일 때는 삭제할 수 없습니다. 스트림 종료를 기다리거나 먼저 캡처 세션을 중지하세요.

실시간 요청 스크린샷 트리거 (Real-Time Control API)

자동화된 규칙 외의 캡처 — 운영 중 이벤트, 사용자가 직접 트리거한 미리 보기, 인시던트 아카이빙 등 — 는 Real-Time Control API로 수동 세션 시작 및 종료가 가능합니다.

워크플로우 연결 방식:

1. templateId와 최대 5개의 스트림 전송 URL을 사용하여 StartRealTimeSnapshot를 호출합니다.
2. API는 해당 캡처 세션을 고유하게 식별하는 persistentId를 반환합니다.
3. 캡처는 스트림이 자연스럽게 종료될 때까지 또는 동일한 persistentId로 StopRealTimeRecord를 호출할 때까지 계속됩니다.

항상 Start API에서 반환되는 persistentId를 저장하십시오. 해당 세션을 조기에 종료할 수 있는 유일한 방법입니다. 이를 분실하면 스트림이 자동으로 종료될 때까지 기다려야 합니다.