# VoiceStudio Configuration: How Output and Cache Directories Are Managed

> Discover how VoiceStudio manages output and cache directories through environment variables, path authorization, and automatic pruning for efficient configuration and security.

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

---

**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`](https://github.com/debpalash/VoiceStudio/blob/main/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`](https://github.com/debpalash/VoiceStudio/blob/main/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.

```python

# 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`](https://github.com/debpalash/VoiceStudio/blob/main/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`](https://github.com/debpalash/VoiceStudio/blob/main/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.

```python

# 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`](https://github.com/debpalash/VoiceStudio/blob/main/backend/worker/task_store.py) and [`backend/worker/executor.py`](https://github.com/debpalash/VoiceStudio/blob/main/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.

```python

# 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`](https://github.com/debpalash/VoiceStudio/blob/main/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`](https://github.com/debpalash/VoiceStudio/blob/main/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`](https://github.com/debpalash/VoiceStudio/blob/main/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`](https://github.com/debpalash/VoiceStudio/blob/main/backend/core/path_authorization.py) and [`backend/api/routers/sonitranslate.py`](https://github.com/debpalash/VoiceStudio/blob/main/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`](https://github.com/debpalash/VoiceStudio/blob/main/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`](https://github.com/debpalash/VoiceStudio/blob/main/backend/services/sonitranslate.py) using path expansion and authorization checks confirmed by the test suite in [`tests/test_mcp_output_mode.py`](https://github.com/debpalash/VoiceStudio/blob/main/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`](https://github.com/debpalash/VoiceStudio/blob/main/backend/main.py) entry point reads these during initialization in the `Config` dataclass from [`backend/core/config.py`](https://github.com/debpalash/VoiceStudio/blob/main/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`](https://github.com/debpalash/VoiceStudio/blob/main/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`](https://github.com/debpalash/VoiceStudio/blob/main/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.