您自己的语音模型¶

Picker header -> "Add model file…" -> native dialog (GGUF, All files)   // setup.custom-models
├── Header check, before anything loads (transcription::gguf_header): GGUF v2/v3;
│   general.architecture parakeet | whisper | qwen3_asr | cohere_asr | sensevoice |
│   gigaam (any other, e.g. llama.cpp's or SenseVoice.cpp's `sensevoice-small`,
│   says the file was made for another program and needs a transcribe.cpp
│   conversion, or the catalog's download; #1299);
│   stt.variant; general.languages with a code Hex knows; only F32, F16, and
│   Q8_0 tensors (the types every build runs on Metal and Vulkan); the tensor
│   data fits the file. Anything else -> "<file> can't be imported: <reason>"
├── Copy -> models/custom/<16 hex>.gguf while hashing; the copy is checked again;
│   receipt <16 hex>.gguf.verified.json (size, SHA-256, mtime, inode where
│   the OS reports one, never the volume's device number, which macOS can
│   renumber at a restart; older receipts' file_id is ignored); manifest <16 hex>.json (name, general.name, family,
│   variant, languages, detection, file name, licence, repo URL). The original
│   is never touched; a failed or cancelled import removes only its partial
│   copy; the same file again keeps the first import
├── ID custom-<first 16 hex of the SHA-256> (TranscriptionModelId::Custom)
├── Card -> name from general.name (Rename edits it), languages from the file,
│   offline only (no streaming), Parakeet without language prompt or Auto,
│   no benchmark; Use prepares it like a catalog model (verifies Hex's copy
│   against its receipt instead of downloading). General's Language menu
│   lists every language the file declares: Hex's usual list first, then the
│   rest of Whisper's codes by English name (Norwegian `no`, Norwegian
│   Nynorsk `nn`, …; #1148)
├── Remove -> Hex's copy, receipt, and manifest only; not the active model
├── Changed (a copy replaced by a link or hard link to the same file reads as
│   changed: its file ID and mtime moved) -> "Check again" rehashes the file:
│   the recorded SHA-256 again -> new receipt, ready; else it stays changed.
│   Missing or changed -> "Import again…": the same file replaces the copy and
│   keeps the import's name
├── The selected import missing or changed -> its card is not In use and
│   shows only Check again / Import again… (no Rename or Remove); a check or
│   import that succeeds asks for it again (ChooseModel), so the listener
│   leaves the fallback for it
└── Saved import missing or changed (size, mtime, or file ID) -> the choice
    stays saved; the listener runs a downloaded fallback (the system language's
    recommendation if downloaded, else the first downloaded catalog model;
    custom_models::runnable); General's model row names the fallback and says
    to check it again in the picker (not "can't listen until downloaded",
    while the fallback is downloaded); the card warns

Labs › Use model files where they are on (labs.model_in_place, off by default)  // labs.model-in-place
Picker header -> "Use model file where it is…" beside "Add model file…" -> the same dialog
├── Gate: the button shows only while the toggle is on, and the add starts only
│   if it is still on when the dialog answers (model_import::in_place_on)
├── custom_models::add_in_place on a worker: the import's header check, one full
│   SHA-256, receipt and manifest (with the file's path, no Hugging Face origin)
│   in models/custom/; nothing copied, nothing written near the file
├── The same file imported by copy before -> same ID, keeps its name; Hex's
│   copy is removed
├── Card -> "Used where it is" · family · languages · the file's name; Use
│   loads it from its path; later uses rehash only when size, mtime, or file ID
│   change, and Check again accepts it when the contents still match
├── Another account changes or removes the file -> Changed or Missing, as above
└── Forget -> Hex's receipt and record only; the file stays

Picker opens, or onboarding starts -> one scan (found_models::scan)   // setup.found-models
├── Where: $HF_HUB_CACHE, else $HF_HOME/hub, else ~/.cache/huggingface/hub
│   (Windows %USERPROFILE%\.cache\huggingface\hub); models--*/snapshots/*/*.gguf
├── Cheap: headers only, through the import's checks; each file's result is kept
│   by path, size, mtime, and file ID, so an unchanged file is never read twice.
│   Never in the background, never a full hash during the scan
├── Exact catalog match: the snapshot links to blobs/<sha256> and that digest and
│   size are a catalog pin (a plain copy: repository, file name, and size)
│   -> that catalog model counts as downloaded; its card says "Found on this
│   computer" and offers Use, never Download
├── Other compatible files -> "Found on this computer" at the top of the picker:
│   name · Not tested by Hex · Q8_0/F16/F32 · owner/name@revision · languages,
│   "It may be too big for this computer's GPU memory." when the tensor data
│   plus a quarter exceeds the largest GPU transcribe.cpp reports, and
│   "Compatible doesn't mean accurate: …"
├── Use -> full SHA-256 once (a catalog file against its pin; another file against
│   its blob name), then prepared like any model. Receipts live with Hex:
│   models/found/<model>.json for a catalog file, models/custom/ for another;
│   later uses rehash only when size, mtime, or file ID change
├── A failed check or load -> "Model could not be used." with the reason; the
│   selection and any recorded audio stay as they were
└── Delete/Remove on a found file -> Forget: Hex's record goes, the file stays.
    Hex never writes, moves, or deletes inside the cache. A forgotten catalog
    file is noted in models/found/<model>.forgotten.json, so later scans no
    longer count it as downloaded and its row offers Download (#1366)

Onboarding opens -> scan; its own download waits until it answers  // setup.found-choice
├── Nothing compatible found -> Setting up Hex, unchanged: the recommended
│   model downloads by itself, and the model step never shows
└── Something found -> the first run's model step in place of Setting up Hex:
    "Choose a speech model", one card of radio rows, no buttons inside
    ├── Hex's recommended model first, selected, [Recommended] -> "731 MB
    │   download", or "On this computer" when its exact file (same SHA-256) is
    │   in the cache (one row, never two)
    ├── Then each found file -> its name, "On this computer" (a catalog model)
    │   or "On this computer · not tested by Hex"; no hashes, repositories,
    │   revisions, or compression
    ├── Picking a row starts it: ours downloads ("Downloading… 42%" on the row)
    │   or, already here, is checked in place; a found file is used where it
    │   is ("Checking…"). A later pick supersedes one still preparing
    ├── Continue starts the selected row if none was picked, then the story
    │   moves on once the pick is under way: ours with its download pill on
    │   top, a found one with no download page or pill at all
    ├── A pick that fails asks again on the list
    ├── Back on the pages after it returns to the list to change the pick,
    │   even with the model ready
    └── The held download is released once the tour passes setup, so a run
        that skips the step still gets the recommended model