Add realtime JP-KO translator project

windows-jp-ko-translator-transfer-20260504/.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+dist-electron/
+vendor/
+release/
+artifacts/
+.tmp*/
+*.zip

windows-jp-ko-translator-transfer-20260504/JP-KO Translator.command

@@ -0,0 +1,8 @@
+#!/bin/zsh
+set -euo pipefail
+cd "/Users/mingu/.openclaw/workspace-codingbot/windows-jp-ko-translator"
+if [ ! -d node_modules ]; then
+  echo "Installing desktop dependencies..."
+  /usr/bin/env npm install
+fi
+/usr/bin/env npm start

windows-jp-ko-translator-transfer-20260504/README.md

@@ -0,0 +1,122 @@
+# JP-KO Translator
+
+Electron + React + TypeScript 기반의 일본어 → 한국어 데스크톱 번역기입니다.
+
+이번 정리에서 실제로 반영한 핵심은 아래 5가지입니다.
+
+- mac Apple Silicon 경로에 `distil-large-v3(faster-whisper/ct2)` 기반 로컬 STT 백엔드를 추가하고, 모델 + Python 런타임을 앱 리소스로 묶을 수 있게 정리
+- Windows 배포물에 `ffmpeg.exe + whisper.cpp 실행 파일 + ggml-base.bin 모델`을 함께 넣어 별도 STT 설치 없이 바로 실행되게 정리
+- 실사용 기본 조합을 `실사용 권장 + 자동 선택`으로 정리
+- Provider 카드를 누르면 실제 입력/저장이 되는 설정 모달과 연결 테스트가 뜨도록 변경
+- Codex auth 의존을 기본값에서 빼고, API 키 기반 provider가 있으면 자동으로 우선 선택되게 변경
+
+## 실행 방법
+
+### macOS
+
+- `JP-KO Translator.command`
+
+mac Apple Silicon 배포에서는 아래 준비 스크립트로 STT 런타임과 모델을 같이 넣을 수 있습니다.
+
+```bash
+npm run prepare:stt:mac
+```
+
+이 스크립트는 아래를 준비합니다.
+
+- `vendor/python/darwin/arm64` : faster-whisper 실행용 Python 런타임
+- `vendor/models/darwin/arm64/distil-large-v3-ct2` : distil-large-v3 모델
+
+### Windows exe bundle
+
+압축 해제 후 아래 파일을 실행합니다.
+
+- `JP-KO Translator.exe`
+
+이 번들은 Windows에서 아래 STT 도구를 같이 포함합니다.
+
+- `ffmpeg.exe`
+- `whisper-cli.exe`
+- `ggml-base.bin`
+
+즉, Windows 사용자는 ffmpeg나 whisper를 따로 설치할 필요가 없습니다.
+
+## 앱 안에서 바뀐 점
+
+### 1) STT
+
+- mac Apple Silicon은 `ffmpeg + bundled Python + faster-whisper(distil-large-v3-ct2)`를 우선 사용합니다.
+- mac 번들 안에 distil-large-v3 모델 디렉터리와 Python 런타임을 같이 넣을 수 있습니다.
+- mac에서 위 리소스를 찾지 못하면 기존 `whisper/whisper.cpp` 탐색 경로로 자동 fallback 합니다.
+- Windows 기본 배포물은 `WASAPI loopback + ffmpeg + whisper.cpp` 조합으로 동작합니다.
+- 오디오 캡처와 전사 파일이 앱 번들에 같이 들어갑니다.
+- 압축만 제대로 풀면 STT 도구를 따로 찾을 필요가 없습니다.
+- 실제 흐름은 `Windows 기본 출력 장치 재생 -> WASAPI loopback 캡처 -> whisper.cpp 전사 -> 번역 provider` 입니다.
+- 기본값에서는 현재 Windows 기본 출력 장치를 자동으로 따라가며, Stereo Mix/VB-Cable 같은 가상 장치를 따로 잡을 필요가 없습니다.
+
+### 2) UI 문구
+
+메인/설정 흐름에서 아래 문구를 걷어냈습니다.
+
+- `로컬 데모`
+- `설정 필요`
+
+대신 사용자는 아래처럼 보게 됩니다.
+
+- `기본 확인`
+- `입력 필요`
+- `로그인 필요`
+
+### 3) Provider 설정 UX
+
+주의: `기본 확인`은 실오디오/STT 흐름 점검용입니다. 실제 번역을 쓰려면 아래 provider 중 하나를 설정해야 합니다.
+
+가장 단순한 실사용 경로는 아래입니다.
+
+1. 설정 화면에서 `실행 모드 = 실사용 권장`
+2. `번역 경로 = 자동 선택`
+3. GPT API / Gemini / DeepL 중 하나의 키만 저장
+4. 설정 화면의 `첫 실행 기준` 카드에서 4개 체크가 채워졌는지 바로 확인
+5. `연결 테스트` 또는 `자동 선택 테스트`로 바로 확인
+
+자동 선택 우선순위는 아래 순서입니다.
+
+- `GPT API`
+- `Gemini`
+- `DeepL`
+- `Codex auth`
+
+즉, Codex auth는 기본 경로가 아니라 고급/대체 경로입니다.
+
+설정 화면에서 provider 카드를 누르면 실제 모달이 열립니다.
+
+- `자동 선택`: 현재 저장된 키 기준 자동 선택 테스트
+- `Codex auth`: Codex CLI 설치 + 로그인 페이지 열기 + auth 파일 경로 입력 + 모델 입력 + 연결 테스트
+- `GPT API`: API 키 / Base URL / 모델 입력 + 연결 테스트
+- `Gemini`: API 키 / Base URL / 모델 입력 + 연결 테스트
+- `DeepL`: API 키 / Base URL 입력 + 연결 테스트
+
+저장하면 앱 전용 설정 파일에 보관되고, 다음 실행부터 바로 반영됩니다.
+
+## QA / Release
+
+```bash
+npm run prepare:stt:mac
+npm run typecheck
+npm run build
+npm run verify:runtime:report
+npm run release:windows
+```
+
+Windows 산출물은 `release/` 아래에 생성됩니다.
+런타임 smoke 결과는 `artifacts/runtime-verify-latest.json`에 남길 수 있습니다.
+
+## 현재 남는 리스크
+
+- mac 실오디오 E2E는 입력 장치, 마이크 권한, 가상 오디오 라우팅이 준비되지 않으면 캡처 단계에서 막힙니다.
+- distil-large-v3 런타임은 실제로 묶을 수 있게 바꿨지만, 리소스 크기가 커서 mac 배포물 용량이 꽤 증가합니다.
+- faster-whisper 경로는 CPU int8 기준으로 붙여 두었고, Apple Silicon 최적화 전용 경로는 아직 아닙니다.
+- Windows STT는 번들형으로 바꿨지만, 실제 인식 품질은 `ggml-base.bin` 모델 기준입니다. 더 높은 품질이 필요하면 더 큰 모델로 교체해야 합니다.
+- Codex auth는 브라우저 로그인 진입만 앱에서 제공합니다. 실제 사용에는 해당 PC에 Codex CLI가 설치되어 있고 로그인 세션(auth.json)이 모두 준비돼 있어야 합니다.
+- `기본 확인`은 실제 번역 엔진이 아니라 캡처/STT 점검용 경로라서, 원격 provider를 설정하지 않으면 실사용 번역기로 쓰기 어렵습니다.
+- macOS는 여전히 시스템 오디오 라우팅 환경에 따라 입력 장치 구성이 달라질 수 있습니다.

