문서 역할: 과거 설계와 구현 이력

2026-11-11 코드 대조 · 로컬 ppi develop b0e1e91c

이 문서는 2026-10-28까지의 설계·구현 이력이다. 브랜치 구조의 대표 설명은 PPI-1376 브랜치 전체 정리, 아동 미접속 저장·재입장·재전송의 후속 제안은 후속 설계를 따른다. 아래 별도 녹화 창·로컬 저장 설명은 당시 접근의 기록이며 현재 권장 구조를 뜻하지 않는다.

코드와 커밋을 대조한 문서 업데이트이며 운영 환경·실기기 검증은 포함하지 않는다.

← PPI 문서 목록

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.ts
apps/web/features/monitor-recording/model/request-recorder-retry.ts
최초 실패를 포함한 상태 발행과 소유자 대상 재시도 명령을 처리합니다.
apps/web/features/monitor-recording/ui/group-recording-controls.tsx
apps/web/features/monitor-recording/ui/monitor-focus-recording-status.tsx
apps/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실제 녹화 훅과 종료 판정을 합성 저장소·앱 브리지로 실행해 마지막 아동 종료와 예약 하드컷을 재현합니다.

검증 결과와 재실행 명령

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앱의 영상 녹화 시작시각. 웹 오디오의 시작시각과 구분
scheduledStartTimesroomId별 당시 예약일시 ISO map. 표시할 때 KST로 변환

기존 plannedStartTimes는 자동 종료 계산에 쓰며 예약 변경을 반영합니다. 고정 표시용 snapshot과 별도로 유지합니다. 시작 당시 예약 목록에 있던 미접속 아동도 예약 map에 포함하므로, 녹화 도중 접속하더라도 당시 예약을 찾을 수 있습니다. 시작 뒤 새로 발견한 예약을 과거 값으로 채우지 않습니다.

저장과 조회 경로

  1. 그룹 페이지가 실제 로그인 진행자와 예약 정보를 녹화 훅에 전달합니다. 자동 시작과 테스트 수동 시작은 같은 start 경로를 사용합니다.
  2. 새 start 요청에서 문맥을 복사하고 앱 녹화 시작 성공과 범위 확인 후 새 메타에 snapshot을 넣습니다. 실패한 시작은 새 snapshot을 남기지 않습니다.
  3. IndexedDB의 StoredRecording이 snapshot을 보존합니다. 복원·재접속·전송 재시도는 이 값을 운반하며 이전 녹화에 현재 계정이나 예약을 보충하지 않습니다.
  4. assembleGroupRecording()이 실제 아동 트랙의 예약만 manifest로 복사하고 기존 업로드 경로가 S3에 전송합니다. 기존 schemaVersion 1에 선택 필드를 추가하므로 예전 저장물도 읽습니다.
  5. 상세 API가 기존 접근 권한을 먼저 확인합니다. 반환할 snapshot map도 허용된 아동 트랙으로 제한합니다. snapshot이 있으면 현재 수업 API를 조회하지 않습니다. 없는 이전 녹화만 기존 API와 5초 제한을 사용합니다.
  6. 서버와 로컬 뷰어 모두 manifest snapshot을 우선 표시합니다. 예약이 있으면 예약일시를, 없으면 실제 영상 시작시각과 녹화 시작을 표시합니다. 저장된 실제 계정은 녹화 진행자로 구분합니다.
예약이 있는 새 녹화26.10.29 목 16:00 예약 / 녹화 진행자: 당시 진행자
예약 없는 테스트 녹화26.10.29 목 16:00 녹화 시작 / 녹화 진행자: 당시 진행자

새 선택 필드는 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 -- <실제 변경한 앱 파일 경로>

