Standardize LanguageCode handling (#1120)

Author: toubatbrian

.changeset/hot-planets-juggle.md

@@ -0,0 +1,14 @@
+---
+"@livekit/agents": patch
+"@livekit/agents-plugin-baseten": patch
+"@livekit/agents-plugin-cartesia": patch
+"@livekit/agents-plugin-deepgram": patch
+"@livekit/agents-plugin-elevenlabs": patch
+"@livekit/agents-plugin-google": patch
+"@livekit/agents-plugin-livekit": patch
+"@livekit/agents-plugin-neuphonic": patch
+"@livekit/agents-plugin-openai": patch
+"@livekit/agents-plugin-sarvam": patch
+---
+
+Standardize LanguageCode handling

agents/src/index.ts

@@ -9,33 +9,31 @@
  * @see {@link https://docs.livekit.io/agents/overview | LiveKit Agents documentation}
  * @packageDocumentation
  */
-import * as beta from './beta/index.js';
-import * as cli from './cli.js';
-import * as inference from './inference/index.js';
-import * as ipc from './ipc/index.js';
-import * as llm from './llm/index.js';
-import * as metrics from './metrics/index.js';
-import * as stream from './stream/index.js';
-import * as stt from './stt/index.js';
-import * as telemetry from './telemetry/index.js';
-import * as tokenize from './tokenize/index.js';
-import * as tts from './tts/index.js';
-import * as voice from './voice/index.js';
-
 export * from './_exceptions.js';
 export * from './audio.js';
+export * as beta from './beta/index.js';
+export * as cli from './cli.js';
 export * from './connection_pool.js';
 export * from './generator.js';
+export * as inference from './inference/index.js';
 export * from './inference_runner.js';
+export * as ipc from './ipc/index.js';
 export * from './job.js';
+export * from './language.js';
+export * as llm from './llm/index.js';
 export * from './log.js';
+export * as metrics from './metrics/index.js';
 export * from './plugin.js';
+export * as stream from './stream/index.js';
+export * as stt from './stt/index.js';
+export * as telemetry from './telemetry/index.js';
+export * as tokenize from './tokenize/index.js';
 export * from './transcription.js';
+export * as tts from './tts/index.js';
 export * from './types.js';
 export * from './utils.js';
 export * from './vad.js';
 export * from './version.js';
+export * as voice from './voice/index.js';
 export { createTimedString, isTimedString, type TimedString } from './voice/io.js';
 export * from './worker.js';
-
-export { beta, cli, inference, ipc, llm, metrics, stream, stt, telemetry, tokenize, tts, voice };

agents/src/inference/llm.ts

@@ -2,16 +2,11 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 import OpenAI from 'openai';
-import {
-  APIConnectionError,
-  APIStatusError,
-  APITimeoutError,
-  DEFAULT_API_CONNECT_OPTIONS,
-  type Expand,
-  toError,
-} from '../index.js';
+import { APIConnectionError, APIStatusError, APITimeoutError } from '../_exceptions.js';
 import * as llm from '../llm/index.js';
+import { DEFAULT_API_CONNECT_OPTIONS } from '../types.js';
 import type { APIConnectOptions } from '../types.js';
+import { type Expand, toError } from '../utils.js';
 import { type AnyString, createAccessToken } from './utils.js';
 
 const DEFAULT_BASE_URL = 'https://agent-gateway.livekit.cloud/v1';

agents/src/inference/stt.test.ts

@@ -2,6 +2,7 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 import { beforeAll, describe, expect, it } from 'vitest';
+import { normalizeLanguage } from '../language.js';
 import { initializeLogger } from '../log.js';
 import { type APIConnectOptions, DEFAULT_API_CONNECT_OPTIONS } from '../types.js';
 import { STT, type STTFallbackModel, normalizeSTTFallback, parseSTTModelString } from './stt.js';
@@ -34,6 +35,12 @@ describe('parseSTTModelString', () => {
     expect(language).toBe('en');
   });
 
+  it('normalizes language suffixes', () => {
+    const [model, language] = parseSTTModelString('deepgram:english');
+    expect(model).toBe('deepgram');
+    expect(language).toBe('en');
+  });
+
   it('provider/model format without language', () => {
     const [model, language] = parseSTTModelString('deepgram/nova-3');
     expect(model).toBe('deepgram/nova-3');
@@ -151,6 +158,16 @@ describe('normalizeSTTFallback', () => {
 });
 
 describe('STT constructor fallback and connOptions', () => {
+  it('normalizes language in constructor and model string', () => {
+    const stt = makeStt({ model: 'deepgram/nova-3:english' });
+    expect(stt['opts'].language).toBe('en');
+  });
+
+  it('prefers explicit normalized language over model suffix', () => {
+    const stt = makeStt({ model: 'deepgram/nova-3:english', language: 'en_US' });
+    expect(stt['opts'].language).toBe(normalizeLanguage('en_US'));
+  });
+
   it('fallback not given defaults to undefined', () => {
     const stt = makeStt();
     expect(stt['opts'].fallback).toBeUndefined();

agents/src/inference/stt.ts

@@ -5,6 +5,7 @@ import { type AudioFrame } from '@livekit/rtc-node';
 import type { WebSocket } from 'ws';
 import { APIError, APIStatusError } from '../_exceptions.js';
 import { AudioByteStream } from '../audio.js';
+import { type LanguageCode, areLanguagesEquivalent, normalizeLanguage } from '../language.js';
 import { log } from '../log.js';
 import { createStreamChannel } from '../stream/stream_channel.js';
 import {
@@ -121,10 +122,10 @@ export interface STTFallbackModel {
 export type STTFallbackModelType = STTFallbackModel | string;
 
 /** Parse a model string into [model, language]. Language is undefined if not specified. */
-export function parseSTTModelString(model: string): [string, string | undefined] {
+export function parseSTTModelString(model: string): [string, LanguageCode | undefined] {
   const idx = model.lastIndexOf(':');
   if (idx !== -1) {
-    return [model.slice(0, idx), model.slice(idx + 1)];
+    return [model.slice(0, idx), normalizeLanguage(model.slice(idx + 1))];
   }
   return [model, undefined];
 }
@@ -156,7 +157,7 @@ const DEFAULT_CANCEL_TIMEOUT = 5000;
 
 export interface InferenceSTTOptions<TModel extends STTModels> {
   model?: TModel;
-  language?: STTLanguages;
+  language?: LanguageCode;
   encoding: STTEncoding;
   sampleRate: number;
   baseURL: string;
@@ -219,25 +220,24 @@ export class STT<TModel extends STTModels> extends BaseSTT {
     let nextModel = model;
     let nextLanguage = language;
     if (typeof nextModel === 'string') {
-      const idx = nextModel.lastIndexOf(':');
-      if (idx !== -1) {
-        const languageFromModel = nextModel.slice(idx + 1) as STTLanguages;
-        if (nextLanguage && nextLanguage !== languageFromModel) {
+      const [parsedModel, parsedLanguage] = parseSTTModelString(nextModel);
+      if (parsedLanguage !== undefined) {
+        if (nextLanguage && !areLanguagesEquivalent(nextLanguage, parsedLanguage)) {
           this.#logger.warn(
             '`language` is provided via both argument and model, using the one from the argument',
             { language: nextLanguage, model: nextModel },
           );
         } else {
-          nextLanguage = languageFromModel;
+          nextLanguage = parsedLanguage as STTLanguages;
         }
-        nextModel = nextModel.slice(0, idx) as TModel;
+        nextModel = parsedModel as TModel;
       }
     }
     const normalizedFallback = fallback ? normalizeSTTFallback(fallback) : undefined;
 
     this.opts = {
       model: nextModel as TModel,
-      language: nextLanguage,
+      language: nextLanguage ? normalizeLanguage(nextLanguage) : undefined,
       encoding,
       sampleRate,
       baseURL: lkBaseURL,
@@ -263,7 +263,11 @@ export class STT<TModel extends STTModels> extends BaseSTT {
   }
 
   updateOptions(opts: Partial<Pick<InferenceSTTOptions<TModel>, 'model' | 'language'>>): void {
-    this.opts = { ...this.opts, ...opts };
+    this.opts = {
+      ...this.opts,
+      ...opts,
+      language: opts.language !== undefined ? normalizeLanguage(opts.language) : this.opts.language,
+    };
 
     for (const stream of this.streams) {
       stream.updateOptions(opts);
@@ -278,7 +282,7 @@ export class STT<TModel extends STTModels> extends BaseSTT {
       options || {};
     const streamOpts = {
       ...this.opts,
-      language: language ?? this.opts.language,
+      language: language !== undefined ? normalizeLanguage(language) : this.opts.language,
     } as InferenceSTTOptions<TModel>;
 
     const stream = new SpeechStream(this, streamOpts, connOptions);
@@ -364,7 +368,11 @@ export class SpeechStream<TModel extends STTModels> extends BaseSpeechStream {
   }
 
   updateOptions(opts: Partial<Pick<InferenceSTTOptions<TModel>, 'model' | 'language'>>): void {
-    this.opts = { ...this.opts, ...opts };
+    this.opts = {
+      ...this.opts,
+      ...opts,
+      language: opts.language !== undefined ? normalizeLanguage(opts.language) : this.opts.language,
+    };
     this.reconnectEvent.set();
   }
 
@@ -569,7 +577,7 @@ export class SpeechStream<TModel extends STTModels> extends BaseSpeechStream {
 
     const requestId = data.session_id || this.requestId;
     const text = data.transcript;
-    const language = data.language || this.opts.language || 'en';
+    const language = normalizeLanguage(data.language || this.opts.language || 'en');
 
     if (!text && !isFinal) return;
 

agents/src/inference/tts.test.ts

@@ -2,6 +2,7 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 import { beforeAll, describe, expect, it } from 'vitest';
+import { normalizeLanguage } from '../language.js';
 import { initializeLogger } from '../log.js';
 import { type APIConnectOptions, DEFAULT_API_CONNECT_OPTIONS } from '../types.js';
 import { TTS, type TTSFallbackModel, normalizeTTSFallback, parseTTSModelString } from './tts.js';
@@ -165,6 +166,17 @@ describe('normalizeTTSFallback', () => {
 });
 
 describe('TTS constructor fallback and connOptions', () => {
+  it('normalizes language in constructor', () => {
+    const tts = makeTts({ language: 'english' });
+    expect(tts['opts'].language).toBe('en');
+  });
+
+  it('normalizes updated language values', () => {
+    const tts = makeTts();
+    tts.updateOptions({ language: 'en_US' });
+    expect(tts['opts'].language).toBe(normalizeLanguage('en_US'));
+  });
+
   it('fallback not given defaults to undefined', () => {
     const tts = makeTts();
     expect(tts['opts'].fallback).toBeUndefined();

agents/src/inference/tts.ts

@@ -6,6 +6,7 @@ import { WebSocket } from 'ws';
 import { APIError, APIStatusError } from '../_exceptions.js';
 import { AudioByteStream } from '../audio.js';
 import { ConnectionPool } from '../connection_pool.js';
+import { type LanguageCode, normalizeLanguage } from '../language.js';
 import { log } from '../log.js';
 import { createStreamChannel } from '../stream/stream_channel.js';
 import { basic as tokenizeBasic } from '../tokenize/index.js';
@@ -150,7 +151,7 @@ const DEFAULT_LANGUAGE = 'en';
 export interface InferenceTTSOptions<TModel extends TTSModels> {
   model?: TModel;
   voice?: string;
-  language?: string;
+  language?: LanguageCode;
   encoding: TTSEncoding;
   sampleRate: number;
   baseURL: string;
@@ -236,7 +237,7 @@ export class TTS<TModel extends TTSModels> extends BaseTTS {
     this.opts = {
       model: nextModel,
       voice: nextVoice,
-      language,
+      language: normalizeLanguage(language),
       encoding,
       sampleRate,
       baseURL: lkBaseURL,
@@ -267,9 +268,13 @@ export class TTS<TModel extends TTSModels> extends BaseTTS {
   }
 
   updateOptions(opts: Partial<Pick<InferenceTTSOptions<TModel>, 'model' | 'voice' | 'language'>>) {
-    this.opts = { ...this.opts, ...opts };
+    this.opts = {
+      ...this.opts,
+      ...opts,
+      language: opts.language !== undefined ? normalizeLanguage(opts.language) : this.opts.language,
+    };
     for (const stream of this.streams) {
-      stream.updateOptions(opts);
+      stream.updateOptions(this.opts);
     }
   }
 
@@ -362,7 +367,11 @@ export class SynthesizeStream<TModel extends TTSModels> extends BaseSynthesizeSt
   }
 
   updateOptions(opts: Partial<Pick<InferenceTTSOptions<TModel>, 'model' | 'voice' | 'language'>>) {
-    this.opts = { ...this.opts, ...opts };
+    this.opts = {
+      ...this.opts,
+      ...opts,
+      language: opts.language !== undefined ? normalizeLanguage(opts.language) : this.opts.language,
+    };
   }
 
   protected async run(): Promise<void> {

agents/src/inference/utils.ts

@@ -3,7 +3,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import { AccessToken } from 'livekit-server-sdk';
 import { WebSocket } from 'ws';
-import { APIConnectionError, APIStatusError } from '../index.js';
+import { APIConnectionError, APIStatusError } from '../_exceptions.js';
 
 export type AnyString = string & NonNullable<unknown>;
 

agents/src/language.test.ts

@@ -0,0 +1,62 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { describe, expect, it } from 'vitest';
+import {
+  areLanguagesEquivalent,
+  getBaseLanguage,
+  getIsoLanguage,
+  getLanguageRegion,
+  normalizeLanguage,
+  toLanguageName,
+} from './language.js';
+
+describe('normalizeLanguage', () => {
+  it('normalizes language names', () => {
+    expect(normalizeLanguage('english')).toBe('en');
+  });
+
+  it('normalizes iso 639-3 codes', () => {
+    expect(normalizeLanguage('eng')).toBe('en');
+  });
+
+  it('normalizes bcp-47 casing and separators', () => {
+    expect(normalizeLanguage('en_us')).toBe('en-US');
+    expect(normalizeLanguage('zh_hans_cn')).toBe('zh-Hans-CN');
+  });
+
+  it('preserves iso 639-3 in compound tags', () => {
+    expect(normalizeLanguage('cmn_hans_cn')).toBe('cmn-Hans-CN');
+  });
+
+  it('passes unknown codes through in lowercase', () => {
+    expect(normalizeLanguage('MULTI')).toBe('multi');
+  });
+
+  it('preserves empty string sentinel', () => {
+    expect(normalizeLanguage('')).toBe('');
+  });
+});
+
+describe('language helpers', () => {
+  it('extracts base language', () => {
+    expect(getBaseLanguage('cmn-Hans-CN')).toBe('zh');
+  });
+
+  it('builds iso language tag', () => {
+    expect(getIsoLanguage('cmn-Hans-CN')).toBe('zh-CN');
+  });
+
+  it('extracts region', () => {
+    expect(getLanguageRegion('en-US')).toBe('US');
+  });
+
+  it('maps normalized code back to language name', () => {
+    expect(toLanguageName('eng')).toBe('english');
+  });
+
+  it('compares equivalent representations', () => {
+    expect(areLanguagesEquivalent('english', 'en')).toBe(true);
+    expect(areLanguagesEquivalent('en_us', 'en-US')).toBe(true);
+  });
+});