@absolutejs/voice-gladia 0.0.1-beta.1

package/README.md

@@ -0,0 +1,66 @@
+# `@absolutejs/voice-gladia`
+
+Gladia real-time speech-to-text adapter for `@absolutejs/voice`.
+
+Implements Gladia's two-step v2 live handshake directly (no Gladia SDK dep): POST `/v2/live` to create a session and receive a one-time WebSocket URL, connect, stream binary PCM/μ-law/A-law audio, and consume `transcript` / `end_of_utterance` JSON messages. Excellent at multilingual code-switch (Hindi-English, Catalan-Spanish, etc.) thanks to Gladia's language model.
+
+## Install
+
+```sh
+bun add @absolutejs/voice-gladia
+```
+
+`@absolutejs/voice` is a runtime dependency.
+
+## Use
+
+```ts
+import { voice } from "@absolutejs/voice";
+import { gladia } from "@absolutejs/voice-gladia";
+
+const app = voice({
+  stt: gladia({
+    apiKey: process.env.GLADIA_API_KEY!,
+    // optional:
+    model: "solaria-1",
+    languages: ["en"],         // language detection seed
+    codeSwitching: true,       // for multilingual callers
+    realtimeProcessing: { sentences: true },
+  }),
+  // ... tts + other options ...
+});
+```
+
+For mixed Hindi/English callers (CoSHE-style), pair with `languageStrategy`:
+
+```ts
+app.use({
+  stt: gladia({ apiKey, codeSwitching: true }),
+  // and at open() time:
+  // languageStrategy: { mode: 'allow-switching', primaryLanguage: 'en', secondaryLanguages: ['hi'] }
+});
+```
+
+## Options
+
+| Option | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `apiKey` | yes | — | Gladia API key, sent as `X-Gladia-Key`. |
+| `model` | no | `solaria-1` | Gladia model id. |
+| `languages` | no | — | Default language list, overridden when `STTAdapterOpenOptions.languageStrategy` resolves a list. |
+| `codeSwitching` | no | — | Enable mid-utterance language switching. |
+| `realtimeProcessing` | no | — | Forwarded to Gladia's `realtime_processing` config (sentences, diarization, etc.). |
+| `punctuationConfig` | no | — | Forwarded to `punctuation_config`. |
+| `baseUrl` | no | `https://api.gladia.io` | Override for staging / enterprise endpoints. |
+| `sessionPath` | no | `/v2/live` | Override if you proxy Gladia behind a gateway. |
+| `connectTimeoutMs` | no | `8000` | Time to wait for the WebSocket `open` event. |
+| `fetch` | no | `globalThis.fetch` | Inject for tests; opportunistic HTTP/2 multiplexing on outbound HTTPS. |
+| `webSocket.factory` | no | `new WebSocket(url)` | Inject a fake socket for tests. |
+
+## Notes
+
+- Audio sent before the WebSocket open completes is buffered and flushed once the socket is ready.
+- `transcript` messages → `partial` when `data.is_final !== true`, `final` otherwise. Confidence + per-utterance `start` / `end` (converted to ms) are lifted onto the transcript.
+- `end_of_utterance` / `speech_end` → `endOfTurn` with `reason: "vendor"`.
+- `session.close(reason)` sends `{ "type": "stop_recording" }` and then closes the socket cleanly.
+- Supported encodings on `STTAdapterOpenOptions.format.encoding`: `pcm_s16le` → `wav/pcm`, `mulaw` / `pcm_mulaw` → `wav/ulaw`, `alaw` / `pcm_alaw` → `wav/alaw`.

package/dist/gladia.d.ts

@@ -0,0 +1,3 @@
+import type { STTAdapter } from '@absolutejs/voice';
+import type { GladiaSTTOptions } from './types';
+export declare const gladia: (config: GladiaSTTOptions) => STTAdapter;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { gladia } from './gladia';
+export type { GladiaEncoding, GladiaLanguageConfig, GladiaModel, GladiaSTTOptions } from './types';

package/dist/index.js

