서버 측 아동 영상 녹화 (camera-video → WebM → S3) — 설계·구현 계획 구현계획

마지막 업데이트 2026-10-15

2026-10-15apps/socket · apps/web상태: 설계·계획 승인, 구현 전

요약: 기존 서버 오디오 녹음(RecordingManager)에 아동 카메라(camera-video, VP8) 입력을 하나 더 붙인다. 녹화 중에는 재인코딩 없이 copy로 WebM segment에 쓰고, 수업 종료 시 기존 mp3와 mux해 mp3와 같은 이름의 .webm으로 S3에 올린다. 영상 경로는 mp3 이후 best-effort로만 실행해 어떤 실패도 mp3·captions·로그 저장을 막지 않는다. 플래그 RECORDING_VIDEO_ENABLED 기본 off.
녹화 범위(10/15 수정): 플래그 on이면 첫 AI 세션이 아니라 수업 시작(GUEST_CONNECTED)부터 종료까지 활동 스텝·AI 세션과 무관하게 녹화한다.

1. 코드 경로

파일변경책임
apps/socket/src/recording/sdpGenerator.ts수정consumer.kind별 m=audio/m=video SDP
apps/socket/src/recording/videoMux.ts신규순수 함수 planVideoMux·buildConcatList·buildVideoMuxArgs, 플래그·키프레임 주기 파서
apps/socket/src/recording/types.ts수정RecordingSession 영상 필드
apps/socket/src/recording/recordingManager.ts수정영상 stem attach/restart/drain, 키프레임 타이머, stop 시 mux·업로드, 로그 확장
apps/socket/src/recording/s3Uploader.ts수정buildVideoS3Key, uploadVideoRecordingToS3(lib-storage 멀티파트)
apps/socket/src/sfu-socket/handlers/media-handlers.ts수정시작 시 camera producer 전달, camera-video produce 시 replaceVideoConsumer
apps/socket/src/sfu-socket/handlers/session-lifecycle-handlers.ts수정GUEST_CONNECTED(수업 시작) 시 플래그 on이면 즉시 녹화 시작 시도
apps/web/app/api/session-logs/route.ts, lib/db-queries.ts, types/db/session-log.types.ts수정PATCH videoRecordingUrl → 녹음 로그 videoS3Key

2. 목적·범위

3. 입출력 흐름

// 녹화 중
mic-audio    ─PlainTransport→ ffmpeg(opus, wallclock ts) → child_segN.ogg ┐
ai-audio     ─PlainTransport→ ffmpeg                     → ai_segN.ogg    ┤ (기존)
camera-video ─PlainTransport→ ffmpeg(-c:v copy, wallclock) → video_segN.webm   + requestKeyFrame 10s 주기

// 종료 (stopRecording)
오디오 stem → post-mix → mixed.mp3 → S3 .mp3 → captions.json        (기존, 변경 없음)
video seg → planVideoMux(start_time, mp3T0) → concat list(duration=다음start−이번start)
          → ffmpeg -i mixed.mp3 -itsoffset Δ -f concat -i list -c:v copy -c:a libopus → .webm → S3 (멀티파트)
saveRecordingLog(mp3Key, captionKey, videoKey|null) → PATCH /api/session-logs
핵심: WebM 오디오 = mp3와 같은 타임라인이라 기존 captions.json을 그대로 재사용한다. concat의 duration 지시어로 카메라 끊김 구간을 정지 화면으로 채우고 이후 싱크를 유지한다.

4. 함수·모듈별 세부

planVideoMux(segments, mp3T0Ms)

영상 stem 수명 주기 (recordingManager.ts)

녹화 시작 조건 — 수업 전체 녹화

현재는 GUEST_CONNECTED에서 metadata만 등록하고 "AI 세션 활성 + mic-audio"일 때 시작해 입장~첫 AI 세션(대기·인트로·안내 영상)이 빠진다. 플래그 on이면 "pending metadata + mic-audio"로 시작한다. 판정은 shouldStartWithoutAiSession() 한 곳.

시점동작
GUEST_CONNECTED (Redis·비Redis 분기)등록 직후 latest mic·ai·camera 조회 → 시작 시도 (mic 없으면 대기)
mic-audio produceisAiSessionActive 없이 시작, 녹음 중이면 기존 replaceChildConsumer
camera-video produce녹음 중이면 replaceVideoConsumer
AI 세션 시작·종료기존 그대로 (ai stem 부착, mic 원본↔처리 교체 시 segment 분할)
사이드 이펙트: 플래그 on 환경에서는 mp3도 수업 전체로 길어진다(captions는 절대 시각이라 그대로 맞음). 재연결 시에는 기존처럼 파일이 나뉜다. 시작에는 mic이 필요하다.

실패 동작

상황결과
카메라 없음mp3만, INFO
영상 ffmpeg 비정상 종료오디오 무영향, 남은 segment로 mux, WARN
유효 segment 0개mux 생략, WARN
mux·업로드 실패·타임아웃(15분)mp3·captions·로그 정상, videoRecordingUrl 없음, ERROR

5. 구현 체크포인트

CP내용막는 위험
0socket recording 테스트·tsc, web session-logs 테스트 baseline 기록기존 실패와 신규 실패 구분
1SDP video 분기 — 오디오 SDP 출력을 먼저 테스트로 고정기존 녹음 전체 파손
2videoMux.ts 순수 함수 단위 테스트 (공백·정렬·drop·음수 offset·이스케이프)A/V 싱크 오차
3실제 ffmpeg 통합: 공백 5s 둔 VP8 segment 2개 + mp3 mux → ffprobe 길이≈7s, opus, webmconcat 공백 보존·copy mux 실동작 — 실패 시 설계 재보고
4영상 stem 수명 주기 (fake spawn·consumer·timer)오디오 오염, ffmpeg·타이머 누수
5종료 mux·업로드 best-effort, videoRecordingUrl 로그영상 실패로 mp3 로그 누락
6수업 전체 녹화 트리거: GUEST_CONNECTED 즉시 시작, AI 세션 조건 제거(플래그 on), camera-video 부착플래그 off 동작 변경, 입장 직후 누락, 중복 시작
7web PATCH·DB videoS3Key (선택 인자 끝에 추가)기존 호출 호환
8prod tmp 디스크·stop 유예 확인 (코드 변경 없음)운영 선행 조건
9사용자 실사용: 박수 싱크, 카메라 off/on 구간성공 기준 확정

6. 주의사항

  • 개인정보: 아동 영상이므로 법정대리인 동의·보관 기간·조회 권한이 정해지기 전에는 플래그를 켜지 않는다.
  • 디스크·종료 시간: 300kbps·50분(수업 전체) 기준 세션당 약 220MB(segment+출력)가 tmp에 필요하고, 배포 SIGTERM 시 stopAll에 mux·업로드 시간이 추가된다 (CP8).
  • 해상도 변동: camera-uplink-adaptation이 수업 중 해상도를 바꾸지만 WebM copy는 스트림 내 해상도 변경을 그대로 담는다. MP4 변환 시에는 고정 scale이 필요하다.
  • 적용 방식: 실인프라·브라우저 검증이 필요하므로 로컬 적용만, 커밋은 사용자 검증 후.

원본 문서(저장소): docs/superpowers/specs/2026-10-15-server-video-recording-design.md, docs/superpowers/plans/2026-10-15-server-video-recording.md

관련 문서: