ScribeCrate

Open-source, self-hosted transcription API.

Transcribe audio, generate subtitles, and translate speech into English on your own hardware. ScribeCrate provides OpenAI-compatible transcription and translation endpoints using Whisper models, powered by faster-whisper. Deploy with Docker on CPU or an NVIDIA GPU.

Previously known as docker-whisper, maintained by hwdsl2. The Docker image remains hwdsl2/whisper-server; existing configuration, API endpoints, and persistent data remain compatible.

Features

OpenAI-compatible API: POST /v1/audio/transcriptions and POST /v1/audio/translations endpoints for integration with clients that support the OpenAI Whisper API.
Whisper model support: choose from tiny, base, small, medium, large-v3, large-v3-turbo, and more.
Speaker diarization: identify who is speaking in each segment with the optional local sherpa-onnx extension.
Model management: inspect server settings and pre-download models with whisper_manage; switch models using WHISPER_MODEL.
Local audio processing: audio stays on your server and is not sent to third parties for transcription.
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.
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.
GPU acceleration: use the :cuda image for faster inference with an NVIDIA GPU. The CUDA image supports linux/amd64.
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.
Persistent model cache: reuse downloaded models across container updates with a Docker volume.
Multiple architectures: CPU images support linux/amd64 and linux/arm64.

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

📘 The Self-Hosted AI Builder’s Guide is a practical guide to building, securing, and operating your own private AI stack.

Also available:

Try it online: Open in Colab — no Docker or installation required
Related AI services: WhisperLive, Kokoro, Embeddings, LiteLLM, Ollama, Docling, 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

GPU quick start (NVIDIA CUDA)

If you have an NVIDIA GPU, use the :cuda image for hardware-accelerated inference:

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

Requirements: NVIDIA GPU, NVIDIA driver 575.57.08+ (Linux) or 576.57+ (Windows), and the NVIDIA Container Toolkit installed on the host. The :cuda image is linux/amd64 only.

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 file=@audio.mp3 \
    -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. WhisperLive

	ScribeCrate	WhisperLive
Use case	Transcribe complete audio files	Live microphone / real-time audio streaming
Protocol	HTTP REST	WebSocket (streaming) + HTTP REST
Latency	JSON after processing; segments via SSE	Near-real-time, word by word
Best for	Meeting recordings, uploaded audio	Browser capture, RTSP streams, live captions
Image size	~190 MB (~3.1 GB for `:cuda`)	~750 MB (~4.5 GB for `:cuda`)

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

Self-hosted VPN & networking projects

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

Supported platforms: 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):

Variable	Description	Default
`WHISPER_MODEL`	Whisper model to use. See model table for options.	`base`
`WHISPER_LANGUAGE`	Default transcription language. BCP-47 code (e.g. `en`, `fr`, `de`, `zh`, `ja`) or `auto` to autodetect.	`auto`
`WHISPER_PORT`	HTTP port for the API (1–65535).	`9000`
`WHISPER_DEVICE`	Compute device: `cpu`, `cuda`, or `auto`. Use `cuda` with the `:cuda` image for GPU acceleration. `auto` detects GPU and falls back to CPU.	`cpu`
`WHISPER_COMPUTE_TYPE`	Quantization / compute type. `int8` is recommended for CPU; `float16` is recommended for CUDA.	`int8` (CPU) / `float16` (CUDA)
`WHISPER_THREADS`	CPU threads for inference. Set to the number of physical cores for best latency.	`2`
`WHISPER_API_KEY`	Optional Bearer token. Fresh persistent installs auto-generate one. If set, all API requests must include `Authorization: Bearer <key>`. Set explicitly empty to disable authentication.	Auto-generated for fresh persistent installs
`WHISPER_LOG_LEVEL`	Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.	`INFO`
`WHISPER_BEAM`	Beam size for transcription and translation decoding. Higher values may improve accuracy at the cost of speed. Use `1` for fastest (greedy) decoding.	`5`
`WHISPER_MAX_REQUEST_BEAM`	Maximum beam size allowed for the per-request `beam` override. Set to `0` to disable this limit.	`10`
`WHISPER_MAX_UPLOAD_MB`	Maximum uploaded audio file size in MB. Requests above this limit return HTTP 413. Set to `0` to disable the limit.	`1024`
`WHISPER_LOCAL_ONLY`	When set to any non-empty value (e.g. `true`), disables all HuggingFace model downloads. For offline or air-gapped deployments with pre-cached models.	(not set)
`WHISPER_WORD_TIMESTAMPS`	When set to `true`, enables word-level timestamps globally for all requests. The `verbose_json` output will include a top-level `words` array with per-word timing and confidence. Can also be enabled per-request via `timestamp_granularities[]=word`.	(not set)
`WHISPER_DIARIZATION`	Set to `true` to enable speaker diarization. Identifies who is speaking in each segment. Uses sherpa-onnx with pyannote segmentation-3.0 ONNX models (~45 MB, auto-downloaded on first use). Not supported in streaming mode.	(not set)
`WHISPER_DIARIZE_NUM_SPEAKERS`	Exact number of speakers (if known). Improves clustering accuracy. Set to `-1` or leave unset for auto-detection.	`-1`
`WHISPER_DIARIZE_THRESHOLD`	Clustering threshold for auto-detection. Lower = more speakers detected, higher = fewer. Ignored when exact speaker count is set.	`0.5`
`WHISPER_DISABLE_USAGE_COUNTS`	Set to `1` to disable anonymous aggregate usage counts.	(not set)

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.