@@ -0,0 +1,257 @@
+// @bun
+// src/gladia.ts
+var DEFAULT_BASE_URL = "https://api.gladia.io";
+var DEFAULT_SESSION_PATH = "/v2/live";
+var DEFAULT_LANGUAGE = "en";
+var DEFAULT_CONNECT_TIMEOUT_MS = 8000;
+var DEFAULT_MODEL = "solaria-1";
+var isHttpsUrl = (url) => typeof url === "string" ? url.startsWith("https://") : url.protocol === "https:";
+var h2IfHttps = (url) => isHttpsUrl(url) ? { protocol: "http2" } : {};
+var createListenerMap = () => ({
+  close: new Set,
+  endOfTurn: new Set,
+  error: new Set,
+  final: new Set,
+  partial: new Set
+});
+var emit = async (listeners, event, payload) => {
+  for (const listener of listeners[event]) {
+    await listener(payload);
+  }
+};
+var omitUndefined = (value) => Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+var resolveBaseUrl = (config) => (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+var resolveSessionUrl = (config) => {
+  const path = config.sessionPath ?? DEFAULT_SESSION_PATH;
+  return new URL(`${resolveBaseUrl(config)}${path.startsWith("/") ? path : `/${path}`}`);
+};
+var resolveEncoding = (format) => {
+  switch (format.encoding) {
+    case "pcm_s16le":
+      return "wav/pcm";
+    case "pcm_mulaw":
+    case "mulaw":
+      return "wav/ulaw";
+    case "pcm_alaw":
+    case "alaw":
+      return "wav/alaw";
+    default:
+      throw new Error(`Unsupported audio encoding "${String(format.encoding)}" for @absolutejs/voice-gladia. ` + `Use pcm_s16le, mulaw, or alaw.`);
+  }
+};
+var resolveBitDepth = (format) => {
+  switch (format.encoding) {
+    case "pcm_s16le":
+      return 16;
+    case "pcm_mulaw":
+    case "mulaw":
+    case "pcm_alaw":
+    case "alaw":
+      return 8;
+    default:
+      return 16;
+  }
+};
+var resolveLanguages = (openOptions, config) => {
+  const strategy = openOptions.languageStrategy;
+  if (strategy?.mode === "fixed" && strategy.primaryLanguage) {
+    return [strategy.primaryLanguage];
+  }
+  if (strategy?.mode === "allow-switching") {
+    const primary = strategy.primaryLanguage;
+    const secondary = strategy.secondaryLanguages ?? [];
+    const combined = primary ? [primary, ...secondary] : [...secondary];
+    return combined.length > 0 ? combined : config.languages;
+  }
+  if (strategy?.mode === "auto-detect" && strategy.allowedLanguages?.length) {
+    return strategy.allowedLanguages;
+  }
+  return config.languages;
+};
+var buildSessionInitBody = (config, openOptions) => omitUndefined({
+  bit_depth: resolveBitDepth(openOptions.format),
+  channels: openOptions.format.channels ?? 1,
+  encoding: resolveEncoding(openOptions.format),
+  language_config: omitUndefined({
+    code_switching: config.codeSwitching,
+    languages: resolveLanguages(openOptions, config) ?? [DEFAULT_LANGUAGE]
+  }),
+  model: config.model ?? DEFAULT_MODEL,
+  punctuation_config: config.punctuationConfig,
+  realtime_processing: config.realtimeProcessing,
+  sample_rate: openOptions.format.sampleRateHz ?? 16000
+});
+var toUint8Array = (chunk) => {
+  if (chunk instanceof Uint8Array)
+    return chunk;
+  if (ArrayBuffer.isView(chunk)) {
+    return new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+  }
+  return new Uint8Array(chunk);
+};
+var gladia = (config) => {
+  if (!config.apiKey) {
+    throw new Error("@absolutejs/voice-gladia requires an apiKey.");
+  }
+  resolveBaseUrl(config);
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  return {
+    kind: "stt",
+    open: async (openOptions) => {
+      const listeners = createListenerMap();
+      const sessionTarget = resolveSessionUrl(config);
+      const sessionResponse = await fetchImpl(sessionTarget, {
+        ...h2IfHttps(sessionTarget),
+        body: JSON.stringify(buildSessionInitBody(config, openOptions)),
+        headers: {
+          "Content-Type": "application/json",
+          "X-Gladia-Key": config.apiKey
+        },
+        method: "POST"
+      });
+      if (!sessionResponse.ok) {
+        const bodyText = await sessionResponse.text().catch(() => "");
+        throw new Error(`Gladia /v2/live returned ${String(sessionResponse.status)} ${sessionResponse.statusText}${bodyText ? `: ${bodyText.slice(0, 200)}` : ""}`);
+      }
+      const sessionBody = await sessionResponse.json();
+      if (!sessionBody?.url) {
+        throw new Error("Gladia session response did not include a websocket url.");
+      }
+      const factory = config.webSocket?.factory ?? ((target) => new WebSocket(target));
+      const socket = factory(sessionBody.url);
+      let opened = false;
+      let closed = false;
+      let seq = 0;
+      const pendingAudio = [];
+      const connectTimeoutMs = config.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+      const sendAudio = (audio) => {
+        socket.send(audio);
+        seq += 1;
+      };
+      const flushPending = () => {
+        for (const chunk of pendingAudio.splice(0, pendingAudio.length)) {
+          sendAudio(chunk);
+        }
+      };
+      const openPromise = new Promise((resolve, reject) => {
+        const openTimeout = setTimeout(() => {
+          if (opened)
+            return;
+          reject(new Error(`Gladia websocket open timeout after ${String(connectTimeoutMs)}ms`));
+          try {
+            socket.close(1013, "open-timeout");
+          } catch {}
+        }, connectTimeoutMs);
+        socket.addEventListener("open", () => {
+          opened = true;
+          clearTimeout(openTimeout);
+          flushPending();
+          resolve();
+        }, { once: true });
+        socket.addEventListener("error", () => {
+          clearTimeout(openTimeout);
+          if (!opened) {
+            reject(new Error("Gladia websocket failed to open."));
+          }
+        });
+      });
+      socket.addEventListener("message", (event) => {
+        if (typeof event.data !== "string")
+          return;
+        let parsed;
+        try {
+          parsed = JSON.parse(event.data);
+        } catch {
+          return;
+        }
+        if (!parsed)
+          return;
+        const type = parsed.type;
+        const data = parsed.data;
+        if (type === "transcript" && data?.utterance) {
+          const isFinal = data.is_final === true;
+          const utterance = data.utterance;
+          if (!utterance.text)
+            return;
+          const event2 = isFinal ? "final" : "partial";
+          emit(listeners, event2, {
+            receivedAt: Date.now(),
+            transcript: {
+              confidence: utterance.confidence,
+              endedAtMs: typeof utterance.end === "number" ? Math.round(utterance.end * 1000) : undefined,
+              id: `gladia:${isFinal ? "final" : "partial"}:${String(seq)}`,
+              isFinal,
+              language: utterance.language,
+              startedAtMs: typeof utterance.start === "number" ? Math.round(utterance.start * 1000) : undefined,
+              text: utterance.text,
+              vendor: "gladia"
+            },
+            type: event2
+          });
+        }
+        if (type === "end_of_utterance" || type === "speech_end") {
+          emit(listeners, "endOfTurn", {
+            reason: "vendor",
+            receivedAt: Date.now(),
+            type: "endOfTurn"
+          });
+        }
+        if (type === "error") {
+          const message = parsed.data?.message ?? "Gladia error";
+          emit(listeners, "error", {
+            error: new Error(message),
+            recoverable: false,
+            type: "error"
+          });
+        }
+      });
+      socket.addEventListener("close", (event) => {
+        if (closed)
+          return;
+        closed = true;
+        emit(listeners, "close", {
+          code: event.code,
+          reason: event.reason || undefined,
+          recoverable: false,
+          type: "close"
+        });
+      });
+      await openPromise;
+      const session = {
+        close: async (reason) => {
+          if (closed)
+            return;
+          closed = true;
+          try {
+            if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
+              socket.send(JSON.stringify({ type: "stop_recording" }));
+              socket.close(1000, reason);
+            }
+          } catch {}
+        },
+        on: (event, handler) => {
+          listeners[event].add(handler);
+          return () => {
+            listeners[event].delete(handler);
+          };
+        },
+        send: async (audio) => {
+          if (closed)
+            return;
+          const bytes = toUint8Array(audio);
+          if (bytes.byteLength === 0)
+            return;
+          if (!opened) {
+            pendingAudio.push(bytes);
+            return;
+          }
+          sendAudio(bytes);
+        }
+      };
+      return session;
+    }
+  };
+};
+export {
+  gladia
+};

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+export type GladiaModel = 'solaria-1' | (string & {});
+export type GladiaEncoding = 'wav/alaw' | 'wav/pcm' | 'wav/ulaw';
+export type GladiaLanguageConfig = {
+    code_switching?: boolean;
+    languages?: readonly string[];
+};
+export type GladiaSTTOptions = {
+    apiKey: string;
+    baseUrl?: string;
+    codeSwitching?: boolean;
+    connectTimeoutMs?: number;
+    fetch?: typeof fetch;
+    languages?: readonly string[];
+    model?: GladiaModel;
+    punctuationConfig?: Record<string, unknown>;
+    realtimeProcessing?: Record<string, unknown>;
+    sessionPath?: string;
+    webSocket?: {
+        factory?: (url: string) => WebSocket;
+    };
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@absolutejs/voice-gladia",
+	"version": "0.0.1-beta.1",
+	"description": "Gladia real-time speech-to-text adapter for @absolutejs/voice",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/absolutejs/voice-adapters.git",
+		"directory": "gladia"
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"license": "CC BY-NC 4.0",
+	"author": "Alex Kahn",
+	"scripts": {
+		"build": "rm -rf dist && bun build ./src/index.ts --outdir dist --target bun --external @absolutejs/voice && tsc --emitDeclarationOnly --project tsconfig.json",
+		"format": "prettier --write \"./**/*.{js,ts,json,md}\"",
+		"release": "bun run format && bun run build && bun publish --access public",
+		"test": "bun test",
+		"typecheck": "bun run tsc --noEmit"
+	},
+	"dependencies": {
+		"@absolutejs/voice": "0.0.22-beta.471"
+	},
+	"devDependencies": {
+		"@types/bun": "1.3.9",
+		"typescript": "^5.9.3"
+	}
+}