windows-jp-ko-translator-transfer-20260504/docs/PRACTICAL_ROLLOUT_PLAN.md

@@ -0,0 +1,61 @@
+# Practical Rollout Plan
+
+## 실사용 기준
+
+아래 4개를 만족하면 `조건부 가능`이 아니라 `실사용 가능`로 봅니다.
+
+1. 사용자가 Windows 압축본을 풀고 exe를 실행할 수 있다.
+2. 일본어 오디오가 Windows 기본 출력 장치로 재생될 때 STT가 실제로 잡힌다.
+3. 번역 provider를 한 번만 넣으면 다음 실행부터 별도 설명 없이 실제 한국어 번역이 바로 나온다.
+4. 번역이 안 될 때 사용자는 `어디가 비었는지`를 앱 안에서 바로 알 수 있다.
+
+## 남은 갭
+
+### 필수
+
+- 기본 provider 전략이 `수동 선택` 중심이라 첫 설정 판단 비용이 높음
+- 저장 후 실제 번역 연결 확인 경로가 약함
+- Codex auth가 보여서 기본 경로처럼 오해될 수 있음
+- Windows 오디오 입력선 흐름이 사용 설명보다 앱 안 UX에서 덜 분명함
+
+### 후순위
+
+- 더 큰 whisper 모델 선택 UX
+- 번역 라인 버퍼/지연 튜닝
+- 설치형 인스톨러/서명 배포
+- 실제 오디오 샘플 기반 회귀 QA 자동화
+
+## 단계 1 / 2 / 3
+
+### 단계 1 — 바로 번역이 붙는 기본선 만들기
+
+- 기본 권장 조합을 `실사용 권장 + 자동 선택`으로 고정
+- 자동 선택 우선순위를 `GPT API → Gemini → DeepL → Codex auth`로 정리
+- Codex는 기본값이 아니라 대체/고급 경로로 위치 조정
+- 저장 후 provider 연결 테스트를 앱에서 바로 실행 가능하게 추가
+
+### 단계 2 — Windows 실사용 흐름 명료화
+
+- 앱 안에 `기본 출력 장치 재생 → WASAPI 캡처 → whisper 전사 → 번역 provider` 흐름을 노출
+- 오류 문구를 `압축 다시 풀기`, `API 키 필요`, `로그인 필요`처럼 행동 가능한 메시지로 유지
+- QA에서 실제 Windows 출력 장치 기준 캡처 확인
+
+### 단계 3 — 배포 마감선
+
+- Windows 실제 기기에서 exe bundle smoke test
+- API 키 1개만 넣고 즉시 번역되는지 검증
+- release note/README를 `무설정 데모` 중심이 아니라 `최소 설정 실사용` 중심으로 재작성
+
+## 지금 바로 반영한 것
+
+- `자동 선택` provider 추가
+- 원격 번역 시작 기본값을 `auto`로 변경
+- 자동 선택 우선순위 구현: GPT API → Gemini → DeepL → Codex auth
+- provider별 `연결 테스트`와 `자동 선택 테스트` 추가
+- 설정 화면에 `실사용 권장` 및 Windows 오디오 흐름 설명 추가
+
+## 아직 사용자 도움이 필요한 것
+
+- 실제 Windows PC에서 오디오가 기본 출력으로 재생되는 환경 확인
+- 어떤 기본 provider를 실제 주력으로 쓸지 결정용 키 1개 제공(OpenAI/Gemini/DeepL 중 하나)
+- Codex를 계속 지원할지, 고급 옵션으로만 둘지 제품 방향 확정