Alternatively, pass it with --env-file

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.

Using docker-compose with GPU (NVIDIA CUDA)

A separate docker-compose.cuda.yml is provided for GPU deployments:

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

Example docker-compose.cuda.yml (already included):

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:

Parameter	Type	Required	Description
`file`	file	✅	Audio file. Supported formats: `mp3`, `mp4`, `m4a`, `wav`, `webm`, `ogg`, `flac` and all other formats supported by ffmpeg.
`model`	string	✅	Pass `whisper-1` (value is accepted but the active model is always used).
`language`	string	—	BCP-47 language code. Overrides `WHISPER_LANGUAGE` for this request.
`prompt`	string	—	Optional text to guide the model's style or continue a previous segment.
`response_format`	string	—	Output format. Default: `json`. See response formats. Ignored when `stream=true`. OpenAI-only `diarized_json` is not supported.
`temperature`	float	—	Sampling temperature (0–1). Default: `0`.
`stream`	boolean	—	Enable SSE streaming. When `true`, segments are returned as `text/event-stream` events as they are decoded. Default: `false`.
`timestamp_granularities[]`	array	—	Timestamp granularities to populate. Values: `word`, `segment`. When `word` is included, `verbose_json` output includes a top-level `words` array. Default: `["segment"]`.

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 file=@meeting.m4a \
    -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 file=@audio.mp3 \
    -F model=whisper-1

Response formats

`response_format`	Description
`json`	`{"text": "..."}` — default, matches OpenAI's basic response
`text`	Plain text, no JSON wrapper
`verbose_json`	Full JSON with language, duration, per-segment timestamps, log-probabilities
`srt`	SubRip subtitle format (`.srt`)
`vtt`	WebVTT subtitle format (`.vtt`)

Example — stream segments as they are decoded:

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

SSE response (uses the OpenAI streaming transcription protocol):

data: {"type":"transcript.text.delta","delta":"Hello, how are you?"}

data: {"type":"transcript.text.delta","delta":" I'm doing well, thank you."}

data: {"type":"transcript.text.done","text":"Hello, how are you? I'm doing well, thank you."}

data: [DONE]

The first delta typically arrives within 1–3 seconds of upload. Each transcript.text.delta event contains the incremental text for the segment just decoded. The final transcript.text.done event contains the full assembled transcript, equivalent to the standard json response.

Example — stream from a browser using fetch

const form = new FormData();
form.append("file", audioBlob, "audio.webm");
form.append("model", "whisper-1");
form.append("stream", "true");

