문서 역할: 과거 설계와 구현 이력
2026-11-11 코드 대조 · 로컬 ppi develop b0e1e91c
이 문서는 2026-10-28까지의 설계·구현 이력이다. 브랜치 구조의 대표 설명은 PPI-1376 브랜치 전체 정리, 아동 미접속 저장·재입장·재전송의 후속 제안은 후속 설계를 따른다. 아래 별도 녹화 창·로컬 저장 설명은 당시 접근의 기록이며 현재 권장 구조를 뜻하지 않는다.
코드와 커밋을 대조한 문서 업데이트이며 운영 환경·실기기 검증은 포함하지 않는다.
PPI-1376 · 최신 구현 확인 2026-10-28 · 그룹 녹화 예정시간 자동 시작·종료
화면은 함께 녹화하고,
목소리는 아동별로 저장합니다.
마지막 업데이트 2026-11-11
그룹 모니터 녹화의 현재 동작은 아래 2026-10-28 구현을 기준으로 합니다. 모니터 앱이 화면을 녹화하고 그룹 페이지가 아동별 오디오를 녹음합니다. 이후 섹션은 별도 녹화 창, 로컬 저장, S3 업로드를 검토하고 구현한 과거 기록입니다. 과거의 현재형 설명을 최신 동작으로 해석하지 마세요.
예정시간 자동 시작·종료와 실패 재시도, 2026-10-28
PPI-1376 작업 브랜치에서 진행자가 녹화 시작·종료를 조작해야 했던 흐름을 예정시각과 수업 종료에 따른 자동 처리로 바꿨습니다. 이 섹션은 현재 코드와 로컬 검증 결과를 설명합니다. 실제 모니터 앱에서 화면 기록 권한을 허용하고 캡처 파일까지 만드는 실기기 검증은 포함하지 않습니다.
구현 기준. PPI-1376 브랜치의 커밋 1da7134e를 기준으로 정리했습니다. 이 문서의 구현 완료는 해당 브랜치 코드를 뜻하며 운영 배포 완료를 뜻하지 않습니다.
예약과 녹화는 각자 한 곳에서 관리합니다
MonitorGroupPage가 useScheduledSessions()의 예약을 읽습니다. resolveRecordingPlannedStarts()은 대상 groupId, 진입 날짜가 있으면 classDate, 화면에 유지된 stableRooms의 room ID로 범위를 좁힙니다. 그중 가장 이른 유효한 scheduledStartTime을 사용합니다. 접속한 아동만 담는 recordingRooms로 예약을 계산하지 않으므로 아동 접속 전에도 시작할 수 있습니다.
예정시각은 예약 API 응답에서 가져옵니다. useScheduledSessions()가 GET /api/monitor-dashboard/planned-lessons를 호출하고 응답의 plannedStartTime을 밀리초 시각인 scheduledStartTime으로 변환합니다. 조회 범위는 현재 시각의 60분 전부터 15분 뒤이며 includeCompleted=true로 종료 상태도 받습니다. API 실패 때는 직전 예약을 보존합니다.
useScheduledRecordingStart()는 타이머와 자동 시작 시도만 관리합니다. 로그인 정보와 예약 목록을 읽었고, 모니터 앱 환경이며, recording.restored가 참일 때 기존 session.start()를 호출합니다. 녹화·오디오·IndexedDB 저장·업로드·새로고침 복원은 기존 useGroupRecordingSession()이 계속 관리합니다.
자동 시작 시도는 페이지 범위와 예정시각으로 구분합니다. 시작 호출 전에 시도를 기록하므로 실패 뒤 무한 반복하거나 사용자가 종료한 같은 일정을 다시 시작하지 않습니다. 같은 페이지에서 다음 예정시각으로 바뀌면 이전 녹화가 done인 경우 새 녹화를 시작할 수 있습니다. 녹화·재개 대기 중에는 진행 중인 녹화를 유지하고, 종료·업로드 중이나 업로드 실패 상태를 자동 시작으로 덮어쓰지 않습니다.
마지막 아동 종료와 수업 하드컷에 맞춰 자동 마감합니다
그룹의 모든 대상 아동이 완료·중단·취소 처리되면 useGroupRecordingSession()이 기존 stopRun()을 자동 호출합니다. 종료 모달과 정상 상태의 녹화 시작·종료 버튼을 제거했습니다. 미종료·상태 미확인·단순 연결 끊김은 조기 종료로 판단하지 않습니다.
종료 판정은 녹화 시도 ID가 아닌 그룹·수업 날짜 범위에서 유지합니다. 녹화 시작이나 재시도로 이미 확인한 종료 상태를 초기화하지 않습니다. 새로고침 직후 예약 조회가 끝나지 않았거나, 현재 카드·저장된 예정시각·저장된 오디오 구간에 포함된 아동 중 종료가 확인되지 않은 아동이 있으면 전체 종료로 마감하지 않습니다. 하드컷 타이머는 이 조회 대기와 별도로 동작합니다.
녹화 복원은 로그인한 진행자와 예약 목록이 준비된 뒤 시작합니다. 새 녹화 메타데이터의 scope가 현재 그룹·수업 날짜·진행자 범위와 일치할 때만 이어서 녹음합니다. 다른 범위의 녹화나 범위 정보가 없는 이전 형식은 현재 수업의 오디오를 붙이지 않고 저장된 조각을 마감·전송합니다. 이때 앱이 같은 녹화 ID를 진행 중이면 먼저 해당 녹화를 중단합니다. 복원 대기 중 범위가 바뀐 요청은 취소하고 자신이 만든 오디오 자원을 정리합니다.
기존 녹화의 종료·전송 중 다른 수업으로 이동해도 기존 녹화의 그룹 표식만 정리합니다. 기존 전송이 끝나면 새 수업의 복원 여부를 다시 확인한 뒤 자동 시작을 허용합니다. 전송 완료만으로 새 수업이 준비됐다고 표시하거나 새 수업의 미전송 기록을 덮어쓰지 않습니다.
하드컷은 녹화 시작 후 40분이 아니라 각 대상 수업의 예정시각에 40분을 더한 절대시각입니다. 예정시각이 서로 다른 아동은 가장 늦은 종료 기준을 사용합니다. 예를 들어 16:00 예정 수업에 16:10 입장하면 16:40에 마감합니다. 예정시각 변경은 새 기준을 반영하고, 조회 응답에서 아동이 빠졌다는 이유만으로 기존 기준을 삭제하지 않습니다.
아동별 예정시각을 녹화의 IndexedDB 메타데이터에 보존해 새로고침 뒤에도 같은 하드컷을 적용합니다. 유효한 예정시각을 전혀 확보하지 못한 녹화만 기존 녹화 시작 후 40분을 안전 상한으로 사용합니다. 하드컷이 지난 수업은 자동 시작과 직접 재시도 모두 새 녹화를 만들지 않습니다. 앱의 시작 응답이 하드컷 뒤 늦게 성공해도 새 녹음을 활성화하지 않고 앱 녹화를 정리합니다.
마지막 아동 종료와 하드컷이 겹쳐도 run.stopping으로 마감은 한 번만 실행합니다. 아동별 녹음기의 마지막 조각 저장과 종료 오프셋 기록, 앱 화면 녹화 중단, 메타데이터 저장, 자원 정리, 업로드 순서를 재사용합니다. 이 그룹 녹화기의 믹스 오디오는 함께 마감하지만 별도 SFU 서버 음성 녹음의 시작·종료 로직은 수정하지 않았습니다. 전송 실패는 기존 전송 재시도로 복구합니다.
집중뷰도 최초 실패를 전달받습니다
이전에는 recordingId가 생긴 뒤에만 상태를 발행해 첫 시작 실패가 집중뷰에 전달되지 않았습니다. 이제 복원 판단이 끝나면 상태 채널을 연결합니다. 실제 녹화 ID가 없을 때는 페이지의 안정적인 pending-… 소유자 ID로 준비·시작·실패 상태를 발행합니다. 상태 대상 room은 접속 아동뿐 아니라 stableRooms 전체입니다.
집중뷰의 requestRecorderRetry()는 관찰한 소유자 ID, openedAt, 상태와 요청 ID를 담아 그룹별 BroadcastChannel에 명령을 보냅니다. 그룹 페이지는 소유자·시각·상태가 맞는 요청만 받고 같은 요청 ID는 한 번 처리합니다. 집중뷰는 별도 녹화기를 만들거나 앱 브리지를 직접 호출하지 않습니다. 수신 확인이 2초 안에 오지 않으면 그룹 모니터 연결 확인 안내를 표시합니다. 수신 확인만으로 성공 배지로 바꾸지 않으며 실제 상태를 기다립니다.
화면 캡처 성공과 오디오 준비를 구분합니다
사용자 클릭 없이 실행한 AudioContext.resume()은 브라우저 정책에 막힐 수 있습니다. 앱의 화면 녹화 시작이 성공해도 오디오가 running인지 확인합니다. 재개 대기는 최대 300ms입니다. 오디오가 준비되지 않으면 resume-needed로 남기고 녹화 안됨과 다시 시작하기를 표시합니다. 녹화 ID와 메타데이터는 보존해 재개하거나 자동 종료 기준에 따라 마감할 수 있습니다.
집중뷰의 클릭을 BroadcastChannel로 전달해도 부모 탭에 사용자 활성화가 전달되지는 않습니다. 오디오가 계속 잠겨 있으면 녹화중으로 표시하지 않고 그룹 모니터 화면에서 다시 누르라는 안내를 유지합니다. 직접 재시도할 때는 사용자 활성화를 유지하도록 AudioContext 생성과 resume 호출을 비동기 경계 앞에서 실행합니다.
변경 코드와 유지한 경계
| 파일 | 역할 |
|---|---|
apps/web/app/monitor-dashboard/[group]/page.tsx | 예약 범위를 계산하고 복원 완료 뒤 자동 시작을 연결합니다. 전체 표시 room을 상태 대상으로 전달합니다. |
apps/web/features/monitor-recording/model/use-scheduled-recording-start.ts | 아동별 예정시각을 선택하고 일정별 자동 시작 시도와 시작 가능 기한을 관리합니다. |
apps/web/features/monitor-recording/model/use-group-recording-session.ts | 앱 시작과 오디오 준비를 확인합니다. 수업 소유 범위와 예정시각을 보존하고 전체 아동 종료·하드컷·복원·저장을 관리합니다. |
apps/web/features/monitor-recording/model/use-publish-recorder-status.tsapps/web/features/monitor-recording/model/request-recorder-retry.ts | 최초 실패를 포함한 상태 발행과 소유자 대상 재시도 명령을 처리합니다. |
apps/web/features/monitor-recording/ui/group-recording-controls.tsxapps/web/features/monitor-recording/ui/monitor-focus-recording-status.tsxapps/web/features/monitor-recording/ui/monitor-recording-status.tsx | 정상 시작·종료 모달과 수동 녹화 버튼을 제거하고 상태 배지·실패 표시·재시도 버튼을 구성합니다. 업로드·전송 재시도 기능은 유지합니다. |
apps/web/features/monitor-recording/ui/scheduled-recording.stories.tsx | 실제 예약 훅과 BroadcastChannel을 쓰는 독립 fixture로 자동 시작과 집중뷰 재시도를 검토합니다. |
apps/web/features/monitor-recording/model/use-recording-lesson-completion.ts | 수업 범위에서 전체 대상과 종료 확인 대상을 유지합니다. |
apps/web/features/monitor-recording/ui/automatic-recording-stop.stories.tsx | 실제 녹화 훅과 종료 판정을 합성 저장소·앱 브리지로 실행해 마지막 아동 종료와 예약 하드컷을 재현합니다. |
검증 결과와 재실행 명령
- 직접 관련 Vitest 28개 파일의 테스트 246개가 통과했습니다. 자동 시작·마지막 아동 종료·예약 변경·알 수 없는 아동·새로고침·수업 범위 전환·전송 실패 후 재시도·늦은 앱 시작 응답을 확인했습니다. 복원과 자동 시작 훅을 함께 실행하는 회귀 테스트도 포함합니다.
- 패키지 타입 검사가 통과했습니다. 최종 복원 변경 파일 ESLint는 오류 0개, 기존 import 순서 경고 1개입니다.
- Storybook 정적 빌드가 통과했습니다. 로컬 브라우저에서 마지막 아동 종료 시 팝업 없이 앱 종료와 전송이 각각 1회 실행되는 것을 확인했습니다. 별도 예약 하드컷 시나리오는 아동 B가 미종료인 상태에서도 클릭 없이 종료·전송을 각 1회 실행했습니다. JavaScript 오류는 없었습니다. 앞서 예정시각 자동 시작과 집중뷰 채널 재시도도 fixture에서 확인했습니다.
- 최종 변경 경로 대상 mutation 실행은 6개 소스의 변이 1,142개를 처리했습니다. Killed 831개, Survived 278개, NoCoverage 32개, RuntimeError 1개입니다. 통과한 테스트로 구별하지 못한 변이가 남아 있습니다. 누적 incremental report의 다른 파일은 이번 숫자에 포함하지 않았습니다.
app/monitor-dashboard/[group]/page.tsx는 대괄호 glob 보정 후에도 관련 테스트가 없어 별도 실행에서No tests were executed로 중단됐습니다. - 최종 독립 guardian 리뷰에서 자동 종료·복원 변경의 추가 P0·P1은 없었습니다. 이전 자동 시작 리뷰에서 확인한 예정시간 전 집중뷰의 정상
ready상태 점검 안내 P2는 남아 있습니다. 이 경우 빨간 실패 테두리는 표시하지 않습니다.
pnpm --dir apps/web exec vitest run features/monitor-recording --exclude '**/.stryker-tmp/**' pnpm --dir apps/web exec tsc --noEmit --incremental false pnpm --dir apps/web exec storybook build --test pnpm test:mutation -- <변경한 앱 파일 경로들>
검증 한계. 위 브라우저 확인은 실제 backend·socket·미디어 장치 없이 실행한 Storybook fixture입니다. 실제 Electron 앱의 화면 기록 권한, 사용자 활성화 없이 오디오가 재개되는지, 장시간 캡처와 최종 녹화 파일은 별도로 확인해야 합니다. 녹화 자동 시작을 위해서는 그룹 모니터 페이지가 열려 있어야 합니다.
아동별 음성 녹음과 종료 후 전송
화면 녹화와 음성 녹음은 실행 주체가 다릅니다. 모니터 앱은 화면을 캡처하고, 그룹 페이지는 카드에서 수신한 아동 마이크와 AI 트랙을 아동별로 녹음합니다. 여러 아동의 음성을 한 파일로 합치지 않습니다.
예약 API의 plannedStartTime → useScheduledSessions().scheduledStartTime → 그룹 페이지의 아동별 plannedStartTimes → 가장 이른 예정시각에 useScheduledRecordingStart()의 begin() → session.start() → 앱 브리지 recording.start()와 AudioContext 준비 → beginRecording()에서 아동별 녹음 시작 카드의 아동 마이크 + 해당 아동의 AI 트랙 → createChildAudioMixer() → 아동별 MediaRecorder → IndexedDB의 오디오 조각 + 녹화 메타데이터 → 자동 종료 시 오디오 파일 + manifest 전송
청취 설정은 녹음 입력을 끄지 않습니다
createChildAudioMixer()는 마이크와 AI를 하나의 출력 트랙으로 합칩니다. 믹서는 진행자 스피커에 연결하지 않습니다. 진행자의 청취 켜기·끄기와 별개로 수신한 트랙을 녹음하며, 콘텐츠 영상 소리는 믹서 입력에 포함하지 않습니다. 현재 상한은 아동 4명이고 오디오 조각 생성 주기는 5초입니다. 상한을 6명으로 올릴 때의 영향은 그룹 녹화 최대 아동 수 4 → 6 변경 영향 검토를 참고하세요.
자동 종료는 마지막 조각을 저장한 뒤 전송합니다
stopRun()은 중복 종료를 막고 아동별 녹음기를 중지해 마지막 조각과 종료 오프셋을 확정합니다. 이어 앱 브리지의 recording.stop()을 요청하고 메타데이터 저장·오디오 자원 정리·파일 조립·전송을 진행합니다. 앱 종료 응답은 최대 10초를 기다리며, 앱 응답 실패 때문에 저장된 오디오의 전송까지 막지 않습니다.
전송 성공 뒤에만 IndexedDB의 해당 녹화와 원래 그룹의 복원 표식을 지웁니다. 실패하면 조각과 메타데이터를 남기고 다시 전송으로 기존 녹화의 전송을 재시도합니다. 저장된 아동 오디오가 전혀 없으면 전송하지 않고 경고와 함께 정리합니다.
웹의 uploadRecording()이 조립하는 전송 대상은 아동별 오디오와 manifest입니다. 앱 화면 영상의 파일명·시작시각·길이는 브리지 결과로 받습니다. 웹의 전송 완료만으로 앱 영상의 마지막 데이터까지 서버가 수신했다는 사실을 보장하지 않습니다.
코드 근거는 apps/web/features/monitor/hooks/use-scheduled-sessions.ts, apps/web/features/monitor-recording/model/child-audio-mixer.ts, apps/web/features/monitor-recording/model/recording-limits.ts, apps/web/features/monitor-recording/model/group-recording-assembly.ts, apps/web/features/monitor-recording/model/monitor-app-bridge.ts, apps/web/features/monitor-recording/model/use-group-recording-session.ts입니다.
녹화 당시 수업 일시와 진행자 저장, 2026-10-29
새 녹화는 시작 당시의 아동별 예약일시와 녹화를 시작한 로그인 계정을 lessonSnapshot에 저장합니다. 나중에 예약이 바뀌거나 조회할 수 없어도 녹화 보기는 이 값을 우선 표시합니다. 시작 성공 시 한 번 복사하며 새로고침·전송 재시도에서 현재 값으로 덮어쓰지 않습니다.
| 필드 | 의미 |
|---|---|
recordedBy.id·recordedBy.name | 시작 당시 로그인 진행자 ID·이름. 배정 담당자·업로드 계정·뷰어 로그인 계정으로 바꾸지 않음 |
recordingStartedAt | 앱의 영상 녹화 시작시각. 웹 오디오의 시작시각과 구분 |
scheduledStartTimes | roomId별 당시 예약일시 ISO map. 표시할 때 KST로 변환 |
기존 plannedStartTimes는 자동 종료 계산에 쓰며 예약 변경을 반영합니다. 고정 표시용 snapshot과 별도로 유지합니다. 시작 당시 예약 목록에 있던 미접속 아동도 예약 map에 포함하므로, 녹화 도중 접속하더라도 당시 예약을 찾을 수 있습니다. 시작 뒤 새로 발견한 예약을 과거 값으로 채우지 않습니다.
저장과 조회 경로
- 그룹 페이지가 실제 로그인 진행자와 예약 정보를 녹화 훅에 전달합니다. 자동 시작과 테스트 수동 시작은 같은 start 경로를 사용합니다.
- 새 start 요청에서 문맥을 복사하고 앱 녹화 시작 성공과 범위 확인 후 새 메타에 snapshot을 넣습니다. 실패한 시작은 새 snapshot을 남기지 않습니다.
- IndexedDB의
StoredRecording이 snapshot을 보존합니다. 복원·재접속·전송 재시도는 이 값을 운반하며 이전 녹화에 현재 계정이나 예약을 보충하지 않습니다. assembleGroupRecording()이 실제 아동 트랙의 예약만 manifest로 복사하고 기존 업로드 경로가 S3에 전송합니다. 기존 schemaVersion 1에 선택 필드를 추가하므로 예전 저장물도 읽습니다.- 상세 API가 기존 접근 권한을 먼저 확인합니다. 반환할 snapshot map도 허용된 아동 트랙으로 제한합니다. snapshot이 있으면 현재 수업 API를 조회하지 않습니다. 없는 이전 녹화만 기존 API와 5초 제한을 사용합니다.
- 서버와 로컬 뷰어 모두 manifest snapshot을 우선 표시합니다. 예약이 있으면 예약일시를, 없으면 실제 영상 시작시각과 녹화 시작을 표시합니다. 저장된 실제 계정은 녹화 진행자로 구분합니다.
새 선택 필드는 JSON 경계에서 형식을 검증합니다. 손상된 snapshot을 이전 자료처럼 취급해 현재 예약으로 대체하지 않습니다. 현재 이름이 비어 있으면 당시 정보 없음으로 표시하며 추정하지 않습니다. 녹화 시작·종료 조건, 음성 처리와 영상 보관 기한은 이 변경에서 바꾸지 않습니다.
실제 문제와 적용 범위
이전 조사에서 로컬 chulsu3 1회기의 녹화 상세와 수업 API는 모두 200이었지만, 상세의 sessionInfo.status는 unavailable이었습니다. lesson은 있으나 응답의 예약일시·담당자 값은 없었습니다. 이 응답만으로 DB의 담당자 정보도 없다고 단정할 수는 없습니다. 기존 로더는 예약시각을 찾지 못하면 담당자 별도 조회까지 이어가지 않습니다.
새 snapshot은 이 변경 이후 시작한 녹화부터 저장합니다. 기존 녹화에 저장되지 않은 당시 진행자를 소급해서 확정하지 않습니다. 따라서 기존 예약 없는 녹화는 계속 정보 없음으로 보일 수 있습니다. 직접 DB 수정이나 기존 파일의 일괄 보강은 하지 않았습니다.
검증 결과와 한계
구현 전 기준선은 46파일399테스트 통과입니다. 새 snapshot 누락을 재현하는 실패를 확인한 뒤 저장·복원·manifest·서버·뷰어를 연결했습니다. 최종 관련 검증은 47파일433테스트 통과입니다. 공유 패키지를 현재 소스로 재빌드한 뒤 타입 검사가 통과했습니다. 기능별 Storybook 정적 빌드도 통과했습니다.
실제 RecordingViewerContainer에 목록·상세 API fixture를 연결한 브라우저에서 저장 예약 26.10.15 목 16:00과 실제 녹화자 표시를 확인했습니다. 현재 수업 정보에는 다른 날짜·담당자를 넣어 저장값 우선을 확인했습니다. 아동 B 음성 선택 후 제목과 수업 정보가 유지됐습니다. 예약 없는 fixture는 앱 V0인 15:59 녹화 시작을 표시했습니다. JavaScript 오류는 없었습니다. 이는 격리 fixture 검증이며 실제 설치형 앱의 새 녹화·S3 전송을 수행한 결과는 아닙니다.
변경 경로를 지정한 mutation 검사의 dry-run은 273테스트가 통과했고, 변경 소스에 해당하는 변이 1,711개를 처리했습니다. Killed 1,340개, Survived 325개, NoCoverage 45개, RuntimeError 1개입니다. 공통 snapshot 모듈은 Killed 92개·Survived 10개였습니다. 누적 incremental report의 다른 파일은 이 숫자에서 제외했습니다. 대괄호가 있는 그룹 페이지는 첫 glob에서 누락되어 별도 리터럴 경로 실행으로 확인했습니다. 그룹 페이지는 경로를 정상 인식한 뒤 관련 테스트가 없어 No tests were executed로 중단됐습니다. 페이지의 로그인 정보 연결 2줄은 타입 검사와 코드 리뷰로 확인했으며 해당 페이지의 mutation 검증은 공백으로 남습니다.
독립 guardian-gate 리뷰에 P0·P1은 없었습니다. P2 한 건으로 손상된 manifest의 2026-02-30 같은 날짜가 Date.parse 정규화를 거쳐 수용되는 약점이 남습니다. 정상 생성은 toISOString을 사용합니다. 임의 직접 호출에 Date 범위를 넘는 epoch를 주면 생성기가 예외를 던지는 전제도 남지만 정상 예약 입력은 getTime의 NaN을 제거하므로 정상 UI 차단은 확인되지 않았습니다. P2는 이번에 자동 수정하지 않았습니다. 변경 파일 lint는 변경 전과 동일한 오류 0·경고 16이며 신규 경고는 없습니다. 신규 주석·suppression은 0개이고 git diff --check가 통과했습니다.
pnpm --dir apps/web exec vitest run features/monitor-recording features/recording-viewer lib/monitor-recording/recording-service.test.ts lib/monitor-recording/manifest-validation.test.ts shared/lib/recording-lesson-snapshot.test.ts --exclude '**/.stryker-tmp/**' pnpm --dir apps/web exec tsc --noEmit pnpm --dir apps/web exec storybook build -c test-artifacts/snapshot-storybook-config -o /private/tmp/ppi1376-snapshot-storybook pnpm test:mutation -- <실제 변경한 앱 파일 경로>
- 로그인 store에서 관측한 계정 ID·이름의 보존이며 서버가 서명한 역사 증명은 아닙니다.
- 브라우저 확인은 격리된 API fixture와 로컬 영상 기준입니다. 실제 설치형 앱에서 새 수업을 녹화해 S3 전송까지 완료한 검증은 아닙니다.
- 장치 권한·장시간 녹화·PC 종료 뒤 자동 전송·실제 90일 삭제는 이번 metadata 변경의 검증 범위가 아닙니다.
코드 근거: apps/web/shared/types/recording-session-info.ts, apps/web/shared/lib/recording-lesson-snapshot.ts, apps/web/app/monitor-dashboard/[group]/page.tsx, apps/web/features/monitor-recording/model/use-group-recording-session.ts, apps/web/features/monitor-recording/model/recording-chunk-store.ts, apps/web/features/monitor-recording/model/recording-manifest.ts, apps/web/features/monitor-recording/model/group-recording-assembly.ts, apps/web/lib/monitor-recording/manifest-validation.ts, apps/web/lib/monitor-recording/recording-service.ts, apps/web/features/recording-viewer/model/find-recordings.ts, apps/web/features/recording-viewer/model/viewer-model.ts입니다.
기존 녹화의 API 수업 정보와 영상 보관 기한, 2026-10-29
이 절의 API 조회는 snapshot이 없는 기존 녹화에 적용합니다. 새 녹화의 고정 정보 저장은 위 절을 따릅니다. /main/log/recording?userId=…&lessonIndex=…가 선택한 녹화의 상세 API에서 수업 정보를 읽습니다. 로그 페이지에서 lesson 객체 전체를 넘기지 않습니다. 제목은 아동명 N회기이며, 다른 아동 음성을 선택해도 로그에서 선택한 아동의 제목을 유지합니다.
제목 옆의 그룹 · N명은 접근 가능한 녹화의 아동 음성 트랙에서 고유 아동을 센 값입니다. 새로고침으로 생긴 여러 세그먼트와 같은 아동의 여러 회기는 중복으로 세지 않습니다.
| 표시 | 값과 근거 |
|---|---|
| 제목 | 예: 아동 A 12회기. 선택한 아동·회기의 수업 정보 또는 녹화 트랙 이름을 사용하며 다른 아동 이름으로 대체하지 않음 |
| 수업 정보 | 예: 26.10.15 목 16:00 예약 / 담당 진행자: 진행자 1. KST로 표시하며 여러 담당자는 쉼표로 나열 |
| 영상 보관 기한 | 예: 27.01.12. 영상 생성일을 KST D+0으로 계산해 D+89 마지막 날을 표시 |
| 상세 안내 | 보관 기한에 마우스를 올리면 예: 2027.01.13 00:00 KST에 삭제 예정. time 요소의 접근성 설명에도 같은 시각을 제공 |
조회 경로와 기존 문제
기존 헤더 구현은 녹화 시작일의 예약 목록에서 아동·회기·그룹을 찾았습니다. 녹화일과 예약일이 다르거나 그룹 배정이 바뀐 기록은 수업 정보가 있어도 찾지 못했습니다. 해당 클라이언트 조회 훅을 제거하고, 선택한 녹화 상세 응답의 sessionInfo로 교체했습니다. 뷰어는 더 이상 /api/monitor-dashboard/planned-lessons를 호출하지 않습니다.
- 뷰어가
GET /api/monitor-recordings?userId=…&lessonIndex=…로 목록을 읽고 선택한 녹화의 상세 API를 호출합니다. getRecordingDetail()은 접근 권한·선택 아동의 인덱스·manifest를 확인한 뒤에만 수업 정보를 조회합니다. 거부·녹화 없음·만료 응답에서는 수업 정보를 조회하지 않습니다.- 서버 로더가
getClassByLessonIndex()로 아동·회기의 예약 날짜와 시간을 구합니다. 녹화일과의 일치를 요구하지 않습니다. 정규 수업 정보가 없으면 기존 lesson의scheduledTime을 사용합니다. - 정규 수업은 예약 날짜 하루의 수업 목록에서 아동·회기·날짜가 일치하는 행을 찾아
groupMemberNames, 없으면memberName을 읽습니다. 예전 그룹 ID와 현재 그룹 ID가 달라도 동일 아동·회기의 정보로 연결합니다. 조회 중인 사용자의 이름을 담당자로 표시하지 않습니다. - 상세 응답의 manifest·재생 URL·수업 정보를 하나의 선택 상태로 교체합니다. 아동·회기·녹화 선택이 바뀌면 이전 정보를 비우고 늦게 도착한 응답을 무시합니다.
메타데이터 조회는 5초로 제한합니다. 실패·시간 초과·응답 형식 오류는 sessionInfo.status = error로 반환해 영상 응답을 유지합니다. 화면에는 예약 정보 조회 실패 / 담당 진행자: 조회 실패를 표시합니다. 실제 정보 부재는 예약 정보 없음 / 담당 진행자: 정보 없음으로 구분합니다. 녹화 시작시각을 예약시각으로 대체하지 않습니다. 예전 상세 응답이나 로컬 파일에 snapshot과 수업 정보가 모두 없으면 수업 정보 없음으로 처리합니다.
보관 기한은 영상 생성일로 계산합니다
manifest.startedAt에 video 트랙의 startOffsetMs를 더해 앱 영상의 실제 시작시각을 계산합니다. 앱 영상이 웹 음성보다 먼저 시작해 KST 자정을 넘긴 경우에도 영상이 생성된 날짜를 기준으로 합니다. 이 변경은 기한과 삭제 예정 시각의 표시이며 실제 서버 삭제 집행 검증은 별도입니다.
검증 결과
API 전환 전 관련 테스트 153개가 통과했습니다. 상세 응답에 수업 정보가 없는 문제를 재현하는 서비스 테스트의 실패를 확인한 뒤 구현했습니다. 최종 관련 테스트는 18개 파일, 173개 통과입니다. 서버 로더의 36개 계약 테스트는 녹화일과 다른 예약일·legacy 정보·담당자 선택·오류·잘못된 날짜를 다룹니다. 서비스 테스트는 권한 확인 뒤의 조회·5초 제한·오류 시 영상 응답 보존을, 뷰어 테스트는 응답 파싱·선택 전환·지연 응답·제목 유지·보관 기한을 확인합니다.
cd apps/web pnpm exec vitest run lib/monitor-recording/recording-service.test.ts lib/monitor-recording/recording-session-info.server.test.ts features/recording-viewer --exclude '**/.stryker-tmp/**' pnpm exec tsc --noEmit
타입 검사와 Storybook 정적 빌드는 통과했습니다. 브라우저에서는 실제 뷰어 컨테이너와 목록·상세 API 형태의 fixture를 연결했습니다. 녹화일 2026-10-29, 예약일 2026-10-15로 설정해 26.10.15 목 16:00 예약 / 담당 진행자: 진행자 1 표시와 아동 B 음성 선택 후에도 아동 A 제목 유지를 확인했습니다. 허용한 목록·상세 경로 외 요청은 fixture에서 실패하도록 했습니다. 실제 운영 데이터 조회나 사용자가 제공한 아동의 운영 기록 검증은 하지 않았습니다.
독립 guardian 리뷰에 P0·P1은 없었습니다. 변경 파일 lint는 기존 오류 17건과 경고 1건이 남았고 새 억제 지시문은 추가하지 않았습니다. 변경 경로를 명시한 pnpm test:mutation -- …은 공유 API 클라이언트 관련 테스트를 포함한 dry-run에서 기존 session-card-management.integration.test.tsx의 실패 문구 불일치로 중단됐습니다. 원래 HEAD의 API 클라이언트로 치환한 격리 실행에서도 동일 테스트가 실패했습니다. 해당 테스트를 수정하거나 제외해 통과시키지 않았으며 이번 최종 변경의 mutation 점수는 없습니다.
남은 한계
- snapshot 없는 기존 녹화의 수업 API는 현재 예약·배정 정보를 반환하므로 당시 값과 다를 수 있습니다. 새 녹화는 저장한 snapshot을 우선합니다.
- 5초 후 HTTP 요청은 취소하지만, legacy DynamoDB 조회가 이미 실행됐거나 abort 오류 뒤 fallback으로 시작되면 응답 반환 뒤에도 끝날 때까지 실행될 수 있습니다.
- 그룹 인원수는 권한으로 필터된 녹음 트랙 기준이므로 녹음되지 않거나 제외된 아동을 포함한 실제 정원과 다를 수 있습니다.
- 삭제 시각은 네이티브 마우스 툴팁과 접근성 설명으로 제공하며 터치·키보드용 상세 열기 동작은 추가하지 않았습니다.
코드 근거: apps/web/lib/monitor-recording/recording-session-info.server.ts, apps/web/lib/monitor-recording/recording-service.ts, apps/web/lib/monitor-recording/recording-service.server.ts, apps/web/shared/types/recording-session-info.ts, apps/web/features/recording-viewer/model/recording-api.ts, apps/web/features/recording-viewer/model/use-s3-recording-library.ts, apps/web/features/recording-viewer/model/viewer-model.ts, apps/web/features/recording-viewer/ui/recording-viewer-container.tsx, apps/web/features/recording-viewer/ui/recording-viewer.tsx입니다.
뷰어 중앙 버튼과 키보드 재생 조작, 2026-10-28
이 절은 PPI-1376 브랜치의 커밋 015bc370에 반영한 뷰어 변경을 설명합니다. 녹화 자동 시작·종료와 별도의 변경이며 운영 배포 완료를 뜻하지 않습니다.
영상 중앙에 원형 재생·일시정지 토글 버튼을 추가했습니다. 중앙 버튼과 기존 상단 버튼은 같은 isPlaying 상태와 onPlay·onPause를 사용합니다. 실제 video 요소의 play·pause 이벤트가 아이콘을 갱신하므로 별도의 재생 상태를 만들지 않습니다.
| 조작 | 동작 |
|---|---|
| 영상 중앙 버튼 | 재생 중에는 일시정지, 일시정지 중에는 재생. 상단 버튼과 상태가 일치 |
| Space | 재생·일시정지 전환. 버튼에 포커스가 있으면 기본 키보드 클릭만 사용해 두 번 전환하지 않음. 길게 눌러 발생한 반복 keydown은 전환하지 않음 |
| ← · → | 10초 전·후 이동. 0초와 전체 길이 사이로 제한. 처리한 키의 기본 페이지 스크롤을 막음 |
| 입력창·배속·음량·편집 영역 | 요소의 원래 키보드 조작을 유지하고 녹화 단축키를 실행하지 않음 |
| 삭제 확인 모달 | 모달 뒤 영상의 단축키 조작을 차단 |
기존 useRecordingPlayer()의 play·pause·seek 경로를 재사용합니다. 시간 이동은 영상 위치와 선택한 음성 채널 동기화에 같은 기준 시각을 전달합니다. 재생할 녹화가 준비되지 않은 상태에는 중앙 버튼을 표시하지 않습니다.
직접 관련 뷰어 테스트 15개 파일, 84개가 통과했습니다. 타입 검사와 Storybook 정적 빌드도 통과했습니다. 실제 로컬 MP4를 사용하는 PlaybackControls story에서 중앙 버튼, 버튼에 포커스가 있는 상태와 페이지의 Space, 좌우 탐색, 삭제 모달의 탐색 차단을 확인했습니다. 브라우저 JavaScript 오류는 없었습니다.
변경 파일 lint에는 변경 전에도 있던 react-hooks/refs 오류 5건만 남았으며 새 억제 지시문은 추가하지 않았습니다. mutation 검사는 2개 소스의 변이 517개를 처리했습니다. Killed 132개, Survived 245개, NoCoverage 139개, RuntimeError 1개로 모든 변이를 탐지한 것은 아닙니다.
독립 리뷰에서 P0·P1은 없었습니다. P2 한 건으로 Shift+Space·Shift+좌우 키도 재생·탐색을 실행하는 점이 남아 있습니다. Ctrl·Meta·Alt 조합은 무시합니다. 브라우저 확인은 로컬 합성 영상 기준이며 실제 서버 녹화 파일과 음성 청취 검증을 대신하지 않습니다.
코드 근거는 apps/web/features/recording-viewer/ui/recording-viewer.tsx, apps/web/features/recording-viewer/ui/recording-viewer.module.css, apps/web/features/recording-viewer/model/use-recording-player.ts, apps/web/features/recording-viewer/ui/recording-viewer.stories.tsx입니다.
pnpm --dir apps/web exec vitest run features/recording-viewer --exclude '**/.stryker-tmp/**' pnpm --dir apps/web exec tsc --noEmit pnpm --dir apps/web exec storybook build --test
현재 구현과 기획서 전체 목표의 경계
| 항목 | 현재 확인한 구현 | 남은 확인 또는 작업 |
|---|---|---|
| 그룹 녹화 시작·종료 | 예약 자동 시작, 전체 대상 아동의 완료·중단·취소 확인 시 종료, 가장 늦은 예정시각 + 40분 하드컷, 정상 모달·수동 버튼 제거 | 실제 앱에서 권한 허용·거부와 장시간 녹화 검증 |
| 포커스뷰 | 그룹 페이지의 상태를 전달받아 표시하고 시작 실패·오디오 재개 대기를 그룹 페이지에 재시도 요청 | 예정시각 전 정상 대기 상태에서도 점검 안내가 보이는 기존 P2. 앱 영상 중단 뒤 직접 재녹화 경로는 이번 변경에 추가하지 않음 |
| 1대1 수업 | 이번 자동 시작·종료 연결은 그룹 페이지에 적용. 포커스뷰는 상태 공유 경로를 사용 | 독립 1대1 수업의 전체 자동 녹화 명세는 이 변경의 완료 범위에 포함하지 않음 |
| 음성 저장 | 아동별 마이크·AI 혼합 오디오, IndexedDB 조각 저장, 종료 후 전송, 실패 재시도 | 별도 SFU 음성 녹음의 기존 시작·종료 조건은 변경하지 않음 |
| 전송 완료와 앱 수명 | 웹은 전송 중 · 페이지를 닫지 마세요, 전송 실패, 전송 완료를 표시. 전송 실패 버튼은 다시 전송 | 기획의 PC 종료 안내, 영상 최종 수신 확인, 창 X 뒤 백그라운드 전송, 앱 재실행 자동 전송은 이 브리지·웹 변경만으로 완료됐다고 판단하지 않음 |
| 보관·권한·재생 | 기존 S3·로그 색인·뷰어의 과거 구현 기록은 아래에 유지 | 영상 KST 90일 삭제, 전체 경로 권한 일치, 여러 파일과 공백의 공통 타임라인은 이번 커밋의 구현·검증 범위 밖. 별도 현황 대조 필요 |
위 표는 현재 커밋의 확인 범위입니다. 기획서의 모든 기능이 완료됐다는 의미가 아닙니다. 특히 웹 오디오 전송 성공과 앱 영상 전송 완료를 구분해야 합니다.
0. 1단계 PoC — 실제 구현 (2026-10-19)
2026-10-21 변경 — 탭 화면 전체 녹화: 카드 영역 좌표로 자르지 않고 캡처한 탭 화면 전체(헤더·Alerts 포함)를 1280×720에 비율 유지로 그립니다. beacon 좌표가 필요 없어져 '화면 재연결 중' 안내 프레임과 video-reconnecting gap을 없앴고, monitor 새로고침 중 화면도 그대로 녹화됩니다. 영상 gap은 화면 공유 중지만 남습니다. 아래 1~3번 섹션의 크롭·재연결 안내 설명은 이전 설계입니다.
브랜치 PPI-1376 · 커밋 c2abbc2b · PR #1182 (develop 대상, 미병합). 결과는 S3에 올리지 않고 녹화 창에서 로컬 다운로드합니다. 탭 전체를 단일 녹화하는 이전 안은 모니터 탭 화면·오디오 녹화 구현 계획을 참고하세요.
확정된 정책
| 항목 | 값 |
|---|---|
| 아동별 파일 | 아동 마이크 + 해당 AI 음성을 섞은 파일 1개 (room 단위, 파일명 = roomId) |
| 최대 녹화 길이 | 30분 — 도달 시 자동 종료·다운로드 (stopReason: "max-duration") |
| 최대 아동 수 | 4명 — 5번째부터 녹음하지 않고 skippedRooms·화면 경고 |
| 녹화 전 대기 | 화면 선택 후 10분 안에 녹화를 시작하지 않으면 연결 정리 |
| 보존 기간 | 90일 후 자동 삭제 — 2단계 S3 lifecycle rule로 적용 (1단계는 로컬 파일만) |
실제 구조
그룹 모니터 탭 /monitor-dashboard/{groupId}
├ 헤더 '녹화' 버튼 → window.open(/monitor-recorder/{groupId}?recordingId=…)
└ useMonitorRecordingBeacon → BroadcastChannel("ppi-monitor-recording:{id}")
500ms마다 pageGeneration · 접속 아동 rooms · 청취 · 영상 스텝 상태 (rect는 송신하지만 미사용)
녹화 창 /monitor-recorder/{groupId} ← monitor-dashboard layout 밖
├ '캡처 시작' → AudioContext 생성(동기) → getDisplayMedia → monitor 탭 선택
├ 영상: 캡처 video(탭 화면 전체) → canvas 1280×720 비율 유지(15fps, setInterval) → MediaRecorder(vp8)
├ 오디오: room마다 RecorderRoomAudio (role monitor, peerId recorder-…, displayName "")
│ → consumeKinds ["audio"] → 아동별 믹서(mic + AI, 스피커 미연결) → MediaRecorder(opus)
└ 종료 → video.webm · {roomId}.webm · manifest.json 다운로드 → 채널에 ended
설계 중 바뀐 결정과 이유
| 결정 | 이유 (코드 근거) |
|---|---|
녹화 route를 /monitor-recorder/[group]로 분리 | app/monitor-dashboard/layout.tsx의 useMonitorSocket이 MONITOR_CONNECTED를 보내고, 서버(connection-handlers.ts:1756)가 displayName = principal.name presence peer를 등록 → 녹화 창이 진행자 목록에 한 명 더 노출됨. 인증은 proxy.ts 가드에 prefix 추가 |
| 수신 전용 = 기존 JOIN 그대로 + START 이벤트 미전송 | JOIN_ROOM만으로는 claim이 생기지 않음. 빈 displayName은 getConnectedHosts의 !peer.displayName 조건으로 제외. Socket 서버 변경 없음 |
useMediasoupConsumer에 consumeKinds 선택 옵션 | 기존 producer·new-producer 두 경로에서만 필터. 미지정 시 기존 동작 동일(기존 호출부 무변경) |
믹서 입력마다 muted <audio> keepalive | Chrome crbug.com/121673 — WebRTC stream을 Web Audio로만 연결하면 무음. session-audio-player.tsx의 기존 우회와 동일 |
| 화면 선택 전부터 room 연결, 녹음은 끊지 않음 | 시작 직후 아동 음성 유실 방지. 입력이 없는 구간도 무음으로 기록해 파일 길이 = 경과 시간 → startOffsetMs 하나로 싱크 |
| 화면 선택 요청 세대(generation) | 선택 창·재생 대기 중 취소·종료되면 늦은 승인을 무효화(track 즉시 stop). 닫힌 AudioContext로 준비 상태가 되살아나는 문제 차단 |
| 진행 중 녹화 창은 focus만 | 같은 이름 창에 URL을 다시 넣으면 재탐색으로 녹화 버퍼 유실. 새로고침 후에는 window.open("", name)으로 핸들만 획득 |
코드 위치
| 파일 | 책임 |
|---|---|
apps/web/features/monitor-recording/model/use-monitor-recording-session.ts | 녹화 창 상태 머신(idle→capturing→recording→stopping→done), room 등록·4명 제한, 30분·10분 타이머, manifest·다운로드 |
…/model/use-video-crop-recorder.ts | getDisplayMedia, 탭 화면 전체 그리기 루프, 공유 중지 안내 프레임, 선택 세대, 출력 정리 |
…/model/use-monitor-recording-beacon.ts | monitor 탭 beacon 송신, sessionStorage 재개, 녹화 창 열기/focus |
…/model/child-audio-mixer.ts | 아동별 mic/AI 입력 교체·keepalive, AudioContext 정지 감시 |
…/model/{recording-channel, crop-geometry, video-frame-state, gap-tracker, recording-manifest, chunk-recorder}.ts | 메시지 검증·세대, 좌표 환산·letterbox, 영상 상태, gap, manifest, MediaRecorder 래퍼 |
…/ui/recorder-room-audio.tsx | room별 수신 전용 SFU 연결 → 믹서 입력 |
apps/web/app/monitor-recorder/[group]/page.tsx | 녹화 route |
첫 실측 (2026-10-19, Chrome 155 · 아동 1명 · 42.9초)
| 항목 | 결과 |
|---|---|
| 영상·오디오 길이·오프셋 | 둘 다 약 42.9초. startOffsetMs 영상 26.5 / 오디오 42.9 (차이 약 16ms) |
| 아동 오디오 | 무음 아님 — mean −30.4dB, max −6.8dB, 2초 이상 무음 구간 없음 (keepalive 효과로 추정) |
| AI 음성 | 녹화 전 구간 입력 없음(audio-input-missing source ai 0~42.9초). AI 미발화·수업 방식상 ai-audio producer 부재·수신 문제 중 미확정 |
| 마이크 끊김 | 약 10ms씩 3회 — 수신 track 재연결 흔적으로 추정 |
| 파일 길이 정보 | MediaRecorder WebM 특성상 duration=N/A → 재생 뷰어에서 탐색 막대 보정 필요 |
검증 상태
1단계 한계: 녹화 데이터는 녹화 창 메모리에만 있습니다. 녹화 창을 닫거나 새로고침하면 유실되며(경고만 표시), 30분 영상은 수백 MB까지 커질 수 있습니다. 탭 복제 시 beacon 세대가 복제 탭으로 넘어가는 문제와 다중 다운로드 허용 창은 미해결(P2)입니다.
이후 진행
진행자 뷰어·로컬 폴더 저장·영상 스텝 소리 재구성은 아래 0-2번 섹션에 구현 내용을 정리했습니다. 녹화 형식은 MP4를 검토했다가 서버 SFU 녹화와 맞추기 위해 WebM(VP8·Opus)으로 확정했습니다.
0-2. 로컬 폴더 저장 · 수업 녹화 뷰어 · 영상 스텝 소리 (2026-10-20)
커밋 9a06b3c6 (로컬 저장·뷰어) · 65a63596 (영상 스텝 소리) · 5d16e451 (안정성 보완) · PR #1182. S3 업로드는 아직 없고, 2단계에서 저장소만 S3로 바꾸면 되도록 폴더 구조를 S3 키와 맞췄습니다.
확정된 결정
| 항목 | 결정과 이유 |
|---|---|
| 녹화 형식 | WebM 우선(영상 VP8 → VP9, 오디오 Opus), MP4는 대체. 아동 카메라·마이크·AI가 SFU로 VP8·Opus로 들어와 서버 녹화가 재인코딩 없이 WebM에 담을 수 있고, 뷰어는 Chrome이기 때문. MP4로 저장하려면 VP8→H.264 재인코딩이 필요해 서버 CPU 부하가 큼 |
| 로컬 하위 폴더 | <a download>는 경로를 만들 수 없어 File System Access API(showDirectoryPicker) 사용. 고른 폴더 핸들은 IndexedDB에 보관해 뷰어 탭도 같은 폴더를 읽음 |
| 폴더 선택 시점 | 캡처 시작 전. 폴더 선택 창과 화면 선택 창은 각각 사용자 클릭이 필요해 별도 버튼으로 분리하고, 폴더를 고르기 전에는 '캡처 시작' 비활성 |
| 탐색 보정 | fix-webm-duration로 길이 정보 기록. 원본·manifest를 먼저 쓰고 200MB 이하 파일만 나중에 덮어씀(보정 중 메모리 급증으로 탭이 죽어도 원본 보존) |
| 영상 스텝 소리 | 아동 단말의 영상 소리는 SFU에 없고 에코 제거로 지워짐 → 재생 기록으로 재구성(아동 단말 부하 0). 원본 영상 소리를 뷰어가 재생 |
폴더 구조
{선택 폴더}/local/monitor-recordings/{groupId}/{recordingId}/
final/video.webm
final/audio/{userId}/{roomId}.webm
manifest.json ← 마지막에 기록. 없으면 뷰어가 무시(부분 저장 폴더)
Chrome은 홈·다운로드·문서·데스크탑 폴더 자체는 선택을 막습니다("시스템 파일 포함"). 그 안에 새 폴더(예: ppi-recordings)를 만들어 고릅니다. 녹화마다 새 recordingId 폴더가 생기므로 이전 녹화를 지울 필요가 없습니다.
manifest 추가 필드
| 필드 | 용도 |
|---|---|
tracks[].path, displayName | 파일 위치(루트 기준), 아동 이름 |
listeningEvents [{atMs, roomId, enabled, volume}] | 모니터 카드 청취 ON/OFF·볼륨 변화. 뷰어 '진행자 기준' 재생에 사용(진행자가 켜 둔 의도 상태, 최대 약 0.5초 지연) |
mediaEvents [{atMs, roomId, activityIndex, stepIndex, mediaType, playing, unmuted, videoStartedAt}] | 영상 스텝 재생 상태. mediaType(resource:video_X → video_X.mp4)을 그대로 남겨 수업 후 활동이 수정돼도 원본을 찾음 |
뷰어 진입과 화면
세션 로그(/main/log) 아동·회차 선택 → '수업 녹화 보기'(새 탭)
→ /main/log/recording?userId=…&lessonIndex=…
→ 폴더의 manifest 중 roomId = {userId}_{lessonIndex} 녹화를 최신순으로 찾음(여러 개면 목록)
→ 재생 대상: 진행자 기준(당시 청취 설정) / 아동별(그 아동 소리만)
- 영상(카드 화면)이 기준 시계. 아동 음성·영상 스텝 소리는 아동별 gain 하나로 묶어 출력하고, 250ms마다 gain 갱신·500ms마다 100ms 넘는 어긋남 보정
- 재생·정지, ±10초, 배속, 음량, 타임라인 클릭 탐색, Space·←·→. 실제 시각(KST) 표시. 타임라인: 전체화면 녹화 구간, 아동 음성(끊김 빗금), 영상 스텝 소리 구간(주황)
- 녹화 폴더 없음·권한 필요·녹화 없음은 안내 화면. 최소정보(아동 카메라)는 서버 녹화 이후 제공
영상 스텝 소리 재구성 흐름
모니터 카드(useHostSocket: guestCurrentStep · guestLayout.mediaType · isVideoPlaying · isGuestVideoUnmuted) → store roomMedia (재생 시작 시 request-video-elapsed로 시작 시각 계산, 0이면 1초 간격 최대 3회 재요청) → beacon media (값이 바뀌면 즉시 송신) → manifest.mediaEvents → 뷰어: 재생 구간 계산 → POST /api/resources/urls → <audio crossOrigin> → 아동 gain
서버의 videoPlayStartedAt은 스텝당 첫 재생 시각만 유지하고, guest-video-end는 모니터로 오지 않습니다. 구간 끝은 스텝·mediaType 변경이나 재생 종료로 판단합니다. 경과 시간은 모니터 제어권(그룹 claim 포함)이 있어야 돌려받습니다(monitor-control-auth.ts).
한계: 아동 단말의 버퍼링 정지·일시정지 자동 재개·디코딩 과부하 건너뛰기는 반영하지 않아 그만큼 영상 소리가 앞설 수 있습니다(현재 모니터 카드와 같은 수준). 친구 선택 미리보기 영상 소리는 제외. S3 CORS(crossOrigin 재생)는 실기기 확인 전입니다.
검증 상태
코드 위치
| 파일 | 책임 |
|---|---|
features/monitor-recording/model/{recording-paths, recording-store-handle, recording-directory-writer, persist-recording, webm-duration}.ts | 경로, 폴더 핸들·권한, 파일 쓰기, 저장 순서·길이 보정 |
features/monitor-recording/model/{listening-events, media-events}.ts | 청취·영상 상태 변화 기록 |
features/recording-viewer/model/{find-recordings, listening-gain, playback-sync, timeline-segments, video-audio-segments, viewer-model}.ts | 녹화 찾기, 진행자 기준 gain, 싱크 계산, 타임라인, 영상 소리 구간 |
features/recording-viewer/model/{use-recording-library, use-recording-player, use-video-audio-urls}.ts | 폴더 읽기, 재생·싱크, 원본 URL |
shared/lib/room-media-state.ts, stores/use-monitor-data-store.ts, features/session/ui/session-card.tsx | 카드 청취·영상 상태(roomListening·roomMedia) |
app/main/log/recording/page.tsx, components/pages/session-log.tsx | 뷰어 route, '수업 녹화 보기' 버튼 |
0-3. S3 업로드 · 서버 기반 녹화 목록 (2a, 2026-10-20)
커밋 6c515d77 · PR #1182. 녹화·manifest·플레이어는 그대로 두고 저장·조회 계층만 S3와 서버 API로 바꿨습니다. 녹화 중 조각 업로드(2b)는 다음 단계입니다.
흐름
녹화 종료 → 파일마다 [upload-url 요청 → S3 presigned PUT (진행률)] → manifest PUT → complete
↓ 실패
기존 로컬 다운로드로 대체
complete → 서버가 S3 manifest 검증 + 파일 존재·크기·형식 확인 → 세션 로그에 아동 room별 색인 행
뷰어 → 목록 API → 상세 API(manifest + 재생 URL 1시간) → 기존 플레이어
저장 위치
s3://ppi/{stage}/monitor-recordings/{groupId}/{recordingId}/
final/video.webm
final/audio/{userId}/{roomId}.webm
manifest.json
{stage} = Web 서버 STAGE (prod · staging · dev). 서버가 붙이며 클라이언트가 지정하지 않음
API (모두 withAuthMember + 담당 범위 확인)
| API | 역할 |
|---|---|
POST /api/monitor-recordings/upload-url | 그룹·아동 room 권한 확인 후 서버가 만든 키로 presigned PUT 발급(15분). recordingId UUID, 경로 조각 문자 검증, 형식(webm·mp4·json)·크기(영상 2GB·오디오 300MB·manifest 1MB) 제한 |
POST /api/monitor-recordings/complete | manifest 검증(경로는 서버가 다시 계산) → S3 HeadObject로 실제 크기·형식 확인 → 아동 room별 색인 행. 다른 그룹 녹화로 등록된 행은 조건부 쓰기로 거부(409), 형식이 맞지 않는 room은 등록에서만 제외 |
GET /api/monitor-recordings?userId&lessonIndex | 해당 아동·회차 녹화 목록(최신순). begins_with(id, "monitor-recording-")로 녹화 행만 조회 |
GET /api/monitor-recordings/{recordingId} | manifest + 재생 URL. 권한 없는 다른 아동의 트랙·청취·영상 이벤트는 제외. manifest가 지워졌으면 만료 |
세션 로그 색인 행
ppi-session-log-{stage} 테이블에 userId + id = monitor-recording-{recordingId}, type: "monitor_recording", message = manifest 키, recordingId·groupId·durationMs. 세션 로그 화면은 이 행을 대화 행으로 표시하지 않습니다. 새 테이블·Terraform 작업은 없습니다.
그 밖의 결정
- 업로드는 파일당 단일 PUT(S3 한도 5GB). multipart는 IAM Abort 권한·미완료 정리 규칙이 필요해 2b로 미룸
- 임의 키를 받는 S3 헬퍼는
"use server"파일(lib/s3.ts)에 두면 서버 액션으로 노출될 수 있어 서버 전용 모듈lib/monitor-recording/recording-s3.server.ts로 분리 - 뷰어 음성
<audio>에crossOrigin="anonymous"(S3 교차 출처 + Web Audio). 재생 URL 만료 시 재생 위치를 유지한 채 재발급(50분에 1회) - 로컬 폴더 저장·조회는 개발 환경에서
?store=local/?source=local일 때만 - 업로드에 성공해도 녹화 창을 닫기 전까지는 완료 화면에서 파일을 직접 내려받을 수 있음
배포 전 수동 설정(코드 밖): 버킷 ppi CORS(앱 origin PUT·GET·HEAD, ETag·Content-Range·Accept-Ranges 노출)와 prod|staging|dev/monitor-recordings/ 90일 lifecycle. 버킷 설정은 저장소에 없어 기존 규칙을 받아 병합 후 적용해야 합니다(put 명령은 전체 교체). 운영 IAM 사용자 권한은 저장소에서 확인 불가.
검증 상태
별도 티켓으로 분리한 기존 보안 문제: DELETE /api/session-logs(인증 없음·임의 S3 키 삭제), POST /api/recording-download(인증 없음·임의 키 다운로드 링크), 세션 로그 POST·PATCH(인증 없음), GET(아동 범위 미확인).
1. 무엇을 남기나요?
영상·활동·상태
영상·활동·상태
녹화 제외
현재 화면에 보이는 카드 영역을 한 영상으로 남깁니다. 스크롤 밖의 카드를 자동으로 펼쳐 담는 기능은 범위에 포함하지 않습니다.
카드 영역 전체 · 오디오 없음
A 마이크 + A AI 음성
B 마이크 + B AI 음성
기본안은 아동마다 마이크와 AI를 섞은 대화 오디오입니다. 아동 마이크만 보존하거나 원본 음성을 각각 보존하는 정책은 구현 전에 확정합니다. 파일 외에 manifest.json으로 영상과 음성을 연결합니다.
2. 누가 녹화를 담당하나요?
카드 영역 위치·크기 전달
녹화 상태 표시 및 시작 진입
아동별 오디오 직접 구독
영상·오디오 녹음 및 업로드 큐
업로드 URL 발급 · 상태 관리
최종 영상·오디오·manifest 저장
녹화 페이지는 작은 별도 창이나 탭으로 열고 끝날 때까지 유지합니다. 처음에는 그 페이지의 ‘캡처 시작’을 사용자가 클릭하여 Chrome 선택창에서 monitor 탭을 선택합니다. 창·전체 화면 캡처는 초기 지원 범위에서 제외해 좌표 변환을 단순하게 합니다.
별도 창에서 다른 monitor 탭을 캡처한 뒤
CropTarget을 전달하면 바로 크롭할 수 있다고 확정하면 안 됩니다. Chrome 공식 Region Capture 문서는 self-capture 제한을 명시합니다. 현재 Chrome에서의 실제 지원은 PoC로 검증하고, 기본 대안은 캡처 영상을 녹화 페이지의 canvas에서 좌표로 잘라 녹화하는 방식입니다. 팝업 최소화·백그라운드 상태에서도 프레임이 유지되는지는 별도 통과 조건입니다.영상 경로
monitor 탭 → getDisplayMedia({ video: true, audio: false })
→ 수신 video → 카드 좌표로 canvas에 그리기
→ canvas.captureStream() → 영상용 MediaRecorder
좌표는 카드 컨테이너의 화면상 경계와 viewport 크기를 전달하고, 수신 영상 해상도에 맞춰 환산합니다. 고정된 출력 해상도에 비율을 유지해 배치합니다. 스크롤·창 크기·줌 변경을 감지하고, 좌표가 오래되거나 탭 식별이 맞지 않으면 전체 화면 대신 ‘화면 재연결 중’ 프레임을 기록합니다.
오디오 경로 — 청취와 녹음은 독립적
SFU의 A 마이크 ─┐
├→ A 전용 Web Audio 믹서 → A MediaRecorder → A.webm
SFU의 A AI 음성 ─┘
SFU의 B 마이크 ─┐
├→ B 전용 Web Audio 믹서 → B MediaRecorder → B.webm
SFU의 B AI 음성 ─┘
monitor의 청취 버튼 → 운영자 스피커 음량만 제어
녹화 페이지는 Mediasoup에서 아동별 트랙을 직접 수신합니다. 믹서는 MediaStreamAudioDestinationNode로 연결하고 스피커 출력에는 연결하지 않습니다. 재접속 시 같은 믹서에 새 입력을 연결해 출력 트랙을 유지합니다. monitor가 받은 스트림을 넘겨 쓰는 방식으로는 monitor 새로고침 시 오디오 연속성을 보장할 수 없습니다.
추가 consumer는 네트워크 사용량을 늘립니다. 녹화 페이지는 오디오만 구독하고, 제어 권한을 가져오거나 기존 monitor를 밀어내지 않는 수신 전용 연결이 필요합니다. 현재 monitor hook을 그대로 재사용하기 전에 권한·claim·join·disconnect 부작용을 확인해야 합니다.
3. monitor를 새로고침하면 어떻게 되나요?
- 녹화 페이지는 열려 있으므로 녹화 실행부를 유지합니다.
- monitor의 heartbeat가 끊기면 영상 출력은 안내 프레임으로 바꿉니다. 숨긴 화면을 계속 정상 화면처럼 표시하지 않습니다.
- monitor가 로드되면 recordingId로 재연결하고 새 카드 좌표·페이지 세대를 전달합니다.
- 탭 식별과 좌표를 확인한 후 영상 출력을 복구하고 중단 구간을 기록합니다.
재선택 없이 복구하는 것이 목표입니다. 대상 탭의 새로고침 시 캡처 유지와 자동 복구는 지원 Chrome에서 실제 검증해야 합니다. 탭 종료·공유 중지·브라우저 종료는 자동 복구 대상이 아니며 다시 사용자 선택이 필요합니다. 녹화 페이지 자체를 새로고침해도 권한과 실행 중 MediaRecorder가 보존되지는 않습니다.
페이지 간 메시지는 같은 origin과 발신 창·녹화 ID·세대를 검증합니다. 재연결은 BroadcastChannel 또는 검증된 postMessage로 구현하고 오래된 좌표 메시지는 무시합니다. 오디오가 실제로 끊기면 무음과 gap 이벤트를 남기며 수신되지 않은 음성을 복원한 것으로 표시하지 않습니다.
4. 녹화가 끝날 때까지 파일을 메모리에 쌓지 않습니다
영상 / A / B 각각 순번 부여
presigned PUT → S3
조립 → 최종 파일 확인
간격은 초기 제안값입니다. timeslice는 정확한 타이머가 아니므로 순번만으로 시간을 계산하지 않고 실제 미디어 타임스탬프와 공통 기준 시간을 사용합니다. 오디오 믹서·영상 recorder의 시작 차이를 오프셋으로 남깁니다.
{stage}/monitor-recordings/{groupId}/{recordingId}/
raw/video/{segmentId}/000001.bin
raw/audio/{userId}/{sessionId}/{segmentId}/000001.bin
final/video.webm
final/audio/{userId}/{sessionId}.webm
manifest.json
조각은 독립 재생 파일이 아니므로 .bin으로 예시했습니다. 실제 MIME 타입은 따로 기록합니다. recorder가 다시 시작되면 새 segmentId를 부여하고, 서로 다른 recorder의 바이트를 무조건 이어 붙이지 않습니다. 파일 완성 작업은 같은 recorder의 순서를 보존하고, 필요하면 remux·재인코딩 및 시간 배치를 수행합니다.
| 상황 | 처리 |
|---|---|
| 전송 성공 | 서버가 해당 조각 업로드를 확인하고 완료 목록에 기록한 후 로컬 복사본 삭제 |
| 네트워크 실패 / URL 만료 | 조각 유지 → 같은 키로 재시도 / URL 재발급. 새 파일 중복 생성 방지 |
| 전송 적체 / 저장 용량 부족 | 대기 바이트·저장 용량 표시, 상한 도달 시 명시적으로 녹화 중단·partial 처리 |
| 종료 클릭 | 마지막 dataavailable → 전송 큐 비우기 → 서버 완료 검증 → 파일 완성 작업 |
| 녹화 창 강제 종료 | 이미 업로드한 조각과 IndexedDB를 기반으로 복구 시도. 마지막 미생성·미저장 조각은 유실 가능 |
초기안은 기존 presigned PUT 패턴에 맞춘 조각별 S3 객체 + 서버 파일 완성 작업입니다. S3 Multipart 방식도 가능하지만 마지막 part를 제외하고 5 MiB 이상을 묶어야 하며, 작은 오디오 조각을 그대로 part로 보낼 수 없습니다. 이 대안은 API·중단 복구·운영 비용을 비교한 뒤 선택합니다.
상태는 ‘녹화 중’과 ‘저장 완료’를 구분
preparing → recording → uploading → finalizing → completed
└──── 실패·강제 종료·누락 ───→ partial / failed
녹화 중에도 업로드는 병행합니다. 여기서 uploading은 녹화 종료 후 남은 전송을 기다리는 상태입니다. 서버가 누락·크기·객체 존재·최종 재생 파일을 검증하기 전에는 completed로 표시하지 않습니다.
5. 영상과 A·B 음성을 어떻게 맞추나요?
‘같은 시각에 시작 버튼을 눌렀다’만으로는 정확히 맞지 않습니다. 녹화 페이지의 단조 증가 시계를 공통 기준으로 삼고 각 미디어의 실제 시작 차이를 기록합니다. 장시간 녹화의 시계 차이도 검증합니다.
| 저장 위치 | 필드와 의미 |
|---|---|
| DB 요약 | recordingId, groupId, classDate, 녹화자, 시작·종료 시각, 상태, manifestKey. 목록 조회와 접근 권한 판단용 |
| manifest 기본 | schemaVersion, recordingId, startedAt, durationMs, 출력 해상도, 브라우저 정보 |
| manifest 트랙 | trackId, userId, roomId, sessionId, lessonIndex, 종류(video / child-mix), source 구성, S3 키, MIME·코덱, startOffsetMs, endOffsetMs |
| manifest 구간 | segmentId, 순번, 타임스탬프, 크기, 체크섬, 재접속·무음·화면 재연결 구간. 중간 합류·퇴장도 기록 |
예를 들어 B가 영상 시작 30초 뒤 합류했다면 B 오디오의 startOffsetMs=30000으로 배치합니다. 장시간 파일은 컨테이너 길이·탐색과 실제 기준 시각의 드리프트를 확인합니다. presigned URL은 만료되므로 DB에는 URL 대신 S3 키를 저장합니다.
6. 현재 코드에서 재사용할 부분과 새로 만들 부분
| 구분 | 확인한 근거 / 제안 |
|---|---|
| 청취 OFF 동작 · 확인 | apps/web/features/session/ui/session-card.tsx:172에서 isAudioEnabled만 변경. session-audio-player.tsx:139에서 masterGain을 0으로 조절합니다. 청취 OFF로 수신 트랙을 해제하지 않습니다. |
| 오디오 수신 · 확인 | apps/web/entities/monitor-session/model/use-monitor-session.ts:263에서 useMediasoupConsumer 호출. apps/web/hooks/mediasoup/use-mediasoup-consumer.ts:149의 PeerStream은 audioStream과 aiAudioStream을 분리합니다. |
| 전송 패턴 · 확인 | apps/web/lib/s3.ts:307의 로그 조각 presigned PUT, apps/web/hooks/use-resource-upload.ts:63의 URL 요청 → S3 직접 업로드 흐름 참고 |
| 기존 수업 녹음 · 확인 | apps/socket/src/recording/s3Uploader.ts:69는 서버 파일을 MP3로 직접 업로드. 이번 브라우저 WebM·그룹 녹화의 저장 경로와 구분해야 합니다. |
| 신규 구현 · 제안 | 녹화 페이지, 수신 전용 오디오 구독, 캡처·크롭, 녹화기·IndexedDB 큐, 녹화 API·DB, S3 조각·manifest, 파일 완성 작업, 상태 UI |
제안 API 계약
POST /api/monitor-recordings 녹화 생성
POST /api/monitor-recordings/{id}/upload-url 조각 URL 발급
POST /api/monitor-recordings/{id}/parts 업로드 조각 확인
POST /api/monitor-recordings/{id}/complete 최종화 요청(중복 호출 허용)
GET /api/monitor-recordings/{id} 상태·결과 조회
서버는 녹화 소유자·그룹 접근 권한·참여 아동을 검증하고 S3 키를 생성합니다. 임의 키·임의 버킷 업로드를 허용하지 않습니다. URL은 전송 직전에 짧게 발급하고 허용 MIME·파일 크기·조각 수를 제한합니다. S3 CORS는 앱 origin의 필요한 PUT·GET·헤더만 허용하며, 녹화 버킷 경로는 비공개로 유지합니다. 보존 기간과 삭제 정책은 운영 정책으로 확정합니다.
실제 지원 Chrome에서 별도 탭 캡처·monitor 새로고침·좌표 크롭·백그라운드·오디오 중복 구독을 검증합니다. 실패하면 전용 녹화 뷰 또는 확장 프로그램 대안을 결정합니다.
카드 범위 정의 → 영상 출력 → 아동별 믹서 → 공통 시계·재접속 이벤트 → 로컬 큐를 연결합니다.
권한·presigned API → 순번별 업로드 → 최종화 worker → manifest·DB → 실패·재시도·partial 복구를 구현합니다.
녹화 시작·경과 시간·아동별 수신 상태·대기 업로드·종료·저장 결과를 표시합니다. API·socket·실제 장치 없이 상태를 재현하는 Storybook fixture와 정적 빌드를 검증합니다.
이 문서는 구현 전 설계 자료입니다. runtime 변경 전 repository-local brainstorming에서 설계 승인을 받고 code-quality-guardian에 따라 baseline·필요 하네스를 마련합니다. 구현 후 guardian-gate 코드 리뷰를 수행합니다.
7. 이 조건을 통과해야 완료입니다
| 검증 상황 | 기대 결과 |
|---|---|
| A·B 동시 녹화 | 무음 영상 1개 + 서로 섞이지 않은 아동별 오디오 2개 + manifest |
| 청취 OFF·볼륨 0% | 운영자 스피커만 무음. 녹음 파일에는 해당 아동·AI 음성 유지 |
| monitor 새로고침 | 녹화 페이지 생존, 오디오 수신 유지, 화면 안내 후 자동 복구. 재선택 여부와 유실 시간을 실제 기록 |
| 스크롤·줌·창 크기·Alerts 열기 | 영상은 카드 경계만 포함. 낡은 좌표나 잘못된 탭이면 안내 프레임으로 전환 |
| 탭 전환·최소화·백그라운드 | 지원 환경에서 프레임·오디오 유지. 실패 시 해당 사용 조건을 제한하고 UI에 표시 |
| 중간 합류·퇴장·SFU 재접속 | 아동·세션 매핑과 오프셋 정확, 새 입력 트랙 연결, 빈 구간 명시 |
| 동기화 | 클랩 등 공통 이벤트로 시작·중간·끝을 비교. 초기 목표 오차 200ms 이내를 제안하며 PoC 후 승인 |
| 긴 녹화 | 최대 예정 수업 길이로 메모리·저장 용량·CPU·드리프트·영상 탐색·파일 완성 시간 검증 |
| 업로드 실패·URL 만료·중복 완료 | 동일 조각 재전송, 최종화 중복 방지, 누락 상태에서 completed 금지 |
| 공유 중지·녹화 창 종료·저장 용량 부족 | 유실 범위를 표시하고 partial 보존. ‘완전 복구’로 오인시키지 않음 |
| 권한·독립 수신 | 다른 그룹 업로드 거부. recorder 연결로 기존 monitor 제어권을 빼앗지 않음 |
8. 확정할 정책과 참고 자료
2026-10-19 확정: AI 포함 혼합 파일, 최대 30분·아동 4명, 90일 자동 삭제 (0번 섹션 참고). 아래는 원래 목록입니다.
구현 전 확정: 아동별 파일에 AI 포함 여부, 최대 녹화 길이·동시 아동 수, 보존·삭제 기간, 새로고침 중 영상 안내 방식, 재생 UI 제공 범위, 파일 완성 worker 실행 환경·비용, 지원 Chrome·OS와 허용 백그라운드 조건.
원본 조각 삭제는 최종 파일 검증과 복구 보존 기간이 지난 뒤에 수행합니다. 파일 완성 worker는 동시 실행 제한·시간 제한·멱등성을 갖추고 실패 시 원본을 유지합니다.
후속 설계: ppi-monitor-app — 진행자 데스크톱 앱 설계 — 이 녹화 페이지를 Electron 숨김 창으로 재사용해 탭 선택 없이 자동 녹화하는 안.
- Chrome Region Capture — 크롭 방식과 self-capture 제한. 다른 탭 자동 크롭을 전제로 하지 않는 근거
- Chrome 화면·오디오 캡처 — 캡처 실행 문서의 수명과 확장 프로그램 대안
- W3C MediaStream Recording — 개별 Blob의 독립 재생 미보장
- AWS S3 Multipart 제한 — 마지막 part 외 최소 5 MiB
코드 근거는 2026-10-17 로컬 PPI checkout 정적 확인입니다. STG 녹화 PoC·패킷 수신·브라우저 수명·최종 파일 재생은 아직 검증하지 않았습니다.
Claude용 핵심 맥락
PPI 모니터 카드 녹화 기능의 구현 전 제안이다. 결과물은 카드 영역의 무음 영상 1개와 아동별 대화 오디오 N개, 동기화 manifest다. 기본 오디오는 각 아동 마이크+해당 AI 음성 혼합이며 정책 확정이 필요하다. 현재 청취 OFF는 masterGain을 0으로 만들 뿐 Mediasoup 수신을 해제하지 않는다.
monitor 새로고침과 녹화 수명을 분리하기 위해 별도 녹화 페이지가 탭 캡처와 오디오 직접 구독을 담당한다. 다른 탭 Region Capture는 지원을 확정하지 않으며 좌표 기반 canvas 크롭을 기본 대안으로 검증한다. 새로고침 자동 복구·최소화·백그라운드 연속성은 PoC 통과가 필요하다. 녹화 페이지가 기존 monitor 제어권을 가져오지 않도록 수신 전용 연결을 설계한다.
recordingId로 영상·음성을 묶고 IndexedDB 임시 큐→조각별 presigned PUT→S3→서버 파일 완성 작업으로 저장한다. 개별 MediaRecorder Blob의 독립 재생은 보장되지 않는다. 재시작마다 segmentId를 분리하고 manifest에 아동·세션 ID, 시작 오프셋, gap을 남긴다. 최종 파일 검증 전 completed 금지.
2026-10-19 1단계 PoC 구현(PR #1182, 커밋 c2abbc2b): 녹화 route는 /monitor-recorder/[group]으로 monitor-dashboard layout 밖(MONITOR_CONNECTED presence 회피). room별 JOIN(role monitor, peerId recorder-{hostId}-{roomId}-{recordingId}, displayName "")+consumeKinds ["audio"], 아동별 mic+AI 믹서(muted audio keepalive, crbug 121673), canvas 크롭 1280x720 15fps, BroadcastChannel beacon 500ms·stale 2s, 로컬 다운로드(video.webm·{roomId}.webm·manifest.json). 정책 30분·4명·대기 10분·90일 삭제(2단계 S3). 첫 실측에서 아동 오디오 정상, AI 입력은 전 구간 없음(원인 미확정), WebM duration N/A. S3 업로드·IndexedDB 큐·finalize는 미구현.
2026-10-20 추가(9a06b3c6·65a63596·5d16e451): 형식은 WebM(VP8·Opus) 우선으로 확정(서버 SFU 녹화가 VP8·Opus를 재인코딩 없이 저장 가능, 뷰어 Chrome). 녹화를 File System Access API로 고른 로컬 폴더에 S3 키와 같은 구조(local/monitor-recordings/{groupId}/{recordingId}/final/…, manifest 마지막)로 저장하고, fix-webm-duration은 원본 저장 후 200MB 이하만 덮어씀. manifest에 path·displayName·listeningEvents(카드 청취 ON/OFF·볼륨)·mediaEvents(영상 스텝 상태, mediaType으로 원본 파일 식별) 추가. 세션 로그 '수업 녹화 보기' → 새 탭 /main/log/recording이 roomId={userId}_{lessonIndex} 녹화를 최신순으로 찾아 재생. 진행자 기준은 listeningEvents로 아동별 gain 재현, 아동 음성과 영상 스텝 소리(원본 /api/resources/urls, crossOrigin audio)는 아동별 gain 공유. 영상 시작 시각은 request-video-elapsed(claim 필요, 0이면 3회 재요청)로 계산, 아동 단말 버퍼링·일시정지는 미반영.
2026-10-21: 영상은 카드 영역 크롭 대신 탭 화면 전체를 1280x720 비율 유지로 녹화(beacon 좌표 미사용, 재연결 안내 프레임·video-reconnecting gap 제거, 공유 중지 gap만). 2026-10-20 S3 업로드 2a(6c515d77): 녹화 종료 시 파일별 presigned PUT으로 s3://ppi/{STAGE}/monitor-recordings/{groupId}/{recordingId}/에 올리고 complete에서 서버가 manifest 검증·HeadObject 크기/형식 확인 후 ppi-session-log에 아동 room별 색인 행(type monitor_recording, id monitor-recording-{recordingId}, 다른 그룹 행은 조건부 쓰기로 거부)을 씀. API 4개(upload-url·complete·목록·상세) 모두 withAuthMember+resolveCanonicalMonitorScope. 상세는 권한 없는 다른 아동 트랙 제외, 재생 URL 1시간(만료 시 위치 유지 재발급). 실패 시 다운로드 대체, 로컬 폴더는 개발용(?store=local/?source=local). S3 CORS·90일 lifecycle은 수동 설정 필요.