Files

EJClaw 1a87ec6677 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>

2026-09-21 10:47:11 +09:00

5.2 KiB

Raw Blame History

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를 못 씁니다. 반드시 이 순서로 설치하세요.

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. 나머지 설치

pip install -r requirements.txt
pip install -e .

4. 프로그램별 캡처 켜기 (선택, 권장)

이걸 빌드하지 않으면 출력 장치 전체 소리를 받습니다 (다른 앱 소리도 섞임).

# 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. 실행

hearo

또는 python -m hearo

처음 쓸 때

모델 화면에서 티어를 고릅니다. VRAM 8GB면 3. 균형, 10GB 이상이면 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에 정리했습니다.

용어집

게임 고유명사가 이상하게 번역될 때 씁니다. 학습이 필요 없고 즉시 적용됩니다.

용어집 화면에서 직접 입력하거나 CSV로 가져오세요.

원문 용어,한국어 역어,English 역어,日本語 역어,中文 역어,메모
Nexus,넥서스,Nexus,ネクサス,基地,LoL
baron,바론,Baron,バロン,男爵,LoL

게임 하나당 200~500개만 등록해도 체감 품질이 크게 달라집니다.

추가학습

말투나 문장 구조까지 바꾸고 싶다면 LoRA로 학습시킬 수 있습니다. 언어쌍당 문장 1,000~3,000개가 필요합니다.

pip install -e ".[finetune]"
python scripts\finetune_mt.py --data data\game.jsonl --tier ultimate --output .\adapters\game-ko

데이터를 어떻게 모으고 어느 모델을 학습시켜야 하는지는 docs/FINETUNING.md를 참고하세요.

자막 창 조작

동작	결과
드래그	위치 이동
우하단 모서리 드래그	크기 조절
마우스 휠	글자 크기
우클릭	잠금 / 클릭 통과 / 항상 위에 / 숨기기

전체화면 게임에서 자막이 안 보이면 게임을 테두리 없는 창 모드로 바꾸세요. 독점 전체화면(exclusive fullscreen)에서는 어떤 오버레이도 표시되지 않습니다.

개발

pip install -e ".[dev]"
pytest              # GPU·오디오 장치 없이 실행됩니다
ruff check src tests scripts

구조는 docs/ARCHITECTURE.md를 보세요.

라이선스

MIT. 사용하는 모델은 각자의 라이선스를 따릅니다 (Whisper: MIT, NLLB: CC-BY-NC, Seed-X: OpenMDW, Qwen3: Apache-2.0). NLLB는 비상업적 이용만 허용됩니다. 상업적으로 쓰려면 4~5티어를 사용하세요.

5.2 KiB Raw Blame History