---
title: "@qvac/asr-ggml — Parakeet"
canonical: https://docs.qvac.tether.io/ecosystem/addons/asr-ggml/
collection: "Ecosystem"
---

# @qvac/asr-ggml — Parakeet (/ecosystem/addons/asr-ggml)



## Overview

[Bare module](https://bare.pears.com) that adds support for transcription in QVAC using [NVIDIA Parakeet](https://huggingface.co/collections/nvidia/parakeet-asr-models-66b50d5a37b9580ee4ba93c2) ASR models via [`parakeet-cpp`](https://github.com/tetherto/qvac-fabric-speech.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](https://github.com/tetherto/qvac/tree/main/packages/registry-server) or by hand:

* **TranscribePsy EU-sub:** [qvac/TranscribePsy-250M-EU-sub-gguf](https://huggingface.co/qvac/TranscribePsy-250M-EU-sub-gguf)
* **TranscribePsy EU:** convert the checkpoint following the [native conversion guide](https://github.com/tetherto/qvac-fabric-speech.cpp/blob/master/engines/parakeet/docs/models.md#transcribepsy).

## Requirement

Bare `>= v1.20`

## Installation

```bash
npm i @qvac/asr-ggml
```

## Quickstart

<Steps>
  <Step>
    If you don't have Bare runtime, install it:

    ```bash
    npm i -g bare bare-make
    ```
  </Step>

  <Step>
    Create a new project:

    ```bash
    mkdir qvac-parakeet-quickstart
    cd qvac-parakeet-quickstart
    npm init -y
    ```
  </Step>

  <Step>
    Install dependencies:

    ```bash
    npm i @qvac/asr-ggml bare-fs bare-process
    ```
  </Step>

  <Step>
    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`](https://github.com/tetherto/qvac), in `packages/asr-ggml`:

    ```bash
    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`.
  </Step>

  <Step>
    Create `index.js`:
  </Step>

  <WrapCode>
    ```js title="index.js" lineNumbers
    '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)
    })
    ```
  </WrapCode>

  <Step>
    Run `index.js`:

    ```bash
    bare index.js
    ```
  </Step>
</Steps>

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

| 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

```javascript
// 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

```javascript
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:

```javascript
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`

```javascript
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:

```javascript
try {
  await model.unload()  // or model.destroy()
} catch (error) {
  console.error('Failed to release model:', error)
}
```

## More resources

* [Package README](https://github.com/tetherto/qvac/tree/main/packages/asr-ggml)
* [Package at npm](https://www.npmjs.com/package/@qvac/asr-ggml)
