### Source Install Flow Example

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/architecture/INSTALLATION_STATE_REVIEW.md

This is the typical output message for the source installation flow, indicating where packages were installed and how to activate the environment.

```bash
Packages were installed into the project's .venv.
Activate it before running WhisperJAV:
    .venv\Scripts\activate
```

--------------------------------

### Setup and Installation

Source: https://github.com/meizhong986/whisperjav/blob/main/notebook/WhisperJAV_v0_7b.ipynb

Installs the necessary libraries for WhisperJAV. This process takes approximately two minutes. It also configures logging for the installation process.

```python
#@markdown **Setup and Installation**
#@markdown *Takes roughly two minutes*

import sys, os
from IPython.utils import io
from IPython.display import clear_output
import contextlib

print('Installing necessary libraries.\n *** This will take a couple of minutes *** \n')

# Construct the log file path using audio_folder
log_file_path = os.path.join(audio_folder, "install_log.txt")

# Open the file in append mode ('a')
with open(log_file_path, 'a') as f:
    # If the file is not empty, truncate it
    if os.stat(log_file_path).st_size != 0:
        f.truncate(0)
@contextlib.contextmanager
def suppress_stdout():
    with open(os.devnull, "w") as devnull:
        old_stdout = sys.stdout
        sys.stdout = devnull
        try:
            yield
        finally:
            sys.stdout = old_stdout
```

--------------------------------

### StepExecutor Initialization Example

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/external_review/executor.py.txt

Demonstrates how to initialize the StepExecutor with a log file, maximum retries, and the option to use 'uv'. This setup is useful for managing package installations with detailed logging and retry mechanisms.

```python
from pathlib import Path

# Assuming StepExecutor and InstallationError are defined elsewhere
# from .executor import StepExecutor, InstallationError

# Placeholder for packages definition
packages = [
    # Example package structure
    # type('obj', (object,), {'name': 'package1', 'required': True}),
    # type('obj', (object,), {'name': 'package2', 'required': False}),
]

executor = StepExecutor(
    log_file=Path("install.log"),
    max_retries=3,
    use_uv=True,
)

for package in packages:
    result = executor.install_package(package, cuda_version="cu128")
    if not result.success and package.required:
        raise InstallationError(f"Failed: {package.name}")

```

--------------------------------

### Setup: Install Core Dependencies with Homebrew

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/en/guides/installation_mac_apple_silicon.md

Install essential tools like Python, FFmpeg, PortAudio, and Git using Homebrew.

```bash
brew install python@3.12 ffmpeg portaudio git
```

--------------------------------

### Quick Start Build Commands

Source: https://github.com/meizhong986/whisperjav/blob/main/installer/README.md

Build an installer for the current version by cleaning previous builds and then generating all necessary files.

```bash
cd installer
python build_release.py --clean   # Clean previous build
python build_release.py           # Generate all files
cd generated
build_installer_v{VERSION}.bat    # Build the .exe
```

--------------------------------

### Development Setup and Testing

Source: https://github.com/meizhong986/whisperjav/blob/main/README.md

Clone the repository, install the project in editable mode with development dependencies, and run tests and linters.

```bash
git clone https://github.com/meizhong986/whisperjav.git
cd whisperjav
pip install -e ".[dev]"
python -m pytest tests/
python -m ruff check whisperjav/
```

--------------------------------

### Initialize Installation Log File

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/external_review/install.py.txt

Initializes the installation log file by clearing previous content and writing a header with the start time. This function is crucial for maintaining installation records.

```python
def _init_logging(source_dir: Path):
    """Initialize log file for installation."""
    global _LOG_FILE
    _LOG_FILE = source_dir / "install_log.txt"
    # Clear previous log
    try:
        with open(_LOG_FILE, "w", encoding="utf-8") as f:
            f.write(f"WhisperJAV Installation Log\n")
            f.write(f"Started: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
            f.write("=" * 80 + "\n\n")
    except Exception:
        pass
```

--------------------------------

### Step 2: Setup & Environment Initialization

Source: https://github.com/meizhong986/whisperjav/blob/main/notebook/WhisperJAV_kaggle_parallel_edition.ipynb

Initializes the environment for Step 2, performing pre-flight checks for GPU and internet connectivity, and handling installation differences between Colab and Kaggle. It defines helper functions for section printing, status reporting, and conditional execution, ensuring a robust setup process.

