@qvac/asr-ggml — Parakeet
Automatic speech recognition (ASR) for speech-to-text with speaker diarization.
Overview
Bare module that adds support for transcription in QVAC using NVIDIA Parakeet ASR models via parakeet-cpp (GGML) as the inference engine.
@qvac/asr-ggml serves the Whisper, Parakeet, and MOSS-Transcribe-Diarize engines behind a single class, ASRGgml. It replaces @qvac/transcription-parakeet. This page covers the Parakeet engine (engine: 'parakeet').
Parakeet supports multiple model variants:
- TDT — multilingual transcription (~25 languages) with punctuation, capitalization, and automatic language detection. Recommended default.
- CTC — English-only, fast transcription without punctuation or capitalization.
- Unified — English; one checkpoint for batch and cache-aware streaming, with punctuation and capitalization.
- TranscribePsy EU — 25 European languages;
parakeetConfig.languageselectsen,other, orauto. - TranscribePsy EU-sub — 8 European languages; distilled from TDT v3.
- EOU — English streaming with a native end-of-turn token.
- Indic Conformer CTC — Indic languages; set
parakeetConfig.language(for example,"hi"). - Nemotron 3.5 ASR Streaming — multilingual batch and cache-aware streaming transcription;
parakeetConfig.languagetakes a locale (for example,"en-US") or"auto"(default). Streaming chunks must be one ofASRGgml.NEMOTRON_STREAMING_CHUNK_MS: 80, 160, 320 (default), 560, or 1120 ms. - Sortformer v1 — speaker diarization (up to 4 speakers); default for offline diarization.
- Sortformer v2.1 + AOSC — speaker diarization (up to 4 speakers); default for streaming diarization.
- Nemotron 3 Diarization — speaker diarization (up to 8 speakers), offline and streaming.
Models
Each Parakeet variant is a single .gguf checkpoint. The model type is auto-detected from the GGUF metadata, so there is no modelType to pass.
The addon loads weights from local paths only — it never downloads. Stage the GGUF files from the QVAC model registry or by hand:
- TranscribePsy EU-sub: qvac/TranscribePsy-250M-EU-sub-gguf
- TranscribePsy EU: convert the checkpoint following the native conversion guide.
Requirement
Bare >= v1.20
Installation
npm i @qvac/asr-ggmlQuickstart
If you don't have Bare runtime, install it:
npm i -g bare bare-makeCreate a new project:
mkdir qvac-parakeet-quickstart
cd qvac-parakeet-quickstart
npm init -yInstall dependencies:
npm i @qvac/asr-ggml bare-fs bare-processDownload the TDT checkpoint from the QVAC registry. The download script ships with the repository, not with the npm package, so run it from a checkout of tetherto/qvac, in packages/asr-ggml:
npm install
npm run download-models:parakeet:registry -- -t tdtThe script saves parakeet-tdt-0.6b-v3.q8_0.gguf to packages/asr-ggml/models/. Copy it to models/parakeet-tdt-0.6b-v3.q8_0.gguf in your project, and place a 16 kHz mono 16-bit WAV file at my-audio.wav.
Create index.js:
'use strict'
const fs = require('bare-fs')
const process = require('bare-process')
const ASRGgml = require('@qvac/asr-ggml')
async function main () {
const model = new ASRGgml({
files: { model: './models/parakeet-tdt-0.6b-v3.q8_0.gguf' },
config: {
engine: 'parakeet',
parakeetConfig: { useGPU: true, maxThreads: 4 }
}
})
await model.load()
const audioBuffer = fs.readFileSync('./my-audio.wav')
const audioData = new Uint8Array(audioBuffer.subarray(44)) // Skip WAV header; read as s16le
const response = await model.run(audioData)
const segments = []
await response
.onUpdate((out) => {
for (const s of Array.isArray(out) ? out : [out]) {
if (s.text && s.toAppend) segments.push(s)
}
})
.await()
console.log('=== TRANSCRIPTION ===')
console.log(segments.map((s) => s.text).join(''))
console.log('=====================')
await model.unload()
}
main().catch(err => {
console.error(err)
process.exit(1)
})Run index.js:
bare index.jsUsage
1. Configure Parakeet Parameters
Pass the engine and its settings in config. config.engine is required whenever config is supplied. Parakeet settings go in config.parakeetConfig; any key outside its vocabulary throws INVALID_CONFIG (24015) from the constructor.
| Group | Keys |
|---|---|
| Compute | maxThreads, useGPU, backend, seed |
| Audio | sampleRate (16000), channels (1) |
| Output | captionEnabled, timestampsEnabled |
| Language | language — multilingual CTC id (e.g. "hi"), required for Indic Conformer; full TranscribePsy EU accepts "en", "other", or "auto" (default). Ignored on monolingual CTC |
| Streaming (ASR) | streaming, streamingChunkMs, streamingEmitPartials, streamingEnergyVad, streamingEnergyVadThresholdDb, streamingEnergyVadWindowMs, streamingEnergyVadHangoverMs, streamingLeftContextMs, streamingRightLookaheadMs |
| Streaming diarization | streamingHistoryMs, streamingSpeakerVad, streamingSpkCacheEnable, streamingSpkCacheLen, streamingFifoLen, streamingChunkLeftContextMs, streamingChunkRightContextMs, streamingSpkCacheUpdatePeriod |
| Diarization, offline and streaming | diarizationThreshold, diarizationMinSegmentMs |
| Speaker-attributed batch ASR | speakerAttribution: { modelPath, mergeSameSpeaker?, minSegmentMs?, padSegmentMs? } |
| Engine | prewarm, prewarmAudioSeconds, longFormWindowFrames, longFormContextFrames |
| Backends | backendsDir, openclCacheDir |
2. Configuration Example
// TDT (multilingual, recommended)
const model = new ASRGgml({
files: { model: './models/parakeet-tdt-0.6b-v3.q8_0.gguf' },
config: {
engine: 'parakeet',
parakeetConfig: {
useGPU: true,
maxThreads: 4,
timestampsEnabled: true,
streaming: false // true opens a session at load time
}
}
})The same shape loads every variant: point files.model at another GGUF (CTC, EOU, Sortformer, and so on). The variant is detected from the file.
3. Create Model Instance
const ASRGgml = require('@qvac/asr-ggml')
const model = new ASRGgml({ files, config })The constructor resolves the engine and validates the model file and config. It throws on any problem — nothing is deferred to load().
| Option | Default | Description |
|---|---|---|
files.model | — | Required. Path to the .gguf checkpoint. Must exist. |
config | — | Engine-scoped config; must carry engine when present. |
engine | — | Alias for config.engine, used when config is omitted. |
enableStats | true | Attach runtime stats to the job-end payload. |
logger | null | A @qvac/logging LoggerInterface. |
exclusiveRun | true | Serialize run() calls to completion. |
4. Load Model
Create the native instance and activate the model:
try {
await model.load()
} catch (error) {
console.error('Failed to load model:', error)
}5. Run Transcription
Audio must be 16 kHz mono. run() and runStreaming() accept a stream, an iterable, a single chunk, or an array of chunks:
Float32Array— f32 samples in[-1, 1]Int16Array— s16 samplesUint8Array— raw bytes, decoded ass16le
try {
const response = await model.run(audioData)
await response
.onUpdate((out) => {
for (const s of Array.isArray(out) ? out : [out]) {
// `toAppend` marks a segment that continues the previous one
if (s.text && s.toAppend) console.log(s.text)
}
})
.await()
} catch (error) {
console.error('Transcription failed:', error)
}run() returns a QvacResponse; drain it with onUpdate(cb) (push) or iterate() (pull). For live audio, use runStreaming(audio, opts). Its options override the streaming* load-time keys per call: chunkMs, historyMs, leftContextMs, rightLookaheadMs, emitPartials, emitEnergyVad, energyVadThresholdDb, energyVadWindowMs, energyVadHangoverMs, emitSpeakerVad, diarizationThreshold, diarizationMinSegmentMs, spkCacheEnable, spkCacheLen, fifoLen, chunkLeftContextMs, chunkRightContextMs, and spkCacheUpdatePeriod. Most drop the streaming prefix, but streamingEnergyVad and streamingSpeakerVad become emitEnergyVad and emitSpeakerVad.
Output payloads:
- Segments — bare
TranscriptionSegment[](or a single segment):text,start,end, plus the Parakeet fieldstoAppend,isEndOfTurn, andstartsWord. Sortformer addsspeakerId(streaming) orspeakerSegments(offline);speakerAttributionaddsspeakerId,start,end, andisFinalper turn. { type: 'vad', ... }— voice-activity change;sourceis'energy'(ASR energy detector) or'sortformer'(speaker activity).{ type: 'endOfTurn', ... }— turn boundary, with native timing and confidence.
6. Release Resources
Release the model when finished, or retire the instance:
try {
await model.unload() // or model.destroy()
} catch (error) {
console.error('Failed to release model:', error)
}