How to Launch Voice-Pro on macOS: Complete Installation Guide

Run bash configure.sh followed by bash start.sh to install system dependencies and launch the Voice-Pro Gradio interface at http://127.0.0.1:7870 without requiring admin privileges.

Voice-Pro is an open-source AI dubbing pipeline from the abus-aikorea/voice-pro repository that combines YouTube downloading, source separation, ASR, translation, and TTS into a unified web interface. On macOS, the application runs inside an isolated Python 3.12 environment managed by the uv package manager, eliminating version conflicts with your system Python installation.

Prerequisites: System Configuration with configure.sh

Before launching Voice-Pro, you must install the required system tools. The repository provides configure.sh at the root level to automate macOS setup.

The script detects macOS by checking if OSTYPE starts with darwin. It then ensures Homebrew is present and uses it to install ffmpeg and git:

bash configure.sh

This step requires internet access but no administrator rights. The script specifically targets the macOS package ecosystem, linking ffmpeg via Homebrew to handle audio processing requirements for the pipeline.

Isolated Environment Setup with start.sh

The start.sh script orchestrates the entire runtime without touching your global Python installation. It performs three critical operations:

1. Downloads the uv binary – The script detects your architecture (aarch64-apple-darwin for Apple Silicon or x86_64-apple-darwin for Intel) and downloads the portable uv package manager into installer_files/uv/.

2. Creates a self-contained Python environment – Using the committed uv.lock file for deterministic builds, the script executes uv sync --frozen --extra cpu to install Python 3.12 and all dependencies into installer_files/.

3. Handles compute backend – On macOS, the script defaults to CPU mode. The GPU selection logic detects the platform and emits a warning if you attempt to force GPU mode, as macOS lacks NVIDIA CUDA support.

Run the setup and launch sequence:

bash start.sh

This command triggers the platform detection logic in start.sh to select the correct binary, then proceeds to dependency synchronization using the locked versions in uv.lock.

Launching the Gradio Web Interface

Once environment preparation completes, start.sh automatically executes the application entry point:

installer_files/env/bin/python start-abus.py voice

This command launches the Gradio-based web UI defined in app/gradio_gulliver.py, which wires together the download → ASR → translation → TTS pipelines. The server binds to http://127.0.0.1:7870 and becomes available in your browser.

The start-abus.py script serves as the main entry point, selecting the "voice" mode that initializes the dubbing interface. Behind the scenes, app/abus_config.py loads user configurations from config-user.json5 and merges them with default settings.

Optional Configuration

Azure Credentials for Cloud Services

To use Azure Translator or Azure TTS instead of local models, copy the example environment file and add your API keys:

cp .env.example .env

Edit .env with your Azure credentials. The application automatically detects these variables on startup and switches to Azure services as implemented in the configuration loading sequence.

GPU Selection Behavior

While macOS does not support NVIDIA CUDA, you can explicitly control the compute mode by setting the GPU_CHOICE environment variable. However, macOS systems ignore GPU requests and default to CPU processing with a warning message to ensure compatibility across both Intel and Apple Silicon architectures.

Troubleshooting Common Launch Issues

ffmpeg not found errors – If you encounter audio processing errors, re-run bash configure.sh to ensure ffmpeg is properly linked via Homebrew.

Missing uv binary – If the uv command fails, delete the installer_files/uv/ directory and re-run bash start.sh. The script will re-download the correct aarch64-apple-darwin or x86_64-apple-darwin binary based on your chipset.

Model download interruptions – Required HuggingFace models are fetched automatically by app/abus_hf.py into the model/ directory on first run. If downloads stall, delete the model/ folder to trigger a fresh download with resume capability.

Summary

• Run bash configure.sh to install Homebrew, ffmpeg, and git on macOS.
• Execute bash start.sh to download uv, create an isolated Python 3.12 environment in installer_files/, and synchronize dependencies from uv.lock.
• The script automatically launches start-abus.py voice, serving the Gradio UI at http://127.0.0.1:7870.
• macOS defaults to CPU mode; GPU selection falls back to CPU with a warning.
• Configure Azure credentials in .env to enable cloud translation and TTS services.

Frequently Asked Questions

Does Voice-Pro require Python to be pre-installed on my Mac?

No. According to the abus-aikorea/voice-pro source code, the start.sh script downloads its own Python 3.12 runtime using the uv package manager and installs all dependencies into installer_files/. This isolated approach avoids conflicts with existing Python installations and requires no admin rights or global package modifications.

Why does Voice-Pro default to CPU mode on macOS?

The start.sh script detects macOS via the OSTYPE variable and automatically selects CPU mode because macOS lacks native NVIDIA CUDA support. Attempting to force GPU mode with GPU_CHOICE=G results in a fallback to CPU processing with a warning message, ensuring compatibility across both Apple Silicon and Intel Macs.

Where are the AI models stored after the first launch?

On initial startup, app/abus_hf.py automatically downloads required HuggingFace models into the local model/ directory. These files persist between sessions, allowing offline operation after the first successful launch. You can delete this directory to force a re-download if models become corrupted or incomplete.

Can I run Voice-Pro on an Intel-based Mac?

Yes. The start.sh script detects your architecture and downloads the appropriate uv binary—x86_64-apple-darwin for Intel Macs or aarch64-apple-darwin for Apple Silicon. Both platforms execute the same Python 3.12 environment and Gradio interface without additional configuration changes.

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