feat: Hearo 1차 구현 — 프로그램 소리 실시간 번역 자막
프로그램별 오디오를 캡처해 로컬 GPU에서 음성인식→번역하고 화면 위 자막으로 보여주는 데스크톱 앱. 한/영/일/중 4개 언어. 구성 - audio: WASAPI 프로그램별 캡처(C++ 보조 프로그램) + 장치 루프백 폴백, 적응형 VAD 발화 분할 - models: 속도~품질 5단계 티어, faster-whisper + CTranslate2/LLM 2백엔드, 용어집(플레이스홀더 보호 + 프롬프트 주입) - core: Qt 비의존 파이프라인 엔진 (캡처/분할/추론 3스레드, 큐 연결) - ui: 사이드바 5화면 + 무테두리 항상위 자막 오버레이, 자체 다크 테마 모델 선정 근거는 docs/MODELS.md, 추가학습 가능 여부와 방법은 docs/FINETUNING.md 참고. 검증: pytest 39개 통과 (GPU·오디오 장치 없이 실행), ruff clean Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
EJClaw
169
README.md
169
README.md
@@ -1,2 +1,169 @@
|
||||
# live-app-translator
|
||||
# Hearo — 듣고, 바로 이해하다
|
||||
|
||||
특정 프로그램에서 나오는 소리를 실시간으로 받아 번역해 자막으로 보여줍니다.
|
||||
번역은 전부 **내 컴퓨터의 GPU에서** 돌아갑니다. 인터넷도, API 키도 필요 없습니다.
|
||||
|
||||
한국어 · English · 日本語 · 中文 사이를 번역합니다.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 무엇을 하는 프로그램인가
|
||||
|
||||
게임을 하는데 영어 음성만 나올 때, 해외 방송을 보는데 자막이 없을 때,
|
||||
그 프로그램을 골라서 `번역 시작`만 누르면 화면 아래에 한국어 자막이 뜹니다.
|
||||
|
||||
```
|
||||
게임 소리 → 음성인식 → 번역 → 화면 위 자막
|
||||
(Whisper) (Seed-X / NLLB)
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 주요 기능
|
||||
|
||||
- **프로그램 단위 소리 캡처** — 게임 소리만 받고 디스코드 음성은 안 받습니다
|
||||
- **5단계 품질 선택** — 속도 우선(0.6초)부터 품질 우선까지, GPU 사양에 맞춰 고릅니다
|
||||
- **자막 자유 설정** — 글꼴·크기·색·외곽선·투명도·위치·줄 수
|
||||
- **용어집** — 게임 고유명사를 원하는 번역으로 고정. 학습 없이 즉시 적용
|
||||
- **추가학습** — 게임/방송 말투로 번역 모델을 LoRA 학습시킬 수 있습니다
|
||||
- **완전 로컬** — 음성이 외부로 나가지 않습니다
|
||||
|
||||
---
|
||||
|
||||
## 설치
|
||||
|
||||
### 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
|
||||
hearo
|
||||
```
|
||||
|
||||
또는 `python -m hearo`
|
||||
|
||||
---
|
||||
|
||||
## 처음 쓸 때
|
||||
|
||||
1. **모델** 화면에서 티어를 고릅니다. VRAM 8GB면 `3. 균형`, 10GB 이상이면 `4. 정밀`
|
||||
2. **홈** 화면에서 소리를 받아올 프로그램을 고릅니다
|
||||
3. 원본 언어(자동 감지 권장)와 번역할 언어를 고릅니다
|
||||
4. `번역 시작`
|
||||
|
||||
모델은 처음 한 번만 자동으로 내려받습니다 (2~17GB, 티어에 따라 다름).
|
||||
저장 위치는 `%APPDATA%\Hearo\models` 입니다.
|
||||
|
||||
---
|
||||
|
||||
## 모델 티어
|
||||
|
||||
| # | 이름 | VRAM | 지연 | 설명 |
|
||||
|---|---|---|---|---|
|
||||
| 1 | 번개 | 2GB | 0.6초 | 속도 최우선. 저사양 GPU |
|
||||
| 2 | 신속 | 4GB | 0.9초 | 인식률은 최상급, 번역만 경량 |
|
||||
| 3 | **균형** | 6GB | 1.2초 | 기본값. 8GB GPU에 가장 무난 |
|
||||
| 4 | **정밀** | 10GB | 2.0초 | **추천.** 현 시점 최고 번역 품질 |
|
||||
| 5 | 극한 | 16GB | 3.0초 | 추가학습(LoRA)에 최적 |
|
||||
|
||||
|
||||
|
||||
어떤 모델을 왜 골랐는지는 [docs/MODELS.md](docs/MODELS.md)에 정리했습니다.
|
||||
|
||||
---
|
||||
|
||||
## 용어집
|
||||
|
||||
게임 고유명사가 이상하게 번역될 때 씁니다. **학습이 필요 없고 즉시 적용됩니다.**
|
||||
|
||||
`용어집` 화면에서 직접 입력하거나 CSV로 가져오세요.
|
||||
|
||||
```csv
|
||||
원문 용어,한국어 역어,English 역어,日本語 역어,中文 역어,메모
|
||||
Nexus,넥서스,Nexus,ネクサス,基地,LoL
|
||||
baron,바론,Baron,バロン,男爵,LoL
|
||||
```
|
||||
|
||||
게임 하나당 200~500개만 등록해도 체감 품질이 크게 달라집니다.
|
||||
|
||||
## 추가학습
|
||||
|
||||
말투나 문장 구조까지 바꾸고 싶다면 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)를 참고하세요.
|
||||
|
||||
---
|
||||
|
||||
## 자막 창 조작
|
||||
|
||||
| 동작 | 결과 |
|
||||
|---|---|
|
||||
| 드래그 | 위치 이동 |
|
||||
| 우하단 모서리 드래그 | 크기 조절 |
|
||||
| 마우스 휠 | 글자 크기 |
|
||||
| 우클릭 | 잠금 / 클릭 통과 / 항상 위에 / 숨기기 |
|
||||
|
||||
전체화면 게임에서 자막이 안 보이면 게임을 **테두리 없는 창 모드**로 바꾸세요.
|
||||
독점 전체화면(exclusive fullscreen)에서는 어떤 오버레이도 표시되지 않습니다.
|
||||
|
||||
---
|
||||
|
||||
## 개발
|
||||
|
||||
```bash
|
||||
pip install -e ".[dev]"
|
||||
pytest # GPU·오디오 장치 없이 실행됩니다
|
||||
ruff check src tests scripts
|
||||
```
|
||||
|
||||
구조는 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)를 보세요.
|
||||
|
||||
## 라이선스
|
||||
|
||||
MIT. 사용하는 모델은 각자의 라이선스를 따릅니다
|
||||
(Whisper: MIT, NLLB: CC-BY-NC, Seed-X: OpenMDW, Qwen3: Apache-2.0).
|
||||
**NLLB는 비상업적 이용만 허용됩니다.** 상업적으로 쓰려면 4~5티어를 사용하세요.
|
||||
|
||||
Reference in New Issue
Block a user