pluja/whishper: a self-hosted Whisper transcription suite with a subtitle editor

What Whishper is for, and who ends up running it

The README describes Whishper as an "open-source, 100% local audio transcription and subtitling suite with a full-featured web UI". The intended user is someone who has media files or URLs and needs text or subtitle files out of them without sending audio to a third party. That covers journalists working with sensitive recordings, video editors who need SRT or VTT files, and anyone transcribing material they are not allowed to upload.

The feature list is deliberately broad: transcription from a URL through yt-dlp, file upload, export to TXT, JSON, VTT or SRT, translation through LibreTranslate, and an in-browser subtitle editor with CPS (characters per second) warnings, segment splitting and segment insertion. The editor is the part that separates Whishper from a plain transcription script. You can fix timings and split long cues without exporting to another tool.

It is not aimed at people who want a hosted service or a one-line CLI. The README points to a self-host guide and a quick start script, and the repository ships a Dockerfile, a Dockerfile.gpu, four compose files and a get-whishper.sh script. Running it means operating a small stack.

The four moving parts behind the web UI

Whishper is not one program. The README lists the pieces explicitly: a Transcription-API in the transcription-api folder that runs Faster-Whisper, a backend in the backend folder that coordinates frontend calls, the database and tasks, a frontend in the frontend folder, plus LibreTranslate, MongoDB and nginx as third-party containers.

The root Dockerfile shows how those pieces are assembled into one image. A Go stage builds the backend binary, a Node stage runs pnpm install and pnpm run build for the SvelteKit frontend, and a python:3.11-slim base installs ffmpeg, curl, nodejs, nginx and supervisor. The transcription API is installed from transcription-api/requirements.txt. Nginx and supervisor then run inside the same container, which is why the compose service exposes a single port.

In docker-compose.yml the whishper service publishes 8082:80 and depends on mongo and translate. It sets PUBLIC_INTERNAL_API_HOST to http://127.0.0.1:80, points WHISPER_MODELS_DIR at /app/models and UPLOAD_DIR at /app/uploads, and fixes CPU_THREADS at 4. The mongo service keeps data under ./whishper_data/db_data, and the translate container disables its own web UI with LT_DISABLE_WEB_UI and exposes port 5000 internally. That layout explains the practical cost: three containers, one bind-mounted data directory, and a translation service that downloads its own language models on first start.

Installing Whishper with Docker Compose and running a first transcription

The README offers two routes: a quick start script (get-whishper.sh, with a .bat equivalent for Windows) or manual steps, and it links the self host guide at whishper-docs.pages.dev/guides/install. The compose file expects a .env file next to it, and the repository ships example.env as the starting point.

Create the environment file from the example before the first start. The compose file reads DB_USER and DB_PASS for MongoDB, defaulting to whishper for both, and WHISHPER_VERSION for the image tag, defaulting to latest.

cp example.env .env

Bring the stack up. The first run pulls pluja/whishper and the LibreTranslate image, and LibreTranslate downloads its models, so expect a long wait before the translation feature responds.

docker compose up -d
docker compose logs -f whishper

Open http://localhost:8082, which is the host side of the 8082:80 mapping in docker-compose.yml. The README documents two input paths in the UI: paste a URL that yt-dlp supports, or upload a file. After the job finishes you can download TXT, JSON, VTT or SRT, or open the subtitle editor. For GPU transcription, the repository provides docker-compose.gpu.yml and Dockerfile.gpu, which target NVIDIA hardware; the README lists non-NVIDIA GPU support as an open roadmap item.

The main branch is frozen, and the README says so

The banner at the top of the README states that a complete rewrite is in progress on the v4 branch and that "this branch will not receive any new releases or updates". The most recent release listed in the repository is v3.1.4 from 2024-09-17, with v3.1.3 in January 2024 and v3.1.2 before that. The last push to the repository was on 2026-07-31, but that activity does not translate into releases on main.

