@moxxy/plugin-stt-local 0.47.0 → 0.48.0

package/src/local-stt.test.ts

@@ -1,14 +1,19 @@
 import * as path from 'node:path';
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import { MOXXY_PCM16_24KHZ_MIME } from '@moxxy/sdk';
 import type { ensureModelFiles } from '@moxxy/model-fetch';
 
 import {
+  createLocalParakeetTranscriber,
   createLocalWhisperTranscriber,
-  type LocalWhisperOptions,
+  type LocalSttOptions,
 } from './local-stt.js';
-import { buildLocalSttPlugin, LOCAL_WHISPER_TRANSCRIBER_NAME } from './index.js';
+import {
+  buildLocalSttPlugin,
+  LOCAL_PARAKEET_TRANSCRIBER_NAME,
+  LOCAL_WHISPER_TRANSCRIBER_NAME,
+} from './index.js';
 import type { HostClientLike } from './host-client.js';
 import type { HostRequest, TranscribeResult } from './host-protocol.js';
 
@@ -60,7 +65,7 @@ function fakeEnsure(): { impl: typeof ensureModelFiles; calls: Parameters<typeof
 }
 
 function makeTranscriber(
-  over: Partial<LocalWhisperOptions> = {},
+  over: Partial<LocalSttOptions> = {},
   result?: TranscribeResult,
 ): {
   transcriber: ReturnType<typeof createLocalWhisperTranscriber>;
@@ -79,7 +84,7 @@ function makeTranscriber(
   return { transcriber, host, ensure };
 }
 
-describe('LocalWhisperTranscriber.transcribe', () => {
+describe('LocalSttTranscriber.transcribe', () => {
   it('defaults to the turbo model, decodes raw PCM, and returns the transcript', async () => {
     const { transcriber, host, ensure } = makeTranscriber();
     const out = await transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME });
@@ -102,7 +107,7 @@ describe('LocalWhisperTranscriber.transcribe', () => {
   });
 
   it('rejects a removed model (small) left in config, before any download', () => {
-    expect(() => makeTranscriber({ model: 'small' })).toThrow(/Unknown local Whisper model "small"/);
+    expect(() => makeTranscriber({ model: 'small' })).toThrow(/Unknown local speech model "small"/);
   });
 
   it('passes a per-call language hint through to the recognizer', async () => {
@@ -183,15 +188,14 @@ describe('LocalWhisperTranscriber.transcribe', () => {
 describe('constructor validation', () => {
   it('throws CONFIG_INVALID for an unknown configured model', () => {
     expect(() => createLocalWhisperTranscriber({ model: 'medium' })).toThrow(
-      /Unknown local Whisper model/,
+      /Unknown local speech model/,
     );
   });
 });
 
 describe('buildLocalSttPlugin', () => {
-  it('registers exactly one transcriber named local-whisper', () => {
+  it('registers local-whisper first', () => {
     const plugin = buildLocalSttPlugin();
-    expect(plugin.transcribers).toHaveLength(1);
     const def = plugin.transcribers![0]!;
     expect(def.name).toBe(LOCAL_WHISPER_TRANSCRIBER_NAME);
     expect(def.displayName).toContain('Local Whisper');
@@ -224,3 +228,118 @@ describe('buildLocalSttPlugin', () => {
     expect(typeof plugin.hooks?.onShutdown).toBe('function');
   });
 });
+
+describe('local-parakeet', () => {
+  /** A minute and a half of loud audio, as a 16-bit PCM WAV-free raw clip @ 24 kHz. */
+  const LONG_AUDIO = rawPcm16(24_000 * 90);
+
+  function makeParakeet(over: Partial<LocalSttOptions> = {}, result?: TranscribeResult) {
+    const host = fakeHost(result);
+    const ensure = fakeEnsure();
+    const hosts = { made: 0 };
+    const transcriber = createLocalParakeetTranscriber({
+      modelsDir: '/models/stt',
+      ensureModelFilesImpl: ensure.impl,
+      hostFactory: () => {
+        hosts.made += 1;
+        return host.host;
+      },
+      log: () => {},
+      ...over,
+    });
+    return { transcriber, host, ensure, hosts };
+  }
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('downloads its four files and sends the joiner to the sidecar', async () => {
+    const { transcriber, host, ensure } = makeParakeet();
+    const out = await transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME });
+    expect(transcriber.name).toBe(LOCAL_PARAKEET_TRANSCRIBER_NAME);
+    expect(out.text).toBe('hello world');
+    expect(ensure.calls[0]!.dir).toBe(path.join('/models/stt', 'parakeet'));
+    expect(ensure.calls[0]!.files.map((file) => file.name)).toEqual([
+      'encoder.int8.onnx',
+      'decoder.int8.onnx',
+      'joiner.int8.onnx',
+      'tokens.txt',
+    ]);
+    expect(host.reqs[0]!.joiner).toBe(path.join('/models/stt', 'parakeet', 'joiner.int8.onnx'));
+  });
+
+  it('reads a long recording piece by piece and joins the text', async () => {
+    const { transcriber, host } = makeParakeet();
+    const out = await transcriber.transcribe(LONG_AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME });
+    expect(host.reqs).toHaveLength(2);
+    expect(out.text).toBe('hello world hello world');
+    expect(out.durationSec).toBeCloseTo(90, 0);
+  });
+
+  it('stops between pieces when the caller aborts', async () => {
+    const controller = new AbortController();
+    const host = fakeHost();
+    const transcribe = host.host.transcribe.bind(host.host);
+    host.host.transcribe = async (req) => {
+      controller.abort(new Error('stop'));
+      return transcribe(req);
+    };
+    const transcriber = createLocalParakeetTranscriber({
+      modelsDir: '/models/stt',
+      ensureModelFilesImpl: fakeEnsure().impl,
+      hostFactory: () => host.host,
+      log: () => {},
+    });
+    await expect(
+      transcriber.transcribe(LONG_AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME, signal: controller.signal }),
+    ).rejects.toThrow(/stop/);
+    expect(host.reqs).toHaveLength(1);
+  });
+
+  it('does not report the hint as the language it heard', async () => {
+    const { transcriber } = makeParakeet();
+    const out = await transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME, language: 'pl' });
+    expect(out.language).toBeUndefined();
+  });
+
+  it('gives its memory back after five idle minutes and loads again on the next use', async () => {
+    vi.useFakeTimers();
+    const { transcriber, host, hosts } = makeParakeet();
+    await transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME });
+    await vi.advanceTimersByTimeAsync(5 * 60_000 - 1);
+    expect(host.shutdowns).toBe(0);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(host.shutdowns).toBe(1);
+    await transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME });
+    expect(hosts.made).toBe(2);
+  });
+
+  it('keeps the model while another transcription is running', async () => {
+    vi.useFakeTimers();
+    const { transcriber, host } = makeParakeet();
+    await transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME });
+    await vi.advanceTimersByTimeAsync(4 * 60_000);
+    await transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME });
+    await vi.advanceTimersByTimeAsync(4 * 60_000);
+    expect(host.shutdowns).toBe(0);
+  });
+
+  it('keeps Whisper loaded, as it always was', async () => {
+    vi.useFakeTimers();
+    const { transcriber, host } = makeTranscriber();
+    await transcriber.transcribe(AUDIO, { mimeType: MOXXY_PCM16_24KHZ_MIME });
+    await vi.advanceTimersByTimeAsync(60 * 60_000);
+    expect(host.shutdowns).toBe(0);
+  });
+
+  it('registers next to local-whisper without choosing itself', () => {
+    const plugin = buildLocalSttPlugin({ defaults: { modelsDir: '/models/stt' } });
+    expect(plugin.transcribers?.map((def) => def.name)).toEqual([
+      LOCAL_WHISPER_TRANSCRIBER_NAME,
+      LOCAL_PARAKEET_TRANSCRIBER_NAME,
+    ]);
+    const inst = plugin.transcribers![1]!.createClient({ model: 'turbo' });
+    expect(inst.name).toBe(LOCAL_PARAKEET_TRANSCRIBER_NAME);
+  });
+});

