@kuralle-syrinx/deepgram 4.1.0 → 4.2.0

package/package.json

@@ -1,9 +1,28 @@
 {
   "name": "@kuralle-syrinx/deepgram",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "private": false,
-  "type": "module",
+  "description": "Deepgram adapters for Syrinx — nova-3 STT, Flux turn-aware STT (semantic end-of-turn), and Aura TTS",
+  "keywords": [
+    "voice",
+    "voice-agent",
+    "speech",
+    "syrinx",
+    "deepgram",
+    "speech-to-text",
+    "text-to-speech"
+  ],
   "license": "MIT",
+  "homepage": "https://github.com/kuralle/syrinx#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kuralle/syrinx.git",
+    "directory": "packages/deepgram"
+  },
+  "bugs": {
+    "url": "https://github.com/kuralle/syrinx/issues"
+  },
+  "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
@@ -12,8 +31,8 @@
     "./tts": "./src/tts.ts"
   },
   "dependencies": {
-    "@kuralle-syrinx/core": "4.1.0",
-    "@kuralle-syrinx/ws": "4.1.0"
+    "@kuralle-syrinx/core": "4.2.0",
+    "@kuralle-syrinx/ws": "4.2.0"
   },
   "devDependencies": {
     "@types/ws": "^8.5.0",

package/src/stt.test.ts

@@ -7,6 +7,8 @@ import {
   Route,
   type ConversationMetricPacket,
   type SttErrorPacket,
+  type SttInterimPacket,
+  type SttPartialPacket,
   type SttResultPacket,
 } from "@kuralle-syrinx/core";
 
@@ -59,6 +61,70 @@ async function waitForValue<T>(items: T[], value: T): Promise<void> {
 }
 
 describe("DeepgramSTTPlugin", () => {
+  it("emits stt.partial with word timings alongside unchanged stt.interim", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data, isBinary) => {
+        if (!isBinary) return;
+        socket.send(JSON.stringify({
+          is_final: false,
+          channel: {
+            alternatives: [{
+              transcript: "hello there",
+              confidence: 0.91,
+              words: [
+                { word: "hello", start: 0.12, end: 0.48, confidence: 0.95 },
+                { word: "there", start: 0.5, end: 0.82, confidence: 0.88 },
+              ],
+            }],
+          },
+        }));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new DeepgramSTTPlugin();
+    const interims: SttInterimPacket[] = [];
+    const partials: SttPartialPacket[] = [];
+    bus.on("stt.interim", (pkt) => {
+      interims.push(pkt as SttInterimPacket);
+    });
+    bus.on("stt.partial", (pkt) => {
+      partials.push(pkt as SttPartialPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      endpoint_url: endpointUrl,
+      sample_rate: 16000,
+    });
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      audio: new Uint8Array(640),
+    });
+    await waitFor(partials);
+
+    expect(interims).toEqual([
+      expect.objectContaining({ kind: "stt.interim", contextId: "turn-1", text: "hello there" }),
+    ]);
+    expect(partials).toEqual([
+      expect.objectContaining({
+        kind: "stt.partial",
+        contextId: "turn-1",
+        text: "hello there",
+        wordTimings: [
+          { word: "hello", startMs: 120, endMs: 480, confidence: 0.95 },
+          { word: "there", startMs: 500, endMs: 820, confidence: 0.88 },
+        ],
+      }),
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
   it("uses provider KeepAlive while idle and CloseStream on shutdown", async () => {
     const controlMessages: string[] = [];
     const endpointUrl = await createLocalServer((socket) => {

package/src/stt.ts

@@ -355,7 +355,7 @@ export class DeepgramSTTPlugin implements VoicePlugin {
         this.pushTurnComplete(providerContextId);
       }
     } else {
-      this.pushInterim(transcript, providerContextId);
+      this.pushInterim(transcript, providerContextId, alt);
     }
   }
 
@@ -512,12 +512,25 @@ export class DeepgramSTTPlugin implements VoicePlugin {
   }
 
   /** Emit interim transcript for real-time display. */
-  private pushInterim(transcript: string, contextId = this.currentContextId): void {
+  private pushInterim(
+    transcript: string,
+    contextId = this.currentContextId,
+    alt: Record<string, unknown> | null = null,
+  ): void {
+    const timestampMs = Date.now();
     this.bus?.push(Route.Main, {
       kind: "stt.interim",
       contextId,
-      timestampMs: Date.now(),
+      timestampMs,
+      text: transcript,
+    });
+    const wordTimings = mapProviderWordTimings(alt);
+    this.bus?.push(Route.Main, {
+      kind: "stt.partial",
+      contextId,
+      timestampMs,
       text: transcript,
+      ...(wordTimings ? { wordTimings } : {}),
     });
   }
 
@@ -751,6 +764,31 @@ async function defaultSocketFactory(): Promise<SocketFactory> {
   return mod.createNodeWsSocket;
 }
 
+function mapProviderWordTimings(
+  alt: Record<string, unknown> | null,
+): ReadonlyArray<{ word: string; startMs: number; endMs: number; confidence: number }> | undefined {
+  if (!alt) return undefined;
+  const words = alt["words"];
+  if (!Array.isArray(words)) return undefined;
+  const timings: Array<{ word: string; startMs: number; endMs: number; confidence: number }> = [];
+  for (const entry of words) {
+    if (!entry || typeof entry !== "object") continue;
+    const row = entry as Record<string, unknown>;
+    const word = row["word"];
+    const start = row["start"];
+    const end = row["end"];
+    const confidence = row["confidence"];
+    if (typeof word !== "string" || typeof start !== "number" || typeof end !== "number") continue;
+    timings.push({
+      word,
+      startMs: start * 1000,
+      endMs: end * 1000,
+      confidence: typeof confidence === "number" ? confidence : 0,
+    });
+  }
+  return timings.length > 0 ? timings : undefined;
+}
+
 function providerAlternative(msg: Record<string, unknown>): Record<string, unknown> | null {
   const channel = msg["channel"];
   if (!channel || typeof channel !== "object") return null;