Kabanosk/whisper-website: self-hosted Whisper transcription, reviewed

What Kabanosk/whisper-website actually does

This is a thin web layer over OpenAI's Whisper. You upload an audio file, choose a model size, and get back the transcript as .srt, .vtt, or plain .txt. The README lists transcription with any Whisper model size from tiny to large, optional timestamps, optional translation, and no cloud dependency for transcription. The intended user is someone who already knows Whisper from the command line and wants a browser form instead of a shell invocation, or who wants a small internal tool on a machine they own. It is not a service. There is no account system in the repository layout, no database, and no persistence layer beyond the model cache volume. Anyone expecting a multi-user deployment will be disappointed, because the app appears to be a single-process FastAPI application that processes one upload at a time. That is fine for a personal or small-team tool and wrong for anything with a queue.

How the FastAPI app and Whisper fit together

The Dockerfile tells most of the story. It starts from python:3.9, installs ffmpeg via apt, copies requirements.txt, installs uv, then runs uv pip install --system -r requirements.txt, copies src/ into /app, and starts uvicorn main:app on 0.0.0.0 port 80. So the runtime is uvicorn serving a FastAPI app defined in src/main.py, with Jinja2 templates for the upload page and python-multipart handling the file upload. The actual transcription work goes through stable-ts, which wraps Whisper and is what produces timestamped segments suitable for subtitle output. ffmpeg-python is in the dependency list because Whisper needs decoded audio, and the srt package handles .srt serialisation. Translation is delegated to deep_translator, which is the one part of the pipeline that may reach the network. The docker-compose.yaml mounts a named volume, whisper-models, at /root/.cache/whisper, which is where Whisper stores downloaded model weights. That volume is the difference between a first run that downloads a model and every subsequent run that does not.

Installing whisper-website with Docker Compose

The README calls Docker Compose the recommended route, and the compose file is short enough to read in full. It builds from the local Dockerfile, publishes port 80, mounts the model cache volume, sets PYTHONUNBUFFERED=1, and uses restart: unless-stopped. Clone and start it:

git clone https://github.com/Kabanosk/whisper-website.git
cd whisper-website
docker compose up -d

After that, open http://127.0.0.1 in a browser. The first transcription will be slow because Whisper has to download the model weights into the volume; later runs reuse them. Stopping the stack with docker compose down leaves the volume in place, so the next up does not re-download. If you already run something on port 80 on that host, the compose file as written will conflict, and you will need to change the published port before starting.

Running it locally with uv and ffmpeg on PATH

The non-Docker route assumes you have ffmpeg installed and available on your PATH. The README points at the ffmpeg download page for that, and notes the Docker image already includes it. The rest uses uv:

git clone https://github.com/Kabanosk/whisper-website.git
cd whisper-website
uv venv
uv pip install -r requirements.txt
cd src
uv run run.py

The app should come up on http://127.0.0.1:8000, and the README says it may open automatically. Note the port difference from the Docker route: 8000 locally, 80 in the container. The requirements.txt pulls torch and transformers, so the install is heavy and the first uv pip install will take a while. If you skip the ffmpeg step, transcription will fail at the decoding stage rather than at upload, which is a confusing place to discover a missing binary.

Constraints the README does not resolve

Several things a deployer would want to know are simply not documented. There is no mention of upload size limits, so it is unclear what happens when someone posts a two-hour recording. There is no discussion of concurrency: the compose file runs a single uvicorn worker with no --workers flag, so requests are handled by one process, and a long transcription will block the next upload. There is no documented queue, job store, or progress endpoint, which means a browser refresh during a long job probably loses your place. There is no authentication of any kind, so exposing this beyond localhost puts an open transcription endpoint on the network. And there is no rollback or migration story, because there is no database and no schema. The one operational lever the repository does expose is the model size: tiny through large. Larger models are more accurate and much slower, and the README does not give guidance on which to pick for a given machine. That is a decision you make blind, or by reading src/main.py.

Where the local-only claim stops being true

The README says there is no cloud dependency for transcription, and for the Whisper step that is accurate: the model runs on your machine, and the weights land in the whisper-models volume. But translation is listed as a feature, and the dependency list includes deep_translator. Translation therefore goes out to a translation service, not through Whisper's own translate task. If your audio is sensitive and you enable translation, the transcript text leaves the host. The README does not flag this distinction, and it is the kind of thing that matters to exactly the people who choose self-hosting in the first place. If you only need transcription, leave translation off and the pipeline stays local. If you need translated subtitles, treat that step as a network operation and decide accordingly.

Compared with running Whisper directly

The obvious alternative is the openai/whisper CLI itself, or stable-ts on the command line, which is what this project already depends on underneath. The difference is real but narrow: the CLI gives you scriptable, batchable transcription with no server process, no port, and no browser, and it is the right tool for a pipeline that processes a directory of files on a schedule. This project gives you a form, a model dropdown, and a download button, which is better when the person doing the transcription is not comfortable in a shell. The trade is that you take on a long-running process, a port binding, and an ffmpeg dependency on the host. If your workflow is already scripted, the web layer adds surface area without adding capability. If your workflow is a colleague dropping an interview recording into a browser, the CLI is the wrong shape entirely.

Editorial conclusion

Adopt it if you need a local Whisper Web UI on a machine you control and you are comfortable reading the source when the README stops short, particularly around concurrency and model choice. Do not adopt it if you need a hosted service, user accounts, or a queue that survives restarts; nothing in the repository suggests any of those exist. Before committing, verify that ffmpeg is on PATH on the host, decide which Whisper model size your hardware can actually run, and confirm whether the translation step's outbound call to deep_translator is acceptable under your data policy, because the transcription itself stays local but that step does not.

Frequently asked questions

Official sources

1. Issues
2. Kabanosk/whisper-website on GitHub
3. License: MIT
4. README