package/src/local-stt.ts

@@ -1,8 +1,9 @@
 /**
- * The `local-whisper` Transcriber: fully local, on-device speech-to-text.
+ * The `local-whisper` and `local-parakeet` Transcribers: fully local, on-device
+ * speech-to-text. They differ only in the catalog entry they read.
  *
  * On the first transcription for a model it downloads + verifies that model's
- * Whisper files (once, via @moxxy/model-fetch), then decodes the inbound audio
+ * files (once, via @moxxy/model-fetch), then decodes the inbound audio
  * to Float32 mono @ 16 kHz IN-PROCESS (raw PCM / WAV) or via ffmpeg (compressed
  * containers) and hands the samples to the sherpa sidecar ({@link HostClient}).
  * No key, no network at transcription time.
@@ -29,7 +30,7 @@ import {
   type ModelFilesProgress,
 } from '@moxxy/model-fetch';
 
-import { TARGET_SAMPLE_RATE } from './audio.js';
+import { splitAtSilence, TARGET_SAMPLE_RATE } from './audio.js';
 import { decodeToMono16k } from './decode.js';
 import { HostClient, type HostClientLike } from './host-client.js';
 import {
@@ -39,27 +40,28 @@ import {
   modelDir,
   modelFiles,
   requireModel,
-  type WhisperModelEntry,
+  type LocalSttModelEntry,
 } from './models.js';
 import { resolveSherpaLibDir, sherpaEnv, sherpaPlatformPackage } from './platform.js';
 
-/** The single registered transcriber name. */
-export const LOCAL_WHISPER_TRANSCRIBER_NAME = 'local-whisper';
+export { LOCAL_PARAKEET_TRANSCRIBER_NAME, LOCAL_WHISPER_TRANSCRIBER_NAME } from './models.js';
 
 const DEFAULT_NUM_THREADS = 2;
 
 /** Resolved on-disk paths sherpa needs for one model. */
