Skip to content

A platform for community discussion. Free, open, simple.

4.1 KB
Raw Blame

Self-hosting the subtitles models (mirror)

By default, live subtitles download their speech-to-text model on first use from Discourse's HuggingFace repository, Discourse/Discourse-STT. The plugin pins that repository to a specific commit.

Some sites can't let browsers reach huggingface.co, or prefer not to: airgapped deployments, enterprise networks, or anyone who wants to control the bytes. They can serve the models themselves and point the live_stt_model_base_url site setting at their own mirror.

Only the model weights are affected. The runtime bundles (worker, VAD, onnxruntime) are always served from the plugin's own public/ directory and need no extra hosting.

What to mirror

The repository has one folder per model. Each user picks a model in their voice settings, so mirror every folder. Keep the folder names and file names exactly as they are.

Folder Model Size
ultra-q4/ Parakeet Ultra, 4-bit encoder (default, "Best quality") ~410 MB
redux-w2a8/ Parakeet Redux, 2-bit encoder ("Smaller") ~210 MB

Every folder holds the same three files:

File Purpose
encoder-model.onnx quantized encoder, a single file (runs on WebGPU)
decoder_joint-model.int8.onnx int8 decoder/joint (runs on WASM)
vocab.txt tokenizer vocabulary

To download them, using the commit the plugin pins (see DEFAULT_MODEL_ROOT in assets/javascripts/discourse/lib/live/stt-models.js):

REV=0862913c8a5c08254d1082747c6443a06e062988
for model in ultra-q4 redux-w2a8; do
  mkdir -p "discourse-stt/$model"
  for f in encoder-model.onnx decoder_joint-model.int8.onnx vocab.txt; do
    curl -L -o "discourse-stt/$model/$f" \
      "https://huggingface.co/Discourse/Discourse-STT/resolve/$REV/$model/$f"
  done
done

The models are CC-BY-4.0. The repository's README lists the attribution and the source of every file.

The plugin requests <base_url>/<folder>/<file> and nothing else.

Hosting requirements

The files are fetched by the browser, from a Web Worker on the forum's origin, not by the Discourse server. So the mirror must be reachable by your users, and must speak CORS if it lives on a different origin:

  • Access-Control-Allow-Origin: <forum origin> (or *) on every file.
  • HTTPS, if the forum is served over HTTPS (mixed content is blocked).
  • A correct Content-Length, which any static file server sends. It drives the download progress shown in the caption overlay. Range requests are not needed.
  • Long-lived cache headers are recommended, because the files never change.

Example nginx location:

location /models/discourse-stt/ {
  root /var/www;
  add_header Access-Control-Allow-Origin "https://forum.example.com";
  add_header Cache-Control "public, max-age=31536000, immutable";
}

Then set the site setting (the trailing slash is optional):

live_stt_model_base_url = https://cdn.example.com/models/discourse-stt

Updating a mirror

Browsers keep a durable copy of the model they use and look it up by URL. If you replace a file at the same URL, users who already have the old copy keep it.

When the plugin moves to a new model revision, publish the new files under a new directory and point the setting there. For example, put the revision in the path: .../discourse-stt/<rev>/.

Each browser keeps only one model. Switching models, or changing the mirror URL, frees the previous copy.

Verifying a mirror

The end-to-end smoke harness lives in the discourse_voice_assets gem repository, alongside the shipped worker bundle. It can run against a local copy of any one model folder:

flite -t "the quick brown fox jumps over the lazy dog" /tmp/fix.wav
STT_MODEL_DIR=/path/to/discourse-stt/ultra-q4 \
  node scripts/smoke-stt-worker.mjs /tmp/fix.wav

Or point it at the mirror itself:

STT_MODEL_BASE_URL=https://cdn.example.com/models/discourse-stt/ultra-q4 \
  node scripts/smoke-stt-worker.mjs /tmp/fix.wav

The harness loads the shipped worker in Chromium (WebGPU required) and fails unless the fixture transcribes.