```python
#@title Step 2: Setup & Environment (Run Once) { display-mode: "form" }
#@markdown - **Fails Fast** if GPU or Internet is missing.
#@markdown - **Colab**: Uses `install_colab.sh` (installs into system Python)
#@markdown - **Kaggle**: Direct pip install with pinned versions (numpy 2.x compatible)

import os
import shutil
import subprocess
import sys
import time
import socket
from pathlib import Path

# Fix matplotlib backend conflict
os.environ['MPLBACKEND'] = 'Agg'
os.environ['TORCH_HUB_TRUST_REPO'] = '1'  # Fix #253

def section(title):
    print(f"\n{'---'*14}\n{title}\n{'---'*14}")

def status(msg, ok=True):
    print(f"{ 'OK' if ok else 'FAIL'} {msg}")

def must(condition, msg):
    if not condition:
        raise RuntimeError(f"SETUP FAILED: {msg}")

# ═══════════════════════════════════════════
# 1. PRE-FLIGHT CHECKS (Fail Fast)
# ═══════════════════════════════════════════
section("PRE-FLIGHT CHECKS")

# Get config from Step 1
if "WHISPERJAV_CONFIG" not in globals():
    from IPython.display import display, HTML
    display(HTML('<div style="background:#fee2e2;padding:10px;border-radius:4px;"><b>Run Step 1 First</b></div>'))
    raise RuntimeError("Step 1 required")

cfg = WHISPERJAV_CONFIG
PLATFORM = cfg['platform']
print(f"Platform: {PLATFORM.upper()}")
print(f"Python:   {sys.executable} ({sys.version.split()[0]})")

```

--------------------------------

### Install WhisperJAV Minimally via Script

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/en/guides/installation_linux.md

Use the provided installation script with the '--minimal' flag for a server setup.

```bash
python install.py --minimal
```

--------------------------------

### Generated Installer File Name

Source: https://github.com/meizhong986/whisperjav/blob/main/installer/README.md

Example of the final executable installer file name created after the build process.

```text
WhisperJAV-1.7.6-Windows-x86_64.exe
```

--------------------------------

### Development Setup for WhisperJAV

Source: https://github.com/meizhong986/whisperjav/blob/main/CONTRIBUTING.md

Clone the repository, set up a virtual environment, activate it, and install development dependencies.

```bash
git clone https://github.com/meizhong986/whisperjav.git
cd whisperjav
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
python install.py --dev
```

--------------------------------

### Setup Whisper and Dependencies

Source: https://github.com/meizhong986/whisperjav/blob/main/notebook/WhisperWithVAD_mr.ipynb

Installs necessary libraries including Whisper, DeepL, SRT, FFmpeg, and specific versions of PyTorch and Triton. This step may take a few minutes.

```bash
#@markdown **Setup Whisper  -grab yourself a coffee, this may take about 3 minutes**
%%capture
!apt-get install sox libsox-fmt-mp3 libsndfile1 ffmpeg
!pip install deepl srt ffmpeg-python spleeter
!pip uninstall -y openai-whisper openai-whisper-20230918  torch torchvision torchaudio torchtext torchdata
!pip install cohere openai
!pip install --no-cache-dir  torch==1.12.1 torchvision torchaudio torchtext torchdata triton==2.0.0 tiktoken==0.3.3
!pip install --no-cache-dir  --no-deps --force-reinstall git+https://github.com/openai/whisper.git

print("Done")
```

--------------------------------

### Create and Activate New Virtual Environment

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/en/guides/installation_windows_python.md

Use this sequence to start fresh in a new virtual environment if you encounter dependency conflicts during installation.

```cmd
REM Start fresh in a new venv
deactivate
rmdir /s /q whisperjav-env
python -m venv whisperjav-env
whisperjav-env\Scripts\activate
python install.py
```

--------------------------------

### Setup Whisper and Dependencies

Source: https://github.com/meizhong986/whisperjav/blob/main/notebook/WhisperWithVAD_pro_20240306.ipynb

Installs essential libraries including ffmpeg, sox, deepl, srt, ffmpeg-python, spleeter, PyTorch, and the Whisper library from GitHub. This step may take a couple of minutes.

```bash
%%capture
!sudo apt update && sudo apt install ffmpeg
!apt-get install sox libsox-fmt-mp3 libsndfile1
!pip install deepl srt ffmpeg-python
!pip install spleeter
!pip install torch torchvision torchaudio torchtext torchdata
!pip install git+https://github.com/openai/whisper.git

print("Done")
```

--------------------------------

### Ollama Setup UI with Re-check Functionality

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/research/OLLAMA_INTEGRATION_RESEARCH.md

Presents a UI pattern for guiding users through external installations like Ollama. Includes download and re-check buttons for a smooth setup process.

