적용 범위: PPI-1376 작업 브랜치
2026-11-11 코드 대조 · 로컬 ppi develop b0e1e91c
본문은 PPI-1376 브랜치 caf485c3 기준이다. 현재 develop b0e1e91c의 동작이나 운영 배포 완료를 보증하지 않는다. 11월 11일 추가 요구는 아동 미접속 녹화 저장·재입장·재전송 설계에서 별도로 관리한다.
코드와 커밋을 대조한 문서 업데이트이며 운영 환경·실기기 검증은 포함하지 않는다.
Feature · PPI-1376 · 2026-11-09
PPI-1376 모니터 앱 수업 녹화 — 브랜치 전체 정리
마지막 업데이트 2026-11-11
모니터 앱(Electron)에서 그룹 카드뷰·1:1 포커스뷰 수업을 화면 영상 1개 + 아동별 음성으로 녹화해 S3에 올리고, 수업 로그의 녹화 보기에서 다시 재생하는 기능. develop 대비 브랜치 고유 커밋 41개(머지 제외)를 기준으로 구조·흐름·변천을 정리합니다.
01코드 경로
| 영역 | 경로 | 책임 |
|---|---|---|
| 녹화(쓰기) | apps/web/features/monitor-recording/ | 앱 브리지, 아동 음성 녹음·조각 저장, 시작·종료 자동화, 업로드, 상태 표시 |
| 녹화 보기(읽기) | apps/web/features/recording-viewer/ | 녹화 목록·상세 조회, 영상·음성 동기 재생, 이어보기 타임라인 |
| 서버 | apps/web/lib/monitor-recording/, app/api/monitor-recordings/ | presigned URL, manifest 검증·complete, 목록·상세·삭제, 권한 |
| 화면 연결 | app/monitor-dashboard/[group]/page.tsx, [group]/[roomId]/page.tsx, app/main/log/recording/page.tsx | 그룹 녹화 / 1:1 녹화 / 녹화 보기 진입 |
| 공통 | shared/lib/ (room-media-state, recording-retention, recording-lesson-snapshot, one-on-one-recording-key) | 영상 스텝 상태, 보관 기한, 수업 정보 스냅샷, 1:1 녹화 키 |
02목적 요약
진행자가 따로 조작하지 않아도 수업이 예정 시각에 자동으로 녹화되고, 끝나면 자동으로 올라가며, 수업 로그에서 아동별로 그날 수업 화면과 아동·AI 대화를 다시 볼 수 있게 한다.
| 항목 | 값 |
|---|---|
| 영상 | 모니터 앱이 메인 창 화면 + 페이지 재생음을 MP4로 녹화해 직접 업로드 |
| 음성 | 웹 페이지가 이미 받고 있는 SFU 스트림으로 room별 아동 mic + AI 음성 혼합 1파일 |
| 녹화 가능 위치 | 모니터 앱 안에서만 (일반 브라우저는 차단·안내) |
| 최대 길이 | 예정 시각 기준 40분 |
| 보관 | 90일 (S3 lifecycle), 기한이 지나면 파일이 남아 있어도 재생 URL 미발급 |
| S3 키 | {stage}/monitor-recordings/{groupId}/{recordingId}/final/…, manifest.json |
| 녹화 목록 | ppi-session-log-{stage}에 room마다 type="monitor_recording" 행 |
03입출력 흐름
그룹 페이지 /monitor-dashboard/{group} 또는 1:1 포커스뷰 /monitor-dashboard/{group}/{roomId}
├ 예정 시각 도달 → 자동 시작 (테스트 모드는 수동 시작·종료 버튼)
│ web → window.ppiMonitorApp.recording.start({ groupId, recordingId })
│ app: 메인 창 MP4 녹화 시작, 시작 시각 V0 응답
│ web: room별 아동 mic + AI 음성 녹음 → 5초 조각을 IndexedDB에 저장
├ 녹화 중
│ 청취 ON/OFF·영상 스텝 재생 상태(roomMedia)를 manifest 이벤트로 기록
│ 새로고침 → 조각 보존 + 새 세그먼트로 재개(gap 기록), 앱 영상은 계속
├ 종료: 모든 아동 완료·중단·취소 │ 예정+40분 │ 다른 경로로 이탈
│ web: 음성 업로드(presigned PUT) → manifest → POST /complete
│ 서버: manifest 검증 → room별 세션로그 행 기록
│ app: 화면 영상 업로드 (kind "video")
│ web: 15초마다 상세 API videoPending 확인 → '영상 전송 대기' / 30분 초과 시 '확인 필요'
└ 녹화 보기 /main/log/recording
GET /api/monitor-recordings?userId=&lessonIndex= → 회기의 녹화들
GET /api/monitor-recordings/{id} → manifest + 재생 URL
영상 + 아동 음성 + 영상 스텝 소리를 V0 기준으로 맞춰 재생04모듈별 세부
녹화 시작·종료
monitor-app-bridge.ts— preload 브리지(window.ppiMonitorApp.recording) 호출. 구버전 앱이 1:1 시작을 거절하면 업데이트 안내.use-scheduled-recording-start.ts— 예정 시각 자동 시작. 마감이 지난 예정 시각은 넘기지 않고, 떠나서 마감한 수업은 재진입해도 다시 자동 시작하지 않음.use-group-recording-session.ts/use-one-on-one-recording.ts— 그룹은 groupId, 1:1은oneonone-{roomId}키로 녹화를 소유. 첫 시작 실패와 포커스뷰 재시도를 공유해 중복 녹화 방지.use-recording-lesson-completion.ts— 전체 아동 종료 시 자동 종료·전송.
음성 녹음·저장
child-audio-mixer.ts+chunk-recorder.ts— 아동 mic와 AI 음성을 섞어 조각 단위로 녹음. 청취 OFF·볼륨 0%에서도 녹음은 유지.recording-chunk-store.ts,gap-tracker.ts— IndexedDB 조각 보존, 새로고침 구간 gap 기록.use-publish-room-media.ts(features/session) — 영상 스텝 재생 상태 기록. 그룹 카드와 1:1 포커스 화면이 함께 사용.
업로드·서버
use-recording-upload.ts— 재시도 때 이미 올린 파일은 건너뜀.use-app-video-confirmation.ts— 앱 영상 수신 확인 전에는 전송 완료로 표시하지 않음.manifest-validation.ts,recording-access.ts— schemaVersion·경로 검증, 그룹/room 권한. 1:1 키에 다른 아동이 섞이면 403.recording-session-info.server.ts,recording-lesson-snapshot.ts— 녹화 당시 예약 일시·진행자를 고정 저장.
녹화 보기
playback-sync.ts,use-recording-player.ts— 영상·음성 동기화, 배속(최대 3배), 중앙 버튼·Space·좌우 10초 단축키, Cmd +/- 확대.continuous-timeline.ts,use-continuous-playback.ts— 같은 회기의 나뉜 녹화를 영상 있는 것만 시작 순서로 이어 붙여 재생, 다음 영상은 미리 받아 둠.use-recording-availability.ts— 녹화 없음·보관 만료·권한 없음(403)·불러오기 실패를 구분해 안내.- 녹화 보기는 같은 탭으로 이동하고, 로그로 돌아오면 선택이 복원됨.
05설계 변천 (커밋 순서)
| 단계 | 커밋 | 내용 |
|---|---|---|
| 1. PoC | c2abbc2b~5d16e451 | 카드 영역 크롭 녹화, 로컬 폴더 저장, 녹화 뷰어와 영상 스텝 소리 재구성 |
| 2. S3 | 6c515d77~144381ca | S3 업로드·서버 기반 목록, 탭 화면 전체 녹화로 전환, 자동 시작, 화질 개선 |
| 3. 역할 분리 | 30488342~fc0c325d | 별도 녹화 창 제거 → 영상은 모니터 앱, 음성은 그룹 페이지. 앱 밖 녹화 차단, 자동 시작·종료, 최대 40분 |
| 4. 뷰어 | 191f2e36~d7e5a108 | 수업 정보 헤더, 재생 단축키, 레터박스, 녹화 당시 일시·진행자 저장 |
| 5. 1:1 확장 | 69f4db70~da01f817 | 포커스뷰 자동 녹화, 단독뷰 펼치기는 외부 브라우저, 이탈 시 즉시 마감 |
| 6. 안정화 | d0326e06~659ced2f | 이어보기, 만료·403·실패 안내, 업로드 중복 방지, 영상 수신 확인 후 완료 표시, 2.5·3배속, 1:1 영상 스텝 소리 |
이전 단계 설계 문서는 PPI-1376 그룹 녹화 자동 시작·종료와 음성 저장 구현(커밋 1da7134e 기준)과 모니터 탭 화면·오디오 녹화 구현 계획을 참고합니다. 저장소 안 상세 설계는
docs/superpowers/specs/2026-10-19~27-*입니다.06주의사항
- 모니터 앱 안에서만 녹화됩니다. 1:1 링크는 앱 안에서 같은 창으로 이동합니다. 새 창에는 녹화 브리지가 없습니다.
- 영상 업로드는 앱 담당입니다. 웹 음성 전송이 끝나도 영상이 없으면 '영상 전송 대기/확인 필요'로 남습니다. 뷰어는 '화면 영상 업로드 대기'를 보여 줍니다.
- 툴바 "다시 시작"으로 생긴 두 번째 이후 앱 영상은 재생하지 않습니다(첫 파일만 재생).
- 1:1 영상 스텝 소리 수정(
659ced2f)은 새로 녹화하는 수업부터 적용됩니다. 이전 1:1 녹화에는 소리를 재구성할 정보가 없습니다. - multipart 업로드는 범위 밖이라 파일당 단일 PUT입니다(영상 2GB·오디오 300MB 상한).