@handy-computer/models

中文文档
0.2.3发布于 2026/10/26MITTypeScriptES Module零依赖构建来源已验证近 30 天下载 8.9万

The curated transcribe.cpp model catalog and the recommendation method shared by Handy, Pi Voice, and models.handy.computer

原始使用文档
文档目录6 节
  1. Four levels
  2. Use
  3. Grades and the speed meter
  4. curation.yaml
  5. Updating
  6. Automation ( .github/workflows/models.yml )

@handy-computer/models

The speech-to-text model catalog and the recommendation method shared by Handy, Pi Voice, and models.handy.computer. Same package version, same engine, same languages: same picks everywhere.

Four levels

LevelWhat it isWhere it comes from
LoadableAnything the app's engine can open, including a GGUF from diskthe app, at runtime
PublishedEvery model transcribe.cpp publishes (ALL_MODELS)transcribe.cpp catalog/
CuratedShown by default and the only models ever recommended (CURATED_MODELS)curation.yaml
RecommendedBest, Fast and Accurate for the user's languagescomputed by recommend(), never stored

Each app chooses how far past Curated it goes. Pi Voice shows Curated; Handy can also search Published. A model that leaves Curated stays Published, so a saved setting that points at it keeps resolving through getModel(id).

Use

import { recommend, CURATED_MODELS, getModel, modelFile, languageAccuracyGrade, modelWaitSeconds,
  speedMeterLevel, autoLanguagePolicy, LANGUAGE_DETECTION_MODEL } from "@handy-computer/models";

// Best/Fast/Accurate from the curated models this engine can load.
const picks = recommend(["en", "de"], { engineVersion: transcribeVersion() });
for (const pick of picks) {
  pick.roles;          // ["best"], ["fast", "accurate"], ...
  pick.status;         // eligible | experimental | unsupported | unbenchmarked
  const file = modelFile(pick.model); // the default (benchmarked) file: files[quant]
  pick.model.repository, pick.model.revision, file.filename, file.size, file.sha256;
}

Download from https://huggingface.co/<repository>/resolve/<revision>/<filename> and verify sha256. files holds every published file, keyed by quant; quant names the default.

previousRevisions lists the revisions this model was pinned to before revision, most recently replaced first, and only ever grows. A download at one of them was shipped before, but may contain identical model bytes (for example, after a file relocation). Compare hashes before treating it as a model update. A download at neither isn't one the catalog ever shipped. Cache reuse and migration are the app's responsibility.

Rust (Handy) reads the same file: @handy-computer/models/catalog.json. Unknown fields can be ignored; the schema number changes on any breaking change.

The functions Pi Voice had keep their names and behaviour (recommendModels, benchmarkModels, frontierModelIds, accuracyGrade, languageAccuracyGrade, speedMeterLevel, modelWaitSeconds, getPreferredRecommendationLanguages, autoLanguagePolicy, undetectablePreferences, rankCatalogModels, ...). createCatalog(data) binds them all to a different catalog, e.g. one fetched at runtime.

Grades and the speed meter

Grades are on measured error at the benchmarked quant: A under 5%, B under 10%, C under 20%, D under 30%, F beyond; each +/- step is a factor of ∛2. The speed meter counts how many of 1.5, 3, 5, 10 and 20 seconds the model beats when processing a 30-second dictation on the benchmark GPU.

curation.yaml

The hand-edited editorial configuration. It holds:

  • transcribeCpp: the transcribe.cpp release to build from. Use the engine version the apps ship; benchmarks can change with engine behaviour.
  • benchmarks: which quant, dataset and machines the picks are judged on.
  • methodology: the recommendation thresholds.
  • languageDetector: the shared spoken-language detector, and its default quant (F16; every other quant stays in files).
  • models: the curated models, by Hugging Face repo name without -gguf, each with a description. Listing a model is what makes it curated; removing it makes it Published only.
  • names: the display name of every published model, curated or not. A model missing here gets a name tidied from its id, and the daily PR lists it.

Everything else (languages, capabilities, licence, files, sizes, benchmarks) comes from transcribe.cpp. If a fact is wrong, fix it in transcribe.cpp. Byte-identical download relocations can be recorded in pins.json as described below.

Updating

npm run pins       # after changing transcribeCpp: pin new or re-uploaded files
npm run generate   # rebuild catalog.json from curation.yaml + transcribe.cpp + pins.json
npm run snapshot   # print every pick that changed, and accept the new snapshot
npm test

generate reads a transcribe.cpp checkout (default ../../../transcribe.cpp, or --transcribe-cpp/TRANSCRIBE_CPP) at the tag in curation.yaml, and needs its tags. It is offline: Hugging Face is only contacted by npm run pins.

pins.json is a lock file. Automatic refresh keeps an existing pin while its file paths and sizes match the release. Otherwise it tries the existing and preferred revisions, then the newest matching revision. The old revision moves to the pin's previous list. CI fails any change that drops a revision.

A byte-identical file relocation does not need an engine release. After verifying every relocated file's SHA-256 and size on Hugging Face, update the pin's revision, retain the old revision in previous, and add filename to each relocated file entry with its new repository-relative path. Keep the entry's key as the path from the engine release and keep its hash and size unchanged. Run npm run generate to emit the new download paths. Regular pin refresh preserves these entries; a later engine release with new paths can resolve them normally. Revision-based caches may need migration, but matching hashes mean the existing model bytes remain valid.

When Hugging Face spells a repo differently from transcribe.cpp (after a rename or a case change, which only redirect), the pin records Hugging Face's spelling and the catalog's repository uses it, since Hugging Face tools name cache folders after it. The id stays transcribe.cpp's.

A public Hugging Face repo counts as released. A model whose repo is still private is pinned with "private": true and left out of the catalog; a later pins picks it up once the repo is public.

Automation (.github/workflows/models.yml)

Every day the workflow runs npm run update: it moves curation.yaml to the newest transcribe.cpp release, refreshes pins, regenerates, re-snapshots the picks, bumps the patch version, and tests. In practice it only finds something when transcribe.cpp tags a new release. Then:

What changedWhat happens
Nothingnothing
Anythingopens (or refreshes) one PR, bot/models-catalog, with the changes in words; merging publishes
A new model that would be picked if curatedan issue per model with the evidence and the YAML to paste; close it to say no

The PR leads with what needs a closer look: pick changes; a curated model's (or the language detector's) download, licence, languages, capabilities or minimum engine; models that need a name; and models left out because their repo is still private. Nothing reaches main or npm without a merge, and every release is a patch.

PRs and pushes run generate --check, the tests and the build. A push to main with a new version in package.json publishes, so a hand edit (curating a model, changing a threshold) is: edit curation.yaml, npm run generate && npm run snapshot, bump the version, open a PR.

To decline a review PR, change curation.yaml or the method on main; closing the PR alone means the same update reopens it the next day.

One-time setup:

  1. Repository Settings → Actions → General → Workflow permissions: allow GitHub Actions to create and approve pull requests.
  2. Publish 0.1.0 by hand once (npm publish --access public from this folder), then on npmjs.com add a trusted publisher for the package: GitHub Actions, handy-computer/models, workflow models.yml. Trusted publishing needs no token to rotate. Alternatively, set an NPM_TOKEN repository secret.
  3. Optional: an HF_TOKEN secret, if Hugging Face rate-limits the pin step.

test/fixtures/pi-voice-picks.json and pi-voice-data.json record Pi Voice's picks and data at the time of the move; parity.test.ts proves this code reproduces them exactly. picks.json is this package's own snapshot.

版本与发布记录

@handy-computer/models 共发布 6 个版本,首次发布于 2026/10/16;过去 12 个月发布了 6 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.2.3latest2026/10/2621 天前
0.2.22026/10/1929 天前
0.2.12026/10/161 个月前
0.2.02026/10/161 个月前
0.1.02026/10/161 个月前
0.0.0-stage2026/10/161 个月前

关于 @handy-computer/models 的常见问题

@handy-computer/models 是什么?

The curated transcribe.cpp model catalog and the recommendation method shared by Handy, Pi Voice, and models.handy.computer

如何安装 @handy-computer/models?

在项目目录运行 npm install @handy-computer/models,或使用 pnpm add / yarn add / bun add。

@handy-computer/models 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@handy-computer/models 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@handy-computer/models 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20.10。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@handy-computer/models 可以商用吗?

@handy-computer/models 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@handy-computer/models 的下载量有多少?

根据 npm 官方下载统计,@handy-computer/models 在 2026/10/17 – 2026/11/15 这 30 天内被下载 89,331 次,日均约 2,978 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@handy-computer/models 还在维护吗?

最新版本 0.2.3 发布于 2026/10/26(21 天前);至今共发布 6 个版本,其中过去 12 个月发布了 6 个;首次发布于 2026/10/16。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。