Repository navigation
Install on macOS
Installing Voxtrama on macOS takes Docker Desktop, a copy of the repository and one command, make up. Voxtrama 0.1 has been tested end to end on macOS with an Intel processor; Apple Silicon has not been tested end to end yet.
Check the Requirements first: memory, disk and the tools make up needs on the host.
-
Open Terminal and run:
make --version python3 --version curl --version git --version
You should see a version line for each command. If macOS offers to install the command line developer tools, accept: they provide
make,python3andgit.
Voxtrama runs in Docker containers, and on macOS Docker Desktop provides them.
-
Install Docker Desktop from docker.com.
-
Start Docker Desktop and wait until it reports that Docker is running.
-
Run:
docker compose version
You should see a Docker Compose version line.
Docker Desktop runs containers inside a Linux virtual machine, and that virtual machine cannot reach the graphics chip of the Mac. Voxtrama therefore transcribes on the processor, whatever Mac you have, and its image is built for the processor only. A summary model is different: Ollama runs on the host, outside Docker, and can use the graphics chip of an Apple Silicon Mac. See Set up the summary model.
Docker Desktop gives the virtual machine a fixed share of the Mac's memory and cores, and Voxtrama sees only that share. Voxtrama reads the memory and cores visible inside the container, so voxtrama doctor and the guided setup propose a profile for the Docker Desktop allocation, not for the whole Mac.
-
In Docker Desktop, open Settings, then Resources.
-
Raise Memory to what the profile you want needs: about 8 GB or less for Low, between 8 GB and 32 GB for Base, 32 GB or more for High. See Requirements.
-
Raise CPUs to the number of cores you want Voxtrama to use.
-
Press Apply & restart.
You should see Docker Desktop restart. Restart Voxtrama afterwards with
make downandmake up.
The labels and defaults of the Resources page change between Docker Desktop versions: see the Docker Desktop documentation for the current ones.
-
Clone the repository:
git clone https://github.com/sjpagan/voxtrama.git voxtrama cd voxtrama -
Copy the example settings file:
cp .env.example .env
Nothing in
.envneeds editing before the first start. The variables you may want later are in Configuration.
-
Run:
make up
You should see four stages:
=== 1. host port ===,=== 2. docker compose up ===,=== 3. waiting for web to answer ===and=== 4. ready ===, followed by an address such ashttp://127.0.0.1:8000. The first run builds the image, so it takes longer than the next ones. -
Open that address in your browser.
You should see the guided setup, on the Local processing step. See First start.
make up runs scripts/up.sh, which:
- uses the port in
VOXTRAMA_HOST_PORTif it is set in the shell or in.env, and otherwise takes the first free port starting from 8000; - runs
docker compose up -d, which starts the queue, then the database step, then the web server and the worker; - polls
http://127.0.0.1:<port>/healthevery 2 seconds, for up to 180 seconds, and stops with a message if thewebcontainer is not running or does not answer in time; - prints the address and how to follow the logs (
docker compose logs -f) and stop Voxtrama (make down).
Voxtrama publishes its port on 127.0.0.1 only, so no other machine can reach it. The web server answers only to the host names 127.0.0.1, localhost and ::1. To open Voxtrama through another name, for example behind your own proxy, add it to VOXTRAMA_ALLOWED_HOSTS in .env; see Configuration.
docker compose up -d starts the same containers. It publishes VOXTRAMA_HOST_PORT if it is set in .env, and port 8000 otherwise. It does not look for a free port and does not wait for the web server: if port 8000 is taken, it fails with a port error.
docker compose up -dVoxtrama keeps everything in one data folder, ~/Voxtrama by default: recordings, results, downloaded models, the database and the settings file. Nothing is kept inside the containers, so stopping or rebuilding them loses nothing.
To use another folder, set an absolute path in .env before the first start. Compose does not expand ~.
VOXTRAMA_DATA_DIR=/Users/yourname/voxtrama-dataAt start-up, Voxtrama takes on the owner of the data folder, so every file it writes there is yours to open, copy or delete without sudo. If the folder does not exist yet, Docker creates it, and Voxtrama then claims it. If the folder belongs to root and already contains files, the container refuses to start with a message that says the folder "belongs to root and is not empty": choose another folder, or set VOXTRAMA_RUN_AS_UID and VOXTRAMA_RUN_AS_GID. See Configuration for the layout of the folder.
On Docker Desktop, the folder you choose must be one Docker Desktop is allowed to share. Docker Desktop's file sharing settings decide which folders those are: see the Docker Desktop documentation if Docker reports that the folder cannot be mounted.
Voxtrama works for transcription as it is. Recaps need a summary model: see Set up the summary model.
This wiki is generated from docs/guide in the repository. Changes go through pull requests there.