코드 근거: 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를 호출하지 않습니다.

  1. 뷰어가 GET /api/monitor-recordings?userId=…&lessonIndex=…로 목록을 읽고 선택한 녹화의 상세 API를 호출합니다.
  2. getRecordingDetail()은 접근 권한·선택 아동의 인덱스·manifest를 확인한 뒤에만 수업 정보를 조회합니다. 거부·녹화 없음·만료 응답에서는 수업 정보를 조회하지 않습니다.
  3. 서버 로더가 getClassByLessonIndex()로 아동·회기의 예약 날짜와 시간을 구합니다. 녹화일과의 일치를 요구하지 않습니다. 정규 수업 정보가 없으면 기존 lesson의 scheduledTime을 사용합니다.
  4. 정규 수업은 예약 날짜 하루의 수업 목록에서 아동·회기·날짜가 일치하는 행을 찾아 groupMemberNames, 없으면 memberName을 읽습니다. 예전 그룹 ID와 현재 그룹 ID가 달라도 동일 아동·회기의 정보로 연결합니다. 조회 중인 사용자의 이름을 담당자로 표시하지 않습니다.
  5. 상세 응답의 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 점수는 없습니다.

남은 한계

코드 근거: 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> keepaliveChrome 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.tsgetDisplayMedia, 탭 화면 전체 그리기 루프, 공유 중지 안내 프레임, 선택 세대, 출력 정리
…/model/use-monitor-recording-beacon.tsmonitor 탭 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.tsxroom별 수신 전용 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 → 재생 뷰어에서 탐색 막대 보정 필요

검증 상태

자동 검증 완료vitest 85건 통과 · tsc 신규 에러 0 · Storybook 정적 빌드(녹화 패널 12상태) · mutation 76.7% (consume 필터 100%)
실기기 확인 남음A·B 동시 녹화 분리 · 청취 OFF 녹음 유지 · monitor 새로고침 자동 복구 · 진행자 목록·제어권 무영향 · 최소화·백그라운드 fps · 30분 메모리·싱크 200ms · 선택 중 취소

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} 녹화를 최신순으로 찾음(여러 개면 목록)
→ 재생 대상: 진행자 기준(당시 청취 설정) / 아동별(그 아동 소리만)

영상 스텝 소리 재구성 흐름

모니터 카드(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 재생)는 실기기 확인 전입니다.

검증 상태

자동 검증 완료vitest 173건 · store 테스트 11건 · tsc 신규 에러 0 · Storybook 정적 빌드 · mutation(recording-paths·media-events·listening-events 100%, playback-sync 95.7%)
실기기 확인 남음폴더 구조 생성 · 세션 로그 → 새 탭 뷰어 · 진행자 기준/아동별 전환 · ±10초·배속 싱크 · 영상 스텝 소리 시작 위치·청취 OFF 무음·음소거 구간 · 200MB 초과 영상 탐색 · URL 만료 재요청 시 음성 연속

코드 위치

파일책임
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/completemanifest 검증(경로는 서버가 다시 계산) → 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 작업은 없습니다.

그 밖의 결정

배포 전 수동 설정(코드 밖): 버킷 ppi CORS(앱 origin PUT·GET·HEAD, ETag·Content-Range·Accept-Ranges 노출)와 prod|staging|dev/monitor-recordings/ 90일 lifecycle. 버킷 설정은 저장소에 없어 기존 규칙을 받아 병합 후 적용해야 합니다(put 명령은 전체 교체). 운영 IAM 사용자 권한은 저장소에서 확인 불가.

검증 상태

자동 검증 완료vitest 213건 · store 테스트 11건 · tsc 신규 에러 0 · Storybook 정적 빌드 · 서비스 테스트(권한 403, 409 충돌, 크기 초과 422, 다른 아동 제외, 만료) · mutation(recording-keys 90.9%, upload-request 80.7%, recording-service 75.2%)
실기기 확인 남음실제 S3 업로드·진행률 · 세션 로그 → 뷰어 재생 · CORS · 1시간 넘는 시청 시 URL 재발급 · 업로드 실패 시 다운로드 대체 · session-log 테이블 스캔 스크립트 영향

별도 티켓으로 분리한 기존 보안 문제: DELETE /api/session-logs(인증 없음·임의 S3 키 삭제), POST /api/recording-download(인증 없음·임의 키 다운로드 링크), 세션 로그 POST·PATCH(인증 없음), GET(아동 범위 미확인).

1. 무엇을 남기나요?

현재 화면에 보이는 카드 영역을 한 영상으로 남깁니다. 스크롤 밖의 카드를 자동으로 펼쳐 담는 기능은 범위에 포함하지 않습니다.

