180 lines
26 KiB
Markdown
180 lines
26 KiB
Markdown
# 겜녹이 (Game Voice Recorder, GVR)
|
|
|
|
디스코드 음성채널에 봇이 들어가 참가자 각자의 목소리를 따로 녹음하고, 게임 PC의 NVIDIA GPU로 한국어 텍스트(STT)로 바꾼 뒤,
|
|
발로란트·리그 오브 레전드 경기 데이터(킬·라운드·오브젝트·인게임 채팅)와 같은 타임라인에 묶어 https://gvr.tkrmagid.kr 에서 보고 듣는 프로그램입니다.
|
|
|
|
- 게임 PC: 포터블 `GameVoiceRecorder.exe` 하나로 디스코드 봇, STT 엔진, 기록 저장소, 설정 화면이 돈다
|
|
- 사이트 서버: 디스코드 로그인(서버 멤버만), 게임 PC 연결 확인·잠금 화면, 기록 중계 (기록은 게임 PC 에만 있음)
|
|
- 설계·계획: [`docs/gemnoki-project-plan.pdf`](docs/gemnoki-project-plan.pdf), 개발 구조·인터페이스: [`docs/dev/ARCHITECTURE.md`](docs/dev/ARCHITECTURE.md)
|
|
- 범인찾기 · 리플레이 동기화 계획서 v1.2 (결정 반영): [`docs/culprit-finder-plan.pdf`](docs/culprit-finder-plan.pdf) · 원본 · 비용 계산 · 프롬프트 초안: `docs/report/culprit/` (실제로 쓰는 프롬프트는 `site/server/prompt/`)
|
|
- **제작 완료 보고서 (M0~M8)**: [`docs/gemnoki-final-report.pdf`](docs/gemnoki-final-report.pdf) · 단계별 테스트 기록: [`docs/dev/test-results.md`](docs/dev/test-results.md)
|
|
- Windows 실행 파일: Gitea 릴리스 [v1.12.1](https://git.tkrmagid.kr/tkrmagid/game_voice_recorder/releases/tag/v1.12.1) (`GameVoiceRecorder-1.12.1-win-x64.zip` 권장, 단일 파일 `GameVoiceRecorder-1.12.1-portable.exe`) · 바뀐 점 보고서 [`docs/gemnoki-v1.3.7-report.pdf`](docs/gemnoki-v1.3.7-report.pdf) · 처음 버전 [v1.0.0](https://git.tkrmagid.kr/tkrmagid/game_voice_recorder/releases/tag/v1.0.0)
|
|
|
|
## 로그인 · 관리자 (v1.2.0~)
|
|
|
|
- exe 는 **등록된 디스코드 계정으로 로그인**해야 열린다. 로그인 버튼 → 브라우저에서 디스코드 로그인 → 사이트 서버(gvr.tkrmagid.kr)가 등록 명단을 확인한다. 등록되지 않은 아이디면 "등록되지 않은 아이디입니다"와 디스코드 아이디를 보여 주고 앱을 열지 않는다.
|
|
- 역할: **최고 관리자**(`293719842274541579`, `1352267557213573160`, 서버에 고정) · **관리자** · **유저**. 유저 등록 · 역할 변경 · 등록 해제는 최고 관리자만, 등록 명단 보기와 관리자 전용 설정은 관리자도 할 수 있다.
|
|
- 설정 창 **🛡️ 관리자** 탭(관리자에게만 보임): 유저 등록(디스코드 아이디 + 역할), 등록 계정 목록(역할 · 마지막 접속 · 앱 버전 · 등록한 사람), 관리자 전용 기능 목록.
|
|
- 관리자 전용 (일반 유저 화면에서는 🔒 잠김, 메인 프로세스에서도 막음): 다른 봇으로 바꾸기 · 봇 토큰, 녹음 안내(TTS) 끄기 · 문구, 음성 보관 기간, 사이트 서버 주소 · PC 이름 · 등록/해제, 학습 데이터 삭제, 파인튜닝.
|
|
- 앱은 시작할 때와 10분마다 등록 여부를 다시 확인한다. 등록이 해제되면 바로 잠그고 봇 · 녹음 · 사이트 연결을 멈춘다. 사이트 서버에 못 붙으면 마지막 확인 뒤 3일까지는 그대로 쓴다.
|
|
- 서버 쪽: `site/server/src/app-auth.ts` (`/auth/app/*`, `/app/me`, `/app/admin/users`), 앱 쪽: `app/src/core/auth.ts`, 권한 목록: `app/src/core/roles.ts`. 로그인 E2E: `app/scripts/login-e2e.mts`.
|
|
|
|
## v1.6.0 바뀐 점
|
|
|
|
- **내 정보** (사이트 오른쪽 위 내 이름 누르기, `site/web/src/components/UserEdit.tsx`): 표시 이름 바꾸기 · 되돌리기(디스코드 서버 별명으로), 내 색, 라이엇 ID, 녹음 제외, 내 기록 보기 · 관리 페이지 · 로그아웃
|
|
- 표시 이름은 사이트 서버에 저장하고(`PUT /site/profile/name`, 1~32자 · 보이지 않는 글자 금지 · 다른 사람 표시 이름과 겹치면 거절 · 10분에 10번) 게임 PC 앱에 바로 보낸다(`PUT /api/internal/names`, 예전 앱은 10분마다 받아 감)
|
|
- 색 · 라이엇 ID · 녹음 제외는 게임 PC 앱 기록에 저장 (`PATCH /api/users/:id`, 본인 또는 관리자. 다른 사람에게 연결된 라이엇 ID 는 본인이 가져갈 수 없음)
|
|
- **관리 페이지** `/admin` (관리자 · 최고 관리자, `site/web/src/pages/AdminPage.tsx`): 게임 PC 연결 · 앱 버전 · 새 버전 안내(Gitea 최신 릴리스), 녹음된 사람 + 앱 등록 유저 목록에서 표시 이름 · 색 · 라이엇 ID · 녹음 제외 바꾸기, 앱 등록 · 역할 · 해제(최고 관리자). 서버 `/site/admin/*` 는 앱 관리자 탭 `/app/admin/*` 와 같은 코드 (`site/server/src/app-auth.ts`). 표시 이름은 사이트에서는 관리자도 바꿀 수 있다
|
|
|
|
## v1.5.0 바뀐 점
|
|
|
|
- **3D 리플레이**: 발로란트 경력 탭에서 경기 리플레이를 내려받아 두면, 사이트 경기 화면 "3D 리플레이"를 열 때 게임 PC 앱이 `%LOCALAPPDATA%\VALORANT\Saved` 아래 `<경기 ID>.vrf` 를 찾아 변환해 보낸다 (처음 한 번 10초 안팎, 그 뒤로는 `GVR-Data/replays/<경기 ID>.json.gz` 보관본). 선수 10명이 3D 맵 위에서 움직이고 그때 대화가 같이 재생된다
|
|
- 변환기 `resources/replay/gvr-replay.exe` (`tools/replay-extract`, .NET 단일 파일). 한 번에 하나 · 낮은 우선순위로 돌린다. 실패하면 이유를 사이트에 보여 주고, 같은 파일은 다시 내려받을 때까지 다시 하지 않는다
|
|
- 앱 `app/src/core/replays.ts`, API `GET /api/matches/:id/replay` (gzip JSON, 변환 중 202) · `GET /api/replays` (찾은 리플레이 목록)
|
|
|
|
## v1.4.3 바뀐 점
|
|
|
|
- 상대 닉네임을 말로 적던 문제 (예: 말소리가 "QQQWWWQ"로 나옴): 그 경기 선수 이름을 모두 핫워드로 넣어서, 말을 못 알아들으면 Whisper 가 닉네임을 그대로 적었다. 이제
|
|
- 선수 이름은 한글이 들어간 것만 핫워드로 넣는다 (영문 · 숫자 닉네임은 한국어 말로 나올 일이 거의 없음)
|
|
- 결과가 선수 이름(또는 그 조각)뿐이면 워커가 선수 이름을 빼고 한 번 더 변환한다 (`worker/gvr_worker/stt.py` `is_name_echo`, 앱이 `player_names` 로 넘김)
|
|
- 한 번만: 예전에 이렇게 적힌 발화를 정밀 모델로 다시 변환한다 (음성 파일이 지워졌으면 숨김, 사람이 고친 발화는 그대로). `app/src/core/stt/pipeline.ts` `recheckNameEchoes`
|
|
|
|
## v1.4.2 바뀐 점
|
|
|
|
- 녹음 중에 음성채널에 들어온 사람이 사이트에서 "알 수 없음"으로 뜨던 문제: 앱이 그 사람을 유저로 저장만 하고 `users.updated` 를 보내지 않았다. 이제 들어올 때 보낸다 (`app/src/core/discord/bot.ts` onVoiceState)
|
|
- 사이트도 실시간 발화 · 녹음 상태에 처음 보는 사람 아이디가 오면 유저 목록을 한 번 다시 받아 온다 (v1.4.1 이하 앱에서도 이름이 뜸)
|
|
|
|
## v1.4.1 바뀐 점
|
|
|
|
- 잡음으로 배운 문장 비교: v1.4.0 은 편집 거리로 비교해서, 배운 문장 뒤에 짧은 실제 말("네", "가자", "아니")이 붙은 발화까지 잡음으로 지웠다. 이제 글자 수가 같고 15% 안 글자만 바뀐 것(인식이 한두 글자 다르게 나온 것)만 같은 문장으로 본다
|
|
|
|
## v1.4.0 바뀐 점
|
|
|
|
- 사이트 발화 우클릭 → **삭제…**: 확인 창에서 "잡음이라 삭제" 또는 "그냥 삭제". 관리자나 말한 사람만 지울 수 있고, 글 · 음성 파일 · 교정 학습 데이터를 게임 PC 에서 지운다 (`POST /api/utterances/:id/delete`)
|
|
- "잡음이라 삭제"는 인식된 문장을 `noise_phrases` 에 배운다. 다음에 같은 문장(띄어쓰기 · 문장부호 무시, 8글자 이상이면 글자 수가 같고 15% 안 글자만 바뀐 것까지. 앞뒤에 말이 붙으면 그대로)이 인식되면 잡음(`noise_reason='learned'`)으로 숨기고 파일을 지운다. 배운 문장은 단어사전 화면에서 보고 지운다 (`GET/DELETE /api/noise-phrases`)
|
|
- 사이트 효과음: "새 발화 알림" · "재생 시작"을 기본으로 끈다 (예전에 저장한 설정도 한 번 꺼 줌, 그 뒤 다시 켜면 그대로)
|
|
|
|
## v1.3.9 바뀐 점
|
|
|
|
- 기록 zip 받아오기: 표시 이름에 `..` 이 있으면(예: `하늘..별`) 그 이름이 들어간 녹음 파일을 "음성 파일 이름이 잘못되었습니다"로 거절해, 내보낸 zip 을 다시 넣지 못했다. zip 안 이름은 꺼낼 때 찾는 열쇠로만 쓰고 이 PC 에 쓸 경로는 발화 ID 로 만들므로, 폴더 구분자(`/`, `\`)만 막는다
|
|
|
|
## v1.3.8 바뀐 점
|
|
|
|
- **녹음 파일 이름**: `날짜_시각_말한사람_게임_모드_맵_라운드_발화ID.ogg` (예: `2026-10-16_04-03-16_사금향_발로란트_경쟁전_어센트_R7_0mv9….ogg`, 롤은 라운드 대신 게임 시간 `12분30초`, 경기 밖은 `…_사금향_경기밖_….ogg`). 시각은 게임 PC 시각, Windows 에서 못 쓰는 글자는 뺀다. `app/src/core/audio-names.ts`
|
|
- 녹음이 끝나면 바로 이 이름으로 저장하고(경기 중에는 지금 라운드), 경기가 끝나 경기 상세(정확한 라운드)가 오거나 표시 이름이 바뀌면 다시 맞춘다. 예전 파일도 처음 켤 때 바꾼다
|
|
- 음성 인식이 그 파일을 읽는 중이거나 대기열에 있으면 바꾸지 않고, 변환이 끝난 뒤 바꾼다. 다른 프로그램이 파일을 열고 있으면 다음에 다시 한다
|
|
- 기록 zip 안 `audio/` 도 같은 이름, 사이트 ogg 다운로드 · 자세한 정보도 같은 이름 (v1.3.7 zip 의 `audio/<발화ID>.ogg` 도 그대로 받는다)
|
|
|
|
## v1.3.7 바뀐 점
|
|
|
|
- **기록 관리** (사이트 "기록" 탭, `site/web/src/pages/RecordsPage.tsx`): 기록을 경기 하나 = 묶음 하나로 보고, 경기 밖 대화는 녹음 세션 안에서 경기 사이마다 묶는다. 다음 경기가 30분 안에 시작하면 "경기 전 대화", 지난 경기가 30분 안에 끝났으면 "경기 후 대화", 아니면 "게임 밖 대화". 묶음을 골라 한 번에 zip 내려받기 · 지우기(관리자) · zip 받아오기(관리자). 앱 `app/src/core/bundles.ts`, API `GET /api/bundles` · `GET /api/bundles/export?ids=` · `POST /api/bundles/delete` · `POST /api/bundles/import`
|
|
- **zip 형식** `gvr-bundle` v1: `manifest.json`(형식 · 묶음 · 개수), `data.json`(유저 · 세션 · 경기 · 라운드 · 이벤트 · 범인 분석 · 발화), `audio/<발화ID>.ogg`, `대화.txt`. 받아오기는 형식 · 버전 · 발화 ID · 말한 사람 · 시각 · 경기 연결 · 음성 파일(ogg 머리) · 개수를 모두 확인하고 하나라도 빠지면 아무것도 넣지 않고 "받아오기 실패: (이유)"로 끝낸다. 이미 있는 발화는 건너뛴다. 받아온 녹음의 보관 기간은 받아온 날부터 센다 (`utterance_imports`)
|
|
- 사이트 ↔ 게임 PC 중계: 큰 zip 을 1MB 조각으로 주고받는다 (사이트 서버 → 앱 요청 본문, 앱 → 사이트 서버 응답 모두)
|
|
|
|
## v1.3.6 바뀐 점
|
|
|
|
- **목소리 깨짐**: 녹음기가 디스코드 패킷이 "도착한 간격"으로 말 사이 쉼을 채웠다. 게임 중(CPU 부하)에는 패킷이 2~3개씩 몰려 와서 말 중간에 20ms 무음이 계속 끼었다 (사용자 파일: 실제 7.0초 발화가 8.5초, 패킷 3개 중 1개가 무음). 이제 RTP 타임스탬프로 패킷 자리를 정한다 (`recorder.ts` `tapRtp` · `Utterance.place`). 예전 녹음은 처음 켤 때 한 번 끼운 무음을 빼고 다시 변환한다 (`ogg.ts` `removeInsertedSilence`)
|
|
- **말한 사람 "알 수 없음"**: 앱이 `users.updated` 를 빈 목록으로 보내 사이트가 유저 목록을 비웠다. 이제 실제 목록을 보낸다 (사이트도 빈 목록이면 다시 받아 옴)
|
|
- **잡음**: 목소리 없음 · 잡음에서 지어낸 문장 · 같은 말 반복은 사이트에 보이지 않고 ogg 도 지운다 (경기 중 실시간 판정은 경기 뒤 정밀 모델이 다시 본 다음). 로그에 "잡음 발화 … 숨김 · 음성 파일 삭제 (이유, 인식 문장)" 로 남는다. 목소리가 0.15초라도 있으면 Whisper 로 넘기고, 반복 고리는 한 번으로 줄여 남은 말을 보여 준다
|
|
- **시작 창**: 포터블 exe 를 푸는 동안 작은 그림 창(`assets/app/splash.bmp`), 앱이 켜지는 동안 "켜는 중" 창
|
|
- **녹음 안내 말 속도** 0.1~2.0 (Edge TTS 는 0.5~2.0, 그보다 느리면 워커 `tempo` 가 atempo 로 늘림)
|
|
- **사이트**: 재생 음량 0~200% · 발화 우클릭(재생 · 자세한 정보(원본 ogg 이름 · 게임 PC 경로 · 크기 · 인식 정보) · ogg 다운로드 · 내용 복사, 앱 `GET /api/utterances/:id/info`)
|
|
- **사이트 로그**: 사이트 서버가 `data/logs/site-날짜.log` 로 남긴다 (게임 PC 연결 · 끊김 · 기록 요청 결과 · 봇 중계 · 범인찾기 · 브라우저 오류). 관리자는 `https://gvr.tkrmagid.kr/logs` 에서 게임 PC 가 꺼져 있어도 보고 내려받는다 (잠금 화면 · 설정 메뉴에 링크). 14일 보관
|
|
- **지금 게임**: 앱 게임 연동 탭 · 사이트(머리글 · 타임라인 오른쪽)에 연결된 게임 · 상태(메뉴 · 대기열 · 요원/챔피언 선택 · 경기 중) · 모드 · 맵 · 라운드 · 점수 · 내 요원/챔피언 · KDA · 게임 시간
|
|
- 발로란트 데스매치 · 팀 데스매치 · 에스컬레이션: 킬 점수를 라운드로 착각해 "R63 승리" 같은 가짜 라운드와 에이스를 만들던 것 고침. 경기 상세에 선수 이름이 비어 오면 이름 서비스로 채운다 ("주인 계정 자동 연결: #" 고침)
|
|
|
|
## v1.3.5 바뀐 점
|
|
|
|
- **표시 이름 빈틈**: 표시 이름을 정하기 전에 시작한 범인 분석이 정한 뒤에 저장되면 결과 본문에 예전 이름이 남을 수 있었다 (이미 이름이 바뀐 유저는 다시 훑지 않았음). 이제 가린 예전 이름을 기억해 두고(`meta.hidden_names`), 분석을 저장할 때마다 · 이름을 다시 받을 때마다 모든 분석에서 바꾼다
|
|
- 상태 메시지 실제 확인: `site/server/scripts/presence-e2e.mts` (사이트 서버 코드로 봇을 빈 음성채널에 넣었다 빼며 확인)
|
|
|
|
## v1.3.4 바뀐 점
|
|
|
|
- **슬래시 명령 응답**: 그 디스코드 서버를 지켜보는 겜녹이 앱이 없으면 사이트 서버가 명령을 무시해서 디스코드에 "애플리케이션이 응답하지 않았어요"만 떴다 (봇 토큰을 직접 쓰는 옛 v1.1.0 PC 와 겹치지 않게 넣은 동작). 이제 1.5초 기다렸다가 아무도 받지 않았으면 이유를 답한다: 앱이 꺼져 있음 / 내 앱이 다른 서버를 녹음 대상으로 정해 둠 / 아직 연결 중. 앱은 서버가 권한을 다시 확인하다 지켜보기를 끊으면 1분 뒤 다시 요청한다
|
|
- **봇 상태 메시지**: 녹음 중(봇이 어느 서버에서든 음성채널에 있음)이면 빨간 상태(다른 용무 중) + "🔴 녹음 중", 아니면 "🎙️ 대기 중 · /녹음시작". 겜녹이 봇은 사이트 서버가, 다른 봇 모드는 앱이 바꾼다. 봇 하나가 여러 서버에 들어가 있어서 채널 이름은 넣지 않는다
|
|
|
|
## v1.3.3 바뀐 점
|
|
|
|
- **따라갈 사람 목록**: 녹음할 서버의 멤버가 모두 나온다. 내 계정이 맨 위, 그다음 관리자(최고 관리자 포함), 나머지는 이름순. 예전에는 봇이 서버를 지켜보기 전에 목록을 요청하면 사이트 서버가 거절했고 앱이 그 오류를 숨겨 "선택 안 함"만 보였다. 이제 가입한 서버면 바로 받고, 실패하면 오류와 다시 불러오기 버튼을 보여 준다. 녹음할 서버를 바꾸면 봇이 새 서버를 바로 지켜본다. 서버: `GET /app/admins`
|
|
- **롤 채팅은 API 로만**: 화면 글자 인식(OCR)을 앱 · 워커 · 빌드에서 모두 뺐다 (pywinrt · mss · Pillow 의존성 제거). 롤 클라이언트(LCU) API 로 챔피언 선택 · 게임 후 채팅을 받는다. 롤은 게임 중 전체 · 팀 채팅을 주는 API 가 없다 (LCU · 게임 클라이언트 API 모두, 비공식 포함). 게임 로그 파일(r3dlog)에 채팅이 남아 있으면 경기 뒤에 붙인다
|
|
- **표시 이름 (실명 숨기기)**: 디스코드 아이디마다 보일 이름을 정하면 사이트(로그인 이름 · 대화 기록 · 유저 목록), 앱, 범인 분석에 그 이름만 쓰고 이미 저장된 이름도 바꾼다. 앱 🛡️ 관리자 탭에서 최고 관리자가 정한다. 서버: `GET /app/names`, `PUT /app/admin/names`, `node dist/cli.js name <아이디> [이름]`
|
|
- 저장소의 시연 · 테스트 데이터, 화면 캡처, 계획서 PDF 에서 실제 이름을 빼고 가짜 이름(하늘)으로 바꿨다
|
|
|
|
## 디스코드 봇
|
|
|
|
- 기본은 **겜녹이 봇으로 진행**: 토큰을 넣지 않아도 로그인만 하면 바로 연결된다. 봇은 사이트 서버가 디스코드에 연결하고, 앱은 로그인 토큰으로 서버 중계(`/app/bot/ws`)를 받는다.
|
|
- **다른 봇으로 진행하기**(관리자만)를 고르면 직접 만든 봇 토큰을 넣는다 (암호화 저장). v1.0.0 에서 토큰을 넣어 쓰던 설치는 다른 봇 모드로 그대로 이어진다.
|
|
- v1.2.1 부터 **겜녹이 봇 토큰은 사이트 서버 밖으로 나가지 않는다** (v1.1.0 은 exe 에 감춰 넣었고, v1.2.0 은 로그인한 유저에게 내려줬다). 등록된 유저의 PC 에도 토큰이 없어서 PC 를 뒤지거나 통신을 가로채도 꺼낼 수 없다.
|
|
음성채널에 들어갈 때 서버가 디스코드에서 받은 일회용 음성 접속 정보만 그 PC 에 넘기고, 음성은 PC ↔ 디스코드로 바로 간다. 사이트 서버가 꺼져 있으면 겜녹이 봇은 쓸 수 없다 (다른 봇 모드는 상관없음). 구조: [`docs/dev/ARCHITECTURE.md` 8장](docs/dev/ARCHITECTURE.md)
|
|
- 빌드에 비밀값이 필요 없어 공개 릴리스에 올려도 된다. 등록되지 않은 사람은 exe 를 받아도 겜녹이 봇을 쓸 수 없다.
|
|
|
|
## 통신 · 데이터 보안 (v1.2.2~)
|
|
|
|
- 앱 ↔ 사이트 서버(로그인 토큰 · 기기 키 · 기록 중계 · 봇 중계)는 **https/wss 만** 쓴다. 사이트 서버 주소를 http 로 바꾸면 거절하고 아무것도 보내지 않는다 (이 PC 안 127.0.0.1 · localhost 만 예외, 개발용). `app/src/core/util/secure-url.ts`
|
|
- 사이트 서버 인증서는 앱에 들어 있는 Mozilla 루트 인증서로만 검증하고 검증을 끌 수 없다. `NODE_TLS_REJECT_UNAUTHORIZED=0`, Windows 인증서 저장소에 깐 가짜 루트 인증서(감시 · 프록시 프로그램)로는 통신을 엿볼 수 없다. 검증 끄기 변수는 시작할 때 지워서 사이트 밖 통신도 검증한다. `app/src/core/util/secure-http.ts`
|
|
- 겜녹이 봇 중계 권한: 앱 유저가 가입한 디스코드 서버, 그 유저가 볼 수 있는 채널만 보이고, 그 유저가 들어갈 수 있는 음성채널에만 봇을 부를 수 있다.
|
|
- 게임 연동(Riot 로컬 API)의 자체 서명 인증서 예외는 이 PC 안 주소에만 쓴다. Riot 원격 API 등 바깥 주소는 항상 인증서를 검증한다.
|
|
- exe(Electron) 잠금: `NODE_OPTIONS` · `NODE_EXTRA_CA_CERTS`(가짜 인증서를 끼워 통신을 엿보는 데 쓰임) · `ELECTRON_RUN_AS_NODE` · `--inspect` 를 무시하고 `app.asar` 만 읽는다 (Electron fuses). 설정 창은 앱 화면만 띄우고 바깥 주소는 브라우저로 연다. 권한 요청(마이크 · 카메라 등)은 거절한다.
|
|
- 사이트 서버: 보안 정책(CSP)으로 이 사이트 스크립트와 이 사이트로의 접속만 허용, 실시간 WebSocket 은 이 사이트에서 온 연결만, 로그인 세션 · 앱 토큰 · 기기 키는 해시로만 저장, 로그에서 로그인 code · state · 검색어를 지운다. 등록 코드 대입 · 로그인 요청 폭주는 IP 별로 막는다. HSTS · http→https 이동 · TLS 1.2 미만 차단은 앞단 프록시(NPMplus)가 한다.
|
|
- 디스코드 음성은 디스코드 자체 암호화(DAVE 종단간 암호화)로 간다.
|
|
|
|
## 🔍 범인찾기 (v1.3.2~)
|
|
|
|
끝난 경기를 고르고 "범인 분석"을 누르면 AI(Claude)가 그 경기의 음성 대화 · 킬 · 라운드/오브젝트 · 경제 · 채팅 · 10명 스탯을 읽고 10명 평점 · 태그 · 한 줄 평과 팀별 범인 1명(이유 + 근거)을 만든다. 근거를 누르면 그 순간의 음성 · 타임라인으로 간다. 계획서: [`docs/culprit-finder-plan.pdf`](docs/culprit-finder-plan.pdf)
|
|
|
|
- 정한 것 (2026-10-15): 범인 = 가장 못함 + 가장 발목 + 결과의 원인을 종합해 팀마다 1명 · 분석 버튼은 등록된 앱 유저 이상(다시 분석은 관리자) · Claude Opus 5.5(생각 high) · 말투 중간맛 · 녹음 안내(TTS)에 "녹음된 대화는 AI 경기 분석에 쓰일 수 있어요" 추가
|
|
- **전적 사이트 계산법 참고**: 평점과 범인은 기록 점수에서 출발해 승부처 · 역할 · 경제 · 음성 소통으로 더하고 뺀다 (지시문 v1.2). 분석할 때 외부 전적 사이트에는 접속하지 않고, 앱이 경기 기록으로 직접 계산한다
|
|
- **기록 점수** (0~10, 모든 경기): OP.GG OP스코어 계산법을 따라 우리 기록으로 계산한 점수 + 경기/팀 순위 + MVP · ACE + 점수를 올리고 깎은 지표. 발로란트는 OP.GG 가 밝힌 입력(라운드 승률 · KAST · ACS · 피해 격차), 롤은 킬 관여 · 데스 · 딜/받은 피해/골드 비중 · CS · 레벨 · CC · 와드. OP.GG 는 가중치를 공개하지 않아서, 계수는 개발할 때 한 번 OP.GG 공식 MCP 로 받은 실제 경기 점수에 맞춰 정했다 (교차 검증: 발로란트 상관 0.97 · 평균 오차 0.49점, 롤 상관 0.94 · 0.60점 · 팀 최하위 일치 85%). `packages/shared/src/rating.ts`, 맞추는 도구 `tools/opscore-fit/`
|
|
- **LOL.PS 라인전**: LOL.PS 라인전 점수의 입력과 같은 10 · 15분 맞라이너 CS · 골드 · 경험치 차 (LOL.PS 점수 모델은 공개되지 않아 차이 값만). 참고한 원문 · 구현 대응: [`tools/opscore-fit/README.md`](tools/opscore-fit/README.md)
|
|
- 실제 E2E (2026-10-15, v1.3.2, `app/scripts/culprit-real-e2e.mts`): 실제 Claude Opus 5.5(생각 high), 외부 사이트 접속 없음. 발로란트 시연 경기 33초 · $0.138, 롤 시연 경기 36초 · $0.123. 기록 · [`docs/dev/test-results.md`](docs/dev/test-results.md)
|
|
- 리플레이 동기화: 공식 · 비공식 API 로 리플레이 시간을 읽을 수 있을 때만 넣는다 (화면 글자 인식(OCR) · 게임 설정 파일 고치기는 하지 않음). Windows 실기 확인 전이라 v1.3.x 에는 없다
|
|
- 앱: 경기 상세에서 추가 지표 저장(발로란트 피해량 · 받은 피해 · KAST · 첫킬 · 설치/해체 · 라운드별 장비, 롤 포지션 · 딜량 · 시야 · 10/15분 CS), "분석할 수 있는 경기" 판정(경기 결과 · 녹음 공백 1분 · 음성 변환), 근거 번호가 달린 AI 자료 만들기, 결과 저장(`culprit_analyses`). `app/src/core/culprit.ts`
|
|
- 사이트 서버: Claude API 키는 서버 환경 변수 `ANTHROPIC_API_KEY` 에만 (`deploy/site/set-anthropic-key.sh`). 권한 · 월 $100 · 하루 20회 · 중복 잠금, 구조화 출력, 근거 번호 확인, 비용 장부(토큰 · 비용만, 대화 내용 없음). `site/server/src/culprit.ts`, 지시문 · 지식 묶음 `site/server/prompt/` (지식 묶음의 요원 · 챔피언 목록은 공식 데이터로 하루 한 번 갱신)
|
|
- 화면: 사이트 🔍 범인찾기 탭 (`site/web/src/pages/CulpritPage.tsx`), 경기 화면의 "🔍 범인 보기". 화면 확인: `node --import tsx app/scripts/culprit-shots.mts`
|
|
|
|
## 진행 현황
|
|
|
|
| 단계 | 내용 | 상태 |
|
|
|---|---|---|
|
|
| M0 기술 검증 | DAVE 음성 연결, faster-whisper STT·음량·잡음·사전, 게임 로컬 API 처리, 게임 PC 진단 기능 | ✅ 완료 ([결과](docs/dev/M0-verification.md)) |
|
|
| M1 녹음 + STT 기본 | 따라가기·명령 참여, TTS 안내, 유저별 녹음, 대기열 STT, /녹음제외·참여 | ✅ 완료 ([실음성 테스트](docs/dev/test-results.md)) |
|
|
| M2 사이트 서버 · 사이트 v1 | 디스코드 로그인, 연결 확인·잠금, 타임라인·따라 읽기·필터·검색·실시간 | ✅ 완료 · https://gvr.tkrmagid.kr 배포 |
|
|
| M3 발로란트 연동 | 경기 감지, 킬·라운드·채팅, 라운드 시간 + 경기 경과 시간, 경기 상세 | ✅ 완료 ([전체 스택 테스트](docs/dev/test-results.md)) |
|
|
| M4 롤 연동 · 채팅 OCR | 게임 API 이벤트, LCU 결과·타임라인, 채팅 OCR·로그, 롤 경기 상세 | ✅ 완료 (Windows 실기 확인: [기록](docs/dev/test-results.md)) · v1.3.3 에서 OCR 은 빼고 LCU API · 로그 파일만 씀 |
|
|
| M5 exe · 설정 · 모델 | 포터블 exe, 첫 실행 마법사, GPU 감지·모델 다운로드, 암호화 저장, 7일 삭제 | ✅ 완료 (Windows 빌드·실행 확인) |
|
|
| M6 단어사전 · UI/UX | 핫워드·교정 사전, 사이트 교정 반영, 테마·애니메이션·효과음 | ✅ 완료 ([사전 효과](docs/dev/test-results.md)) |
|
|
| M7 실사용 테스트 | 통합 테스트, 성능·안정화 | ✅ 완료 (GPU 실음성: CER 3.6%, 지연 1.05초 · [기록](docs/dev/test-results.md)) |
|
|
| M8 파인튜닝 | 교정 데이터 + 합성 음성 LoRA 학습, 오류율 비교 후 교체 | ✅ 완료 (GPU 시험 학습: CER 4.8% → 1.8%) |
|
|
| 범인찾기 (v1.3.x) | AI(Claude Opus 5.5 high) 10명 평점 · 팀별 범인 · 근거, 기록 점수(OP.GG OP스코어 계산법) · 10/15분 라인전(LOL.PS 정의) | ✅ 완료 (실제 Claude E2E, 사이트 배포, [v1.3.5](https://git.tkrmagid.kr/tkrmagid/game_voice_recorder/releases/tag/v1.3.5) · 리플레이 동기화는 Windows 실기 확인 뒤) |
|
|
|
|
## 저장소 구조
|
|
|
|
```
|
|
app/ 게임 PC 앱 (Electron + Node.js 코어, TypeScript)
|
|
worker/ STT 워커 (Python, faster-whisper, 롤 로그 채팅, 모델 관리, 파인튜닝)
|
|
site/server/ 사이트 서버 (Fastify, Discord OAuth2, 기기 중계)
|
|
site/web/ 사이트 화면 (React + Vite)
|
|
packages/shared/ 앱·사이트 공통 타입
|
|
deploy/ 사이트 서버 배포 (.5 Docker, gvr.tkrmagid.kr)
|
|
tools/ 사전 생성기 등
|
|
docs/ 설명서·계획서, 개발 문서, 브랜드
|
|
assets/ 앱·사이트 아이콘·배너
|
|
```
|
|
|
|
## 개발
|
|
|
|
```bash
|
|
# STT 워커
|
|
cd worker && uv venv --python 3.11 .venv && uv pip install --python .venv/bin/python -r requirements-dev.txt
|
|
.venv/bin/python -m pytest -q
|
|
|
|
# 사이트 (가짜 데이터로 화면 개발: http://127.0.0.1:5173)
|
|
cd site/web && npm install && npm run dev
|
|
cd site/server && npm install && npm test
|
|
deploy/site/deploy.sh # .5 배포 (deploy/README.md)
|
|
|
|
# 앱 코어 (헤드리스)
|
|
cd app && npm install && npm test
|
|
npm run core -- --diagnose # 게임 PC 진단 (GPU·STT 속도·Riot API·롤 로그 채팅)
|
|
```
|