Getting Started # Getting Started > Install ResponsiveVoice, speak your first sentence, or upgrade from v1 Three ways in, depending on where you are starting from. [Quick Start](/getting-started/quick-start/)New here? Speak your first sentence in a few lines, from a script tag or from npm. [Installation](/getting-started/installation/)Every install route in detail — CDN bundle, npm, and which package each project needs. [Migration Guide](/getting-started/migration/)Already using the legacy responsivevoice.js? Upgrade to @responsivevoice/core, with the API differences called out. ## Next [Guides](/guides/)Voice selection, the web player, events, and the rest of the feature surface. [Examples](/examples/)Runnable projects — browser, Vite, CLI, and server. # Installation > How to install ResponsiveVoice packages ## Core package The main client library for browser text-to-speech. Both paths deliver the same package — pick the one that fits your project: * **Browser bundle (CDN)** — no build step; add one script tag and use the global `responsiveVoice`. Best for plain HTML, prototypes, CMS sites, and legacy pages. Call `init()` with your API key — without it you get demo mode (browser default voice only). * **npm** — for apps with a bundler (Vite, webpack, Next). Install and import. - Browser bundle (CDN) ```html ``` - npm ```bash npm install @responsivevoice/core # or: pnpm add @responsivevoice/core # or: yarn add @responsivevoice/core ``` ```typescript import { getResponsiveVoice } from '@responsivevoice/core'; const rv = await getResponsiveVoice({ apiKey: 'YOUR_API_KEY' }); ``` ## API client REST API client for direct server communication. * npm ```bash npm install @responsivevoice/api-client ``` * pnpm ```bash pnpm add @responsivevoice/api-client ``` * yarn ```bash yarn add @responsivevoice/api-client ``` ## Types package `@responsivevoice/types` (TypeScript types + Zod schemas) ships automatically as a dependency of the packages above, and `api-client` re-exports the common ones — so you rarely install it directly. If you want the schemas standalone: `npm install @responsivevoice/types`. ## Requirements ### Browsers The browser bundle (CDN) is Babel + core-js polyfilled and works in Chrome 69+, Firefox 65+, Safari 12+, Edge 79+, iOS Safari 12+, Chrome Android 69+, Android WebView 69+ without any additional setup. ESM/CJS packages are syntax-compatible but leave browser polyfilling to your bundler; see [Browser Support](/guides/browser-support/) for each package’s minimum browser versions. ### Node.js | Package | Minimum | Full functionality | | ----------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `@responsivevoice/types` | 14+ | All features | | `@responsivevoice/text` | 14+ | All features | | `@responsivevoice/api-client` | 16+ | HTTP synthesis requires Node 18+ for native `fetch` and `Blob`. On Node 16–17, pass a `fetch` implementation via the `fetch` config option (e.g. `node-fetch` or `undici`). | | `@responsivevoice/core` | 16+ | Browser-only (Web Speech API + audio playback); Node is the build environment (bundle with Vite/webpack), not a runtime target | | `@responsivevoice/features` | 14+ | Browser-only (DOM APIs) | WebSocket streaming requires Node 22+ for the native `WebSocket` global, or pass any W3C-compatible WebSocket implementation (e.g. the `ws` package) via the `WebSocket` config option. ### TypeScript 5.0+ (optional, but recommended). Full type definitions included in all packages. # Migration Guide > Upgrade from legacy responsivevoice.js to @responsivevoice/core This guide helps you migrate from the legacy `responsivevoice.js` script to the modern `@responsivevoice/core` package. ## What’s New 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 * **Access to Premium neural voices** from several specialized TTS Providers (via bring-your-own-keys) * **New UI features** — see the new [ResponsiveVoice WebPlayer](/guides/web-player/) in action in the [live example](https://examples.responsivevoice.org/browser/web-player/) and [how to customize it](https://examples.responsivevoice.org/browser/web-player-customization/). Tip The migration is designed to be a drop-in replacement. Most code will work without changes. ## Installation Changes ### Before ```html ``` ### 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) ```html ``` * npm ```bash npm install @responsivevoice/core ``` ```typescript 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 ```javascript // Global configuration via URL parameter ; // Or via global variable window.responsiveVoice.setDefaultVoice('UK English Female'); ``` ### After * Browser bundle (CDN) ```html ``` * npm ```typescript 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) ```javascript responsiveVoice.speak('Hello', 'UK English Female', { onstart: () => console.log('Started'), onend: () => console.log('Ended'), }); ``` * npm ```typescript 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 69+, Firefox 65+, Safari 12+, Edge 79+, iOS Safari 12+, Chrome Android 69+, Android WebView 69+. 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: ```typescript 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: ```typescript const voices = rv.getVoices(); console.log(voices.map((v) => v.name)); ``` ### “API key required” Error Make sure to initialize with an API key: ```typescript 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: ```typescript button.addEventListener('click', () => { rv.speak('Hello'); }); ``` See the [FAQ](/guides/faq/#does-responsivevoice-work-on-ios) for details. ## Need Help? * [API Reference](/api/core/src/) * [Support](https://responsivevoice.org/support) # Quick Start > Get up and running with ResponsiveVoice in minutes ## Basic Usage Drop in the script tag or install from npm — both reach the same API: * Browser bundle (CDN) ```html Speak ``` * npm ```bash npm install @responsivevoice/core # or: pnpm add @responsivevoice/core / yarn add @responsivevoice/core ``` ```typescript import { getResponsiveVoice } from '@responsivevoice/core'; const rv = await getResponsiveVoice({ apiKey: 'YOUR_API_KEY' }); rv.speak('Hello, world!'); ``` Note The examples below use the `rv` instance returned by `getResponsiveVoice()` (npm). With the browser bundle, call the same methods on the global `responsiveVoice`. ## Voice Selection ```typescript // Get available voices const voices = rv.getVoices(); console.log(voices); // Speak with a specific voice rv.speak('Hello', 'UK English Female'); rv.speak('Hello', 'US English Male'); rv.speak('Hallo', 'Deutsch Female'); ``` ## Playback Control ```typescript // Pause speech rv.pause(); // Resume speech rv.resume(); // Cancel speech rv.cancel(); // Check if speaking if (rv.isPlaying()) { console.log('Currently speaking'); } ``` ## Events ```typescript // Per-call callbacks — bound to this speak() call rv.speak('Hello with events', 'UK English Female', { onstart: () => console.log('Speech started'), onend: () => console.log('Speech ended'), onerror: (error) => console.error('Speech error:', error), onboundary: (charIndex, name) => console.log('Word boundary:', charIndex, name), }); // Global events — fire across every speak() call (pause/resume live here) rv.addEventListener('OnPause', () => console.log('Speech paused')); rv.addEventListener('OnResume', () => console.log('Speech resumed')); ``` Tip For more advanced usage, see the [Voice Selection](/guides/voice-selection/) and [Events](/guides/events/) guides.