VoiceStudio Configuration: How Output and Cache Directories Are Managed

VoiceStudio separates output and cache concerns into distinct configuration layers, using environment variables for global defaults, path authorization for security whitelisting, and automatic pruning to manage transient worker cache files.

VoiceStudio (debpalash/VoiceStudio) implements a robust configuration system that isolates user-generated audio files from temporary processing data. The architecture combines a global configuration dataclass with runtime path validation to ensure secure file operations across the synthesis pipeline. This design keeps persistent output predictable while automatically maintaining bounded disk usage for transient caches.

Backend Core Configuration

The foundation of VoiceStudio's configuration system resides in the backend core, where global defaults are established before the server accepts requests.

The Config Dataclass

In backend/core/config.py, the Config dataclass defines optional fields output_dir and input_dir that control where the system writes final audio files and temporary cache data. The input_dir field specifically serves as the cache location for large model files and audio clips during processing. These paths populate during server startup and propagate throughout the application layer.

Environment Variable Loading

When the server initializes in backend/main.py, the configuration loads from environment variables with specific naming conventions:

• VOICE_STUDIO_OUTPUT_DIR – Specifies the default directory for synthesized audio files
• VOICE_STUDIO_CACHE_DIR – Defines the location for transient input caches

If these variables are unset, the system falls back to sensible defaults under the user's home directory. This approach allows operators to customize storage locations without modifying source code.

# Example: launching the server with custom directories

import os
os.environ["VOICE_STUDIO_OUTPUT_DIR"] = "/data/voice_outputs"
os.environ["VOICE_STUDIO_CACHE_DIR"]  = "/tmp/voice_cache"

# The server loads these values automatically

from backend.main import app  # FastAPI instance

Path Authorization Layer

VoiceStudio implements a security mechanism to prevent arbitrary file system writes by validating output directories against a whitelist.

Whitelisting Output Directories

The backend/core/path_authorization.py module maintains a registry of allowed directory "kinds" that API callers may reference. For example, the system recognizes "soni_output_dir" as an authorized output location. This abstraction prevents clients from specifying arbitrary paths while allowing flexibility within designated zones.

Request Validation in Routers

The backend/api/routers/sonitranslate.py router extracts the requested output directory from incoming request payloads and validates it against the authorized kinds defined in the path authorization module. If the directory is missing, empty, or not an absolute path, the router raises a ValueError before processing begins. This validation occurs at the API boundary, ensuring only sanitized paths reach the service layer.

# Example: API request to the sonitranslate endpoint

import httpx

payload = {
    "text": "Hello world",
    "output_authorization": {"kind": "soni_output_dir"},
    "output_dir": "/authorized/soni_output_dir"
}
resp = httpx.post("http://localhost:8000/api/sonitranslate", json=payload)
print(resp.json()["output_path"])

# -> "/authorized/soni_output_dir/abcd1234.wav"

Worker-Side Cache Management

While output directories handle persistent files, VoiceStudio manages transient data through a sophisticated caching system in the worker layer.

Task Store and Leasing

The backend/worker/task_store.py and backend/worker/executor.py modules utilize the input_dir path supplied via the global configuration. The executor creates isolated subdirectories for each input reference using the _cache_name(ref) function and maintains leases on these directories while tasks run. This prevents race conditions when multiple workers process simultaneous requests.

Automatic Cache Pruning

To prevent unbounded disk growth, the system implements a pruning routine named _prune_input_cache that monitors cache size. When the cache exceeds a configured byte limit, the routine evicts the oldest files while ensuring that partial downloads currently in use are never deleted prematurely. This automatic maintenance occurs transparently during task execution.

# Example: Worker-side cache usage (simplified)

from backend.worker.executor import TaskExecutor

executor = TaskExecutor(input_dir="/tmp/voice_cache")
await executor._fetch_one(ref, fetch)   # stores input under a lease

# Cache is automatically pruned when size > limit

API-Level Output Handling

The final stage of the VoiceStudio configuration flow involves writing synthesized audio to authorized locations.

In backend/services/sonitranslate.py, the service receives optional output_file and output_dir parameters from validated requests. After confirming authorization, the service resolves the final path using Path(output_dir).expanduser() to handle tilde expansion, then writes the generated audio file to that location. The tests/test_mcp_output_mode.py test suite confirms that the default output mode points to the "resources" directory and that custom paths parse correctly.

Summary

• Global defaults are defined in backend/core/config.py and loaded from VOICE_STUDIO_OUTPUT_DIR and VOICE_STUDIO_CACHE_DIR environment variables during server startup.
• Security validation occurs in backend/core/path_authorization.py and backend/api/routers/sonitranslate.py, ensuring only whitelisted, absolute paths are used for output.
• Transient cache management uses the input_dir configuration in backend/worker/task_store.py, with automatic pruning via _prune_input_cache to maintain disk limits.
• Final output is written through backend/services/sonitranslate.py using path expansion and authorization checks confirmed by the test suite in tests/test_mcp_output_mode.py.

Frequently Asked Questions

How do I change the default output and cache directories in VoiceStudio?

Set the VOICE_STUDIO_OUTPUT_DIR and VOICE_STUDIO_CACHE_DIR environment variables before starting the server. The backend/main.py entry point reads these during initialization in the Config dataclass from backend/core/config.py. If unset, the system defaults to subdirectories under the user's home folder.

Why does VoiceStudio require path authorization for output directories?

The path authorization layer in backend/core/path_authorization.py prevents directory traversal attacks and arbitrary file writes. By validating output_dir against whitelisted "kinds" like "soni_output_dir" in the router, the system ensures API callers can only write to explicitly approved locations, even if they possess valid credentials.

How does VoiceStudio prevent cache overflow?

The worker implements automatic cache pruning through the _prune_input_cache routine in the task store system. This function monitors the input_dir size and removes the oldest cached files when exceeding byte limits, while protecting partially downloaded files currently under lease by active tasks.

What happens if I provide a relative path for output_dir?

The backend/api/routers/sonitranslate.py router validates that output_dir must be an absolute path. If a relative path is provided, the validation raises a ValueError immediately, preventing the request from reaching the synthesis service. This enforcement ensures predictable file locations and prevents ambiguity in path resolution.

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