interpreter-v2 2.13.0__tar.gz

interpreter_v2-2.13.0/.gitignore

@@ -0,0 +1,35 @@
+# Binary
+/interpreter
+/interpreter.exe
+
+# Models directory (downloaded on first run)
+models/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+ENV/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*.iml
+
+# OS
+.DS_Store
+Thumbs.db
+.env
+
+# Claude Code
+.claude/
+
+# Debug files
+debug_capture.png

interpreter_v2-2.13.0/.python-version

@@ -0,0 +1 @@
+3.12

interpreter_v2-2.13.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: interpreter-v2
+Version: 2.13.0
+Summary: Offline screen translator for Japanese retro games
+Author: qube
+License-Expression: MIT
+Keywords: games,japanese,ocr,retro,translation
+Requires-Python: <3.13,>=3.11
+Requires-Dist: ctranslate2
+Requires-Dist: dbus-python>=1.3.2; sys_platform == 'linux'
+Requires-Dist: evdev-binary>=1.9.0; sys_platform == 'linux'
+Requires-Dist: meikiocr
+Requires-Dist: mss>=9.0.0
+Requires-Dist: numpy
+Requires-Dist: nvidia-cublas-cu12; sys_platform == 'win32' or sys_platform == 'linux'
+Requires-Dist: nvidia-cudnn-cu12; sys_platform == 'win32' or sys_platform == 'linux'
+Requires-Dist: onnxruntime
+Requires-Dist: opencv-python
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pygetwindow>=0.0.9; sys_platform == 'win32'
+Requires-Dist: pygobject>=3.42.0; sys_platform == 'linux'
+Requires-Dist: pynput>=1.7.0; sys_platform == 'darwin' or sys_platform == 'win32'
+Requires-Dist: pyobjc-framework-cocoa>=12.1; sys_platform == 'darwin'
+Requires-Dist: pyobjc-framework-quartz>=10.0; sys_platform == 'darwin'
+Requires-Dist: pyside6>=6.6.0
+Requires-Dist: python-xlib>=0.33; sys_platform == 'linux'
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests
+Requires-Dist: sentencepiece
+Requires-Dist: structlog>=24.0.0
+Requires-Dist: tqdm
+Requires-Dist: windows-capture-interpreter>=1.5.1; sys_platform == 'win32'
+Description-Content-Type: text/markdown
+
+# Interpreter
+
+Offline screen translator for Japanese retro games. Captures text from any window, performs OCR, translates to English, and displays subtitles in a floating overlay.
+
+![screenshot](screenshot.png)
+
+## Features
+
+- **Fully offline** - No cloud APIs, no internet required after setup
+- **Free** - No API costs or subscriptions
+- **Private** - Text never leaves your machine
+- **Optimized for retro games** - Uses MeikiOCR, trained specifically on Japanese game text
+- **Two overlay modes** - Banner (subtitle bar) or inplace (text over game)
+- **Translation caching** - Fuzzy matching avoids re-translating similar text
+- **Multi-display support** - Overlay appears on the same display as the game
+
+## Requirements
+
+- **Windows 10 version 1903+**, macOS, or Linux (X11/XWayland/Wayland)
+
+### Linux Notes
+
+- **Global hotkeys** require `input` group membership. The installer will show instructions.
+- **Native Wayland capture** requires GStreamer PipeWire plugin. The installer will attempt to install it automatically.
+- **Inplace overlay** on Wayland only works with fullscreen windows (Wayland's security model prevents knowing window positions).
+
+## Installation
+
+### One-liner Install
+
+**macOS/Linux:**
+```bash
+curl -LsSf https://raw.githubusercontent.com/bquenin/interpreter/main/install.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+powershell -c "irm https://raw.githubusercontent.com/bquenin/interpreter/main/install.ps1 | iex"
+```
+
+Then run with `interpreter-v2`.
+
+## Upgrading
+
+To update to the latest version, run the installer again (see Installation above).
+
+## Usage
+
+```bash
+interpreter-v2
+```
+
+This opens the GUI where you can select a window to capture and configure all settings.
+
+## Overlay Modes
+
+### Banner Mode (default)
+A subtitle bar at the bottom of the screen displaying translated text. Draggable, opaque background, centered text.
+
+### Inplace Mode
+Transparent overlay positioned over the game window. Translated text appears directly over the original Japanese text at OCR-detected positions. Click-through so you can interact with the game.
+
+## How It Works
+
+1. **Screen Capture** - Captures the target window at the configured refresh rate
+2. **OCR** - [MeikiOCR](https://github.com/rtr46/meikiocr) extracts Japanese text (optimized for pixel fonts)
+3. **Translation** - [Sugoi V4](https://huggingface.co/entai2965/sugoi-v4-ja-en-ctranslate2) translates Japanese to English
+4. **Display** - Shows translated text in the selected overlay mode
+
+## Troubleshooting
+
+### Poor OCR accuracy
+Try adjusting the OCR confidence slider in the GUI. Lower values include more text (but may include garbage), higher values are stricter.
+
+### Slow performance
+First run downloads models (~1.5GB). Subsequent runs use cached models from `~/.cache/huggingface/`.

interpreter_v2-2.13.0/README.md

@@ -0,0 +1,76 @@
+# Interpreter
+
+Offline screen translator for Japanese retro games. Captures text from any window, performs OCR, translates to English, and displays subtitles in a floating overlay.
+
+![screenshot](screenshot.png)
+
+## Features
+
+- **Fully offline** - No cloud APIs, no internet required after setup
+- **Free** - No API costs or subscriptions
+- **Private** - Text never leaves your machine
+- **Optimized for retro games** - Uses MeikiOCR, trained specifically on Japanese game text
+- **Two overlay modes** - Banner (subtitle bar) or inplace (text over game)
+- **Translation caching** - Fuzzy matching avoids re-translating similar text
+- **Multi-display support** - Overlay appears on the same display as the game
+
+## Requirements
+
+- **Windows 10 version 1903+**, macOS, or Linux (X11/XWayland/Wayland)
+
+### Linux Notes
+
+- **Global hotkeys** require `input` group membership. The installer will show instructions.
+- **Native Wayland capture** requires GStreamer PipeWire plugin. The installer will attempt to install it automatically.
+- **Inplace overlay** on Wayland only works with fullscreen windows (Wayland's security model prevents knowing window positions).
+
+## Installation
+
+### One-liner Install
+
+**macOS/Linux:**
+```bash
+curl -LsSf https://raw.githubusercontent.com/bquenin/interpreter/main/install.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+powershell -c "irm https://raw.githubusercontent.com/bquenin/interpreter/main/install.ps1 | iex"
+```
+
+Then run with `interpreter-v2`.
+
+## Upgrading
+
+To update to the latest version, run the installer again (see Installation above).
+
+## Usage
+
+```bash
+interpreter-v2
+```
+
+This opens the GUI where you can select a window to capture and configure all settings.
+
+## Overlay Modes
+
+### Banner Mode (default)
+A subtitle bar at the bottom of the screen displaying translated text. Draggable, opaque background, centered text.
+
+### Inplace Mode
+Transparent overlay positioned over the game window. Translated text appears directly over the original Japanese text at OCR-detected positions. Click-through so you can interact with the game.
+
+## How It Works
+
+1. **Screen Capture** - Captures the target window at the configured refresh rate
+2. **OCR** - [MeikiOCR](https://github.com/rtr46/meikiocr) extracts Japanese text (optimized for pixel fonts)
+3. **Translation** - [Sugoi V4](https://huggingface.co/entai2965/sugoi-v4-ja-en-ctranslate2) translates Japanese to English
+4. **Display** - Shows translated text in the selected overlay mode
+
+## Troubleshooting
+
+### Poor OCR accuracy
+Try adjusting the OCR confidence slider in the GUI. Lower values include more text (but may include garbage), higher values are stricter.
+
+### Slow performance
+First run downloads models (~1.5GB). Subsequent runs use cached models from `~/.cache/huggingface/`.

interpreter_v2-2.13.0/install.ps1

@@ -0,0 +1,71 @@
+# install.ps1 - One-liner installer for interpreter-v2
+# Usage: powershell -c "irm https://raw.githubusercontent.com/bquenin/interpreter/main/install.ps1 | iex"
+
+$ErrorActionPreference = 'Stop'
+
+Write-Host ""
+Write-Host "=== interpreter-v2 Installer ===" -ForegroundColor Cyan
+Write-Host "Offline screen translator for Japanese retro games"
+Write-Host ""
+
+# Check if uv is installed
+$uvPath = Get-Command uv -ErrorAction SilentlyContinue
+if (-not $uvPath) {
+    Write-Host "[1/2] Installing uv package manager..." -ForegroundColor Yellow
+    Invoke-RestMethod https://astral.sh/uv/install.ps1 | Invoke-Expression
+
+    # Refresh PATH to find uv
+    $env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path", "User")
+
+    # Verify uv is now available
+    $uvPath = Get-Command uv -ErrorAction SilentlyContinue
+    if (-not $uvPath) {
+        Write-Host "Error: uv installation failed. Please restart your terminal and try again." -ForegroundColor Red
+        exit 1
+    }
+    Write-Host "uv installed successfully!" -ForegroundColor Green
+} else {
+    Write-Host "[1/2] uv is already installed" -ForegroundColor Green
+}
+
+# Install or upgrade interpreter-v2
+Write-Host "[2/3] Installing interpreter-v2 from PyPI..." -ForegroundColor Yellow
+Write-Host "     (this may take a minute on first install)" -ForegroundColor Gray
+# Use Python 3.12 explicitly - onnxruntime doesn't have wheels for 3.14 yet
+# Temporarily allow errors so uv's progress output (on stderr) doesn't stop the script
+$ErrorActionPreference = 'Continue'
+uv tool install --upgrade --python 3.12 interpreter-v2
+$installExitCode = $LASTEXITCODE
+$ErrorActionPreference = 'Stop'
+if ($installExitCode -ne 0) {
+    Write-Host ""
+    Write-Host "Installation failed!" -ForegroundColor Red
+    Write-Host "This may be due to missing dependencies. Try:" -ForegroundColor Yellow
+    Write-Host "  uv python install 3.12"
+    Write-Host "  Then run this installer again."
+    exit 1
+}
+$ErrorActionPreference = 'SilentlyContinue'
+uv tool update-shell | Out-Null
+$ErrorActionPreference = 'Stop'
+
+# Pre-compile bytecode and warm up OS caches
+Write-Host "[3/3] Optimizing for fast startup..." -ForegroundColor Yellow
+$toolDir = "$env:LOCALAPPDATA\uv\tools\interpreter-v2"
+if (Test-Path $toolDir) {
+    & "$toolDir\Scripts\python.exe" -m compileall -q "$toolDir\Lib" 2>$null
+    # Warm up caches (Windows Defender, etc.) by running once
+    & interpreter-v2 --list-windows 2>$null | Out-Null
+}
+
+Write-Host ""
+Write-Host "========================================" -ForegroundColor Green
+Write-Host "  Installation complete!" -ForegroundColor Green
+Write-Host "========================================" -ForegroundColor Green
+Write-Host ""
+Write-Host "To start, run:" -ForegroundColor White
+Write-Host ""
+Write-Host "  interpreter-v2" -ForegroundColor Cyan
+Write-Host ""
+Write-Host "You may need to restart your terminal first."
+Write-Host ""

interpreter_v2-2.13.0/install.sh

@@ -0,0 +1,150 @@
+#!/bin/bash
+# install.sh - One-liner installer for interpreter-v2
+# Usage: curl -LsSf https://raw.githubusercontent.com/bquenin/interpreter/main/install.sh | bash
+
+set -e
+
+# Colors
+CYAN='\033[0;36m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+GRAY='\033[0;90m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+# Determine total steps (Linux has extra steps)
+if [[ "$(uname)" == "Linux" ]]; then
+    TOTAL_STEPS=5
+else
+    TOTAL_STEPS=3
+fi
+
+echo ""
+echo -e "${CYAN}=== interpreter-v2 Installer ===${NC}"
+echo "Offline screen translator for Japanese retro games"
+echo ""
+
+# Check if uv is installed
+if ! command -v uv &> /dev/null; then
+    echo -e "${YELLOW}[1/${TOTAL_STEPS}] Installing uv package manager...${NC}"
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+
+    # Add uv to PATH for this session
+    export PATH="$HOME/.local/bin:$PATH"
+
+    # Verify uv is now available
+    if ! command -v uv &> /dev/null; then
+        echo -e "${RED}Error: uv installation failed. Please restart your terminal and try again.${NC}"
+        exit 1
+    fi
+    echo -e "${GREEN}uv installed successfully!${NC}"
+else
+    echo -e "${GREEN}[1/${TOTAL_STEPS}] uv is already installed${NC}"
+fi
+
+# Install or upgrade interpreter-v2
+echo -e "${YELLOW}[2/${TOTAL_STEPS}] Installing interpreter-v2 from PyPI...${NC}"
+echo -e "${GRAY}     (this may take a minute on first install)${NC}"
+# Use Python 3.12 - uv-managed Python includes tkinter, system Python 3.13+ often doesn't
+if ! uv tool install --upgrade --python 3.12 interpreter-v2 2>&1; then
+    echo ""
+    echo -e "${RED}Installation failed!${NC}"
+    echo -e "${YELLOW}This may be due to missing dependencies. Try:${NC}"
+    echo -e "  uv python install 3.12"
+    echo -e "  Then run this installer again."
+    exit 1
+fi
+uv tool update-shell > /dev/null 2>&1 || true
+
+# Pre-compile bytecode and warm up OS caches
+echo -e "${YELLOW}[3/${TOTAL_STEPS}] Optimizing for fast startup...${NC}"
+TOOL_DIR="$HOME/.local/share/uv/tools/interpreter-v2"
+if [ -d "$TOOL_DIR" ]; then
+    # Compile bytecode (exclude .tmpl.py template files that aren't valid Python)
+    "$TOOL_DIR/bin/python" -m compileall -q -x '\.tmpl\.py$' "$TOOL_DIR/lib" 2>/dev/null || true
+    # Warm up OS caches by running once
+    interpreter-v2 --list-windows > /dev/null 2>&1 || true
+fi
+
+# Install Wayland dependencies (Linux only)
+if [[ "$(uname)" == "Linux" ]]; then
+    echo -e "${YELLOW}[4/${TOTAL_STEPS}] Checking Wayland capture dependencies...${NC}"
+
+    # Skip if not running on Wayland
+    if [ -z "$WAYLAND_DISPLAY" ]; then
+        echo -e "${GRAY}     Not running on Wayland, skipping${NC}"
+    # Skip if GStreamer PipeWire plugin already installed
+    elif gst-inspect-1.0 pipewiresrc > /dev/null 2>&1; then
+        echo -e "${GREEN}     GStreamer PipeWire plugin already installed${NC}"
+    # Need to install - detect package manager
+    elif command -v apt-get &> /dev/null; then
+        echo -e "${GRAY}     Installing gstreamer1.0-pipewire...${NC}"
+        sudo apt-get install -y gstreamer1.0-pipewire gir1.2-gstreamer-1.0 2>/dev/null || \
+            echo -e "${YELLOW}     Could not install automatically. Run: sudo apt-get install gstreamer1.0-pipewire gir1.2-gstreamer-1.0${NC}"
+    elif command -v dnf &> /dev/null; then
+        echo -e "${GRAY}     Installing gstreamer1-plugin-pipewire...${NC}"
+        sudo dnf install -y gstreamer1-plugin-pipewire 2>/dev/null || \
+            echo -e "${YELLOW}     Could not install automatically. Run: sudo dnf install gstreamer1-plugin-pipewire${NC}"
+    elif command -v pacman &> /dev/null; then
+        echo -e "${GRAY}     Installing gst-plugin-pipewire...${NC}"
+        sudo pacman -S --noconfirm gst-plugin-pipewire 2>/dev/null || \
+            echo -e "${YELLOW}     Could not install automatically. Run: sudo pacman -S gst-plugin-pipewire${NC}"
+    else
+        echo -e "${YELLOW}     Please install GStreamer PipeWire plugin for native Wayland capture${NC}"
+    fi
+fi
+
+# Install desktop entry and icon (Linux only)
+if [[ "$(uname)" == "Linux" ]]; then
+    echo -e "${YELLOW}[5/${TOTAL_STEPS}] Installing desktop entry...${NC}"
+
+    # Find the installed icon
+    ICON_SRC=$(find "$TOOL_DIR/lib" -name "icon.png" -path "*/resources/icons/*" 2>/dev/null | head -1)
+
+    if [ -n "$ICON_SRC" ]; then
+        # Install icon
+        mkdir -p "$HOME/.local/share/icons/hicolor/256x256/apps"
+        cp "$ICON_SRC" "$HOME/.local/share/icons/hicolor/256x256/apps/interpreter-v2.png"
+
+        # Install desktop entry
+        mkdir -p "$HOME/.local/share/applications"
+        cat > "$HOME/.local/share/applications/interpreter-v2.desktop" << 'EOF'
+[Desktop Entry]
+Name=Interpreter
+Comment=Offline screen translator for Japanese games
+Exec=interpreter-v2
+Icon=interpreter-v2
+Type=Application
+Categories=Utility;Translation;
+StartupWMClass=interpreter-v2
+EOF
+
+        # Update caches
+        gtk-update-icon-cache -f "$HOME/.local/share/icons/hicolor" 2>/dev/null || true
+        update-desktop-database "$HOME/.local/share/applications" 2>/dev/null || true
+
+        echo -e "${GREEN}Desktop entry installed${NC}"
+    else
+        echo -e "${GRAY}Skipping desktop entry (icon not found)${NC}"
+    fi
+fi
+
+echo ""
+echo -e "${GREEN}========================================${NC}"
+echo -e "${GREEN}  Installation complete!${NC}"
+echo -e "${GREEN}========================================${NC}"
+echo ""
+echo "To start, run:"
+echo ""
+echo -e "  ${CYAN}interpreter-v2${NC}"
+echo ""
+if [[ "$(uname)" == "Linux" ]]; then
+    echo -e "${YELLOW}Hotkeys:${NC} To use global hotkeys, add yourself to the input group:"
+    echo ""
+    echo -e "  ${CYAN}sudo usermod -aG input \$USER${NC}"
+    echo ""
+    echo "Then log out and back in."
+    echo ""
+fi
+echo "You may need to restart your terminal first."
+echo ""

interpreter_v2-2.13.0/interpreter-v2.desktop

@@ -0,0 +1,8 @@
+[Desktop Entry]
+Name=Interpreter
+Comment=Offline screen translator for Japanese games
+Exec=interpreter-v2
+Icon=interpreter-v2
+Type=Application
+Categories=Utility;Translation;
+StartupWMClass=interpreter-v2

interpreter_v2-2.13.0/pyproject.toml

@@ -0,0 +1,98 @@
+[project]
+name = "interpreter-v2"
+version = "2.13.0"
+description = "Offline screen translator for Japanese retro games"
+readme = "README.md"
+requires-python = ">=3.11,<3.13"
+license = "MIT"
+authors = [
+    { name = "qube" }
+]
+keywords = ["ocr", "translation", "japanese", "games", "retro"]
+
+dependencies = [
+    # OCR
+    "meikiocr",
+    "onnxruntime",
+    # Translation (Sugoi V4)
+    "ctranslate2",
+    "sentencepiece",
+    # Image processing
+    "Pillow>=10.0.0",
+    "numpy",
+    "opencv-python",
+    # Screen capture
+    "mss>=9.0.0",
+    # Configuration
+    "PyYAML>=6.0",
+    # Model download
+    "requests",
+    "tqdm",
+    # Logging
+    "structlog>=24.0.0",
+    # macOS only - window capture
+    "pyobjc-framework-Quartz>=10.0; sys_platform == 'darwin'",
+    # Windows only - window capture
+    "pygetwindow>=0.0.9; sys_platform == 'win32'",
+    # Fork with HWND support for reliable capture with dynamic window titles
+    "windows-capture-interpreter>=1.5.1; sys_platform == 'win32'",
+    # Linux only - window capture (X11)
+    "python-xlib>=0.33; sys_platform == 'linux'",
+    # Linux only - window capture (Wayland via PipeWire portal)
+    "dbus-python>=1.3.2; sys_platform == 'linux'",
+    "PyGObject>=3.42.0; sys_platform == 'linux'",
+    # GPU acceleration (CUDA 12) - Windows and Linux
+    "nvidia-cublas-cu12; sys_platform == 'win32' or sys_platform == 'linux'",
+    "nvidia-cudnn-cu12; sys_platform == 'win32' or sys_platform == 'linux'",
+    # GUI
+    "PySide6>=6.6.0",
+    # Global hotkeys (macOS/Windows use pynput, Linux uses evdev directly)
+    "pynput>=1.7.0; sys_platform == 'darwin' or sys_platform == 'win32'",
+    "pyobjc-framework-cocoa>=12.1; sys_platform == 'darwin'",
+    # Linux only - global hotkeys (evdev-binary provides pre-built wheels, no kernel headers needed)
+    "evdev-binary>=1.9.0; sys_platform == 'linux'",
+]
+
+[project.scripts]
+interpreter-v2 = "interpreter:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/interpreter"]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.14.10",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+src = ["src"]
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "F",      # pyflakes
+    "W",      # pycodestyle warnings
+    "I",      # isort
+    "UP",     # pyupgrade
+    "B",      # flake8-bugbear
+    "SIM",    # flake8-simplify
+    "RUF",    # ruff-specific rules
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+    "RUF001", # ambiguous unicode (intentional Japanese punctuation)
+    "RUF012", # mutable class attributes (ctypes structures)
+    "SIM102", # nested if statements (sometimes clearer)
+    "SIM105", # contextlib.suppress (try/except/pass is clearer)
+    "SIM108", # ternary operator (multi-line if/else is clearer)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["interpreter"]
+

interpreter_v2-2.13.0/src/interpreter/__init__.py

@@ -0,0 +1,20 @@
+"""Interpreter - Offline screen translator for Japanese retro games.
+
+This application captures text from a target window, performs OCR using
+MeikiOCR, translates using Sugoi V4, and displays subtitles in a
+transparent overlay.
+"""
+
+from importlib.metadata import version
+
+__version__ = version("interpreter-v2")
+
+
+def main():
+    """Entry point for the application."""
+    from .gui import run
+
+    return run()
+
+
+__all__ = ["__version__", "main"]

interpreter_v2-2.13.0/src/interpreter/__main__.py

@@ -0,0 +1,11 @@
+"""Main entry point for Interpreter.
+
+This module is executed when running:
+- python -m interpreter
+- interpreter-v2 (via pyproject.toml entry point)
+"""
+
+from .gui import run
+
+if __name__ == "__main__":
+    run()