A unified interface for browser speech synthesis and Eleven Labs voices.

# Using npm
npm install speech-provider

# Using yarn
yarn add speech-provider

# Using bun
bun add speech-provider

Full API documentation is available at https://osteele.github.io/speech-provider/.

import { getVoiceProvider } from 'speech-provider';

// Use browser voices only
const provider = getVoiceProvider({});

// Use Eleven Labs voices if API key is available
const provider = getVoiceProvider({ elevenLabsApiKey: 'your-api-key' });

// Use Eleven Labs with custom cache duration
const provider = getVoiceProvider({
  elevenLabsApiKey: 'your-api-key',
  cacheMaxAge: 86400 // Cache for 1 day
});

// Get voices for a specific language
const voices = await provider.getVoices({ lang: 'en-US', minVoices: 1 });

// Get default voice for a language
const defaultVoice = await provider.getDefaultVoice({ lang: 'en-US' });

// Create and play an utterance
if (defaultVoice) {
  const utterance = defaultVoice.createUtterance('Hello, world!');
  utterance.onstart = () => console.log('Started speaking');
  utterance.onend = () => console.log('Finished speaking');
  utterance.start();
}

• Unified interface for both browser speech synthesis and Eleven Labs voices
• Automatic fallback to browser voices when Eleven Labs API key is not provided
• Typesafe API with TypeScript support
• Simple voice selection by language
• Event listeners for speech start and end events
• Automatic caching of Eleven Labs API responses to reduce API calls
• Configurable cache duration for Eleven Labs responses

This package is used in Mandarin Sentence Practice, a web application for practicing Mandarin Chinese with listening and translation exercises. The app uses this package to provide high-quality text-to-speech for Mandarin sentences, with automatic fallback to browser voices when Eleven Labs is not available.

Creates a voice provider based on the available API keys. Falls back to browser speech synthesis if no API keys are provided.

function getVoiceProvider(options: {
  elevenLabsApiKey?: string | null;
  cacheMaxAge?: number; // Cache duration in seconds (default: 1 hour)
}): VoiceProvider;

Creates an Eleven Labs voice provider with optional configuration.

function createElevenLabsVoiceProvider(
  apiKey: string,
  options?: {
    validateResponses?: boolean;
    printVoiceProperties?: boolean;
    cacheMaxAge?: number; // Cache duration in seconds (default: 1 hour)
  }
): VoiceProvider;

The library implements automatic caching for Eleven Labs API responses:

• Browser voices are cached automatically by the browser's speech synthesis engine
• Eleven Labs responses are cached using IndexedDB with a default duration of 1 hour
• Cache duration can be configured when creating the provider
• Cached responses are automatically invalidated after the specified duration
• Cache can be disabled by setting cacheMaxAge: null in the provider options

Examples of cache configuration:

// Use default 1-hour cache
const provider = getVoiceProvider({ elevenLabsApiKey: 'your-api-key' });

// Cache for 1 day
const provider = getVoiceProvider({
  elevenLabsApiKey: 'your-api-key',
  cacheMaxAge: 86400 // 24 hours in seconds
});

// Cache for 1 week
const provider = getVoiceProvider({
  elevenLabsApiKey: 'your-api-key',
  cacheMaxAge: 604800 // 7 days in seconds
});

// Disable caching (preferred approach)
const provider = getVoiceProvider({
  elevenLabsApiKey: 'your-api-key',
  cacheMaxAge: null
});

// Alternative way to disable caching
const provider = getVoiceProvider({
  elevenLabsApiKey: 'your-api-key',
  cacheMaxAge: 0
});

interface VoiceProvider {
  name: string;
  getVoices({ lang, minVoices }: { lang: string; minVoices: number }): Promise<Voice[]>;
  getDefaultVoice({ lang }: { lang: string }): Promise<Voice | null>;
}

interface Voice {
  name: string;
  id: string;
  lang: string;
  provider: VoiceProvider;
  description: string | null;
  createUtterance(text: string): Utterance;
}

interface Utterance {
  start(): void;
  stop(): void;
  set onstart(callback: () => void);
  set onend(callback: () => void);
}

The browser speech synthesis provider (BrowserVoiceProvider) is supported in all modern browsers:

• Chrome/Edge: Full support (voices load asynchronously)
• Firefox: Full support
• Safari: Full support (iOS and macOS)
• Opera: Full support

Note: Voice availability and quality vary by browser and operating system. Chrome and Edge typically offer the best selection of voices.

The ElevenLabs provider (ElevenLabsVoiceProvider) requires:

• IndexedDB: For caching API responses (supported in all modern browsers)
• Fetch API: For making API requests (supported in all modern browsers)
• Audio API: For playing synthesized speech (supported in all modern browsers)

• Modern browser with ES2022 support
• IndexedDB support (for ElevenLabs caching)
• No Internet Explorer support

The library is designed for client-side use. When used in SSR environments:

• Browser voice provider gracefully handles the absence of window.speechSynthesis
• Returns empty arrays when browser APIs are unavailable
• Safe to import in SSR frameworks (Next.js, Nuxt, etc.) but should only be used client-side

Contributions are welcome! Please read the CONTRIBUTING.md guide for details on our code of conduct and the process for submitting pull requests.

See CHANGELOG.md for a list of changes and version history.

Copyright 2025 by Oliver Steele

Available under the MIT License