Manual Model Install

Stage any built-in model by hand so WinSTT can run it without ever touching the network — for proxy-blocked, firewalled, or fully air-gapped machines.

Model picker

WinSTT normally downloads built-in models from the Hugging Face Hub on demand. If your network blocks huggingface.co — corporate proxy, firewall, air-gapped lab, country-level block — you can copy the model files into the cache yourself, and the picker will pick them up on the next restart.

Where models live

WinSTT uses the standard huggingface_hub cache, not its own models/ directory.

Inside the cache each repo gets a folder named models--<owner>--<repo> with blobs/, refs/, and snapshots/ subfolders. huggingface_hub resumes interrupted pulls automatically — a partial download leaves a *.incomplete marker that resumes on the next attempt.

Stage a model offline

1. Identify the repo ID

   Open the picker in WinSTT (or check Available Models) and note the Hugging Face repo for the model you want. A few common ones:

   The catalog at src-tauri/src/winstt/catalog.rs is the authoritative list — the onnx_model_name field holds the exact repo ID for every entry.

   Picker label	HF repo ID
   Whisper Tiny (multilingual)	onnx-community/whisper-tiny
   Whisper Tiny.en	onnx-community/whisper-tiny.en
   Whisper Base.en	onnx-community/whisper-base.en
   Whisper Small	onnx-community/whisper-small
   Whisper Large v3 Turbo	onnx-community/whisper-large-v3-turbo
   Lite-Whisper Large v3 Turbo (acc)	onnx-community/lite-whisper-large-v3-turbo-acc-ONNX
   Kokoro-82M (TTS)	onnx-community/Kokoro-82M-v1.0-ONNX

2. Download the snapshot on a connected machine

   The cleanest path is to use huggingface_hub on a machine that does have network access:

   pip install huggingface_hub
   huggingface-cli download onnx-community/whisper-tiny.en --local-dir ./whisper-tiny.en

   This pulls the entire repo into ./whisper-tiny.en/. You can also browse the repo in a web browser and download each file by hand — the URLs look like:

   https://huggingface.co/onnx-community/whisper-tiny.en/resolve/main/onnx/encoder_model.onnx
   https://huggingface.co/onnx-community/whisper-tiny.en/resolve/main/onnx/decoder_model_merged.onnx
   https://huggingface.co/onnx-community/whisper-tiny.en/resolve/main/tokenizer.json
   https://huggingface.co/onnx-community/whisper-tiny.en/resolve/main/config.json
   https://huggingface.co/onnx-community/whisper-tiny.en/resolve/main/generation_config.json
   https://huggingface.co/onnx-community/whisper-tiny.en/resolve/main/preprocessor_config.json

   You only need the quantization variants you'll actually run. For Whisper that's typically encoder_model.onnx and decoder_model_merged.onnx (default precision), plus optional *_fp16.onnx, *_q4.onnx, or *_int8.onnx for the other quantizations the model card lists.

   WinSTT does not auto-quantize

   To run, say, q4 you must have the *_q4.onnx weights from the upstream repo. The picker greys out any quantization whose files aren't present — it never compresses weights itself.

3. Place the files into the cache layout

   Inside C:\Users\<you>\.cache\huggingface\hub\, recreate the standard layout for one model:

   models--onnx-community--whisper-tiny.en/
   ├── refs/
   │   └── main                # text file containing the commit SHA you downloaded
   ├── snapshots/
   │   └── <commit-sha>/       # mirror of the repo at that revision
   │       ├── config.json
   │       ├── tokenizer.json
   │       ├── generation_config.json
   │       ├── preprocessor_config.json
   │       └── onnx/
   │           ├── encoder_model.onnx
   │           └── decoder_model_merged.onnx
   └── blobs/                  # optional — symlink targets; can be empty if snapshots/ holds real files

   The simplest approach is to download with huggingface-cli on a connected machine, then copy the entire models--<owner>--<repo> folder verbatim to the target. This preserves the blobs-and-symlinks layout huggingface_hub expects.

   robocopy `
     "\\source-machine\C$\Users\you\.cache\huggingface\hub\models--onnx-community--whisper-tiny.en" `
     "$env:USERPROFILE\.cache\huggingface\hub\models--onnx-community--whisper-tiny.en" `
     /MIR

4. Restart WinSTT

   The picker re-probes the Hugging Face cache every time the settings panel opens. After a restart the model's quantization badge flips from Not cached to Cached, and you can swap to it with no active network connection.

   If the badge stays Not cached, the folder layout doesn't match. Open %APPDATA%\WinSTT\debug.log and search for hub_cache_dir or models--; those lines say which path the probe walked and what it expected to find.

Where staged models appear in the picker

A manually-placed model is indistinguishable from one WinSTT downloaded itself — both live in the same cache. In the model picker it appears in its family group with the same accuracy/speed bars, size, and language scope, and each quantization you staged shows a Cached badge instead of a Download button. Variants you didn't stage stay greyed out until their files are present.

Verify without launching the app

To sanity-check the layout before launching the app, run the Rust STT example in cache-only mode:

cd src-tauri
STT_BENCH_CACHE_ONLY=1 cargo run --release --example stt_decode_bench -- --catalog tiny.en

The example uses the same catalog resolver as the app and fails with the missing file or cache path if the staged snapshot is incomplete:

Bulk staging for a fleet

For IT teams deploying WinSTT across a managed fleet, the usual pattern is:

1. Stage everything once

   Run a one-time online setup on a build machine to download every model the org wants pre-staged.

2. Zip the cache

   Archive the whole C:\Users\<build-user>\.cache\huggingface\hub\ folder.

3. Deploy to each user

   Unpack the archive into each user's %USERPROFILE%\.cache\huggingface\hub\ via your MDM or GPO of choice.

4. Lock the network off

   Set the system env var HF_HUB_OFFLINE=1 to forbid any outbound Hub request. WinSTT then uses only what's already cached.

Related