Repository navigation
Configuration
Voxtrama reads its settings from four sources. When two sources set the same value, the stronger one wins.
| Order | Source | Where it lives | Written by |
|---|---|---|---|
| 1 | environment variables |
.env next to compose.yaml, passed to every container by make up and docker compose
|
you |
| 2 | voxtrama.toml |
the data folder | the guided setup, the Settings pages, or you by hand |
| 3 | proposal.toml |
the data folder | Voxtrama, as the proposal for this machine |
| 4 | built-in defaults | the code | nobody |
proposal.toml is read only while voxtrama.toml does not exist. It holds the hardware profile and the two core counts proposed for the machine. The first job, or the guided setup, writes voxtrama.toml with the values that were used, and from then on proposal.toml is no longer in force. A voxtrama.toml that cannot be parsed is treated as absent.
A value set in the environment wins over the file. The Settings pages mark such a value from environment, and saving it there has no effect until the variable changes or is removed. After editing .env, restart with make down and make up.
A value that fails validation stops the start-up, and the message names the variable.
Everything Voxtrama keeps lives in one folder. With the compose.yaml shipped in the repository, the folder is ~/Voxtrama unless VOXTRAMA_DATA_DIR says otherwise. Inside the containers the folder is always /data.
~/Voxtrama/
├── recordings/<id>/ # the audio you imported, and the copies made from it
├── runs/<job id>/ # one folder per job: manifest.json, output.json, run.log
├── models/ # downloaded model weights
├── logs/ # created at start-up
├── workflows/ # your custom workflows, created with the first one
├── voxtrama.toml # the installation's settings
├── proposal.toml # the proposal for this machine, until voxtrama.toml exists
└── voxtrama.db # the database
The container's start-up script creates recordings/, runs/, models/ and logs/ when they are missing. Voxtrama does not write into logs/ in this version; each job's log is its run.log.
A recording's folder holds the file you gave, unchanged, and the copies made from it:
| File | What it is |
|---|---|
resampled_16k.wav |
a 16 kHz mono copy, made when the original is not already a 16 kHz mono WAV |
cleaned_16k_v1.wav |
the filtered, levelled copy the transcription reads |
peaks-v3.json |
the levels the player draws its waveform from |
A job's folder holds manifest.json, output.json and run.log. It also holds edits.json once you have corrected a point by hand.
Nothing is kept inside the containers. Taking your data with you says what to copy to another machine.
Every variable is optional and starts with VOXTRAMA_. .env.example lists them commented out. Lists and objects are written as JSON.
| Variable | Default | Range or format | What it does |
|---|---|---|---|
VOXTRAMA_DATA_DIR |
~/Voxtrama |
an absolute path | the data folder on your machine; compose.yaml does not expand ~ in a value you set |
VOXTRAMA_HOST_PORT |
8000 |
a port number | the port on your machine the app answers on; the container always listens on 8000 |
VOXTRAMA_RUN_AS_UID, VOXTRAMA_RUN_AS_GID
|
the owner of the data folder | numeric ids | the user and group Voxtrama writes as, for network mounts and service accounts |
VOXTRAMA_ALLOWED_HOSTS |
["127.0.0.1", "localhost", "::1"] |
JSON list of names | the host names the app answers to; any other gets Forbidden: unknown host.
|
VOXTRAMA_MODELS_DIR |
<data folder>/models |
a path | where model weights are stored |
VOXTRAMA_DATABASE_URL |
sqlite:///<data folder>/voxtrama.db |
a database URL | the database |
VOXTRAMA_QUEUE_URL |
redis://localhost:6379/0 |
a Redis URL | the job queue; compose.yaml sets it to the redis container |
VOXTRAMA_EVAL_DIR |
none | a path | the folder voxtrama calibrate reads; see Command line
|
VOXTRAMA_LOG_LEVEL |
INFO |
a Python log level, for example DEBUG
|
the detail in docker compose logs
|
VOXTRAMA_EXTRA_ROOTS |
none | none | listed in .env.example but not implemented in 0.1; setting it has no effect |
Outside the compose.yaml shipped in the repository, the data folder defaults to ~/Library/Application Support/voxtrama on macOS and ~/.local/share/voxtrama on Linux. VOXTRAMA_HOST_PORT is read by compose.yaml. make up also reads it from .env; when it is not set, make up picks the first free port from 8000 upward and prints the address.
| Variable | Default | Range or format | What it does |
|---|---|---|---|
VOXTRAMA_HARDWARE_PROFILE |
the proposal, else base
|
low, base or high
|
the Whisper model: low is small, base is medium, high is large-v3 |
VOXTRAMA_CORES_PER_CHUNK |
the proposal for this machine | a whole number, at least 1 | the processor cores each chunk of audio uses |
VOXTRAMA_PARALLEL_CHUNKS |
the proposal for this machine | a whole number, at least 1 | how many chunks of audio are transcribed at the same time |
VOXTRAMA_MAX_SPEAKERS |
4 |
a whole number, at least 1 | the most voices speaker diarization tells apart |
VOXTRAMA_MAX_UPLOAD_MB |
8192 |
a whole number, at least 1 | the largest upload the new-job form accepts; the limit applies to the whole request, so several files count together |
A single job can carry its own max_speakers, cores_per_chunk and parallel_chunks in its choices, and they win over the installation's values for that job only. The new-job form has fields for the two core counts and none for max_speakers: no page sets it per job, so the installation's value applies.
| Variable | Default | Range or format | What it does |
|---|---|---|---|
VOXTRAMA_OLLAMA_URL |
none | an http or https address without credentials |
the model server; the guided setup proposes http://host.docker.internal:11434
|
VOXTRAMA_OLLAMA_MODEL |
none | a model name, for example qwen3:4b
|
the summary model |
VOXTRAMA_OLLAMA_AUTH |
none |
user:password or a token |
the credential: Basic with a colon, Bearer otherwise; sent only over https, or to a server on this machine |
VOXTRAMA_PROVIDERS |
none | JSON object of named servers | several model servers; replaces VOXTRAMA_OLLAMA_URL and VOXTRAMA_OLLAMA_AUTH
|
VOXTRAMA_PROVIDER_TIMEOUT_SECONDS |
1800 |
seconds | how long one call to the summary model may take |
VOXTRAMA_PARALLEL_WINDOWS |
2 |
1 to 16 | how many parts of a long transcript go to the model at the same time |
An address that carries a credential, such as https://user:secret@host, is refused at start-up. Summary models and servers explains each variable.
| Variable | Default | Range or format | What it does |
|---|---|---|---|
VOXTRAMA_SUMMARY_DETAIL |
3 |
1 to 5 | the Summary detail level a new job starts with |
VOXTRAMA_PAUSE_MERGE_SECONDS |
1.5 |
0.1 to 10 | the Pause merge a new job starts with; the form's slider covers 0.5 to 5 seconds |
VOXTRAMA_RETENTION_DAYS |
none, so finished jobs are kept | 1 to 36500 | delete finished jobs after this many days |
VOXTRAMA_DEFAULT_LOCALE |
none | a language code | the interface language used when the browser's Accept-Language offers none Voxtrama has; without it, English |
The interface language is chosen in this order: the browser's Accept-Language, then VOXTRAMA_DEFAULT_LOCALE, then English.
compose.yaml sets these for its services. They are listed so you recognise them in the output of docker compose config.
| Variable | Value in compose.yaml
|
What it does |
|---|---|---|
VOXTRAMA_DATA_DIR |
/data |
the data folder inside the container |
VOXTRAMA_HOST_DATA_DIR |
the folder on your machine | lets the setup pages show the folder as you typed it |
VOXTRAMA_QUEUE_URL |
redis://redis:6379/0 |
the queue, in the redis container |
VOXTRAMA_HARDWARE_PROFILE |
empty unless set on the host | passed through, so that all three containers read the same value |
HF_HUB_DISABLE_PROGRESS_BARS |
1 |
keeps download bars out of the worker's log; Voxtrama reports download progress itself |
VOXTRAMA_PROFILE, VOXTRAMA_HOST and VOXTRAMA_PORT exist in the code and are not used by the application in 0.1. Leave them unset.
voxtrama.toml is plain text that you can edit by hand and copy to another machine. Removing it makes the next visit a first start.
| Key | Type | What it holds |
|---|---|---|
hardware_profile |
"low", "base" or "high"
|
the transcription profile |
cores_per_chunk |
whole number, at least 1 | cores per chunk |
parallel_chunks |
whole number, at least 1 | chunks in parallel |
ollama_model |
text | the summary model |
ollama_url |
text | the address of the model server that answered at setup |
retention_days |
whole number, 1 to 36500 | the installation's retention limit |
instance_token |
text | a random token the guided setup generates and keeps when settings are saved; this version does not use it |
[model_context_limits] |
table of model name to number | the context window measured for each model at setup, which Use at most can only lower |
Only the keys that match a setting are read as settings. model_context_limits and instance_token are read by the setup code.
A file with example values:
hardware_profile = "high"
cores_per_chunk = 4
parallel_chunks = 2
ollama_model = "qwen3:4b"
ollama_url = "http://host.docker.internal:11434"
[model_context_limits]
"qwen3:4b" = 8192This wiki is generated from docs/guide in the repository. Changes go through pull requests there.