This matters for adoption decisions. If you pick up Whishper today you are installing a codebase whose maintainer has publicly stopped shipping updates to it. Bug reports against main may not be addressed. The v4 branch is the place where work continues, and the README does not describe its status, its compatibility, or whether it can be deployed.

There are smaller gaps too. The README roadmap lists local folder as media input, full-text search across transcriptions, user authentication, and browser audio recording as unfinished. The compose file publishes the UI on port 8082 with no authentication in front of it, so exposing it beyond localhost is a decision you make knowingly, not something the project handles for you.

Translation quality depends on a second container you also operate

Translation is not done by Whisper. The README credits LibreTranslate, and the compose file runs it as the whisper-libretranslate container with LT_DISABLE_WEB_UI set and a healthcheck that runs scripts/healthcheck.py every 2 seconds. Its data and cache live under ./whishper_data/libretranslate.

Two consequences follow. First, translation quality is LibreTranslate quality, which varies by language pair and is unrelated to how well Whisper transcribed the audio. Second, the translation container is a separate failure domain. If it has not finished downloading models, or the healthcheck never passes, transcription still works but the translate step does not. The README does not describe rollback or retry behaviour for a failed translation job.

Whishper also lets you leave translation out. The whishper service sets PUBLIC_TRANSLATION_API_HOST to an empty string in the shipped compose file, and the README frames translation as a feature of the suite rather than a requirement. If you only need transcription and subtitle editing, the LibreTranslate container is the piece you can drop from your deployment.

How Whishper differs from running faster-whisper directly

The obvious alternative is the faster-whisper library itself, which Whishper uses as its transcription backend. Running it directly means a Python environment, a model download, and a command invocation per file. You get transcription text and timestamps, and nothing else. There is no queue, no database, no editor, and no translation step unless you add one.

Whishper trades that minimalism for a service. MongoDB stores transcription records, the Go backend manages tasks, and the SvelteKit frontend gives you a subtitle editor with CPS warnings and segment splitting. The cost is the stack: three containers, a bind-mounted data directory, an nginx proxy, and a supervisor process tree inside one image. You also inherit the AGPL-3.0 obligations of the whole suite rather than a permissive library licence.

A second comparison point is the roadmap entry for insanely-fast-whisper as an optional backend. The README lists it as unchecked, so today the backend is Faster-Whisper. If raw throughput on a single file is your only concern, the library route is simpler and avoids the containers entirely. Whishper earns its complexity when you need the editing and export workflow around the transcription.

Licence and the cost of staying on this branch

Whishper is licensed AGPL-3.0. That is a copyleft licence with a network clause: if you modify the software and let users interact with it over a network, the licence requires you to offer them the corresponding source. For internal use inside an organisation this is usually unremarkable. For anyone planning to build a hosted transcription product on top of Whishper, it changes the calculus, and the project's own README does not discuss the implications. This is a description of the licence text, not legal advice; read the LICENSE file and talk to a lawyer if you plan to redistribute or host it.

Upgrade cost is the more immediate concern. The README states that main will not receive new releases, and the newest release is v3.1.4 from 2024-09-17. There is no documented migration path from v3 to v4, no compatibility statement, and no deprecation notes in the repository. Anyone adopting now should treat the deployment as a fixed version: pin WHISHPER_VERSION to a specific tag rather than latest, so a future image push does not change behaviour underneath you. The compose file defaults to latest, which is the opposite of what a frozen branch suggests you should do.

Editorial conclusion

Adopt Whishper if you need subtitles produced and edited on hardware you control, you are comfortable running Docker Compose, and you can accept a frozen main branch. Skip it if you need authentication, browser recording or a maintained release line, because the README states this branch will not receive new releases. Before committing, deploy the stack, confirm the LibreTranslate container finishes downloading its models, and check whether the v4 branch already covers the features you need.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. pluja/whishper on GitHub
3. Project website
4. README
5. Releases