영상 1개video.webm
카드 영역 전체 · 오디오 없음
A 오디오 1개A.webm
A 마이크 + A AI 음성
B 오디오 1개B.webm
B 마이크 + B AI 음성

기본안은 아동마다 마이크와 AI를 섞은 대화 오디오입니다. 아동 마이크만 보존하거나 원본 음성을 각각 보존하는 정책은 구현 전에 확정합니다. 파일 외에 manifest.json으로 영상과 음성을 연결합니다.

2. 누가 녹화를 담당하나요?

모니터 페이지카드 표시 · 청취 제어
카드 영역 위치·크기 전달
녹화 상태 표시 및 시작 진입
별도 녹화 페이지탭 캡처 · 카드 영역 자르기
아동별 오디오 직접 구독
영상·오디오 녹음 및 업로드 큐
↓ 녹화 페이지가 브라우저에서 S3로 직접 전송
PPI API녹화 ID · 참여자·권한 확인
업로드 URL 발급 · 상태 관리
S3 + 파일 완성 작업조각 보관 → 파일 조립·컨테이너 정리
최종 영상·오디오·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를 새로고침하면 어떻게 되나요?

  1. 녹화 페이지는 열려 있으므로 녹화 실행부를 유지합니다.
  2. monitor의 heartbeat가 끊기면 영상 출력은 안내 프레임으로 바꿉니다. 숨긴 화면을 계속 정상 화면처럼 표시하지 않습니다.
  3. monitor가 로드되면 recordingId로 재연결하고 새 카드 좌표·페이지 세대를 전달합니다.
  4. 탭 식별과 좌표를 확인한 후 영상 출력을 복구하고 중단 구간을 기록합니다.

재선택 없이 복구하는 것이 목표입니다. 대상 탭의 새로고침 시 캡처 유지와 자동 복구는 지원 Chrome에서 실제 검증해야 합니다. 탭 종료·공유 중지·브라우저 종료는 자동 복구 대상이 아니며 다시 사용자 선택이 필요합니다. 녹화 페이지 자체를 새로고침해도 권한과 실행 중 MediaRecorder가 보존되지는 않습니다.

페이지 간 메시지는 같은 origin과 발신 창·녹화 ID·세대를 검증합니다. 재연결은 BroadcastChannel 또는 검증된 postMessage로 구현하고 오래된 좌표 메시지는 무시합니다. 오디오가 실제로 끊기면 무음과 gap 이벤트를 남기며 수신되지 않은 음성을 복원한 것으로 표시하지 않습니다.

4. 녹화가 끝날 때까지 파일을 메모리에 쌓지 않습니다

① 조각 생성예: 5~10초 간격
영상 / A / B 각각 순번 부여
② 임시 보관·전송IndexedDB 저장
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를 기반으로 복구 시도. 마지막 미생성·미저장 조각은 유실 가능
MediaRecorder의 각 Blob은 단독 재생을 보장하지 않습니다. ‘조각 업로드 성공’과 ‘최종 재생 파일 완성’을 구분합니다. 현재 PPI의 로그 조각 업로드는 전송 패턴 참고이며, 미디어 조립 작업이 이미 존재한다는 의미는 아닙니다.

초기안은 기존 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·헤더만 허용하며, 녹화 버킷 경로는 비공개로 유지합니다. 보존 기간과 삭제 정책은 운영 정책으로 확정합니다.

1단계 · 기술 검증
실제 지원 Chrome에서 별도 탭 캡처·monitor 새로고침·좌표 크롭·백그라운드·오디오 중복 구독을 검증합니다. 실패하면 전용 녹화 뷰 또는 확장 프로그램 대안을 결정합니다.
2단계 · 녹화 핵심
카드 범위 정의 → 영상 출력 → 아동별 믹서 → 공통 시계·재접속 이벤트 → 로컬 큐를 연결합니다.
3단계 · 저장·복구
권한·presigned API → 순번별 업로드 → 최종화 worker → manifest·DB → 실패·재시도·partial 복구를 구현합니다.
4단계 · 운영 화면과 인수
녹화 시작·경과 시간·아동별 수신 상태·대기 업로드·종료·저장 결과를 표시합니다. 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 숨김 창으로 재사용해 탭 선택 없이 자동 녹화하는 안.

코드 근거는 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은 수동 설정 필요.