basket_utils/VIDEO-SHARING-IMPLEMENTATION.md

# MP4 파일 공유 구현 및 검증

2026-09-07

## 적용 범위

GPT-5.6 Luna(xhigh)에 구현을 위임하고 주 에이전트가 코드 검토 및 브라우저 QA를 수행했다.

- 상단 '영상 공유'에서 관리 항목을 제외한 공유 전용 패널을 연다.
- 작전판 전체 또는 선택 선수 POV로 1280×720 MP4를 만든다. POV 선택 시 선수 번호를 표시한다.
- MediaRecorder가 지원하는 실제 MP4 MIME을 선택하며 WebM을 MP4로 이름만 바꾸지 않는다.
- 별도 WebGL 출력 캔버스에서 전술 스냅샷을 렌더링하고 진행률·취소·영상 미리보기를 제공한다.
- 벽시계 시간 기준으로 프레임을 예약해 화면 주사율에 따라 영상이 빨라지는 문제를 방지한다.
- 생성 완료 후 별도의 사용자 클릭에서 Web Share 파일 공유를 호출한다. 카카오톡·대화방은 사용자가 OS 및 카카오톡 UI에서 선택한다.
- 파일 공유가 안 되는 환경에는 MP4 다운로드를 보조 수단으로 제공한다. 링크 공유는 구현하지 않았다.
- 전술·이름·출력 시점이 바뀌면 이전 영상의 공유를 차단한다. 생성/메타데이터 확인 중 취소와 리소스 정리를 처리한다.
- 미리보기 키보드 재생과 편집기 재생 단축키를 분리한다.

## 실제 브라우저 확인

- 최종 `npm test`: 102개 통과. `npm run build`: 성공. 기존 단일 번들 크기 경고는 유지.
- 현재 인앱 Chromium 환경에서 작전판 MP4가 1280×720, 약 1.65초로 생성됐다. 원본 전술은 UI 기준 약 1.7초다.
- O1 선수 시점도 1280×720, 약 1.64초 영상으로 생성됐다. 두 영상 모두 미리보기에서 끝까지 재생되어 ended 상태에 도달했다.
- 390×844 모바일 뷰포트와 1440×1000 PC에서 공유 패널 표시를 확인했다. 이는 화면 크기 검증이며 실제 모바일 OS 테스트가 아니다.
- 생성 취소 후 공유 버튼 비활성화, 전술 이름 변경 후 기존 영상 무효화, 미리보기 Space 재생 후 편집기 시간 0 유지 확인.
- OS 파일 공유 호출 후 취소 상태를 확인했다. 실제 카카오톡 대화방으로 메시지를 전송하지 않았다.
- 브라우저 오류 로그 없음.
- 최종 카메라 보존 수정 후 POV 영상을 다시 생성하고, 닫은 뒤 원래 선수 시점과 재생 시간 0으로 돌아오는 것을 확인했다.

## 제약 및 남은 완료 조건

- 실제 iOS/Android 카카오톡 단체방 전송과 수신 영상 UI/재생은 검증하지 못했다. 이것이 제품의 최종 인수 기준이며 브라우저 생성 성공으로 대체할 수 없다.
- 직접 MP4 녹화를 지원하지 않는 브라우저에서는 영상 생성이 안 된다. 파일 공유 지원과 영상 생성 지원은 각각 다르다. 주요 대상 기기에서 불안정하면 서버 인코딩이나 네이티브 파일 공유 브리지로 보완해야 한다.
- 브라우저 캡처는 실시간 녹화다. 생성에는 영상 길이 정도의 시간이 필요하고, 느린 GPU나 프레임 드롭으로 실제 파일 길이·프레임 간격에 작은 차이가 생길 수 있다. 생성 중 탭을 숨기면 실패로 처리한다.
- 저장소·승인 로그인·다중 팀·서버 렌더링·HTTPS 배포는 이번 MP4 공유 변경에 포함되지 않았다.
- 배포한 MP4는 회수/만료할 수 없다. 공유 API 응답만으로 단체방 전송 완료를 단정하지 않는다.

## 관련 파일

- `src/videoExport.js`: MP4 생성·검증·취소·파일 공유·다운로드.
- `src/videoExport.test.js`: 녹화 시간, 지원 검사, stale/cancel/메타데이터 정리, 공유 동작.
- `src/scene.js`: 별도 영상 출력 캔버스와 카메라 처리.
- `src/main.js`, `src/ui.js`, `src/style.css`: 공유 패널과 기존 편집기 통합.