New: QVAC SDK now supports Kotlin. Build local AI into your JVM and Android apps.
QVAC Logo

@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.language selects en, other, or auto.
  • 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.language takes a locale (for example, "en-US") or "auto" (default). Streaming chunks must be one of ASRGgml.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:

Requirement

Bare >= v1.20

Installation

npm i @qvac/asr-ggml

Quickstart

If you don't have Bare runtime, install it:

npm i -g bare bare-make

Create a new project:

mkdir qvac-parakeet-quickstart
cd qvac-parakeet-quickstart
npm init -y

Install dependencies:

npm i @qvac/asr-ggml bare-fs bare-process

Download 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 tdt

The 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:

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.js

Usage

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.

GroupKeys
ComputemaxThreads, useGPU, backend, seed
AudiosampleRate (16000), channels (1)
OutputcaptionEnabled, timestampsEnabled
Languagelanguage — 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 diarizationstreamingHistoryMs, streamingSpeakerVad, streamingSpkCacheEnable, streamingSpkCacheLen, streamingFifoLen, streamingChunkLeftContextMs, streamingChunkRightContextMs, streamingSpkCacheUpdatePeriod
Diarization, offline and streamingdiarizationThreshold, diarizationMinSegmentMs
Speaker-attributed batch ASRspeakerAttribution: { modelPath, mergeSameSpeaker?, minSegmentMs?, padSegmentMs? }
Engineprewarm, prewarmAudioSeconds, longFormWindowFrames, longFormContextFrames
BackendsbackendsDir, 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().

OptionDefaultDescription
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.
enableStatstrueAttach runtime stats to the job-end payload.
loggernullA @qvac/logging LoggerInterface.
exclusiveRuntrueSerialize 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 samples
  • Uint8Array — raw bytes, decoded as s16le
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 fields toAppend, isEndOfTurn, and startsWord. Sortformer adds speakerId (streaming) or speakerSegments (offline); speakerAttribution adds speakerId, start, end, and isFinal per turn.
  • { type: 'vad', ... } — voice-activity change; source is '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)
}

More resources

On this page

Ask anything about QVAC.