```text
┌─────────────────────────────────────────────────┐
│  Translation Engine Setup                        │
│                                                  │
│  Ollama is not installed on this system.         │
│                                                  │
│  Ollama is a free, open-source tool that runs    │
│  AI models locally on your computer.             │
│                                                  │
│  [Download Ollama]    [Check Again]              │
│                                                  │
│  ▸ What is Ollama?                               │
│  ▸ Troubleshooting                               │
└─────────────────────────────────────────────────┘
```

--------------------------------

### WhisperJAV Installer: Minimal Installation

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/en/guides/installation_linux.md

Runs the WhisperJAV installer for a minimal setup, including only transcription capabilities and excluding other features.

```bash
python install.py --minimal     # Transcription only
```

--------------------------------

### Get Installation Statistics

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/external_review/executor.py.txt

Retrieves the current counts for installed, skipped, and failed items. Useful for reporting and monitoring the installation process.

```python
def get_stats(self) -> dict:
    """
    Get installation statistics.

    Returns:
        Dict with install_count, skip_count, fail_count
    """
    return {
        "install_count": self._install_count,
        "skip_count": self._skip_count,
        "fail_count": self._fail_count,
        "total": self._install_count + self._skip_count + self._fail_count,
    }
```

--------------------------------

### Generate and Build Installer Steps

Source: https://github.com/meizhong986/whisperjav/blob/main/installer/README.md

Steps to clean previous builds, generate new files, and then build the installer executable.

```bash
cd installer
python build_release.py --clean
python build_release.py

cd generated
build_installer_v1.7.6.bat
```

--------------------------------

### Standard Install (Recommended)

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/en/guides/installation_windows_python.md

Use this command for a standard installation that automatically detects and configures GPU support if available.

```cmd
REM Standard install (recommended)
python install.py
```

--------------------------------

### Run WhisperJAV Source Installer

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/en/guides/installation_linux.md

Executes the automated installation script for WhisperJAV, which handles dependency detection, PyTorch installation, and WhisperJAV setup.

```bash
# Step 3: Run the installer
python install.py
```

--------------------------------

### Get Installer Command

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/external_review/executor.py.txt

This snippet represents a placeholder for a method that retrieves the command to be used for installation.

```Python
    def _get_installer_cmd(self) -> List[str]:
        ""

```

--------------------------------

### Install WhisperJAV from Source

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/en/guides/installation_mac_apple_silicon.md

Clone the whisperjav repository and run the installation script. Use `--cpu-only` if you do not intend to use MPS.

```bash
git clone https://github.com/meizhong986/whisperjav.git
cd whisperjav
python install.py --cpu-only
```

--------------------------------

### Setup Execution Environment

Source: https://github.com/meizhong986/whisperjav/blob/main/notebook/WhisperJAV_kaggle_parallel_edition.ipynb

Configures platform-specific paths (Kaggle, Colab, Local) and creates necessary directories for output and temporary files. Exports the output directory path for subsequent steps.

```python
import os
import shutil
import sys
import time
import subprocess
from pathlib import Path
from concurrent.futures import ThreadPoolExecutor, as_completed
from IPython.display import HTML, FileLink, display

def format_pass_error(log: str, tail_chars: int = 1500) -> str:
    """v1.8.14 (#321): show the END of the failed-pass log so users see the
    actual exception/traceback, not a leading HF Hub 'unauthenticated requests'
    warning. If the log is short, show all of it; otherwise show the last
    tail_chars characters with an ellipsis prefix.
    """
    if not log:
        return "    (no log captured)"
    log = log.rstrip()
    if len(log) <= tail_chars:
        excerpt = log
    else:
        excerpt = "...(earlier output truncated)...\n" + log[-tail_chars:]
    # Indent each line for readability
    return "\n".join("      " + line for line in excerpt.splitlines())


# ═══════════════════════════════════════════
# PLATFORM SETUP
# ═══════════════════════════════════════════

if "WHISPERJAV_CONFIG" not in globals():
    raise RuntimeError("Run Step 1 first!")

cfg = WHISPERJAV_CONFIG
PLATFORM = cfg['platform']

# Define Paths based on Platform
if PLATFORM == "kaggle":
    INPUT_DIR = Path("/kaggle/input")
    OUTPUT_DIR = Path("/kaggle/working/output")
    TEMP_DIR = Path("/tmp/whisperjav")
    # Find dataset folder (usually first subdir in input)
    try:
        DATASET_DIR = next(d for d in INPUT_DIR.iterdir() if d.is_dir())
    except StopIteration:
        DATASET_DIR = INPUT_DIR
elif PLATFORM == "colab":
    INPUT_DIR = Path(f"/content/drive/MyDrive/{cfg['folder_name']}")
    OUTPUT_DIR = INPUT_DIR  # Output in same folder
    TEMP_DIR = Path("/content/temp")
    DATASET_DIR = INPUT_DIR
else:
    # Local fallback
    INPUT_DIR = Path("./")
    OUTPUT_DIR = Path("./output")
    TEMP_DIR = Path("./temp")
    DATASET_DIR = INPUT_DIR

# Create dirs
OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
TEMP_DIR.mkdir(parents=True, exist_ok=True)

# Export OUTPUT_DIR for Step 4 to find SRTs
WHISPERJAV_OUTPUT_DIR = OUTPUT_DIR
```