windows-jp-ko-translator-transfer-20260504/docs/QA_RELEASE_CHECKLIST.md

@@ -0,0 +1,19 @@
+# JP-KO Translator QA Checklist
+
+## 이번 정리에서 확인한 항목
+
+- 개발자용 문구 `로컬 데모`, `설정 필요` 제거 후 `기본 확인 / 입력 필요 / 로그인 필요`로 정리
+- provider 카드 클릭 시 실제 모달 열림
+- API 키 / Base URL / 모델 저장 가능
+- Codex auth 로그인 진입 버튼 추가
+- `기본 확인`은 실오디오/STT 점검용이고, 실제 번역은 원격 provider 설정이 필요함을 문구로 명시
+- Windows 배포물에 `ffmpeg.exe`, `whisper-cli.exe`, `ggml-base.bin` 포함
+- `npm run typecheck`
+- `npm run build`
+- `npm run release:windows`
+
+## 현재 남는 리스크
+
+- Windows STT는 번들형으로 바뀌었지만 기본 모델이 `ggml-base.bin`이라 고품질 모델보다 인식 품질이 낮을 수 있음
+- Codex auth는 브라우저 로그인 진입을 제공하지만 실제 사용 여부는 로컬 세션 상태에 의존함
+- macOS는 시스템 오디오 라우팅 환경에 따라 입력 장치 설정이 달라질 수 있음

