Installation

# npm
npm install @responsivevoice/core

# yarn
yarn add @responsivevoice/core

# pnpm
pnpm add @responsivevoice/core

Get your API credentials

Out of the box, core runs in demo mode — it speaks with the browser's default voice only. Registering and verifying your website unlocks the full server voice catalog:

1. Register for a free ResponsiveVoice account.
2. A default website is created for you automatically — its identifier is your API key. Copy it from the dashboard.
3. Initialize core with your API key.
4. Verify your website's domain in the dashboard so requests from your site are recognized — this unlocks the full set of voices.

Quick Start

ES Module

import { getResponsiveVoice } from '@responsivevoice/core';

const rv = await getResponsiveVoice({ apiKey: 'YOUR_API_KEY' });

// Basic usage
rv.speak('Hello world', 'UK English Female');

// With options
rv.speak('Hello world', 'UK English Female', {
  pitch: 1.0,
  rate: 1.0,
  volume: 1.0,
  onstart: () => console.log('Started'),
  onend: () => console.log('Finished'),
});

Browser bundle (CDN)

<script src="https://cdn.responsivevoice.org/sdk/latest/responsivevoice.js"></script>
<script>
  responsiveVoice.init({ apiKey: 'YOUR_API_KEY' });
  responsiveVoice.speak('Hello world', 'UK English Female');
</script>

API

Initialization

// Recommended: async factory (creates singleton, calls init internally)
const rv = await getResponsiveVoice({ apiKey: 'YOUR_KEY' });

// Alternative: manual construction + init
const rv = new ResponsiveVoice();
await rv.init({ apiKey: 'YOUR_KEY' });

| Option | Type | Default | Description | | ---------------- | --------- | --------------------- | ----------------------------------------- | | apiKey | string | — | Your registered website/origin identifier | | defaultVoice | string | 'UK English Female' | Default voice name | | forceFallback | boolean | false | Force HTTP audio (skip native TTS) | | characterLimit | number | 100 | Text chunk character limit | | transport | string | 'chunks' | Audio transport: chunks/stream/websocket |

Methods

speak(text, voice?, options?)

Speaks the given text.

rv.speak('Hello world');
rv.speak('Hello world', 'US English Male');
rv.speak('Hello world', 'UK English Female', {
  rate: 1.2,
  onend: () => console.log('Done'),
});

cancel()

Stops all speech.

rv.cancel();

pause()

Pauses current speech.

rv.pause();

resume()

Resumes paused speech.

rv.resume();

getVoices()

Returns available voices.

const voices = rv.getVoices();
// [{ name: 'UK English Female', lang: 'en-GB', gender: 'f' }, ...]

isPlaying()

Returns whether speech is currently playing.

if (rv.isPlaying()) {
  rv.cancel();
}

Events

rv.speak('Hello', 'UK English Female', {
  onstart: () => console.log('Started'),
  onend: () => console.log('Finished'),
  onerror: (error) => console.error('Error:', error),
});

Browser Support

For detailed compatibility information, see the Browser Support documentation.

Minimum browser versions:

| Browser | Min Version | Native TTS | Fallback API | | -------------- | ----------- | ---------- | ------------ | | Chrome | 66+ | Yes | Yes | | Firefox | 57+ | Limited | Yes | | Safari | 14+ | Yes | Yes | | Edge | 16+ | Yes | Yes | | iOS Safari | 14+ | Yes | Yes | | Chrome Android | 66+ | Yes | Yes |

Bundlers

Core targets the browser. Install it from npm and bundle it with Vite, webpack, or any modern bundler — it runs in the browser, not server-side. For server-side or headless TTS (HTTP synthesis without a browser), use @responsivevoice/api-client directly.

Migration from Legacy

Script Tag (most legacy users)

<!-- Before -->
<script src="https://code.responsivevoice.org/responsivevoice.js?key=YOUR_KEY"></script>
<script>
  responsiveVoice.speak('Hello');
</script>

<!-- After — only change: remove ?key from URL, add init() call -->
<script src="https://cdn.responsivevoice.org/sdk/latest/responsivevoice.js"></script>
<script>
  responsiveVoice.init({ apiKey: 'YOUR_KEY' });
  responsiveVoice.speak('Hello');
</script>

See the Migration Guide for details.

Documentation

Full documentation at docs.responsivevoice.org.

License

MIT

Other language SDKs: Python · Go · PHP · Java