--------------------------------

### Log Final Installation Status and Next Steps

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/external_review/post_install.py.template.txt

Logs the completion of the desktop shortcut creation, installation time, and provides guidance for the user on next steps.

```python
log(f"  ✔ Desktop shortcut: Created")
log(f"  ✔ Installation time: {minutes}m {seconds}s")
log("")
log("Next Steps:")
log("  1. Launch WhisperJAV from the desktop shortcut")
log("  2. On first run, AI models will download (~3GB, 5-10 minutes)")
log("  3. Select your video files and start processing!")
log("")
log(f"Logs saved to: {LOG_FILE}")
log("=" * 80)
log("")
```

--------------------------------

### Setup: Upgrade Pip and Install PyTorch

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/en/guides/installation_mac_apple_silicon.md

Ensure you have the latest version of pip and install PyTorch and Torchaudio, which are required for MPS acceleration.

```bash
pip install --upgrade pip
pip install torch torchaudio
```

--------------------------------

### Troubleshooting: Run from Source

Source: https://github.com/meizhong986/whisperjav/blob/main/whisperjav/webview_gui/QUICK_START.md

If the GUI won't start due to missing assets, try running it directly from the repository root after navigating to the correct directory.

```bash
# Ensure you're in the repository root
cd C:\BIN\git\WhisperJav_V1_Minami_Edition

# Run from source
python -m whisperjav.webview_gui.main
```

--------------------------------

### Print FFmpeg Installation Instructions

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/external_review/install.py.txt

Provides guidance on installing FFmpeg based on the operating system. This is displayed when FFmpeg is not detected.

```python
def _print_ffmpeg_instructions():
    """Print FFmpeg installation instructions."""
    log("         FFmpeg is required for audio/video processing.")
    log("         Install FFmpeg and add it to your PATH before using WhisperJAV.")
    if sys.platform == "linux":
        log("         Linux: sudo apt-get install ffmpeg")
    elif sys.platform == "darwin":
        log("         macOS: brew install ffmpeg")
    else:
        log("         Windows: Download from https://www.gyan.dev/ffmpeg/builds/")
```

--------------------------------

### Silent Installation with Options

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/en/guides/installation_windows_standalone.md

Execute a silent installation, disabling local LLM and PATH modification, using the START /WAIT command for better control.

```cmd
cmd /C START /WAIT WhisperJAV-1.8.9-Windows-x86_64.exe /S /AddToPath=0 /InstallLocalLLM=0
```

--------------------------------

### Install PyTorch with CUDA 12.8 via Conda

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/en/guides/installation_linux.md

Installs PyTorch and Torchaudio with automatic CUDA 12.8 setup using Conda. This method simplifies CUDA management.

```bash
# Step 2: Install PyTorch via conda (handles CUDA automatically)
conda install pytorch torchaudio pytorch-cuda=12.8 -c pytorch -c nvidia -y
```

--------------------------------

### Print Installation Summary

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/external_review/post_install.py.template.txt

Logs a comprehensive installation summary to the console, including the total installation duration in minutes and seconds.

```python
def print_installation_summary(install_start_time: float):
    """Print a comprehensive installation summary"""
    install_duration = int(time.time() - install_start_time)
    minutes = install_duration // 60
    seconds = install_duration % 60

    log("\n\n")
    log("=" * 80)
    log(" " * 20 + "WhisperJAV v{{VERSION}} Installation Complete!")
    log("=" * 80)
    log("")
    log(f"Installation Summary:")
```

--------------------------------

### Get UV Package Installer Version

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/external_review/post_install_v1.8.2rc1.py.txt

Retrieves the version string of the 'uv' package installer if it's available and executable. Returns None if USE_UV is false or an error occurs.

```python
def get_uv_version() -> Optional[str]:
    """Get uv version string if available."""
    if not USE_UV:
        return None
    try:
        result = subprocess.run(
            [UV_EXE, "--version"],
            capture_output=True,
            text=True,
            timeout=5
        )
        if result.returncode == 0:
            return result.stdout.strip()
    except Exception:
        pass
    return None
```

--------------------------------

### Installation Scripts Overview

Source: https://github.com/meizhong986/whisperjav/blob/main/installer/README.md

Details on the installation scripts available for Linux/macOS and Windows users.

```text
| Script | Platform | Description |
|--------|----------|-------------|
| `install_linux.sh` | Linux/macOS | Full installation with venv |
| `install_windows.bat` | Windows | Full installation with venv |

Both scripts:
- Create isolated Python virtual environment
- Install PyTorch with appropriate CUDA version
- Install WhisperJAV from GitHub (latest version)
- Create desktop shortcuts
```

--------------------------------

### Ollama Installation and Status Check Logic

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/research/OLLAMA_INTEGRATION_RESEARCH.md

Illustrates a decision tree for checking Ollama installation, running status, model availability, and VRAM sufficiency. Guides users through missing components.

```text
Is Ollama installed? → Guide install if not
Is Ollama running? → Offer to start if not
Is model available? → Auto-pull with consent
Is VRAM sufficient? → Suggest appropriate model
```

--------------------------------

### Install Qwen-ASR

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/en/architecture/ADR-003-qwen3-asr-integration.md

Install the Qwen-ASR library. Use the [vllm] extra for production environments. FlashAttention 2 is optional.

```bash
# Minimal
pip install -U qwen-asr

# With vLLM (recommended for production)
pip install -U qwen-asr[vllm]

# Optional: FlashAttention 2
pip install -U flash-attn --no-build-isolation
```

--------------------------------

### Get Package Installer Command Prefix

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/external_review/post_install_v1.8.2rc1.py.txt

Determines and returns the command prefix list and name for the package installer. It prioritizes 'uv' if USE_UV is true, otherwise falls back to 'pip'.

```python
def get_package_installer_cmd() -> Tuple[list, str]:
    """
    Get the appropriate package installer command prefix.

    Returns:
        tuple: (command_prefix_list, installer_name)

    uv is preferred (10-30x faster) with pip as fallback.
    """
    python_exe = os.path.join(sys.prefix, 'python.exe')

    if USE_UV:
        # uv pip install --python <path> ensures we install to the right env
        return ([UV_EXE, "pip", "install", "--python", python_exe], "uv")
    else:
        return ([python_exe, "-m", "pip", "install"], "pip")
```

--------------------------------

### Main Installation Workflow Function

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/external_review/post_install.py.template.txt

Orchestrates the entire post-installation process, including logging, preflight checks, dependency installation, and GPU/CUDA detection.

```python
def main() -> int:
    """Main installation workflow"""
    install_start_time = time.time()

    log_section("WhisperJAV v{{VERSION}} Post-Install Started")
    log(f"Installation prefix: {sys.prefix}")
    log(f"Python executable: {sys.executable}")
    log(f"Python version: {sys.version}")
    log_installer_info()  # Log which package installer (uv or pip) will be used

    # === Phase 1: Preflight Checks ===
    log_section("Phase 1: Preflight Checks")

    # Check write permission to installation directory
    log("Checking write permission to installation directory...")
    try:
        test_file = os.path.join(sys.prefix, ".write_test")
        with open(test_file, "w") as f:
            f.write("ok")
        os.remove(test_file)
        log("  Write permission: OK")
    except PermissionError:
        log("  FATAL: No write permission to installation directory!")
        log(f"  Directory: {sys.prefix}")
        create_failure_file("No write permission to installation directory")
        return 1
    except Exception as e:
        log(f"  Write permission check warning: {e}")
        # Non-fatal, proceed

    if not check_disk_space(8):
        create_failure_file("Insufficient disk space (8GB required)")
        return 1

    if not check_network():
        create_failure_file("Network connectivity required")
        return 1

    # Ensure VC++ Redistributable is installed (required for PyTorch, native libs)
    ensure_vc_redist()

    # Setup config directory in %APPDATA% and migrate from old location if needed
    log("")
    log("Setting up configuration directory...")
    setup_config_directory()
    migrate_config()

    # Check WebView2 (non-fatal, but prompt user)
    if not check_webview2_windows():
        prompt_webview2_install()

    # === Phase 2: GPU and CUDA Detection ===
    log_section("Phase 2: GPU and CUDA Detection")
    driver_info = check_cuda_driver()

    # === Phase 3: PyTorch Installation ===
    log_section("Phase 3: PyTorch Installation")
    if not install_pytorch(driver_info):
        create_failure_file("PyTorch installation failed")
        return 1

    # === Phase 3.5: Git-Based Core Packages ===
    # These packages are installed from GitHub and need special handling:
    # - They benefit from git timeout/retry logic
    # - They must be installed AFTER PyTorch (dependency)
    # - They are excluded from requirements.txt to avoid pip/uv git issues
    log_section("Phase 3.5: Core Whisper Packages (Git-based)")

    git_packages = [
        # Core ASR packages (order matters - whisper before stable-ts)
        ("openai-whisper @ git+https://github.com/openai/whisper@main", "OpenAI Whisper"),
        ("stable-ts @ git+https://github.com/meizhong986/stable-ts-fix-setup.git@main", "Stable-TS (WhisperJAV fork)"),
        # FFmpeg Python bindings
        ("ffmpeg-python @ git+https://github.com/kkroening/ffmpeg-python.git", "FFmpeg-Python"),
        # Speech enhancement (enhance extra - included in standalone installer)
        ("clearvoice @ git+https://github.com/meizhong986/ClearerVoice-Studio.git#subdirectory=clearvoice", "ClearVoice Speech Enhancement"),
    ]

    log("Installing core packages from GitHub...")
    log("These packages require git and may take a few minutes.")
    log("")

    for package_spec, description in git_packages:
        if not run_pip(
            ["install", package_spec, "--progress-bar", "on"],
            f"Install {description}"
        ):
            create_failure_file(f"{description} installation failed")
            return 1

    log("")
    log("Core Whisper packages installed successfully.")

    # === Phase 4: Python Dependencies ===
    log_section("Phase 4: Python Dependencies Installation")

    req_path = os.path.join(sys.prefix, "requirements_v{{VERSION}}.txt")
    if not os.path.exists(req_path):
        log(f"ERROR: requirements_v{{VERSION}}.txt not found at {req_path}")
        create_failure_file(f"Missing requirements file: {req_path}")
        return 1
```

--------------------------------

### Install PyTorch with CUDA 11.8 via Conda

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/en/guides/installation_linux.md

Installs PyTorch and Torchaudio with automatic CUDA 11.8 setup using Conda. This method simplifies CUDA management for older driver versions.

```bash
# Or for CUDA 11.8:
conda install pytorch torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia -y
```

--------------------------------

### Run the Installer Script

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/en/guides/installation_windows_python.md

Execute the standard installation script or use the batch wrapper to install WhisperJAV. Both methods achieve the same result by running the install.py script.

```cmd
REM Standard install (auto-detects GPU)
python install.py
```

```cmd
REM Or use the batch wrapper:
installer\install_windows.bat
```

--------------------------------

### Install WhisperJAV with Specific Extras (Correct Method)

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/en/guides/installation_windows_python.md

Demonstrates the correct method to install WhisperJAV with extras, ensuring PyTorch is installed first and using `--no-deps` to avoid dependency conflicts.

```cmd
REM RIGHT: Install PyTorch first, then WhisperJAV with no-deps
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu128
pip install --no-deps -e "."
pip install "whisperjav[cli]" --no-deps
```

--------------------------------

### Install Speech Enhancement Dependencies from Registry

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/external_review/install.py.txt

Installs speech enhancement dependencies using pip. It first attempts to get the package list from a registry and falls back to a hardcoded list if the registry query fails.

```python
enhance_deps = _get_enhance_deps_from_registry()
        if enhance_deps:
            run_pip(
                executor,
                ["install"] + enhance_deps,
                "Install speech enhancement dependencies",
                allow_fail=True
            )
```

--------------------------------

### Troubleshooting: Constructor Installation

Source: https://github.com/meizhong986/whisperjav/blob/main/installer/README.md

Command to install the constructor package if it's missing or causing issues.

```bash
conda install constructor -c conda-forge
```

--------------------------------

### Complete WhisperJAV UI Workflow Example

Source: https://github.com/meizhong986/whisperjav/blob/main/whisperjav/webview_gui/API_REFERENCE.md

This comprehensive example demonstrates the full JavaScript workflow for the WhisperJAV application. It covers initializing the UI, adding input files or folders, starting and cancelling processing, and handling logs and status updates.

```javascript
// Initialize UI
async function initializeUI() {
    // Set default output directory
    const defaultDir = await pywebview.api.get_default_output_dir();
    document.getElementById('output-dir').value = defaultDir;
}

// Add files
async function addFiles() {
    const result = await pywebview.api.select_files();
    if (result.success) {
        result.paths.forEach(path => {
            // Add to input list UI
            addToInputList(path);
        });
    }
}

// Add folder
async function addFolder() {
    const result = await pywebview.api.select_folder();
    if (result.success) {
        addToInputList(result.path);
    }
}

// Start processing
async function startProcessing() {
    // Collect options from form
    const options = {
        inputs: getInputList(),
        mode: document.getElementById('mode').value,
        sensitivity: document.getElementById('sensitivity').value,
        language: document.getElementById('language').value,
        output_dir: document.getElementById('output-dir').value,
        verbosity: document.getElementById('verbosity').value,
        async_processing: document.getElementById('async').checked,
        no_vad: document.getElementById('noVad').checked,
    };

    // Start process
    const result = await pywebview.api.start_process(options);

    if (result.success) {
        console.log('Started:', result.command);

        // Update UI
        document.getElementById('start-btn').disabled = true;
        document.getElementById('cancel-btn').disabled = false;

        // Start log polling
        startLogPolling();
    } else {
        alert('Error: ' + result.message);
    }
}

// Cancel processing
async function cancelProcessing() {
    const result = await pywebview.api.cancel_process();
    if (result.success) {
        console.log('Cancelled');
        stopLogPolling();
    }
}

// Log polling
let logPollInterval = null;

function startLogPolling() {
    logPollInterval = setInterval(async () => {
        // Fetch new logs
        const logs = await pywebview.api.get_logs();
        logs.forEach(line => {
            appendToConsole(line);
        });

        // Check status
        const status = await pywebview.api.get_process_status();

        if (status.status === 'completed') {
            console.log('Process completed successfully');
            stopLogPolling();
            onProcessComplete();
        } else if (status.status === 'error') {
            console.error('Process failed:', status.exit_code);
            stopLogPolling();
            onProcessError(status.exit_code);
        } else if (status.status === 'cancelled') {
            console.log('Process cancelled');
            stopLogPolling();
            onProcessCancelled();
        }
    }, 100);
}

function stopLogPolling() {
    if (logPollInterval) {
        clearInterval(logPollInterval);
        logPollInterval = null;
    }
}

// Event handlers
function onProcessComplete() {
    document.getElementById('start-btn').disabled = false;
    document.getElementById('cancel-btn').disabled = true;
    document.getElementById('status').textContent = 'Completed';
}

function onProcessError(exitCode) {
    document.getElementById('start-btn').disabled = false;
    document.getElementById('cancel-btn').disabled = true;
    document.getElementById('status').textContent = `Error (${exitCode})`;
}

function onProcessCancelled() {
    document.getElementById('start-btn').disabled = false;
    document.getElementById('cancel-btn').disabled = true;
    document.getElementById('status').textContent = 'Cancelled';
}

// Initialize on load
window.addEventListener('DOMContentLoaded', initializeUI);
```

--------------------------------

### Print Installation Summary

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/external_review/executor.py.txt

Displays a formatted summary of installation statistics to the log. This provides a clear overview of the outcome.

```python
def print_summary(self):
    """Print installation summary."""
    stats = self.get_stats()
    self.log("")
    self.log("=" * 40)
    self.log("  Installation Summary")
    self.log("=" * 40)
    self.log(f"  Installed: {stats['install_count']}")
    self.log(f"  Skipped:   {stats['skip_count']}")
    self.log(f"  Failed:    {stats['fail_count']}")
    self.log(f"  Total:     {stats['total']}")
    self.log("=" * 40)
```

--------------------------------

### Ollama Not Running Error Message

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/research/OLLAMA_INTEGRATION_RESEARCH.md

This message appears if Ollama is installed but not currently running. It instructs the user on how to start the Ollama service.

```text
Translation engine is installed but not running.
Start Ollama from your system tray (Windows) or Applications (macOS). Or run: ollama serve
```

--------------------------------

### SceneDetectorFactory: Get Available Backends

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/architecture/SCENE_DETECTION_SPECIFICATION.md

Retrieves a list of all registered scene detection backends along with their availability status and installation hints.

```python
# Get all backends with availability status
SceneDetectorFactory.get_available_backends()
# → [{"name": "auditok", "display_name": "Auditok (Silence-Based)",
#      "available": True, "install_hint": ""}, ...]
```

--------------------------------

### Fast Install (Skip Optional Packages)

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/en/guides/installation_windows_python.md

Perform a faster installation by skipping speech enhancement and local LLM packages.

```cmd
REM Fast install (skip slow optional packages)
python install.py --no-speech-enhancement --no-local-llm
```

--------------------------------

### Help Command

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/research/FASTER_WHISPER_XXL_CLI_REFERENCE.md

Display all available command-line options and their descriptions.

```bash
faster-whisper-xxl.exe --help
```

--------------------------------

### Install with Local LLM Support

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/en/guides/installation_windows_python.md

Install all features, including local LLM translation capabilities.

```cmd
REM Everything including local LLM
python install.py --local-llm
```

--------------------------------

### Copy Launcher to Root Directory

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/external_review/post_install_v1.8.2rc1.py.txt

Copies the user-friendly launcher executable to the root of the installation directory. This function is called as part of the post-installation setup.

```python
# === Phase 5.5: Copy Launcher to Root ===
log_section("Phase 5.5: User-Friendly Launcher Setup")
launcher_exe = copy_launcher_to_root()
```

--------------------------------

### Get Git Packages for a Step

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/external_review/install.py.txt

Retrieves git-based packages for given extras. Returns a list of (git_url, description) tuples for packages installed from Git sources.

```python
def _get_git_packages_for_step(extras: list) -> list:
    """
    Get git-based packages for given extras.

    Args:
        extras: List of Extra enum values to include

    Returns:
        List of (git_url, description) tuples
    """
    if not _REGISTRY_AVAILABLE:
        return []

    packages = []
    for extra in extras:
        for pkg in get_packages_by_extra(extra):
            if pkg.source == InstallSource.GIT and pkg.git_url:
                if pkg.matches_platform():
                    desc = pkg.reason or f"Install {pkg.name}"
                    packages.append((pkg.git_url, desc))

    return packages
```

--------------------------------

### Qwen2-Audio Instruction Following

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/architecture/ADR-002-multi-model-asr-architecture.md

7B parameter Audio-LLM for instruction following. Requires loading the model with device_map='auto'.

```python
from transformers import Qwen2AudioForConditionalGeneration, AutoProcessor
import librosa

processor = AutoProcessor.from_pretrained("Qwen/Qwen2-Audio-7B-Instruct")
model = Qwen2AudioForConditionalGeneration.from_pretrained(
    "Qwen/Qwen2-Audio-7B-Instruct",
    device_map="auto"
)
```

--------------------------------

### Prompt User to Install WebView2

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/external_review/post_install_v1.8.2rc1.py.txt

Prompts the user to install the WebView2 runtime by opening the download URL in a browser and providing a timed input for confirmation. Re-checks installation status afterwards.

```python
def prompt_webview2_install():
    """Prompt user to install WebView2 and open download page"""
    log("\n" + "!" * 80)
    log("  IMPORTANT: WebView2 Runtime Required for GUI")
    log("!" * 80)
    log("")
    log("WhisperJAV uses Microsoft Edge WebView2 for its modern web-based interface.")
    log("WebView2 is not currently installed on this system.")
    log("")
    log("The installer will now open your browser to download WebView2.")
    log("You have 30 seconds to install it, or the installer will continue automatically.")
    log("")

    download_url = "https://go.microsoft.com/fwlink/p/?LinkId=2124703"
    try:
        import webbrowser
        webbrowser.open(download_url)
        log(f"Opening: {download_url}")
    except Exception:
        log(f"Please manually download from: {download_url}")

    log("")
    timed_input("Press Enter after installing WebView2 (auto-continues in 30s): ", 30, "")

    # Re-check after user confirms
    if check_webview2_windows():
        log("WebView2 detected! Installation will continue.")
    else:
        log("WARNING: WebView2 still not detected. You can install it later.")
        log("         The application will not launch without WebView2.")
```

--------------------------------

### Linux/macOS Upgrade Procedure

Source: https://github.com/meizhong986/whisperjav/blob/main/tests/INSTALLATION_ACCEPTANCE_TESTS.md

This bash script deactivates the current virtual environment, removes the old one, and then executes the installation script for a fresh setup on Linux or macOS.

```bash
# Step 1: Deactivate and remove old environment
deactivate  # if in venv
rm -rf whisperjav-env  # or your venv name

# Step 2: Fresh install
./installer/install_linux.sh
```

--------------------------------

### Audio-LLM (Qwen2-Audio) Usage Examples

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/architecture/ADR-002-multi-model-asr-architecture.md

Shows how to use the Audio-LLM mode with Qwen2-Audio, including custom prompts.

```bash
whisperjav video.mp4 --mode audio-llm
whisperjav video.mp4 --mode audio-llm --llm-prompt "Transcribe and describe emotions"
```

--------------------------------

### Check for Conflicting Python Packages

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/en/UPGRADE_TROUBLESHOOTING.md

Verify installed Python packages for conflicts. This command helps diagnose issues where WhisperJAV fails to start due to incompatible package versions.

```cmd
python.exe -m pip check
```

--------------------------------

### Add Phase 3 Installer Guidance to FAQ

Source: https://github.com/meizhong986/whisperjav/blob/main/docs/ISSUE_TRACKER_v1.8.x.md

This documentation update provides guidance for checking Phase 3 installer progress and tailing logs.

```markdown
commit `e1cddf0`: FAQ "The installer is stuck" entry expanded with Phase 3 progress-checking guidance + tail-the-log instructions.
```