markdown and emoji filters + advanced preprocessing

Author: simllll

agents/src/voice/agent_session.ts

@@ -49,6 +49,7 @@ import { AgentInput, AgentOutput } from './io.js';
 import { RoomIO, type RoomInputOptions, type RoomOutputOptions } from './room_io/index.js';
 import type { UnknownUserData } from './run_context.js';
 import type { SpeechHandle } from './speech_handle.js';
+import { DEFAULT_TTS_TEXT_TRANSFORMS, type TextTransformSpec } from './transcription/transforms.js';
 
 export interface VoiceOptions {
   allowInterruptions: boolean;
@@ -60,6 +61,7 @@ export interface VoiceOptions {
   maxToolSteps: number;
   preemptiveGeneration: boolean;
   userAwayTimeout?: number | null;
+  ttsTextTransforms?: TextTransformSpec[] | null;
 }
 
 const defaultVoiceOptions: VoiceOptions = {
@@ -72,6 +74,7 @@ const defaultVoiceOptions: VoiceOptions = {
   maxToolSteps: 3,
   preemptiveGeneration: false,
   userAwayTimeout: 15.0,
+  ttsTextTransforms: DEFAULT_TTS_TEXT_TRANSFORMS,
 } as const;
 
 export type TurnDetectionMode = 'stt' | 'vad' | 'realtime_llm' | 'manual' | _TurnDetector;

agents/src/voice/generation.ts

@@ -27,6 +27,7 @@ import type { AgentSession } from './agent_session.js';
 import type { AudioOutput, LLMNode, TTSNode, TextOutput } from './io.js';
 import { RunContext } from './run_context.js';
 import type { SpeechHandle } from './speech_handle.js';
+import { type TextTransformSpec, applyTextTransforms } from './transcription/index.js';
 
 /** @internal */
 export class _LLMGenerationData {
@@ -474,6 +475,7 @@ export function performTTSInference(
   text: ReadableStream<string>,
   modelSettings: ModelSettings,
   controller: AbortController,
+  textTransforms?: readonly TextTransformSpec[] | null,
 ): [Task<void>, ReadableStream<AudioFrame>] {
   const audioStream = new IdentityTransform<AudioFrame>();
   const outputWriter = audioStream.writable.getWriter();
@@ -484,7 +486,13 @@ export function performTTSInference(
     let ttsStream: ReadableStream<AudioFrame> | null = null;
 
     try {
-      ttsStream = await node(text, modelSettings);
+      // Apply text transforms
+      let transformedText = text;
+      if (textTransforms && textTransforms.length > 0) {
+        transformedText = await applyTextTransforms(text, textTransforms);
+      }
+
+      ttsStream = await node(transformedText, modelSettings);
       if (ttsStream === null) {
         await outputWriter.close();
         return;

agents/src/voice/index.ts

@@ -9,3 +9,4 @@ export * from './events.js';
 export * from './report.js';
 export * from './room_io/index.js';
 export { RunContext } from './run_context.js';
+export * from './transcription/index.js';

agents/src/voice/transcription/index.ts

@@ -2,3 +2,7 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 export * from './_utils.js';
+export * from './transforms.js';
+export * from './transforms_agnostic.js';
+export * from './transforms_en.js';
+export * from './transforms_de.js';

agents/src/voice/transcription/transforms.test.ts

@@ -0,0 +1,103 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { ReadableStream } from 'node:stream/web';
+import { describe, expect, it } from 'vitest';
+import {
+  DEFAULT_TTS_TEXT_TRANSFORMS,
+  applyTextTransforms,
+  getAvailableTransforms,
+} from './transforms.js';
+
+/**
+ * Helper to convert a string to a ReadableStream
+ */
+function stringToStream(text: string): ReadableStream<string> {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(text);
+      controller.close();
+    },
+  });
+}
+
+/**
+ * Helper to read a stream to a string
+ */
+async function streamToString(stream: ReadableStream<string>): Promise<string> {
+  const reader = stream.getReader();
+  let result = '';
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    result += value;
+  }
+  return result;
+}
+
+describe('Text Transforms Core', () => {
+  it('should export DEFAULT_TTS_TEXT_TRANSFORMS', () => {
+    expect(DEFAULT_TTS_TEXT_TRANSFORMS).toBeDefined();
+    expect(DEFAULT_TTS_TEXT_TRANSFORMS).toEqual(['filter_markdown', 'filter_emoji']);
+  });
+
+  it('should list available transforms for English', () => {
+    const transforms = getAvailableTransforms('en');
+    expect(transforms.has('filter_markdown')).toBe(true);
+    expect(transforms.has('filter_emoji')).toBe(true);
+    expect(transforms.has('format_numbers')).toBe(true);
+    expect(transforms.has('format_dollar_amounts')).toBe(true);
+  });
+
+  it('should list available transforms for German', () => {
+    const transforms = getAvailableTransforms('de');
+    expect(transforms.has('filter_markdown')).toBe(true);
+    expect(transforms.has('filter_emoji')).toBe(true);
+    expect(transforms.has('format_numbers_de')).toBe(true);
+    expect(transforms.has('format_euro_amounts')).toBe(true);
+  });
+
+  it('should throw error for invalid transform name', async () => {
+    const stream = stringToStream('test');
+    await expect(
+      applyTextTransforms(stream, ['invalid_transform' as any], { language: 'en' }),
+    ).rejects.toThrow('Invalid transform');
+  });
+
+  it('should apply custom transform function', async () => {
+    const customTransform = (text: ReadableStream<string>) => {
+      return new ReadableStream({
+        async start(controller) {
+          const reader = text.getReader();
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+              controller.close();
+              break;
+            }
+            controller.enqueue(value.toUpperCase());
+          }
+        },
+      });
+    };
+
+    const stream = stringToStream('hello world');
+    const result = await applyTextTransforms(stream, [customTransform]);
+    const output = await streamToString(result);
+    expect(output).toBe('HELLO WORLD');
+  });
+
+  it('should apply multiple transforms in sequence', async () => {
+    const stream = stringToStream('**Price: $5** 🎉');
+    const result = await applyTextTransforms(
+      stream,
+      ['filter_markdown', 'filter_emoji', 'format_dollar_amounts'],
+      { language: 'en' },
+    );
+    const output = await streamToString(result);
+    expect(output).toContain('Price:');
+    expect(output).toContain('five dollars');
+    expect(output).not.toContain('**');
+    expect(output).not.toContain('🎉');
+  });
+});