live-app-translator/docs/ARCHITECTURE.md

구조

데이터 흐름

[캡처 스레드]           [분할 스레드]              [추론 스레드]          [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 이 모든 팩을 켠 상태로 이 겹침을 잡는다.

용어집은 실제 모델로 검증해야 한다

이 기능은 단위 테스트만으로는 검증되지 않는다. "번역 모델이 자리표시자를 그대로 통과시킨다"는 전제 자체가 틀릴 수 있기 때문이다. 실제 NLLB 를 돌려 보고 나서야 드러난 것들:

1. 자리표시자 형식. 처음 쓰던 ⟦0⟧ 는 NLLB 가 괄호를 통째로 날려 0 만 남겼다(생존률 0/3). 후보 8종을 실측해 #0# 로 바꿨다(3/3). 그전까지 용어가 자막에서 그냥 사라지고 있었다.
2. 소실 대비. 모델이 문장 일부를 통째로 누락하면 그 안의 자리표시자도 사라진다. 그대로 복원하면 용어가 증발하는데 이건 용어집을 안 쓴 것보다 나쁘다. 그래서 하나라도 사라지면 보호 없이 한 번 더 번역한다.
3. 서술어는 문장 전체일 때만. "need ammo" 를 문장 한가운데서 치환하면 모델이 문법을 세울 근거를 잃어 "탄 필요해와 구급상자" 가 된다. 명사만 바꾸면 "탄약과 구급상자가 필요합니다" 로 제대로 나온다. 그래서 절·서술어 항목 56개는 whole_only 로 두어 그 말만 단독으로 나왔을 때만 적용한다.
4. 조사 어긋남. 역어의 받침이 자리표시자와 다르면 "자기장를" 이 남는다. 받침은 한글 코드에서 바로 읽히므로 fix_particles() 로 정확히 고친다.

배치 계산을 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 렌더링으로 화면 생성 및 자막 픽셀 검증