# Kabanosk/whisper-website: self-hosted audio to subtitles with Whisper > A small FastAPI app that wraps OpenAI's Whisper for local transcription and subtitle export, run either with Docker Compose or with uv and ffmpeg on the host. It is a good fit if you want .srt files without sending audio to someone else's API, and a poor fit if you need multi-user accounts or long-job queueing. **Kabanosk/whisper-website** — Simple self-hosted web application, which can be used to convert audio to subtitles by OpenAI's Whisper model - Repository: https://github.com/Kabanosk/whisper-website - Stars: 324 · Forks: 74 - Language: Python - License: MIT - Published: 2026-09-15 · Updated: 2026-09-15 · Language: en - Canonical page: https://hysenlabs.com/projects/kabanosk-whisper-website ## What Kabanosk/whisper-website actually does The project is a web front end for OpenAI's Whisper speech recognition model. You upload an audio file, choose a model size, and get back a transcript as .srt, .vtt or plain .txt. The README lists the model range as tiny through large, and notes that plain text export drops timestamps when they are switched off. There is also an optional translation step applied to the transcript, handled by deep_translator according to requirements.txt. The audience is narrow on purpose. It suits someone who already has a machine capable of running Whisper and wants a browser form instead of a command line invocation. The README states the selling point plainly: transcription has no cloud dependency, everything runs on your own hardware. That matters if the audio is a meeting recording, an interview, or anything you would rather not upload. It is not a transcription service, and nothing in the repository suggests it is trying to become one. ## The FastAPI and stable-ts path from upload to .srt The Dockerfile shows the runtime shape. The container is built from python:3.9, ffmpeg is installed through apt, dependencies come from requirements.txt via uv, the src/ directory is copied to /app, and the process starts as uvicorn main:app on host 0.0.0.0 port 80. So the HTTP layer is FastAPI served by uvicorn, and the entry point module is main inside src/. Transcription itself is not raw Whisper. requirements.txt pins stable-ts alongside torch, numpy, tqdm, more-itertools, transformers and ffmpeg-python. stable-ts is the layer that produces the timestamped segments used for the subtitle formats, which is why the same run can emit .srt, .vtt or text depending on what you pick. The srt package at version 3.5.3 handles serialisation of the subtitle file. Translation goes through deep_translator, which is a separate dependency from the Whisper model itself, so a translated transcript is a two-stage operation: recognise, then translate the recognised text. One detail worth flagging: the README says the Docker route caches downloaded Whisper models in a named volume, and docker-compose.yaml confirms it, mounting whisper-models at /root/.cache/whisper. Model weights are large, so this volume is the difference between a slow first run and a slow every run. ## Installing whisper-website with Docker Compose The README calls Docker Compose the recommended route, mainly because it keeps model downloads cached between restarts. Clone the repository and start the stack: ```bash git clone https://github.com/Kabanosk/whisper-website.git cd whisper-website docker compose up -d ``` The compose file maps port 80 to port 80 and sets restart: unless-stopped, so the container comes back after a reboot. Once it is up, open http://127.0.0.1 in a browser. Stopping it is docker compose down, and per the README the cached models stay in the Docker volume, so the next docker compose up will not re-download them. If port 80 is already taken on your machine, that is the line to change in docker-compose.yaml before starting, since the published port is hardcoded there rather than configurable through an environment variable. ## Running whisper-website locally without Docker The second route skips containers. The README requires ffmpeg installed and available on your PATH for this path, because the Docker image is what normally supplies it. Clone, then create a virtual environment and install dependencies with uv: ```bash git clone https://github.com/Kabanosk/whisper-website.git cd whisper-website uv venv uv pip install -r requirements.txt ``` Then run the app from inside src: ```bash cd src uv run run.py ``` The README says the browser opens at http://127.0.0.1:8000 if it does not open automatically, which is a different port from the Docker route. That difference is easy to trip over if you switch between the two: port 80 in the container, port 8000 locally. The first transcription you run will also download the Whisper model you selected, and on the local route that cache lives in your home directory rather than in a Docker volume. ## Where whisper-website is the wrong tool The README documents no authentication, no user accounts and no API keys. The related search terms people use around this project include login and anonymous access, and the repository gives no basis for either: there is no login layer described, and no configuration for restricting who can reach the form. Running it on a host reachable from a network means anyone who can reach the port can upload audio and consume your CPU or GPU. For a laptop on localhost that is fine. On a shared server it is not. There is also no documented queue, worker pool or job persistence. Transcription happens as part of the request path through FastAPI and uvicorn, so a long file occupies the process. Upload several large files at once and you are relying on whatever concurrency uvicorn and the model provide, which the documentation does not describe. If you need background jobs, retries or a status endpoint, this project does not offer them and you would be building that layer yourself. Finally, the translation feature is not the same as Whisper's translate task. It is a separate deep_translator call on the produced transcript, so quality depends on that library and its upstream service, not on the Whisper model. That distinction is not spelled out in the README, and it is worth knowing before you judge output quality. ## How it compares to running the Whisper CLI directly The obvious alternative is the whisper command line from the openai/whisper repository, which this project links to and builds on. The CLI takes a file path and writes output files to a directory; there is no browser, no upload form, and no HTTP server. If your workflow is a shell script over a folder of recordings, the CLI is fewer moving parts and one less service to keep running. The difference in approach is where the work happens. whisper-website puts a FastAPI process in front of the model so a person with a browser can pick a file, choose a size and download a subtitle file, and it adds stable-ts for the timestamp handling plus the srt package for serialisation. The CLI gives you the model and its own output writers. Choose the CLI when the input is already on disk and the caller is a script. Choose this project when the caller is a human who does not want to open a terminal, or when several people on a trusted network need the same form. ## Maintenance, dependencies and the MIT licence The last push to the default branch was on 2026-09-11, and the repository is not archived, so the code is recent. There are no retrieved releases, which means versioning is by commit rather than by tagged artefacts. If you deploy from the main branch, an upgrade is a git pull plus a rebuild of the image, and the practical risk sits in requirements.txt rather than in the application code: fastapi, uvicorn, torch, transformers and stable-ts are all unpinned except for ffmpeg-python==0.2.0 and srt~=3.5.3. A rebuild months from now can pull newer versions of those libraries, and torch in particular changes size and CUDA assumptions between releases. Pinning the file yourself before a production deploy is the cheap insurance here. The licence is MIT. That is permissive: it allows use, modification and redistribution provided the copyright notice and permission notice are kept. It says nothing about the Whisper model weights, which are downloaded separately at runtime and carry their own terms from OpenAI, nor about deep_translator's upstream translation service. If you plan to redistribute a built image or run it commercially, those two are the items to check rather than the MIT text itself. This is a description of what the licence says, not legal advice. ## Conclusion Adopt it if you want a browser form in front of Whisper on your own hardware and your inputs are short audio files. Skip it if you need accounts, job queues or a hosted service, since the README documents none of those. Before committing, check the ffmpeg dependency on the local path, confirm the whisper-models volume survives your deploy method, and decide whether the MIT licence terms fit how you plan to redistribute the image. ## FAQ ### What is Kabanosk/whisper-website? It is a self-hosted web application that converts audio to text and subtitles using OpenAI's Whisper model. You upload a file, pick a model size, and download .srt, .vtt or plain .txt, with optional translation. ### Does whisper-website need an internet connection to transcribe? The README states there is no cloud dependency for transcription and that everything runs on your own machine. The model weights are downloaded once and then cached, in a Docker volume on the Compose route. ### How do I install whisper-website? The README recommends Docker Compose: clone the repository and run docker compose up -d, then open http://127.0.0.1. Without Docker, you create a virtual environment with uv, install requirements.txt, and run uv run run.py from inside src, which serves on port 8000. ### Does whisper-website support login or anonymous access? The README documents no authentication, accounts or access control of any kind. Anyone who can reach the listening port can use the upload form, so exposure should be limited to a trusted network or localhost. ### Which Whisper model sizes can whisper-website use? The README lists transcription with any Whisper model size, from tiny through large. Larger models improve accuracy and take longer, and the first run with a given size downloads its weights. ## Sources - [Issues](https://github.com/Kabanosk/whisper-website/issues) - [Kabanosk/whisper-website on GitHub](https://github.com/Kabanosk/whisper-website) - [License: MIT](https://github.com/Kabanosk/whisper-website/blob/main/LICENSE) - [README](https://github.com/Kabanosk/whisper-website/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kabanosk-whisper-website