hwdsl2/whisper-server repository overview

⁠ScribeCrate

Open-source, self-hosted transcription API.

GitHub: https://github.com/hwdsl2/scribecrate⁠

ScribeCrate is a self-hosted speech-to-text API for transcribing audio, generating subtitles, and translating speech into English. It provides OpenAI-compatible transcription and translation endpoints using Whisper⁠ models, powered by faster-whisper⁠. Deploy with Docker on CPU or an NVIDIA GPU.

Features:

• OpenAI-compatible API: POST /v1/audio/transcriptions and POST /v1/audio/translations endpoints for integration with clients that support the OpenAI Whisper API.
• Private, local processing: audio stays on your server and is not sent to third parties for transcription.
• Speaker diarization: identify who is speaking in each segment with the optional local sherpa-onnx⁠ extension.
• Streaming results: add stream=true to receive transcription segments via Server-Sent Events as they are decoded, without waiting for the entire uploaded file to finish processing.
• Whisper model support: choose from tiny, base, small, medium, large-v3, large-v3-turbo, and more.
• CPU and GPU support: run on CPU or accelerate inference with an NVIDIA GPU using the :cuda image.
• Broad audio format support: MP3, M4A, WAV, WebM, OGG, FLAC, and other audio formats supported by FFmpeg.
• Flexible output: JSON, plain text, verbose JSON, SRT subtitles, and WebVTT subtitles.
• Offline operation: run without internet access using pre-cached models and WHISPER_LOCAL_ONLY.
• Automated builds: images are automatically built and published through GitHub Actions⁠, with publicly accessible build workflows.

Also available as part of the Self-Hosted AI Stack⁠, which deploys a complete self-hosted AI stack with a single command.

Also available:

• Try it online: Open in Colab⁠ — no Docker or installation required
• Related AI services: ScribeCrate Live⁠, SpeakCrate⁠, Embeddings⁠, LiteLLM⁠, Ollama⁠, ParseCrate⁠, MCP Gateway⁠

⁠Quick start

Use this command to start ScribeCrate:

docker run \
    --name whisper \
    --restart=always \
    -v whisper-data:/var/lib/whisper \
    -p 9000:9000 \
    -d hwdsl2/whisper-server

docker run \
    --name whisper \
    --restart=always \
    --gpus=all \
    -v whisper-data:/var/lib/whisper \
    -p 9000:9000 \
    -d hwdsl2/whisper-server:cuda

Important: This image requires at least 700 MB of available RAM for the default base model. Systems with 512 MB or less of RAM are not supported.

Note: For internet-facing deployments, use a reverse proxy⁠ to add HTTPS. Also replace -p 9000:9000 with -p 127.0.0.1:9000:9000 in the docker run command above, to prevent direct access to the unencrypted port.

The Whisper base model (~145 MB) is downloaded and cached on first start. Check the logs to confirm the server is ready:

docker logs whisper

Once you see "ScribeCrate transcription server is ready", retrieve the API key generated for a fresh install with the persistent volume shown above:

scribecrate_api_key="$(docker exec whisper whisper_manage --getkey)"

Transcribe your first audio file, replacing your_server_ip with your server address and audio.mp3 with your audio file:

curl http://your_server_ip:9000/v1/audio/transcriptions \
    -H "Authorization: Bearer $scribecrate_api_key" \
    -F [email protected] \
    -F model=whisper-1

Response:

{"text": "Your transcribed text appears here."}

Tip: Need a sample audio file to test? Download this English speech sample (WAV, MIT License) from the Azure Samples⁠ repository:

curl -L -o sample_speech.wav \
    "https://github.com/Azure-Samples/cognitive-services-speech-sdk/raw/master/sampledata/audiofiles/katiesteve.wav"

curl http://your_server_ip:9000/v1/audio/transcriptions \
    -H "Authorization: Bearer $scribecrate_api_key" \
    -F file=@sample_speech.wav \
    -F model=whisper-1

Alternatively, you may set up Whisper without Docker⁠. To learn more about how to use this image, read the sections below.

⁠ScribeCrate vs. ScribeCrate Live

ScribeCrate Live is a separately deployed server powered by WhisperLive⁠.

⁠Community

• 📬 Get project updates and free deployment guides⁠ (1–2 emails/month)
• 💬 Join the r/selfhostedstack⁠ community for discussions and showcases
• ⭐ Star the repository if you find it useful — it helps others discover it

⁠Requirements

• A Linux server (local or cloud) with Docker installed
• Supported architectures: amd64 (x86_64), arm64 (e.g. Raspberry Pi 4/5, AWS Graviton)
• Minimum RAM: ~700 MB free for the default base model (see model table⁠)
• Internet access for the initial model download (the model is cached locally afterwards). Not required if using WHISPER_LOCAL_ONLY=true with pre-cached models.

