Files

EJClaw 8b36b244ff feat: LiveSub 2차 — 자막 on/off, 모니터·위치 선택, GPU 저부하, 게임 용어집

이름을 Hearo → LiveSub 로 변경. 말장난보다 하는 일이 바로 보이는 쪽이 낫다.

자막 on/off
- 전역 단축키 Ctrl+Alt+S (자막) / Ctrl+Alt+D (번역) — Windows RegisterHotKey +
  네이티브 이벤트 필터라 게임 창이 떠 있어도 동작. 다른 OS 에서는 no-op
- 단축키·체크박스·우클릭 메뉴가 모두 같은 경로를 타도록 통합

모니터 선택 + 디스코드식 배치
- placement.py: Qt 비의존 배치 계산 (모니터 목록 → 9분할 좌표)
- AnchorGrid 위젯으로 3x3 위치 선택, 드래그하면 자유 배치로 전환
- 모니터 구성이 바뀌어도 자막이 화면 밖으로 사라지지 않도록 클램프

GPU 저부하 모드 (기본 켜짐)
- 연산 정밀도 int8 강등, VRAM 상한 35%, 추론 후 60ms 양보,
  300초 무음 시 모델 언로드, 중간 결과 비활성
- 기본 티어를 균형(6GB) → 신속(4GB) 으로 하향
- 8GB GPU 기준 자막 2.8GB / 게임 5.2GB

게임 용어집 번들 (304개)
- 롤 74 · 발로란트 59 · 오버워치2 49 · FPS공통 46 · 마크 38 · 방송 38
- 체크박스로 켜고 끄며, 사용자가 직접 등록한 항목이 항상 우선

검증: pytest 91개 통과 (배치 14 + 팩 12 + UI 6 신규), ruff clean

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-09-21 17:49:26 +09:00

8.2 KiB

Raw Blame History

LiveSub — 게임 소리를 실시간 자막으로

게임이나 프로그램에서 나오는 소리를 실시간으로 받아 번역해, 화면 위에 자막으로 얹어줍니다. 디스코드 오버레이처럼 동작하고, 번역은 전부 내 컴퓨터의 GPU에서 돌아갑니다. 인터넷도, API 키도 필요 없습니다.

한국어 · English · 日本語 · 中文 사이를 번역합니다.

무엇을 하는 프로그램인가

게임을 하는데 영어 음성만 나올 때, 해외 방송을 보는데 자막이 없을 때, 그 프로그램을 골라서 번역 시작만 누르면 화면에 한국어 자막이 뜹니다.

게임 소리  →  음성인식  →  번역  →  화면 위 자막
             (Whisper)    (Seed-X / NLLB)

주요 기능

프로그램 단위 소리 캡처 — 게임 소리만 받고 디스코드 음성은 안 받습니다
게임과 같이 써도 안 무겁게 — GPU를 얼마나 양보할지 직접 정합니다 (아래 참고)
디스코드식 자막 배치 — 모니터를 고르고 9칸 중 하나를 누르면 그 자리에 붙습니다
전역 단축키 — 게임 중에 Ctrl+Alt+S 로 자막을 껐다 켭니다
게임별 기본 용어집 내장 — 롤·발로란트·옵치2·마크·FPS공통·방송용어 304개
5단계 품질 선택 — 속도 우선(0.6초)부터 품질 우선까지
자막 자유 설정 — 글꼴·크기·색·외곽선·투명도·줄 수
추가학습 — 게임/방송 말투로 번역 모델을 LoRA 학습시킬 수 있습니다
완전 로컬 — 음성이 외부로 나가지 않습니다

게임과 같이 쓰기 (GPU 절약)

게임이 먼저입니다. 설정 화면의 저부하 모드(기본 켜짐)가 이렇게 동작합니다.

항목	기본값	하는 일
연산 정밀도	int8	VRAM 사용량과 연산량을 줄입니다
VRAM 상한	35%	게임이 쓸 VRAM을 먼저 확보합니다
GPU 양보 시간	60ms	문장 하나 처리 후 GPU를 잠깐 놓습니다
유휴 시 모델 해제	300초	조용하면 모델을 내려 VRAM을 통째로 반납합니다
중간 결과	꺼짐	같은 오디오를 두 번 인식하지 않습니다

8GB GPU 기준으로 자막이 약 2.8GB만 쓰고 나머지 5GB 이상을 게임에 남깁니다. 게임이 여전히 버벅이면 VRAM 상한을 낮추거나 모델 티어를 1. 번개로 내리세요.

자막 위치 잡기

자막 화면에서 모니터를 고르고 네모칸을 누르면 그 자리에 붙습니다. 디스코드 오버레이와 같은 방식입니다. 미세 조정은 자막을 직접 드래그하면 되고, 그러면 그 위치를 그대로 기억합니다.

단축키	동작
`Ctrl+Alt+S`	자막 켜기 / 끄기
`Ctrl+Alt+D`	번역 시작 / 정지

전역 단축키라 게임 창이 떠 있어도 동작합니다 (Windows 전용). 설정에서 바꿀 수 있습니다.

설치

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

livesub

또는 python -m livesub

처음 쓸 때

홈 화면에서 소리를 받아올 프로그램을 고릅니다
원본 언어(자동 감지 권장)와 번역할 언어를 고릅니다
용어집 화면에서 하는 게임을 체크합니다 (고유명사 오역이 확 줄어듭니다)
자막 화면에서 모니터와 위치를 정합니다
번역 시작 — 또는 게임 중에 Ctrl+Alt+D

모델 티어 기본값은 2. 신속입니다. 게임과 같이 돌리기 좋은 지점이라 그렇게 잡았고, VRAM이 넉넉하면 모델 화면에서 올리면 됩니다.

모델은 처음 한 번만 자동으로 내려받습니다 (2~17GB, 티어에 따라 다름). 저장 위치는 %APPDATA%\LiveSub\models 입니다.

모델 티어

#	이름	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에 정리했습니다.

용어집

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

기본 제공 용어집 (체크만 하면 끝)

팩	개수	내용
리그 오브 레전드	74	바론·갱·억제기·한타·오브젝트 콜
발로란트	59	스파이크·설치·해체·이코·리테이크
오버워치 2	49	궁 게이지·거점·화물·역할군
FPS 공통	46	배그·CS·에이펙스에서 두루 쓰는 교전/파티 콜
마인크래프트	38	블록·몹·차원 이름 (한국어판 공식 번역어)
방송·스트리밍	38	후원·구독·클립·메타 등 방송 말투

직접 추가하기

용어집 화면 표에 입력하거나 CSV로 가져오세요. 같은 단어를 직접 등록하면 기본 팩보다 항상 우선합니다.

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

추가학습

말투나 문장 구조까지 바꾸고 싶다면 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를 참고하세요.

자막 창 조작

동작	결과
`Ctrl+Alt+S`	자막 켜기 / 끄기 (게임 중에도 동작)
드래그	위치 이동 (자유 배치로 전환)
우하단 모서리 드래그	크기 조절
마우스 휠	글자 크기
우클릭	잠금 / 클릭 통과 / 항상 위에 / 숨기기

클릭 통과는 기본으로 켜져 있어, 자막 위를 클릭해도 게임으로 전달됩니다. 위치를 옮기려면 자막 화면에서 클릭 통과를 잠깐 끄세요.

전체화면 게임에서 자막이 안 보이면 게임을 테두리 없는 창 모드로 바꾸세요. 독점 전체화면(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티어를 사용하세요.

8.2 KiB Raw Blame History