vein: speech-to-text core — streaming dictation with hotwords - #1655
Merged
Conversation
… hotwords Streaming STT is the product surface; workflows learn around it (dream cycles), no STT step. src/audio/: service (model download+verify, cached recognizers, two-recognizer streams: fast greedy NeMo partials + hotword- capable Zipformer finals, batch transcribe), catalog, hotwords compiler (synthesized bpe.vocab — sherpa needs modelingUnit bpe or the list is a silent no-op), sessions + corrections, /audio/stream WebSocket (raw ws on the Node server; Bearer or ?key=), /audio/* routes. sherpa-onnx-node is an optionalDependency, lazy-loaded; routes answer 501 without it. Plan doc rewritten from the bake-off: measured latency/accuracy for kroko, NeMo fast-conformer 80/480 ms, Nemotron; NeMo online transducers are greedy-only in sherpa (no hotwords); sample-rate change aborts the process.
Mic → AudioWorklet → PCM16LE → /audio/stream, with model picker (+ SSE download), inline hotwords, and editable finals that post corrections. Inline HTML (tsc copies no assets); served before the key middleware so a browser can load it, everything it calls stays gated.
Replaces the inline /audio/try page. A gear in the topbar opens a Settings modal whose "Enable dictation" downloads the default model pair (kroko finals + NeMo 80 ms partials) and stores the choice in localStorage; installation stays a server fact via /audio/models. Once the chosen models are confirmed installed, a mic appears in the chat input: partials render live at the end of the textarea and finals replace them. A hotwords textarea in Settings is sent inline with every stream for experimenting with biasing.
A WebSocket upgrade never enters Express, so the /lab bridge couldn't carry /lab/audio/stream. vein now exposes createAudioUpgradeHandler (the piece attachAudioWebSocket is built on) with an authorize hook; mcp hooks the server's upgrade event, applies the lab Basic/x-api-token rule, lazily builds the lab vein like the bridge does, and hands the socket over. Other upgrade paths get a 404 instead of a hanging socket.
One resolver (src/model-dir.ts) for MiniLM and STT: VEIN_MODEL_DIR, then the VEIN_MODEL_CACHE alias, then <cache root>/vein/models where the root is VEIN_CACHE_DIR / XDG_CACHE_HOME / ~/.cache — the convention mcp's GAIA checkout already uses, so the server's ~/.cache/vein volume persists models with no new env. A pre-existing ~/.cache/vein-models keeps being used when nothing is configured.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Streaming speech-to-text inside vein over sherpa-onnx, per the rewritten §4 of
vein/plans/local-desktop-and-stt.md. Dictation over a WebSocket is the product surface; workflows sit around the recognizer as the learning loop ("dream cycles", §4.8). No STT workflow step in v1.src/audio/stt.ts— service: model download + sha256 verify +tar xjf, cached recognizers, streams (PCM16 in →partial/finalevents out), two-recognizer mode (fast greedy NeMo model for partials, hotword-capable Zipformer for finals + endpointing), batchtranscribe.sherpa-onnx-nodeis an optionalDependency, lazy-imported; without it/audio/*answers 501 and everything else is untouched.src/audio/hotwords.ts— contextual biasing. Two verified gotchas baked in: sherpa needsmodelingUnit: "bpe"(unset →cjkchar→ silent no-op), and abpe.vocabthe released models don't ship, synthesized fromtokens.txt. Named lists under<dataDir>/audio/hotwords/are the dream cycle's promotion artifact.src/audio/sessions.ts— finals + user corrections per session (training data for the dream cycle).src/audio/ws.ts—GET /audio/streamvia rawwson the Node server (@hono/node-wsdoesn't support node-server 2.x). Bearer or?key=.src/audio/routes.ts—/audio/models(+ SSE download),/audio/transcribe,/audio/hotwords/:name,/audio/sessions/:id(+ corrections).web/src/dictation.ts,SettingsDialog, mic inChatFlyout): gear → Settings → "Enable dictation" downloads the default pair and stores the choice inlocalStorage; a mic then appears in the AI chat input and dictates into it (partials live, finals replace them). Settings also has an inline hotwords list sent with every stream, for experimenting with biasing. Try it:VEIN_WORKSPACE_BACKEND=fs npx tsx src/server.ts(afternpm run build:web), open the UI, gear, enable./lab(mcp/src/lab/mount.tsattachLabAudio): the dictation socket works through the Express host too — mcp hooks the server'supgradeevent, applies the lab Basic/x-api-tokenrule, and hands matching sockets to vein'screateAudioUpgradeHandler. Verified end to end against a worktree mcp (401 without auth, 404 other paths, full replay with Basic auth, and the UI mic under/lab/).createVein({ stt }),ctx.services.stt,VEIN_MODEL_DIR(alias ofVEIN_MODEL_CACHE),VEIN_STT_MODEL,VEIN_STT_PARTIAL_MODEL.Measured (M-series Mac, see doc §4.1)
zipformer-en-kroko(57 MB)nemo-fast-conformer-en-80ms(103 MB)nemo-fast-conformer-en-480ms(106 MB)nemotron-speech-en-80ms(463 MB)End to end over the socket at real-time pace: partials 50–100 ms behind the audio, final ~300 ms after
end. Hotwords turned "on this FHIC swarm" into "on the Sphinx swarm" and "hive" into "Hive".Tests
npm run test:stt(opt-inVEIN_TEST_STT=1) downloads kroko and streams its bundled clip: 3/3 locally.