GhiVideo 소스 복제 — v4 작업 시작 기준

기존 GhiVideo 저장소 HEAD의 트래킹 소스 362개 파일을 복제.
(node_modules·storage·빌드 산출물·대용량 미디어는 .gitignore 규칙대로 제외)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/history/2026-07-02_영상fps-데이터기반-자동산출.md

@@ -0,0 +1,34 @@
+# 영상 fps 데이터 기반 자동 산출 (고정 29.97 → 가변)
+
+**소요 시간**: 약 20분
+**Context 사용량**: input ~150k / output ~6k tokens
+
+## 배경
+프레임번호↔시간 변환이 `VIDEO_FPS = 30000/1001`(29.97)로 하드코딩 → 30fps 영상 전용.
+24/60fps 등 다른 영상은 이름표가 어긋남. 어떤 fps 영상이 로드될지 미리 알 수 없음.
+
+## 문제 데이터
+드론 CSV(`frame_cnt,latitude,...`)엔 **시간이 없고 frame_cnt(프레임 번호)만** 있음.
+→ fps 를 CSV 단독으로 못 구함. **영상 길이(duration)** 와 결합 필요.
+
+## 해결
+`effectiveFps = maxFrameCnt / duration` → 표준 fps(23.976/24/25/29.97/30/50/59.94/60) 중
+±10% 이내면 스냅, 아니면 원시값. 데이터/길이 미확보 시 29.97 폴백.
+
+### 변경 파일 (2개, 소규모)
+- [VideoPlayer.tsx](../../client/src/components/player/VideoPlayer.tsx)
+  - `effectiveFps` useMemo 신설(storeFrames+duration). `VIDEO_FPS` 하드코딩 4곳 제거
+    (frame 계산 / HUD 표시 / 프레임입력 이동 / StationOverlay prop).
+  - useFrameStep 의 fps(VFC 감지, 31 오감지)는 미사용 → destructure 제거.
+- [StationOverlay.tsx](../../client/src/components/overlay/StationOverlay.tsx)
+  - `fpsRef`(prop fps 기반) 추가. 프레임↔시간 변환 VIDEO_FPS 사용처(최근접 프레임 탐색, estFrame)를
+    fpsRef.current 로 교체. VIDEO_FPS 상수는 폴백 기본값으로만 유지.
+
+## 주의/전제
+- 드론 CSV 가 영상 전체 구간을 덮는다는 전제(마지막 frame_cnt ≈ 영상 끝). 부분만 덮으면 fps 과소 →
+  스냅 실패 시 원시값 사용. 필요 시 메타데이터/FFprobe 로 보강 가능.
+- 표준 목록 밖 fps 는 스냅 없이 원시값 사용.
+
+## 검증
+- `tsc --noEmit` 통과
+- `npm run build` 성공 → 새 해시 `index-BbUe4Gr4.js` :55000 서빙 확인