VoiceStudio Backend Configuration Options: Environment Variables and Worker Settings Explained

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 and 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 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 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. 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 exposes immutable constants used throughout the application:

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.

How to Configure VoiceStudio Backend

Local Development Setup

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

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:

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 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 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, 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 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. 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.

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