81e0271b69
Some checks failed
Windows / verify (push) Has been cancelled
모델이 티어에 따라 2~17GB 를 차지하는데 %APPDATA% 에 박혀 있어서 C 드라이브가 좁은 사람은 손쓸 방법이 없었다. 처음 켤 때 한 번 묻고, 그 선택을 기억하고, 설정에서 바꿀 수 있게 한다. 닭과 달걀 문제가 하나 있다 — "어디에 둘지" 는 사용자가 정하는데 그 선택 자체는 고정된 곳에 적어둬야 다음 실행에 찾을 수 있다. 그래서 OS 표준 폴더에는 위치를 가리키는 쪽지(location.json) 한 장만 두고, 내용물은 전부 고른 폴더에 둔다. - storage.py 신설: 쪽지 읽기/쓰기, 경로 검증, 여유 공간, 데이터 이동 - config.py 의 CONFIG_PATH 를 config_path() 로 바꾼다. import 시점 상수라 위치를 바꿔도 옛 경로를 계속 가리켰다 - 위치가 정해지기 전에는 파일 로그를 열지 않는다. 열면 고르지도 않은 기본 폴더가 만들어지고 거기에 로그가 남는다 - 이전 버전 사용자에게는 묻지 않는다. 기본 위치에 쓰던 흔적이 있으면 그대로 쓴다 — 같은 자리를 다시 고르는 헛수고를 시킬 이유가 없다 - 고른 디스크가 빠져도 죽지 않고 기본 위치로 물러난다 - 위치를 바꿀 때 받아둔 모델을 옮길지 물어본다. 수 GB 라 창이 얼어붙지 않도록 별도 스레드에서 옮긴다 - windows_smoke 에 이 화면 렌더링 점검을 추가하고, 스크린샷을 호스트로 회수한다. 경로 표기와 디스크 조회는 OS 마다 다르게 도는 부분이다
325 lines
12 KiB
Markdown
325 lines
12 KiB
Markdown
# LiveSub — 게임 소리를 실시간 자막으로
|
|
|
|
|
|
|
|
게임이나 프로그램에서 나오는 소리를 실시간으로 받아 번역해, 화면 위에 자막으로 얹어줍니다.
|
|
디스코드 오버레이처럼 동작하고, 번역은 전부 **내 컴퓨터의 GPU에서** 돌아갑니다.
|
|
인터넷도, API 키도 필요 없습니다.
|
|
|
|
한국어 · English · 日本語 · 中文 사이를 번역합니다.
|
|
|
|
---
|
|
|
|
## 무엇을 하는 프로그램인가
|
|
|
|
게임을 하는데 영어 음성만 나올 때, 해외 방송을 보는데 자막이 없을 때,
|
|
그 프로그램을 골라서 `번역 시작`만 누르면 화면에 한국어 자막이 뜹니다.
|
|
|
|
```
|
|
게임 소리 → 음성인식 → 번역 → 화면 위 자막
|
|
(Whisper) (Seed-X / NLLB)
|
|
```
|
|
|
|
|
|
|
|
## 주요 기능
|
|
|
|
- **프로그램 단위 소리 캡처** — 게임 소리만 받고 디스코드 음성은 안 받습니다
|
|
- **게임과 같이 써도 안 무겁게** — GPU를 얼마나 양보할지 직접 정합니다 (아래 참고)
|
|
- **디스코드식 자막 배치** — 모니터를 고르고 9칸 중 하나를 누르면 그 자리에 붙습니다
|
|
- **전역 단축키** — 게임 중에 `Ctrl+Alt+S` 로 자막을 껐다 켭니다
|
|
- **게임별 기본 용어집 내장** — 옵치2·워독스·배그·R6·롤·발로란트·에이펙스 등 **540개** (필수 게임은 기본 켜짐)
|
|
- **5단계 품질 선택** — 속도 우선(0.6초)부터 품질 우선까지
|
|
- **자막 자유 설정** — 글꼴·크기·색·외곽선·투명도·줄 수
|
|
- **추가학습** — 게임/방송 말투로 번역 모델을 LoRA 학습시킬 수 있습니다
|
|
- **존댓말 / 반말 선택** — 기본은 존댓말. 원문이 실제로 존댓말이면 반말 모드여도 존댓말을 지킵니다
|
|
- **포터블 exe** — 설치 없이 파일 하나로 실행 (아래 참고)
|
|
- **완전 로컬** — 음성이 외부로 나가지 않습니다
|
|
|
|
---
|
|
|
|
## 게임과 같이 쓰기 (GPU 절약)
|
|
|
|
게임이 먼저입니다. `설정` 화면의 **저부하 모드**(기본 켜짐)가 이렇게 동작합니다.
|
|
|
|
| 항목 | 기본값 | 하는 일 |
|
|
|---|---|---|
|
|
| 연산 정밀도 | int8 | VRAM 사용량과 연산량을 줄입니다 |
|
|
| VRAM 상한 | 35% | 게임이 쓸 VRAM을 먼저 확보합니다 |
|
|
| GPU 양보 시간 | 60ms | 문장 하나 처리 후 GPU를 잠깐 놓습니다 |
|
|
| 유휴 시 모델 해제 | 300초 | 조용하면 모델을 내려 VRAM을 통째로 반납합니다 |
|
|
| 중간 결과 | 꺼짐 | 같은 오디오를 두 번 인식하지 않습니다 |
|
|
|
|
8GB GPU 기준으로 자막이 약 2.8GB만 쓰고 나머지 5GB 이상을 게임에 남깁니다.
|
|
게임이 여전히 버벅이면 VRAM 상한을 낮추거나 모델 티어를 `1. 번개`로 내리세요.
|
|
|
|
|
|
|
|
## 말투 — 존댓말 / 반말
|
|
|
|
홈 화면에서 고릅니다. **기본은 존댓말**입니다.
|
|
|
|
| 상황 | 존댓말 모드 | 반말 모드 |
|
|
|---|---|---|
|
|
| 영어·중국어 원문 (높임 없음) | 존댓말 | 반말 |
|
|
| 일본어 원문이 `です/ます` | 존댓말 | **존댓말** |
|
|
| 일본어 원문이 반말 | 존댓말 | 반말 |
|
|
|
|
**원문이 실제로 존댓말이면 반말 모드여도 존댓말로 나옵니다.** 상대가 정중하게
|
|
말했는데 자막이 반말이면 뉘앙스가 통째로 뒤집히기 때문입니다.
|
|
영어·중국어는 문법적 높임이 없어서 항상 고른 모드를 따릅니다.
|
|
|
|
```
|
|
Enemy coming from the left 존댓말 → 적이 왼쪽에서 옵니다
|
|
반말 → 적이 왼쪽에서 와
|
|
左から来ます (정중) 존댓말 → 적이 왼쪽에서 옵니다
|
|
반말 → 적이 왼쪽에서 옵니다 ← 원문이 존댓말
|
|
```
|
|
|
|
## 자막 위치 잡기
|
|
|
|
`자막` 화면에서 **모니터를 고르고 네모칸을 누르면** 그 자리에 붙습니다.
|
|
디스코드 오버레이와 같은 방식입니다. 미세 조정은 자막을 직접 드래그하면 되고,
|
|
그러면 그 위치를 그대로 기억합니다.
|
|
|
|
|
|
|
|
| 단축키 | 동작 |
|
|
|---|---|
|
|
| `Ctrl+Alt+S` | 자막 켜기 / 끄기 |
|
|
| `Ctrl+Alt+D` | 번역 시작 / 정지 |
|
|
|
|
전역 단축키라 **게임 창이 떠 있어도 동작합니다** (Windows 전용). `설정`에서 바꿀 수 있습니다.
|
|
|
|
---
|
|
|
|
## 설치 — 둘 중 하나
|
|
|
|
| | 포터블 (권장) | 일반 설치 |
|
|
|---|---|---|
|
|
| 준비물 | `LiveSub.exe` 하나 | Python + PyTorch |
|
|
| 크기 | 약 500~700MB | 약 3GB |
|
|
| 쓸 수 있는 티어 | 1~3 | 1~5 전부 |
|
|
| 번역 품질 | NLLB | NLLB + Seed-X / Qwen3 |
|
|
|
|
포터블은 PyTorch를 빼서 만듭니다 (토크나이저용 `transformers`는 포함). PyTorch+CUDA만 2.5GB라 한 파일로 묶으면
|
|
**실행할 때마다** 그걸 임시폴더에 푸느라 1분 넘게 걸리기 때문입니다.
|
|
음성인식도 번역도 CTranslate2 위에서 돌아가 PyTorch가 필요 없으므로,
|
|
1~3티어는 포터블에서 그대로 다 됩니다.
|
|
|
|
### 포터블 만들기
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File packaging\build-portable.ps1
|
|
```
|
|
|
|
`dist\LiveSub.exe` 하나만 복사하면 끝입니다. 모델은 exe에 없고, **첫 실행 때
|
|
고른 폴더**로 내려받습니다.
|
|
|
|
---
|
|
|
|
## 일반 설치
|
|
|
|
### 1. 사전 준비
|
|
|
|
- Windows 10 (2004 이상) 또는 Windows 11
|
|
- NVIDIA GPU (권장 VRAM 6GB 이상) + 최신 드라이버
|
|
- Python 3.10 ~ 3.12
|
|
|
|
### 2. PyTorch (CUDA 빌드) 먼저
|
|
|
|
CPU 버전이 깔리면 GPU를 못 씁니다. 반드시 이 순서로 설치하세요.
|
|
|
|
```powershell
|
|
py -3.12 -m venv .venv
|
|
.venv\Scripts\activate
|
|
|
|
# Blackwell(RTX 50 시리즈)은 cu128, 그 이전 세대는 cu124
|
|
pip install torch --index-url https://download.pytorch.org/whl/cu128
|
|
```
|
|
|
|
### 3. 나머지 설치
|
|
|
|
```powershell
|
|
pip install -r requirements.txt
|
|
pip install -e .
|
|
```
|
|
|
|
### 4. 프로그램별 캡처 켜기 (선택, 권장)
|
|
|
|
이걸 빌드하지 않으면 출력 장치 전체 소리를 받습니다 (다른 앱 소리도 섞임).
|
|
|
|
```powershell
|
|
# Visual Studio 2022 Build Tools (C++ 데스크톱) + CMake 필요
|
|
winget install Microsoft.VisualStudio.2022.BuildTools
|
|
winget install Kitware.CMake
|
|
|
|
powershell -ExecutionPolicy Bypass -File native\process_loopback\build.ps1
|
|
```
|
|
|
|
### 5. 실행
|
|
|
|
```powershell
|
|
livesub
|
|
```
|
|
|
|
또는 `python -m livesub`
|
|
|
|
---
|
|
|
|
## 처음 쓸 때
|
|
|
|
### 먼저 저장 위치를 고릅니다
|
|
|
|
모델이 티어에 따라 2~17GB를 차지합니다. C 드라이브가 좁으면 곤란하니
|
|
**처음 켜면 어디에 저장할지 물어봅니다.** 고른 폴더에 모델·설정·번역 기록이
|
|
전부 들어갑니다.
|
|
|
|
|
|
|
|
한 번 고르면 기억하므로 다음부터는 바로 뜹니다. Windows 표준 폴더
|
|
(`%APPDATA%\LiveSub`)가 기본 제안이고 그대로 두셔도 됩니다 — 거기에는
|
|
"어느 폴더를 쓰는지" 적은 쪽지 한 장만 남습니다.
|
|
|
|
나중에 바꾸려면 `설정 > 저장 위치 > 위치 변경`입니다. 받아둔 모델을 새 위치로
|
|
**옮길지 물어보므로** 다시 받을 필요는 없습니다.
|
|
|
|
|
|
|
|
### 그다음
|
|
|
|
1. **홈** 화면에서 소리를 받아올 프로그램을 고릅니다
|
|
2. 원본 언어(자동 감지 권장)와 번역할 언어를 고릅니다
|
|
3. **용어집** 화면에서 하는 게임을 체크합니다 (고유명사 오역이 확 줄어듭니다)
|
|
4. **자막** 화면에서 모니터와 위치를 정합니다
|
|
5. `번역 시작` — 또는 게임 중에 `Ctrl+Alt+D`
|
|
|
|
모델 티어 기본값은 `2. 신속`입니다. 게임과 같이 돌리기 좋은 지점이라 그렇게 잡았고,
|
|
VRAM이 넉넉하면 **모델** 화면에서 올리면 됩니다.
|
|
|
|
모델은 처음 한 번만 자동으로 내려받습니다 (2~17GB, 티어에 따라 다름).
|
|
저장 위치는 처음 켤 때 고른 그 폴더입니다.
|
|
|
|
|
|
|
|
---
|
|
|
|
## 모델 티어
|
|
|
|
| # | 이름 | VRAM | 지연 | 설명 |
|
|
|---|---|---|---|---|
|
|
| 1 | 번개 | 2GB | 0.6초 | 속도 최우선. 저사양 GPU |
|
|
| 2 | **신속** | 4GB | 0.9초 | **기본값.** 인식률은 최상급, 번역만 경량 |
|
|
| 3 | 균형 | 6GB | 1.2초 | 게임을 안 켜고 볼 때 무난 |
|
|
| 4 | **정밀** | 10GB | 2.0초 | **추천.** 현 시점 최고 번역 품질 |
|
|
| 5 | 극한 | 16GB | 3.0초 | 추가학습(LoRA)에 최적 |
|
|
|
|
어떤 모델을 왜 골랐는지는 [docs/MODELS.md](docs/MODELS.md)에 정리했습니다.
|
|
|
|
---
|
|
|
|
## 용어집
|
|
|
|
게임 고유명사가 이상하게 번역될 때 씁니다. **학습이 필요 없고 즉시 적용됩니다.**
|
|
|
|
### 기본 제공 용어집
|
|
|
|
**처음 설치하면 `FPS 공통 · 오버워치2 · 배그 · R6 · 워독스`가 이미 켜져 있습니다.**
|
|
안 하는 게임은 체크를 끄면 됩니다.
|
|
|
|
| 팩 | 개수 | 내용 |
|
|
|---|---|---|
|
|
| 리그 오브 레전드 | 74 | 바론·갱·억제기·한타·오브젝트 콜 |
|
|
| 레인보우 식스 시즈 | 67 | 보강·하드브리치·앵커/로머·디퓨저·파밸 |
|
|
| 배틀그라운드 | 65 | 자기장·어부·파밍·낙하·스쿼드 콜 |
|
|
| 발로란트 | 59 | 스파이크·설치·해체·이코·리테이크 |
|
|
| 워치독스 | 59 | 데드섹·ctOS·블룸·해킹/잠입 용어 |
|
|
| 오버워치 2 | 49 | 궁 게이지·거점·화물·역할군 |
|
|
| FPS 공통 | 46 | 장르 전반의 총기·교전·파티 콜 |
|
|
| 에이펙스 레전드 | 45 | 링·배너·리스폰 비컨·스쿼드 콜 |
|
|
| 마인크래프트 | 38 | 블록·몹·차원 이름 (한국어판 공식 번역어) |
|
|
| 방송·스트리밍 | 38 | 후원·구독·클립·메타 등 방송 말투 |
|
|
|
|
#### 여러 팩을 같이 켜면
|
|
|
|
적용 순서는 **장르 공통 → 게임 전용 → 내가 등록한 것** 입니다. 뒤에 오는 쪽이 이기므로
|
|
`knocked`는 배그를 켰으면 항상 "눕혔다"(배그)가 되고, 체크한 순서에 휘둘리지 않습니다.
|
|
|
|
게임 전용 팩끼리 역어가 갈리는 경우(예: `payload`가 오버워치는 "화물", 워독스는 "페이로드")는
|
|
용어집 화면이 어떤 단어인지 알려줍니다. 안 하는 게임을 끄거나, 원하는 역어를 직접
|
|
등록하면 됩니다.
|
|
|
|
|
|
|
|
### 직접 추가하기
|
|
|
|
`용어집` 화면 표에 입력하거나 CSV로 가져오세요.
|
|
**같은 단어를 직접 등록하면 기본 팩보다 항상 우선합니다.**
|
|
|
|
```csv
|
|
원문 용어,한국어 역어,English 역어,日本語 역어,中文 역어,메모
|
|
Nexus,넥서스,Nexus,ネクサス,基地,LoL
|
|
baron,바론,Baron,バロン,男爵,LoL
|
|
```
|
|
|
|
## 추가학습
|
|
|
|
말투나 문장 구조까지 바꾸고 싶다면 LoRA로 학습시킬 수 있습니다.
|
|
언어쌍당 문장 1,000~3,000개가 필요합니다.
|
|
|
|
```powershell
|
|
pip install -e ".[finetune]"
|
|
python scripts\finetune_mt.py --data data\game.jsonl --tier ultimate --output .\adapters\game-ko
|
|
```
|
|
|
|
데이터를 어떻게 모으고 어느 모델을 학습시켜야 하는지는
|
|
[docs/FINETUNING.md](docs/FINETUNING.md)를 참고하세요.
|
|
|
|
---
|
|
|
|
## 자막 창 조작
|
|
|
|
| 동작 | 결과 |
|
|
|---|---|
|
|
| `Ctrl+Alt+S` | 자막 켜기 / 끄기 (게임 중에도 동작) |
|
|
| 드래그 | 위치 이동 (자유 배치로 전환) |
|
|
| 우하단 모서리 드래그 | 크기 조절 |
|
|
| 마우스 휠 | 글자 크기 |
|
|
| 우클릭 | 잠금 / 클릭 통과 / 항상 위에 / 숨기기 |
|
|
|
|
클릭 통과는 기본으로 켜져 있어, 자막 위를 클릭해도 게임으로 전달됩니다.
|
|
위치를 옮기려면 `자막` 화면에서 클릭 통과를 잠깐 끄세요.
|
|
|
|
전체화면 게임에서 자막이 안 보이면 게임을 **테두리 없는 창 모드**로 바꾸세요.
|
|
독점 전체화면(exclusive fullscreen)에서는 어떤 오버레이도 표시되지 않습니다.
|
|
|
|
---
|
|
|
|
## 개발
|
|
|
|
```bash
|
|
pip install -e ".[dev]"
|
|
pytest # GPU·오디오 장치 없이 실행됩니다
|
|
ruff check src tests scripts
|
|
```
|
|
|
|
구조는 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)를 보세요.
|
|
|
|
### Windows 자동 검증
|
|
|
|
개발은 리눅스에서 하므로 오디오 캡처·전역 단축키·exe 빌드는 여기서 테스트할 수
|
|
없습니다. Windows 러너를 붙이면 push할 때마다 자동으로 확인되고 exe와
|
|
스크린샷이 artifact로 올라옵니다 — [docs/WINDOWS-TESTING.md](docs/WINDOWS-TESTING.md).
|
|
|
|
러너 없이 그때그때 확인만 하려면:
|
|
|
|
```powershell
|
|
.\.venv\Scripts\python packaging\windows_smoke.py
|
|
```
|
|
|
|
## 라이선스
|
|
|
|
MIT. 사용하는 모델은 각자의 라이선스를 따릅니다
|
|
(Whisper: MIT, NLLB: CC-BY-NC, Seed-X: OpenMDW, Qwen3: Apache-2.0).
|
|
**NLLB는 비상업적 이용만 허용됩니다.** 상업적으로 쓰려면 4~5티어를 사용하세요.
|