-export interface WhisperModelPaths {
+export interface LocalSttModelPaths {
   readonly encoder: string;
   readonly decoder: string;
+  readonly joiner?: string;
   readonly tokens: string;
 }
 
-export interface LocalWhisperOptions {
-  /** Model id. The only one is `turbo`, also the default. */
+export interface LocalSttOptions {
+  /** Model id, `turbo` by default. */
   readonly model?: string;
   /** Default Whisper language tag (BCP-47-ish, e.g. `en`, `pl`). Per-call
-   *  `TranscribeOptions.language` overrides it; omit to let Whisper auto-detect. */
+   *  `TranscribeOptions.language` overrides it; omit to let Whisper auto-detect.
+   *  Parakeet takes no hint: it works the language out itself. */
   readonly language?: string;
   /** Inference threads. Default 2. */
   readonly numThreads?: number;
@@ -84,7 +86,7 @@ export interface LocalWhisperOptions {
 
 /** Process-wide set of live transcribers so the plugin's `onShutdown` hook can
  *  kill every sidecar it spawned. */
-const ACTIVE_STT = new Set<LocalWhisperTranscriber>();
+const ACTIVE_STT = new Set<LocalSttTranscriber>();
 
 /** Shut down every live local transcriber (kills their sidecars). */
 export function shutdownLocalStt(): void {
@@ -92,10 +94,10 @@ export function shutdownLocalStt(): void {
   ACTIVE_STT.clear();
 }
 
-export class LocalWhisperTranscriber implements Transcriber {
-  readonly name = LOCAL_WHISPER_TRANSCRIBER_NAME;
+export class LocalSttTranscriber implements Transcriber {
+  readonly name: string;
 
-  private readonly model: WhisperModelEntry;
+  private readonly model: LocalSttModelEntry;
   private readonly defaultLanguage: string;
   private readonly numThreads: number;
   private readonly modelsDir: string;
@@ -110,11 +112,15 @@ export class LocalWhisperTranscriber implements Transcriber {
   private host: HostClientLike | null = null;
   /** In-flight model download promise — de-dupes concurrent first-use. */
   private ensuring: Promise<EnsureModelFilesResult> | null = null;
+  /** Transcriptions in flight: the model stays in memory while any is running. */
+  private running = 0;
+  private idleTimer: ReturnType<typeof setTimeout> | null = null;
 
-  constructor(opts: LocalWhisperOptions = {}) {
+  constructor(opts: LocalSttOptions = {}) {
     // Validate the configured model up front so a bad config fails clearly at
     // construction rather than on the first (possibly channel-triggered) call.
     this.model = requireModel(opts.model ?? DEFAULT_MODEL_ID, 'model');
+    this.name = this.model.transcriber;
     this.defaultLanguage = typeof opts.language === 'string' ? opts.language.trim() : '';
     this.numThreads =
       opts.numThreads && Number.isInteger(opts.numThreads) && opts.numThreads > 0
@@ -151,48 +157,88 @@ export class LocalWhisperTranscriber implements Transcriber {
     const paths = await this.ensureModelFiles(opts.signal);
     opts.signal?.throwIfAborted();
 
-    const language = ((opts.language ?? this.defaultLanguage) || '').trim();
-    const host = this.getHost();
-    const result = await host.transcribe({
-      modelKey: paths.encoder,
-      encoder: paths.encoder,
-      decoder: paths.decoder,
-      tokens: paths.tokens,
-      numThreads: this.numThreads,
-      provider: this.provider,
-      language,
-      task: 'transcribe',
-      samples,
-      sampleRate: TARGET_SAMPLE_RATE,
-    });
+    const language = this.model.joiner ? '' : ((opts.language ?? this.defaultLanguage) || '').trim();
+    const { maxChunkSeconds } = this.model;
+    const parts = maxChunkSeconds ? splitAtSilence(samples, TARGET_SAMPLE_RATE, maxChunkSeconds) : [samples];
+    const texts: string[] = [];
+    let detected: string | undefined;
+
+    this.holdModel();
+    try {
+      for (const part of parts) {
+        opts.signal?.throwIfAborted();
+        const result = await this.getHost().transcribe({
+          modelKey: paths.encoder,
+          encoder: paths.encoder,
+          decoder: paths.decoder,
+          ...(paths.joiner ? { joiner: paths.joiner } : {}),
+          tokens: paths.tokens,
+          numThreads: this.numThreads,
+          provider: this.provider,
+          language,
+          task: 'transcribe',
+          samples: part,
+          sampleRate: TARGET_SAMPLE_RATE,
+        });
+        texts.push(result.text.trim());
+        detected ??= result.language;
+      }
+    } finally {
+      this.letModelGo();
+    }
 
     const durationSec = samples.length / TARGET_SAMPLE_RATE;
-    // Prefer Whisper's detected language; else the caller/default hint (when
-    // set) so downstream still gets a BCP-47 tag.
-    const reported = result.language ?? (language || undefined);
+    // Prefer the detected language; else the caller/default hint (when set) so
+    // downstream still gets a BCP-47 tag.
+    const reported = detected ?? (language || undefined);
     const out: {
       text: string;
       language?: string;
       durationSec?: number;
-    } = { text: result.text.trim(), durationSec };
+    } = { text: texts.filter(Boolean).join(' '), durationSec };
     if (reported) out.language = reported;
     return out;
   }
 
   /** Kill this transcriber's sidecar (if any) and drop registration. */
   shutdown(): void {
+    this.cancelIdleRelease();
     this.host?.shutdown();
     this.host = null;
     ACTIVE_STT.delete(this);
   }
 
+  private holdModel(): void {
+    this.running += 1;
+    this.cancelIdleRelease();
+  }
+
+  /** The last transcription to finish starts the idle clock. Killing the sidecar
+   *  is what frees the model's memory; the next call forks a new one. */
+  private letModelGo(): void {
+    this.running -= 1;
+    const { idleReleaseMs } = this.model;
+    if (!idleReleaseMs || this.running > 0) return;
+    this.idleTimer = setTimeout(() => {
+      this.idleTimer = null;
+      this.host?.shutdown();
+      this.host = null;
+    }, idleReleaseMs);
+    this.idleTimer.unref?.();
+  }
+
+  private cancelIdleRelease(): void {
+    if (this.idleTimer) clearTimeout(this.idleTimer);
+    this.idleTimer = null;
+  }
+
   private getHost(): HostClientLike {
     this.host ??= this.hostFactory();
     return this.host;
   }
 
   /** Resolve on-disk paths for the model, downloading its files once. */
-  private async ensureModelFiles(signal?: AbortSignal): Promise<WhisperModelPaths> {
+  private async ensureModelFiles(signal?: AbortSignal): Promise<LocalSttModelPaths> {
     const dir = modelDir(this.model, this.modelsDir);
     let inflight = this.ensuring;
     if (!inflight) {
@@ -213,6 +259,7 @@ export class LocalWhisperTranscriber implements Transcriber {
     return {
       encoder: path.join(dir, this.model.encoder.name),
       decoder: path.join(dir, this.model.decoder.name),
+      ...(this.model.joiner ? { joiner: path.join(dir, this.model.joiner.name) } : {}),
       tokens: path.join(dir, this.model.tokens.name),
     };
   }
@@ -228,7 +275,7 @@ export class LocalWhisperTranscriber implements Transcriber {
         if (pct >= 100) return;
         started = true;
         const mb = Math.round(modelBytes(this.model) / 1_000_000);
-        this.log(`stt-local: first use — downloading Whisper ${this.model.id} (~${mb} MB) to ${this.modelsDir}, one-time`);
+        this.log(`stt-local: first use — downloading ${this.model.label} (~${mb} MB) to ${this.modelsDir}, one-time`);
       }
       if (pct >= lastPct + 10) {
         lastPct = pct - (pct % 10);
@@ -246,8 +293,8 @@ export class LocalWhisperTranscriber implements Transcriber {
       throw new MoxxyError({
         code: 'PLUGIN_LOAD_FAILED',
         message: pkg
-          ? `Local Whisper could not load the sherpa-onnx binary (${pkg}). Reinstall @moxxy/plugin-stt-local so its platform dependency is fetched.`
-          : `Local Whisper has no sherpa-onnx binary for ${process.platform}-${process.arch}.`,
+          ? `Local transcription could not load the sherpa-onnx binary (${pkg}). Reinstall @moxxy/plugin-stt-local so its platform dependency is fetched.`
+          : `Local transcription has no sherpa-onnx binary for ${process.platform}-${process.arch}.`,
         hint: 'Use the OpenAI Whisper backend instead, or run on a supported platform (macOS/Linux/Windows x64, macOS/Linux arm64).',
         context: { platform: process.platform, arch: process.arch },
       });
@@ -262,6 +309,10 @@ export class LocalWhisperTranscriber implements Transcriber {
   }
 }
 
-export function createLocalWhisperTranscriber(opts: LocalWhisperOptions = {}): LocalWhisperTranscriber {
-  return new LocalWhisperTranscriber(opts);
+export function createLocalWhisperTranscriber(opts: LocalSttOptions = {}): LocalSttTranscriber {
+  return new LocalSttTranscriber(opts);
+}
+
+export function createLocalParakeetTranscriber(opts: LocalSttOptions = {}): LocalSttTranscriber {
+  return new LocalSttTranscriber({ ...opts, model: 'parakeet' });
 }

package/src/models.test.ts

@@ -14,8 +14,45 @@ import {
 describe('MODEL_CATALOG', () => {
   const HF = 'https://huggingface.co/csukuangfj/sherpa-onnx-whisper-turbo/resolve/2ca6ff69fc878651b770880507669577ac41c2ff';
 
-  it('pins only Whisper turbo, as its three int8 files on a fixed Hugging Face revision', () => {
-    expect(modelIds()).toEqual(['turbo']);
+  it('pins Whisper turbo and Parakeet, each read by its own transcriber', () => {
+    expect(modelIds()).toEqual(['turbo', 'parakeet']);
+    expect(findModel('turbo')!.transcriber).toBe('local-whisper');
+    expect(findModel('parakeet')!.transcriber).toBe('local-parakeet');
+  });
+
+  it('pins Parakeet as its four int8 files on a fixed Hugging Face revision', () => {
+    const PARAKEET = 'https://huggingface.co/csukuangfj/sherpa-onnx-nemo-parakeet-tdt-0.6b-v3-int8/resolve/2bda32ec70b097a55adaa07d9a7173915b43cc78';
+    const parakeet = findModel('parakeet')!;
+    expect(modelFiles(parakeet)).toEqual([
+      {
+        name: 'encoder.int8.onnx',
+        url: `${PARAKEET}/encoder.int8.onnx`,
+        bytes: 652_184_281,
+        sha256: 'acfc2b4456377e15d04f0243af540b7fe7c992f8d898d751cf134c3a55fd2247',
+      },
+      {
+        name: 'decoder.int8.onnx',
+        url: `${PARAKEET}/decoder.int8.onnx`,
+        bytes: 11_845_275,
+        sha256: '179e50c43d1a9de79c8a24149a2f9bac6eb5981823f2a2ed88d655b24248db4e',
+      },
+      {
+        name: 'joiner.int8.onnx',
+        url: `${PARAKEET}/joiner.int8.onnx`,
+        bytes: 6_355_277,
+        sha256: '3164c13fc2821009440d20fcb5fdc78bff28b4db2f8d0f0b329101719c0948b3',
+      },
+      {
+        name: 'tokens.txt',
+        url: `${PARAKEET}/tokens.txt`,
+        bytes: 93_939,
+        sha256: 'd58544679ea4bc6ac563d1f545eb7d474bd6cfa467f0a6e2c1dc1c7d37e3c35d',
+      },
+    ]);
+    expect(modelDir(parakeet, '/m')).toBe(path.join('/m', 'parakeet'));
+  });
+
+  it('pins Whisper turbo as its three int8 files on a fixed Hugging Face revision', () => {
     const turbo = findModel('turbo')!;
     expect(turbo.encoder).toEqual({
       name: 'turbo-encoder.int8.onnx',
@@ -71,8 +108,8 @@ describe('requireModel', () => {
         expect.unreachable(`${removed} should be rejected`);
       } catch (err) {
         expect((err as { code?: string }).code).toBe('CONFIG_INVALID');
-        expect((err as Error).message).toMatch(/Unknown local Whisper model/);
-        expect((err as { hint?: string }).hint).toBe('Valid models: turbo.');
+        expect((err as Error).message).toMatch(/Unknown local speech model/);
+        expect((err as { hint?: string }).hint).toBe('Valid models: turbo, parakeet.');
       }
     }
   });

package/src/models.ts

@@ -1,15 +1,17 @@
 /**
- * The pinned Whisper model catalog.
+ * The pinned local speech model catalog.
  *
- * The one model is Whisper large-v3 turbo, the multilingual sherpa-onnx int8
- * export. Its three files download as they are from Hugging Face, pinned to a
- * fixed revision and checked against their size and sha256 — byte for byte the
- * files the project's `asr-models` GitHub release packs into a `.tar.bz2`
- * (verified 2026-10-24), but with no archive to unpack: unpacking it in
- * JavaScript took about 67 s against 9 s for the download.
+ * Whisper large-v3 turbo is the multilingual sherpa-onnx int8 export. Its three
+ * files download as they are from Hugging Face, pinned to a fixed revision and
+ * checked against their size and sha256 — byte for byte the files the project's
+ * `asr-models` GitHub release packs into a `.tar.bz2` (verified 2026-10-24), but
+ * with no archive to unpack: unpacking it in JavaScript took about 67 s against
+ * 9 s for the download. Multilingual (not an `.en` export), so Polish and every
+ * other Whisper language work.
  *
- * Multilingual (not an `.en` export), so Polish and every other Whisper
- * language work.
+ * Parakeet TDT 0.6B v3 is the sherpa-onnx int8 export of NVIDIA's transducer
+ * (CC-BY-4.0), pinned the same way. It works out the spoken language itself, in
+ * 25 languages, and takes no language hint.
  */
 
 import path from 'node:path';
@@ -18,25 +20,42 @@ import { MoxxyError } from '@moxxy/sdk';
 import { moxxyPath } from '@moxxy/sdk/server';
 import type { ModelFile } from '@moxxy/model-fetch/files';
 
-export type WhisperModelId = 'turbo';
+export type LocalSttModelId = 'turbo' | 'parakeet';
 
-export interface WhisperModelEntry {
+/** The transcriber that reads Whisper turbo. */
+export const LOCAL_WHISPER_TRANSCRIBER_NAME = 'local-whisper';
+/** The transcriber that reads Parakeet. */
+export const LOCAL_PARAKEET_TRANSCRIBER_NAME = 'local-parakeet';
+
+export interface LocalSttModelEntry {
   /** Stable model id (also the `model` config value and its directory name). */
-  readonly id: WhisperModelId;
+  readonly id: LocalSttModelId;
   /** Human label for UI surfaces / the first-use notice. */
   readonly label: string;
+  /** The registered transcriber that reads this model. */
+  readonly transcriber: string;
   readonly encoder: ModelFile;
   readonly decoder: ModelFile;
+  /** Only a transducer has one; it is what tells the sidecar which engine to load. */
+  readonly joiner?: ModelFile;
   readonly tokens: ModelFile;
+  /** Longer audio is read piece by piece, for a model whose memory grows with it. */
+  readonly maxChunkSeconds?: number;
+  /** Drop the model from memory after this long without use. */
+  readonly idleReleaseMs?: number;
 }
 
 const TURBO_REVISION = '2ca6ff69fc878651b770880507669577ac41c2ff';
 const TURBO_BASE = `https://huggingface.co/csukuangfj/sherpa-onnx-whisper-turbo/resolve/${TURBO_REVISION}`;
 
-export const MODEL_CATALOG: readonly WhisperModelEntry[] = [
+const PARAKEET_REVISION = '2bda32ec70b097a55adaa07d9a7173915b43cc78';
+const PARAKEET_BASE = `https://huggingface.co/csukuangfj/sherpa-onnx-nemo-parakeet-tdt-0.6b-v3-int8/resolve/${PARAKEET_REVISION}`;
+
+export const MODEL_CATALOG: readonly LocalSttModelEntry[] = [
   {
     id: 'turbo',
     label: 'Whisper turbo (multilingual, large-v3 turbo)',
+    transcriber: LOCAL_WHISPER_TRANSCRIBER_NAME,
     encoder: {
       name: 'turbo-encoder.int8.onnx',
       url: `${TURBO_BASE}/turbo-encoder.int8.onnx`,
@@ -56,15 +75,47 @@ export const MODEL_CATALOG: readonly WhisperModelEntry[] = [
       sha256: 'b34b360dbb493e781e479794586d661700670d65564001f23024971d1f2fa126',
     },
   },
+  {
+    id: 'parakeet',
+    label: 'Parakeet TDT 0.6B v3',
+    transcriber: LOCAL_PARAKEET_TRANSCRIBER_NAME,
+    encoder: {
+      name: 'encoder.int8.onnx',
+      url: `${PARAKEET_BASE}/encoder.int8.onnx`,
+      bytes: 652_184_281,
+      sha256: 'acfc2b4456377e15d04f0243af540b7fe7c992f8d898d751cf134c3a55fd2247',
+    },
+    decoder: {
+      name: 'decoder.int8.onnx',
+      url: `${PARAKEET_BASE}/decoder.int8.onnx`,
+      bytes: 11_845_275,
+      sha256: '179e50c43d1a9de79c8a24149a2f9bac6eb5981823f2a2ed88d655b24248db4e',
+    },
+    joiner: {
+      name: 'joiner.int8.onnx',
+      url: `${PARAKEET_BASE}/joiner.int8.onnx`,
+      bytes: 6_355_277,
+      sha256: '3164c13fc2821009440d20fcb5fdc78bff28b4db2f8d0f0b329101719c0948b3',
+    },
+    tokens: {
+      name: 'tokens.txt',
+      url: `${PARAKEET_BASE}/tokens.txt`,
+      bytes: 93_939,
+      sha256: 'd58544679ea4bc6ac563d1f545eb7d474bd6cfa467f0a6e2c1dc1c7d37e3c35d',
+    },
+    // Measured: 5 minutes in one go took 3 GB, and the model holds 850 MB at rest.
+    maxChunkSeconds: 60,
+    idleReleaseMs: 5 * 60_000,
+  },
 ];
 
 /** Every file of a model, in download order. */
-export function modelFiles(entry: WhisperModelEntry): ModelFile[] {
-  return [entry.encoder, entry.decoder, entry.tokens];
+export function modelFiles(entry: LocalSttModelEntry): ModelFile[] {
+  return [entry.encoder, entry.decoder, ...(entry.joiner ? [entry.joiner] : []), entry.tokens];
 }
 
 /** The model's download size in bytes. */
-export function modelBytes(entry: WhisperModelEntry): number {
+export function modelBytes(entry: LocalSttModelEntry): number {
   return modelFiles(entry).reduce((sum, file) => sum + file.bytes, 0);
 }
 
@@ -74,30 +125,30 @@ export function defaultModelsDir(): string {
 }
 
 /** Where a model's files live under the models root. */
-export function modelDir(entry: WhisperModelEntry, modelsDir: string): string {
+export function modelDir(entry: LocalSttModelEntry, modelsDir: string): string {
   return path.join(modelsDir, entry.id);
 }
 
-/** The model used when the caller doesn't pick one — the only one there is. */
-export const DEFAULT_MODEL_ID: WhisperModelId = 'turbo';
+/** The model used when the caller doesn't pick one. */
+export const DEFAULT_MODEL_ID: LocalSttModelId = 'turbo';
 
 /** All valid model ids, for error messages and validation. */
 export function modelIds(): string[] {
   return MODEL_CATALOG.map((m) => m.id);
 }
 
-export function findModel(id: string): WhisperModelEntry | undefined {
+export function findModel(id: string): LocalSttModelEntry | undefined {
   return MODEL_CATALOG.find((m) => m.id === id);
 }
 
 /** Resolve a model id to its catalog entry, or throw a clear, actionable error
  *  listing the valid ids. `field` names where the bad id came from. */
-export function requireModel(id: string, field: string): WhisperModelEntry {
+export function requireModel(id: string, field: string): LocalSttModelEntry {
   const entry = findModel(id);
   if (!entry) {
     throw new MoxxyError({
       code: 'CONFIG_INVALID',
-      message: `Unknown local Whisper model ${JSON.stringify(id)} (${field}).`,
+      message: `Unknown local speech model ${JSON.stringify(id)} (${field}).`,
       hint: `Valid models: ${modelIds().join(', ')}.`,
       context: { field, model: id },
     });