const res = await fetch("http://your_server_ip:9000/v1/audio/transcriptions", {
  method: "POST",
  headers: { Authorization: "Bearer your_api_key" },
  body: form,
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  // SSE frames are separated by "\n\n"; split and process complete frames
  const frames = buffer.split("\n\n");
  buffer = frames.pop(); // keep any incomplete trailing frame
  for (const frame of frames) {
    if (!frame.startsWith("data: ")) continue;
    const payload = frame.slice(6);
    if (payload.startsWith("[DONE]")) break;
    const event = JSON.parse(payload);
    if (event.type === "transcript.text.delta") console.log(event.delta);
    if (event.type === "transcript.text.done") console.log("Full text:", event.text);
  }
}

Example — get SRT subtitles:

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

Example — verbose JSON with timestamps:

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

Example — verbose JSON with word-level timestamps:

curl http://your_server_ip:9000/v1/audio/transcriptions \
    -H "Authorization: Bearer $scribecrate_api_key" \
    -F file=@audio.mp3 \
    -F model=whisper-1 \
    -F response_format=verbose_json \
    -F "timestamp_granularities[]=word"

When timestamp_granularities[] includes word, the verbose_json response includes a top-level words array:

{
  "word": "hello",
  "start": 0.5,
  "end": 0.8,
  "probability": 0.98
}

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.

Note: Translation is not supported with English-only (.en) models. Use a multilingual model (e.g. base, small, large-v3-turbo).

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

To change the active model:

(Optional but recommended) Pre-download the new model while the server is running:
```
docker exec whisper whisper_manage --downloadmodel large-v3-turbo
```
Update WHISPER_MODEL in your whisper.env file (or add -e WHISPER_MODEL=large-v3-turbo to your docker run command).
Restart the container:
```
docker restart whisper
```

Available models:

Model	Disk	RAM (approx)	Notes
`tiny`	~75 MB	~250 MB	Fastest; lower accuracy
`tiny.en`	~75 MB	~250 MB	English-only
`base`	~145 MB	~700 MB	Good balance — default
`base.en`	~145 MB	~700 MB	English-only
`small`	~465 MB	~1.5 GB	Better accuracy
`small.en`	~465 MB	~1.5 GB	English-only
`medium`	~1.5 GB	~5 GB	High accuracy
`medium.en`	~1.5 GB	~5 GB	English-only
`large-v1`	~3 GB	~10 GB	Older large model
`large-v2`	~3 GB	~10 GB	Very high accuracy
`large-v3`	~3 GB	~10 GB	Best accuracy
`large-v3-turbo`	~1.6 GB	~6 GB	Fast + high accuracy ⭐
`turbo`	~1.6 GB	~6 GB	Alias for `large-v3-turbo`

Tip: large-v3-turbo offers accuracy close to large-v3 at roughly half the resource cost. It is the recommended upgrade path from base for most production deployments.

RAM figures are approximate and reflect INT8 quantization (default). Models are cached in the /var/lib/whisper Docker volume and only downloaded once.

Securing your server

If your ScribeCrate server is reachable from the public internet — even briefly — apply at minimum these protections. Transcription is CPU/GPU-intensive, so an unauthenticated endpoint can be abused to burn your compute resources.

1. Use an API key. Fresh installs with a mounted /var/lib/whisper volume auto-generate an API key. Display it with docker exec whisper whisper_manage --showkey, or use docker exec whisper whisper_manage --getkey in scripts. Existing installs without a key remain open for backward compatibility; set WHISPER_API_KEY in your env file to enable authentication manually. All authenticated requests must include Authorization: Bearer <key>.

# Generate a 32-byte random key
openssl rand -hex 32

2. Bind to localhost when fronted by a reverse proxy. Replace -p 9000:9000 with -p 127.0.0.1:9000:9000 (or change "9000:9000/tcp" to "127.0.0.1:9000:9000/tcp" in docker-compose.yml) so the unencrypted port is not reachable directly from outside the host.

3. Limit upload size. The server rejects uploads above WHISPER_MAX_UPLOAD_MB (default 1024). For internet-facing deployments, also configure your reverse proxy to reject oversized uploads (e.g. nginx client_max_body_size 100M;) before they reach the app.

4. Mind the log level. WHISPER_LOG_LEVEL=DEBUG may write transcript text to logs. Keep it at INFO or higher on shared systems.

5. Enable CORS at the proxy if calling from a browser. The server does not set Access-Control-Allow-Origin headers by default; add them at your reverse proxy if you intend to call the API directly from a web page on a different origin.

6. Consider rate limiting. Place a rate-limit (e.g. nginx limit_req_zone, Caddy rate_limit) in front of the server to cap concurrent transcriptions per client IP.

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):

server {
    listen 443 ssl;
    server_name whisper.example.com;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # Audio files can be large — increase the upload limit as needed
    client_max_body_size 100M;

    location / {
        proxy_pass         http://127.0.0.1:9000;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;       # required for chunked streaming (SSE)
        proxy_read_timeout 300s;
    }
}

Update Docker image

To update the Docker image and container, first download the latest version:

docker pull hwdsl2/whisper-server

If the Docker image is already up to date, you should see:

Status: Image is up to date for hwdsl2/whisper-server:latest

Otherwise, it will download the latest version. Remove and re-create the container:

docker rm -f whisper
# Then re-run the docker run command from Quick start with the same volume and port.

Your downloaded models are preserved in the whisper-data volume.

