Backend2025-05-016분 읽기

Agora Cloud Recording REST API — 녹화 수명주기와 저장소 설정

Cloud Recording의 non-streaming client가 RTC channel에 참여해 media를 기록하는 방식과 `acquire → start → query → stop` 수명주기를 설명합니다. REST 인증과 RTC token을 구분하고, individual·composite·web page recording mode, object storage 설정, resource 만료와 stop 처리를 구현 예제로 다룹니다.

Cloud RecordingREST APICSPAWS S3

목차(9개 항목)

Cloud Recording이란?
브라우저 녹화와 무엇이 다른가?
어떻게 동작하는가?
Agora Cloud Recording의 장단점
시작하기
시작하기
1. REST API 호출 예시
참고 문서
관련 글
참고 자료

Agora Cloud Recording을 사용하면 실시간 스트림을 서버 측에서 자동으로 녹화해 클라우드 저장소에 저장할 수 있습니다.

Cloud Recording이란?

Cloud Recording은 Agora 채널의 음성·영상 스트림을 서버에서 녹화하고, AWS S3·Azure·Google Cloud·Alibaba·Tencent·Baidu·Huawei 또는 S3 호환 스토리지에 저장하는 기능입니다. 애플리케이션 서버는 REST API로 녹화를 시작·업데이트·중지·조회합니다.

브라우저 녹화와 무엇이 다른가?

브라우저에서도 MediaRecorder로 녹화할 수 있지만, 서버 녹화와 운영 특성이 다릅니다.

클라이언트 연산: 브라우저에서 다자간 화면을 합성하고 인코딩하면 참가자 기기의 CPU·메모리·배터리를 사용합니다.
수명 주기: 탭이나 앱이 종료되면 클라이언트 녹화도 끝납니다. MediaRecorder.start(timeslice)나 requestData()로 청크를 주기적으로 내보내 저장할 수 있으므로, 모든 데이터가 반드시 메모리에서 유실되는 것은 아닙니다.
운영 부담: 자체 SFU/MCU에서 녹화하려면 구독, 합성, 인코딩, 저장, 장애 복구 파이프라인을 운영해야 합니다.

어떻게 동작하는가?

Cloud Recording 서비스는 비송출 클라이언트처럼 채널에 참여해 설정한 스트림을 구독합니다. mix 모드는 여러 스트림을 합성하고, individual 모드는 사용자별 스트림을 분리하며, web 모드는 지정한 웹페이지를 렌더링해 녹화합니다. 기본 산출물은 HLS(.m3u8와 세그먼트)이고, mix·web 모드에서 recordingFileConfig.avFileType을 ['hls', 'mp4']로 설정하면 MP4도 생성할 수 있습니다.

         [화상 채널 (SD-RTN)]
   User A ──┐                ┌── User B
            │                │
            ▼                ▼
   ┌──────────────────────────────┐
   │   Agora SD-RTN (미디어 라우팅) │
   └──────────────┬───────────────┘
                  │  (모든 오디오/비디오 스트림 구독)
                  ▼
   ┌──────────────────────────────┐
   │  Recording Server            │   ← 비송출 클라이언트처럼 join
   │  (설정한 스트림 구독)          │      녹화 연산은 서버에서 수행
   │                              │
   │  mix      → 갤러리 1개 트랙   │
   │  individual → 화자별 트랙     │
   │  web      → 헤드리스 브라우저 │
   └──────────────┬───────────────┘
                  │  REST: acquire → start → stop
                  ▼
   ┌──────────────────────────────┐
   │  Cloud Storage (S3/GCS/...)  │   .mp4 / .m3u8 + .ts
   └──────────────────────────────┘

   녹화 태스크는 클라이언트 앱과 독립적으로 동작하며,
   채널 유휴 시간이 maxIdleTime을 넘으면 종료

도입 후 얻게 되는 이점 (Pros)

클라이언트에서 녹화용 합성·인코딩을 수행하지 않습니다. 통화 자체의 캡처·송수신 부하는 그대로 남습니다.
녹화 태스크는 특정 브라우저 탭과 독립적으로 동작합니다. 다만 구독할 스트림이 없어진 뒤 maxIdleTime을 넘기면 종료되며, 기본값은 30초입니다.

녹화 모드:

Composite Mode: 여러 명의 화면을 하나의 갤러리 뷰 영상으로 합쳐서 저장. (정정: REST API에서는 이 모드를 mode=mix로 지정합니다. "Composite"은 설명용 명칭이고 실제 파라미터 값은 mix입니다.)
Individual Mode: 화자별로 영상을 따로 저장하여 후반 편집(Post-production)에 용이.
Web Page Mode: 특정 URL의 웹페이지 전체를 화면 캡처하듯 녹화합니다. 클라우드 서버 측에서 헤드리스(Headless) 브라우저를 띄워 화면에 렌더링되는 모든 UI, 애니메이션, 화이트보드, 채팅창 등을 사용자가 보는 화면 그대로 녹화하므로 온라인 강의나 웨비나에 매우 유용합니다.

