마지막 업데이트 2026-10-15
요약: 기존 서버 오디오 녹음(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 세션과 무관하게 녹화한다.
| 파일 | 변경 | 책임 |
|---|---|---|
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 |
// 녹화 중 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
captions.json을 그대로 재사용한다. concat의 duration 지시어로 카메라 끊김 구간을 정지 화면으로 채우고 이후 싱크를 유지한다.planVideoMux(segments, mp3T0Ms)planPostMix와 같은 방어). 전부 drop이면 null → mux 생략.durationSec[i] = start[i+1] − start[i], 마지막은 null.offsetMs = start[0] − mp3T0, 음수면 0으로 보정 + WARN.recordingManager.ts)"child" | "ai" | "video"로 확장, role별 필드 접근은 getRoleRefs 헬퍼 하나로 모음.videoDegraded만 올림(오디오 degraded 오염 금지).replaceVideoConsumer: 영상 없으면 attach, 있으면 restart, 닫힌 producer·videoDegraded면 skip. operationChain으로 직렬화.현재는 GUEST_CONNECTED에서 metadata만 등록하고 "AI 세션 활성 + mic-audio"일 때 시작해 입장~첫 AI 세션(대기·인트로·안내 영상)이 빠진다. 플래그 on이면 "pending metadata + mic-audio"로 시작한다. 판정은 shouldStartWithoutAiSession() 한 곳.
| 시점 | 동작 |
|---|---|
GUEST_CONNECTED (Redis·비Redis 분기) | 등록 직후 latest mic·ai·camera 조회 → 시작 시도 (mic 없으면 대기) |
mic-audio produce | isAiSessionActive 없이 시작, 녹음 중이면 기존 replaceChildConsumer |
camera-video produce | 녹음 중이면 replaceVideoConsumer |
| AI 세션 시작·종료 | 기존 그대로 (ai stem 부착, mic 원본↔처리 교체 시 segment 분할) |
| 상황 | 결과 |
|---|---|
| 카메라 없음 | mp3만, INFO |
| 영상 ffmpeg 비정상 종료 | 오디오 무영향, 남은 segment로 mux, WARN |
| 유효 segment 0개 | mux 생략, WARN |
| mux·업로드 실패·타임아웃(15분) | mp3·captions·로그 정상, videoRecordingUrl 없음, ERROR |
| CP | 내용 | 막는 위험 |
|---|---|---|
| 0 | socket recording 테스트·tsc, web session-logs 테스트 baseline 기록 | 기존 실패와 신규 실패 구분 |
| 1 | SDP video 분기 — 오디오 SDP 출력을 먼저 테스트로 고정 | 기존 녹음 전체 파손 |
| 2 | videoMux.ts 순수 함수 단위 테스트 (공백·정렬·drop·음수 offset·이스케이프) | A/V 싱크 오차 |
| 3 | 실제 ffmpeg 통합: 공백 5s 둔 VP8 segment 2개 + mp3 mux → ffprobe 길이≈7s, opus, webm | concat 공백 보존·copy mux 실동작 — 실패 시 설계 재보고 |
| 4 | 영상 stem 수명 주기 (fake spawn·consumer·timer) | 오디오 오염, ffmpeg·타이머 누수 |
| 5 | 종료 mux·업로드 best-effort, videoRecordingUrl 로그 | 영상 실패로 mp3 로그 누락 |
| 6 | 수업 전체 녹화 트리거: GUEST_CONNECTED 즉시 시작, AI 세션 조건 제거(플래그 on), camera-video 부착 | 플래그 off 동작 변경, 입장 직후 누락, 중복 시작 |
| 7 | web PATCH·DB videoS3Key (선택 인자 끝에 추가) | 기존 호출 호환 |
| 8 | prod tmp 디스크·stop 유예 확인 (코드 변경 없음) | 운영 선행 조건 |
| 9 | 사용자 실사용: 박수 싱크, 카메라 off/on 구간 | 성공 기준 확정 |
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
관련 문서: