How Voice-Pro Handles GPU or CPU Selection: Device Detection and Configuration

Voice-Pro determines whether to use GPU or CPU through a three-tier detection system in app/one_click.py that prioritizes the GPU_CHOICE environment variable, falls back to a persisted installer_files/gpu_choice.txt file, and defaults to CPU if neither is present.

Voice-Pro, an open-source voice processing toolkit maintained by abus-aikorea, implements a deterministic bootstrap mechanism to select between CUDA GPU acceleration and CPU execution. Understanding how Voice-Pro handles GPU or CPU selection is critical for ensuring the correct PyTorch binaries are installed and that downstream modules target the appropriate compute device. The selection logic resides in the OneClick helper class and influences both the dependency resolution phase and runtime model allocation.

The Three-Tier Detection Hierarchy

Voice-Pro's device selection follows a priority cascade defined in the OneClick.gpu_choice() class method within app/one_click.py. This hierarchy allows users to override persisted settings via environment variables while maintaining defaults across application restarts.

Environment Variable Override

The system first inspects the GPU_CHOICE environment variable at startup. Valid values are "G" for GPU or "C" for CPU. When this variable is set, it takes precedence over all other configuration sources, enabling temporary overrides without modifying persisted files.

Persisted Configuration File

If GPU_CHOICE is unset or empty, the code looks for installer_files/gpu_choice.txt inside the installation directory. This file is written by the start and update scripts (start.bat or start.sh) during initial setup. The content (G or C) is read and normalized to uppercase to determine the compute preference.

CPU Default Fallback

When neither the environment variable nor the persisted file yields a valid value, the method returns "C", forcing CPU execution. This conservative default ensures the application remains functional on systems without CUDA-capable hardware.

# https://github.com/abus-aikorea/voice-pro/blob/main/one_click.py#L60-L68

def gpu_choice(cls):
    # GPU_CHOICE env var > choice saved by start/update scripts > CPU

    choice = os.environ.get("GPU_CHOICE", "").upper()
    if not choice:
        saved = os.path.join(cls.install_dir, "gpu_choice.txt")
        if os.path.exists(saved):
            choice = open(saved).read().strip().upper()
    return choice if choice in ("G", "C") else "C"

Applying the Selection: Installation and Runtime

The value returned by gpu_choice() drives two distinct behaviors that occur at different stages of the application lifecycle.

UV Dependency Resolution

During environment installation or updates, Voice-Pro uses UV (the Python package installer) to synchronize dependencies. The device selection determines which optional dependency group (extra) is passed to the sync command. The pyproject.toml defines separate gpu and cpu extras that control whether CUDA-enabled PyTorch wheels are installed.

# https://github.com/abus-aikorea/voice-pro/blob/main/one_click.py#L160-L169

extra = "gpu" if cls.gpu_choice() == "G" else "cpu"
uv = cls.uv_exe()
cls.oc_run_cmd(f'"{uv}" sync --frozen --extra {extra}', assert_success=True)

When "gpu" is selected, UV installs CUDA-compiled PyTorch binaries required for GPU acceleration. The "cpu" extra installs CPU-only wheels, reducing installation size on systems without compatible NVIDIA hardware.

Runtime Device Allocation

Throughout Voice-Pro's core modules—including ASR (Automatic Speech Recognition), TTS (Text-to-Speech), and translation—the code relies on PyTorch's device management. When GPU_CHOICE is "G", the application assumes CUDA availability (verified via torch.cuda.is_available()) and explicitly moves models to the "cuda" device. Because the appropriate PyTorch package was installed during the UV sync phase, runtime code can safely assume GPU availability when the selection is "G".

Practical Configuration Examples

Users can control Voice-Pro's compute device through several methods depending on their workflow requirements.

Forcing GPU Usage

Set the environment variable before launching the application:

export GPU_CHOICE=G  # Linux/macOS

# OR

set GPU_CHOICE=G     # Windows CMD

# Then start

start.bat

Forcing CPU Usage

Explicitly disable GPU acceleration to avoid CUDA initialization:

export GPU_CHOICE=C
start.bat

Using Persisted Settings

Allow the start scripts to read from installer_files/gpu_choice.txt by omitting the environment variable:

# Ensure installer_files/gpu_choice.txt contains G or C

unset GPU_CHOICE
start.bat

Summary

• Detection Order: Voice-Pro checks GPU_CHOICE environment variable first, then installer_files/gpu_choice.txt, and defaults to CPU ("C").
• Installation Impact: The selection determines whether UV installs gpu or cpu extras from pyproject.toml, controlling PyTorch wheel variants.
• Runtime Behavior: Downstream modules use the selection to target PyTorch devices, with "G" enabling CUDA model placement.
• Configuration Location: Core logic resides in app/one_click.py within the OneClick.gpu_choice() method (lines 60-68).

Frequently Asked Questions

How do I permanently set Voice-Pro to use GPU?

Write G to the installer_files/gpu_choice.txt file in your Voice-Pro installation directory. This persists the preference across restarts without requiring environment variables. Alternatively, run the start scripts once with GPU_CHOICE=G exported, which typically writes this value to the file automatically.

What happens if I set GPU_CHOICE to an invalid value?

Invalid values (anything other than "G" or "C") cause the gpu_choice() method to return "C", forcing CPU mode. This safety mechanism prevents startup failures due to typos or unsupported device codes.

Why does Voice-Pro use UV extras instead of runtime detection?

Using UV extras during installation ensures only the necessary PyTorch binaries are downloaded. GPU wheels include large CUDA libraries (several gigabytes), while CPU wheels are significantly smaller. This approach optimizes disk usage and installation time based on the target hardware.

Can I switch from GPU to CPU without reinstalling?

Yes. Change the GPU_CHOICE environment variable to "C" and restart the application. However, if the underlying PyTorch packages were installed for GPU, you may need to run the update scripts to sync CPU-only dependencies via uv sync --extra cpu to avoid CUDA runtime errors.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}