자체 미디어 서버를 운영하지 않아도 되지만, REST 자격 증명을 보호하고 녹화 태스크를 제어할 애플리케이션 백엔드는 필요합니다.

Agora Cloud Recording의 장단점

장점 (Pros): 녹화용 합성·인코딩을 참가자 기기에서 분리하고, 브라우저 탭과 독립된 태스크로 녹화해 설정한 스토리지에 저장합니다.
단점 (Cons): 녹화 시간에 비례한 추가 과금(Pay-as-you-go)이 발생합니다.

시작하기

Agora 콘솔에서 프로젝트를 만들고 Cloud Recording을 활성화합니다.
REST API로 acquire → start → stop 순서로 호출해 녹화 리소스를 할당하고, 녹화를 시작·중지합니다.
스토리지 설정: 녹화 파일을 저장할 CSP(Cloud Storage Provider)를 설정합니다. AWS S3, Azure, Google Cloud, Alibaba, Tencent, Baidu Smart, Huawei 등을 지원합니다.

REST API 호출 예시

녹화 리소스 획득 후 시작하는 흐름입니다:

# 1. acquire - 녹화 리소스 할당 (resourceId는 5분간 유효, 수신 후 2초 내 start 권장)
curl -X POST "https://api.agora.io/v1/apps/{appId}/cloud_recording/acquire" \
  -H "Authorization: Basic {base64CustomerCredentials}" \
  -H "Content-Type: application/json" \
  -d '{"cname":"채널명","uid":"12345","clientRequest":{}}'

# 2. start - 녹화 시작 (mode는 mix | individual | web)
curl -X POST "https://api.agora.io/v1/apps/{appId}/cloud_recording/resourceid/{resourceId}/mode/individual/start" \
  -H "Authorization: Basic {base64CustomerCredentials}" \
  -H "Content-Type: application/json" \
  -d '{"cname":"채널명","uid":"12345","clientRequest":{"storageConfig":{...}}}'

Authorization 값은 Customer ID와 Customer Secret을 customerId:customerSecret으로 결합해 Base64 인코딩한 값입니다. 이 자격 증명은 브라우저에 노출하지 말고 백엔드에서만 사용합니다. App Certificate를 활성화한 프로젝트라면 녹화 서비스가 채널에 참여할 RTC 토큰도 clientRequest.token에 전달해야 합니다.

{
  "resourceId": "예약된 리소스 ID",
  "sid": "녹화 세션 ID"
}

인라인 코드 예: acquire, start, stop 엔드포인트를 순서대로 호출하면 됩니다.

참고 문서

자세한 단계와 API 스펙은 Agora Cloud Recording REST quickstart를 참고하세요.

#12 실시간 통화 왜 녹화하나 — Cloud Recording Architecture — 이 글의 "왜 녹화하나"를 아키텍처 관점에서 더 깊게 파고듭니다.
#14 녹화 모드 해부 — Individual/Mix/Web — 본문에서 다룬 세 가지 녹화 모드의 내부 동작과 산출물 차이를 해부합니다.
#11 Cloud Recording 녹화 파일 저장 — S3 — storageConfig로 S3에 파일을 떨구는 부분을 실전 설정 중심으로 다룹니다.
#13 On-Premise vs Cloud Recording — "자체 미디어 서버 vs 클라우드 녹화"의 비용/운영 트레이드오프 비교.
#33 Cloud Recording 점프 재생 — moov/ENDLIST/DISCONTINUITY — 녹화 산출물(mp4/m3u8)을 재생할 때 생기는 실전 이슈를 다룹니다.

참고 자료

Cloud Recording REST quickstart — acquire → start → query → stop 흐름과 요청 예시.
Cloud Recording REST API reference — mode, clientRequest, storageConfig 등 파라미터 스펙.
Composite recording (mode=mix) — 합성 녹화 설정과 레이아웃 옵션.
Individual recording (mode=individual) — 사용자별 분리 녹화의 동작과 산출물 구조.
Web page recording (mode=web) — 웹페이지 녹화 가이드.
Cloud Recording REST authentication — 모든 요청에 필요한 Basic 인증 헤더 구성 방법.
MediaStream Recording — 브라우저 MediaRecorder의 청크 생성과 데이터 수명 주기 표준.

공식 문서

https://docs.agora.io/en/realtime-media/cloud-recording/rest-quickstart