# Common Troubleshooting Steps for Voice-Pro Issues: A Complete Guide

> Fix common Voice-Pro issues with our guide. Resolve startup crashes by deleting installer files or address CUDA errors by adjusting compute types and model sizes.

- Repository: [ABUS/voice-pro](https://github.com/abus-aikorea/voice-pro)
- Tags: how-to-guide
- Published: 2026-08-03

---

**Delete the `installer_files/` directory and rerun the launcher to fix most startup crashes, or adjust compute types and model sizes to resolve CUDA memory errors.**

Voice-Pro is an open-source, three-layer Gradio web application that orchestrates video downloading, **ASR** (Automatic Speech Recognition), translation, and **TTS** (Text-to-Speech) pipelines. Because it integrates external tools like ffmpeg, CUDA drivers, and Azure cloud services, issues often manifest as UI error toasts or console tracebacks. This guide covers the most frequent Voice-Pro problems and their fixes based on the actual source code in `abus-aikorea/voice-pro`.

## Understanding the Voice-Pro Architecture

Voice-Pro follows a modular Gradio architecture defined in [`app/abus_app_voice.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/abus_app_voice.py). The entry point [`start-voice.py`](https://github.com/abus-aikorea/voice-pro/blob/main/start-voice.py) loads user configuration from [`src/config.py`](https://github.com/abus-aikorea/voice-pro/blob/main/src/config.py) and assembles the UI from tab modules (`app/tab_*.py`), which delegate processing to core functions (`app/abus_*.py`). Errors typically bubble up from the processing layer through Gradio controllers (`app/gradio_*.py`) and are logged via `structlog`.

Knowing this flow helps isolate whether a failure stems from environment setup (installer/virtual-env), configuration (`.env` files), or runtime resource limits (GPU memory).

## Fixing Installation and Startup Failures

### Red Error Toasts or Crashes on Launch

If Voice-Pro displays a red error toast immediately or crashes during startup, the cause is usually corrupted or missing files in the `installer_files/` directory. This folder contains the uv package manager, Python interpreter, and installed dependencies.

**Recommended fix:** Delete the entire `installer_files/` directory and rerun `start.bat` (Windows) or [`start.sh`](https://github.com/abus-aikorea/voice-pro/blob/main/start.sh) (Linux/macOS). The launcher will redownload uv, create a fresh virtual environment, and reinstall all dependencies.

```python

# Force a clean reinstall programmatically

import shutil
import os
import subprocess

installer_dir = os.path.join(os.getcwd(), "installer_files")
if os.path.isdir(installer_dir):
    shutil.rmtree(installer_dir)  # Remove corrupted environment

subprocess.run(["start.bat"], shell=True)  # Re-run launcher

```

### Browser Does Not Open Automatically

When the command window finishes but the browser fails to launch, the auto-launch flag may be disabled, or the Windows command window may have closed prematurely.

**Recommended fix:** Manually navigate to `http://127.0.0.1:7870` in your browser, or close the terminal and rerun `start.bat` to trigger the launch sequence again.

## Resolving CUDA and GPU Memory Errors

### CUDA Out-of-Memory Errors

Selecting a large Whisper model, enabling denoise level 2, or using float compute precision can exhaust GPU RAM, causing the ASR pipeline to fail.

**Recommended fix:** Reduce the denoise level to **0** or **1**, or switch the compute type to **int** (quantized) in the Gradio UI. The backend applies this setting in modules like [`app/abus_asr_faster_whisper.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/abus_asr_faster_whisper.py).

```python

# Example: Configuring compute type to reduce VRAM usage

# In the UI, set "Compute Type" dropdown to "int" for quantized inference

# This is read by the ASR backend during model initialization

```

### GPU Not Detected

Voice-Pro relies on the `GPU_CHOICE` environment variable or a [`gpu_choice.txt`](https://github.com/abus-aikorea/voice-pro/blob/main/gpu_choice.txt) file in `installer_files/` to determine whether to use CUDA or CPU.

**Recommended fix:** Delete [`installer_files/gpu_choice.txt`](https://github.com/abus-aikorea/voice-pro/blob/main/installer_files/gpu_choice.txt) to force re-detection, or explicitly set the environment variable before running the start script:
- `GPU_CHOICE=G` for GPU (CUDA)
- `GPU_CHOICE=C` for CPU-only mode

## Improving Subtitle and Audio Quality

### Poor Subtitle Accuracy

Small Whisper models (e.g., `tiny` or `base`) or unsuitable compute types produce low-quality transcriptions.

**Recommended fix:** Switch to a larger model such as `large-v3-turbo` and ensure the compute type is set to **float** for higher fidelity rather than quantized **int** modes. This trades processing speed for accuracy as documented in the README troubleshooting section.

## Fixing Translation and TTS Service Failures

### Intermittent Translation or TTS Errors

The default Google-based translation endpoints are subject to rate limiting and geographic blocking, causing sporadic failures in the dubbing pipeline.

**Recommended fix:** Configure Azure Translator and Azure Speech Services by copying `.env.example` to `.env` and filling in your API keys. The application validates these credentials in [`app/abus_config.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/abus_config.py) using helper functions like `get_azure_speech_key()` and `get_azure_translator_key()`.

```python

# Example: Loading Azure credentials from .env

from app.abus_config import get_azure_speech_key, get_azure_translator_key

try:
    speech_key = get_azure_speech_key()          # Raises ValueError if missing

    translator_key = get_azure_translator_key()  # Raises ValueError if missing

    print("Azure credentials loaded successfully")
except ValueError as e:
    print(f"Configuration error: {e}")

```

The UI assembly logic in [`app/abus_app_voice.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/abus_app_voice.py) calls `azure_text_api_working()` from [`app/abus_genuine.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/abus_genuine.py) to determine whether to display the Azure TTS tab or fall back to limited offline options.

## Addressing FFmpeg and Model Download Issues

### FFmpeg-Related Errors

Missing codecs or ffmpeg not being on the system `PATH` causes video processing failures.

**Recommended fix:** The `start.bat` script automatically downloads a portable ffmpeg binary into `installer_files/ffmpeg/`. If you maintain a custom ffmpeg installation, ensure the binary is reachable from your system `PATH` environment variable.

### Stalled or Corrupted Model Downloads

Network interruptions during initial setup can leave partial model files in the `model/` directory.

**Recommended fix:** Re-run the start script. The downloader will resume or redownload missing model files. All filesystem paths—including `model/`, `workspace/`, and `installer_files/`—are resolved through [`app/abus_path.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/abus_path.py) to handle platform-specific directory conventions.

## Where Fixes Live in the Codebase

Understanding the specific files responsible for error handling helps with advanced debugging:

- **[`app/abus_app_voice.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/abus_app_voice.py)** – Top-level UI assembly that wires tabs and checks Azure service availability via `azure_text_api_working()`.
- **[`app/abus_config.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/abus_config.py)** – Reads `.env` variables via `python-dotenv` and raises clear exceptions if Azure keys are malformed or missing.
- **[`app/abus_path.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/abus_path.py)** – Centralized path resolution for `installer_files/`, `model/`, and `workspace/` directories.
- **[`app/abus_genuine.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/abus_genuine.py)** – Detects whether Azure services are properly configured and enabled.
- **[`app/gradio_gulliver.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/gradio_gulliver.py)** – Core "Dubbing Studio" pipeline controller where processing errors are logged.
- **[`start-voice.py`](https://github.com/abus-aikorea/voice-pro/blob/main/start-voice.py)** – Entry point that handles `GPU_CHOICE` logic and launches the Gradio interface.

## Summary

- **Clean reinstalls** fix most startup crashes by removing corrupted `installer_files/` directories.
- **CUDA OOM errors** are resolved by reducing denoise levels or switching to `int` compute types.
- **Azure credentials** must be configured in `.env` (copied from `.env.example`) to avoid translation/TTS rate limits.
- **GPU detection** relies on the `GPU_CHOICE` environment variable or deleting stale [`gpu_choice.txt`](https://github.com/abus-aikorea/voice-pro/blob/main/gpu_choice.txt) files.
- **Model and ffmpeg paths** are managed automatically by the launcher, but custom installations require proper `PATH` configuration.

## Frequently Asked Questions

### How do I completely reset Voice-Pro to factory settings?

Delete the `installer_files/` directory in the project root and rerun `start.bat` or [`start.sh`](https://github.com/abus-aikorea/voice-pro/blob/main/start.sh). This forces the launcher to redownload uv, recreate the Python virtual environment, and reinstall all dependencies without touching your workspace files or downloaded models.

### Why does Voice-Pro fail with a CUDA out-of-memory error on large files?

The selected Whisper model or denoise level 2 processing exceeds your GPU's VRAM. Open the Gradio UI settings and reduce the denoise level to **0** or **1**, or change the compute type from **float** to **int** (quantized) to reduce memory consumption by approximately 50%.

### How do I enable Azure Text-to-Speech to avoid Google rate limits?

Copy `.env.example` to `.env` in the project root, then add your Azure Speech key and Translator key to the file. The [`app/abus_config.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/abus_config.py) module will automatically load these values on startup, and [`app/abus_app_voice.py`](https://github.com/abus-aikorea/voice-pro/blob/main/app/abus_app_voice.py) will enable the Azure TTS tab if the credentials are valid.