# VoiceStudio Backend Configuration Options: Environment Variables and Worker Settings Explained

> Explore VoiceStudio backend configuration options, including environment variables and worker settings. Learn how to manage system-level and transport-layer connections effectively for your VoiceStudio project.

- Repository: [Palash Debnath/VoiceStudio](https://github.com/debpalash/VoiceStudio)
- Tags: how-to-guide
- Published: 2026-09-11

---

**VoiceStudio's backend configuration is controlled through environment variables for system-level settings and the `WorkerConfig` dataclass for transport-layer worker connections, all centralized in [`backend/core/config.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/config.py) and [`backend/worker/transport/client.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/worker/transport/client.py).**

The **debpalash/VoiceStudio** repository exposes two distinct layers of VoiceStudio backend configuration options: environment-driven initialization settings that control data paths, timeouts, and compute resources, and programmatic worker settings that manage secure transport connections. Understanding these configuration mechanisms allows you to deploy the backend across different environments—from local development machines to distributed worker pools—without modifying source code.

## Environment Variable Configuration

The [`backend/core/config.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/config.py) module reads **environment variables** once at startup via `ensure_dirs()` and `_ensure_short_hf_cache_on_windows()`. These variables determine file system layout, process lifecycle, and cache behavior.

### Data Directory and Storage Paths

The `OMNIVOICE_DATA_DIR` environment variable defines the root directory for all persistent storage. When unset, the backend applies platform-specific defaults: `~/Library/Application Support/OmniVoice` on macOS, `%APPDATA%\\OmniVoice` on Windows, and `~/.omnivoice` on Linux. From this root, the system derives several subdirectories:
- `VOICES_DIR` for voice model storage
- `OUTPUTS_DIR` for generated audio
- `DUB_DIR` for dubbing projects
- `PREVIEW_DIR` for temporary preview files
- `DB_PATH` pointing to the SQLite database at `${DATA_DIR}/omnivoice.db`
- `LOG_PATH` and `CRASH_LOG_PATH` for runtime and crash diagnostics

### Performance and Resource Tuning

Two critical environment variables control compute resource allocation:

- **`OMNIVOICE_IDLE_TIMEOUT`**: Specifies the idle shutdown threshold in seconds (default `900`). After this period of inactivity, the backend triggers shutdown procedures to free resources.
- **`OMNIVOICE_CPU_POOL`**: Sets the number of CPU-only workers. The default value `0` resolves dynamically to `min(8, cpu_count)`, automatically scaling to available hardware without manual intervention.

### Hugging Face Cache Overrides

To prevent path length issues on Windows or direct cache to specific storage, the backend checks three environment variables in order of precedence: `OMNIVOICE_CACHE_DIR`, `HF_HOME`, and `HF_HUB_CACHE`. If none are set on Windows, `_ensure_short_hf_cache_on_windows()` generates a short-path fallback to avoid NTFS path length limitations.

### FFmpeg Binary Resolution

On macOS and Linux systems, [`backend/core/config.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/config.py) automatically prepends `/opt/homebrew/bin` and `/usr/local/bin` to the `PATH` environment variable if those directories exist. This ensures the `ffmpeg` binary is discoverable without requiring system-wide installation or manual path configuration.

## Worker Transport Configuration

Remote workers connecting to the VoiceStudio control plane use the **`WorkerConfig`** dataclass defined in [`backend/worker/transport/client.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/worker/transport/client.py). This configuration is not environment-based but passed programmatically when initializing worker instances.

### WorkerConfig Connection Parameters

The `WorkerConfig` dataclass requires these secure transport parameters:

- **`endpoint`**: The HTTPS address of the control server (e.g., `https://127.0.0.1:3900`).
- **`cert_fingerprint`**: SHA-256 fingerprint of the server certificate for certificate pinning.
- **`certificate_pem`**: PEM-encoded certificate data for TLS verification.
- **`keypair`**: A `WorkerKeypair` instance containing the private/public key pair for mutual TLS authentication.
- **`enrollment_token`**: One-time token for initial worker registration.
- **`worker_id`**: Optional persistent identifier assigned by the server for reconnections.

### Task Concurrency and Capabilities

Worker capacity is defined through:
- **`max_concurrent_tasks`**: The maximum number of simultaneous tasks the worker accepts (internally clamped by `clamp_concurrency`).
- **`capabilities`**: A list of dictionaries describing supported models, languages, and engines (e.g., `[{"engine": "faster-whisper", "languages": ["en", "es"]}]`).
- **`host`**: Static host metadata generated by `describe_host()`, including hostname, OS type, and CPU count.

## Runtime-Derived Constants

After parsing environment variables, [`backend/core/config.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/config.py) exposes immutable constants used throughout the application:

```python
from backend.core import config

# File system layout

print(f"Data root: {config.DATA_DIR}")
print(f"Database: {config.DB_PATH}")
print(f"Voice storage: {config.VOICES_DIR}")

# Performance settings

print(f"Idle timeout: {config.IDLE_TIMEOUT_SECONDS}s")
print(f"CPU workers: {config.CPU_POOL_WORKERS}")

```

These constants are computed exactly once during module import, ensuring deterministic behavior across the FastAPI application initialized in [`backend/main.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/main.py).

## How to Configure VoiceStudio Backend

### Local Development Setup

Override the data directory and Hugging Face cache for isolated testing:

```python
import os

os.environ["OMNIVOICE_DATA_DIR"] = "/tmp/voice_studio_dev"
os.environ["OMNIVOICE_CACHE_DIR"] = "/mnt/fast_storage/hf_cache"

# Import after setting environment variables

from backend.core import config
from backend.core.config import ensure_dirs

ensure_dirs()  # Creates directory structure

print(f"Runtime DB: {config.DB_PATH}")

```

### Worker Connection Setup

Configure a remote worker with certificate pinning and concurrency limits:

```python
from backend.worker.transport.client import WorkerConfig, describe_host

worker_cfg = WorkerConfig(
    endpoint="https://voice-studio.internal:3900",
    cert_fingerprint="AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12",
    max_concurrent_tasks=4,
    capabilities=[{
        "engine": "faster-whisper",
        "languages": ["en", "de", "fr"],
        "gpu": True
    }],
    host=describe_host()
)

```

## Summary

- **Environment variables** in [`backend/core/config.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/config.py) control file paths (`OMNIVOICE_DATA_DIR`), process timeouts (`OMNIVOICE_IDLE_TIMEOUT`), compute pools (`OMNIVOICE_CPU_POOL`), and Hugging Face cache locations.
- **`WorkerConfig`** in [`backend/worker/transport/client.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/worker/transport/client.py) manages secure worker connections through endpoint URLs, certificate fingerprints, and mutual TLS keypairs.
- **Derived constants** (`DATA_DIR`, `DB_PATH`, `CPU_POOL_WORKERS`) are computed at startup and used throughout the FastAPI application.
- **FFmpeg resolution** happens automatically on Unix systems by extending `PATH` with common Homebrew and local installation directories.
- All configuration is read once at import time, making the backend deterministic after initialization.

## Frequently Asked Questions

### How do I change the default data directory for VoiceStudio?

Set the `OMNIVOICE_DATA_DIR` environment variable before importing any backend modules. According to the source code in [`backend/core/config.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/config.py), this variable overrides the platform-specific defaults (macOS `~/Library/Application Support/OmniVoice`, Windows `%APPDATA%\\OmniVoice`, or Linux `~/.omnivoice`). The backend automatically creates subdirectories for voices, outputs, and the SQLite database under this root when `ensure_dirs()` runs.

### What controls how many CPU workers VoiceStudio uses?

The `OMNIVOICE_CPU_POOL` environment variable sets the number of CPU-only workers. If set to `0` (the default), the backend calculates `min(8, cpu_count)` to automatically scale with your hardware. This value is stored in `CPU_POOL_WORKERS` constant and determines the size of the process pool available for audio processing tasks that don't require GPU acceleration.

### How do workers securely connect to the VoiceStudio backend?

Workers use the `WorkerConfig` dataclass defined in [`backend/worker/transport/client.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/worker/transport/client.py) to establish mutual TLS connections. You must provide the `endpoint` URL, `cert_fingerprint` for pinning, `certificate_pem` data, and a `keypair` for authentication. The `enrollment_token` handles initial registration, while `max_concurrent_tasks` and `capabilities` tell the control plane what workloads the worker can accept.

### Where does VoiceStudio store its SQLite database?

The database path is derived from the `DATA_DIR` constant, stored at `${DATA_DIR}/omnivoice.db` as defined in [`backend/core/config.py`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/config.py). By default, this resolves to the omnivoice.db file within your platform's application support directory, but you can redirect it by setting the `OMNIVOICE_DATA_DIR` environment variable before startup.