Edge TTS

A TypeScript library for Microsoft Edge Text-to-Speech (TTS) with streaming support and browser playback capabilities.

Installation

npm install @duyquangnvx/edge-tts

Usage

Node.js Usage

import { Communicate } from '@duyquangnvx/edge-tts';

const communicate = new Communicate("Hello, world!", {
  voice: 'en-US-AriaNeural',
  rate: '+0%',
  volume: '+0%',
  pitch: '+0Hz'
});

for await (const chunk of communicate.stream()) {
  if (chunk.type === 'audio') {
    // Handle audio data
    console.log('Audio chunk received:', chunk.data.length, 'bytes');
  } else if (chunk.type === 'WordBoundary') {
    // Handle word boundary information
    console.log('Word boundary:', chunk.text, 'at offset:', chunk.offset);
  }
}

Browser Usage with Playback

For browser environments with audio playback support:

import { EdgePlayback } from '@duyquangnvx/edge-tts/browser';

const playback = new EdgePlayback({
  autoPlay: true,
  onProgress: (progress) => {
    console.log('Progress:', progress.currentTime, 'Current word:', progress.text);
  },
  onStateChange: (state) => {
    console.log('State changed:', state);
  },
  onError: (error) => {
    console.error('Playback error:', error);
  }
});

// Start speaking
await playback.speak("Hello, this is a streaming text-to-speech example!", {
  voice: 'en-US-AriaNeural',
  rate: '+0%',
  volume: '+0%',
  pitch: '+0Hz'
});

// Control playback
playback.pause();
playback.play();
playback.setVolume(0.8);
playback.stop();

// Cleanup when done
playback.dispose();

Browser Bundle Import

You can also import the entire browser bundle:

import { Communicate, EdgePlayback } from '@duyquangnvx/edge-tts/browser';

API Reference

Core Classes

Communicate

Main class for TTS communication with Edge services.

new Communicate(text: string, config?: TTSConfig)

Methods:

• stream(): Returns an async iterator for streaming TTS chunks
• close(): Closes the communication

EdgePlayback

Browser-specific class for audio playback with controls.

new EdgePlayback(options?: PlaybackOptions)

Methods:

• speak(text: string, config?: TTSConfig): Start streaming and playing text
• play(): Resume playback
• pause(): Pause playback
• stop(): Stop playback and reset
• setVolume(volume: number): Set volume (0.0 to 1.0)
• getVolume(): Get current volume
• getState(): Get current playback state
• getProgress(): Get current progress information
• dispose(): Cleanup resources

Configuration

TTSConfig

interface TTSConfig {
  voice?: string;
  rate?: string;
  volume?: string;
  pitch?: string;
  // ... other Edge TTS options
}

PlaybackOptions

interface PlaybackOptions {
  autoPlay?: boolean;        // Auto-start playback (default: true)
  bufferSize?: number;       // Audio buffer size (default: 5)
  onProgress?: (progress: PlaybackProgress) => void;
  onStateChange?: (state: PlaybackState) => void;
  onError?: (error: Error) => void;
}

Examples

See the src/examples/ directory for complete usage examples:

• basic-usage.ts: Basic TTS streaming
• voice-management.ts: Voice selection and management
• advanced-usage.ts: Advanced features and configurations

Run examples:

npm run example:basic
npm run example:voices
npm run example:advanced
npm run examples

Browser Support

The browser bundle requires:

• Web Audio API support
• Modern browser with ES2020+ support
• HTTPS context (for Web Audio API)

Development

# Install dependencies
npm install

# Build
npm run build

# Development with watch
npm run dev

# Type checking
npm run typecheck

# Clean build artifacts
npm run clean

License

ISC