For GPU acceleration (:cuda image):

• NVIDIA GPU with CUDA support (Compute Capability 6.0+)
• NVIDIA driver⁠ 575.57.08+ (Linux) or 576.57+ (Windows) installed on the host
• NVIDIA Container Toolkit⁠ installed
• The :cuda image supports linux/amd64 only

For internet-facing deployments, see Using a reverse proxy⁠ to add HTTPS.

⁠Download

Get the trusted build from the Docker Hub registry⁠:

docker pull hwdsl2/whisper-server

For NVIDIA GPU acceleration, pull the :cuda tag instead:

docker pull hwdsl2/whisper-server:cuda

Alternatively, you may download from Quay.io⁠:

docker pull quay.io/hwdsl2/whisper-server
docker image tag quay.io/hwdsl2/whisper-server hwdsl2/whisper-server

CPU images support linux/amd64 and linux/arm64. The :cuda tag supports linux/amd64 only.

⁠Environment variables

All variables are optional. Fresh installs with a mounted /var/lib/whisper volume auto-generate a Bearer token. Existing installs without a key remain open for backward compatibility.

This Docker image uses the following variables, that can be declared in an env file (see example⁠):

Note: In your env file, you may enclose values in single quotes, e.g. VAR='value'. Do not add spaces around =. If you change WHISPER_PORT, update the -p flag in the docker run command accordingly.

Example using an env file:

cp whisper.env.example whisper.env
# Edit whisper.env with your settings, then:
docker run \
    --name whisper \
    --restart=always \
    -v whisper-data:/var/lib/whisper \
    -v ./whisper.env:/whisper.env:ro \
    -p 9000:9000 \
    -d hwdsl2/whisper-server

The env file is bind-mounted into the container, so changes are picked up on every restart without recreating the container.

docker run \
    --name whisper \
    --restart=always \
    -v whisper-data:/var/lib/whisper \
    -p 9000:9000 \
    --env-file=whisper.env \
    -d hwdsl2/whisper-server

⁠Using docker-compose

cp whisper.env.example whisper.env
# Edit whisper.env as needed, then:
docker compose up -d
docker logs whisper

Example docker-compose.yml (already included):

services:
  whisper:
    image: hwdsl2/whisper-server
    container_name: whisper
    restart: always
    ports:
      - "9000:9000/tcp"  # For a host-based reverse proxy, change to "127.0.0.1:9000:9000/tcp"
    volumes:
      - whisper-data:/var/lib/whisper
      - ./whisper.env:/whisper.env:ro

volumes:
  whisper-data:
    name: whisper-data

Note: For internet-facing deployments, use a reverse proxy⁠ to add HTTPS. Also change "9000:9000/tcp" to "127.0.0.1:9000:9000/tcp" in docker-compose.yml, to prevent direct access to the unencrypted port.

cp whisper.env.example whisper.env
# Edit whisper.env as needed, then:
docker compose -f docker-compose.cuda.yml up -d
docker logs whisper

services:
  whisper:
    image: hwdsl2/whisper-server:cuda
    container_name: whisper
    restart: always
    ports:
      - "9000:9000/tcp"  # For a host-based reverse proxy, change to "127.0.0.1:9000:9000/tcp"
    volumes:
      - whisper-data:/var/lib/whisper
      - ./whisper.env:/whisper.env:ro
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

volumes:
  whisper-data:
    name: whisper-data

⁠API reference

ScribeCrate provides endpoints compatible with OpenAI's audio transcription⁠ and audio translation⁠ interfaces. For clients using the OpenAI SDK, configure the base URL and use your ScribeCrate API key:

Authentication: Fresh persistent installs require an API key. Retrieve it for the SDK configuration and curl examples below:

scribecrate_api_key="$(docker exec whisper whisper_manage --getkey)"

export OPENAI_BASE_URL="http://your_server_ip:9000/v1"
export OPENAI_API_KEY="$scribecrate_api_key"

If API key authentication is disabled, omit the Authorization header in curl examples. OpenAI SDK clients still require a nonempty key; set OPENAI_API_KEY=unused.

Speaker diarization, when enabled, is a local sherpa-onnx extension and is not equivalent to OpenAI diarization models. OpenAI-only transcription options such as gpt-4o-transcribe-diarize, response_format=diarized_json, include=logprobs, chunking_strategy, known_speaker_names, and known_speaker_references are not supported and return 400.

⁠Transcribe audio

POST /v1/audio/transcriptions
Content-Type: multipart/form-data

Parameters:

Local faster-whisper extension: You can set beam to override WHISPER_BEAM for a single transcription or translation request. This is not part of the OpenAI API schema, so do not send it to the hosted OpenAI API or strict OpenAI-compatible gateways. The default per-request cap is 10 (WHISPER_MAX_REQUEST_BEAM); set that variable to 0 to disable the cap. Beam search mainly affects deterministic decoding when temperature=0.

Example:

curl http://your_server_ip:9000/v1/audio/transcriptions \
    -H "Authorization: Bearer $scribecrate_api_key" \
    -F [email protected] \
    -F model=whisper-1 \
    -F language=en

With API key authentication:

curl http://your_server_ip:9000/v1/audio/transcriptions \
    -H "Authorization: Bearer your_api_key" \
    -F [email protected] \
    -F model=whisper-1

⁠Response formats

See Response formats⁠ for more details.

⁠Translate audio

POST /v1/audio/translations
Content-Type: multipart/form-data

Translates audio in any language to English text. Compatible with OpenAI's audio translation endpoint⁠. Accepts the common translation parameters. The output is always in English.

Example:

curl http://your_server_ip:9000/v1/audio/translations \
    -H "Authorization: Bearer $scribecrate_api_key" \
    -F file=@french_audio.mp3 \
    -F model=whisper-1

⁠List models

GET /v1/models

Returns the active model in OpenAI-compatible format.

curl http://your_server_ip:9000/v1/models -H "Authorization: Bearer $scribecrate_api_key"

⁠Interactive API docs

An interactive Swagger UI is available at:

http://your_server_ip:9000/docs

⁠Persistent data

All server data is stored in the Docker volume (/var/lib/whisper inside the container):

/var/lib/whisper/
├── models--Systran--faster-whisper-*/   # Cached Whisper model files (downloaded from HuggingFace)
├── .port                 # Active port (used by whisper_manage)
├── .model                # Active model name (used by whisper_manage)
└── .server_addr          # Cached server IP (used by whisper_manage)

Back up the Docker volume to preserve downloaded models. Models are large (145 MB – 3 GB) and can take several minutes to download on first start; preserving the volume avoids re-downloading on container recreation.

Tip: The /var/lib/whisper volume uses the same HuggingFace cache layout as docker-whisper-live's /var/lib/whisper-live volume. If you have already downloaded a model with docker-whisper-live, you can bind-mount the same volume directory to avoid re-downloading.

⁠Managing the server

Use whisper_manage inside the running container to inspect and manage the server.

Show server info:

docker exec whisper whisper_manage --showinfo

List available models:

docker exec whisper whisper_manage --listmodels

Pre-download a model:

docker exec whisper whisper_manage --downloadmodel large-v3-turbo

⁠Switching models

See Switching models⁠.

⁠Securing your server

See Securing your server⁠.

⁠Using a reverse proxy

For internet-facing deployments, place a reverse proxy in front of ScribeCrate to handle HTTPS termination. The server works without HTTPS on a local or trusted network, but HTTPS is recommended when the API endpoint is exposed to the internet.

Use one of the following addresses to reach the ScribeCrate container from your reverse proxy:

• whisper:9000 — if your reverse proxy runs as a container in the same Docker network as ScribeCrate (e.g. defined in the same docker-compose.yml).
• 127.0.0.1:9000 — if your reverse proxy runs on the host and port 9000 is published (the default docker-compose.yml publishes it).

Example with Caddy⁠ (Docker image⁠) (automatic TLS via Let's Encrypt, reverse proxy in the same Docker network):

Caddyfile:

whisper.example.com {
  reverse_proxy whisper:9000
}

Example with nginx (reverse proxy on the host):

See Using a reverse proxy⁠.

Fresh persistent installs auto-generate a WHISPER_API_KEY. Display it with docker exec whisper whisper_manage --showkey, or use docker exec whisper whisper_manage --getkey in scripts. For existing installs without a key, set WHISPER_API_KEY in your env file to enable authentication.

⁠Update Docker image

See Update Docker image⁠.

⁠Using with other AI services

See Using with other AI services⁠.

⁠Speaker diarization

Speaker diarization identifies who is speaking in each transcribed segment. It is a local extension powered by sherpa-onnx.

See Speaker diarization⁠ for setup, examples, output formats, and notes.

⁠Usage counts

See Usage counts⁠.

⁠Technical details

See Technical details⁠.

⁠License

Note: The software components inside the pre-built image (such as faster-whisper and its dependencies) are under the licenses chosen by their copyright holders. As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

Copyright (C) 2026 Lin Song
This work is licensed under the MIT License⁠.

faster-whisper is Copyright (C) SYSTRAN, and is distributed under the MIT License⁠.

ScribeCrate is an independent server using Whisper models and is not affiliated with, endorsed by, or sponsored by OpenAI or SYSTRAN.