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

> Easily launch Voice-Pro on macOS with our simple guide. Install dependencies and start the Gradio interface at http://127.0.0.1:7870 without admin rights.

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

---

**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`](https://github.com/abus-aikorea/voice-pro/blob/main/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
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`](https://github.com/abus-aikorea/voice-pro/blob/main/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
bash start.sh

```

This command triggers the platform detection logic in [`start.sh`](https://github.com/abus-aikorea/voice-pro/blob/main/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`](https://github.com/abus-aikorea/voice-pro/blob/main/start.sh) automatically executes the application entry point:

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

```

This command launches the Gradio-based web UI defined in [`app/gradio_gulliver.py`](https://github.com/abus-aikorea/voice-pro/blob/main/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`](https://github.com/abus-aikorea/voice-pro/blob/main/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`](https://github.com/abus-aikorea/voice-pro/blob/main/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:

```bash
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`](https://github.com/abus-aikorea/voice-pro/blob/main/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`](https://github.com/abus-aikorea/voice-pro/blob/main/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`](https://github.com/abus-aikorea/voice-pro/blob/main/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`](https://github.com/abus-aikorea/voice-pro/blob/main/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`](https://github.com/abus-aikorea/voice-pro/blob/main/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.