Cloud Recording으로 스트림 자동 녹화하기 (Backend)

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

Cloud Recording이란?

Cloud Recording은 Agora 채널에 진행 중인 음성·영상 스트림을 Agora 서버에서 녹화하고, 설정한 클라우드 스토리지(AWS S3, Azure, Google Cloud, Alibaba, Tencent, Baidu Smart, Huawei)에 파일로 저장하는 기능입니다. 앱에서 별도 녹화 로직을 구현하지 않아도 되고, 손쉽게 REST API로 녹화를 시작·업데이트·중지·조회할 수 있습니다.

왜 WebRTC 자체 기능으로는 안 될까?

WebRTC는 기본적으로 '실시간 통신'을 위한 기술이므로, 순수 WebRTC 환경에서 녹화를 구현하려면 다음과 같은 치명적인 한계가 발생합니다.

• 클라이언트 리소스 폭발: 브라우저(MediaRecorder API)에서 직접 다자간 화면을 믹싱하고 인코딩하면 사용자 기기의 CPU/메모리 점유율이 급증해 앱이 강제 종료되거나 심각한 발열이 발생합니다.
• 치명적인 불안정성: 사용자의 네트워크가 끊기거나 실수로 앱/브라우저를 닫으면, 그때까지 메모리에 쌓이던 녹화 데이터가 모두 유실됩니다.
• 서버 구축의 복잡성: 이를 해결하기 위해 자체 미디어 서버(SFU/MCU)를 구축해 녹화 파이프라인을 만들려면 막대한 인프라 비용과 개발 리소스가 소모됩니다.

어떻게 동작하는가?

아고라 클라우드 레코딩의 개념은 심플합니다. 아고라의 클라우드 서버가 '보이지 않는 더미 클라이언트(Dummy Client)'로서 우리가 만든 화상 채널에 접속합니다. 그리고 채널에 오가는 모든 오디오와 비디오 스트림을 수신하여 클라우드에서 직접 믹싱한 뒤, Storage (aws, azure, google etc) 버킷으로 .mp4 혹은 .m3u8 파일로 꽂아줍니다.

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

• 클라이언트 부하 제로: 녹화에 필요한 모든 연산(디코딩, 레이아웃 배치, 인코딩)을 아고라 서버가 담당합니다. 클라이언트는 평소처럼 화상회의만 하면 됩니다.
• 압도적인 안정성: 사용자의 앱이 크래시 나더라도, '가상 유저'인 아고라 레코딩 서버는 방에 남아 끝까지 녹화를 완료하고 S3에 저장합니다.

녹화 모드:

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

서버리스(Serverless) 경험: 미디어 서버 인프라를 관리할 필요 없이, REST API로 호출하면 됩니다.

Agora Cloud Recording의 장단점

• 장점 (Pros): 클라이언트 성능 저하가 전혀 없으며, 사용자의 연결이 끊겨도 '가상 유저'인 클라우드 서버가 방에 남아 끝까지 안정적으로 녹화해 AWS S3 등에 다이렉트로 저장합니다. 복잡한 인프라 관리 없이 REST API만으로 제어할 수 있습니다.
• 단점 (Cons): 녹화 시간에 비례한 추가 과금(Pay-as-you-go)이 발생합니다.

시작하기

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

REST API 호출 예시

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

// # 1. acquire - 녹화 리소스 할당
curl -X POST "https://api.agora.io/v1/apps/{appId}/cloud_recording/acquire" \
  -H "Content-Type: application/json" \
  -d '{"cname":"채널명","uid":"12345","clientRequest":{}}'

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

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

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

참고 문서

자세한 단계와 API 스펙은 Agora 공식 문서 - Cloud Recording 시작하기를 참고하세요.