e4a048c8d5
리뷰 지적 2건과, 그것을 고치다 드러난 용어집 버그 1건을 함께 처리했다. 1) 저부하 모드 토글이 모델에 반영되지 않던 버그 ModelManager 는 생성 시점의 low_power 로 정밀도를 정하는데 설정에서 토글해도 갱신되지 않았고, stop() 은 모델을 내리지 않아 이전 정밀도 모델이 그대로 남았다. TranslationEngine.sync_performance() 를 추가해 값이 바뀌면 언로드 후 갱신하고, _bootstrap 과 재시작 경로에서 부른다. 2) 필수 게임 팩이 기본으로 꺼져 있던 문제 새 설치 기본값을 fps-common + 오버워치 + 배그 + R6 + 워독스로 켰다. 3) (1)(2)를 고치며 드러난 것: 팩 여러 개를 켜면 결과가 체크 순서에 휘둘렸다. knocked 가 FPS공통 "기절" / 배그 "눕혔다" 로 갈리는 식으로 19개 용어가 충돌하는데, 사용자는 그 순서를 볼 수도 바꿀 수도 없었다. 팩에 scope(generic/game) 를 두고 범용 -> 게임 전용 -> 사용자 항목 순으로 적용해 결정적으로 만들었다. 게임 팩끼리 갈리는 것은 사람이 판단할 문제라 find_conflicts() 로 뽑아 용어집 화면에 표시한다. 4) 용어 겹침 버그: "the blue"(조각)가 "blue zone" 보다 앞 위치라는 이유로 먼저 잡혀 "자기장 자기장" 이 됐다. 최장일치 정렬은 같은 시작 위치에서만 통한다. 조각 항목을 제거하고, 모든 팩을 켠 상태로 각 용어가 정확히 한 번만 치환되는지 검사하는 테스트를 추가했다. 검증: pytest 110개 통과 (저부하 6 + 팩 계층/충돌/겹침 12 신규), ruff clean Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
136 lines
6.9 KiB
Markdown
136 lines
6.9 KiB
Markdown
# 구조
|
|
|
|
## 데이터 흐름
|
|
|
|
```
|
|
[캡처 스레드] [분할 스레드] [추론 스레드] [GUI 스레드]
|
|
livesub_capture.exe → Segmenter (VAD) → Whisper → 번역 모델 → 자막 오버레이
|
|
또는 WASAPI 발화 단위로 절단 용어집 적용 컨트롤 창 로그
|
|
↓ ↓ ↓ ↑
|
|
오디오 큐 구간 큐(최대 32) TranslationLine Qt Signal
|
|
(16kHz mono f32) 확정 / 중간결과
|
|
```
|
|
|
|
세 워커 스레드는 모두 큐로만 연결된다. 어느 한 단계가 밀려도 나머지가 멈추지 않는다.
|
|
큐가 가득 차면 **오래된 오디오를 버린다** — 실시간 자막에서는 밀린 소리보다 지금 나는
|
|
소리가 항상 더 가치 있기 때문이다.
|
|
|
|
## 패키지
|
|
|
|
```
|
|
src/livesub/
|
|
constants.py 전역 상수, 언어 표, 경로
|
|
config.py 설정 dataclass + JSON 영속화
|
|
app.py 진입점
|
|
|
|
audio/
|
|
base.py CaptureBackend 추상 클래스, 리샘플링
|
|
process_loopback.py 프로그램별 캡처 (네이티브 보조 프로그램 구동)
|
|
wasapi_loopback.py 출력 장치 전체 캡처 (PyAudioWPatch)
|
|
file_source.py WAV 재생 (테스트·데모용)
|
|
segmenter.py 적응형 VAD로 발화 구간 절단
|
|
|
|
models/
|
|
tiers.py 5단계 티어 + 프롬프트 형식 정의
|
|
asr.py faster-whisper 래퍼
|
|
translator.py CTranslate2 / Transformers 두 백엔드
|
|
glossary.py 용어집 (플레이스홀더 보호 + 프롬프트 주입)
|
|
packs.py 게임별 기본 용어집 팩 로드·병합
|
|
manager.py 티어별 모델 쌍 로드·해제, GPU 탐지, VRAM 상한
|
|
|
|
core/
|
|
engine.py 파이프라인 오케스트레이션 (Qt 비의존)
|
|
events.py TranslationLine, EngineStatus
|
|
|
|
ui/
|
|
theme.py 디자인 토큰 + QSS
|
|
overlay.py 자막 창 + 공용 렌더링 함수
|
|
placement.py 모니터 목록 + 9분할 배치 계산 (Qt 비의존)
|
|
hotkeys.py 전역 단축키 (Windows RegisterHotKey)
|
|
main_window.py 사이드바 + 페이지 스택
|
|
pages/ 홈 / 모델 / 자막 / 용어집 / 설정
|
|
widgets/ Card, StatusPill, LevelMeter, AnchorGrid
|
|
|
|
resources/glossaries/ 게임별 기본 용어집 JSON (롤·발로란트·옵치2·마크 등)
|
|
|
|
native/process_loopback/ WASAPI process loopback C++ 보조 프로그램
|
|
scripts/finetune_mt.py LoRA 추가학습
|
|
```
|
|
|
|
## 설계 판단
|
|
|
|
### 캡처를 별도 실행 파일로 뺀 이유
|
|
|
|
WASAPI의 `ActivateAudioInterfaceAsync` + `AUDIOCLIENT_ACTIVATION_TYPE_PROCESS_LOOPBACK`
|
|
은 COM 비동기 콜백을 요구한다. ctypes로 COM vtable을 흉내 내는 것보다 C++ 200줄이
|
|
훨씬 안전하고 디버깅이 쉽다. 파이프로 생 PCM만 주고받으므로 인터페이스도 단순하다.
|
|
|
|
보조 프로그램이 없으면 `capture_capabilities()` 가 이를 알려주고 장치 루프백으로
|
|
자동 폴백한다. 빌드 없이도 프로그램은 동작한다.
|
|
|
|
### 게임이 먼저다
|
|
|
|
이 프로그램은 게임 위에 얹혀 도는 것이 기본 용도라, 자막 품질보다 게임 프레임을
|
|
지키는 쪽이 대체로 더 중요하다. 저부하 모드는 네 방향에서 GPU를 양보한다.
|
|
|
|
1. **연산 정밀도 강등** (`ModelManager.effective_*_spec`) — float16 → int8.
|
|
티어 정의 자체를 건드리지 않고 파생 사양만 바꾸므로, 모드를 끄면 즉시 원복된다.
|
|
2. **VRAM 상한** (`apply_vram_limit`) — 모델을 올리기 *전에* 걸어야 실제로 먹는다.
|
|
게임과 동시에 돌 때 프레임을 죽이는 주범은 연산 시간이 아니라 VRAM 고갈이다.
|
|
게임이 쓸 메모리를 우리가 먹으면 텍스처 스트리밍이 시스템 메모리로 밀려난다.
|
|
3. **추론 후 양보** — 문장 하나를 처리하고 수십 ms 쉰다. 연속 발화 때 GPU를
|
|
독점하지 않기 위해서다.
|
|
4. **유휴 언로드** — 조용한 구간이 길어지면 모델을 통째로 내린다. 그래서
|
|
`_infer_loop` 은 모델 참조를 캐시하지 않고 매번 `models.recognizer()` 를 부른다.
|
|
|
|
### 중간 결과는 번역하지 않는다
|
|
|
|
말하는 도중에도 인식 결과를 흐리게 보여주면 체감 지연이 크게 줄어든다. 하지만
|
|
매번 번역까지 돌리면 GPU가 몇 배로 바빠지고, 문장이 완성되기 전 번역은 어차피
|
|
틀린다. 그래서 **중간 결과는 원문만, 확정 문장만 번역**한다.
|
|
|
|
### 용어집 팩은 계층으로 겹친다
|
|
|
|
여러 게임 팩을 동시에 켜면 같은 단어의 역어가 갈린다 (`knocked`는 FPS 공통에서
|
|
"기절", 배그에서 "눕혔다"). 단순히 켠 순서대로 덮어쓰면 체크박스를 누른 순서가
|
|
결과를 바꾸는데, 사용자는 그 순서를 볼 수도 바꿀 수도 없다.
|
|
|
|
그래서 팩에 `scope`("generic" / "game")를 두고 **범용 → 게임 전용 → 사용자 항목**
|
|
순으로 적용한다. 게임 전용이 항상 범용을 이기므로 결과가 결정적이다.
|
|
게임 팩끼리 갈리는 것은 사람이 판단할 문제라, `find_conflicts()` 로 뽑아 UI에
|
|
그대로 보여준다.
|
|
|
|
데이터 쪽 함정도 하나 있다. 용어 목록은 최장일치를 위해 길이 내림차순으로
|
|
정렬하지만, 이는 **같은 시작 위치**에서만 통한다. "the blue"(조각)가 등록돼
|
|
있으면 "the blue zone"에서 더 앞 위치라는 이유로 "blue zone"을 이겨 "자기장
|
|
자기장"이 된다. `test_each_term_protects_as_a_single_unit` 이 모든 팩을 켠
|
|
상태로 이 겹침을 잡는다.
|
|
|
|
### 배치 계산을 Qt에서 떼어냈다
|
|
|
|
`placement.py` 는 `ScreenInfo` 라는 순수 데이터만 받아 좌표를 계산한다. 덕분에
|
|
모니터가 없는 CI 환경에서도 "두 번째 모니터 하단 중앙", "음수 좌표 모니터",
|
|
"화면보다 큰 자막 창" 같은 경우를 전부 테스트할 수 있다 (`tests/test_placement.py`).
|
|
자막이 화면 밖으로 나가 영영 안 보이는 사고는 여기서 막는다.
|
|
|
|
### UI 코드와 렌더링 코드 분리
|
|
|
|
자막 설정 미리보기와 실제 오버레이가 `paint_subtitle()` 하나를 공유한다.
|
|
QSS로 미리보기를 흉내 내면 `text-shadow` 미지원 같은 이유로 실제와 어긋난다.
|
|
|
|
### 엔진은 Qt를 모른다
|
|
|
|
`core/engine.py` 는 콜백만 받는다. Qt 의존은 `MainWindow` 가 콜백을 Signal로
|
|
다시 던지는 지점에만 있다. 덕분에 GPU도 오디오 장치도 없는 환경에서 파이프라인
|
|
전체를 테스트할 수 있다 (`tests/test_pipeline.py`).
|
|
|
|
## 테스트
|
|
|
|
`pytest` 전체가 GPU·오디오 장치 없이 돈다.
|
|
|
|
- `test_segmenter.py` — 합성 사인파로 VAD 절단 검증
|
|
- `test_pipeline.py` — 가짜 캡처/인식/번역으로 엔진 종단 검증
|
|
- `test_glossary.py` — 최장일치, 단어경계, 왕복 변환
|
|
- `test_config.py` — 스키마 변경 내성
|
|
- `test_ui_smoke.py` — offscreen 렌더링으로 화면 생성 및 자막 픽셀 검증
|