Using with other AI services

ScribeCrate can be used as the speech-to-text service in a broader self-hosted AI setup.

For full and lightweight Docker Compose stacks, manual docker run examples, and voice/RAG/MCP pipeline examples with Kokoro, Embeddings, LiteLLM, Ollama, Docling, and MCP Gateway, see Self-Hosted AI Stack.

Speaker diarization

Speaker diarization identifies who is speaking in each transcribed segment. It is a local extension powered by sherpa-onnx using the pyannote segmentation-3.0 model exported to ONNX format.

Enable diarization:

# In your whisper.env:
WHISPER_DIARIZATION=true

ONNX models (~45 MB total) are automatically downloaded on first use and cached in the /var/lib/whisper volume. To pre-download them:

docker exec whisper whisper_manage --downloaddiarize

Output with diarization enabled:

verbose_json adds a speaker field to each segment:

{
  "segments": [
    {"id": 0, "start": 1.0, "end": 3.5, "text": "We should launch next week.", "speaker": "SPEAKER_00"},
    {"id": 1, "start": 4.0, "end": 6.2, "text": "I think QA needs two more days.", "speaker": "SPEAKER_01"}
  ]
}

srt and vtt prepend the speaker label:

1
00:00:01,000 --> 00:00:03,500
[SPEAKER_00] We should launch next week.

2
00:00:04,000 --> 00:00:06,200
[SPEAKER_01] I think QA needs two more days.

text format shows the speaker label on speaker changes:

[SPEAKER_00] We should launch next week.
[SPEAKER_01] I think QA needs two more days.

Notes:

Important

Diarization requires full audio analysis and is not supported in streaming mode (stream=true). If both are enabled, diarization is silently skipped.

Set WHISPER_DIARIZE_NUM_SPEAKERS if you know the exact number of speakers for better accuracy.
The diarization pipeline runs after transcription, adding a small amount of processing time proportional to audio duration.

Usage counts

This image uses public GitHub release asset download counts for anonymous, aggregate usage counts. Counts are approximate and are not unique users or active installs. The image does not send a telemetry payload or use a private collector. It only attempts the best-effort count after the server starts successfully with a mounted /var/lib/whisper volume, and again when that persistent install first runs a different image build. To opt out, set WHISPER_DISABLE_USAGE_COUNTS=1.

Technical details

Base image: python:3.12-slim for :latest; nvidia/cuda for :cuda
Runtime: Python 3 (virtual environment at /opt/venv)
STT engine: faster-whisper with CTranslate2 (INT8 by default on CPU, FP16 on CUDA)
API framework: FastAPI + Uvicorn
Audio decoding: PyAV (bundled FFmpeg libraries)
Data directory: /var/lib/whisper (Docker volume)
Model storage: HuggingFace Hub format inside the volume — downloaded once, reused on restarts

License

Note: The software components inside the pre-built image (such as faster-whisper and its dependencies) are under the respective licenses chosen by their respective 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.

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.

Name		Name	Last commit message	Last commit date
.github		.github
docs/images		docs/images
notebooks		notebooks
.dockerignore		.dockerignore
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
Dockerfile.cuda		Dockerfile.cuda
LICENSE.md		LICENSE.md
README-ru.md		README-ru.md
README-zh-Hant.md		README-zh-Hant.md
README-zh.md		README-zh.md
README.md		README.md
api_server.py		api_server.py
diarizer.py		diarizer.py
docker-compose.cuda.yml		docker-compose.cuda.yml
docker-compose.yml		docker-compose.yml
manage.sh		manage.sh
run.sh		run.sh
whisper.env.example		whisper.env.example

Navigation Menu

Repository files navigation

ScribeCrate

Features

Quick start

ScribeCrate vs. WhisperLive

Community

Requirements

Download

Environment variables

Using docker-compose

API reference

Transcribe audio

Response formats

Translate audio

List models

Interactive API docs

Persistent data

Managing the server

Switching models

Securing your server

Using a reverse proxy

Update Docker image

Using with other AI services

Speaker diarization

Usage counts

Technical details

License

About

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

ScribeCrate

Features

Quick start

ScribeCrate vs. WhisperLive

Community

Requirements

Download

Environment variables

Using docker-compose

API reference

Transcribe audio

Response formats

Translate audio

List models

Interactive API docs

Persistent data

Managing the server

Switching models

Securing your server

Using a reverse proxy

Update Docker image

Using with other AI services

Speaker diarization

Usage counts

Technical details

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Contributors

Languages