# How VoiceStudio Supports Multiple Operating Systems and Docker: Cross-Platform Architecture Explained

> Discover how VoiceStudio achieves cross-platform compatibility on Windows macOS and Linux and supports Docker deployments with NVIDIA CUDA and AMD ROCm GPU acceleration.

- Repository: [Palash Debnath/VoiceStudio](https://github.com/debpalash/VoiceStudio)
- Tags: architecture
- Published: 2026-09-04

---

**VoiceStudio runs natively on Windows, macOS, and Linux through platform-specific TTS binaries while offering containerized deployment via a multi-stage Dockerfile that supports both NVIDIA CUDA and AMD ROCm GPU acceleration.**

VoiceStudio (debpalash/VoiceStudio) is an open-source text-to-speech application designed for maximum portability across operating systems. Its architecture cleanly separates platform-specific execution from containerized server deployment, enabling users to run the software either as a native desktop application or as a Docker container on any compatible host.

## Native Cross-Platform Desktop Support

VoiceStudio achieves native multi-operating system support through a combination of pre-compiled binaries and runtime architecture detection.

### Platform-Specific TTS Binary Distribution

The core TTS engine, `omnivoice-tts`, ships with pre-built executables for each supported OS and CPU architecture. According to the repository's [`bin/README.md`](https://github.com/debpalash/VoiceStudio/blob/main/bin/README.md), the platform matrix includes:

- **Windows** x86_64
- **macOS** x86_64 and arm64 (Apple Silicon)
- **Linux** x86_64 and aarch64

These binaries reside in the `bin/` directory, with provenance tracked in [`backend/engines/omnivoice_gguf/quant_map.json`](https://github.com/debpalash/VoiceStudio/blob/main/backend/engines/omnivoice_gguf/quant_map.json) and build scripts located in [`scripts/build-omnivoice-tts.sh`](https://github.com/debpalash/VoiceStudio/blob/main/scripts/build-omnivoice-tts.sh). The CI pipeline produces architecture-specific artifacts that the installer detects and extracts based on the host environment.

### Runtime Binary Selection and Validation

At runtime, the backend validates binary presence and compatibility through [`services/binary_preflight.py`](https://github.com/debpalash/VoiceStudio/blob/main/services/binary_preflight.py). The `BinaryPreflight.select_binary()` method automatically detects the host operating system and CPU architecture, then selects the appropriate `omnivoice-tts` executable from the `bin/` directory. This ensures that VoiceStudio launches the correct engine variant without manual configuration.

```python
from services.binary_preflight import BinaryPreflight
engine_path = BinaryPreflight.select_binary()
print(f"Using TTS engine at: {engine_path}")

```

## Docker-Based Server Deployment

Beyond native execution, VoiceStudio provides a containerized server mode that standardizes deployment across any Docker-compatible infrastructure.

### Multi-Stage Dockerfile Architecture

The `deploy/Dockerfile` implements a multi-stage build process that separates frontend compilation from runtime dependencies. The build stage uses Bun to compile the React frontend, while the runtime stage bases on a PyTorch image to support GPU-accelerated inference. System dependencies including `ffmpeg` are installed during the image construction (lines 47-53) to satisfy torchaudio requirements.

The Dockerfile also bundles the frontend assets directly into the server image:

```dockerfile
COPY --from=frontend-builder /app/frontend/dist /app/frontend/dist

```

This approach (lines 15-16) ensures the container serves both the API and UI from a single image, eliminating the need for separate web server containers.

### GPU Acceleration for NVIDIA and AMD

VoiceStudio's Docker implementation supports hardware-accelerated inference on both NVIDIA and AMD GPUs through configurable build arguments. The `BASE_IMAGE` and `GPU_FLAVOR` arguments allow swapping between CUDA and ROCm variants of the PyTorch base image.

A critical guard step (lines 97-104) prevents the package installation process from overwriting the GPU-specific Torch build provided by the base image. This assertion preserves AMD or NVIDIA support throughout the dependency resolution process:

```bash
docker build \
  --build-arg BASE_IMAGE=pytorch/pytorch:2.8.0-cuda12.8-cudnn9-runtime \
  --build-arg GPU_FLAVOR=cuda \
  -t voicestudio:gpu .

```

### CPU-Only Container Deployment

For environments without GPU resources, the Dockerfile defaults to CPU-optimized execution. The following commands build and run a lightweight VoiceStudio instance suitable for general-purpose servers:

```bash
docker build -t voicestudio:latest .
docker run -p 3900:3900 -v $(pwd)/omnivoice_data:/app/omnivoice_data voicestudio:latest

```

## Docker Compose Orchestration

The repository includes a [`deploy/docker-compose.yml`](https://github.com/debpalash/VoiceStudio/blob/main/deploy/docker-compose.yml) file that simplifies production deployment. This configuration defines a minimal orchestration setup that:

- Exposes port 3900 to the host
- Mounts persistent volumes for SQLite databases, HuggingFace model caches, and user-generated voice data
- Supports optional GPU passthrough via the `--gpus all` flag

To deploy using Docker Compose:

```bash
cd deploy
docker compose up --build

```

For GPU-accelerated instances, modify the compose command to include GPU device access:

```bash
docker compose up --build --gpus all

```

## Summary

- VoiceStudio supports native execution on Windows, macOS, and Linux through architecture-specific `omnivoice-tts` binaries stored in `bin/`.
- The [`services/binary_preflight.py`](https://github.com/debpalash/VoiceStudio/blob/main/services/binary_preflight.py) module automatically selects and validates the correct binary for the host platform at runtime.
- The `deploy/Dockerfile` uses a multi-stage build to bundle React frontend assets with a PyTorch backend, supporting both CPU and GPU inference.
- GPU acceleration is configurable via `BASE_IMAGE` and `GPU_FLAVOR` build arguments, with guard clauses protecting CUDA or ROCm installations.
- Docker Compose orchestration in [`deploy/docker-compose.yml`](https://github.com/debpalash/VoiceStudio/blob/main/deploy/docker-compose.yml) provides persistent storage and simplified server deployment on port 3900.

## Frequently Asked Questions

### Which operating systems does VoiceStudio support for native installation?

VoiceStudio supports native execution on Windows (x86_64), macOS (x86_64 and arm64), and Linux (x86_64 and aarch64). The installer automatically detects the host platform and selects the appropriate pre-compiled binary from the `bin/` directory, handling the configuration without user intervention.

### How do I enable GPU acceleration when running VoiceStudio in Docker?

Enable GPU acceleration by passing the `--build-arg BASE_IMAGE` and `--build-arg GPU_FLAVOR` flags during the Docker build process. For NVIDIA GPUs, use `pytorch/pytorch:2.8.0-cuda12.8-cudnn9-runtime` as the base image with `GPU_FLAVOR=cuda`. For AMD GPUs, specify a ROCm-based PyTorch image. The Dockerfile includes guard logic (lines 97-104) that prevents pip from overwriting these GPU-specific Torch builds during dependency installation.

### Can VoiceStudio run on AMD GPUs inside Docker containers?

Yes, VoiceStudio supports AMD ROCm acceleration through Docker. Specify a ROCm-enabled PyTorch base image using the `BASE_IMAGE` build argument and set `GPU_FLAVOR=rocm`. The multi-stage Dockerfile automatically preserves the ROCm-compatible Torch installation, enabling inference acceleration on AMD hardware without manual configuration inside the container.

### What is the purpose of the [`binary_preflight.py`](https://github.com/debpalash/VoiceStudio/blob/main/binary_preflight.py) service?

The [`services/binary_preflight.py`](https://github.com/debpalash/VoiceStudio/blob/main/services/binary_preflight.py) module performs runtime validation of the TTS engine binaries. It checks for the presence, integrity, and platform compatibility of the `omnivoice-tts` executables located in `bin/`, then automatically selects the correct architecture-specific binary for the current operating system. This ensures reliable cross-platform operation without requiring users to manually specify engine paths or download separate installers.