Migration Guide

This guide helps you migrate from the legacy responsivevoice.js script to the modern @responsivevoice/core package.

Overview

The new package provides:

• TypeScript support with full type definitions
• Modern build formats (ESM, CJS, browser bundle)
• Tree-shakeable exports
• Better error handling
• API-first architecture (voice data fetched at runtime)
• Full backward compatibility with the legacy API

Tip

The migration is designed to be a drop-in replacement. Most code will work without changes.

Installation Changes

Before

<script src="https://code.responsivevoice.org/responsivevoice.js?key=YOUR_KEY"></script>

After

The closest migration keeps a script tag — load the browser bundle from the CDN and move your key into an init() call. Use npm instead if your app has a bundler.

Browser bundle (CDN)

<script src="https://cdn.responsivevoice.org/sdk/latest/responsivevoice.js"></script>
<script>
  responsiveVoice.init({ apiKey: 'YOUR_KEY' });
</script>

npm

npm install @responsivevoice/core

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

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

API Mapping

The core API remains the same:

Legacy	Modern	Notes
responsiveVoice.speak()	rv.speak()	Same signature
responsiveVoice.cancel()	rv.cancel()	Same behavior
responsiveVoice.pause()	rv.pause()	Same behavior
responsiveVoice.resume()	rv.resume()	Same behavior
responsiveVoice.getVoices()	rv.getVoices()	Same behavior
responsiveVoice.isPlaying()	rv.isPlaying()	Same behavior

In the browser bundle the global stays responsiveVoice; with npm you call the same methods on the rv instance from getResponsiveVoice(). The signatures are identical either way.

Configuration Changes

Before

// Global configuration via URL parameter
<script src="...?key=YOUR_KEY"></script>;

// Or via global variable
window.responsiveVoice.setDefaultVoice('UK English Female');

After

Browser bundle (CDN)

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

npm

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

const rv = await getResponsiveVoice({
  apiKey: 'YOUR_KEY',
  defaultVoice: 'UK English Female',
});

Event System

Per-call event callbacks are unchanged from the legacy script:

Browser bundle (CDN)

responsiveVoice.speak('Hello', 'UK English Female', {
  onstart: () => console.log('Started'),
  onend: () => console.log('Ended'),
});

npm

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

Breaking Changes

Caution

The following changes may require code updates:

1. Voice Data is Fetched at Runtime

Voice mappings are no longer bundled in the JavaScript file — init() fetches them from the API and caches them locally.

Impact: First initialization needs a network connection to fetch the voice catalog. There's nothing to pre-fetch — init() already loads voices before it resolves.

2. No Internet Explorer Support

The browser bundle (CDN) ships the polyfills modern browsers need and targets Chrome 66+, Firefox 57+, Safari 12+, Edge 17+, and iOS 12+. Internet Explorer 11 is not supported.

Impact: If you need to support IE11 or similarly old browsers, stay on the legacy responsivevoice.js (v1).

TypeScript Support

The new package includes full TypeScript definitions:

import {
  getResponsiveVoice,
  type ResponsiveVoiceInitOptions,
} from '@responsivevoice/core';
import type { SpeakParams } from '@responsivevoice/types';

const options: ResponsiveVoiceInitOptions = {
  apiKey: 'YOUR_KEY',
};

const rv = await getResponsiveVoice(options);

const params: SpeakParams = {
  pitch: 1.0,
  rate: 1.0,
  onend: () => console.log('Done'),
};

rv.speak('Hello', 'UK English Female', params);

Troubleshooting

"Voice not found" Error

Ensure the voice name exactly matches an available voice:

const voices = rv.getVoices();
console.log(voices.map((v) => v.name));

"API key required" Error

Make sure to initialize with an API key:

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

Audio Not Playing on iOS

Mobile browsers (iOS, and Android Chrome) block autoplay, but ResponsiveVoice handles this automatically with a built-in permission prompt that captures the first tap and unlocks audio. If you've disabled the prompt, trigger speech from your own gesture handler instead:

button.addEventListener('click', () => {
  rv.speak('Hello');
});

See the FAQ for details.

Need Help?

• GitHub Issues
• API Reference
• Support