livekit-plugin-parrot-stt 0.1.0

package/dist/index.js

@@ -0,0 +1,280 @@
+// src/index.ts
+import { Plugin } from "@livekit/agents";
+
+// src/stt.ts
+import {
+  AudioByteStream,
+  asLanguageCode,
+  log,
+  stt
+} from "@livekit/agents";
+import { WebSocket } from "ws";
+
+// src/models.ts
+var envInt = (name, fallback) => {
+  const v = process.env[name];
+  if (v === void 0 || v === "") return fallback;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : fallback;
+};
+var defaultRinggSTTOptions = {
+  url: process.env.RINGG_STT_URL ?? "wss://prod-api.ringg.ai/stt/v1/stream",
+  apiKey: process.env.RINGG_STT_API_KEY ?? "",
+  language: process.env.RINGG_STT_LANGUAGE ?? "en",
+  sampleRate: envInt("RINGG_STT_SAMPLE_RATE", 16e3),
+  encoding: process.env.RINGG_STT_ENCODING ?? "int16",
+  mode: process.env.RINGG_STT_MODE ?? "stream",
+  enableCapPunc: true,
+  vadTailSilMs: 200,
+  vadConfidence: 0.55,
+  acceptClientVadEvents: false,
+  keepaliveIntervalMs: 3e4,
+  finalizeGraceMs: 1500
+};
+var buildStartPayload = (opts) => ({
+  type: "start",
+  sample_rate: opts.sampleRate,
+  encoding: opts.encoding,
+  language: opts.language,
+  mode: opts.mode,
+  vad_tail_sil_ms: opts.vadTailSilMs,
+  vad_confidence: opts.vadConfidence,
+  enable_cap_punc: opts.enableCapPunc,
+  accept_client_vad_events: opts.acceptClientVadEvents,
+  api_key: opts.apiKey
+});
+
+// src/stt.ts
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var STT = class extends stt.STT {
+  label = "ringg.STT";
+  #opts;
+  constructor(opts = {}) {
+    super({ streaming: true, interimResults: true });
+    this.#opts = { ...defaultRinggSTTOptions, ...opts };
+    if (!this.#opts.apiKey) {
+      throw new Error(
+        "Ringg STT: API key is required \u2014 set $RINGG_STT_API_KEY or pass { apiKey }."
+      );
+    }
+    if (!this.#opts.url) {
+      throw new Error("Ringg STT: url is required \u2014 set $RINGG_STT_URL or pass { url }.");
+    }
+  }
+  get provider() {
+    return "ringg";
+  }
+  get model() {
+    return `ringg-parrot-${this.#opts.language}`;
+  }
+  updateOptions(opts) {
+    this.#opts = { ...this.#opts, ...opts };
+  }
+  async _recognize(_frame) {
+    throw new Error(
+      "Ringg STT plugin is streaming-only; use stream(). (Ringg also exposes a REST /transcriptions endpoint, but it is not wired into this plugin.)"
+    );
+  }
+  stream(options) {
+    return new SpeechStream(this, this.#opts, options?.connOptions);
+  }
+};
+var SpeechStream = class _SpeechStream extends stt.SpeechStream {
+  label = "ringg.SpeechStream";
+  #opts;
+  #logger = log();
+  #speaking = false;
+  #requestId;
+  constructor(sttImpl, opts, connOptions) {
+    super(sttImpl, opts.sampleRate, connOptions);
+    this.#opts = opts;
+  }
+  async run() {
+    const ws = new WebSocket(this.#opts.url);
+    ws.binaryType = "nodebuffer";
+    await new Promise((resolve, reject) => {
+      const onErr = (err) => reject(err);
+      ws.once("open", () => {
+        ws.off("error", onErr);
+        resolve();
+      });
+      ws.once("error", onErr);
+    });
+    ws.send(JSON.stringify(buildStartPayload(this.#opts)));
+    await new Promise((resolve, reject) => {
+      const onMsg = (data, isBinary) => {
+        if (isBinary) return;
+        let ev;
+        try {
+          ev = JSON.parse(data.toString());
+        } catch {
+          return;
+        }
+        if (ev.type === "ready") {
+          this.#requestId = ev.request_id;
+          cleanup();
+          resolve();
+        } else if (ev.type === "error") {
+          cleanup();
+          reject(
+            new Error(
+              `Ringg STT: handshake rejected \u2014 ${ev.detail ?? "unknown error"}`
+            )
+          );
+        }
+      };
+      const onClose = (code) => {
+        cleanup();
+        reject(new Error(`Ringg STT: connection closed during handshake (code ${code})`));
+      };
+      const cleanup = () => {
+        ws.off("message", onMsg);
+        ws.off("close", onClose);
+      };
+      ws.on("message", onMsg);
+      ws.once("close", onClose);
+    });
+    this.#logger.child({ url: this.#opts.url, language: this.#opts.language, requestId: this.#requestId }).debug("ringg stt: connected");
+    let closed = false;
+    const closeWs = () => {
+      if (!closed) {
+        closed = true;
+        try {
+          ws.close();
+        } catch {
+        }
+      }
+    };
+    let keepalive;
+    if (this.#opts.keepaliveIntervalMs > 0) {
+      keepalive = setInterval(() => {
+        if (ws.readyState === WebSocket.OPEN) {
+          try {
+            ws.send(JSON.stringify({ type: "ping" }));
+          } catch {
+          }
+        }
+      }, this.#opts.keepaliveIntervalMs);
+    }
+    const recvTask = new Promise((resolve, reject) => {
+      ws.on("message", (data, isBinary) => {
+        if (isBinary) return;
+        let ev;
+        try {
+          ev = JSON.parse(data.toString());
+        } catch {
+          return;
+        }
+        this.#handleEvent(ev);
+      });
+      ws.once("close", () => resolve());
+      ws.once("error", (err) => reject(err));
+    });
+    const sendTask = async () => {
+      const samples20ms = Math.floor(this.#opts.sampleRate / 50);
+      const bstream = new AudioByteStream(this.#opts.sampleRate, 1, samples20ms);
+      const shipFrames = (frames) => {
+        for (const f of frames) {
+          if (ws.readyState === WebSocket.OPEN) {
+            ws.send(new Uint8Array(f.data.buffer, f.data.byteOffset, f.data.byteLength));
+          }
+        }
+      };
+      for (; ; ) {
+        if (closed) break;
+        const { done, value } = await this.input.next();
+        if (done) break;
+        if (value === _SpeechStream.FLUSH_SENTINEL) {
+          shipFrames(bstream.flush());
+        } else {
+          shipFrames(bstream.write(value.data.buffer));
+        }
+      }
+      shipFrames(bstream.flush());
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: "end" }));
+      }
+    };
+    const abortPromise = new Promise((resolve) => {
+      const signal = this.abortController.signal;
+      if (signal.aborted) return resolve();
+      signal.addEventListener("abort", () => resolve(), { once: true });
+    });
+    const finiteInputPath = (async () => {
+      await sendTask();
+      await sleep(this.#opts.finalizeGraceMs);
+    })();
+    try {
+      await Promise.race([abortPromise, recvTask, finiteInputPath]);
+    } finally {
+      if (keepalive) clearInterval(keepalive);
+      closeWs();
+      await recvTask.catch(() => {
+      });
+    }
+  }
+  #handleEvent(ev) {
+    switch (ev.type) {
+      case "transcript": {
+        const t = ev;
+        const text = (t.transcription ?? "").trim();
+        if (!text) return;
+        if (!this.#speaking) {
+          this.#speaking = true;
+          this.queue.put({ type: stt.SpeechEventType.START_OF_SPEECH });
+        }
+        const data = {
+          language: asLanguageCode(t.language ?? this.#opts.language),
+          text,
+          startTime: 0,
+          endTime: 0,
+          confidence: 1
+        };
+        if (t.is_final) {
+          this.queue.put({
+            type: stt.SpeechEventType.FINAL_TRANSCRIPT,
+            alternatives: [data],
+            requestId: this.#requestId
+          });
+          if (this.#speaking) {
+            this.#speaking = false;
+            this.queue.put({ type: stt.SpeechEventType.END_OF_SPEECH });
+          }
+        } else {
+          this.queue.put({
+            type: stt.SpeechEventType.INTERIM_TRANSCRIPT,
+            alternatives: [data],
+            requestId: this.#requestId
+          });
+        }
+        break;
+      }
+      case "error": {
+        this.#logger.child({ event: ev }).error("ringg stt: server error");
+        break;
+      }
+      // ready (duplicate), ack, pong, and unknown types are ignored
+      default:
+        break;
+    }
+  }
+};
+
+// src/index.ts
+var RinggPlugin = class extends Plugin {
+  constructor() {
+    super({
+      title: "ringg",
+      version: "0.1.0",
+      package: "livekit-plugin-parrot-stt"
+    });
+  }
+};
+Plugin.registerPlugin(new RinggPlugin());
+export {
+  STT,
+  SpeechStream,
+  buildStartPayload,
+  defaultRinggSTTOptions
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/stt.ts","../src/models.ts"],"sourcesContent":["// livekit-plugin-parrot-stt — Ringg Parrot STT for LiveKit Agents (Node.js)\n\nimport { Plugin } from '@livekit/agents';\n\nexport * from './stt.js';\nexport * from './models.js';\n\nclass RinggPlugin extends Plugin {\n  constructor() {\n    super({\n      title: 'ringg',\n      version: '0.1.0',\n      package: 'livekit-plugin-parrot-stt',\n    });\n  }\n}\n\nPlugin.registerPlugin(new RinggPlugin());\n","// Ringg Parrot STT plugin for LiveKit Agents.\n//\n// Implements the streaming STT interface (`stt.STT` + `stt.SpeechStream`) by\n// speaking the Ringg WebSocket protocol directly (there is no JS SDK).\n\nimport {\n  type APIConnectOptions,\n  type AudioBuffer,\n  AudioByteStream,\n  asLanguageCode,\n  log,\n  stt,\n} from '@livekit/agents';\nimport type { AudioFrame } from '@livekit/rtc-node';\nimport { type RawData, WebSocket } from 'ws';\nimport {\n  type RinggSTTOptions,\n  type RinggServerEvent,\n  type RinggTranscriptEvent,\n  buildStartPayload,\n  defaultRinggSTTOptions,\n} from './models.js';\n\nconst sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));\n\nexport class STT extends stt.STT {\n  label = 'ringg.STT';\n  #opts: RinggSTTOptions;\n\n  constructor(opts: Partial<RinggSTTOptions> = {}) {\n    super({ streaming: true, interimResults: true });\n    this.#opts = { ...defaultRinggSTTOptions, ...opts };\n    if (!this.#opts.apiKey) {\n      throw new Error(\n        'Ringg STT: API key is required — set $RINGG_STT_API_KEY or pass { apiKey }.',\n      );\n    }\n    if (!this.#opts.url) {\n      throw new Error('Ringg STT: url is required — set $RINGG_STT_URL or pass { url }.');\n    }\n  }\n\n  get provider(): string {\n    return 'ringg';\n  }\n\n  get model(): string {\n    return `ringg-parrot-${this.#opts.language}`;\n  }\n\n  updateOptions(opts: Partial<RinggSTTOptions>): void {\n    this.#opts = { ...this.#opts, ...opts };\n  }\n\n  async _recognize(_frame: AudioBuffer): Promise<stt.SpeechEvent> {\n    throw new Error(\n      'Ringg STT plugin is streaming-only; use stream(). ' +\n        '(Ringg also exposes a REST /transcriptions endpoint, but it is not wired into this plugin.)',\n    );\n  }\n\n  stream(options?: { connOptions?: APIConnectOptions }): stt.SpeechStream {\n    return new SpeechStream(this, this.#opts, options?.connOptions);\n  }\n}\n\nexport class SpeechStream extends stt.SpeechStream {\n  label = 'ringg.SpeechStream';\n  #opts: RinggSTTOptions;\n  #logger = log();\n  #speaking = false;\n  #requestId?: string;\n\n  constructor(sttImpl: STT, opts: RinggSTTOptions, connOptions?: APIConnectOptions) {\n    // Passing sampleRate as `neededSampleRate` makes the base class resample\n    // incoming (typically 48kHz) LiveKit frames down to Ringg's rate for us.\n    super(sttImpl, opts.sampleRate, connOptions);\n    this.#opts = opts;\n  }\n\n  protected async run(): Promise<void> {\n    const ws = new WebSocket(this.#opts.url);\n    ws.binaryType = 'nodebuffer';\n\n    // 1) wait for the socket to open\n    await new Promise<void>((resolve, reject) => {\n      const onErr = (err: Error) => reject(err);\n      ws.once('open', () => {\n        ws.off('error', onErr);\n        resolve();\n      });\n      ws.once('error', onErr);\n    });\n\n    // 2) send the `start` handshake and wait for the `ready` reply\n    ws.send(JSON.stringify(buildStartPayload(this.#opts)));\n    await new Promise<void>((resolve, reject) => {\n      const onMsg = (data: RawData, isBinary: boolean) => {\n        if (isBinary) return;\n        let ev: RinggServerEvent;\n        try {\n          ev = JSON.parse(data.toString());\n        } catch {\n          return;\n        }\n        if (ev.type === 'ready') {\n          this.#requestId = (ev as { request_id?: string }).request_id;\n          cleanup();\n          resolve();\n        } else if (ev.type === 'error') {\n          cleanup();\n          reject(\n            new Error(\n              `Ringg STT: handshake rejected — ${(ev as { detail?: string }).detail ?? 'unknown error'}`,\n            ),\n          );\n        }\n      };\n      const onClose = (code: number) => {\n        cleanup();\n        reject(new Error(`Ringg STT: connection closed during handshake (code ${code})`));\n      };\n      const cleanup = () => {\n        ws.off('message', onMsg);\n        ws.off('close', onClose);\n      };\n      ws.on('message', onMsg);\n      ws.once('close', onClose);\n    });\n\n    this.#logger\n      .child({ url: this.#opts.url, language: this.#opts.language, requestId: this.#requestId })\n      .debug('ringg stt: connected');\n\n    let closed = false;\n    const closeWs = () => {\n      if (!closed) {\n        closed = true;\n        try {\n          ws.close();\n        } catch {\n          /* ignore */\n        }\n      }\n    };\n\n    // keepalive: application-level JSON ping (Ringg replies with `pong`)\n    let keepalive: ReturnType<typeof setInterval> | undefined;\n    if (this.#opts.keepaliveIntervalMs > 0) {\n      keepalive = setInterval(() => {\n        if (ws.readyState === WebSocket.OPEN) {\n          try {\n            ws.send(JSON.stringify({ type: 'ping' }));\n          } catch {\n            /* ignore */\n          }\n        }\n      }, this.#opts.keepaliveIntervalMs);\n    }\n\n    // 3) receive loop — resolves when the server closes the socket\n    const recvTask = new Promise<void>((resolve, reject) => {\n      ws.on('message', (data: RawData, isBinary: boolean) => {\n        if (isBinary) return; // Ringg only sends JSON text frames\n        let ev: RinggServerEvent;\n        try {\n          ev = JSON.parse(data.toString());\n        } catch {\n          return;\n        }\n        this.#handleEvent(ev);\n      });\n      ws.once('close', () => resolve());\n      ws.once('error', (err) => reject(err));\n    });\n\n    // 4) send loop — reads resampled frames from `this.input`, ships raw PCM16\n    const sendTask = async () => {\n      const samples20ms = Math.floor(this.#opts.sampleRate / 50); // 20ms chunks\n      const bstream = new AudioByteStream(this.#opts.sampleRate, 1, samples20ms);\n      const shipFrames = (frames: AudioFrame[]) => {\n        for (const f of frames) {\n          if (ws.readyState === WebSocket.OPEN) {\n            // send exactly this frame's bytes (raw PCM16 LE), regardless of view offset\n            ws.send(new Uint8Array(f.data.buffer, f.data.byteOffset, f.data.byteLength));\n          }\n        }\n      };\n\n      for (;;) {\n        if (closed) break;\n        const { done, value } = await this.input.next();\n        if (done) break;\n        if (value === SpeechStream.FLUSH_SENTINEL) {\n          shipFrames(bstream.flush());\n        } else {\n          shipFrames(bstream.write((value as AudioFrame).data.buffer));\n        }\n      }\n\n      // input exhausted: flush remaining audio and ask the server to finalize\n      shipFrames(bstream.flush());\n      if (ws.readyState === WebSocket.OPEN) {\n        ws.send(JSON.stringify({ type: 'end' }));\n      }\n    };\n\n    // abort (session close / cancel) → stop promptly\n    const abortPromise = new Promise<void>((resolve) => {\n      const signal = this.abortController.signal;\n      if (signal.aborted) return resolve();\n      signal.addEventListener('abort', () => resolve(), { once: true });\n    });\n\n    // finite input (a file): after the send loop finishes, wait a grace period\n    // for trailing final transcripts, then let the socket close.\n    const finiteInputPath = (async () => {\n      await sendTask();\n      await sleep(this.#opts.finalizeGraceMs);\n    })();\n\n    try {\n      await Promise.race([abortPromise, recvTask, finiteInputPath]);\n    } finally {\n      if (keepalive) clearInterval(keepalive);\n      closeWs();\n      // let recvTask settle so its listeners are cleaned up\n      await recvTask.catch(() => {});\n    }\n  }\n\n  #handleEvent(ev: RinggServerEvent): void {\n    switch (ev.type) {\n      case 'transcript': {\n        const t = ev as RinggTranscriptEvent;\n        const text = (t.transcription ?? '').trim();\n        if (!text) return;\n\n        if (!this.#speaking) {\n          this.#speaking = true;\n          this.queue.put({ type: stt.SpeechEventType.START_OF_SPEECH });\n        }\n\n        const data: stt.SpeechData = {\n          language: asLanguageCode(t.language ?? this.#opts.language),\n          text,\n          startTime: 0,\n          endTime: 0,\n          confidence: 1.0,\n        };\n\n        if (t.is_final) {\n          this.queue.put({\n            type: stt.SpeechEventType.FINAL_TRANSCRIPT,\n            alternatives: [data],\n            requestId: this.#requestId,\n          });\n          if (this.#speaking) {\n            this.#speaking = false;\n            this.queue.put({ type: stt.SpeechEventType.END_OF_SPEECH });\n          }\n        } else {\n          this.queue.put({\n            type: stt.SpeechEventType.INTERIM_TRANSCRIPT,\n            alternatives: [data],\n            requestId: this.#requestId,\n          });\n        }\n        break;\n      }\n      case 'error': {\n        this.#logger.child({ event: ev }).error('ringg stt: server error');\n        break;\n      }\n      // ready (duplicate), ack, pong, and unknown types are ignored\n      default:\n        break;\n    }\n  }\n}\n","// Types and defaults for the Ringg Parrot STT plugin.\n//\n// The wire protocol is the one implemented by the Python `ringglabs` SDK\n// (ringglabs.stt) and used by the Pipecat `RinggSTTService`:\n//   - connect to a WebSocket\n//   - send a JSON `start` frame (auth = `api_key` inside this frame)\n//   - stream raw binary PCM16 (little-endian, mono) audio frames\n//   - receive JSON `transcript` events discriminated by `is_final`\n\nexport type RinggEncoding = 'int16' | 'linear16' | 'float32' | 'int32';\nexport type RinggMode = 'stream' | 'on_final';\n// hi | en are the documented values; keep it open for forward-compat.\nexport type RinggLanguage = 'hi' | 'en' | (string & {});\n\n/** Resolved options for {@link STT}. */\nexport interface RinggSTTOptions {\n  /** Full WebSocket URL, e.g. `wss://prod-api.ringg.ai/stt/v1/stream`. */\n  url: string;\n  /** Ringg API key. Sent inside the `start` JSON frame (not a header). */\n  apiKey: string;\n  /** Language code sent to the server (default `en`). */\n  language: RinggLanguage;\n  /** Audio sample rate the plugin sends to Ringg. LiveKit frames are resampled to this. */\n  sampleRate: number;\n  /** Audio encoding declared to the server. LiveKit gives PCM16, so `int16`. */\n  encoding: RinggEncoding;\n  /** `stream` = interim + final; `on_final` = finals only. */\n  mode: RinggMode;\n  /** Ask the server for capitalisation/punctuation. */\n  enableCapPunc: boolean;\n  /** Server-VAD trailing silence (ms) before finalizing a segment. */\n  vadTailSilMs: number;\n  /** Server-VAD confidence threshold (0..1). */\n  vadConfidence: number;\n  /** If true, the client is expected to send speaking-boundary events (advanced). */\n  acceptClientVadEvents: boolean;\n  /** Application-level keepalive ping interval (ms). 0 disables. */\n  keepaliveIntervalMs: number;\n  /** After the input ends, how long to keep reading for trailing finals (ms). */\n  finalizeGraceMs: number;\n}\n\nconst envInt = (name: string, fallback: number): number => {\n  const v = process.env[name];\n  if (v === undefined || v === '') return fallback;\n  const n = Number(v);\n  return Number.isFinite(n) ? n : fallback;\n};\n\nexport const defaultRinggSTTOptions: RinggSTTOptions = {\n  url: process.env.RINGG_STT_URL ?? 'wss://prod-api.ringg.ai/stt/v1/stream',\n  apiKey: process.env.RINGG_STT_API_KEY ?? '',\n  language: (process.env.RINGG_STT_LANGUAGE as RinggLanguage) ?? 'en',\n  sampleRate: envInt('RINGG_STT_SAMPLE_RATE', 16000),\n  encoding: (process.env.RINGG_STT_ENCODING as RinggEncoding) ?? 'int16',\n  mode: (process.env.RINGG_STT_MODE as RinggMode) ?? 'stream',\n  enableCapPunc: true,\n  vadTailSilMs: 200,\n  vadConfidence: 0.55,\n  acceptClientVadEvents: false,\n  keepaliveIntervalMs: 30000,\n  finalizeGraceMs: 1500,\n};\n\n// ---- Server → client wire events (JSON text frames) ----\n\nexport interface RinggReadyEvent {\n  type: 'ready';\n  request_id: string;\n  [k: string]: unknown;\n}\n\nexport interface RinggTranscriptEvent {\n  type: 'transcript';\n  transcription: string;\n  is_final: boolean;\n  language?: string;\n  request_id?: string;\n  segment_idx?: number;\n  [k: string]: unknown;\n}\n\nexport interface RinggErrorEvent {\n  type: 'error';\n  detail: string;\n  code?: string;\n  status_code?: number;\n}\n\nexport interface RinggAckEvent {\n  type: 'ack';\n  ack_for: string;\n  state: string;\n}\n\nexport interface RinggPongEvent {\n  type: 'pong';\n  timestamp: number;\n}\n\nexport type RinggServerEvent =\n  | RinggReadyEvent\n  | RinggTranscriptEvent\n  | RinggErrorEvent\n  | RinggAckEvent\n  | RinggPongEvent\n  | { type: string; [k: string]: unknown };\n\n/** Build the JSON `start` handshake payload. */\nexport const buildStartPayload = (opts: RinggSTTOptions): Record<string, unknown> => ({\n  type: 'start',\n  sample_rate: opts.sampleRate,\n  encoding: opts.encoding,\n  language: opts.language,\n  mode: opts.mode,\n  vad_tail_sil_ms: opts.vadTailSilMs,\n  vad_confidence: opts.vadConfidence,\n  enable_cap_punc: opts.enableCapPunc,\n  accept_client_vad_events: opts.acceptClientVadEvents,\n  api_key: opts.apiKey,\n});\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "livekit-plugin-parrot-stt",
+  "version": "0.1.0",
+  "description": "Ringg Parrot Speech-to-Text plugin for LiveKit Agents (Node.js)",
+  "keywords": [
+    "livekit",
+    "livekit-agents",
+    "stt",
+    "speech-to-text",
+    "ringg",
+    "parrot",
+    "asr"
+  ],
+  "license": "Apache-2.0",
+  "author": "Ringg AI",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Stonkr/livekit-plugin-parrot-stt.git"
+  },
+  "homepage": "https://github.com/Stonkr/livekit-plugin-parrot-stt#readme",
+  "bugs": "https://github.com/Stonkr/livekit-plugin-parrot-stt/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "ws": "^8.21.1"
+  },
+  "peerDependencies": {
+    "@livekit/agents": "^1.5.0",
+    "@livekit/rtc-node": "^0.13.0"
+  },
+  "devDependencies": {
+    "@livekit/agents": "^1.5.3",
+    "@livekit/rtc-node": "^0.13.31",
+    "@types/node": "^22.10.0",
+    "@types/ws": "^8.18.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+// livekit-plugin-parrot-stt — Ringg Parrot STT for LiveKit Agents (Node.js)
+
+import { Plugin } from '@livekit/agents';
+
+export * from './stt.js';
+export * from './models.js';
+
+class RinggPlugin extends Plugin {
+  constructor() {
+    super({
+      title: 'ringg',
+      version: '0.1.0',
+      package: 'livekit-plugin-parrot-stt',
+    });
+  }
+}
+
+Plugin.registerPlugin(new RinggPlugin());

package/src/models.ts

@@ -0,0 +1,121 @@
+// Types and defaults for the Ringg Parrot STT plugin.
+//
+// The wire protocol is the one implemented by the Python `ringglabs` SDK
+// (ringglabs.stt) and used by the Pipecat `RinggSTTService`:
+//   - connect to a WebSocket
+//   - send a JSON `start` frame (auth = `api_key` inside this frame)
+//   - stream raw binary PCM16 (little-endian, mono) audio frames
+//   - receive JSON `transcript` events discriminated by `is_final`
+
+export type RinggEncoding = 'int16' | 'linear16' | 'float32' | 'int32';
+export type RinggMode = 'stream' | 'on_final';
+// hi | en are the documented values; keep it open for forward-compat.
+export type RinggLanguage = 'hi' | 'en' | (string & {});
+
+/** Resolved options for {@link STT}. */
+export interface RinggSTTOptions {
+  /** Full WebSocket URL, e.g. `wss://prod-api.ringg.ai/stt/v1/stream`. */
+  url: string;
+  /** Ringg API key. Sent inside the `start` JSON frame (not a header). */
+  apiKey: string;
+  /** Language code sent to the server (default `en`). */
+  language: RinggLanguage;
+  /** Audio sample rate the plugin sends to Ringg. LiveKit frames are resampled to this. */
+  sampleRate: number;
+  /** Audio encoding declared to the server. LiveKit gives PCM16, so `int16`. */
+  encoding: RinggEncoding;
+  /** `stream` = interim + final; `on_final` = finals only. */
+  mode: RinggMode;
+  /** Ask the server for capitalisation/punctuation. */
+  enableCapPunc: boolean;
+  /** Server-VAD trailing silence (ms) before finalizing a segment. */
+  vadTailSilMs: number;
+  /** Server-VAD confidence threshold (0..1). */
+  vadConfidence: number;
+  /** If true, the client is expected to send speaking-boundary events (advanced). */
+  acceptClientVadEvents: boolean;
+  /** Application-level keepalive ping interval (ms). 0 disables. */
+  keepaliveIntervalMs: number;
+  /** After the input ends, how long to keep reading for trailing finals (ms). */
+  finalizeGraceMs: number;
+}
+
+const envInt = (name: string, fallback: number): number => {
+  const v = process.env[name];
+  if (v === undefined || v === '') return fallback;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : fallback;
+};
+
+export const defaultRinggSTTOptions: RinggSTTOptions = {
+  url: process.env.RINGG_STT_URL ?? 'wss://prod-api.ringg.ai/stt/v1/stream',
+  apiKey: process.env.RINGG_STT_API_KEY ?? '',
+  language: (process.env.RINGG_STT_LANGUAGE as RinggLanguage) ?? 'en',
+  sampleRate: envInt('RINGG_STT_SAMPLE_RATE', 16000),
+  encoding: (process.env.RINGG_STT_ENCODING as RinggEncoding) ?? 'int16',
+  mode: (process.env.RINGG_STT_MODE as RinggMode) ?? 'stream',
+  enableCapPunc: true,
+  vadTailSilMs: 200,
+  vadConfidence: 0.55,
+  acceptClientVadEvents: false,
+  keepaliveIntervalMs: 30000,
+  finalizeGraceMs: 1500,
+};
+
+// ---- Server → client wire events (JSON text frames) ----
+
+export interface RinggReadyEvent {
+  type: 'ready';
+  request_id: string;
+  [k: string]: unknown;
+}
+
+export interface RinggTranscriptEvent {
+  type: 'transcript';
+  transcription: string;
+  is_final: boolean;
+  language?: string;
+  request_id?: string;
+  segment_idx?: number;
+  [k: string]: unknown;
+}
+
+export interface RinggErrorEvent {
+  type: 'error';
+  detail: string;
+  code?: string;
+  status_code?: number;
+}
+
+export interface RinggAckEvent {
+  type: 'ack';
+  ack_for: string;
+  state: string;
+}
+
+export interface RinggPongEvent {
+  type: 'pong';
+  timestamp: number;
+}
+
+export type RinggServerEvent =
+  | RinggReadyEvent
+  | RinggTranscriptEvent
+  | RinggErrorEvent
+  | RinggAckEvent
+  | RinggPongEvent
+  | { type: string; [k: string]: unknown };
+
+/** Build the JSON `start` handshake payload. */
+export const buildStartPayload = (opts: RinggSTTOptions): Record<string, unknown> => ({
+  type: 'start',
+  sample_rate: opts.sampleRate,
+  encoding: opts.encoding,
+  language: opts.language,
+  mode: opts.mode,
+  vad_tail_sil_ms: opts.vadTailSilMs,
+  vad_confidence: opts.vadConfidence,
+  enable_cap_punc: opts.enableCapPunc,
+  accept_client_vad_events: opts.acceptClientVadEvents,
+  api_key: opts.apiKey,
+});