windows-jp-ko-translator-transfer-20260504/docs/WINDOWS_RELEASE_GUIDE.md

@@ -0,0 +1,67 @@
+# Windows release guide
+
+Windows 기본 배포물은 이제 실행 파일만 있는 껍데기가 아닙니다.
+
+압축을 풀면 아래가 같이 들어 있습니다.
+
+- `JP-KO Translator.exe`
+- `resources/bin/win32/x64/ffmpeg.exe`
+- `resources/bin/win32/x64/whisper-cli.exe`
+- `resources/bin/win32/x64/ggml-base.bin`
+
+즉, Windows 사용자는 ffmpeg / whisper를 따로 설치하지 않아도 됩니다.
+
+## 사용 방법
+
+1. zip을 **완전히** 압축 해제합니다.
+2. `JP-KO Translator.exe`를 실행합니다.
+3. 설정 화면에서 `첫 실행 기준` 카드가 보이는지 확인합니다.
+4. provider 카드를 눌러 키 또는 로그인 정보를 입력합니다.
+5. `API 키 1개 저장`과 `실사용 조합 유지`가 완료로 바뀌는지 봅니다.
+6. 저장 후 `연결 테스트` 또는 `자동 선택 테스트`를 한 번 실행합니다.
+7. 시작합니다.
+
+## Provider 설정 흐름
+
+앱 안에서 직접 설정할 수 있습니다.
+
+- `Codex auth`
+  - Codex CLI 설치
+  - 로그인 페이지 열기
+  - auth 파일 경로 입력
+  - 모델 입력
+- `GPT API`
+  - API 키 / Base URL / 모델 입력
+- `Gemini`
+  - API 키 / Base URL / 모델 입력
+- `DeepL`
+  - API 키 / Base URL 입력
+
+예전처럼 카드에 `설정 필요`만 보이고 끝나지 않습니다.
+
+`기본 확인`은 실오디오/STT 경로만 점검하는 내장 확인 모드입니다. 실제 번역을 사용하려면 GPT API, Gemini, DeepL, Codex auth 중 하나를 설정해야 합니다.
+
+## STT 동작 방식
+
+- 오디오 캡처: `ffmpeg.exe`
+- 음성 인식: `whisper.cpp`
+- 기본 모델: `ggml-base.bin`
+- 입력 소스: Windows WASAPI loopback
+- 기본값은 현재 Windows 기본 출력 장치를 자동으로 따라가므로, Stereo Mix/VB-Cable 같은 가상 장치를 따로 만들 필요가 없습니다.
+
+## smoke 확인용 명령
+
+```bash
+npm run verify:runtime:report
+```
+
+성공/실패와 provider probe, capture 준비 상태, end-to-end 요약은 `artifacts/runtime-verify-latest.json`에 남습니다.
+
+non-Windows 호스트에서 이 명령을 돌릴 때 Windows용 번들 모델만 들어 있는 경우에는, 이제 `Windows에서 직접 실행해 확인` 안내로 분리해 표시합니다. 이 경우는 앱 결함이라기보다 호스트 불일치입니다.
+
+## 현재 남는 제한
+
+- 기본 모델은 `ggml-base.bin`이라 더 큰 모델보다 정확도가 낮을 수 있습니다.
+- Codex auth는 로그인 진입만 앱에서 열어줍니다. 실제 사용에는 로컬 PC에 Codex CLI 설치와 로그인 세션(auth.json)이 모두 필요합니다.
+- `기본 확인`은 실제 번역 엔진이 아니라 캡처/STT 점검용 경로입니다.
+- Apple Silicon macOS에서 Windows용 `portable` 단일 exe 패키징은 여전히 제한이 있어서, 현재 주 산출물은 exe bundle zip입니다.