feat(plugins-soniox): surface per-run language segments

.changeset/soniox-language-segments.md

@@ -0,0 +1,6 @@
+---
+'@livekit/agents': patch
+'@livekit/agents-plugin-soniox': patch
+---
+
+Add Soniox STT support and surface per-run source and target language segments on STT speech data.

.changeset/soniox-stt-server-errors.md

@@ -0,0 +1,5 @@
+---
+'@livekit/agents-plugin-soniox': patch
+---
+
+Surface Soniox STT server error frames as API status errors.

agents/src/stt/stt.ts

@@ -75,6 +75,24 @@ export interface SpeechData {
    * May contain multiple entries when a single utterance spans multiple source languages.
    */
   sourceLanguages?: LanguageCode[];
+  /**
+   * The original transcription segments in the source language(s), when translation is active.
+   * Each entry corresponds to the same-indexed entry in `sourceLanguages`.
+   */
+  sourceTexts?: string[];
+  /**
+   * The target language(s) produced by a translation-capable STT service, one entry per
+   * consecutive same-language run, parallel to `targetTexts`.
+   *
+   * `language` holds the dominant or first target language and `targetLanguages` carries the
+   * fine-grained per-run breakdown. Populated when translation is active.
+   */
+  targetLanguages?: LanguageCode[];
+  /**
+   * The translated transcription segments in the target language(s).
+   * Each entry corresponds to the same-indexed entry in `targetLanguages`.
+   */
+  targetTexts?: string[];
   /**
    * Optional plugin-specific metadata (e.g. voice profile, provider diagnostics).
    *

plugins/soniox/README.md

@@ -0,0 +1,3 @@
+# Soniox plugin for LiveKit Agents
+
+Support for Soniox Speech-to-Text streaming.

plugins/soniox/api-extractor.json

@@ -0,0 +1,8 @@
+/**
+ * Config file for API Extractor.  For more info, please visit: https://api-extractor.com
+ */
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "extends": "../../api-extractor-shared.json",
+  "mainEntryPointFilePath": "./dist/index.d.ts"
+}

plugins/soniox/etc/agents-plugin-soniox.api.md

@@ -0,0 +1,102 @@
+## API Report File for "@livekit/agents-plugin-soniox"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { APIConnectOptions } from '@livekit/agents';
+import { AudioBuffer as AudioBuffer_2 } from '@livekit/agents';
+import { stt } from '@livekit/agents';
+
+// @public (undocumented)
+export interface ContextGeneralItem {
+    // (undocumented)
+    key: string;
+    // (undocumented)
+    value: string;
+}
+
+// @public (undocumented)
+export interface ContextObject {
+    general?: ContextGeneralItem[];
+    terms?: string[];
+    text?: string;
+    translationTerms?: ContextTranslationTerm[];
+}
+
+// @public (undocumented)
+export interface ContextTranslationTerm {
+    // (undocumented)
+    source: string;
+    // (undocumented)
+    target: string;
+}
+
+// @public (undocumented)
+export class SpeechStream extends stt.SpeechStream {
+    constructor(stt: STT, opts: STTOptions, connOptions?: APIConnectOptions);
+    // (undocumented)
+    label: string;
+    // (undocumented)
+    protected run(): Promise<void>;
+}
+
+// @public (undocumented)
+export class STT extends stt.STT {
+    constructor(opts?: Partial<STTOptions>);
+    // (undocumented)
+    label: string;
+    // (undocumented)
+    get model(): string;
+    // (undocumented)
+    get provider(): string;
+    // (undocumented)
+    _recognize(_: AudioBuffer_2): Promise<stt.SpeechEvent>;
+    // (undocumented)
+    stream(options?: {
+        connOptions?: APIConnectOptions;
+    }): SpeechStream;
+}
+
+// @public (undocumented)
+export interface STTOptions {
+    // (undocumented)
+    apiKey?: string;
+    // (undocumented)
+    baseUrl: string;
+    // (undocumented)
+    clientReferenceId?: string;
+    // (undocumented)
+    context?: ContextObject | string;
+    // (undocumented)
+    enableLanguageIdentification: boolean;
+    // (undocumented)
+    enableSpeakerDiarization: boolean;
+    // (undocumented)
+    languageHints?: string[];
+    // (undocumented)
+    languageHintsStrict: boolean;
+    maxEndpointDelayMs: number;
+    // (undocumented)
+    model: string;
+    // (undocumented)
+    numChannels: number;
+    // (undocumented)
+    sampleRate: number;
+    // (undocumented)
+    translation?: TranslationConfig;
+}
+
+// @public (undocumented)
+export type TranslationConfig = {
+    type: 'one_way';
+    targetLanguage: string;
+} | {
+    type: 'two_way';
+    languageA: string;
+    languageB: string;
+};
+
+// (No @packageDocumentation comment for this package)
+
+```

plugins/soniox/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@livekit/agents-plugin-soniox",
+  "version": "1.4.4",
+  "description": "Soniox plugin for LiveKit Agents for Node.js",
+  "main": "dist/index.js",
+  "require": "dist/index.cjs",
+  "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"
+    }
+  },
+  "author": "LiveKit",
+  "type": "module",
+  "repository": "git@github.com:livekit/agents-js.git",
+  "license": "Apache-2.0",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup --onSuccess \"pnpm build:types\"",
+    "build:types": "tsc --declaration --emitDeclarationOnly && node ../../scripts/copyDeclarationOutput.js",
+    "clean": "rm -rf dist",
+    "clean:build": "pnpm clean && pnpm build",
+    "lint": "eslint -f unix \"src/**/*.{ts,js}\"",
+    "api:check": "api-extractor run --typescript-compiler-folder ../../node_modules/typescript",
+    "api:update": "api-extractor run --local --typescript-compiler-folder ../../node_modules/typescript --verbose"
+  },
+  "devDependencies": {
+    "@livekit/agents": "workspace:*",
+    "@livekit/rtc-node": "catalog:",
+    "@microsoft/api-extractor": "^7.35.0",
+    "@types/ws": "catalog:",
+    "tsup": "^8.3.5",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "ws": "catalog:"
+  },
+  "peerDependencies": {
+    "@livekit/agents": "workspace:*",
+    "@livekit/rtc-node": "catalog:"
+  }
+}