This is the full developer documentation for ResponsiveVoice # ResponsiveVoice > The modern, TypeScript-first text-to-speech library for browsers and Node.js ## Packages [Section titled “Packages”](#packages) @responsivevoice/core The heart -- and lungs -- of ResponsiveVoice. A drop-in replacement for the former **responsivevoice.js**, with modern TypeScript support, that runs in the browser. @responsivevoice/api-client REST API client with retry logic, response validation, and beautiful error handling. @responsivevoice/types Shared Schemas and Types used in the entire ecosystem. ## Features [Section titled “Features”](#features) TypeScript First Full TypeScript support with strict types and IntelliSense. Modern Build ESM, CJS, and a browser bundle (CDN). Tree-shakeable exports. 100+ Voices Access to 100+ voices across 50+ languages. Backward Compatible Drop-in replacement for legacy responsivevoice.js. *For LLMs and AI agents: [llms.txt](/llms.txt), [llms-full.txt](/llms-full.txt), or the [For AI Agents](/guides/ai-agents/) guide — append `.md` to any docs URL.* # Examples > Learn by example with working demos and code samples Explore working examples that demonstrate ResponsiveVoice capabilities. All examples live in the [examples repository](https://github.com/responsivevoice/examples). ## CDN Examples [Section titled “CDN Examples”](#cdn-examples) Drop a ` ``` Without an API key the library runs in **demo mode** — it falls back to browser-native Web Speech API voices. Call `rv.isDemoMode()` at runtime to detect this state (for example, to surface a "Demo Mode" indicator in your UI). ## Next Steps [Section titled “Next Steps”](#next-steps) * [Extended Usage Example](/examples/extended) — voice selection, speech controls, event logging * [npm + Vite Example](/examples/vite) — the same flow via ESM import and a bundler * [Events Guide](/guides/events) — the full event lifecycle * [Voice Selection Guide](/guides/voice-selection) — picking voices programmatically # CLI Tool > Command-line text-to-speech utility for Node.js A command-line tool that synthesizes text to speech and saves audio to a file. Uses `@responsivevoice/api-client` directly — server-side only, no browser involvement. Tip [Source code](https://github.com/responsivevoice/examples/tree/main/node/cli) ## Quick start [Section titled “Quick start”](#quick-start) ```bash export RESPONSIVEVOICE_API_KEY="your-api-key" # https://app.responsivevoice.org export RESPONSIVEVOICE_API_SECRET="your-api-secret" # "Server-to-server API secrets" npm install npm run cli -- "Hello, world!" --output hello.mp3 ``` Unlike the browser examples, the CLI has no demo mode — the API client requires a valid key and secret to make HTTP requests to the synthesis endpoint. The `README` in the source tree lists every flag (`--voice`, `--rate`, `--pitch`, `--volume`, `--stdout`, `--list-voices`). ## Next Steps [Section titled “Next Steps”](#next-steps) * [HTTP Server](/examples/server) — REST wrapper around the same API client * [REST API Overview](/rest-api/overview/) — direct HTTP usage * [API Client Reference](/api/api-client/src) — full client documentation # Events & Callbacks Example > Live view of every public event and per-call callback firing A focused teacher for the speech lifecycle — speak one utterance and watch every public event and per-call callback fire in real time. Tip [Live demo](https://examples.responsivevoice.org/browser/events-callbacks/) · [Source code](https://github.com/responsivevoice/examples/tree/main/browser/events-callbacks) ## Why a separate example [Section titled “Why a separate example”](#why-a-separate-example) There are two parallel ways to observe speech: `responsiveVoice.addEventListener(name, fn)` (process-wide, persists across calls) and inline `onstart` / `onend` / `onerror` / `onboundary` callbacks passed to `speak()` (bound to a single utterance). Most confusion in the wild stems from mixing them up. This example surfaces both at the same visual level — a row of per-call pills bound to one utterance, and a row of global pills that fire across the lifetime of the page — so the distinction is concrete instead of conceptual. ## What you'll see [Section titled “What you'll see”](#what-youll-see) * **Two rows of pills.** The top row (four pills: `onstart`, `onboundary`, `onend`, `onerror`) are the per-call callbacks you pass to `speak()`. The bottom row (nine pills: `OnReady`, `OnVoiceResolved`, `OnStart`, `OnPartStart`, `OnPartEnd`, `OnPause`, `OnResume`, `OnEnd`, `OnError`) are the global events you register with `addEventListener()`. * **The default text triggers chunking.** The text box starts with a multi-sentence sample long enough that the engine splits it into several parts. Click Speak and you'll see `OnPartStart` show `part X of N` and `OnPartEnd` count up as each chunk finishes. * **Pills reset on every Speak click**, except `OnReady` — that one fires once when the page loads and stays green for the rest of the session. * **The full event log sits below the pills.** Once you recognize a pill, you can scroll the log to see the actual data each event carries. * **`onboundary` only fires for browser-native voices.** When a voice plays through the HTTP fallback (server-side audio), the boundary callback stays quiet and its counter doesn't move. * **`OnPause` has a \~60-second browser limit.** If you click Pause and don't click Resume within about a minute, the browser cancels the speech automatically and you'll see `OnEnd` fire instead of `OnResume`. ## Next Steps [Section titled “Next Steps”](#next-steps) * [Events Guide](/guides/events) — full event reference and async/await patterns * [Basic Example](/examples/basic) — minimal `OnReady` + `speak()` flow without the inspection scaffolding # Extended Usage Example > Full-featured demo with voice selection, speech controls, and event logging A full-featured example showing voice selection, playback controls, speech parameter tuning, and a live event log. Tip [Live demo](https://examples.responsivevoice.org/browser/extended/) · [Source code](https://github.com/responsivevoice/examples/tree/main/browser/extended) ## What it covers [Section titled “What it covers”](#what-it-covers) * Voice browser with language filtering * `speak` / `pause` / `resume` / `cancel` controls * Rate / pitch / volume sliders * Platform detection (browser, OS, device type) * Real-time event log * Demo mode indicator driven by `rv.isDemoMode()` * Force-fallback toggle (use HTTP audio instead of Web Speech API) ## Speech parameter ranges [Section titled “Speech parameter ranges”](#speech-parameter-ranges) | Parameter | Min | Default | Max | Description | | --------- | --- | ------- | --- | ------------ | | `rate` | 0.1 | 1.0 | 2.0 | Speech speed | | `pitch` | 0.1 | 1.0 | 2.0 | Voice pitch | | `volume` | 0.0 | 1.0 | 1.0 | Audio volume | ```js rv.speak('Hello!', 'UK English Female', { rate: 1.2, pitch: 1.0, volume: 0.8, }); ``` ## Force fallback mode [Section titled “Force fallback mode”](#force-fallback-mode) Bypass the Web Speech API and always use HTTP audio from the server: ```js await rv.init({ apiKey: 'your-api-key', forceFallback: true }); ``` Useful when you need consistent audio across browsers, or when Web Speech API voices are unavailable on the target device. ## Next Steps [Section titled “Next Steps”](#next-steps) * [Basic Example](/examples/basic) — the minimal starting point * [Voice Selection Guide](/guides/voice-selection) — advanced voice filtering * [Events Guide](/guides/events) — full event reference # HTTP Server > REST API server for text-to-speech synthesis A minimal HTTP server that exposes REST endpoints for text-to-speech synthesis. Useful as a reverse proxy — keeps your API key off the browser and lets your frontend call your own origin. Tip [Source code](https://github.com/responsivevoice/examples/tree/main/node/server) ## Quick start [Section titled “Quick start”](#quick-start) ```bash export RESPONSIVEVOICE_API_KEY="your-api-key" # https://app.responsivevoice.org export RESPONSIVEVOICE_API_SECRET="your-api-secret" # "Server-to-server API secrets" npm install npm run server # Server on http://localhost:3001 ``` ## Endpoints [Section titled “Endpoints”](#endpoints) | Method | Path | Description | | ------ | ---------------------- | ----------------------------- | | GET | `/` | API documentation | | GET | `/voices` | List all voices | | GET | `/voices/:lang` | Voices by language | | POST | `/synthesize` | Synthesize speech (JSON body) | | GET | `/synthesize?text=...` | Synthesize via query params | ## Calling from a frontend [Section titled “Calling from a frontend”](#calling-from-a-frontend) ```js async function speak(text) { const response = await fetch('http://localhost:3001/synthesize', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ text, voice: 'UK English Female' }), }); const audio = new Audio(URL.createObjectURL(await response.blob())); audio.play(); } ``` The server ships with permissive CORS headers (`Access-Control-Allow-Origin: *`). Tighten to your domain(s) before deploying anything public-facing. ## Next Steps [Section titled “Next Steps”](#next-steps) * [CLI Tool](/examples/cli) — same API client, command-line form * [REST API Overview](/rest-api/overview/) — direct HTTP usage * [API Client Reference](/api/api-client/src) — full client documentation # npm + Vite Example > Installed from npm, bundled for the browser by Vite `@responsivevoice/core` installed from npm and bundled for the browser by [Vite](https://vitejs.dev/). Same feature set as the [Basic Example](/examples/basic), but the library arrives via ESM `import` instead of a CDN ` ``` The feature ships in the CDN bundle — no extra imports. ## Multi-mount [Section titled “Multi-mount”](#multi-mount) When `selector` matches more than one top-level element, an independent player is mounted on each. Single-active-narrator coordination is implicit: starting playback on one resets every other player to idle. Nested matches (e.g. `
` inside `
`) are filtered automatically — only the outermost match mounts. Publishers who specifically want nested mounts write a more specific selector. ## Imperative mount [Section titled “Imperative mount”](#imperative-mount) For SPAs and lazy-loaded sections, call `rv.webPlayer?.mount(selectorOrElement, overrides?)` after the element is in the DOM: ```js fetch('/article/123') .then((r) => r.text()) .then((html) => { document.getElementById('dynamic-area').innerHTML = html; const handle = rv.webPlayer?.mount('#dynamic-area', { theme: 'neutral' }); // later, before removing the element from the DOM: // handle?.unmount(); }); ``` Overrides are leaf-merged over the init config — `{ controls: { brand: false } }` keeps the rest of the init defaults intact. ## Skipping content [Section titled “Skipping content”](#skipping-content) Any element carrying `data-rv-skip` is excluded from narration: ```html

Read this paragraph.

This block is skipped.

Continue reading from here.

``` ## Next steps [Section titled “Next steps”](#next-steps) * [Web Player Customization](/examples/web-player-customization) — live control panel for every option. # Web Player Customization > Live control panel for every webPlayer option — theme, controls, navigation, layout, and CSS spacing variable. Tune every `webPlayer` option in real time. Each toggle re-mounts the player via `rv.webPlayer.mount()` with leaf-merged overrides, and the matching JSON config snippet updates alongside the player so you can copy-paste the result into your own setup. Tip [Live demo](https://examples.responsivevoice.org/browser/web-player-customization/) · [Source code](https://github.com/responsivevoice/examples/tree/main/browser/web-player-customization) ## What you can tweak [Section titled “What you can tweak”](#what-you-can-tweak) * **Theme** — `Neutral`, `ResponsiveVoice`, or custom tokens (9-token color picker covering bg, fg, muted, accent, accentSoft, hover, border, track, fill). * **Controls** — toggle progress, time, skip, speed, brand individually. Play / pause is always shown. * **Navigation** — paragraph highlight and click-to-jump independently. * **Position** — main-pill placement: keyword (`before` / `after` / `inline`) relative to the container, or `{ target, at }` for a custom mount target. * **Layout** — main-pill width (`shrink` / `fill`) and outer display (`block` / `inline`). * **Mini-Player** — visibility, viewport corner (or CSS-offset object), and entrance/exit animation. * **Sanitize** — keep scripts, styles, controls, and media out of narration (on by default), plus extra `exclude` selectors of your own. * **Spacing** — the `--rv-player-margin` CSS custom property, controlling the player's surrounding margin. ## How re-mount works [Section titled “How re-mount works”](#how-re-mount-works) The example panel keeps a single mount handle and replaces it on every change: ```js let handle = null; function remount() { handle?.unmount(); handle = rv.webPlayer?.mount('#sample', buildConfig()); } ``` `buildConfig()` reads the panel state and returns a `WebPlayerMountOverrides` object that's leaf-merged over the init config. The same shape works in `rv.init({ features: { webPlayer: ... } })` for static sites. ## Custom mount target [Section titled “Custom mount target”](#custom-mount-target) The `position` field accepts either a keyword (`'before'`, `'after'`, `'inline'`) relative to `selector`, or an object that mounts the player into any element on the page. This is useful when the article element is constrained by your layout (sidebar, fixed slot, CMS-driven composition): ```ts rv.webPlayer?.mount('#article', { position: { target: '#player-slot', at: 'inside' }, }); ``` `at` accepts `'inside'` (first child of the target, the default), `'before'` (sibling before), or `'after'` (sibling after). `target` is required — the keyword form covers the article-relative case. If `target` doesn't match anything in the DOM at mount time, the player falls back to the keyword `'before'` and logs a warning. ## Mini-player position [Section titled “Mini-player position”](#mini-player-position) The floating mini-player surfaces when the main player scrolls out of view. Its viewport corner is configurable via `miniPlayer.position`: ```ts rv.webPlayer?.mount('#article', { miniPlayer: { enabled: true, position: 'bottom-right' }, }); ``` Accepted values: * A corner keyword: `'top-left'`, `'top-right'`, `'bottom-left'`, `'bottom-right'`. Default `'bottom-left'`. * A CSS-offset object: `{ top, right, bottom, left }`, each a CSS length string. At least one side is required; opposing sides (`top` + `bottom`, `left` + `right`) are rejected. ```ts rv.webPlayer?.mount('#article', { miniPlayer: { enabled: true, position: { top: '80px', right: '20px' } }, }); ``` The boolean shorthand is the natural form for the on/off case — `miniPlayer: true` enables the mini-player at the default corner, `miniPlayer: false` disables it. ## Mini-player animation [Section titled “Mini-player animation”](#mini-player-animation) `miniPlayer.animation` controls how the mini-player enters and leaves as you scroll: ```ts rv.webPlayer?.mount('#article', { miniPlayer: { enabled: true, animation: 'fade' }, }); ``` Accepted values: * `'slide'` — fades in and slides from the docked corner. Default. * `'fade'` — fades in and out, no movement. * `'pop'` — fades in with a brief scale-up. * `'none'` — appears and disappears instantly. The slide direction follows where the mini-player sits: anything in the lower half of the viewport rises into place, anything in the upper half drops in — so corner keywords and custom offsets both enter from the nearest edge. Motion is skipped automatically when the browser requests reduced motion, so every preset falls back to an instant swap for those readers. ## Choosing a voice per player [Section titled “Choosing a voice per player”](#choosing-a-voice-per-player) By default every web player narrates with the website's default voice (the `voice` profile from `/v2/config`). The web-player config exposes four flat playback fields — `voice`, `rate`, `pitch`, `volume` — that mirror the arguments of `core.speak(text, voice, params)`. Each is independently optional and overrides the website default for one player: ```ts rv.webPlayer?.mount('#article', { voice: 'US English Male', rate: 0.9, }); ``` `voice` accepts the full [`VoiceSelector`](/guides/voice-selection/) grammar. In JS, write whichever form is most natural — strings for named voices, real `RegExp` literals for patterns, plain objects for structured queries. The schema normalizes a `RegExp` to its JSON-clean `{ regex, flags }` form on parse, so the same selector works identically in JS, server config, and every SDK language: ```ts // 1. Exact voice name rv.webPlayer?.mount('#en-article', { voice: 'UK English Female', }); // 2. Structured query — pick a Portuguese female voice from any provider rv.webPlayer?.mount('#pt-article', { voice: { lang: 'pt', gender: 'female' }, }); // 3. Regex pattern — first voice whose name matches rv.webPlayer?.mount('#multi-article', { voice: /English.*Male/i, }); ``` The shape parallels `speak()` directly: ```ts // Direct speak() call: rv.speak('Hello', /UK English/, { rate: 0.9, volume: 0.8 }); // ^text ^voice ^speech params // Equivalent web-player config — same fields, same names: rv.webPlayer?.mount('#article', { voice: /UK English/, rate: 0.9, volume: 0.8, }); ``` ### Setting a default for every player [Section titled “Setting a default for every player”](#setting-a-default-for-every-player) The same fields are valid in the website config (`webPlayer.voice` / `rate` / `pitch` / `volume`), in which case every auto-discovered article starts with those values instead of the website-wide default: ```ts rv.init({ features: { webPlayer: { enabled: true, voice: 'US English Male', rate: 0.95, }, }, }); ``` Per-mount overrides leaf-merge over this config, so a player that mounts with `{ rate: 1.2 }` keeps the `'US English Male'` voice and only changes the rate. ### What inherits, what overrides [Section titled “What inherits, what overrides”](#what-inherits-what-overrides) Each playback field is independently optional. Any field you omit falls through to the website default voice profile (the profile's `name` becomes the string-form `voice` selector when none is set): | Field | When omitted | | -------- | --------------------------------------------------------- | | `voice` | Inherits the website default voice's `name` as a selector | | `pitch` | Inherits the website default `pitch` | | `rate` | Inherits the website default `rate` | | `volume` | Inherits the website default `volume` | ## Next steps [Section titled “Next steps”](#next-steps) * [Web Player Example](/examples/web-player) — the basic integration without the customization panel. * [Voice Selection](/guides/voice-selection/) — the full `VoiceSelector` grammar used by the `voice` field. # Installation > How to install ResponsiveVoice packages ## Core package [Section titled “Core package”](#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 [Section titled “API client”](#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 [Section titled “Types package”](#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 [Section titled “Requirements”](#requirements) ### Browsers [Section titled “Browsers”](#browsers) Chrome 66+, Firefox 57+, Safari 12+, Edge 17+, iOS Safari 12+, Chrome Android 66+. The browser bundle (CDN) includes all necessary polyfills and works in these browsers without any additional setup. ESM/CJS packages are syntax-compatible but leave browser polyfilling to your bundler. ### Node.js [Section titled “Node.js”](#nodejs) | 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 [Section titled “TypeScript”](#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. ## Overview [Section titled “Overview”](#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 [Section titled “Installation Changes”](#installation-changes) ### Before [Section titled “Before”](#before) ```html ``` ### After [Section titled “After”](#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 [Section titled “API Mapping”](#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 [Section titled “Configuration Changes”](#configuration-changes) ### Before [Section titled “Before”](#before-1) ```javascript // Global configuration via URL parameter ; // Or via global variable window.responsiveVoice.setDefaultVoice('UK English Female'); ``` ### After [Section titled “After”](#after-1) * Browser bundle (CDN) ```html ``` * npm ```typescript import { getResponsiveVoice } from '@responsivevoice/core'; const rv = await getResponsiveVoice({ apiKey: 'YOUR_KEY', defaultVoice: 'UK English Female', }); ``` ## Event System [Section titled “Event System”](#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 [Section titled “Breaking Changes”](#breaking-changes) Caution The following changes may require code updates: ### 1. Voice Data is Fetched at Runtime [Section titled “1. Voice Data is Fetched at Runtime”](#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 [Section titled “2. No Internet Explorer Support”](#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 [Section titled “TypeScript Support”](#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 [Section titled “Troubleshooting”](#troubleshooting) ### "Voice not found" Error[Section titled “"Voice not found" Error”](#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[Section titled “"API key required" Error”](#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[Section titled “Audio Not Playing on iOS”](#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? [Section titled “Need Help?”](#need-help) * [GitHub Issues](https://github.com/responsivevoice/core/issues) * [API Reference](/api/core/src/) * [Support](https://responsivevoice.org/support) # Quick Start > Get up and running with ResponsiveVoice in minutes ## Basic Usage [Section titled “Basic Usage”](#basic-usage) Drop in the script tag or install from npm — both reach the same API: * Browser bundle (CDN) ```html ``` * 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 [Section titled “Voice Selection”](#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 [Section titled “Playback Control”](#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 [Section titled “Events”](#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. # For AI Agents > Machine-readable documentation for LLMs and AI agents — llms.txt, full/abridged text bundles, and per-page Markdown. This documentation ships a machine-readable layer for LLMs and AI agents. Every page is available as plain text and Markdown, with curated bundles for whole-site ingestion. ## Agent Skill [Section titled “Agent Skill”](#agent-skill) Teach your coding agent to install and run ResponsiveVoice with one command: ```bash npx skills add responsivevoice/skills ``` It installs into Claude Code, Cursor, GitHub Copilot, Gemini CLI, and other agents that read filesystem [Agent Skills](https://github.com/responsivevoice/skills), covering the browser library, REST API, and language SDKs. ## Endpoints [Section titled “Endpoints”](#endpoints) [/llms.txt ](/llms.txt)Index of the documentation sets, following the llmstxt.org convention. [/llms-full.txt ](/llms-full.txt)The complete documentation as a single text file. [/llms-small.txt ](/llms-small.txt)An abridged build with non-essential content removed. [/llms.md ](/llms.md)A Markdown index of every page. ## Per-page Markdown [Section titled “Per-page Markdown”](#per-page-markdown) Append `.md` to any documentation URL to get its Markdown source — for example, `/getting-started/installation.md`. ## Discovery [Section titled “Discovery”](#discovery) * `robots.txt` advertises the XML sitemap (`/sitemap-index.xml`) and permits search indexing and AI grounding. * `/llms.txt` is served at the well-known path from the [llmstxt.org](https://llmstxt.org) convention. # App Features > Configure the no-code website voice features available from the ResponsiveVoice app. The [ResponsiveVoice app](https://app.responsivevoice.org) lets you turn website voice features on and off without writing custom JavaScript. These features use the same v2 configuration that powers the SDK, so changes made in the app are reflected in the website configuration returned to your installed ResponsiveVoice script. ![The ResponsiveVoice app's website configuration page: site details at the top and the full list of voice-feature toggles below.](/img/app/dashboard.png) [Open the ResponsiveVoice app ](https://app.responsivevoice.org)Configure these features for your site — no code required. Note Some features speak on their own — a few, like the welcome message, as soon as the page loads. Browsers don't allow audio until the visitor interacts with the page, so these play once the visitor responds to ResponsiveVoice's built-in permission prompt, which captures that first interaction automatically. ## Quick Reference [Section titled “Quick Reference”](#quick-reference) | Feature | What it does | | ----------------------------------------------------- | -------------------------------------------------------------------- | | [Welcome message](#welcome-message) | Speaks a short message after the page loads. | | [Speak selected text](#speak-selected-text) | Speaks text the visitor highlights. | | [Speak links](#speak-links) | Speaks link text when the visitor hovers over a link. | | [Accessibility navigation](#accessibility-navigation) | Speaks interactive elements as the visitor tabs through the page. | | [Paragraph navigation](#paragraph-navigation) | Lets visitors move through readable text with Ctrl+Up and Ctrl+Down. | | [Inactivity message](#inactivity-message) | Speaks after a period without visitor interaction. | | [End-of-page message](#end-of-page-message) | Speaks when the visitor reaches the bottom of the page. | | [Exit-intent message](#exit-intent-message) | Speaks when the visitor moves toward leaving the page. | | [Multiple messages](#multiple-messages) | Rotates between several message variants. | | [Web player](#web-player) | Adds an article reader with highlighting and a mini-player. | ## Welcome Message [Section titled “Welcome Message”](#welcome-message) The welcome message speaks a short greeting or instruction shortly after a visitor opens the page. Use it for a brief introduction, not for long announcements. A good message tells visitors what they can do next, for example: "Welcome. Select any text to hear it spoken aloud." Configuration notes: * Enable **Welcome message** in the app. * Enter the message text. * Use **Play welcome message once per session** when repeat playback would be annoying. * Preview the message before saving. Troubleshooting: * The message plays once the visitor responds to the permission prompt — browsers don't allow audio before that first interaction, so it won't speak the instant the page loads. * Keep the text short so it does not overlap with other automatic messages. ## Speak Selected Text [Section titled “Speak Selected Text”](#speak-selected-text) Speak selected text lets visitors highlight text on the page and hear it spoken aloud. This is useful for readers who want help with a sentence, word, product description, or article section without playing the whole page. Configuration notes: * Enable **Speak selected text** in the app. * Save the configuration and reload the website page. * Test by selecting a short piece of visible text. Troubleshooting: * Text inside buttons, forms, scripts, or hidden elements may not be suitable for selection playback. * If a page prevents text selection with CSS or custom JavaScript, this feature may not trigger. ## Speak Links [Section titled “Speak Links”](#speak-links) Speak links reads the visible text of a link when a visitor hovers over it. This helps visitors understand where a link goes before activating it. It works best when links have meaningful labels such as "View pricing" rather than vague labels such as "Click here." Configuration notes: * Enable **Speak links** in the app. * Save and reload the website page. * Hover over a normal text link to test it. Troubleshooting: * Links with no visible text or only decorative icons may not produce useful speech. * For keyboard-first navigation, use [Accessibility navigation](#accessibility-navigation). ## Accessibility Navigation [Section titled “Accessibility Navigation”](#accessibility-navigation) Accessibility navigation speaks interactive elements as visitors move through the page with the Tab key. It is intended for links, buttons, and form controls. The spoken text comes from the element label, accessible name, or visible text. Configuration notes: * Enable **Speak interactive elements using the Tab key** in the app. * Save and reload the website page. * Press Tab through the page and listen to each focused element. Troubleshooting: * If an element has no useful label, improve its visible text, `aria-label`, or associated form label. * Avoid enabling too many automatic speech features on the same page until you have tested the experience. ## Paragraph Navigation [Section titled “Paragraph Navigation”](#paragraph-navigation) Paragraph navigation lets visitors move through readable page content with Ctrl+Up and Ctrl+Down while hearing the current paragraph. This is useful for long-form pages, help articles, and documentation where visitors may want keyboard control over reading. Configuration notes: * Enable **Speak paragraph using CTRL-UP and CTRL-DOWN keys** in the app. * Save and reload the website page. * Test on a content-heavy page with normal paragraphs and headings. Troubleshooting: * Short pages may not have enough readable blocks for this to feel useful. * Pages with unusual markup may need the [Web Player advanced content settings](/guides/web-player/#advanced) instead. ## Inactivity Message [Section titled “Inactivity Message”](#inactivity-message) The inactivity message speaks after the visitor has not interacted with the page for a period of time. Use it carefully. The best messages are short and helpful, such as "Still there? You can press play to listen to this page." Configuration notes: * Enable **Inactivity message** in the app. * Enter the message text. * Preview the message before saving. Troubleshooting: * Do not combine long inactivity, welcome, end-of-page, and exit-intent messages without testing the page flow. * If visitors report unexpected audio, shorten the message or disable this feature on quieter pages. ## End-of-Page Message [Section titled “End-of-Page Message”](#end-of-page-message) The end-of-page message speaks when the visitor reaches the bottom of the page. Use it as a closing prompt, such as a support reminder, next step, or short call to action. Configuration notes: * Enable **End-of-page message** in the app. * Enter the message text. * Scroll to the bottom of a test page after saving. Troubleshooting: * Infinite-scroll pages or pages with dynamically loaded content may need extra testing. * Keep the message short enough that it does not interrupt normal navigation. ## Exit-Intent Message [Section titled “Exit-Intent Message”](#exit-intent-message) The exit-intent message speaks when the visitor moves the pointer toward leaving the page. Use it sparingly. It can be helpful for short reminders, but it can also surprise visitors if it is too long or too frequent. Configuration notes: * Enable **Exit-intent message** in the app. * Enter a short message. * Test by moving the pointer toward the top of the browser window. Troubleshooting: * Exit intent is pointer-based and may not apply on all touch devices. * Avoid using this feature for essential information. ## Multiple Messages [Section titled “Multiple Messages”](#multiple-messages) Message fields can contain several alternatives separated by a pipe character (`|`). ResponsiveVoice chooses one at random when the feature speaks. Example: ```text Welcome to our site.|Need help? Select any text to hear it spoken.|You can listen to this page while you browse. ``` This works for message-style features such as welcome, inactivity, end-of-page, and exit-intent messages. Tips: * Keep each variant short. * Do not put a pipe character inside the message itself. * Preview several times when testing random messages. ## Web Player [Section titled “Web Player”](#web-player) The web player adds a visible article reader with paragraph highlighting, click-to-jump, and playback controls. This is what your visitors see: ![The web player's pill control: a play button, speed, skip buttons, a progress bar with elapsed and total time, and the ResponsiveVoice brand icon.](/img/web-player/player-controls.png) When the main control scrolls out of view, a floating mini-player keeps playback within reach: ![The floating mini-player docked in the bottom-left corner, with a circular progress ring around the play button.](/img/web-player/mini-player.png) You configure all of this from the **Web Player** panel in the app — no code required. Each section below maps an app setting to what it does. Developers installing or overriding the player in code should use the [Web Player guide](/guides/web-player/) instead. ### Theme [Section titled “Theme”](#theme) Choose a preset — **Neutral** or **ResponsiveVoice** — or set custom colors to match your brand. ![The Theme section of the app's Web Player panel.](/img/web-player/settings-theme.png) ### Layout [Section titled “Layout”](#layout) ![The Layout section of the app's Web Player panel: Position, Width, and Display.](/img/web-player/settings-layout.png) | App field | Default | What it does | | --------- | ------------------------- | ------------------------------------------------------------------------ | | Position | *Before the content* | Mounts the player before, after, inline inside, or inside a custom slot. | | Width | *Shrink to content* | Shrink hugs the controls; Fill spans the container. | | Display | *Block (on its own line)* | Block gives the player its own line; Inline flows with surrounding text. | ### Controls [Section titled “Controls”](#controls) ![The Controls section of the app's Web Player panel: show/hide checkboxes for each control, plus the floating mini-player options.](/img/web-player/settings-controls.png) | App field | Default | What it does | | --------------------- | ------------- | ------------------------------------------------------------- | | Progress | *On* | Shows progress through the readable content. | | Time | *On* | Shows elapsed and total estimated time. | | Skip | *On* | Shows previous and next paragraph buttons. | | Speed | *On* | Shows the speed cycle button. | | Brand | *On* | Shows the ResponsiveVoice brand icon. | | Floating mini-player | *On* | Shows the mini-player when the main player is out of view. | | Mini-player position | *Bottom left* | Places the mini-player in a viewport corner or custom offset. | | Mini-player animation | *Slide* | Uses Slide, Fade, Pop, or None. | ### Behavior [Section titled “Behavior”](#behavior) ![The Behavior section of the app's Web Player panel: toggles for Highlight paragraphs, Click to jump, and Skip code & hidden content.](/img/web-player/settings-behavior.png) | App field | Default | What it does | | -------------------------- | ------- | ------------------------------------------------------------------------------------------- | | Highlight paragraphs | *On* | Highlights the currently spoken element. | | Click to jump | *On* | Lets visitors click a paragraph to start reading there. | | Skip code & hidden content | *On* | Excludes scripts, styles, form controls, embedded media, and hidden content from narration. | ### Advanced [Section titled “Advanced”](#advanced) ![The Advanced section of the app's Web Player panel: Content container, Paragraphs to read, Voice override, and Exclude from narration.](/img/web-player/settings-advanced.png) | App field | Default | What it does | | ---------------------- | ----------------- | -------------------------------------------------------------------- | | Content container | *article* | CSS selector for the element that contains readable content. | | Paragraphs to read | *p, h2, h3, li* | CSS selector for the readable elements inside the container. | | Voice override | *Website default* | Optional voice for this player only. | | Exclude from narration | *empty* | Extra CSS selectors to skip, in addition to the built-in exclusions. | ### Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) #### The player doesn't appear [Section titled “The player doesn't appear”](#the-player-doesnt-appear) Confirm the **Web Player** toggle is on and your ResponsiveVoice script is installed on the page. If you set a **Content container**, make sure it matches an element that exists on the page. #### The player is in the wrong place [Section titled “The player is in the wrong place”](#the-player-is-in-the-wrong-place) Adjust **Position** under Layout. If your theme wraps the whole page in one article, point **Content container** at the specific content area instead. #### The wrong text is read, or paragraphs are missing [Section titled “The wrong text is read, or paragraphs are missing”](#the-wrong-text-is-read-or-paragraphs-are-missing) Check that **Paragraphs to read** matches your content, and that nothing you want read is being removed by **Skip code & hidden content** or **Exclude from narration**. #### The mini-player doesn't appear [Section titled “The mini-player doesn't appear”](#the-mini-player-doesnt-appear) Confirm **Floating mini-player** is on, then scroll until the main player leaves view while it is playing. ### Live preview and testing [Section titled “Live preview and testing”](#live-preview-and-testing) Use the app preview to confirm the experience before saving, then test once on the real site too: * Press play and confirm the selected voice sounds right. * Confirm the progress, time, skip, speed, and brand controls match the Controls panel. * Click a paragraph if **Click to jump** is enabled. * Confirm highlighting appears if **Highlight paragraphs** is enabled. * Scroll until the main player leaves view and confirm the mini-player appears if enabled. * Add a known excluded element and confirm it is skipped. ### Advanced Usage [Section titled “Advanced Usage”](#advanced-usage) Need to install, theme, or override the player in code? The developer guide covers the programmatic path with `init()` and `mount()`. [Web Player guide (for developers) ](/guides/web-player/)Configure and override the web player programmatically with init() and mount(). # Browser Support > Browser and platform compatibility for ResponsiveVoice ResponsiveVoice works across all modern browsers with automatic fallback. @responsivevoice/api-client * ![Chrome](/_astro/chrome.CRByiUFQ_ZIwTCu.svg)Chrome66+ * ![Firefox](/_astro/firefox.1bWoP6pv_ZXpkDg.svg)Firefox57+ * ![Safari](/_astro/safari.na3_-uQk_PMAUK.svg)Safari12+ * ![Edge](/_astro/edge.HDH_c98u_1zCODK.svg)Edge17+ * ![Opera](/_astro/opera.BNOhXFRG_2faPJg.svg)Opera53+ * ![iOS Safari](/_astro/safari.na3_-uQk_PMAUK.svg)iOS Safari12+ * ![Chrome Android](/_astro/chrome.CRByiUFQ_ZIwTCu.svg)Chrome Android66+ * ![Android WebView](/_astro/android-webview_64x64._FpYT5CQ_1iPoo.webp)Android WebView66+ @responsivevoice/core * ![Chrome](/_astro/chrome.CRByiUFQ_ZIwTCu.svg)Chrome66+ * ![Firefox](/_astro/firefox.1bWoP6pv_ZXpkDg.svg)Firefox57+ * ![Safari](/_astro/safari.na3_-uQk_PMAUK.svg)Safari14+ * ![Edge](/_astro/edge.HDH_c98u_1zCODK.svg)Edge16+ * ![Opera](/_astro/opera.BNOhXFRG_2faPJg.svg)Opera53+ * ![iOS Safari](/_astro/safari.na3_-uQk_PMAUK.svg)iOS Safari14+ * ![Chrome Android](/_astro/chrome.CRByiUFQ_ZIwTCu.svg)Chrome Android66+ * ![Android WebView](/_astro/android-webview_64x64._FpYT5CQ_1iPoo.webp)Android WebView66+ *Data generated from [MDN Browser Compat Data](https://github.com/mdn/browser-compat-data)* Note Firefox has limited native voice support. ResponsiveVoice automatically uses the fallback API when needed. Tip `@responsivevoice/types` is pure TypeScript with no browser runtime requirements. ## How Fallback Works [Section titled “How Fallback Works”](#how-fallback-works) ![Diagram](/d2/docs/guides/browser-support-0.svg) ## Native vs Fallback [Section titled “Native vs Fallback”](#native-vs-fallback) | Feature | Native (Web Speech API) | Fallback (API) | | --------------- | ----------------------- | -------------- | | Latency | Instant | \~100–300 ms\* | | Offline | | | | Voice quality | Varies by OS | Consistent | | Boundary events | | | | SSML support | | | Note \* Fallback synthesis typically returns audio in \~100–300 ms; cached phrases in under 100 ms. Longer or uncached requests may take up to \~700 ms. These figures are indicative, not a guarantee. ## Platform-Specific Notes [Section titled “Platform-Specific Notes”](#platform-specific-notes) ### Chrome / Chromium [Section titled “Chrome / Chromium”](#chrome--chromium) * Best voice selection with Google TTS voices * Voices like "Google UK English Female" available * Full boundary event support * May require user interaction to start audio ### Safari / iOS [Section titled “Safari / iOS”](#safari--ios) * Apple voices with "(Enhanced)" variants * Good offline voice quality * iOS requires user gesture to begin playback * Some voices locked to specific iOS versions ### Firefox [Section titled “Firefox”](#firefox) * Limited native voice support * Falls back to API more frequently * No boundary events when using fallback * Full functionality with API fallback ### Edge [Section titled “Edge”](#edge) * Windows voices available (David, Zira, etc.) * Good Web Speech API support * Microsoft neural voices on Windows 10+ ## Mobile Considerations [Section titled “Mobile Considerations”](#mobile-considerations) ### iOS [Section titled “iOS”](#ios) ```typescript // Optional: trigger speech from your own button instead of the built-in prompt document.getElementById('speakBtn').addEventListener('click', () => { rv.speak('Hello from iOS', 'UK English Female'); }); ``` Tip Mobile browsers (iOS, and Android Chrome) block autoplay, so audio needs a user gesture — but ResponsiveVoice handles this automatically with a built-in permission prompt that captures the first tap and unlocks audio. You can disable it and drive speech from your own UI (like the button above). See [the FAQ](/guides/faq/#does-responsivevoice-work-on-ios). ### Android [Section titled “Android”](#android) * Android Chrome requires a user gesture before audio — handled automatically by the same built-in permission prompt as iOS * Voice availability varies by device manufacturer * Google TTS voices commonly available * May need to download voices in system settings ### Android WebView [Section titled “Android WebView”](#android-webview) Caution The Web Speech API (native TTS) is **not supported** in Android WebView. ResponsiveVoice automatically falls back to the API for all speech synthesis. * Minimum supported: Android WebView 66+ * Native TTS unavailable - always uses API fallback * Audio playback works normally via Audio element * Common in hybrid apps (Cordova, Capacitor, React Native WebView) ## Node.js Support [Section titled “Node.js Support”](#nodejs-support) ResponsiveVoice works in Node.js environments using the [`@responsivevoice/api-client`](/getting-started/installation/#api-client) package. The minimum Node.js version varies by package: | Package | Minimum Node.js | | -------------------------------- | --------------- | | `@responsivevoice/types`, `text` | 14+ | | `@responsivevoice/api-client` | 16+ | `@responsivevoice/core` and `@responsivevoice/features` target the browser — Node is only their build environment (bundle with Vite/webpack), not a runtime. ### Node.js 18+ (recommended) [Section titled “Node.js 18+ (recommended)”](#nodejs-18-recommended) All features work out of the box with native `fetch`, `Blob`, and `AbortController`: ```typescript import { ResponsiveVoiceAPIClient } from '@responsivevoice/api-client'; const client = new ResponsiveVoiceAPIClient({ apiKey: process.env.RESPONSIVEVOICE_API_KEY, apiSecret: process.env.RESPONSIVEVOICE_API_SECRET, }); const audio = await client.synthesize({ text: 'Hello from Node.js', voice: 'UK English Female', }); ``` ### Node.js 16–17 [Section titled “Node.js 16–17”](#nodejs-1617) Native `fetch` is not available. Pass a fetch implementation via the `fetch` config option: ```typescript import fetch from 'node-fetch'; import { ResponsiveVoiceAPIClient } from '@responsivevoice/api-client'; const client = new ResponsiveVoiceAPIClient({ apiKey: process.env.RESPONSIVEVOICE_API_KEY, apiSecret: process.env.RESPONSIVEVOICE_API_SECRET, fetch, }); ``` ### WebSocket streaming on Node.js < 22 [Section titled “WebSocket streaming on Node.js < 22”](#websocket-streaming-on-nodejs--22) The global `WebSocket` was added in Node.js 22. On older versions, pass a WebSocket implementation: ```typescript import WebSocket from 'ws'; import { WebSocketConnection } from '@responsivevoice/api-client'; const ws = new WebSocketConnection({ baseUrl: 'https://texttospeech.responsivevoice.org', apiKey: process.env.RESPONSIVEVOICE_API_KEY, WebSocket, }); ``` ## Feature Detection [Section titled “Feature Detection”](#feature-detection) Check platform capabilities: ```typescript // Check if the Web Speech API is available const hasNativeTTS = 'speechSynthesis' in window; // Whether ResponsiveVoice can use native voices on this platform const nativeSupported = rv.isNativeSupported(); // Check if a voice name is in the resolvable catalog const voices = rv.getVoices(); const hasUKFemale = voices.some((v) => v.name === 'UK English Female'); // Native <-> fallback switches are reported via the OnServiceSwitched event rv.addEventListener('OnServiceSwitched', (payload) => { console.log(`Switched from ${payload.from} to ${payload.to}`); }); ``` ## Forcing Fallback [Section titled “Forcing Fallback”](#forcing-fallback) Force server (fallback) audio even when native voices exist — set it at init or toggle at runtime: ```typescript // At init const rv = await getResponsiveVoice({ apiKey: 'YOUR_API_KEY', forceFallback: true, }); // Or at runtime rv.setForceFallback(true); ``` ## User Interaction Requirements [Section titled “User Interaction Requirements”](#user-interaction-requirements) Modern browsers require user interaction before playing audio: ```typescript // ❌ This may be blocked window.onload = () => { rv.speak('Hello'); // Blocked by autoplay policy }; // ✅ This works button.onclick = () => { rv.speak('Hello'); // Allowed - user initiated }; ``` ### Workaround: Initialize on First Interaction [Section titled “Workaround: Initialize on First Interaction”](#workaround-initialize-on-first-interaction) On mobile, ResponsiveVoice's built-in permission prompt already unlocks audio on the first gesture — use this manual pattern only if you've disabled the prompt and want to unlock from your own handler: ```typescript let initialized = false; document.addEventListener( 'click', () => { if (!initialized) { rv.speak('', 'UK English Female'); // Silent init initialized = true; } }, { once: true }, ); ``` ## Testing Across Platforms [Section titled “Testing Across Platforms”](#testing-across-platforms) ```typescript // Log platform info for debugging console.log({ browser: navigator.userAgent, hasNativeTTS: 'speechSynthesis' in window, nativeVoices: window.speechSynthesis?.getVoices().length ?? 0, rvVoices: rv.getVoices().length, }); ``` # Events > Handling speech events and callbacks ## Event System [Section titled “Event System”](#event-system) ResponsiveVoice gives you two ways to observe speech: * **Per-call callbacks** — passed inline to `speak()`, bound to that one utterance, and reset on the next `speak()`. * **Global events** — registered once with `addEventListener()`, firing across every `speak()` call. Tip Try the [**live Events & Callbacks demo**](https://examples.responsivevoice.org/browser/events-callbacks/) — every per-call callback and global event lights up as you click Speak. The companion [docs page](/examples/events-callbacks) explains the design. ## Per-call callbacks [Section titled “Per-call callbacks”](#per-call-callbacks) Pass these in the options object of `speak(text, voice?, options?)`. They belong to a single utterance. | Callback | Signature | Fires | | ------------ | ------------------------------------------- | ---------------------------------------------- | | `onstart` | `() => void` | speech begins | | `onend` | `() => void` | speech completes | | `onerror` | `(error: Error) => void` | an error occurs | | `onboundary` | `(charIndex: number, name: string) => void` | crosses a word/sentence boundary (native only) | ```typescript rv.speak('Hello world', 'UK English Female', { onstart: () => console.log('Started speaking'), onend: () => console.log('Finished speaking'), onerror: (error) => console.error('Error:', error.message), onboundary: (charIndex, name) => { console.log(`Boundary (${name}) at character ${charIndex}`); }, }); ``` Note `onboundary` only fires with native browser voices, not the fallback (server) audio engine. ## Global events [Section titled “Global events”](#global-events) Register once with `addEventListener(name, handler)`; they fire across every `speak()` call. Event names are PascalCase: | Event | Payload | Fires | | ---------------------- | --------------------------------- | ------------------------------------------- | | `OnReady` | — | client initialized and ready | | `OnLoad` | — | alias of `OnReady` (legacy) | | `OnStart` | — | an utterance starts | | `OnEnd` | — | an utterance ends | | `OnPause` | — | speech is paused | | `OnResume` | — | speech resumes | | `OnError` | `{ error, message? }` | an error occurs | | `OnVoiceResolved` | voice-resolution details | a voice is resolved for an utterance | | `OnServiceSwitched` | `{ from, to }` | engine switches between native and fallback | | `OnPartStart` | `{ partIndex, totalParts, text }` | a text chunk starts speaking | | `OnPartEnd` | `{ partIndex, totalParts, text }` | a text chunk finishes | | `OnClickEvent` | — | a user gesture (click) is detected | | `OnAllowSpeechClicked` | `{ allowed }` | user responds to the permission prompt | ```typescript rv.addEventListener('OnStart', () => console.log('Speech started')); rv.addEventListener('OnPause', () => console.log('Speech paused')); rv.addEventListener('OnResume', () => console.log('Speech resumed')); ``` Pause and resume are **only** global events — they are not per-call callbacks. See the [`RVEventType` reference](/api/types/src/#rveventtypeschema) for the complete list of event names. ### Removing listeners [Section titled “Removing listeners”](#removing-listeners) Pass the same handler reference you registered: ```typescript const handler = () => console.log('Speech started'); rv.addEventListener('OnStart', handler); rv.removeEventListener('OnStart', handler); ``` ## Error handling [Section titled “Error handling”](#error-handling) The per-call `onerror` callback receives a standard [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error). The `OnError` event delivers a payload `{ error, message? }` whose `error` is that same `Error`: ```typescript rv.speak('Hello', 'UK English Female', { onerror: (error) => { console.error('Speech failed:', error.message); }, }); ``` ## Async/await pattern [Section titled “Async/await pattern”](#asyncawait-pattern) Wrap `speak()` in a Promise using `onend` and `onerror`: ```typescript function speakAsync(text: string, voice: string): Promise { return new Promise((resolve, reject) => { rv.speak(text, voice, { onend: () => resolve(), onerror: (error) => reject(error), }); }); } // Usage async function readParagraphs(paragraphs: string[]) { for (const paragraph of paragraphs) { await speakAsync(paragraph, 'UK English Female'); } console.log('All paragraphs read'); } ``` ## Progress tracking UI [Section titled “Progress tracking UI”](#progress-tracking-ui) Use `onboundary` to update a progress bar as speech advances (native voices only): ```typescript let startTime: number; rv.speak(longText, 'UK English Female', { onstart: () => { startTime = Date.now(); progressBar.style.width = '0%'; }, onboundary: (charIndex) => { const progress = (charIndex / longText.length) * 100; progressBar.style.width = `${progress}%`; }, onend: () => { progressBar.style.width = '100%'; console.log(`Completed in ${Date.now() - startTime}ms`); }, }); ``` ## Queue events [Section titled “Queue events”](#queue-events) Each `speak()` call carries its own callbacks: ```typescript rv.speak('First sentence', 'UK English Female', { onend: () => console.log('First done, starting second'), }); rv.speak('Second sentence', 'UK English Female', { onstart: () => console.log('Second starting'), onend: () => console.log('Queue complete'), }); ``` # Frequently Asked Questions > Common questions about ResponsiveVoice — pricing, browser and Node.js support, API keys, streaming, and available voices. ResponsiveVoice is TypeScript-first text-to-speech for browsers and Node.js. Answers to the questions we hear most often are below. ## Is ResponsiveVoice free to use?[Section titled “Is ResponsiveVoice free to use?”](#is-responsivevoice-free-to-use) Yes. The ResponsiveVoice library is open source and free to use from npm or a CDN. Create a free account at [responsivevoice.org/register](https://responsivevoice.org/register) — it takes a few seconds — to unlock free server voices for your site. Without an account the library runs in demo mode. Paid plans add features such as streaming, and premium voice providers (Microsoft Azure, OpenAI, Google Cloud) are supported via Bring Your Own Key (BYOK). ## Which browsers and runtimes are supported?[Section titled “Which browsers and runtimes are supported?”](#which-browsers-and-runtimes-are-supported) ResponsiveVoice runs in all evergreen browsers and in Node.js, using the native Web Speech API where available and server voices (with an account) otherwise. See the [Browser Support](/guides/browser-support/) guide for the full compatibility matrix. ## Do I need an API key?[Section titled “Do I need an API key?”](#do-i-need-an-api-key) Yes, to use server voices — and it's free. Register an account to get one. The key is a website identity, not a secret: it's tied to your registered domain, so it's safe to include in client-side code. Without a key, the library runs in demo mode. ## Does ResponsiveVoice support streaming audio?[Section titled “Does ResponsiveVoice support streaming audio?”](#does-responsivevoice-support-streaming-audio) Yes — on higher-tier plans. Audio is delivered as it's synthesized via HTTP audio streaming or WebSocket streaming, so playback can start before the full clip is ready. Other tiers return the complete audio in a single response. ## How many voices and languages are available?[Section titled “How many voices and languages are available?”](#how-many-voices-and-languages-are-available) The base catalog includes around 100 voices across many languages and genders, chosen through the [voice resolution chain](/guides/voice-selection/) (native Web Speech or fallback). Bring Your Own Key (BYOK) providers add their own voices on top — growing the catalog to thousands. ## Does ResponsiveVoice work on iOS?[Section titled “Does ResponsiveVoice work on iOS?”](#does-responsivevoice-work-on-ios) Yes. iOS (and some mobile browsers) require a user gesture before audio can play, and ResponsiveVoice handles that automatically — it shows a built-in permission prompt that captures the first tap and unlocks audio, so you don't need to add your own button. The prompt is customizable, or you can disable it and trigger speech from your own UI instead. ## How can I improve speech quality?[Section titled “How can I improve speech quality?”](#how-can-i-improve-speech-quality) Punctuation shapes pacing and emphasis — add commas and periods for natural pauses. For tricky pronunciations, respell a word phonetically, add hyphens between syllables, or spell it out letter by letter. You can also configure text replacements for consistent pronunciation of names and domain terms. ## Can I change the speaking rate, pitch, and volume?[Section titled “Can I change the speaking rate, pitch, and volume?”](#can-i-change-the-speaking-rate-pitch-and-volume) Yes. Set `rate` and `pitch` (0–2, default 1) and `volume` (0–1, default 1) per request. Native browser voices (Web Speech API) apply them directly; for voices that synthesize server-side — API-only voices, or when the browser lacks the requested voice — how each adjustment applies depends on that provider. ## Does ResponsiveVoice support SSML?[Section titled “Does ResponsiveVoice support SSML?”](#does-responsivevoice-support-ssml) SSML (voice markup) is part of the Web Speech API specification, but no current browser actually implements it, and there's no announced commitment to add it. So ResponsiveVoice takes plain text — shape delivery with the `rate`, `pitch`, and `volume` parameters, plus punctuation and text replacements for pacing and pronunciation. If browsers add SSML support, ResponsiveVoice will adopt it. # Text Chunking > How ResponsiveVoice handles long text ## Overview [Section titled “Overview”](#overview) ResponsiveVoice automatically splits long text into smaller chunks for optimal playback. This ensures reliable speech synthesis even with large amounts of text. ## Why Chunking? [Section titled “Why Chunking?”](#why-chunking) * **API Limits**: TTS services have character limits per request * **Memory**: Smaller audio buffers are more efficient * **Responsiveness**: Speech starts faster with smaller chunks * **Reliability**: Reduces chance of timeouts and errors ## Automatic Chunking [Section titled “Automatic Chunking”](#automatic-chunking) Chunking happens automatically when you call `speak()`: ```typescript // This long text is automatically split into chunks responsiveVoice.speak( ` Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris. `, 'UK English Female', ); ``` ## Chunk Boundaries [Section titled “Chunk Boundaries”](#chunk-boundaries) Within the character limit, text is split at the latest (rightmost) natural boundary, preferring higher-priority delimiters first: 1. **Sentence endings** (`.` `?` `!`) 2. **Major separators** (`;` `:`) 3. **Clause separators** (`,`) 4. **Word boundaries** (spaces) 5. **CJK character boundaries** (between ideographs, when no earlier boundary fits) Tip The chunker never splits in the middle of a word, and skips `.`/`,` inside numbers like `3.14` or `1,000`. ## Default Limits [Section titled “Default Limits”](#default-limits) | Setting | Value | Description | | ------------------ | --------- | -------------------------------------- | | Default chunk size | 100 chars | Characters per chunk when not set | | Min chunk size | 50 chars | Lower bound (smaller values clamp up) | | Max chunk size | 300 chars | Upper bound (larger values clamp down) | | Sentence priority | High | Prefers sentence boundaries | ## Custom Configuration [Section titled “Custom Configuration”](#custom-configuration) The chunk character limit is a page-wide setting. Set it globally: * Browser bundle (CDN) ```html ``` * npm (ESM) ```typescript import { getResponsiveVoice } from '@responsivevoice/core'; // At startup const rv = await getResponsiveVoice({ characterLimit: 150 }); // clamped to 50–300 // Or at runtime rv.setCharacterLimit(150); rv.getCharacterLimit(); // 150 ``` Note Examples below use the browser bundle's global `responsiveVoice`. With the npm package, call the same methods on the instance returned by `getResponsiveVoice()`. ## Seamless Playback [Section titled “Seamless Playback”](#seamless-playback) Chunks are queued and played sequentially without gaps: ```typescript responsiveVoice.speak(longArticle, 'UK English Female', { onstart: () => console.log('Started reading article'), onend: () => console.log('Finished reading article'), // onend fires once when ALL chunks complete }); ``` ## Manual Chunking [Section titled “Manual Chunking”](#manual-chunking) For complete control, split the text yourself with `chunkText()`. Each chunk is `{ text, index, total, isLast }`: ```typescript const chunks = responsiveVoice.chunkText(article, { characterLimit: 200 }); for (const chunk of chunks) { await new Promise((resolve) => responsiveVoice.speak(chunk.text, 'UK English Female', { onend: resolve }), ); } ``` `chunkText` is also importable standalone from `@responsivevoice/text`. ## Progress with Chunks [Section titled “Progress with Chunks”](#progress-with-chunks) Track progress across chunks: ```typescript const chunks = responsiveVoice.chunkText(longText, { characterLimit: 200 }); let currentChunk = 0; function speakNextChunk() { if (currentChunk >= chunks.length) { console.log('Complete!'); return; } const chunk = chunks[currentChunk]; const progress = ((chunk.index + 1) / chunk.total) * 100; console.log(`Progress: ${progress.toFixed(0)}%`); responsiveVoice.speak(chunk.text, 'UK English Female', { onend: () => { currentChunk++; speakNextChunk(); }, }); } speakNextChunk(); ``` ## Special Characters [Section titled “Special Characters”](#special-characters) The chunker is aware of: * **Numbers**: won't split on `.` or `,` inside a number (`3.14`, `1,000`) * **Grouping pairs**: prefers not to split inside quotes, parentheses, or brackets ```typescript // Numbers stay intact responsiveVoice.speak('The price is $19.99 per month.', voice); // Quoted text is kept together responsiveVoice.speak('She said "Hello there, friend!" and waved.', voice); ``` ## SSML [Section titled “SSML”](#ssml) ResponsiveVoice takes **plain text**, not SSML — no current browser implements the Web Speech API's SSML, so it isn't supported. Shape delivery with the `rate`, `pitch`, and `volume` parameters plus punctuation. See the [FAQ](/guides/faq/#does-responsivevoice-support-ssml). ## Performance Tips [Section titled “Performance Tips”](#performance-tips) 1. **Pre-chunk large texts** for better control 2. **Keep `characterLimit` within range** (50–300; default 100) 3. **Avoid very small chunks** (causes choppy playback) 4. **Consider caching** for repeated content # Voice Resolver Hook > Intercept and transform voice selectors before resolution ## Overview [Section titled “Overview”](#overview) The `resolveVoice` hook lets integrating applications intercept the voice selector passed to `speak()` and transform it before the voice matching chain runs. This is useful when an external system passes voice names that don't match ResponsiveVoice's voice catalogue — instead of modifying every call site, a single hook can remap, normalize, or redirect selectors. ## Usage [Section titled “Usage”](#usage) ```typescript import { getResponsiveVoice } from '@responsivevoice/core'; const rv = await getResponsiveVoice({ apiKey: 'YOUR_KEY', resolveVoice: (selector) => { if (typeof selector === 'string') { const aliases: Record = { 'Google UK English Female': 'UK English Female', 'Microsoft Zira': 'US English Female', }; return aliases[selector] ?? selector; } return selector; }, }); // "Google UK English Female" is silently remapped to "UK English Female" rv.speak('Hello', 'Google UK English Female'); ``` ## Hook Signature [Section titled “Hook Signature”](#hook-signature) ```typescript type ResolveVoiceHook = ( selector: VoiceSelector | undefined, ) => VoiceSelector | undefined; ``` | Parameter | Type | Description | | ----------- | ---------------------------- | ----------------------------------------------------------------------- | | `selector` | `VoiceSelector \| undefined` | The incoming voice selector, or `undefined` when no voice was specified | | **Returns** | `VoiceSelector \| undefined` | A transformed selector, or `undefined` to use `defaultVoice` | `VoiceSelector` is a union of three forms (the post-parse output the hook receives): | Type | JS form | Wire form | Meaning | | --------------- | --------------------- | ------------------------------------ | -------------------------------- | | `string` | `'UK English Female'` | same | Resolve by exact voice name | | `RegexSelector` | `/Portuguese/` | `{ regex: 'Portuguese', flags: '' }` | First voice matching the pattern | | `VoiceQuery` | `{ lang: 'pt' }` | same | Structured filter (AND logic) | The hook receives the post-parse `VoiceSelector`, where any incoming JS `RegExp` has already been normalized to the `{ regex, flags }` literal form. The hook's return value can be either form — a returned `RegExp` is normalized the same way before reaching the resolver. ## Return Value Semantics [Section titled “Return Value Semantics”](#return-value-semantics) | Hook returns | What happens | | ----------------------------- | ----------------------------------------------------- | | A `string` | Resolves by name (exact match, then fallback chain) | | A `RegExp` or `RegexSelector` | Resolves by pattern (first match) | | A `VoiceQuery` | Resolves by structured query (lang, gender, provider) | | `undefined` | Falls through to the configured `defaultVoice` | Caution The hook does **not** fire when `params.voice` is set. That escape hatch passes a raw `SpeechSynthesisVoice` object and bypasses the entire resolution chain, including the hook. ## Patterns [Section titled “Patterns”](#patterns) ### Static aliasing [Section titled “Static aliasing”](#static-aliasing) Map legacy or external voice names to ResponsiveVoice names: ```typescript resolveVoice: (selector) => { if (typeof selector === 'string') { const map: Record = { 'old-voice-name': 'UK English Female', 'legacy-male': 'US English Male', }; return map[selector] ?? selector; } return selector; }, ``` ### Locale-based routing [Section titled “Locale-based routing”](#locale-based-routing) Redirect to a locale-appropriate voice when the exact name doesn't exist: ```typescript resolveVoice: (selector) => { if (typeof selector === 'string' && !knownVoices.has(selector)) { const locale = extractLocale(selector); const gender = extractGender(selector); return { lang: locale, gender }; } return selector; }, ``` ### Debug logging [Section titled “Debug logging”](#debug-logging) Observe what selectors are being passed without changing behavior: ```typescript resolveVoice: (selector) => { console.log('[RV] resolving voice:', selector); return selector; }, ``` ## TypeScript [Section titled “TypeScript”](#typescript) Both `ResolveVoiceHook` and `VoiceSelector` are exported from `@responsivevoice/core`: ```typescript import type { ResolveVoiceHook, VoiceSelector } from '@responsivevoice/core'; const myHook: ResolveVoiceHook = (selector) => { // your logic return selector; }; ``` # Voice Selection > How to select voices using names, patterns, and structured queries The second argument to `speak()` is a **voice selector** — a `string`, `RegExp`, or structured query that tells ResponsiveVoice which voice to use: ```typescript rv.speak(text: string, voice?: VoiceSelectorInput, params?: SpeakOptions): void; ``` `VoiceSelector` (the post-parse, on-the-wire form) is a union of three JSON-serializable shapes: | Type | JS form | Wire form | Description | | --------------- | --------------------- | ------------------------------------- | -------------------------------- | | `string` | `'UK English Female'` | same | Exact voice name | | `RegexSelector` | `/Portuguese/i` | `{ regex: 'Portuguese', flags: 'i' }` | First voice matching the pattern | | `VoiceQuery` | `{ lang: 'pt' }` | same | Structured filter (AND logic) | In JS code, pass a real `RegExp` literal and the schema normalizes it to the JSON-clean `{ regex, flags }` form on parse — the resolver, server payloads, and SDKs all see the wire form, so the contract is identical across every language. ## By Name [Section titled “By Name”](#by-name) The simplest form — pass a ResponsiveVoice voice name as a string: ```typescript rv.speak('Hello', 'UK English Female'); rv.speak('Hello', 'US English Male'); rv.speak('Bonjour', 'French Female'); rv.speak('Hallo', 'Deutsch Male'); ``` If the exact name isn't available on the current platform, the [voice matching chain](#voice-matching-chain) kicks in to find the closest alternative. ## By Pattern [Section titled “By Pattern”](#by-pattern) Pass a `RegExp` to match against all non-deprecated voice names. The first match wins: ```typescript rv.speak('Olá', /Portuguese/); rv.speak('Hello', /English.*Female/i); ``` In server-side config or non-JS SDKs (Python, Go, PHP, Java), use the JSON literal form instead — it's the same selector after the schema normalizes: ```json { "regex": "Portuguese" } { "regex": "English.*Female", "flags": "i" } ``` Tip Pattern matching is useful when you want any voice from a family (e.g., any Portuguese variant) rather than a specific voice name. ## By Query [Section titled “By Query”](#by-query) Pass a `VoiceQuery` object to filter voices by attributes. All conditions are AND-ed — a voice must match every specified field: | Field | Type | Behavior | | ---------- | ---------------------------------- | --------------------------------------------------- | | `name` | `string` | Case-insensitive; exact match first, then substring | | `lang` | `string` | BCP-47 prefix match (`"pt"` matches `"pt-BR"`) | | `gender` | `'f' \| 'm' \| 'male' \| 'female'` | Gender filter | | `isByok` | `boolean` | Filter to BYOK (Bring Your Own Key) voices only | | `provider` | `string` | Provider name, case-insensitive | ```typescript // By language rv.speak('Bonjour', { lang: 'fr' }); // By language + gender rv.speak('Olá', { lang: 'pt', gender: 'f' }); // By provider (BYOK voices) rv.speak('Hello', { provider: 'Google Cloud WaveNet', lang: 'en-GB', gender: 'm', }); ``` ## Direct Voice Override [Section titled “Direct Voice Override”](#direct-voice-override) When you have a raw `SpeechSynthesisVoice` object from the browser's Web Speech API, you can pass it directly via the `params.voice` option: ```typescript const nativeVoices = speechSynthesis.getVoices(); const samantha = nativeVoices.find((v) => v.name === 'Samantha'); rv.speak('Hello', undefined, { voice: samantha }); ``` Caution This bypasses the entire ResponsiveVoice resolution chain, including the [`resolveVoice` hook](/guides/voice-resolver/). The voice must be a valid `SpeechSynthesisVoice` from the current browser. ## Default Voice [Section titled “Default Voice”](#default-voice) When no voice selector is passed to `speak()`, the configured default voice is used. The built-in default is `'UK English Female'`. ```typescript // Set at init const rv = await getResponsiveVoice({ apiKey: 'YOUR_KEY', defaultVoice: 'US English Female', }); rv.speak('Uses US English Female'); // Change at runtime rv.setDefaultVoice('French Male'); rv.speak('Uses French Male now'); ``` ## Language-Aware Website Widgets [Section titled “Language-Aware Website Widgets”](#language-aware-website-widgets) ResponsiveVoice accepts a language query, but your interface decides when to change languages. A multilingual website widget should normally use this precedence: 1. A voice explicitly chosen by the visitor 2. Language detected from text the visitor typed 3. The browser's preferred language 4. English fallback using `UK English Female` ```typescript function browserLanguage(): string { return (navigator.languages?.[0] || navigator.language || 'en') .toLowerCase() .split('-')[0]; } function selectorForLanguage(language: string) { const lang = language.toLowerCase().split('-')[0]; // Keep the English experience consistent and premium by default. if (lang === 'en') return 'UK English Female'; return { lang, gender: 'f' } as const; } function speakVisitorText(text: string, selectedVoice?: string) { // Supply this with your preferred client-side or server-side detector. const typedLanguage = text.length >= 20 ? detectLanguage(text) : undefined; const language = typedLanguage || browserLanguage(); const voice = selectedVoice || selectorForLanguage(language); rv.speak(text, voice); } ``` Use browser language to initialize placeholder text and the first suggested voice. Re-run language detection after the visitor types enough text to make a useful decision, but do not override a manual voice selection. Note The SDK does not guess the language of arbitrary text. Keep detection in the application so you can choose the detector, confidence threshold, privacy behavior, and fallback policy that fit your site. ## Force Fallback [Section titled “Force Fallback”](#force-fallback) Set `forceFallback` to skip native browser voices entirely and always use server-side HTTP audio. This provides consistent voice quality across all browsers: ```typescript const rv = await getResponsiveVoice({ apiKey: 'YOUR_KEY', forceFallback: true, }); // Toggle at runtime rv.setForceFallback(false); ``` ## Resolution Precedence [Section titled “Resolution Precedence”](#resolution-precedence) When `speak()` is called, voice selection resolves in this order (highest priority first): 1. **`params.voice` override** — direct `SpeechSynthesisVoice` object; bypasses everything below 2. **[`resolveVoice` hook](/guides/voice-resolver/)** — intercepts and transforms the selector before resolution 3. **Explicit `VoiceSelector`** — the `string`, `RegExp` (or its `{ regex, flags? }` wire form), or `VoiceQuery` passed to `speak()` 4. **`defaultVoice` config** — used when no selector is provided ## Voice Matching Chain [Section titled “Voice Matching Chain”](#voice-matching-chain) Once a voice name is determined, ResponsiveVoice walks the voice's internal chain of system voice IDs and tries these matching strategies **in order across all chain entries** (strategy-first): 1. **Exact match** — direct name comparison against browser voices 2. **Whitespace normalized** — handles Chrome's Unicode non-breaking spaces (U+00A0) in Asian voice names 3. **Parenthetical stripped** — handles Apple Safari's "(Enhanced)" / "(Premium)" suffixes 4. **Partial match** — case-insensitive substring match 5. **Language fallback** — any browser voice matching the target language 6. **HTTP fallback** — server-side TTS via the ResponsiveVoice API Tip Strategy-first iteration means an exact match later in the chain always beats a partial match earlier in the chain. This ensures the most specific match wins. ## Listing Voices [Section titled “Listing Voices”](#listing-voices) Use `getVoices()` to list all available voices on the current platform: ```typescript const voices = rv.getVoices(); console.log(voices); // [ // { name: 'UK English Female', lang: 'en-GB', gender: 'f' }, // { name: 'UK English Male', lang: 'en-GB', gender: 'm' }, // { name: 'US English Female', lang: 'en-US', gender: 'f' }, // ... // ] ``` ## Platform-Specific Voices [Section titled “Platform-Specific Voices”](#platform-specific-voices) Some voices are only available on specific platforms: | Platform | Notes | | -------- | ------------------------------------ | | Chrome | Google voices, best selection | | Safari | Apple voices, "(Enhanced)" variants | | Firefox | Limited native voices, uses fallback | | iOS | Version-specific voice sets | | Android | Device-dependent voices | ## Language Codes [Section titled “Language Codes”](#language-codes) Voices use BCP-47 language codes: | Code | Language | | ------- | -------------------- | | `en-GB` | British English | | `en-US` | American English | | `fr-FR` | French | | `de-DE` | German | | `es-ES` | Spanish | | `ja-JP` | Japanese | | `zh-CN` | Chinese (Simplified) | ## Example: Voice Selector UI [Section titled “Example: Voice Selector UI”](#example-voice-selector-ui) Try all three selector forms side by side in the [**live Voice Selector demo**](https://examples.responsivevoice.org/browser/voice-selector/) — type a name, type a regex, or build a query and watch the snippet rewrite as you switch tabs. The accompanying [docs page](/examples/voice-selector) explains the design choices. The minimal pattern below shows the simplest case (build a dropdown from `getVoices()`): ```typescript // Build a voice selector dropdown const select = document.createElement('select'); rv.getVoices().forEach((voice) => { const option = document.createElement('option'); option.value = voice.name; option.textContent = `${voice.name} (${voice.lang})`; select.appendChild(option); }); select.addEventListener('change', () => { rv.speak('Sample text', select.value); }); ``` # Web Player > Configure the web player theme, layout, controls, behavior, and advanced narration options. The **web player** is a drop-in article reader with paragraph highlighting, click-to-jump, playback controls, and a floating mini-player that follows the reader once the main controls scroll out of view. You can add a default web player to any page **without code** from the [ResponsiveVoice Dashboard](/guides/app-features/#web-player). This guide covers the **code path** — installing, configuring, and overriding the player programmatically with `init()` and `mount()`. For live examples, see the [Web Player example](/examples/web-player/) and [Web Player Customization](/examples/web-player-customization/) pages. ## At a Glance [Section titled “At a Glance”](#at-a-glance) 1. Drop the CDN script in your page and call: ```javascript responsiveVoice.init({ apiKey: 'YOUR_API_KEY', features: { webPlayer: { enabled: true }, }, }); ``` 2. Choose a **Theme**: `neutral`, `responsivevoice`, or custom color tokens. 3. Set the **Layout** if the player should appear somewhere other than before the article. 4. Choose **Controls** such as progress, time, skip, speed, brand, and mini-player settings. 5. Tune **Behavior** such as paragraph highlighting, click-to-jump, and skipping non-readable content. 6. Use **Advanced** only when you need custom selectors, voice override, or extra narration exclusions. ## Add the Script and Initialize [Section titled “Add the Script and Initialize”](#add-the-script-and-initialize) Drop the CDN bundle into your page and turn the player on. By default it attaches to the first `
` element it finds and narrates every `p`, `h2`, `h3`, and `li` inside it. ```html ``` If your page has an `
`, the player appears above it after initialization. Note `init()` is async because it fetches your website configuration. The player mounts once initialization resolves; you do not need to `await` anything for a static `
` already in the DOM. ## Theme optional [Section titled “Theme ”](#theme) Theme controls the visual style of the player. Two presets ship with the player, plus a custom-token path for brand colors. Tabs preserve your selection across pages. * Neutral The default theme is light, minimal, and designed to sit comfortably on most host pages. No extra configuration is needed: ```js window.responsiveVoice.init({ apiKey: 'YOUR_API_KEY', features: { webPlayer: { enabled: true }, }, }); ``` * ResponsiveVoice The ResponsiveVoice theme uses the same controls and layout, recolored around the ResponsiveVoice violet. ```js window.responsiveVoice.init({ apiKey: 'YOUR_API_KEY', features: { webPlayer: { enabled: true, theme: 'responsivevoice' }, }, }); ``` * Custom tokens Override individual color tokens to match your brand. Every field is optional; omitted values fall back to the neutral defaults. ```js window.responsiveVoice.init({ apiKey: 'YOUR_API_KEY', features: { webPlayer: { enabled: true, theme: { fill: '#10b981', track: '#d1fae5', accentSoft: '#d1fae5', }, }, }, }); ``` The full nine-token palette is `bg`, `fg`, `muted`, `accent`, `accentSoft`, `hover`, `border`, `track`, and `fill`. The [customization picker](https://examples.responsivevoice.org/browser/web-player-customization/) lets you tune those values and copy the matching configuration. ## Layout optional [Section titled “Layout ”](#layout) Layout controls where the player appears and how much space it uses. | Config option | Default | What it does | | ---------------- | ---------- | ------------------------------------------------------------------------------- | | `position` | `'before'` | Mounts the player before, after, inline inside, or inside a custom target. | | `layout.mode` | `'shrink'` | `shrink` hugs the controls; `fill` spans the container. | | `layout.display` | `'block'` | `block` gives the player its own line; `inline` flows with surrounding content. | ```js window.responsiveVoice.init({ apiKey: 'YOUR_API_KEY', features: { webPlayer: { enabled: true, position: 'before', layout: { mode: 'shrink', display: 'block', }, }, }, }); ``` For a custom mount target, pass an object: ```js window.responsiveVoice.init({ apiKey: 'YOUR_API_KEY', features: { webPlayer: { enabled: true, position: { target: '#article-player', at: 'inside', }, }, }, }); ``` ## Controls optional [Section titled “Controls ”](#controls) Controls decide which buttons are visible and whether the floating mini-player is enabled. | Config option | Default | What it does | | ---------------------- | --------------- | ------------------------------------------------------------- | | `controls.progress` | `true` | Shows progress through the readable content. | | `controls.time` | `true` | Shows elapsed and total estimated time. | | `controls.skip` | `true` | Shows previous and next paragraph buttons. | | `controls.speed` | `true` | Shows the speed cycle button. | | `controls.brand` | `true` | Shows the ResponsiveVoice brand icon. | | `miniPlayer.enabled` | `true` | Shows the mini-player when the main player is out of view. | | `miniPlayer.position` | `'bottom-left'` | Places the mini-player in a viewport corner or custom offset. | | `miniPlayer.animation` | `'slide'` | Uses `none`, `fade`, `slide`, or `pop`. | ```js window.responsiveVoice.init({ apiKey: 'YOUR_API_KEY', features: { webPlayer: { enabled: true, controls: { progress: true, time: true, skip: true, speed: true, brand: true, }, miniPlayer: { enabled: true, position: 'bottom-left', animation: 'slide', }, }, }, }); ``` ## Behavior optional [Section titled “Behavior ”](#behavior) Behavior covers highlighting, click-to-jump, and skipping non-readable content. | Config option | Default | What it does | | ------------------------------- | ------- | ------------------------------------------------------------------------------------------- | | `navigation.paragraphHighlight` | `true` | Highlights the currently spoken element. | | `navigation.paragraphClick` | `true` | Lets visitors click a paragraph to start reading there. | | `sanitize.enabled` | `true` | Excludes scripts, styles, form controls, embedded media, and hidden content from narration. | ```js window.responsiveVoice.init({ apiKey: 'YOUR_API_KEY', features: { webPlayer: { enabled: true, navigation: { paragraphHighlight: true, paragraphClick: true, }, sanitize: { enabled: true }, }, }, }); ``` Keep `sanitize.enabled` on for normal sites. Turning it off narrates raw matched text and is mainly useful for debugging unusual markup. ## Advanced optional [Section titled “Advanced ”](#advanced) Advanced options are for site-specific markup and voice overrides. Most websites can leave these at their defaults. Use them when the player needs to read a specific part of a page, skip extra elements, or use a different voice from the website default. | Config option | Default | What it does | | ------------------- | ----------------- | ------------------------------------------------------------------- | | `selector` | `'article'` | CSS selector for the element that contains readable content. | | `paragraphSelector` | `'p, h2, h3, li'` | CSS selector for readable elements inside the container. | | `voice` | Website default | Optional voice selector for this player only. | | `sanitize.exclude` | `[]` | Extra CSS selectors to skip in addition to the built-in exclusions. | ```js window.responsiveVoice.init({ apiKey: 'YOUR_API_KEY', features: { webPlayer: { enabled: true, selector: '.post-body', paragraphSelector: 'p, h2, h3, blockquote', voice: 'UK English Female', sanitize: { enabled: true, exclude: ['.pull-quote', '.byline'], }, }, }, }); ``` If `selector` matches more than one element on the page, every match gets its own independent player. Starting playback on one automatically pauses every other player. Nested matches, such as an `
` inside another `
`, are filtered to the outermost element so duplicate players are not created. ### Place the Player in a specific container [Section titled “Place the Player in a specific container”](#place-the-player-in-a-specific-container) Many WordPress themes and marketing sites wrap the entire page in an `
`. In that layout, the default `selector: 'article'` can place the player above the page title and narrate calls to action or other content that is not part of the listening experience. Use a purpose-built content container and player slot instead: ```html

A better way to experience the web

Visitors can listen while they commute, work, or rest their eyes.

The current passage is highlighted as the article is read.

``` ```js window.responsiveVoice.webPlayer?.mount('#article-preview', { voice: 'UK English Female', theme: 'responsivevoice', paragraphSelector: 'h2, p', position: { target: '#article-player', at: 'inside', }, }); ``` This pattern is useful for product pages too: place a short, representative article demo after trust proof such as customer logos, then let visitors try the same player their readers would receive. ### Voice Override [Section titled “Voice Override”](#voice-override) Without configuration, the player narrates with the website default voice. To override per player, add a `voice` field. It accepts a name string, a `RegExp`, or a structured query, exactly like the second argument to `speak()`. ```js window.responsiveVoice.init({ apiKey: 'YOUR_API_KEY', features: { webPlayer: { enabled: true, voice: 'UK English Female', rate: 0.95, }, }, }); ``` The full grammar lives in [Voice Selection](/guides/voice-selection/). The same `voice`, `rate`, `pitch`, and `volume` fields are also valid as per-mount overrides on `mount()`. ### Exclude From Narration [Section titled “Exclude From Narration”](#exclude-from-narration) Mark any element with `data-rv-skip` to keep it out of the narration. The player still highlights surrounding paragraphs; the skipped element is invisible to the reader's progression. ```html

Read this paragraph.

Continue from here.

``` Useful for code blocks, figure captions, ad slots, pull quotes, and bylines. By default the player never reads content that is not visible prose. Scripts, styles, form controls, embedded media, and elements marked `hidden` or `aria-hidden="true"` are excluded from narration even when they sit inside a matched paragraph. A paragraph left empty after sanitization is dropped from the reading flow. Add your own selectors with `sanitize.exclude`. Those selectors are added to the built-in exclusions; they do not replace the built-in list. ## Testing [Section titled “Testing”](#testing) After integrating, verify on the real page — its markup determines what's found and narrated: * Press play and confirm the selected voice sounds right. * Confirm the configured controls (progress, time, skip, speed, brand) appear. * Click a paragraph if `navigation.paragraphClick` is enabled. * Confirm highlighting appears if `navigation.paragraphHighlight` is enabled. * Scroll until the main player leaves view and confirm the mini-player appears if enabled. * Add a known excluded element and confirm it is skipped. ## Dynamic Content [Section titled “Dynamic Content”](#dynamic-content) For SPAs and lazy-loaded sections, the article may not be in the DOM when `init()` runs, so the auto-discovery pass misses it. Use `webPlayer.mount()` to attach a player after the element is rendered: ```js const html = await fetch('/posts/123').then((r) => r.text()); document.getElementById('post-area').innerHTML = html; const handle = window.responsiveVoice.webPlayer?.mount('#post-area'); // later, before removing the element: handle?.unmount(); ``` `mount()` accepts the same option shape as the init config, leaf-merged over it. For example, `mount('#post-area', { rate: 1.2 })` keeps every other setting intact and only changes the rate. It returns `null` if the feature is not enabled or the element cannot be found, so the `?.` guards are intentional. Caution Always call `handle.unmount()` before you remove the host element from the DOM. The player keeps DOM listeners attached to the article and the document. A forgotten unmount will not crash anything, but it can leak event handlers across SPA navigations. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### The player doesn't appear[Section titled “The player doesn't appear”](#the-player-doesnt-appear) * Confirm `init()` ran and resolved, and `features.webPlayer.enabled` is `true`. * Confirm `selector` matches an element that is already in the DOM when `init()` runs. Content rendered later (SPA, lazy-load) is missed by the one-time auto-discovery pass — mount it explicitly with [`mount()`](#dynamic-content). ### `mount()` returned `null`[Section titled “mount() returned null”](#mount-returned-null) It returns `null` when the feature isn't enabled or the target element isn't in the DOM — which is why the `?.` guards matter. Confirm `enabled: true` and that the element exists before the call. ### The wrong content is read, or paragraphs are missing[Section titled “The wrong content is read, or paragraphs are missing”](#the-wrong-content-is-read-or-paragraphs-are-missing) * `paragraphSelector` must match the elements you want narrated (default `p, h2, h3, li`). * Sanitization drops scripts, styles, form controls, media, and `hidden` / `aria-hidden` nodes, plus anything matching `data-rv-skip` or your `sanitize.exclude` selectors; a paragraph left empty after sanitization is skipped. ### The mini-player doesn't appear[Section titled “The mini-player doesn't appear”](#the-mini-player-doesnt-appear) `miniPlayer.enabled` must be `true`, and it only surfaces while playback is active and the main player has scrolled out of view. ### Handlers leak across SPA navigations[Section titled “Handlers leak across SPA navigations”](#handlers-leak-across-spa-navigations) Call `handle.unmount()` before removing the host element — the player keeps listeners on the article and document until you do. ## Next Steps [Section titled “Next Steps”](#next-steps) [Live demo ](https://examples.responsivevoice.org/browser/web-player/)The basic integration running in your browser. Source on GitHub, ready to copy and adapt. [Customize live ](https://examples.responsivevoice.org/browser/web-player-customization/)Tweak every option in real time. The matching init() and mount() snippets update alongside the player. [Web Player example walkthrough ](/examples/web-player/)In-docs walkthrough of multi-mount, imperative mount, and skipped content. [Voice Selection ](/guides/voice-selection/)The selector grammar used by the voice field: name string, regex, or structured query. # Why ResponsiveVoice? > How ResponsiveVoice v2 compares to ElevenLabs, Microsoft Azure, and Google Cloud for adding text-to-speech to a website. ResponsiveVoice is an open-source, TypeScript-first text-to-speech layer for the web. It is the integration and control layer between your site and one or more voice engines — browser-native, ResponsiveVoice's hosted voices, or premium providers you bring yourself. Note ResponsiveVoice v2 is a complete rewrite of the original library — MIT-licensed, fully typed, and split into focused packages. Older reviews describing it as a fixed-price Web Speech API wrapper predate this release. ## What ResponsiveVoice gives you [Section titled “What ResponsiveVoice gives you”](#what-responsivevoice-gives-you) * **Open source, MIT-licensed.** The client (`@responsivevoice/core`) is a drop-in replacement for the legacy `responsivevoice.js` — same `speak`/`cancel`/`pause`/`resume` API, now typed and tree-shakeable. * **Browser-native with automatic fallback.** Uses the Web Speech API when the device has a matching voice, and falls back to hosted server voices when it doesn't — one API, consistent behavior across browsers. * **100+ voices across 50+ languages**, fetched and cached at runtime, so the catalog improves without a package upgrade. * **Bring Your Own Key (BYOK).** Route premium voices from **Google Cloud**, **Microsoft Azure**, and **OpenAI** through ResponsiveVoice using your own provider key — you keep the provider relationship and the per-character billing, and gain RV's browser integration, fallback, streaming, and player features on top. * **Streaming playback.** HTTP audio or WebSocket, so speech starts before the full clip is ready. * **Predictable pricing.** A free plan plus fixed-tier plans, instead of metering every character. * **REST + WebSocket API** documented by an OpenAPI 3.1 specification, for server-side and non-browser use. ## How it compares [Section titled “How it compares”](#how-it-compares) The premium providers below produce excellent neural audio. The distinction is that ResponsiveVoice is the **integration layer** — and with BYOK it can front those same providers rather than competing with them. | Capability | ResponsiveVoice | ElevenLabs | Azure / Google Cloud | | ------------------------- | -------------------------------- | ---------------------------- | -------------------- | | Open source (MIT) | Yes | No | No | | Drop-in browser script | Yes | Via your own backend | Via your own backend | | Browser-native + fallback | Yes | Cloud only | Cloud only | | Premium neural voices | Via BYOK (Azure, OpenAI, Google) | Native | Native | | Voice cloning | No | Yes | Limited | | Pricing model | Free plan + fixed tiers | Per-character / subscription | Per-character | | Streaming | HTTP + WebSocket | Yes | Yes | ## When to choose what [Section titled “When to choose what”](#when-to-choose-what) * **Choose ResponsiveVoice** when you want a drop-in, open-source browser TTS with native-plus-fallback behavior, predictable pricing, and the option to bring premium provider voices via BYOK without re-architecting — read-aloud, accessibility, language learning, article narration, and announcements. * **Choose a provider directly** when best-in-class voice cloning or maximum expressive realism is the product itself, and you're set up to manage the integration and per-character billing. Many sites use both: ResponsiveVoice for the browser integration and player, with a premium provider supplied via BYOK for the voices. ## Next steps [Section titled “Next steps”](#next-steps) * [Installation](/getting-started/installation/) — add the script or install from npm. * [Voice Selection](/guides/voice-selection/) — filter and resolve voices. * [REST API Overview](/rest-api/overview/) — server-side synthesis. # Authentication > API key and secret authentication for the ResponsiveVoice REST API ## Authentication [Section titled “Authentication”](#authentication) Every REST API request is authenticated with two credentials sent as headers: * **`X-API-Key`** — your website's public identifier. * **`X-API-Secret`** — your non-public server credential. Both must be sent together: ```bash curl https://texttospeech.responsivevoice.org/v2/voices \ -H "X-API-Key: YOUR_API_KEY" \ -H "X-API-Secret: YOUR_API_SECRET" ``` ### Getting your credentials [Section titled “Getting your credentials”](#getting-your-credentials) Both live in your website's settings in the [ResponsiveVoice dashboard](https://app.responsivevoice.org) (no account yet? [sign up](https://responsivevoice.org/register)): * **API key** — shown in the "Your site code" snippet (`key: XXXXX`). * **API secret** — created under "Server-to-server API secrets". It is shown **only once** when generated, so copy it immediately; you can revoke it there at any time. Caution The API secret is a credential — keep it server-side. Never embed it in browser code or commit it to source control. Browser apps use the [`@responsivevoice/core`](/getting-started/quick-start/) SDK, which authenticates by origin and does not need the secret. # Error Handling > Error responses and rate limits for the ResponsiveVoice REST API ## Error Responses [Section titled “Error Responses”](#error-responses) All errors return JSON with an `error` object. Validation errors add an `errors` array detailing each problem: ```json { "error": { "message": "Language code is required", "code": "VALIDATION_ERROR", "statusCode": 400, "errors": ["Provide \"lang\" or \"voice\" parameter"] } } ``` ### Error Codes [Section titled “Error Codes”](#error-codes) | HTTP Code | Code | Description | | --------- | ---------------------------- | -------------------------------------------------------------------------------------- | | 400 | VALIDATION\_ERROR | Invalid request parameters | | 401 | UNAUTHORIZED | Invalid or missing API key or secret | | 404 | NOT\_FOUND | Voice or resource not found | | 429 | RATE\_LIMIT\_EXCEEDED | Tier request-rate limit exceeded | | 429 | BURST\_RATE\_LIMIT\_EXCEEDED | Too many requests from one client in a short window | | 500 | INTERNAL\_ERROR | Server error | | 502 | *(none)* | Upstream TTS provider error; `message` carries the provider's failure, no `code` field | ## Rate Limits [Section titled “Rate Limits”](#rate-limits) Rate limits apply per API key, which is required — requests without a valid key are rejected. The same limits apply to both the v1 and v2 APIs. | Plan | Requests per minute | | ---------- | ------------------- | | Free | 100 | | Commercial | 1,000 | | Enterprise | Custom | The per-minute limits above are counted per API key. A separate burst check applies per API key **and** client IP over a short window, so unusually rapid bursts from one client can be limited briefly even while you're under the per-minute limit. ### Monthly character quota [Section titled “Monthly character quota”](#monthly-character-quota) | Plan | Characters per month | | ---------- | ------------------------------------- | | Free | 1,000,000 | | Commercial | Fair use — contact us for high volume | | Enterprise | Custom | Keys that exceed the monthly quota are suspended until upgraded. Note A `429` carries a `Retry-After` header — the seconds to wait before retrying (dynamic; read and honor it, and the retry will succeed). The body `code` says which limit was hit: `RATE_LIMIT_EXCEEDED` (per-minute tier limit) or `BURST_RATE_LIMIT_EXCEEDED` (per API key + client IP burst). `X-RateLimit-Limit` and `X-RateLimit-Remaining` accompany responses and reflect the per-minute limit, so a burst `429` may show remaining requests alongside a short `Retry-After`. # Overview > Introduction to the ResponsiveVoice REST API ## ResponsiveVoice REST API [Section titled “ResponsiveVoice REST API”](#responsivevoice-rest-api) The ResponsiveVoice REST API generates speech audio from any language or platform — no website required. Use it for: * Server-side audio generation * Mobile apps (Android, iOS) and other non-browser clients * Batch processing of text to speech * Platforms without Web Speech API support **Base URL:** `https://texttospeech.responsivevoice.org/v2` Prefer a client library A client library wraps these endpoints with typing, retries, and streaming. For TypeScript or Node, use [`@responsivevoice/api-client`](/sdks/typescript/). From a language without a client library, call the REST endpoints directly as documented below. Tip Building a website rather than calling the API directly? Embed [`@responsivevoice/core`](/getting-started/quick-start/) instead — it speaks via the browser's Web Speech API and only falls back to this REST API when needed. ### Features [Section titled “Features”](#features) * **Multilingual built-in voice catalog** * **Streaming support** via HTTP audio streaming and WebSocket streaming * **BYOK premium providers** — bring your own provider API keys for premium voices * **CDN-cacheable** GET endpoint for efficient audio delivery * **HATEOAS navigation** links in voice responses ### Interactive Documentation [Section titled “Interactive Documentation”](#interactive-documentation) Explore the API interactively with the [Scalar API Reference](https://texttospeech.responsivevoice.org/reference). The full OpenAPI specification is available at [`/openapi.json`](https://texttospeech.responsivevoice.org/openapi.json) — import it into Postman, Insomnia, or other API tools. ### Endpoint Reference [Section titled “Endpoint Reference”](#endpoint-reference) Detailed endpoint documentation is auto-generated from the OpenAPI specification — see the [Endpoint Reference](/rest-api/reference/). V1 Deprecation V1 is deprecated. Only `GET /v1/text:synthesize` remains for backward compatibility with the legacy JS client. All new integrations should use the v2 endpoints documented in the [Endpoint Reference](/rest-api/reference/). # TypeScript SDK > Using @responsivevoice/api-client for typed TTS API access Official TypeScript client with full typing, retry logic, WebSocket streaming, and Node.js/browser support. Source: [`api-client`](https://github.com/responsivevoice/api-client). ## Installation [Section titled “Installation”](#installation) ```bash npm install @responsivevoice/api-client ``` ## Quick Start [Section titled “Quick Start”](#quick-start) ```typescript import { ResponsiveVoiceAPIClient } from '@responsivevoice/api-client'; const client = new ResponsiveVoiceAPIClient({ apiKey: process.env.RESPONSIVEVOICE_API_KEY, apiSecret: process.env.RESPONSIVEVOICE_API_SECRET, }); // Synthesize const audio = await client.synthesize({ text: 'Hello world', voice: 'UK English Female', format: 'mp3', }); console.log(audio.blob, audio.url, audio.format); // List voices (with optional filters) const { voices } = await client.getVoices({ lang: 'en-GB', gender: 'female' }); // Cancel a request const controller = new AbortController(); setTimeout(() => controller.abort(), 5_000); await client.synthesize( { text: 'Long text…', voice: 'UK English Female' }, { signal: controller.signal }, ); ``` ## Authentication [Section titled “Authentication”](#authentication) Server-side callers send an `apiKey` + `apiSecret` pair (the client attaches them as `X-API-Key` + `X-API-Secret`). Get both from your website's settings in the [ResponsiveVoice dashboard](https://app.responsivevoice.org) ([sign up](https://responsivevoice.org/register)): the **API key** from the "Your site code" snippet, and the **API secret** under "Server-to-server API secrets" (shown only once, revocable). Keep the secret server-side — browser apps use [`@responsivevoice/core`](/getting-started/quick-start/), which authenticates by origin and needs no secret. ## Runtime Notes [Section titled “Runtime Notes”](#runtime-notes) * **Node 18+**: works out of the box (native `fetch`, `Blob`, `AbortController`). * **Node 16–17**: pass a `fetch` polyfill via the `fetch` config option. * **Node < 22 + WebSocket streaming**: pass a `WebSocket` implementation (e.g. `ws`) to `WebSocketConnection`. ## Reference Documentation [Section titled “Reference Documentation”](#reference-documentation) * [API Reference (TypeDoc)](/api/api-client/src/) — complete typed API surface * [Package README on GitHub](https://github.com/responsivevoice/api-client#readme) — full walkthrough, all configuration options, error taxonomy, retry tuning Tip The client defaults to the v2 API base URL. For help: . # @responsivevoice/api-client > API documentation for @responsivevoice/api-client REST and WebSocket client for the ResponsiveVoice Text-to-Speech API. This is the Node.js entry point — re-exports the shared surface from `./index.common` and adds the Node-only `FileStorage` adapter plus its factory registration. Browsers resolve to `./index.browser` via the package `exports` map. ## Classes [Section titled “Classes”](#classes) ### ApiError [Section titled “ApiError”](#apierror) Defined in: [src/errors.ts:28](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L28) Error thrown when an API request fails #### Extends [Section titled “Extends”](#extends) * [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror) #### Extended by [Section titled “Extended by”](#extended-by) * [`AuthError`](/api/api-client/src/#autherror) * [`NotFoundError`](/api/api-client/src/#notfounderror) * [`RateLimitError`](/api/api-client/src/#ratelimiterror) * [`ValidationError`](/api/api-client/src/#validationerror) #### Constructors [Section titled “Constructors”](#constructors) ##### Constructor [Section titled “Constructor”](#constructor) ```ts new ApiError( message, status, statusText, url, body?, cause?): ApiError; ``` Defined in: [src/errors.ts:41](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L41) ###### Parameters [Section titled “Parameters”](#parameters) | Parameter | Type | | ------------ | --------- | | `message` | `string` | | `status` | `number` | | `statusText` | `string` | | `url` | `string` | | `body?` | `unknown` | | `cause?` | `Error` | ###### Returns [Section titled “Returns”](#returns) [`ApiError`](/api/api-client/src/#apierror) ###### Overrides [Section titled “Overrides”](#overrides) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`constructor`](/api/api-client/src/#constructor-10) #### Properties [Section titled “Properties”](#properties) ##### body? [Section titled “body?”](#body) ```ts readonly optional body?: unknown; ``` Defined in: [src/errors.ts:36](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L36) Response body, if available ##### cause? [Section titled “cause?”](#cause) ```ts readonly optional cause?: Error; ``` Defined in: [src/errors.ts:11](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L11) Original error that caused this error, if any ###### Inherited from [Section titled “Inherited from”](#inherited-from) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`cause`](/api/api-client/src/#cause-6) ##### message [Section titled “message”](#message) ```ts message: string; ``` Defined in: [lib.es5.d.ts:1075](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1075) ###### Inherited from [Section titled “Inherited from”](#inherited-from-1) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`message`](/api/api-client/src/#message-6) ##### name [Section titled “name”](#name) ```ts name: string; ``` Defined in: [lib.es5.d.ts:1074](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1074) ###### Inherited from [Section titled “Inherited from”](#inherited-from-2) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`name`](/api/api-client/src/#name-6) ##### stack? [Section titled “stack?”](#stack) ```ts optional stack?: string; ``` Defined in: [lib.es5.d.ts:1076](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1076) ###### Inherited from [Section titled “Inherited from”](#inherited-from-3) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`stack`](/api/api-client/src/#stack-6) ##### status [Section titled “status”](#status) ```ts readonly status: number; ``` Defined in: [src/errors.ts:30](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L30) HTTP status code of the failed request ##### statusText [Section titled “statusText”](#statustext) ```ts readonly statusText: string; ``` Defined in: [src/errors.ts:33](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L33) HTTP status text ##### url [Section titled “url”](#url) ```ts readonly url: string; ``` Defined in: [src/errors.ts:39](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L39) Request URL that failed #### Accessors [Section titled “Accessors”](#accessors) ##### isClientError [Section titled “isClientError”](#isclienterror) ###### Get Signature [Section titled “Get Signature”](#get-signature) ```ts get isClientError(): boolean; ``` Defined in: [src/errors.ts:60](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L60) Check if this error is a client error (4xx) ###### Returns [Section titled “Returns”](#returns-1) `boolean` ##### isRetryable [Section titled “isRetryable”](#isretryable) ###### Get Signature [Section titled “Get Signature”](#get-signature-1) ```ts get isRetryable(): boolean; ``` Defined in: [src/errors.ts:75](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L75) Check if this error is retryable Server errors (5xx) and rate limits (429) are retryable ###### Returns [Section titled “Returns”](#returns-2) `boolean` ##### isServerError [Section titled “isServerError”](#isservererror) ###### Get Signature [Section titled “Get Signature”](#get-signature-2) ```ts get isServerError(): boolean; ``` Defined in: [src/errors.ts:67](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L67) Check if this error is a server error (5xx) ###### Returns [Section titled “Returns”](#returns-3) `boolean` *** ### AuthError [Section titled “AuthError”](#autherror) Defined in: [src/errors.ts:83](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L83) Error thrown when authentication fails (401/403) #### Extends [Section titled “Extends”](#extends-1) * [`ApiError`](/api/api-client/src/#apierror) #### Constructors [Section titled “Constructors”](#constructors-1) ##### Constructor [Section titled “Constructor”](#constructor-1) ```ts new AuthError( message, status, statusText, url, body?): AuthError; ``` Defined in: [src/errors.ts:84](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L84) ###### Parameters [Section titled “Parameters”](#parameters-1) | Parameter | Type | | ------------ | --------- | | `message` | `string` | | `status` | `number` | | `statusText` | `string` | | `url` | `string` | | `body?` | `unknown` | ###### Returns [Section titled “Returns”](#returns-4) [`AuthError`](/api/api-client/src/#autherror) ###### Overrides [Section titled “Overrides”](#overrides-1) [`ApiError`](/api/api-client/src/#apierror).[`constructor`](/api/api-client/src/#constructor) #### Properties [Section titled “Properties”](#properties-1) ##### body? [Section titled “body?”](#body-1) ```ts readonly optional body?: unknown; ``` Defined in: [src/errors.ts:36](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L36) Response body, if available ###### Inherited from [Section titled “Inherited from”](#inherited-from-4) [`ApiError`](/api/api-client/src/#apierror).[`body`](/api/api-client/src/#body) ##### cause? [Section titled “cause?”](#cause-1) ```ts readonly optional cause?: Error; ``` Defined in: [src/errors.ts:11](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L11) Original error that caused this error, if any ###### Inherited from [Section titled “Inherited from”](#inherited-from-5) [`ApiError`](/api/api-client/src/#apierror).[`cause`](/api/api-client/src/#cause) ##### message [Section titled “message”](#message-1) ```ts message: string; ``` Defined in: [lib.es5.d.ts:1075](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1075) ###### Inherited from [Section titled “Inherited from”](#inherited-from-6) [`ApiError`](/api/api-client/src/#apierror).[`message`](/api/api-client/src/#message) ##### name [Section titled “name”](#name-1) ```ts name: string; ``` Defined in: [lib.es5.d.ts:1074](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1074) ###### Inherited from [Section titled “Inherited from”](#inherited-from-7) [`ApiError`](/api/api-client/src/#apierror).[`name`](/api/api-client/src/#name) ##### stack? [Section titled “stack?”](#stack-1) ```ts optional stack?: string; ``` Defined in: [lib.es5.d.ts:1076](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1076) ###### Inherited from [Section titled “Inherited from”](#inherited-from-8) [`ApiError`](/api/api-client/src/#apierror).[`stack`](/api/api-client/src/#stack) ##### status [Section titled “status”](#status-1) ```ts readonly status: number; ``` Defined in: [src/errors.ts:30](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L30) HTTP status code of the failed request ###### Inherited from [Section titled “Inherited from”](#inherited-from-9) [`ApiError`](/api/api-client/src/#apierror).[`status`](/api/api-client/src/#status) ##### statusText [Section titled “statusText”](#statustext-1) ```ts readonly statusText: string; ``` Defined in: [src/errors.ts:33](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L33) HTTP status text ###### Inherited from [Section titled “Inherited from”](#inherited-from-10) [`ApiError`](/api/api-client/src/#apierror).[`statusText`](/api/api-client/src/#statustext) ##### url [Section titled “url”](#url-1) ```ts readonly url: string; ``` Defined in: [src/errors.ts:39](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L39) Request URL that failed ###### Inherited from [Section titled “Inherited from”](#inherited-from-11) [`ApiError`](/api/api-client/src/#apierror).[`url`](/api/api-client/src/#url) #### Accessors [Section titled “Accessors”](#accessors-1) ##### isClientError [Section titled “isClientError”](#isclienterror-1) ###### Get Signature [Section titled “Get Signature”](#get-signature-3) ```ts get isClientError(): boolean; ``` Defined in: [src/errors.ts:60](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L60) Check if this error is a client error (4xx) ###### Returns [Section titled “Returns”](#returns-5) `boolean` ###### Inherited from [Section titled “Inherited from”](#inherited-from-12) [`ApiError`](/api/api-client/src/#apierror).[`isClientError`](/api/api-client/src/#isclienterror) ##### isRetryable [Section titled “isRetryable”](#isretryable-1) ###### Get Signature [Section titled “Get Signature”](#get-signature-4) ```ts get isRetryable(): boolean; ``` Defined in: [src/errors.ts:75](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L75) Check if this error is retryable Server errors (5xx) and rate limits (429) are retryable ###### Returns [Section titled “Returns”](#returns-6) `boolean` ###### Inherited from [Section titled “Inherited from”](#inherited-from-13) [`ApiError`](/api/api-client/src/#apierror).[`isRetryable`](/api/api-client/src/#isretryable) ##### isServerError [Section titled “isServerError”](#isservererror-1) ###### Get Signature [Section titled “Get Signature”](#get-signature-5) ```ts get isServerError(): boolean; ``` Defined in: [src/errors.ts:67](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L67) Check if this error is a server error (5xx) ###### Returns [Section titled “Returns”](#returns-7) `boolean` ###### Inherited from [Section titled “Inherited from”](#inherited-from-14) [`ApiError`](/api/api-client/src/#apierror).[`isServerError`](/api/api-client/src/#isservererror) *** ### ClientVoiceCache [Section titled “ClientVoiceCache”](#clientvoicecache) Defined in: [src/voice-cache.ts:77](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/voice-cache.ts#L77) Client-side voice cache with multi-environment storage support. #### Constructors [Section titled “Constructors”](#constructors-2) ##### Constructor [Section titled “Constructor”](#constructor-2) ```ts new ClientVoiceCache(config?): ClientVoiceCache; ``` Defined in: [src/voice-cache.ts:88](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/voice-cache.ts#L88) ###### Parameters [Section titled “Parameters”](#parameters-2) | Parameter | Type | | --------- | ----------------------------------------------------------- | | `config` | [`VoiceCacheConfig`](/api/api-client/src/#voicecacheconfig) | ###### Returns [Section titled “Returns”](#returns-8) [`ClientVoiceCache`](/api/api-client/src/#clientvoicecache) #### Properties [Section titled “Properties”](#properties-2) ##### enabled [Section titled “enabled”](#enabled) ```ts readonly enabled: boolean; ``` Defined in: [src/voice-cache.ts:86](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/voice-cache.ts#L86) Whether caching is active; mirrors `VoiceCacheConfig.enabled`. #### Methods [Section titled “Methods”](#methods) ##### clear() [Section titled “clear()”](#clear) ```ts clear(): Promise; ``` Defined in: [src/voice-cache.ts:349](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/voice-cache.ts#L349) Clear the voice cache. ###### Returns [Section titled “Returns”](#returns-9) `Promise`\<`void`> ##### getBrowserVoiceHash() [Section titled “getBrowserVoiceHash()”](#getbrowservoicehash) ```ts getBrowserVoiceHash(): Promise; ``` Defined in: [src/voice-cache.ts:321](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/voice-cache.ts#L321) Get the stored browser voice hash. Stored separately from voice data so it persists across API URL changes. ###### Returns [Section titled “Returns”](#returns-10) `Promise`\<`string` | `null`> ##### getVoices() [Section titled “getVoices()”](#getvoices) ```ts getVoices(): Promise; ``` Defined in: [src/voice-cache.ts:260](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/voice-cache.ts#L260) Get cached voice data. ###### Returns [Section titled “Returns”](#returns-11) `Promise`\<[`CachedVoiceData`](/api/api-client/src/#cachedvoicedata) | `null`> Cached voice data or null if not cached / cache disabled ##### isFresh() [Section titled “isFresh()”](#isfresh) ```ts isFresh(data): boolean; ``` Defined in: [src/voice-cache.ts:284](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/voice-cache.ts#L284) Check whether cached data is still fresh (within TTL). ###### Parameters [Section titled “Parameters”](#parameters-3) | Parameter | Type | | --------- | --------------------------------------------------------- | | `data` | [`CachedVoiceData`](/api/api-client/src/#cachedvoicedata) | ###### Returns [Section titled “Returns”](#returns-12) `boolean` ##### migrateVoiceCache() [Section titled “migrateVoiceCache()”](#migratevoicecache) ```ts migrateVoiceCache(): Promise; ``` Defined in: [src/voice-cache.ts:113](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/voice-cache.ts#L113) Migrate legacy unscoped cache entries to API-key-scoped keys. Should be called once during initialization when apiKey is available. ###### Returns [Section titled “Returns”](#returns-13) `Promise`\<`void`> ##### setBrowserVoiceHash() [Section titled “setBrowserVoiceHash()”](#setbrowservoicehash) ```ts setBrowserVoiceHash(hash): Promise; ``` Defined in: [src/voice-cache.ts:335](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/voice-cache.ts#L335) Store the browser voice hash. ###### Parameters [Section titled “Parameters”](#parameters-4) | Parameter | Type | | --------- | -------- | | `hash` | `string` | ###### Returns [Section titled “Returns”](#returns-14) `Promise`\<`void`> ##### setVoices() [Section titled “setVoices()”](#setvoices) ```ts setVoices( etag, voices, systemVoices): Promise; ``` Defined in: [src/voice-cache.ts:296](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/voice-cache.ts#L296) Store voice data in the cache. ###### Parameters [Section titled “Parameters”](#parameters-5) | Parameter | Type | Description | | -------------- | --------------------------------------- | ----------------------------- | | `etag` | `string` | ETag from the server response | | `voices` | `VoiceData`\[] | Voice collection to cache | | `systemVoices` | `SystemVoiceResponse`\[] \| `undefined` | System voices to cache | ###### Returns [Section titled “Returns”](#returns-15) `Promise`\<`void`> ##### create() [Section titled “create()”](#create) ```ts static create(config): | ClientVoiceCache | NoOpCache; ``` Defined in: [src/voice-cache.ts:364](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/voice-cache.ts#L364) Create a ClientVoiceCache or NoOpCache based on configuration. ###### Parameters [Section titled “Parameters”](#parameters-6) | Parameter | Type | | --------- | ----------------------------------------------------------------------------- | | `config` | \| [`VoiceCacheConfig`](/api/api-client/src/#voicecacheconfig) \| `undefined` | ###### Returns [Section titled “Returns”](#returns-16) \| [`ClientVoiceCache`](/api/api-client/src/#clientvoicecache) | `NoOpCache` *** ### FileStorage [Section titled “FileStorage”](#filestorage) Defined in: [src/file-storage.ts:11](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/file-storage.ts#L11) Node.js-only `CacheStorageAdapter` that persists voice-cache entries to a JSON file under the operating system's temp directory. Loaded lazily via dynamic `import()` of `node:fs`/`node:os`/`node:path` so browser bundlers never encounter `node:` built-ins. All operations are silent-fail: I/O errors (missing modules, permission denied, corrupt file) resolve to `null`/no-op rather than throwing. #### Implements [Section titled “Implements”](#implements) * [`CacheStorageAdapter`](/api/api-client/src/#cachestorageadapter) #### Constructors [Section titled “Constructors”](#constructors-3) ##### Constructor [Section titled “Constructor”](#constructor-3) ```ts new FileStorage(fileId): FileStorage; ``` Defined in: [src/file-storage.ts:26](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/file-storage.ts#L26) ###### Parameters [Section titled “Parameters”](#parameters-7) | Parameter | Type | Description | | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fileId` | `string` | Identifier used to scope the temp file name (`rv-voice-cache-{fileId}.json`). Typically a hash of the API key so concurrent clients with different keys don't share storage. | ###### Returns [Section titled “Returns”](#returns-17) [`FileStorage`](/api/api-client/src/#filestorage) #### Methods [Section titled “Methods”](#methods-1) ##### getItem() [Section titled “getItem()”](#getitem) ```ts getItem(key): Promise; ``` Defined in: [src/file-storage.ts:56](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/file-storage.ts#L56) Read a stored value by key. Returns `null` when the key is absent, the backing file is missing/unreadable, or the runtime is not Node.js. ###### Parameters [Section titled “Parameters”](#parameters-8) | Parameter | Type | | --------- | -------- | | `key` | `string` | ###### Returns [Section titled “Returns”](#returns-18) `Promise`\<`string` | `null`> ###### Implementation of [Section titled “Implementation of”](#implementation-of) [`CacheStorageAdapter`](/api/api-client/src/#cachestorageadapter).[`getItem`](/api/api-client/src/#getitem-2) ##### removeItem() [Section titled “removeItem()”](#removeitem) ```ts removeItem(key): Promise; ``` Defined in: [src/file-storage.ts:97](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/file-storage.ts#L97) Remove a stored value. Deletes the backing file when the last entry is removed. Silently no-ops when the runtime is not Node.js. ###### Parameters [Section titled “Parameters”](#parameters-9) | Parameter | Type | | --------- | -------- | | `key` | `string` | ###### Returns [Section titled “Returns”](#returns-19) `Promise`\<`void`> ###### Implementation of [Section titled “Implementation of”](#implementation-of-1) [`CacheStorageAdapter`](/api/api-client/src/#cachestorageadapter).[`removeItem`](/api/api-client/src/#removeitem-2) ##### setItem() [Section titled “setItem()”](#setitem) ```ts setItem(key, value): Promise; ``` Defined in: [src/file-storage.ts:73](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/file-storage.ts#L73) Persist a value under `key`, merging into any existing JSON payload. Silently no-ops when the runtime is not Node.js or the write fails. ###### Parameters [Section titled “Parameters”](#parameters-10) | Parameter | Type | | --------- | -------- | | `key` | `string` | | `value` | `string` | ###### Returns [Section titled “Returns”](#returns-20) `Promise`\<`void`> ###### Implementation of [Section titled “Implementation of”](#implementation-of-2) [`CacheStorageAdapter`](/api/api-client/src/#cachestorageadapter).[`setItem`](/api/api-client/src/#setitem-2) *** ### MemoryStorage [Section titled “MemoryStorage”](#memorystorage) Defined in: [src/voice-cache.ts:13](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/voice-cache.ts#L13) In-memory storage adapter. Lives for the process/page lifetime. #### Implements [Section titled “Implements”](#implements-1) * [`CacheStorageAdapter`](/api/api-client/src/#cachestorageadapter) #### Constructors [Section titled “Constructors”](#constructors-4) ##### Constructor [Section titled “Constructor”](#constructor-4) ```ts new MemoryStorage(): MemoryStorage; ``` ###### Returns [Section titled “Returns”](#returns-21) [`MemoryStorage`](/api/api-client/src/#memorystorage) #### Methods [Section titled “Methods”](#methods-2) ##### getItem() [Section titled “getItem()”](#getitem-1) ```ts getItem(key): string | null; ``` Defined in: [src/voice-cache.ts:17](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/voice-cache.ts#L17) Retrieve a stored value by key, or `null` if absent. ###### Parameters [Section titled “Parameters”](#parameters-11) | Parameter | Type | | --------- | -------- | | `key` | `string` | ###### Returns [Section titled “Returns”](#returns-22) `string` | `null` ###### Implementation of [Section titled “Implementation of”](#implementation-of-3) [`CacheStorageAdapter`](/api/api-client/src/#cachestorageadapter).[`getItem`](/api/api-client/src/#getitem-2) ##### removeItem() [Section titled “removeItem()”](#removeitem-1) ```ts removeItem(key): void; ``` Defined in: [src/voice-cache.ts:27](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/voice-cache.ts#L27) Remove the value stored under `key`. No-op if absent. ###### Parameters [Section titled “Parameters”](#parameters-12) | Parameter | Type | | --------- | -------- | | `key` | `string` | ###### Returns [Section titled “Returns”](#returns-23) `void` ###### Implementation of [Section titled “Implementation of”](#implementation-of-4) [`CacheStorageAdapter`](/api/api-client/src/#cachestorageadapter).[`removeItem`](/api/api-client/src/#removeitem-2) ##### setItem() [Section titled “setItem()”](#setitem-1) ```ts setItem(key, value): void; ``` Defined in: [src/voice-cache.ts:22](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/voice-cache.ts#L22) Store `value` under `key`, overwriting any existing entry. ###### Parameters [Section titled “Parameters”](#parameters-13) | Parameter | Type | | --------- | -------- | | `key` | `string` | | `value` | `string` | ###### Returns [Section titled “Returns”](#returns-24) `void` ###### Implementation of [Section titled “Implementation of”](#implementation-of-5) [`CacheStorageAdapter`](/api/api-client/src/#cachestorageadapter).[`setItem`](/api/api-client/src/#setitem-2) *** ### NetworkError [Section titled “NetworkError”](#networkerror) Defined in: [src/errors.ts:156](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L156) Error thrown when a network error occurs #### Extends [Section titled “Extends”](#extends-2) * [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror) #### Extended by [Section titled “Extended by”](#extended-by-1) * [`TimeoutError`](/api/api-client/src/#timeouterror) #### Constructors [Section titled “Constructors”](#constructors-5) ##### Constructor [Section titled “Constructor”](#constructor-5) ```ts new NetworkError( message, url, cause?): NetworkError; ``` Defined in: [src/errors.ts:160](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L160) ###### Parameters [Section titled “Parameters”](#parameters-14) | Parameter | Type | | --------- | -------- | | `message` | `string` | | `url` | `string` | | `cause?` | `Error` | ###### Returns [Section titled “Returns”](#returns-25) [`NetworkError`](/api/api-client/src/#networkerror) ###### Overrides [Section titled “Overrides”](#overrides-2) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`constructor`](/api/api-client/src/#constructor-10) #### Properties [Section titled “Properties”](#properties-3) ##### cause? [Section titled “cause?”](#cause-2) ```ts readonly optional cause?: Error; ``` Defined in: [src/errors.ts:11](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L11) Original error that caused this error, if any ###### Inherited from [Section titled “Inherited from”](#inherited-from-15) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`cause`](/api/api-client/src/#cause-6) ##### message [Section titled “message”](#message-2) ```ts message: string; ``` Defined in: [lib.es5.d.ts:1075](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1075) ###### Inherited from [Section titled “Inherited from”](#inherited-from-16) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`message`](/api/api-client/src/#message-6) ##### name [Section titled “name”](#name-2) ```ts name: string; ``` Defined in: [lib.es5.d.ts:1074](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1074) ###### Inherited from [Section titled “Inherited from”](#inherited-from-17) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`name`](/api/api-client/src/#name-6) ##### stack? [Section titled “stack?”](#stack-2) ```ts optional stack?: string; ``` Defined in: [lib.es5.d.ts:1076](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1076) ###### Inherited from [Section titled “Inherited from”](#inherited-from-18) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`stack`](/api/api-client/src/#stack-6) ##### url [Section titled “url”](#url-2) ```ts readonly url: string; ``` Defined in: [src/errors.ts:158](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L158) Request URL that failed #### Accessors [Section titled “Accessors”](#accessors-2) ##### isRetryable [Section titled “isRetryable”](#isretryable-2) ###### Get Signature [Section titled “Get Signature”](#get-signature-6) ```ts get isRetryable(): boolean; ``` Defined in: [src/errors.ts:169](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L169) Network errors are always retryable ###### Returns [Section titled “Returns”](#returns-26) `boolean` *** ### NotFoundError [Section titled “NotFoundError”](#notfounderror) Defined in: [src/errors.ts:93](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L93) Error thrown when a resource is not found (404) #### Extends [Section titled “Extends”](#extends-3) * [`ApiError`](/api/api-client/src/#apierror) #### Constructors [Section titled “Constructors”](#constructors-6) ##### Constructor [Section titled “Constructor”](#constructor-6) ```ts new NotFoundError( message, resource, status, statusText, url, body?): NotFoundError; ``` Defined in: [src/errors.ts:97](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L97) ###### Parameters [Section titled “Parameters”](#parameters-15) | Parameter | Type | | ------------ | --------- | | `message` | `string` | | `resource` | `string` | | `status` | `number` | | `statusText` | `string` | | `url` | `string` | | `body?` | `unknown` | ###### Returns [Section titled “Returns”](#returns-27) [`NotFoundError`](/api/api-client/src/#notfounderror) ###### Overrides [Section titled “Overrides”](#overrides-3) [`ApiError`](/api/api-client/src/#apierror).[`constructor`](/api/api-client/src/#constructor) #### Properties [Section titled “Properties”](#properties-4) ##### body? [Section titled “body?”](#body-2) ```ts readonly optional body?: unknown; ``` Defined in: [src/errors.ts:36](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L36) Response body, if available ###### Inherited from [Section titled “Inherited from”](#inherited-from-19) [`ApiError`](/api/api-client/src/#apierror).[`body`](/api/api-client/src/#body) ##### cause? [Section titled “cause?”](#cause-3) ```ts readonly optional cause?: Error; ``` Defined in: [src/errors.ts:11](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L11) Original error that caused this error, if any ###### Inherited from [Section titled “Inherited from”](#inherited-from-20) [`ApiError`](/api/api-client/src/#apierror).[`cause`](/api/api-client/src/#cause) ##### message [Section titled “message”](#message-3) ```ts message: string; ``` Defined in: [lib.es5.d.ts:1075](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1075) ###### Inherited from [Section titled “Inherited from”](#inherited-from-21) [`ApiError`](/api/api-client/src/#apierror).[`message`](/api/api-client/src/#message) ##### name [Section titled “name”](#name-3) ```ts name: string; ``` Defined in: [lib.es5.d.ts:1074](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1074) ###### Inherited from [Section titled “Inherited from”](#inherited-from-22) [`ApiError`](/api/api-client/src/#apierror).[`name`](/api/api-client/src/#name) ##### resource [Section titled “resource”](#resource) ```ts readonly resource: string; ``` Defined in: [src/errors.ts:95](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L95) The resource that was not found ##### stack? [Section titled “stack?”](#stack-3) ```ts optional stack?: string; ``` Defined in: [lib.es5.d.ts:1076](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1076) ###### Inherited from [Section titled “Inherited from”](#inherited-from-23) [`ApiError`](/api/api-client/src/#apierror).[`stack`](/api/api-client/src/#stack) ##### status [Section titled “status”](#status-2) ```ts readonly status: number; ``` Defined in: [src/errors.ts:30](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L30) HTTP status code of the failed request ###### Inherited from [Section titled “Inherited from”](#inherited-from-24) [`ApiError`](/api/api-client/src/#apierror).[`status`](/api/api-client/src/#status) ##### statusText [Section titled “statusText”](#statustext-2) ```ts readonly statusText: string; ``` Defined in: [src/errors.ts:33](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L33) HTTP status text ###### Inherited from [Section titled “Inherited from”](#inherited-from-25) [`ApiError`](/api/api-client/src/#apierror).[`statusText`](/api/api-client/src/#statustext) ##### url [Section titled “url”](#url-3) ```ts readonly url: string; ``` Defined in: [src/errors.ts:39](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L39) Request URL that failed ###### Inherited from [Section titled “Inherited from”](#inherited-from-26) [`ApiError`](/api/api-client/src/#apierror).[`url`](/api/api-client/src/#url) #### Accessors [Section titled “Accessors”](#accessors-3) ##### isClientError [Section titled “isClientError”](#isclienterror-2) ###### Get Signature [Section titled “Get Signature”](#get-signature-7) ```ts get isClientError(): boolean; ``` Defined in: [src/errors.ts:60](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L60) Check if this error is a client error (4xx) ###### Returns [Section titled “Returns”](#returns-28) `boolean` ###### Inherited from [Section titled “Inherited from”](#inherited-from-27) [`ApiError`](/api/api-client/src/#apierror).[`isClientError`](/api/api-client/src/#isclienterror) ##### isRetryable [Section titled “isRetryable”](#isretryable-3) ###### Get Signature [Section titled “Get Signature”](#get-signature-8) ```ts get isRetryable(): boolean; ``` Defined in: [src/errors.ts:75](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L75) Check if this error is retryable Server errors (5xx) and rate limits (429) are retryable ###### Returns [Section titled “Returns”](#returns-29) `boolean` ###### Inherited from [Section titled “Inherited from”](#inherited-from-28) [`ApiError`](/api/api-client/src/#apierror).[`isRetryable`](/api/api-client/src/#isretryable) ##### isServerError [Section titled “isServerError”](#isservererror-2) ###### Get Signature [Section titled “Get Signature”](#get-signature-9) ```ts get isServerError(): boolean; ``` Defined in: [src/errors.ts:67](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L67) Check if this error is a server error (5xx) ###### Returns [Section titled “Returns”](#returns-30) `boolean` ###### Inherited from [Section titled “Inherited from”](#inherited-from-29) [`ApiError`](/api/api-client/src/#apierror).[`isServerError`](/api/api-client/src/#isservererror) *** ### RateLimitError [Section titled “RateLimitError”](#ratelimiterror) Defined in: [src/errors.ts:114](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L114) Error thrown when rate limited (429) #### Extends [Section titled “Extends”](#extends-4) * [`ApiError`](/api/api-client/src/#apierror) #### Constructors [Section titled “Constructors”](#constructors-7) ##### Constructor [Section titled “Constructor”](#constructor-7) ```ts new RateLimitError( message, status, statusText, url, retryAfter?, body?): RateLimitError; ``` Defined in: [src/errors.ts:118](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L118) ###### Parameters [Section titled “Parameters”](#parameters-16) | Parameter | Type | | ------------- | --------- | | `message` | `string` | | `status` | `number` | | `statusText` | `string` | | `url` | `string` | | `retryAfter?` | `number` | | `body?` | `unknown` | ###### Returns [Section titled “Returns”](#returns-31) [`RateLimitError`](/api/api-client/src/#ratelimiterror) ###### Overrides [Section titled “Overrides”](#overrides-4) [`ApiError`](/api/api-client/src/#apierror).[`constructor`](/api/api-client/src/#constructor) #### Properties [Section titled “Properties”](#properties-5) ##### body? [Section titled “body?”](#body-3) ```ts readonly optional body?: unknown; ``` Defined in: [src/errors.ts:36](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L36) Response body, if available ###### Inherited from [Section titled “Inherited from”](#inherited-from-30) [`ApiError`](/api/api-client/src/#apierror).[`body`](/api/api-client/src/#body) ##### cause? [Section titled “cause?”](#cause-4) ```ts readonly optional cause?: Error; ``` Defined in: [src/errors.ts:11](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L11) Original error that caused this error, if any ###### Inherited from [Section titled “Inherited from”](#inherited-from-31) [`ApiError`](/api/api-client/src/#apierror).[`cause`](/api/api-client/src/#cause) ##### message [Section titled “message”](#message-4) ```ts message: string; ``` Defined in: [lib.es5.d.ts:1075](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1075) ###### Inherited from [Section titled “Inherited from”](#inherited-from-32) [`ApiError`](/api/api-client/src/#apierror).[`message`](/api/api-client/src/#message) ##### name [Section titled “name”](#name-4) ```ts name: string; ``` Defined in: [lib.es5.d.ts:1074](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1074) ###### Inherited from [Section titled “Inherited from”](#inherited-from-33) [`ApiError`](/api/api-client/src/#apierror).[`name`](/api/api-client/src/#name) ##### retryAfter? [Section titled “retryAfter?”](#retryafter) ```ts readonly optional retryAfter?: number; ``` Defined in: [src/errors.ts:116](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L116) Time in seconds to wait before retrying, if provided by the API ##### stack? [Section titled “stack?”](#stack-4) ```ts optional stack?: string; ``` Defined in: [lib.es5.d.ts:1076](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1076) ###### Inherited from [Section titled “Inherited from”](#inherited-from-34) [`ApiError`](/api/api-client/src/#apierror).[`stack`](/api/api-client/src/#stack) ##### status [Section titled “status”](#status-3) ```ts readonly status: number; ``` Defined in: [src/errors.ts:30](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L30) HTTP status code of the failed request ###### Inherited from [Section titled “Inherited from”](#inherited-from-35) [`ApiError`](/api/api-client/src/#apierror).[`status`](/api/api-client/src/#status) ##### statusText [Section titled “statusText”](#statustext-3) ```ts readonly statusText: string; ``` Defined in: [src/errors.ts:33](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L33) HTTP status text ###### Inherited from [Section titled “Inherited from”](#inherited-from-36) [`ApiError`](/api/api-client/src/#apierror).[`statusText`](/api/api-client/src/#statustext) ##### url [Section titled “url”](#url-4) ```ts readonly url: string; ``` Defined in: [src/errors.ts:39](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L39) Request URL that failed ###### Inherited from [Section titled “Inherited from”](#inherited-from-37) [`ApiError`](/api/api-client/src/#apierror).[`url`](/api/api-client/src/#url) #### Accessors [Section titled “Accessors”](#accessors-4) ##### isClientError [Section titled “isClientError”](#isclienterror-3) ###### Get Signature [Section titled “Get Signature”](#get-signature-10) ```ts get isClientError(): boolean; ``` Defined in: [src/errors.ts:60](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L60) Check if this error is a client error (4xx) ###### Returns [Section titled “Returns”](#returns-32) `boolean` ###### Inherited from [Section titled “Inherited from”](#inherited-from-38) [`ApiError`](/api/api-client/src/#apierror).[`isClientError`](/api/api-client/src/#isclienterror) ##### isRetryable [Section titled “isRetryable”](#isretryable-4) ###### Get Signature [Section titled “Get Signature”](#get-signature-11) ```ts get isRetryable(): boolean; ``` Defined in: [src/errors.ts:75](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L75) Check if this error is retryable Server errors (5xx) and rate limits (429) are retryable ###### Returns [Section titled “Returns”](#returns-33) `boolean` ###### Inherited from [Section titled “Inherited from”](#inherited-from-39) [`ApiError`](/api/api-client/src/#apierror).[`isRetryable`](/api/api-client/src/#isretryable) ##### isServerError [Section titled “isServerError”](#isservererror-3) ###### Get Signature [Section titled “Get Signature”](#get-signature-12) ```ts get isServerError(): boolean; ``` Defined in: [src/errors.ts:67](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L67) Check if this error is a server error (5xx) ###### Returns [Section titled “Returns”](#returns-34) `boolean` ###### Inherited from [Section titled “Inherited from”](#inherited-from-40) [`ApiError`](/api/api-client/src/#apierror).[`isServerError`](/api/api-client/src/#isservererror) *** ### ResponseValidationError [Section titled “ResponseValidationError”](#responsevalidationerror) Defined in: [src/errors.ts:210](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L210) Error thrown when API response validation fails This is for client-side validation of response data against expected schemas #### Extends [Section titled “Extends”](#extends-5) * [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror) #### Constructors [Section titled “Constructors”](#constructors-8) ##### Constructor [Section titled “Constructor”](#constructor-8) ```ts new ResponseValidationError( message, issues, data): ResponseValidationError; ``` Defined in: [src/errors.ts:217](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L217) ###### Parameters [Section titled “Parameters”](#parameters-17) | Parameter | Type | | --------- | --------------------------------------------- | | `message` | `string` | | `issues` | { `message`: `string`; `path`: `string`; }\[] | | `data` | `unknown` | ###### Returns [Section titled “Returns”](#returns-35) [`ResponseValidationError`](/api/api-client/src/#responsevalidationerror) ###### Overrides [Section titled “Overrides”](#overrides-5) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`constructor`](/api/api-client/src/#constructor-10) #### Properties [Section titled “Properties”](#properties-6) ##### cause? [Section titled “cause?”](#cause-5) ```ts readonly optional cause?: Error; ``` Defined in: [src/errors.ts:11](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L11) Original error that caused this error, if any ###### Inherited from [Section titled “Inherited from”](#inherited-from-41) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`cause`](/api/api-client/src/#cause-6) ##### data [Section titled “data”](#data) ```ts readonly data: unknown; ``` Defined in: [src/errors.ts:215](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L215) The raw response data that failed validation ##### issues [Section titled “issues”](#issues) ```ts readonly issues: { message: string; path: string; }[]; ``` Defined in: [src/errors.ts:212](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L212) Detailed validation issues from Zod ###### message [Section titled “message”](#message-5) ```ts message: string; ``` ###### path [Section titled “path”](#path) ```ts path: string; ``` ##### message [Section titled “message”](#message-6) ```ts message: string; ``` Defined in: [lib.es5.d.ts:1075](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1075) ###### Inherited from [Section titled “Inherited from”](#inherited-from-42) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`message`](/api/api-client/src/#message-6) ##### name [Section titled “name”](#name-5) ```ts name: string; ``` Defined in: [lib.es5.d.ts:1074](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1074) ###### Inherited from [Section titled “Inherited from”](#inherited-from-43) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`name`](/api/api-client/src/#name-6) ##### stack? [Section titled “stack?”](#stack-5) ```ts optional stack?: string; ``` Defined in: [lib.es5.d.ts:1076](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1076) ###### Inherited from [Section titled “Inherited from”](#inherited-from-44) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`stack`](/api/api-client/src/#stack-6) #### Accessors [Section titled “Accessors”](#accessors-5) ##### formattedIssues [Section titled “formattedIssues”](#formattedissues) ###### Get Signature [Section titled “Get Signature”](#get-signature-13) ```ts get formattedIssues(): string; ``` Defined in: [src/errors.ts:227](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L227) Get a formatted string of all validation issues ###### Returns [Section titled “Returns”](#returns-36) `string` *** ### ResponsiveVoiceAPIClient [Section titled “ResponsiveVoiceAPIClient”](#responsivevoiceapiclient) Defined in: [src/client.ts:93](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L93) ResponsiveVoice API Client Provides methods to interact with the ResponsiveVoice TTS API: * Synthesize text to speech * List available voices * Get specific voice information #### Example [Section titled “Example”](#example) ```typescript const client = new ResponsiveVoiceAPIClient({ apiKey: 'your-api-key' }); // Synthesize text const audio = await client.synthesize({ text: 'Hello, world!', lang: 'en-US', }); // Play the audio const audioElement = new Audio(audio.url); audioElement.play(); ``` #### Constructors [Section titled “Constructors”](#constructors-9) ##### Constructor [Section titled “Constructor”](#constructor-9) ```ts new ResponsiveVoiceAPIClient(config): ResponsiveVoiceAPIClient; ``` Defined in: [src/client.ts:112](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L112) Create a new ResponsiveVoice API client ###### Parameters [Section titled “Parameters”](#parameters-18) | Parameter | Type | Description | | --------- | --------------------------------------------------------------------------------------- | -------------------- | | `config` | [`ResponsiveVoiceAPIClientConfig`](/api/api-client/src/#responsivevoiceapiclientconfig) | Client configuration | ###### Returns [Section titled “Returns”](#returns-37) [`ResponsiveVoiceAPIClient`](/api/api-client/src/#responsivevoiceapiclient) ###### Throws [Section titled “Throws”](#throws) Error if apiKey is not provided #### Accessors [Section titled “Accessors”](#accessors-6) ##### baseUrl [Section titled “baseUrl”](#baseurl) ###### Get Signature [Section titled “Get Signature”](#get-signature-14) ```ts get baseUrl(): string; ``` Defined in: [src/client.ts:169](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L169) Get the current base URL ###### Returns [Section titled “Returns”](#returns-38) `string` #### Methods [Section titled “Methods”](#methods-3) ##### clearVoiceCache() [Section titled “clearVoiceCache()”](#clearvoicecache) ```ts clearVoiceCache(): Promise; ``` Defined in: [src/client.ts:456](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L456) Clear the client-side voice cache ###### Returns [Section titled “Returns”](#returns-39) `Promise`\<`void`> ##### getBrowserVoiceHash() [Section titled “getBrowserVoiceHash()”](#getbrowservoicehash-1) ```ts getBrowserVoiceHash(): Promise; ``` Defined in: [src/client.ts:471](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L471) Get the stored browser voice hash. Used by `core` to check if browser voices changed since last report. ###### Returns [Section titled “Returns”](#returns-40) `Promise`\<`string` | `null`> ##### getCachedVoiceData() [Section titled “getCachedVoiceData()”](#getcachedvoicedata) ```ts getCachedVoiceData(): Promise; ``` Defined in: [src/client.ts:463](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L463) Get the raw cached voice data. ###### Returns [Section titled “Returns”](#returns-41) `Promise`\<[`CachedVoiceData`](/api/api-client/src/#cachedvoicedata) | `null`> ##### getConfig() [Section titled “getConfig()”](#getconfig) ```ts getConfig(requestOptions?): Promise<{ analytics: { enabled: boolean; }; auth?: { exp: number; token: string; }; features: { accessibilityNavigation: { enabled: boolean; }; exitIntent: { enabled: boolean; text: string | null; }; paragraphNavigation: { enabled: boolean; }; speakEndPage: { enabled: boolean; text: string | null; }; speakInactivity: { enabled: boolean; text: string | null; }; speakLinks: { enabled: boolean; }; speakSelectedText: { enabled: boolean; }; webPlayer: { controls: { brand: boolean; progress: boolean; skip: boolean; speed: boolean; time: boolean; }; enabled: boolean; layout: { display: "inline" | "block"; mode: "fill" | "shrink"; }; miniPlayer: { animation: "none" | "fade" | "slide" | "pop"; enabled: boolean; position: | "top-left" | "top-right" | "bottom-left" | "bottom-right" | { bottom?: string; left?: string; right?: string; top?: string; }; }; navigation: { paragraphClick: boolean; paragraphHighlight: boolean; }; paragraphSelector: string; pitch?: number; position: | "inline" | "before" | "after" | { at: "before" | "after" | "inside"; target: string; }; rate?: number; sanitize: { enabled: boolean; exclude: string[]; }; selector: string; theme: | "neutral" | "responsivevoice" | { accent?: string; accentSoft?: string; bg?: string; border?: string; fg?: string; fill?: string; hover?: string; muted?: string; track?: string; }; voice?: | string | { flags?: string; regex: string; } | { gender?: "male" | "female" | "f" | "m"; isByok?: boolean; lang?: string; name?: string; provider?: string; }; volume?: number; }; welcomeMessage: { enabled: boolean; text: string | null; }; welcomeMessageOnce: boolean; }; voice: { name: string; pitch: number; rate: number; volume: number; }; }>; ``` Defined in: [src/client.ts:707](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L707) Fetch the per-website configuration (features, voice profile, analytics). Returns a typed `WebsiteConfigResponse` validated against the Zod schema. ###### Parameters [Section titled “Parameters”](#parameters-19) | Parameter | Type | | ----------------- | ------------------------------------------------------- | | `requestOptions?` | [`RequestOptions`](/api/api-client/src/#requestoptions) | ###### Returns [Section titled “Returns”](#returns-42) `Promise`\<{ `analytics`: { `enabled`: `boolean`; }; `auth?`: { `exp`: `number`; `token`: `string`; }; `features`: { `accessibilityNavigation`: { `enabled`: `boolean`; }; `exitIntent`: { `enabled`: `boolean`; `text`: `string` | `null`; }; `paragraphNavigation`: { `enabled`: `boolean`; }; `speakEndPage`: { `enabled`: `boolean`; `text`: `string` | `null`; }; `speakInactivity`: { `enabled`: `boolean`; `text`: `string` | `null`; }; `speakLinks`: { `enabled`: `boolean`; }; `speakSelectedText`: { `enabled`: `boolean`; }; `webPlayer`: { `controls`: { `brand`: `boolean`; `progress`: `boolean`; `skip`: `boolean`; `speed`: `boolean`; `time`: `boolean`; }; `enabled`: `boolean`; `layout`: { `display`: `"inline"` | `"block"`; `mode`: `"fill"` | `"shrink"`; }; `miniPlayer`: { `animation`: `"none"` | `"fade"` | `"slide"` | `"pop"`; `enabled`: `boolean`; `position`: | `"top-left"` | `"top-right"` | `"bottom-left"` | `"bottom-right"` | { `bottom?`: `string`; `left?`: `string`; `right?`: `string`; `top?`: `string`; }; }; `navigation`: { `paragraphClick`: `boolean`; `paragraphHighlight`: `boolean`; }; `paragraphSelector`: `string`; `pitch?`: `number`; `position`: | `"inline"` | `"before"` | `"after"` | { `at`: `"before"` | `"after"` | `"inside"`; `target`: `string`; }; `rate?`: `number`; `sanitize`: { `enabled`: `boolean`; `exclude`: `string`\[]; }; `selector`: `string`; `theme`: | `"neutral"` | `"responsivevoice"` | { `accent?`: `string`; `accentSoft?`: `string`; `bg?`: `string`; `border?`: `string`; `fg?`: `string`; `fill?`: `string`; `hover?`: `string`; `muted?`: `string`; `track?`: `string`; }; `voice?`: | `string` | { `flags?`: `string`; `regex`: `string`; } | { `gender?`: `"male"` | `"female"` | `"f"` | `"m"`; `isByok?`: `boolean`; `lang?`: `string`; `name?`: `string`; `provider?`: `string`; }; `volume?`: `number`; }; `welcomeMessage`: { `enabled`: `boolean`; `text`: `string` | `null`; }; `welcomeMessageOnce`: `boolean`; }; `voice`: { `name`: `string`; `pitch`: `number`; `rate`: `number`; `volume`: `number`; }; }> ##### getVoice() [Section titled “getVoice()”](#getvoice) ```ts getVoice(name, requestOptions?): Promise<{ deprecated?: boolean; fallbackVoice?: boolean; gender?: string; id: number; lang?: string; name: string; pitch?: number; rate?: number; service?: "g1" | "g2" | "g3" | "g5" | "gwn" | "msv" | "oai"; timerSpeed?: number; voiceName?: string; volume?: number; }>; ``` Defined in: [src/client.ts:490](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L490) Get a specific voice by name Retrieves detailed information about a specific system voice. ###### Parameters [Section titled “Parameters”](#parameters-20) | Parameter | Type | Description | | ----------------- | ------------------------------------------------------- | ------------------------------ | | `name` | `string` | The voice name to look up | | `requestOptions?` | [`RequestOptions`](/api/api-client/src/#requestoptions) | Optional request configuration | ###### Returns [Section titled “Returns”](#returns-43) `Promise`\<{ `deprecated?`: `boolean`; `fallbackVoice?`: `boolean`; `gender?`: `string`; `id`: `number`; `lang?`: `string`; `name`: `string`; `pitch?`: `number`; `rate?`: `number`; `service?`: `"g1"` | `"g2"` | `"g3"` | `"g5"` | `"gwn"` | `"msv"` | `"oai"`; `timerSpeed?`: `number`; `voiceName?`: `string`; `volume?`: `number`; }> Promise resolving to SystemVoice object ###### Example [Section titled “Example”](#example-1) ```typescript const voice = await client.getVoice('UK English Female'); console.log(`Voice service: ${voice.service}`); ``` ##### getVoices() [Section titled “getVoices()”](#getvoices-1) ```ts getVoices(filters?, requestOptions?): Promise<{ systemVoices: { deprecated?: boolean; fallbackVoice?: boolean; gender?: string; id: number; lang?: string; name: string; pitch?: number; rate?: number; service?: "g1" | "g2" | "g3" | "g5" | "gwn" | "msv" | "oai"; timerSpeed?: number; voiceName?: string; volume?: number; }[]; voices: { deprecated?: boolean; flag: string; gender: "f" | "m"; isByok?: boolean; lang: string; name: string; provider?: string; voiceIDs: number[]; }[]; }>; ``` Defined in: [src/client.ts:402](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L402) Retrieves the list of available voices, optionally filtered by language or gender. Without filters, results are served from the client-side cache when fresh; filtered queries always hit the network. ###### Parameters [Section titled “Parameters”](#parameters-21) | Parameter | Type | Description | | ----------------- | ------------------------------------------------------- | ---------------------------------- | | `filters?` | [`VoiceFilters`](/api/api-client/src/#voicefilters) | Optional filters to apply | | `requestOptions?` | [`RequestOptions`](/api/api-client/src/#requestoptions) | Optional per-request configuration | ###### Returns [Section titled “Returns”](#returns-44) `Promise`\<{ `systemVoices`: { `deprecated?`: `boolean`; `fallbackVoice?`: `boolean`; `gender?`: `string`; `id`: `number`; `lang?`: `string`; `name`: `string`; `pitch?`: `number`; `rate?`: `number`; `service?`: `"g1"` | `"g2"` | `"g3"` | `"g5"` | `"gwn"` | `"msv"` | `"oai"`; `timerSpeed?`: `number`; `voiceName?`: `string`; `volume?`: `number`; }\[]; `voices`: { `deprecated?`: `boolean`; `flag`: `string`; `gender`: `"f"` | `"m"`; `isByok?`: `boolean`; `lang`: `string`; `name`: `string`; `provider?`: `string`; `voiceIDs`: `number`\[]; }\[]; }> Both the user-facing `voices` array and the personalized `systemVoices` array (see `SystemVoice` from `@responsivevoice/types`) ###### Example [Section titled “Example”](#example-2) ```typescript // Get all voices const { voices } = await client.getVoices(); // Get female voices const { voices: female } = await client.getVoices({ gender: 'female' }); // Get Spanish voices const { voices: spanish } = await client.getVoices({ lang: 'es' }); ``` ##### getVoicesByLanguage() [Section titled “getVoicesByLanguage()”](#getvoicesbylanguage) ```ts getVoicesByLanguage(lang, requestOptions?): Promise<{ deprecated?: boolean; flag: string; gender: "f" | "m"; isByok?: boolean; lang: string; name: string; provider?: string; voiceIDs: number[]; }[]>; ``` Defined in: [src/client.ts:532](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L532) Get voices for a specific language Retrieves all voices available for the specified language code. ###### Parameters [Section titled “Parameters”](#parameters-22) | Parameter | Type | Description | | ----------------- | ------------------------------------------------------- | --------------------------------------------------- | | `lang` | `string` | BCP-47 language code (e.g., 'en-US', 'es', 'fr-FR') | | `requestOptions?` | [`RequestOptions`](/api/api-client/src/#requestoptions) | Optional request configuration | ###### Returns [Section titled “Returns”](#returns-45) `Promise`\<{ `deprecated?`: `boolean`; `flag`: `string`; `gender`: `"f"` | `"m"`; `isByok?`: `boolean`; `lang`: `string`; `name`: `string`; `provider?`: `string`; `voiceIDs`: `number`\[]; }\[]> Promise resolving to array of Voice objects ###### Example [Section titled “Example”](#example-3) ```typescript const germanVoices = await client.getVoicesByLanguage('de-DE'); const frenchVoices = await client.getVoicesByLanguage('fr'); ``` ##### refreshAuth() [Section titled “refreshAuth()”](#refreshauth) ```ts refreshAuth(requestOptions?): Promise<{ exp: number; token: string; }>; ``` Defined in: [src/client.ts:645](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L645) Re-run the v2 browser handshake and mint a fresh `AuthToken`. Called by `core` when its current handshake token nears expiry or after a 401 from a previously-valid token. Origin verification uses the same headers as `/v2/config`. ###### Parameters [Section titled “Parameters”](#parameters-23) | Parameter | Type | | ----------------- | ------------------------------------------------------- | | `requestOptions?` | [`RequestOptions`](/api/api-client/src/#requestoptions) | ###### Returns [Section titled “Returns”](#returns-46) `Promise`\<{ `exp`: `number`; `token`: `string`; }> ##### reportVoices() [Section titled “reportVoices()”](#reportvoices) ```ts reportVoices(report, requestOptions?): Promise<{ count: number; systemVoices: { deprecated?: boolean; fallbackVoice?: boolean; gender?: string; id: number; lang?: string; name: string; pitch?: number; rate?: number; service?: "g1" | "g2" | "g3" | "g5" | "gwn" | "msv" | "oai"; timerSpeed?: number; voiceName?: string; volume?: number; }[]; voices: { deprecated?: boolean; flag: string; gender: "f" | "m"; isByok?: boolean; lang: string; name: string; provider?: string; voiceIDs: number[]; }[]; }>; ``` Defined in: [src/client.ts:594](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L594) Report browser voices and receive a personalized voice collection Sends information about available browser voices to the server, which returns an optimized voice collection for the user's browser/OS combination and subscription tier. ###### Parameters [Section titled “Parameters”](#parameters-24) | Parameter | Type | Description | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | `report` | { `platform`: { `browser`: `string`; `browserVersion`: `string`; `deviceType?`: `"desktop"` \| `"mobile"` \| `"tablet"`; `os`: `string`; `osVersion`: `string`; }; `sdkVersion?`: `string`; `timestamp`: `string`; `voices`: { `default?`: `boolean`; `lang`: `string`; `localService`: `boolean`; `name`: `string`; `voiceURI`: `string`; }\[]; } | Voice report containing platform info and browser voices | | `report.platform` | { `browser`: `string`; `browserVersion`: `string`; `deviceType?`: `"desktop"` \| `"mobile"` \| `"tablet"`; `os`: `string`; `osVersion`: `string`; } | Platform information | | `report.platform.browser?` | `string` | Browser name (e.g., "Chrome", "Safari", "Firefox") | | `report.platform.browserVersion?` | `string` | Browser version (e.g., "120.0.6099.109") | | `report.platform.deviceType?` | `"desktop"` \| `"mobile"` \| `"tablet"` | Device type hint | | `report.platform.os?` | `string` | OS name (e.g., "Windows", "macOS", "iOS", "Android") | | `report.platform.osVersion?` | `string` | OS version (e.g., "14.2", "11", "10") | | `report.sdkVersion?` | `string` | Client SDK version | | `report.timestamp?` | `string` | Client timestamp (ISO 8601) | | `report.voices?` | { `default?`: `boolean`; `lang`: `string`; `localService`: `boolean`; `name`: `string`; `voiceURI`: `string`; }\[] | List of available browser voices | | `requestOptions?` | [`RequestOptions`](/api/api-client/src/#requestoptions) & { `browserVoiceHash?`: `string`; } | Optional request configuration | ###### Returns [Section titled “Returns”](#returns-47) `Promise`\<{ `count`: `number`; `systemVoices`: { `deprecated?`: `boolean`; `fallbackVoice?`: `boolean`; `gender?`: `string`; `id`: `number`; `lang?`: `string`; `name`: `string`; `pitch?`: `number`; `rate?`: `number`; `service?`: `"g1"` | `"g2"` | `"g3"` | `"g5"` | `"gwn"` | `"msv"` | `"oai"`; `timerSpeed?`: `number`; `voiceName?`: `string`; `volume?`: `number`; }\[]; `voices`: { `deprecated?`: `boolean`; `flag`: `string`; `gender`: `"f"` | `"m"`; `isByok?`: `boolean`; `lang`: `string`; `name`: `string`; `provider?`: `string`; `voiceIDs`: `number`\[]; }\[]; }> Personalized voice collection with count ###### Example [Section titled “Example”](#example-4) ```typescript const report = { platform: { browser: 'Chrome', browserVersion: '120.0.0', os: 'Windows', osVersion: '11', }, voices: speechSynthesis.getVoices().map(v => ({ name: v.name, lang: v.lang, localService: v.localService, voiceURI: v.voiceURI, default: v.default, })), timestamp: new Date().toISOString(), }; const response = await client.reportVoices(report); console.log(`Received ${response.count} personalized voices`); ``` ##### synthesize() [Section titled “synthesize()”](#synthesize) ```ts synthesize(options, requestOptions?): Promise<{ blob: Blob; duration?: number; format: "mp3" | "ogg" | "wav"; prosodyApplied: ("pitch" | "rate" | "volume")[]; url: string; }>; ``` Defined in: [src/client.ts:194](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L194) Synthesize text to speech Converts text to audio using the specified voice and parameters. Returns an AudioResponse with a Blob and URL that can be used for playback. ###### Parameters [Section titled “Parameters”](#parameters-25) | Parameter | Type | Description | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `options` | { `engine?`: `"g1"` \| `"g2"` \| `"g3"` \| `"g5"` \| `"gwn"` \| `"msv"` \| `"oai"`; `format?`: `"mp3"` \| `"ogg"` \| `"wav"`; `gender?`: `"male"` \| `"female"`; `lang?`: `string`; `name?`: `string`; `pitch?`: `number`; `rate?`: `number`; `text`: `string`; `voice?`: `string`; `volume?`: `number`; } | Synthesis options including text, language, and voice parameters | | `options.engine?` | `"g1"` \| `"g2"` \| `"g3"` \| `"g5"` \| `"gwn"` \| `"msv"` \| `"oai"` | TTS service engine to use | | `options.format?` | `"mp3"` \| `"ogg"` \| `"wav"` | Audio output format | | `options.gender?` | `"male"` \| `"female"` | Voice gender preference | | `options.lang?` | `string` | BCP-47 language code (e.g., "en-US"). Required unless voice is provided. | | `options.name?` | `string` | System voice name | | `options.pitch?` | `number` | Voice pitch (0–2, default 1 = normal). Providers may normalize to their own scale. | | `options.rate?` | `number` | Speech rate (0–2, default 1 = normal). Providers may normalize to their own scale. | | `options.text?` | `string` | Text to synthesize (max 4000 characters) | | `options.voice?` | `string` | ResponsiveVoice name (e.g., "UK English Male"). Resolved server-side to engine + lang. | | `options.volume?` | `number` | Volume (0–1, default 1 = full). | | `requestOptions?` | [`RequestOptions`](/api/api-client/src/#requestoptions) | Optional request configuration | ###### Returns [Section titled “Returns”](#returns-48) `Promise`\<{ `blob`: `Blob`; `duration?`: `number`; `format`: `"mp3"` | `"ogg"` | `"wav"`; `prosodyApplied`: (`"pitch"` | `"rate"` | `"volume"`)\[]; `url`: `string`; }> Promise resolving to AudioResponse with audio blob and URL ###### Example [Section titled “Example”](#example-5) ```typescript const audio = await client.synthesize({ text: 'Hello, world!', voice: 'US English Female', }); console.log(`Audio format: ${audio.format}`); console.log(`Audio URL: ${audio.url}`); ``` ##### synthesizeStream() [Section titled “synthesizeStream()”](#synthesizestream) ```ts synthesizeStream(options, requestOptions?): AsyncGenerator; ``` Defined in: [src/client.ts:250](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L250) Synthesize text to speech with HTTP streaming. Returns an AsyncGenerator that yields StreamChunk objects as audio data arrives from the server. The server streams audio incrementally as it is synthesized (HTTP audio streaming), reducing time-to-first-byte. ###### Parameters [Section titled “Parameters”](#parameters-26) | Parameter | Type | Description | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `options` | { `engine?`: `"g1"` \| `"g2"` \| `"g3"` \| `"g5"` \| `"gwn"` \| `"msv"` \| `"oai"`; `format?`: `"mp3"` \| `"ogg"` \| `"wav"`; `gender?`: `"male"` \| `"female"`; `lang?`: `string`; `name?`: `string`; `pitch?`: `number`; `rate?`: `number`; `text`: `string`; `voice?`: `string`; `volume?`: `number`; } | Synthesis options (same as synthesize()) | | `options.engine?` | `"g1"` \| `"g2"` \| `"g3"` \| `"g5"` \| `"gwn"` \| `"msv"` \| `"oai"` | TTS service engine to use | | `options.format?` | `"mp3"` \| `"ogg"` \| `"wav"` | Audio output format | | `options.gender?` | `"male"` \| `"female"` | Voice gender preference | | `options.lang?` | `string` | BCP-47 language code (e.g., "en-US"). Required unless voice is provided. | | `options.name?` | `string` | System voice name | | `options.pitch?` | `number` | Voice pitch (0–2, default 1 = normal). Providers may normalize to their own scale. | | `options.rate?` | `number` | Speech rate (0–2, default 1 = normal). Providers may normalize to their own scale. | | `options.text?` | `string` | Text to synthesize (max 4000 characters) | | `options.voice?` | `string` | ResponsiveVoice name (e.g., "UK English Male"). Resolved server-side to engine + lang. | | `options.volume?` | `number` | Volume (0–1, default 1 = full). | | `requestOptions?` | [`RequestOptions`](/api/api-client/src/#requestoptions) | Optional request configuration (timeout, signal) | ###### Returns [Section titled “Returns”](#returns-49) `AsyncGenerator`\<[`StreamChunk`](/api/types/src/#streamchunk)> AsyncGenerator yielding StreamChunk objects ###### Example [Section titled “Example”](#example-6) ```typescript const chunks: Uint8Array[] = []; for await (const chunk of client.synthesizeStream({ text: 'Hello', lang: 'en-US' })) { if (chunk.type === 'audio') chunks.push(chunk.data); if (chunk.type === 'end') console.log(`${chunk.totalBytes} bytes`); } ``` ##### updateBaseUrl() [Section titled “updateBaseUrl()”](#updatebaseurl) ```ts updateBaseUrl(newUrl): void; ``` Defined in: [src/client.ts:162](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L162) Update the base URL for subsequent requests. Called internally when X-Server-URL header is received, or externally by consumers. ###### Parameters [Section titled “Parameters”](#parameters-27) | Parameter | Type | | --------- | -------- | | `newUrl` | `string` | ###### Returns [Section titled “Returns”](#returns-50) `void` ##### verifyOrigin() [Section titled “verifyOrigin()”](#verifyorigin) ```ts verifyOrigin(token, requestOptions?): Promise; ``` Defined in: [src/client.ts:674](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L674) Submit an origin-verification token to confirm site ownership. Sent as an `Authorization: Bearer` credential; on success the site is marked verified. Not retried. ###### Parameters [Section titled “Parameters”](#parameters-28) | Parameter | Type | | ----------------- | ------------------------------------------------------- | | `token` | `string` | | `requestOptions?` | [`RequestOptions`](/api/api-client/src/#requestoptions) | ###### Returns [Section titled “Returns”](#returns-51) `Promise`\<[`VerifyOriginResponse`](/api/api-client/src/#verifyoriginresponse)> *** ### ResponsiveVoiceError [Section titled “ResponsiveVoiceError”](#responsivevoiceerror) Defined in: [src/errors.ts:9](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L9) Base error class for all API client errors #### Extends [Section titled “Extends”](#extends-6) * `Error` #### Extended by [Section titled “Extended by”](#extended-by-2) * [`ApiError`](/api/api-client/src/#apierror) * [`NetworkError`](/api/api-client/src/#networkerror) * [`ResponseValidationError`](/api/api-client/src/#responsevalidationerror) * [`RetryExhaustedError`](/api/api-client/src/#retryexhaustederror) #### Constructors [Section titled “Constructors”](#constructors-10) ##### Constructor [Section titled “Constructor”](#constructor-10) ```ts new ResponsiveVoiceError(message, cause?): ResponsiveVoiceError; ``` Defined in: [src/errors.ts:13](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L13) ###### Parameters [Section titled “Parameters”](#parameters-29) | Parameter | Type | | --------- | -------- | | `message` | `string` | | `cause?` | `Error` | ###### Returns [Section titled “Returns”](#returns-52) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror) ###### Overrides [Section titled “Overrides”](#overrides-6) ```ts Error.constructor ``` #### Properties [Section titled “Properties”](#properties-7) ##### cause? [Section titled “cause?”](#cause-6) ```ts readonly optional cause?: Error; ``` Defined in: [src/errors.ts:11](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L11) Original error that caused this error, if any ###### Overrides [Section titled “Overrides”](#overrides-7) ```ts Error.cause ``` ##### message [Section titled “message”](#message-7) ```ts message: string; ``` Defined in: [lib.es5.d.ts:1075](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1075) ###### Inherited from [Section titled “Inherited from”](#inherited-from-45) ```ts Error.message ``` ##### name [Section titled “name”](#name-6) ```ts name: string; ``` Defined in: [lib.es5.d.ts:1074](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1074) ###### Inherited from [Section titled “Inherited from”](#inherited-from-46) ```ts Error.name ``` ##### stack? [Section titled “stack?”](#stack-6) ```ts optional stack?: string; ``` Defined in: [lib.es5.d.ts:1076](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1076) ###### Inherited from [Section titled “Inherited from”](#inherited-from-47) ```ts Error.stack ``` *** ### RetryExhaustedError [Section titled “RetryExhaustedError”](#retryexhaustederror) Defined in: [src/errors.ts:191](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L191) Error thrown when all retry attempts are exhausted #### Extends [Section titled “Extends”](#extends-7) * [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror) #### Constructors [Section titled “Constructors”](#constructors-11) ##### Constructor [Section titled “Constructor”](#constructor-11) ```ts new RetryExhaustedError( message, attempts, lastError): RetryExhaustedError; ``` Defined in: [src/errors.ts:198](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L198) ###### Parameters [Section titled “Parameters”](#parameters-30) | Parameter | Type | | ----------- | -------- | | `message` | `string` | | `attempts` | `number` | | `lastError` | `Error` | ###### Returns [Section titled “Returns”](#returns-53) [`RetryExhaustedError`](/api/api-client/src/#retryexhaustederror) ###### Overrides [Section titled “Overrides”](#overrides-8) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`constructor`](/api/api-client/src/#constructor-10) #### Properties [Section titled “Properties”](#properties-8) ##### attempts [Section titled “attempts”](#attempts) ```ts readonly attempts: number; ``` Defined in: [src/errors.ts:193](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L193) Number of attempts made ##### cause? [Section titled “cause?”](#cause-7) ```ts readonly optional cause?: Error; ``` Defined in: [src/errors.ts:11](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L11) Original error that caused this error, if any ###### Inherited from [Section titled “Inherited from”](#inherited-from-48) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`cause`](/api/api-client/src/#cause-6) ##### lastError [Section titled “lastError”](#lasterror) ```ts readonly lastError: Error; ``` Defined in: [src/errors.ts:196](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L196) The last error that occurred ##### message [Section titled “message”](#message-8) ```ts message: string; ``` Defined in: [lib.es5.d.ts:1075](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1075) ###### Inherited from [Section titled “Inherited from”](#inherited-from-49) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`message`](/api/api-client/src/#message-6) ##### name [Section titled “name”](#name-7) ```ts name: string; ``` Defined in: [lib.es5.d.ts:1074](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1074) ###### Inherited from [Section titled “Inherited from”](#inherited-from-50) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`name`](/api/api-client/src/#name-6) ##### stack? [Section titled “stack?”](#stack-7) ```ts optional stack?: string; ``` Defined in: [lib.es5.d.ts:1076](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1076) ###### Inherited from [Section titled “Inherited from”](#inherited-from-51) [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`stack`](/api/api-client/src/#stack-6) *** ### TimeoutError [Section titled “TimeoutError”](#timeouterror) Defined in: [src/errors.ts:177](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L177) Error thrown when a request times out #### Extends [Section titled “Extends”](#extends-8) * [`NetworkError`](/api/api-client/src/#networkerror) #### Constructors [Section titled “Constructors”](#constructors-12) ##### Constructor [Section titled “Constructor”](#constructor-12) ```ts new TimeoutError( message, url, timeout, cause?): TimeoutError; ``` Defined in: [src/errors.ts:181](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L181) ###### Parameters [Section titled “Parameters”](#parameters-31) | Parameter | Type | | --------- | -------- | | `message` | `string` | | `url` | `string` | | `timeout` | `number` | | `cause?` | `Error` | ###### Returns [Section titled “Returns”](#returns-54) [`TimeoutError`](/api/api-client/src/#timeouterror) ###### Overrides [Section titled “Overrides”](#overrides-9) [`NetworkError`](/api/api-client/src/#networkerror).[`constructor`](/api/api-client/src/#constructor-5) #### Properties [Section titled “Properties”](#properties-9) ##### cause? [Section titled “cause?”](#cause-8) ```ts readonly optional cause?: Error; ``` Defined in: [src/errors.ts:11](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L11) Original error that caused this error, if any ###### Inherited from [Section titled “Inherited from”](#inherited-from-52) [`NetworkError`](/api/api-client/src/#networkerror).[`cause`](/api/api-client/src/#cause-2) ##### message [Section titled “message”](#message-9) ```ts message: string; ``` Defined in: [lib.es5.d.ts:1075](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1075) ###### Inherited from [Section titled “Inherited from”](#inherited-from-53) [`NetworkError`](/api/api-client/src/#networkerror).[`message`](/api/api-client/src/#message-2) ##### name [Section titled “name”](#name-8) ```ts name: string; ``` Defined in: [lib.es5.d.ts:1074](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1074) ###### Inherited from [Section titled “Inherited from”](#inherited-from-54) [`NetworkError`](/api/api-client/src/#networkerror).[`name`](/api/api-client/src/#name-2) ##### stack? [Section titled “stack?”](#stack-8) ```ts optional stack?: string; ``` Defined in: [lib.es5.d.ts:1076](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1076) ###### Inherited from [Section titled “Inherited from”](#inherited-from-55) [`NetworkError`](/api/api-client/src/#networkerror).[`stack`](/api/api-client/src/#stack-2) ##### timeout [Section titled “timeout”](#timeout) ```ts readonly timeout: number; ``` Defined in: [src/errors.ts:179](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L179) Timeout duration in milliseconds ##### url [Section titled “url”](#url-5) ```ts readonly url: string; ``` Defined in: [src/errors.ts:158](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L158) Request URL that failed ###### Inherited from [Section titled “Inherited from”](#inherited-from-56) [`NetworkError`](/api/api-client/src/#networkerror).[`url`](/api/api-client/src/#url-2) #### Accessors [Section titled “Accessors”](#accessors-7) ##### isRetryable [Section titled “isRetryable”](#isretryable-5) ###### Get Signature [Section titled “Get Signature”](#get-signature-15) ```ts get isRetryable(): boolean; ``` Defined in: [src/errors.ts:169](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L169) Network errors are always retryable ###### Returns [Section titled “Returns”](#returns-55) `boolean` ###### Inherited from [Section titled “Inherited from”](#inherited-from-57) [`NetworkError`](/api/api-client/src/#networkerror).[`isRetryable`](/api/api-client/src/#isretryable-2) *** ### ValidationError [Section titled “ValidationError”](#validationerror) Defined in: [src/errors.ts:135](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L135) Error thrown when request validation fails (400) #### Extends [Section titled “Extends”](#extends-9) * [`ApiError`](/api/api-client/src/#apierror) #### Constructors [Section titled “Constructors”](#constructors-13) ##### Constructor [Section titled “Constructor”](#constructor-13) ```ts new ValidationError( message, status, statusText, url, errors?, body?): ValidationError; ``` Defined in: [src/errors.ts:139](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L139) ###### Parameters [Section titled “Parameters”](#parameters-32) | Parameter | Type | | ------------ | ----------------------------------- | | `message` | `string` | | `status` | `number` | | `statusText` | `string` | | `url` | `string` | | `errors?` | `Record`\<`string`, `string`\[]> | | `body?` | `unknown` | ###### Returns [Section titled “Returns”](#returns-56) [`ValidationError`](/api/api-client/src/#validationerror) ###### Overrides [Section titled “Overrides”](#overrides-10) [`ApiError`](/api/api-client/src/#apierror).[`constructor`](/api/api-client/src/#constructor) #### Properties [Section titled “Properties”](#properties-10) ##### body? [Section titled “body?”](#body-4) ```ts readonly optional body?: unknown; ``` Defined in: [src/errors.ts:36](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L36) Response body, if available ###### Inherited from [Section titled “Inherited from”](#inherited-from-58) [`ApiError`](/api/api-client/src/#apierror).[`body`](/api/api-client/src/#body) ##### cause? [Section titled “cause?”](#cause-9) ```ts readonly optional cause?: Error; ``` Defined in: [src/errors.ts:11](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L11) Original error that caused this error, if any ###### Inherited from [Section titled “Inherited from”](#inherited-from-59) [`ApiError`](/api/api-client/src/#apierror).[`cause`](/api/api-client/src/#cause) ##### errors? [Section titled “errors?”](#errors) ```ts readonly optional errors?: Record; ``` Defined in: [src/errors.ts:137](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L137) Validation error details, if provided by the API ##### message [Section titled “message”](#message-10) ```ts message: string; ``` Defined in: [lib.es5.d.ts:1075](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1075) ###### Inherited from [Section titled “Inherited from”](#inherited-from-60) [`ApiError`](/api/api-client/src/#apierror).[`message`](/api/api-client/src/#message) ##### name [Section titled “name”](#name-9) ```ts name: string; ``` Defined in: [lib.es5.d.ts:1074](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1074) ###### Inherited from [Section titled “Inherited from”](#inherited-from-61) [`ApiError`](/api/api-client/src/#apierror).[`name`](/api/api-client/src/#name) ##### stack? [Section titled “stack?”](#stack-9) ```ts optional stack?: string; ``` Defined in: [lib.es5.d.ts:1076](https://github.com/microsoft/TypeScript/blob/v6.0.3/lib/lib.es5.d.ts#L1076) ###### Inherited from [Section titled “Inherited from”](#inherited-from-62) [`ApiError`](/api/api-client/src/#apierror).[`stack`](/api/api-client/src/#stack) ##### status [Section titled “status”](#status-4) ```ts readonly status: number; ``` Defined in: [src/errors.ts:30](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L30) HTTP status code of the failed request ###### Inherited from [Section titled “Inherited from”](#inherited-from-63) [`ApiError`](/api/api-client/src/#apierror).[`status`](/api/api-client/src/#status) ##### statusText [Section titled “statusText”](#statustext-4) ```ts readonly statusText: string; ``` Defined in: [src/errors.ts:33](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L33) HTTP status text ###### Inherited from [Section titled “Inherited from”](#inherited-from-64) [`ApiError`](/api/api-client/src/#apierror).[`statusText`](/api/api-client/src/#statustext) ##### url [Section titled “url”](#url-6) ```ts readonly url: string; ``` Defined in: [src/errors.ts:39](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L39) Request URL that failed ###### Inherited from [Section titled “Inherited from”](#inherited-from-65) [`ApiError`](/api/api-client/src/#apierror).[`url`](/api/api-client/src/#url) #### Accessors [Section titled “Accessors”](#accessors-8) ##### isClientError [Section titled “isClientError”](#isclienterror-4) ###### Get Signature [Section titled “Get Signature”](#get-signature-16) ```ts get isClientError(): boolean; ``` Defined in: [src/errors.ts:60](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L60) Check if this error is a client error (4xx) ###### Returns [Section titled “Returns”](#returns-57) `boolean` ###### Inherited from [Section titled “Inherited from”](#inherited-from-66) [`ApiError`](/api/api-client/src/#apierror).[`isClientError`](/api/api-client/src/#isclienterror) ##### isRetryable [Section titled “isRetryable”](#isretryable-6) ###### Get Signature [Section titled “Get Signature”](#get-signature-17) ```ts get isRetryable(): boolean; ``` Defined in: [src/errors.ts:75](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L75) Check if this error is retryable Server errors (5xx) and rate limits (429) are retryable ###### Returns [Section titled “Returns”](#returns-58) `boolean` ###### Inherited from [Section titled “Inherited from”](#inherited-from-67) [`ApiError`](/api/api-client/src/#apierror).[`isRetryable`](/api/api-client/src/#isretryable) ##### isServerError [Section titled “isServerError”](#isservererror-4) ###### Get Signature [Section titled “Get Signature”](#get-signature-18) ```ts get isServerError(): boolean; ``` Defined in: [src/errors.ts:67](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/errors.ts#L67) Check if this error is a server error (5xx) ###### Returns [Section titled “Returns”](#returns-59) `boolean` ###### Inherited from [Section titled “Inherited from”](#inherited-from-68) [`ApiError`](/api/api-client/src/#apierror).[`isServerError`](/api/api-client/src/#isservererror) *** ### WebSocketConnection [Section titled “WebSocketConnection”](#websocketconnection) Defined in: [src/websocket.ts:125](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/websocket.ts#L125) Persistent WebSocket client for the TTS streaming endpoint (`/v2/text/stream`). Maintains a single connection, demultiplexes audio frames by request ID, handles pings and exponential-backoff reconnection, and exposes the same [StreamChunk](/api/types/src/#streamchunk) iterator shape as the HTTP `synthesizeStream()` fallback so consumers can swap transports without reshaping their audio pipeline. Instantiate via [ResponsiveVoiceAPIClient](/api/api-client/src/#responsivevoiceapiclient)'s WebSocket transport mode; direct construction is supported for custom clients. The connection opens on first `connect()` or `synthesizeStream()` call — there is no eager handshake. #### Constructors [Section titled “Constructors”](#constructors-14) ##### Constructor [Section titled “Constructor”](#constructor-14) ```ts new WebSocketConnection(config): WebSocketConnection; ``` Defined in: [src/websocket.ts:136](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/websocket.ts#L136) ###### Parameters [Section titled “Parameters”](#parameters-33) | Parameter | Type | | --------- | ----------------------------------------------------------------------------- | | `config` | [`WebSocketConnectionConfig`](/api/api-client/src/#websocketconnectionconfig) | ###### Returns [Section titled “Returns”](#returns-60) [`WebSocketConnection`](/api/api-client/src/#websocketconnection) #### Accessors [Section titled “Accessors”](#accessors-9) ##### connected [Section titled “connected”](#connected) ###### Get Signature [Section titled “Get Signature”](#get-signature-19) ```ts get connected(): boolean; ``` Defined in: [src/websocket.ts:158](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/websocket.ts#L158) Whether the WebSocket is currently open and ready ###### Returns [Section titled “Returns”](#returns-61) `boolean` #### Methods [Section titled “Methods”](#methods-4) ##### cancel() [Section titled “cancel()”](#cancel) ```ts cancel(requestId): void; ``` Defined in: [src/websocket.ts:319](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/websocket.ts#L319) Cancel an in-flight synthesis request. ###### Parameters [Section titled “Parameters”](#parameters-34) | Parameter | Type | | ----------- | -------- | | `requestId` | `string` | ###### Returns [Section titled “Returns”](#returns-62) `void` ##### close() [Section titled “close()”](#close) ```ts close(): void; ``` Defined in: [src/websocket.ts:228](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/websocket.ts#L228) Close the connection gracefully. ###### Returns [Section titled “Returns”](#returns-63) `void` ##### connect() [Section titled “connect()”](#connect) ```ts connect(): Promise; ``` Defined in: [src/websocket.ts:166](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/websocket.ts#L166) Open the WebSocket connection. Resolves when the connection is open. If already connected, returns immediately. ###### Returns [Section titled “Returns”](#returns-64) `Promise`\<`void`> ##### synthesizeStream() [Section titled “synthesizeStream()”](#synthesizestream-1) ```ts synthesizeStream(request): AsyncGenerator; ``` Defined in: [src/websocket.ts:248](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/websocket.ts#L248) Send a synthesis request and return a streaming chunk generator. The returned AsyncGenerator yields the same StreamChunk types as the HTTP synthesizeStream() method. ###### Parameters [Section titled “Parameters”](#parameters-35) | Parameter | Type | Description | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `request` | { `engine?`: `"g1"` \| `"g2"` \| `"g3"` \| `"g5"` \| `"gwn"` \| `"msv"` \| `"oai"`; `format?`: `"mp3"` \| `"ogg"` \| `"wav"`; `gender?`: `"male"` \| `"female"`; `lang?`: `string`; `name?`: `string`; `pitch?`: `number`; `rate?`: `number`; `text`: `string`; `voice?`: `string`; `volume?`: `number`; } | - | | `request.engine?` | `"g1"` \| `"g2"` \| `"g3"` \| `"g5"` \| `"gwn"` \| `"msv"` \| `"oai"` | TTS service engine to use | | `request.format?` | `"mp3"` \| `"ogg"` \| `"wav"` | Audio output format | | `request.gender?` | `"male"` \| `"female"` | Voice gender preference | | `request.lang?` | `string` | BCP-47 language code (e.g., "en-US"). Required unless voice is provided. | | `request.name?` | `string` | System voice name | | `request.pitch?` | `number` | Voice pitch (0–2, default 1 = normal). Providers may normalize to their own scale. | | `request.rate?` | `number` | Speech rate (0–2, default 1 = normal). Providers may normalize to their own scale. | | `request.text` | `string` | Text to synthesize (max 4000 characters) | | `request.voice?` | `string` | ResponsiveVoice name (e.g., "UK English Male"). Resolved server-side to engine + lang. | | `request.volume?` | `number` | Volume (0–1, default 1 = full). | ###### Returns [Section titled “Returns”](#returns-65) `AsyncGenerator`\<[`StreamChunk`](/api/types/src/#streamchunk)> ## Interfaces [Section titled “Interfaces”](#interfaces) ### CachedVoiceData [Section titled “CachedVoiceData”](#cachedvoicedata) Defined in: [src/types.ts:55](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L55) Cached voice data stored in the client-side cache. #### Properties [Section titled “Properties”](#properties-11) ##### cachedAt [Section titled “cachedAt”](#cachedat) ```ts cachedAt: number; ``` Defined in: [src/types.ts:63](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L63) Timestamp when the data was cached ##### etag [Section titled “etag”](#etag) ```ts etag: string; ``` Defined in: [src/types.ts:57](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L57) ETag from the server response ##### systemVoices? [Section titled “systemVoices?”](#systemvoices) ```ts optional systemVoices?: SystemVoiceResponse[]; ``` Defined in: [src/types.ts:61](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L61) Cached system voices (dense; reachable from voices\[\*].voiceIDs chains) ##### voices [Section titled “voices”](#voices) ```ts voices: VoiceData[]; ``` Defined in: [src/types.ts:59](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L59) Cached voice collection *** ### CacheStorageAdapter [Section titled “CacheStorageAdapter”](#cachestorageadapter) Defined in: [src/types.ts:10](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L10) Storage adapter interface for plugging in custom cache backends. All methods may return synchronously or asynchronously. #### Methods [Section titled “Methods”](#methods-5) ##### getItem() [Section titled “getItem()”](#getitem-2) ```ts getItem(key): string | Promise | null; ``` Defined in: [src/types.ts:12](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L12) Retrieve a value by key, or `null` if not present. ###### Parameters [Section titled “Parameters”](#parameters-36) | Parameter | Type | | --------- | -------- | | `key` | `string` | ###### Returns [Section titled “Returns”](#returns-66) `string` | `Promise`\<`string` | `null`> | `null` ##### removeItem() [Section titled “removeItem()”](#removeitem-2) ```ts removeItem(key): void | Promise; ``` Defined in: [src/types.ts:16](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L16) Remove the value stored under `key`. No-op if absent. ###### Parameters [Section titled “Parameters”](#parameters-37) | Parameter | Type | | --------- | -------- | | `key` | `string` | ###### Returns [Section titled “Returns”](#returns-67) `void` | `Promise`\<`void`> ##### setItem() [Section titled “setItem()”](#setitem-2) ```ts setItem(key, value): void | Promise; ``` Defined in: [src/types.ts:14](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L14) Store a value under `key`, overwriting any existing entry. ###### Parameters [Section titled “Parameters”](#parameters-38) | Parameter | Type | | --------- | -------- | | `key` | `string` | | `value` | `string` | ###### Returns [Section titled “Returns”](#returns-68) `void` | `Promise`\<`void`> *** ### RateLimitInfo [Section titled “RateLimitInfo”](#ratelimitinfo) Defined in: [src/types.ts:129](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L129) Rate-limit headers surfaced from a response; a field is null when absent. #### Properties [Section titled “Properties”](#properties-12) ##### limit [Section titled “limit”](#limit) ```ts limit: number | null; ``` Defined in: [src/types.ts:131](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L131) `X-RateLimit-Limit` — max requests per window. ##### remaining [Section titled “remaining”](#remaining) ```ts remaining: number | null; ``` Defined in: [src/types.ts:133](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L133) `X-RateLimit-Remaining` — requests left in the current window. ##### retryAfter [Section titled “retryAfter”](#retryafter-1) ```ts retryAfter: number | null; ``` Defined in: [src/types.ts:135](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L135) `Retry-After` — seconds to wait, present on 429. *** ### RequestOptions [Section titled “RequestOptions”](#requestoptions) Defined in: [src/types.ts:191](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L191) Request options for API calls #### Properties [Section titled “Properties”](#properties-13) ##### signal? [Section titled “signal?”](#signal) ```ts optional signal?: AbortSignal; ``` Defined in: [src/types.ts:196](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L196) Custom signal for abort control ##### skipRetry? [Section titled “skipRetry?”](#skipretry) ```ts optional skipRetry?: boolean; ``` Defined in: [src/types.ts:199](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L199) Skip retry logic for this request ##### timeout? [Section titled “timeout?”](#timeout-1) ```ts optional timeout?: number; ``` Defined in: [src/types.ts:193](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L193) Custom timeout for this request *** ### ResolvedClientConfig [Section titled “ResolvedClientConfig”](#resolvedclientconfig) Defined in: [src/types.ts:141](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L141) Resolved configuration with all defaults applied #### Properties [Section titled “Properties”](#properties-14) ##### apiKey [Section titled “apiKey”](#apikey) ```ts apiKey: string; ``` Defined in: [src/types.ts:143](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L143) API key used to authenticate every request. ##### apiSecret [Section titled “apiSecret”](#apisecret) ```ts apiSecret: string | null; ``` Defined in: [src/types.ts:145](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L145) Server-issued secret; null when unset (browser callers). ##### authHeaders [Section titled “authHeaders”](#authheaders) ```ts authHeaders: | (() => | Record | Promise>) | null; ``` Defined in: [src/types.ts:147](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L147) Auth-header injection hook; null when unset (server callers using only apiKey+secret). ##### baseUrl [Section titled “baseUrl”](#baseurl-1) ```ts baseUrl: string; ``` Defined in: [src/types.ts:151](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L151) Fully-resolved base URL for the TTS API (no trailing slash). ##### fetch [Section titled “fetch”](#fetch) ```ts fetch: (input, init?) => Promise; ``` Defined in: [src/types.ts:159](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L159) Fetch implementation (defaults to the global `fetch`). [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/fetch) ###### Parameters [Section titled “Parameters”](#parameters-39) | Parameter | Type | | --------- | ---------------------- | | `input` | `RequestInfo` \| `URL` | | `init?` | `RequestInit` | ###### Returns [Section titled “Returns”](#returns-69) `Promise`\<`Response`> ##### onRateLimit [Section titled “onRateLimit”](#onratelimit) ```ts onRateLimit: ((info) => void) | null; ``` Defined in: [src/types.ts:165](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L165) Rate-limit header observer; null when unset. ##### onServerUrlChange [Section titled “onServerUrlChange”](#onserverurlchange) ```ts onServerUrlChange: ((newUrl) => void) | null; ``` Defined in: [src/types.ts:163](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L163) Callback invoked when the server assigns a new base URL (`X-RV-Server-URL` header). ##### onTokenRenewed [Section titled “onTokenRenewed”](#ontokenrenewed) ```ts onTokenRenewed: ((renewed) => void) | null; ``` Defined in: [src/types.ts:149](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L149) Sliding-renewal pickup callback; null when unset. ##### retryAttempts [Section titled “retryAttempts”](#retryattempts) ```ts retryAttempts: number; ``` Defined in: [src/types.ts:155](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L155) Max retry attempts for transient failures. ##### retryDelay [Section titled “retryDelay”](#retrydelay) ```ts retryDelay: number; ``` Defined in: [src/types.ts:157](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L157) Base delay between retries in milliseconds (exponential backoff multiplies this). ##### timeout [Section titled “timeout”](#timeout-2) ```ts timeout: number; ``` Defined in: [src/types.ts:153](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L153) Per-request timeout in milliseconds. ##### voiceCache [Section titled “voiceCache”](#voicecache) ```ts voiceCache: VoiceCacheConfig; ``` Defined in: [src/types.ts:161](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L161) Voice-cache configuration resolved with defaults applied. *** ### ResponsiveVoiceAPIClientConfig [Section titled “ResponsiveVoiceAPIClientConfig”](#responsivevoiceapiclientconfig) Defined in: [src/types.ts:69](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L69) Configuration for the ResponsiveVoice API client #### Properties [Section titled “Properties”](#properties-15) ##### apiKey [Section titled “apiKey”](#apikey-1) ```ts apiKey: string; ``` Defined in: [src/types.ts:71](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L71) API key — account identifier; never used as a credential alone. ##### apiSecret? [Section titled “apiSecret?”](#apisecret-1) ```ts optional apiSecret?: string; ``` Defined in: [src/types.ts:79](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L79) Server-issued secret paired with `apiKey`. When set, the client attaches `X-API-Key` + `X-API-Secret` headers to every request. For server-to-server callers only — should not be used in browser code. ##### authHeaders? [Section titled “authHeaders?”](#authheaders-1) ```ts optional authHeaders?: () => | Record | Promise>; ``` Defined in: [src/types.ts:89](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L89) Hook returning auth headers to attach to every request. Called per request, so the caller can return a fresh bearer token each time (e.g. core injects `Authorization: Bearer ` here after a handshake). Headers returned merge into the request, overriding any conflicting `X-API-Key`/`X-API-Secret`. May return synchronously or as a Promise — the client awaits the result. ###### Returns [Section titled “Returns”](#returns-70) \| `Record`\<`string`, `string`> | `Promise`\<`Record`\<`string`, `string`>> ##### baseUrl? [Section titled “baseUrl?”](#baseurl-2) ```ts optional baseUrl?: string; ``` Defined in: [src/types.ts:99](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L99) Base URL for the API (default: `https://texttospeech.responsivevoice.org/v2`) ##### fetch? [Section titled “fetch?”](#fetch-1) ```ts optional fetch?: (input, init?) => Promise; ``` Defined in: [src/types.ts:111](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L111) Custom fetch implementation (for testing or server-side usage) [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/fetch) ###### Parameters [Section titled “Parameters”](#parameters-40) | Parameter | Type | | --------- | ---------------------- | | `input` | `RequestInfo` \| `URL` | | `init?` | `RequestInit` | ###### Returns [Section titled “Returns”](#returns-71) `Promise`\<`Response`> ##### onRateLimit? [Section titled “onRateLimit?”](#onratelimit-1) ```ts optional onRateLimit?: (info) => void; ``` Defined in: [src/types.ts:125](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L125) Hook fired on every response carrying rate-limit headers (`X-RateLimit-Limit`/`X-RateLimit-Remaining`/`Retry-After`). Lets callers pace requests against the advertised allowance rather than discovering the limit only by hitting 429s. ###### Parameters [Section titled “Parameters”](#parameters-41) | Parameter | Type | | --------- | ----------------------------------------------------- | | `info` | [`RateLimitInfo`](/api/api-client/src/#ratelimitinfo) | ###### Returns [Section titled “Returns”](#returns-72) `void` ##### onServerUrlChange? [Section titled “onServerUrlChange?”](#onserverurlchange-1) ```ts optional onServerUrlChange?: (newUrl) => void; ``` Defined in: [src/types.ts:117](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L117) Callback invoked when the server assigns a different URL via X-Server-URL header ###### Parameters [Section titled “Parameters”](#parameters-42) | Parameter | Type | | --------- | -------- | | `newUrl` | `string` | ###### Returns [Section titled “Returns”](#returns-73) `void` ##### onTokenRenewed? [Section titled “onTokenRenewed?”](#ontokenrenewed-1) ```ts optional onTokenRenewed?: (renewed) => void; ``` Defined in: [src/types.ts:96](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L96) Hook fired when a response carries an `X-RV-Auth-Renewed` header (sliding renewal piggy-back from tts-api). Receives the fresh token * exp so the caller can swap its stored bearer transparently. ###### Parameters [Section titled “Parameters”](#parameters-43) | Parameter | Type | | --------------- | --------------------------------------- | | `renewed` | { `exp`: `number`; `token`: `string`; } | | `renewed.exp` | `number` | | `renewed.token` | `string` | ###### Returns [Section titled “Returns”](#returns-74) `void` ##### retryAttempts? [Section titled “retryAttempts?”](#retryattempts-1) ```ts optional retryAttempts?: number; ``` Defined in: [src/types.ts:105](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L105) Number of retry attempts for transient errors (default: 3) ##### retryDelay? [Section titled “retryDelay?”](#retrydelay-1) ```ts optional retryDelay?: number; ``` Defined in: [src/types.ts:108](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L108) Base delay between retries in milliseconds (default: 1000) ##### timeout? [Section titled “timeout?”](#timeout-3) ```ts optional timeout?: number; ``` Defined in: [src/types.ts:102](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L102) Request timeout in milliseconds (default: 30000) ##### voiceCache? [Section titled “voiceCache?”](#voicecache-1) ```ts optional voiceCache?: VoiceCacheConfig; ``` Defined in: [src/types.ts:114](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L114) Voice cache configuration (enabled by default) *** ### RetryConfig [Section titled “RetryConfig”](#retryconfig) Defined in: [src/retry.ts:10](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/retry.ts#L10) Configuration for retry behavior #### Properties [Section titled “Properties”](#properties-16) ##### backoffMultiplier [Section titled “backoffMultiplier”](#backoffmultiplier) ```ts backoffMultiplier: number; ``` Defined in: [src/retry.ts:21](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/retry.ts#L21) Multiplier for exponential backoff ##### baseDelay [Section titled “baseDelay”](#basedelay) ```ts baseDelay: number; ``` Defined in: [src/retry.ts:15](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/retry.ts#L15) Base delay between retries in milliseconds ##### jitter [Section titled “jitter”](#jitter) ```ts jitter: boolean; ``` Defined in: [src/retry.ts:24](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/retry.ts#L24) Whether to add jitter to delay times ##### maxAttempts [Section titled “maxAttempts”](#maxattempts) ```ts maxAttempts: number; ``` Defined in: [src/retry.ts:12](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/retry.ts#L12) Maximum number of retry attempts (not including the initial request) ##### maxDelay [Section titled “maxDelay”](#maxdelay) ```ts maxDelay: number; ``` Defined in: [src/retry.ts:18](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/retry.ts#L18) Maximum delay between retries in milliseconds *** ### RetryDecision [Section titled “RetryDecision”](#retrydecision) Defined in: [src/retry.ts:41](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/retry.ts#L41) Result of checking if an error is retryable #### Properties [Section titled “Properties”](#properties-17) ##### delay? [Section titled “delay?”](#delay) ```ts optional delay?: number; ``` Defined in: [src/retry.ts:46](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/retry.ts#L46) Suggested delay before retrying, in milliseconds ##### shouldRetry [Section titled “shouldRetry”](#shouldretry) ```ts shouldRetry: boolean; ``` Defined in: [src/retry.ts:43](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/retry.ts#L43) Whether the operation should be retried *** ### VerifyOriginResponse [Section titled “VerifyOriginResponse”](#verifyoriginresponse) Defined in: [src/client.ts:63](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L63) Response from `POST /v2/auth/verify-origin`. #### Properties [Section titled “Properties”](#properties-18) ##### origin [Section titled “origin”](#origin) ```ts origin: string; ``` Defined in: [src/client.ts:67](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L67) The proven origin (`scheme://host[:port]`). ##### verified [Section titled “verified”](#verified) ```ts verified: boolean; ``` Defined in: [src/client.ts:65](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/client.ts#L65) Whether the request origin was verified for the apiKey. *** ### VoiceCacheConfig [Section titled “VoiceCacheConfig”](#voicecacheconfig) Defined in: [src/types.ts:32](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L32) Configuration for the client-side voice cache. #### Properties [Section titled “Properties”](#properties-19) ##### apiKey? [Section titled “apiKey?”](#apikey-2) ```ts optional apiKey?: string; ``` Defined in: [src/types.ts:49](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L49) API key used to scope cache keys per-website (prevents cross-site cache collisions on same domain) ##### customStorage? [Section titled “customStorage?”](#customstorage) ```ts optional customStorage?: CacheStorageAdapter; ``` Defined in: [src/types.ts:40](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L40) Custom storage adapter — overrides `storage` when provided ##### enabled? [Section titled “enabled?”](#enabled-1) ```ts optional enabled?: boolean; ``` Defined in: [src/types.ts:34](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L34) Whether caching is enabled (default: true) ##### keyPrefix? [Section titled “keyPrefix?”](#keyprefix) ```ts optional keyPrefix?: string; ``` Defined in: [src/types.ts:43](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L43) Key prefix for cache entries (default: 'rv-voice-cache') ##### storage? [Section titled “storage?”](#storage) ```ts optional storage?: CacheStorageType; ``` Defined in: [src/types.ts:37](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L37) Storage backend selection (default: 'auto') ##### ttl? [Section titled “ttl?”](#ttl) ```ts optional ttl?: number; ``` Defined in: [src/types.ts:46](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L46) Cache TTL in seconds — cached data within this window is served without a network request (default: 300) *** ### VoiceFilters [Section titled “VoiceFilters”](#voicefilters) Defined in: [src/types.ts:171](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L171) Filters for listing voices #### Properties [Section titled “Properties”](#properties-20) ##### browser? [Section titled “browser?”](#browser) ```ts optional browser?: string; ``` Defined in: [src/types.ts:179](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L179) Platform context for personalized voice selection (not a filter for cache bypass) ##### browserVersion? [Section titled “browserVersion?”](#browserversion) ```ts optional browserVersion?: string; ``` Defined in: [src/types.ts:181](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L181) Browser version (paired with `browser` for platform-aware voice resolution) ##### gender? [Section titled “gender?”](#gender) ```ts optional gender?: "male" | "female"; ``` Defined in: [src/types.ts:176](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L176) Filter by gender ##### lang? [Section titled “lang?”](#lang) ```ts optional lang?: string; ``` Defined in: [src/types.ts:173](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L173) Filter by language code ##### os? [Section titled “os?”](#os) ```ts optional os?: string; ``` Defined in: [src/types.ts:183](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L183) Operating system name (paired with `os_version` for platform-aware voice resolution) ##### osVersion? [Section titled “osVersion?”](#osversion) ```ts optional osVersion?: string; ``` Defined in: [src/types.ts:185](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L185) Operating system version (paired with `os` for platform-aware voice resolution) *** ### WebSocketConnectionConfig [Section titled “WebSocketConnectionConfig”](#websocketconnectionconfig) Defined in: [src/websocket.ts:39](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/websocket.ts#L39) Configuration for constructing a [WebSocketConnection](/api/api-client/src/#websocketconnection). Only `baseUrl` is required; the rest control reconnect behaviour and authentication. Pass a `WebSocket` constructor to use the client outside browsers where the global `WebSocket` is unavailable. #### Properties [Section titled “Properties”](#properties-21) ##### apiKey? [Section titled “apiKey?”](#apikey-3) ```ts optional apiKey?: string; ``` Defined in: [src/websocket.ts:43](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/websocket.ts#L43) API key for authentication ##### autoReconnect? [Section titled “autoReconnect?”](#autoreconnect) ```ts optional autoReconnect?: boolean; ``` Defined in: [src/websocket.ts:53](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/websocket.ts#L53) Auto-reconnect on unexpected close. ###### Default Value [Section titled “Default Value”](#default-value) ```ts true ``` ##### baseUrl [Section titled “baseUrl”](#baseurl-3) ```ts baseUrl: string; ``` Defined in: [src/websocket.ts:41](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/websocket.ts#L41) Base URL of the TTS API (https\://...) — will be converted to wss\:// ##### getAuthToken? [Section titled “getAuthToken?”](#getauthtoken) ```ts optional getAuthToken?: () => Promise; ``` Defined in: [src/websocket.ts:49](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/websocket.ts#L49) Resolves the bearer JWT to send as the `token` upgrade query param. Awaited on every `connect()` so reconnects carry a fresh, unexpired token. Returns `undefined` when no bearer is held (key-only upgrade). ###### Returns [Section titled “Returns”](#returns-75) `Promise`\<`string` | `undefined`> ##### maxReconnectAttempts? [Section titled “maxReconnectAttempts?”](#maxreconnectattempts) ```ts optional maxReconnectAttempts?: number; ``` Defined in: [src/websocket.ts:55](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/websocket.ts#L55) Max reconnect attempts before giving up. ###### Default Value [Section titled “Default Value”](#default-value-1) ```ts 5 ``` ##### pingInterval? [Section titled “pingInterval?”](#pinginterval) ```ts optional pingInterval?: number; ``` Defined in: [src/websocket.ts:51](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/websocket.ts#L51) Ping interval in ms to keep the connection alive. ###### Default Value [Section titled “Default Value”](#default-value-2) ```ts 25000 ``` ##### reconnectDelay? [Section titled “reconnectDelay?”](#reconnectdelay) ```ts optional reconnectDelay?: number; ``` Defined in: [src/websocket.ts:57](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/websocket.ts#L57) Base delay between reconnect attempts in ms (exponential backoff). ###### Default Value [Section titled “Default Value”](#default-value-3) ```ts 1000 ``` ##### WebSocket? [Section titled “WebSocket?”](#websocket) ```ts optional WebSocket?: (url) => WebSocket; ``` Defined in: [src/websocket.ts:68](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/websocket.ts#L68) Custom WebSocket constructor for environments where the global `WebSocket` is not available (e.g. Node.js below v22). Pass `ws` or any W3C-compatible implementation. ###### Parameters [Section titled “Parameters”](#parameters-44) | Parameter | Type | | --------- | ----------------- | | `url` | `string` \| `URL` | ###### Returns [Section titled “Returns”](#returns-76) `WebSocket` ###### Example [Section titled “Example”](#example-7) ```typescript import WebSocket from 'ws'; new WebSocketConnection({ baseUrl: '...', WebSocket }); ``` ## Type Aliases [Section titled “Type Aliases”](#type-aliases) ### CacheStorageType [Section titled “CacheStorageType”](#cachestoragetype) ```ts type CacheStorageType = "auto" | "localStorage" | "sessionStorage" | "filesystem" | "memory"; ``` Defined in: [src/types.ts:27](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/types.ts#L27) Storage type for voice cache. * `'auto'` (default): detects environment and picks the best backend * `'localStorage'`: force browser localStorage * `'sessionStorage'`: force browser sessionStorage * `'filesystem'`: force Node.js filesystem (os.tmpdir()) * `'memory'`: force in-memory Map (process/page lifetime only) ## Variables [Section titled “Variables”](#variables) ### DEFAULT\_RETRY\_CONFIG [Section titled “DEFAULT\_RETRY\_CONFIG”](#default_retry_config) ```ts const DEFAULT_RETRY_CONFIG: RetryConfig; ``` Defined in: [src/retry.ts:30](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/retry.ts#L30) Default retry configuration ## Functions [Section titled “Functions”](#functions) ### calculateRetryDelay() [Section titled “calculateRetryDelay()”](#calculateretrydelay) ```ts function calculateRetryDelay( attempt, config, suggestedDelay?): number; ``` Defined in: [src/retry.ts:90](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/retry.ts#L90) Calculate delay for a retry attempt using exponential backoff #### Parameters [Section titled “Parameters”](#parameters-45) | Parameter | Type | Description | | ----------------- | ------------------------------------------------- | -------------------------------------------------------- | | `attempt` | `number` | The retry attempt number (1-based) | | `config` | [`RetryConfig`](/api/api-client/src/#retryconfig) | Retry configuration | | `suggestedDelay?` | `number` | Optional suggested delay (e.g., from Retry-After header) | #### Returns [Section titled “Returns”](#returns-77) `number` Delay in milliseconds *** ### createRetryWrapper() [Section titled “createRetryWrapper()”](#createretrywrapper) ```ts function createRetryWrapper(config?): (fn) => Promise; ``` Defined in: [src/retry.ts:178](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/retry.ts#L178) Create a retry wrapper with pre-configured settings #### Parameters [Section titled “Parameters”](#parameters-46) | Parameter | Type | | --------- | ---------------------------------------------------------------- | | `config` | `Partial`\<[`RetryConfig`](/api/api-client/src/#retryconfig)> | #### Returns [Section titled “Returns”](#returns-78) \<`T`>(`fn`) => `Promise`\<`T`> *** ### isRetryableError() [Section titled “isRetryableError()”](#isretryableerror) ```ts function isRetryableError(error): RetryDecision; ``` Defined in: [src/retry.ts:52](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/retry.ts#L52) Determine if an error is retryable #### Parameters [Section titled “Parameters”](#parameters-47) | Parameter | Type | | --------- | --------- | | `error` | `unknown` | #### Returns [Section titled “Returns”](#returns-79) [`RetryDecision`](/api/api-client/src/#retrydecision) *** ### withRetry() [Section titled “withRetry()”](#withretry) ```ts function withRetry(fn, config?): Promise; ``` Defined in: [src/retry.ts:130](https://github.com/responsivevoice/api-client/blob/v2.0.1/src/retry.ts#L130) Execute a function with retry logic #### Type Parameters [Section titled “Type Parameters”](#type-parameters) | Type Parameter | | -------------- | | `T` | #### Parameters [Section titled “Parameters”](#parameters-48) | Parameter | Type | Description | | --------- | ---------------------------------------------------------------- | --------------------------------------------------- | | `fn` | () => `Promise`\<`T`> | The async function to execute | | `config` | `Partial`\<[`RetryConfig`](/api/api-client/src/#retryconfig)> | Retry configuration (partial, merged with defaults) | #### Returns [Section titled “Returns”](#returns-80) `Promise`\<`T`> The result of the function #### Throws [Section titled “Throws”](#throws-1) RetryExhaustedError if all retries fail ## References [Section titled “References”](#references) ### AudioFormat [Section titled “AudioFormat”](#audioformat) Re-exports [AudioFormat](/api/types/src/#audioformat) *** ### AudioResponse [Section titled “AudioResponse”](#audioresponse) Re-exports [AudioResponse](/api/types/src/#audioresponse) *** ### StreamAudioChunk [Section titled “StreamAudioChunk”](#streamaudiochunk) Re-exports [StreamAudioChunk](/api/types/src/#streamaudiochunk) *** ### StreamChunk [Section titled “StreamChunk”](#streamchunk) Re-exports [StreamChunk](/api/types/src/#streamchunk) *** ### StreamEnd [Section titled “StreamEnd”](#streamend) Re-exports [StreamEnd](/api/types/src/#streamend) *** ### StreamError [Section titled “StreamError”](#streamerror) Re-exports [StreamError](/api/types/src/#streamerror) *** ### StreamMetadata [Section titled “StreamMetadata”](#streammetadata) Re-exports [StreamMetadata](/api/types/src/#streammetadata) *** ### SynthesizeRequest [Section titled “SynthesizeRequest”](#synthesizerequest) Re-exports [SynthesizeRequest](/api/types/src/#synthesizerequest) *** ### SynthesizeResponse [Section titled “SynthesizeResponse”](#synthesizeresponse) Re-exports [SynthesizeResponse](/api/types/src/#synthesizeresponse) *** ### SystemVoice [Section titled “SystemVoice”](#systemvoice) Re-exports [SystemVoice](/api/types/src/#systemvoice) *** ### TTSService [Section titled “TTSService”](#ttsservice) Re-exports [TTSService](/api/types/src/#ttsservice) *** ### Voice [Section titled “Voice”](#voice) Re-exports [Voice](/api/types/src/#voice) *** ### VoiceGender [Section titled “VoiceGender”](#voicegender) Re-exports [VoiceGender](/api/types/src/#voicegender) # @responsivevoice/core > API documentation for @responsivevoice/core The ResponsiveVoice text-to-speech client library. Provides a modern TypeScript API over the native Web Speech API with HTTP/WebSocket fallback for premium and non-native voices. Re-exports the dashboard feature plugins from `@responsivevoice/features` for convenience. Use `getResponsiveVoice()` to obtain the singleton client. ## Classes [Section titled “Classes”](#classes) ### ResponsiveVoice [Section titled “ResponsiveVoice”](#responsivevoice) Defined in: [src/responsivevoice.ts:32](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L32) ResponsiveVoice — the complete text-to-speech interface. Features: * Automatic voice resolution with 5-strategy matching across each voice's fallback chain * Native Web Speech API when available * HTTP audio fallback for universal support * iOS audio unlock handling * Text chunking for long text * Event system (OnStart, OnEnd, OnError, etc.) * Analytics character tracking * Queue-until-ready: speak() calls before init() are queued and replayed #### Extends [Section titled “Extends”](#extends) * `ResponsiveVoiceCore` #### Constructors [Section titled “Constructors”](#constructors) ##### Constructor [Section titled “Constructor”](#constructor) ```ts new ResponsiveVoice(options?): ResponsiveVoice; ``` Defined in: [src/responsivevoice-core.ts:357](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L357) ###### Parameters [Section titled “Parameters”](#parameters) | Parameter | Type | | --------- | ------------------------------------------------------------------------- | | `options` | [`ResponsiveVoiceInitOptions`](/api/core/src/#responsivevoiceinitoptions) | ###### Returns [Section titled “Returns”](#returns) [`ResponsiveVoice`](/api/core/src/#responsivevoice) ###### Inherited from [Section titled “Inherited from”](#inherited-from) ```ts ResponsiveVoiceCore.constructor ``` #### Properties [Section titled “Properties”](#properties) ##### features [Section titled “features”](#features) ```ts features: FeatureManager; ``` Defined in: [src/responsivevoice-core.ts:306](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L306) Feature manager for dashboard features (welcome message, speak links, etc.) ###### Inherited from [Section titled “Inherited from”](#inherited-from-1) ```ts ResponsiveVoiceCore.features ``` ##### version [Section titled “version”](#version) ```ts readonly version: string = __RV_CORE_VERSION__; ``` Defined in: [src/responsivevoice.ts:34](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L34) Package version of `@responsivevoice/core`, injected at build time. ##### services [Section titled “services”](#services) ```ts readonly static services: { FALLBACK_AUDIO: 1; NATIVE_TTS: 0; }; ``` Defined in: [src/responsivevoice-core.ts:260](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L260) Service type constants for backward compatibility. ###### FALLBACK\_AUDIO [Section titled “FALLBACK\_AUDIO”](#fallback_audio) ```ts FALLBACK_AUDIO: 1; ``` ###### NATIVE\_TTS [Section titled “NATIVE\_TTS”](#native_tts) ```ts NATIVE_TTS: 0; ``` ###### Inherited from [Section titled “Inherited from”](#inherited-from-2) ```ts ResponsiveVoiceCore.services ``` #### Accessors [Section titled “Accessors”](#accessors) ##### allowPermissionPopupEverywhere [Section titled “allowPermissionPopupEverywhere”](#allowpermissionpopupeverywhere) ###### Get Signature [Section titled “Get Signature”](#get-signature) ```ts get allowPermissionPopupEverywhere(): boolean; ``` Defined in: [src/responsivevoice.ts:318](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L318) Force showing popup everywhere (not just mobile/Safari) ###### Returns [Section titled “Returns”](#returns-1) `boolean` ###### Set Signature [Section titled “Set Signature”](#set-signature) ```ts set allowPermissionPopupEverywhere(value): void; ``` Defined in: [src/responsivevoice.ts:322](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L322) ###### Parameters [Section titled “Parameters”](#parameters-1) | Parameter | Type | | --------- | --------- | | `value` | `boolean` | ###### Returns [Section titled “Returns”](#returns-2) `void` ##### clickEventDetected [Section titled “clickEventDetected”](#clickeventdetected) ###### Get Signature [Section titled “Get Signature”](#get-signature-1) ```ts get clickEventDetected(): boolean; ``` Defined in: [src/responsivevoice.ts:350](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L350) Check if a click event has been detected ###### Returns [Section titled “Returns”](#returns-3) `boolean` ##### debug [Section titled “debug”](#debug) ###### Get Signature [Section titled “Get Signature”](#get-signature-2) ```ts get debug(): boolean; ``` Defined in: [src/responsivevoice.ts:474](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L474) Debug flag — enable/disable debug logging ###### Returns [Section titled “Returns”](#returns-4) `boolean` ###### Set Signature [Section titled “Set Signature”](#set-signature-1) ```ts set debug(enabled): void; ``` Defined in: [src/responsivevoice.ts:478](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L478) ###### Parameters [Section titled “Parameters”](#parameters-2) | Parameter | Type | | --------- | --------- | | `enabled` | `boolean` | ###### Returns [Section titled “Returns”](#returns-5) `void` ##### debugTools [Section titled “debugTools”](#debugtools) ###### Get Signature [Section titled “Get Signature”](#get-signature-3) ```ts get debugTools(): DebugTools | undefined; ``` Defined in: [src/responsivevoice.ts:495](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L495) Operational debug tools. **Only available when `debug` is true.** Returns `undefined` when `debug` is false. Lazily constructed on first access and cached; dropped when `debug` is turned off, so re-enabling produces a fresh instance rather than a stale one. ###### Example [Section titled “Example”](#example) ```ts responsiveVoice.debug = true; await responsiveVoice.debugTools?.clearCache('voices'); ``` ###### Returns [Section titled “Returns”](#returns-6) [`DebugTools`](/api/core/src/#debugtools-1) | `undefined` ##### disablePermissionPopup [Section titled “disablePermissionPopup”](#disablepermissionpopup) ###### Get Signature [Section titled “Get Signature”](#get-signature-4) ```ts get disablePermissionPopup(): boolean; ``` Defined in: [src/responsivevoice.ts:294](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L294) Disable the permission popup entirely ###### Returns [Section titled “Returns”](#returns-7) `boolean` ###### Set Signature [Section titled “Set Signature”](#set-signature-2) ```ts set disablePermissionPopup(value): void; ``` Defined in: [src/responsivevoice.ts:298](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L298) ###### Parameters [Section titled “Parameters”](#parameters-3) | Parameter | Type | | --------- | --------- | | `value` | `boolean` | ###### Returns [Section titled “Returns”](#returns-8) `void` ##### enableEstimationTimeout [Section titled “enableEstimationTimeout”](#enableestimationtimeout) ###### Get Signature [Section titled “Get Signature”](#get-signature-5) ```ts get enableEstimationTimeout(): boolean; ``` Defined in: [src/responsivevoice.ts:459](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L459) Whether estimation-based timeout is enabled for speech playback. ###### Default Value [Section titled “Default Value”](#default-value) ```ts true ``` ###### Returns [Section titled “Returns”](#returns-9) `boolean` ###### Set Signature [Section titled “Set Signature”](#set-signature-3) ```ts set enableEstimationTimeout(value): void; ``` Defined in: [src/responsivevoice.ts:463](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L463) ###### Parameters [Section titled “Parameters”](#parameters-4) | Parameter | Type | | --------- | --------- | | `value` | `boolean` | ###### Returns [Section titled “Returns”](#returns-10) `void` ##### fallbackMode [Section titled “fallbackMode”](#fallbackmode) ###### Get Signature [Section titled “Get Signature”](#get-signature-6) ```ts get fallbackMode(): boolean; ``` Defined in: [src/responsivevoice.ts:236](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L236) Check if currently using fallback mode. Returns true if the fallback (HTTP audio) engine is currently active. ###### Returns [Section titled “Returns”](#returns-11) `boolean` ##### outputDevice [Section titled “outputDevice”](#outputdevice) ###### Get Signature [Section titled “Get Signature”](#get-signature-7) ```ts get outputDevice(): string | null; ``` Defined in: [src/responsivevoice.ts:153](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L153) Output device property (getter/setter). Note: Setter is fire-and-forget; prefer `setOutputDevice()` for async handling. ###### Returns [Section titled “Returns”](#returns-12) `string` | `null` ###### Set Signature [Section titled “Set Signature”](#set-signature-4) ```ts set outputDevice(deviceId): void; ``` Defined in: [src/responsivevoice.ts:157](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L157) ###### Parameters [Section titled “Parameters”](#parameters-5) | Parameter | Type | | ---------- | ------------------ | | `deviceId` | `string` \| `null` | ###### Returns [Section titled “Returns”](#returns-13) `void` ##### prosodyFallback [Section titled “prosodyFallback”](#prosodyfallback) ###### Get Signature [Section titled “Get Signature”](#get-signature-8) ```ts get prosodyFallback(): boolean; ``` Defined in: [src/responsivevoice.ts:307](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L307) Whether client-side prosody fallback (`audio.playbackRate`, `audio.volume`) is applied for knobs the server didn't apply natively. Three-tier resolution: per-`speak()` opt > instance setting > init default > true. ###### Returns [Section titled “Returns”](#returns-14) `boolean` ###### Set Signature [Section titled “Set Signature”](#set-signature-5) ```ts set prosodyFallback(value): void; ``` Defined in: [src/responsivevoice.ts:311](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L311) ###### Parameters [Section titled “Parameters”](#parameters-6) | Parameter | Type | | --------- | --------- | | `value` | `boolean` | ###### Returns [Section titled “Returns”](#returns-15) `void` ##### speechAllowedByUser [Section titled “speechAllowedByUser”](#speechallowedbyuser) ###### Get Signature [Section titled “Get Signature”](#get-signature-9) ```ts get speechAllowedByUser(): boolean | null; ``` Defined in: [src/responsivevoice.ts:287](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L287) User's speech permission state (null if not yet asked) ###### Returns [Section titled “Returns”](#returns-16) `boolean` | `null` ##### webPlayer [Section titled “webPlayer”](#webplayer) ###### Get Signature [Section titled “Get Signature”](#get-signature-10) ```ts get webPlayer(): WebPlayerFeature | undefined; ``` Defined in: [src/responsivevoice-core.ts:316](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L316) Imperative API for the web player feature. Returns the active orchestrator when `webPlayer.enabled: true` was passed to [init](/api/core/src/#init) (or `Partial` was overridden), `undefined` otherwise. Use `rv.webPlayer?.mount(selectorOrElement, overrides?)` to attach a player to dynamically-added content (SPAs, lazy-loaded sections). ###### Returns [Section titled “Returns”](#returns-17) `WebPlayerFeature` | `undefined` ###### Inherited from [Section titled “Inherited from”](#inherited-from-3) ```ts ResponsiveVoiceCore.webPlayer ``` #### Methods [Section titled “Methods”](#methods) ##### addEventListener() [Section titled “addEventListener()”](#addeventlistener) ```ts addEventListener(event, callback): void; ``` Defined in: [src/responsivevoice.ts:393](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L393) Add event listener ###### Parameters [Section titled “Parameters”](#parameters-7) | Parameter | Type | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `event` | \| `"OnLoad"` \| `"OnReady"` \| `"OnStart"` \| `"OnEnd"` \| `"OnError"` \| `"OnPause"` \| `"OnResume"` \| `"OnServiceSwitched"` \| `"OnClickEvent"` \| `"OnAllowSpeechClicked"` \| `"OnPartStart"` \| `"OnPartEnd"` \| `"OnVoiceResolved"` | | `callback` | `GenericEventCallback` | ###### Returns [Section titled “Returns”](#returns-18) `void` ##### allowSpeechClicked() [Section titled “allowSpeechClicked()”](#allowspeechclicked) ```ts allowSpeechClicked(allowed): void; ``` Defined in: [src/responsivevoice.ts:329](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L329) Programmatically set speech permission response ###### Parameters [Section titled “Parameters”](#parameters-8) | Parameter | Type | | --------- | --------- | | `allowed` | `boolean` | ###### Returns [Section titled “Returns”](#returns-19) `void` ##### applyTextReplacements() [Section titled “applyTextReplacements()”](#applytextreplacements) ```ts applyTextReplacements(text): string; ``` Defined in: [src/responsivevoice.ts:423](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L423) Apply the current text replacement rules to a string and return the result. ###### Parameters [Section titled “Parameters”](#parameters-9) | Parameter | Type | Description | | --------- | -------- | --------------------- | | `text` | `string` | The text to transform | ###### Returns [Section titled “Returns”](#returns-20) `string` The text with all matching replacement rules applied ##### cancel() [Section titled “cancel()”](#cancel) ```ts cancel(): void; ``` Defined in: [src/responsivevoice-core.ts:944](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L944) Cancel current speech and clear queue ###### Returns [Section titled “Returns”](#returns-21) `void` ###### Inherited from [Section titled “Inherited from”](#inherited-from-4) ```ts ResponsiveVoiceCore.cancel ``` ##### checkSpeechAllowed() [Section titled “checkSpeechAllowed()”](#checkspeechallowed) ```ts checkSpeechAllowed(options?): boolean; ``` Defined in: [src/responsivevoice-core.ts:1028](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L1028) Check if speech is allowed and show permission popup if needed ###### Parameters [Section titled “Parameters”](#parameters-10) | Parameter | Type | | --------- | ----------------------------------------------------------------- | | `options` | [`PermissionPopupOptions`](/api/core/src/#permissionpopupoptions) | ###### Returns [Section titled “Returns”](#returns-22) `boolean` ###### Inherited from [Section titled “Inherited from”](#inherited-from-5) ```ts ResponsiveVoiceCore.checkSpeechAllowed ``` ##### chunkText() [Section titled “chunkText()”](#chunktext) ```ts chunkText(text, options?): TextChunk[]; ``` Defined in: [src/responsivevoice.ts:434](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L434) Split text into chunks using the current character limit and chunking rules. ###### Parameters [Section titled “Parameters”](#parameters-11) | Parameter | Type | Description | | ------------------------- | -------------------------------- | ---------------------------------------- | | `text` | `string` | The text to chunk | | `options?` | { `characterLimit?`: `number`; } | Optional overrides (e.g. characterLimit) | | `options.characterLimit?` | `number` | - | ###### Returns [Section titled “Returns”](#returns-23) [`TextChunk`](/api/text/src/#textchunk)\[] Array of TextChunk objects ##### clearFallbackPool() [Section titled “clearFallbackPool()”](#clearfallbackpool) ```ts clearFallbackPool(): void; ``` Defined in: [src/responsivevoice.ts:165](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L165) Clear the fallback audio pool. Stops all playing audio and resets the pool to empty state. ###### Returns [Section titled “Returns”](#returns-24) `void` ##### clickEvent() [Section titled “clickEvent()”](#clickevent) ```ts clickEvent(): void; ``` Defined in: [src/responsivevoice.ts:366](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L366) Manually trigger the click event handler. Simulates a user interaction event for permission initialization. ###### Returns [Section titled “Returns”](#returns-25) `void` ##### dispose() [Section titled “dispose()”](#dispose) ```ts dispose(): void; ``` Defined in: [src/responsivevoice-core.ts:1043](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L1043) Clean up resources ###### Returns [Section titled “Returns”](#returns-26) `void` ###### Inherited from [Section titled “Inherited from”](#inherited-from-6) ```ts ResponsiveVoiceCore.dispose ``` ##### enableWindowClickHook() [Section titled “enableWindowClickHook()”](#enablewindowclickhook) ```ts enableWindowClickHook(): void; ``` Defined in: [src/responsivevoice.ts:358](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L358) Enable window click hook for user interaction detection. Called automatically on iOS, Android, and Safari. ###### Returns [Section titled “Returns”](#returns-27) `void` ##### getAvailableVoices() [Section titled “getAvailableVoices()”](#getavailablevoices) ```ts getAvailableVoices(): string[]; ``` Defined in: [src/responsivevoice.ts:50](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L50) Get voices with availability information ###### Returns [Section titled “Returns”](#returns-28) `string`\[] ##### getBrowserVoiceCount() [Section titled “getBrowserVoiceCount()”](#getbrowservoicecount) ```ts getBrowserVoiceCount(): number; ``` Defined in: [src/responsivevoice.ts:66](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L66) Get the count of available browser voices. ###### Returns [Section titled “Returns”](#returns-29) `number` ##### getBrowserVoices() [Section titled “getBrowserVoices()”](#getbrowservoices) ```ts getBrowserVoices(): SpeechSynthesisVoice[]; ``` Defined in: [src/responsivevoice.ts:59](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L59) Get browser's native SpeechSynthesis voices. ###### Returns [Section titled “Returns”](#returns-30) `SpeechSynthesisVoice`\[] Array of SpeechSynthesisVoice objects (may be empty on some platforms) ##### getCharacterLimit() [Section titled “getCharacterLimit()”](#getcharacterlimit) ```ts getCharacterLimit(): number; ``` Defined in: [src/responsivevoice.ts:126](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L126) Get the current character limit for text chunking. ###### Returns [Section titled “Returns”](#returns-31) `number` ##### getConfig() [Section titled “getConfig()”](#getconfig) ```ts getConfig(): { apiKey: string; defaultParams: SpeakParams; defaultVoice: string; }; ``` Defined in: [src/responsivevoice.ts:535](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L535) Get current configuration ###### Returns [Section titled “Returns”](#returns-32) ```ts { apiKey: string; defaultParams: SpeakParams; defaultVoice: string; } ``` ###### apiKey [Section titled “apiKey”](#apikey) ```ts apiKey: string; ``` ###### defaultParams [Section titled “defaultParams”](#defaultparams) ```ts defaultParams: SpeakParams; ``` ###### defaultVoice [Section titled “defaultVoice”](#defaultvoice) ```ts defaultVoice: string; ``` ##### getDefaultVoice() [Section titled “getDefaultVoice()”](#getdefaultvoice) ```ts getDefaultVoice(): string; ``` Defined in: [src/responsivevoice.ts:80](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L80) Get the default voice ###### Returns [Section titled “Returns”](#returns-33) `string` ##### getEstimatedTimeLength() [Section titled “getEstimatedTimeLength()”](#getestimatedtimelength) ```ts getEstimatedTimeLength(text, multiplier?): number; ``` Defined in: [src/responsivevoice.ts:451](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L451) Estimate the speech duration for a given text ###### Parameters [Section titled “Parameters”](#parameters-12) | Parameter | Type | Default value | Description | | ------------ | -------- | ------------- | ------------------------------------------------- | | `text` | `string` | `undefined` | The text to estimate duration for | | `multiplier` | `number` | `1` | Optional multiplier for the duration (default: 1) | ###### Returns [Section titled “Returns”](#returns-34) `number` Estimated duration in milliseconds ##### getOutputDevice() [Section titled “getOutputDevice()”](#getoutputdevice) ```ts getOutputDevice(): string | null; ``` Defined in: [src/responsivevoice.ts:145](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L145) Get the current audio output device ID ###### Returns [Section titled “Returns”](#returns-35) `string` | `null` Device ID or null if using default device ##### getPlatformInfo() [Section titled “getPlatformInfo()”](#getplatforminfo) ```ts getPlatformInfo(): PlatformInfo; ``` Defined in: [src/responsivevoice.ts:519](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L519) Get platform information (boolean flags for browser/OS detection) ###### Returns [Section titled “Returns”](#returns-36) [`PlatformInfo`](/api/core/src/#platforminfo) ##### getPlatformVersionInfo() [Section titled “getPlatformVersionInfo()”](#getplatformversioninfo) ```ts getPlatformVersionInfo(): PlatformVersionInfo; ``` Defined in: [src/responsivevoice.ts:528](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L528) Get human-readable platform version information. ###### Returns [Section titled “Returns”](#returns-37) [`PlatformVersionInfo`](/api/core/src/#platformversioninfo) Browser name/version, OS name/version, and device type ##### getServiceEnabled() [Section titled “getServiceEnabled()”](#getserviceenabled) ```ts getServiceEnabled(service): boolean; ``` Defined in: [src/responsivevoice.ts:212](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L212) Check if a TTS service is enabled ###### Parameters [Section titled “Parameters”](#parameters-13) | Parameter | Type | | --------- | -------- | | `service` | `number` | ###### Returns [Section titled “Returns”](#returns-38) `boolean` ##### getServicePriority() [Section titled “getServicePriority()”](#getservicepriority) ```ts getServicePriority(): number[]; ``` Defined in: [src/responsivevoice.ts:228](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L228) Get the current service priority order ###### Returns [Section titled “Returns”](#returns-39) `number`\[] ##### getVoices() [Section titled “getVoices()”](#getvoices) ```ts getVoices(): { deprecated?: boolean; flag: string; gender: "f" | "m"; isByok?: boolean; lang: string; name: string; provider?: string; voiceIDs: number[]; }[]; ``` Defined in: [src/responsivevoice.ts:43](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L43) Get all available voices ###### Returns [Section titled “Returns”](#returns-40) ##### getVolume() [Section titled “getVolume()”](#getvolume) ```ts getVolume(): number; ``` Defined in: [src/responsivevoice.ts:100](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L100) Get the current volume setting ###### Returns [Section titled “Returns”](#returns-41) `number` ##### hidePermissionPopup() [Section titled “hidePermissionPopup()”](#hidepermissionpopup) ```ts hidePermissionPopup(): void; ``` Defined in: [src/responsivevoice.ts:343](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L343) Hide the permission popup ###### Returns [Section titled “Returns”](#returns-42) `void` ##### init() [Section titled “init()”](#init) ```ts init(options?): Promise; ``` Defined in: [src/responsivevoice-core.ts:472](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L472) Initialize ResponsiveVoice — the single configuration entry point. Creates the API client, fetches voice data, and emits OnReady. Can be called multiple times safely (idempotent after first init). Speak calls made before init() completes are queued and replayed. ###### Parameters [Section titled “Parameters”](#parameters-14) | Parameter | Type | Description | | --------- | ------------------------------------------------------------------------- | ------------------------------------------ | | `options` | [`ResponsiveVoiceInitOptions`](/api/core/src/#responsivevoiceinitoptions) | API key, voice defaults, and feature flags | ###### Returns [Section titled “Returns”](#returns-43) `Promise`\<`void`> Promise that resolves when ready ###### Example [Section titled “Example”](#example-1) ```typescript await rv.init({ apiKey: 'your-api-key' }); rv.speak('Hello world'); ``` ###### Inherited from [Section titled “Inherited from”](#inherited-from-7) ```ts ResponsiveVoiceCore.init ``` ##### isDemoMode() [Section titled “isDemoMode()”](#isdemomode) ```ts isDemoMode(): boolean; ``` Defined in: [src/responsivevoice.ts:276](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L276) Check if running in demo mode (no API key) ###### Returns [Section titled “Returns”](#returns-44) `boolean` ##### isFallbackAudioPlaying() [Section titled “isFallbackAudioPlaying()”](#isfallbackaudioplaying) ```ts isFallbackAudioPlaying(): boolean; ``` Defined in: [src/responsivevoice.ts:172](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L172) Check if fallback audio is currently playing ###### Returns [Section titled “Returns”](#returns-45) `boolean` ##### isForceFallback() [Section titled “isForceFallback()”](#isforcefallback) ```ts isForceFallback(): boolean; ``` Defined in: [src/responsivevoice.ts:195](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L195) Check if fallback mode is forced ###### Returns [Section titled “Returns”](#returns-46) `boolean` ##### isNativeAvailable() [Section titled “isNativeAvailable()”](#isnativeavailable) ```ts isNativeAvailable(): Promise; ``` Defined in: [src/responsivevoice.ts:254](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L254) Check if native TTS is available ###### Returns [Section titled “Returns”](#returns-47) `Promise`\<`boolean`> ##### isNativeSupported() [Section titled “isNativeSupported()”](#isnativesupported) ```ts isNativeSupported(): boolean; ``` Defined in: [src/responsivevoice.ts:247](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L247) Check if native TTS is supported ###### Returns [Section titled “Returns”](#returns-48) `boolean` ##### isPaused() [Section titled “isPaused()”](#ispaused) ```ts isPaused(): boolean; ``` Defined in: [src/responsivevoice-core.ts:1021](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L1021) Check if speech is paused ###### Returns [Section titled “Returns”](#returns-49) `boolean` ###### Inherited from [Section titled “Inherited from”](#inherited-from-8) ```ts ResponsiveVoiceCore.isPaused ``` ##### isPlaying() [Section titled “isPlaying()”](#isplaying) ```ts isPlaying(): boolean; ``` Defined in: [src/responsivevoice-core.ts:1014](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L1014) Check if speech is currently playing ###### Returns [Section titled “Returns”](#returns-50) `boolean` ###### Inherited from [Section titled “Inherited from”](#inherited-from-9) ```ts ResponsiveVoiceCore.isPlaying ``` ##### isReady() [Section titled “isReady()”](#isready) ```ts isReady(): boolean; ``` Defined in: [src/responsivevoice.ts:269](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L269) Check if ResponsiveVoice is initialized ###### Returns [Section titled “Returns”](#returns-51) `boolean` ##### log() [Section titled “log()”](#log) ```ts log(message): void; ``` Defined in: [src/responsivevoice.ts:512](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L512) Log a debug message (only outputs if debug is enabled) ###### Parameters [Section titled “Parameters”](#parameters-15) | Parameter | Type | | --------- | -------- | | `message` | `string` | ###### Returns [Section titled “Returns”](#returns-52) `void` ##### pause() [Section titled “pause()”](#pause) ```ts pause(): void; ``` Defined in: [src/responsivevoice-core.ts:964](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L964) Pause current speech Note: Paused speech will auto-cancel after 60 seconds (browser limitation) ###### Returns [Section titled “Returns”](#returns-53) `void` ###### Inherited from [Section titled “Inherited from”](#inherited-from-10) ```ts ResponsiveVoiceCore.pause ``` ##### refreshAuthToken() [Section titled “refreshAuthToken()”](#refreshauthtoken) ```ts refreshAuthToken(): Promise; ``` Defined in: [src/responsivevoice-core.ts:829](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L829) Re-run the v2 handshake against `/v2/auth/refresh` and update the stored token. Invoked automatically by the bearer-header builder when the token is near expiry; SDK consumers may also call this manually after an unexpected 401. ###### Returns [Section titled “Returns”](#returns-54) `Promise`\<`void`> ###### Inherited from [Section titled “Inherited from”](#inherited-from-11) ```ts ResponsiveVoiceCore.refreshAuthToken ``` ##### removeEventListener() [Section titled “removeEventListener()”](#removeeventlistener) ```ts removeEventListener(event, callback): void; ``` Defined in: [src/responsivevoice.ts:400](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L400) Remove event listener ###### Parameters [Section titled “Parameters”](#parameters-16) | Parameter | Type | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `event` | \| `"OnLoad"` \| `"OnReady"` \| `"OnStart"` \| `"OnEnd"` \| `"OnError"` \| `"OnPause"` \| `"OnResume"` \| `"OnServiceSwitched"` \| `"OnClickEvent"` \| `"OnAllowSpeechClicked"` \| `"OnPartStart"` \| `"OnPartEnd"` \| `"OnVoiceResolved"` | | `callback` | `GenericEventCallback` | ###### Returns [Section titled “Returns”](#returns-55) `void` ##### resume() [Section titled “resume()”](#resume) ```ts resume(): void; ``` Defined in: [src/responsivevoice-core.ts:984](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L984) Resume paused speech If pause timed out, re-queues remaining text automatically. ###### Returns [Section titled “Returns”](#returns-56) `void` ###### Inherited from [Section titled “Inherited from”](#inherited-from-12) ```ts ResponsiveVoiceCore.resume ``` ##### setCharacterLimit() [Section titled “setCharacterLimit()”](#setcharacterlimit) ```ts setCharacterLimit(limit): void; ``` Defined in: [src/responsivevoice.ts:119](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L119) Set the character limit for text chunking. ###### Parameters [Section titled “Parameters”](#parameters-17) | Parameter | Type | Description | | --------- | -------- | ---------------------------------------------------- | | `limit` | `number` | Character limit (clamped to 50–300 at chunking time) | ###### Returns [Section titled “Returns”](#returns-57) `void` ##### setDefaultRate() [Section titled “setDefaultRate()”](#setdefaultrate) ```ts setDefaultRate(rate): void; ``` Defined in: [src/responsivevoice.ts:109](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L109) Set the default speech rate ###### Parameters [Section titled “Parameters”](#parameters-18) | Parameter | Type | Description | | --------- | -------- | ------------------------ | | `rate` | `number` | Speech rate (0.1 to 1.5) | ###### Returns [Section titled “Returns”](#returns-58) `void` ##### setDefaultVoice() [Section titled “setDefaultVoice()”](#setdefaultvoice) ```ts setDefaultVoice(voice): void; ``` Defined in: [src/responsivevoice.ts:73](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L73) Set the default voice ###### Parameters [Section titled “Parameters”](#parameters-19) | Parameter | Type | | --------- | -------- | | `voice` | `string` | ###### Returns [Section titled “Returns”](#returns-59) `void` ##### setForceFallback() [Section titled “setForceFallback()”](#setforcefallback) ```ts setForceFallback(force): void; ``` Defined in: [src/responsivevoice.ts:183](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L183) Force fallback mode (always use HTTP audio) ###### Parameters [Section titled “Parameters”](#parameters-20) | Parameter | Type | | --------- | --------- | | `force` | `boolean` | ###### Returns [Section titled “Returns”](#returns-60) `void` ##### setOutputDevice() [Section titled “setOutputDevice()”](#setoutputdevice) ```ts setOutputDevice(deviceId): Promise; ``` Defined in: [src/responsivevoice.ts:136](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L136) Set the audio output device for fallback audio playback. Uses the Web Audio `setSinkId()` API (Chrome 49+, Edge 17+). ###### Parameters [Section titled “Parameters”](#parameters-21) | Parameter | Type | Description | | ---------- | -------- | -------------------------------------------------------- | | `deviceId` | `string` | Device ID from navigator.mediaDevices.enumerateDevices() | ###### Returns [Section titled “Returns”](#returns-61) `Promise`\<`void`> ##### setServiceEnabled() [Section titled “setServiceEnabled()”](#setserviceenabled) ```ts setServiceEnabled(service, enabled): void; ``` Defined in: [src/responsivevoice.ts:205](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L205) Enable or disable a TTS service. ###### Parameters [Section titled “Parameters”](#parameters-22) | Parameter | Type | Description | | --------- | --------- | ------------------------------------------------------------ | | `service` | `number` | Service type constant (NATIVE\_TTS = 0, FALLBACK\_AUDIO = 1) | | `enabled` | `boolean` | Whether the service should be enabled | ###### Returns [Section titled “Returns”](#returns-62) `void` ##### setServicePriority() [Section titled “setServicePriority()”](#setservicepriority) ```ts setServicePriority(priority): void; ``` Defined in: [src/responsivevoice.ts:221](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L221) Set the priority order for TTS services. ###### Parameters [Section titled “Parameters”](#parameters-23) | Parameter | Type | Description | | ---------- | ----------- | ---------------------------------------------------------- | | `priority` | `number`\[] | Array of service types in priority order (first = highest) | ###### Returns [Section titled “Returns”](#returns-63) `void` ##### setTextReplacements() [Section titled “setTextReplacements()”](#settextreplacements) ```ts setTextReplacements(rules): void; ``` Defined in: [src/responsivevoice.ts:413](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L413) Set text replacement rules for custom text transformations. ###### Parameters [Section titled “Parameters”](#parameters-24) | Parameter | Type | Description | | --------- | ------------------------------------------------------------------------ | -------------------------------------------- | | `rules` | [`TextReplacementRule`](/api/core/src/#textreplacementrule)\[] \| `null` | Array of replacement rules, or null to clear | ###### Returns [Section titled “Returns”](#returns-64) `void` ##### setVolume() [Section titled “setVolume()”](#setvolume) ```ts setVolume(volume): void; ``` Defined in: [src/responsivevoice.ts:91](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L91) Set the global volume (0-1) ###### Parameters [Section titled “Parameters”](#parameters-25) | Parameter | Type | | --------- | -------- | | `volume` | `number` | ###### Returns [Section titled “Returns”](#returns-65) `void` ##### showPermissionPopup() [Section titled “showPermissionPopup()”](#showpermissionpopup) ```ts showPermissionPopup(options?): void; ``` Defined in: [src/responsivevoice.ts:336](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L336) Show the permission popup manually ###### Parameters [Section titled “Parameters”](#parameters-26) | Parameter | Type | | --------- | ----------------------------------------------------------------- | | `options` | [`PermissionPopupOptions`](/api/core/src/#permissionpopupoptions) | ###### Returns [Section titled “Returns”](#returns-66) `void` ##### speak() [Section titled “speak()”](#speak) ###### Call Signature [Section titled “Call Signature”](#call-signature) ```ts speak( text, voice?, params?): void; ``` Defined in: [src/responsivevoice-core.ts:847](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L847) Speak text using TTS. ###### Parameters [Section titled “Parameters”](#parameters-27) | Parameter | Type | Description | | --------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | `string` | Text to speak | | `voice?` | [`VoiceSelectorInput`](/api/types/src/#voiceselectorinput) | Voice name, regex pattern, or query filter. Accepts a real `RegExp` (e.g. `/Portuguese/i`) as JS sugar — internally normalized to the JSON-clean `{ regex, flags }` literal. | | `params?` | `SpeakOptions` | Speech parameters and callbacks | ###### Returns [Section titled “Returns”](#returns-67) `void` ###### Inherited from [Section titled “Inherited from”](#inherited-from-13) ```ts ResponsiveVoiceCore.speak ``` ###### Call Signature [Section titled “Call Signature”](#call-signature-1) ```ts speak(text, params?): void; ``` Defined in: [src/responsivevoice-core.ts:853](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L853) Speak text using the default voice with custom parameters. ###### Parameters [Section titled “Parameters”](#parameters-28) | Parameter | Type | Description | | --------- | -------------- | ------------------------------- | | `text` | `string` | Text to speak | | `params?` | `SpeakOptions` | Speech parameters and callbacks | ###### Returns [Section titled “Returns”](#returns-68) `void` ###### Inherited from [Section titled “Inherited from”](#inherited-from-14) ```ts ResponsiveVoiceCore.speak ``` ##### voiceSupport() [Section titled “voiceSupport()”](#voicesupport) ```ts voiceSupport(): boolean; ``` Defined in: [src/responsivevoice.ts:262](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L262) Check if Web Speech API is supported. Legacy compatibility method — prefer `isNativeSupported()`. ###### Returns [Section titled “Returns”](#returns-69) `boolean` ## Interfaces [Section titled “Interfaces”](#interfaces) ### DebugTools [Section titled “DebugTools”](#debugtools-1) Defined in: [src/debug-tools.ts:33](https://github.com/responsivevoice/core/blob/v2.0.1/src/debug-tools.ts#L33) Operational helpers exposed only when `responsiveVoice.debug = true`. Lets a developer or support operator clear scoped cache state without touching `localStorage` by hand. Never part of the default surface so third-party scripts can't accidentally invoke it. #### Methods [Section titled “Methods”](#methods-1) ##### clearCache() [Section titled “clearCache()”](#clearcache) ```ts clearCache(scope?): Promise; ``` Defined in: [src/debug-tools.ts:45](https://github.com/responsivevoice/core/blob/v2.0.1/src/debug-tools.ts#L45) Clear persistent browser cache scoped to the current API key. * `'voices'` delegates to `apiClient.clearVoiceCache()` so custom storage adapters (memory / IndexedDB / file) are honored. * `'server'` and `'config'` clear their own localStorage keys directly. * `'all'` (default) clears every scope. Silently no-ops when the API key is not set or `localStorage` is unavailable (SSR, private browsing). ###### Parameters [Section titled “Parameters”](#parameters-29) | Parameter | Type | | --------- | ----------------------------------------- | | `scope?` | [`CacheScope`](/api/core/src/#cachescope) | ###### Returns [Section titled “Returns”](#returns-70) `Promise`\<`void`> *** ### PermissionConfig [Section titled “PermissionConfig”](#permissionconfig) Defined in: [src/permissions/manager.ts:44](https://github.com/responsivevoice/core/blob/v2.0.1/src/permissions/manager.ts#L44) Permission manager configuration #### Properties [Section titled “Properties”](#properties-1) ##### allowPermissionPopupEverywhere? [Section titled “allowPermissionPopupEverywhere?”](#allowpermissionpopupeverywhere-1) ```ts optional allowPermissionPopupEverywhere?: boolean; ``` Defined in: [src/permissions/manager.ts:55](https://github.com/responsivevoice/core/blob/v2.0.1/src/permissions/manager.ts#L55) Show permission UI on all platforms (not just iOS) ###### Default Value [Section titled “Default Value”](#default-value-1) ```ts false ``` ##### disablePermissionPopup? [Section titled “disablePermissionPopup?”](#disablepermissionpopup-1) ```ts optional disablePermissionPopup?: boolean; ``` Defined in: [src/permissions/manager.ts:49](https://github.com/responsivevoice/core/blob/v2.0.1/src/permissions/manager.ts#L49) Disable permission popup/prompts ###### Default Value [Section titled “Default Value”](#default-value-2) ```ts false ``` *** ### PermissionPopupOptions [Section titled “PermissionPopupOptions”](#permissionpopupoptions) Defined in: [src/permissions/popup.ts:13](https://github.com/responsivevoice/core/blob/v2.0.1/src/permissions/popup.ts#L13) Options for the permission popup (per-call overrides) #### Properties [Section titled “Properties”](#properties-2) ##### allowLabel? [Section titled “allowLabel?”](#allowlabel) ```ts optional allowLabel?: string; ``` Defined in: [src/permissions/popup.ts:19](https://github.com/responsivevoice/core/blob/v2.0.1/src/permissions/popup.ts#L19) Override the ALLOW button label (default: "ALLOW") ##### appendTo? [Section titled “appendTo?”](#appendto) ```ts optional appendTo?: HTMLElement; ``` Defined in: [src/permissions/popup.ts:25](https://github.com/responsivevoice/core/blob/v2.0.1/src/permissions/popup.ts#L25) Append popup to a specific container instead of document.body ##### classPrefix? [Section titled “classPrefix?”](#classprefix) ```ts optional classPrefix?: string; ``` Defined in: [src/permissions/popup.ts:27](https://github.com/responsivevoice/core/blob/v2.0.1/src/permissions/popup.ts#L27) CSS class prefix to replace the default "rv" prefix (e.g. "myapp" → "myappNotification") ##### denyLabel? [Section titled “denyLabel?”](#denylabel) ```ts optional denyLabel?: string; ``` Defined in: [src/permissions/popup.ts:21](https://github.com/responsivevoice/core/blob/v2.0.1/src/permissions/popup.ts#L21) Override the DENY button label (default: "DENY") ##### position? [Section titled “position?”](#position) ```ts optional position?: "top" | "bottom"; ``` Defined in: [src/permissions/popup.ts:23](https://github.com/responsivevoice/core/blob/v2.0.1/src/permissions/popup.ts#L23) Position of the popup bar (default: "bottom") ##### renderPopup? [Section titled “renderPopup?”](#renderpopup) ```ts optional renderPopup?: (onAllow, onDeny) => HTMLElement; ``` Defined in: [src/permissions/popup.ts:32](https://github.com/responsivevoice/core/blob/v2.0.1/src/permissions/popup.ts#L32) Custom renderer — return your own HTMLElement for full control. Called with allow/deny callbacks; when invoked, skips the default popup entirely. ###### Parameters [Section titled “Parameters”](#parameters-30) | Parameter | Type | | --------- | ------------ | | `onAllow` | () => `void` | | `onDeny` | () => `void` | ###### Returns [Section titled “Returns”](#returns-71) `HTMLElement` ##### textOverride? [Section titled “textOverride?”](#textoverride) ```ts optional textOverride?: string; ``` Defined in: [src/permissions/popup.ts:17](https://github.com/responsivevoice/core/blob/v2.0.1/src/permissions/popup.ts#L17) Override the action text (default: "wants to play speech") ##### urlOverride? [Section titled “urlOverride?”](#urloverride) ```ts optional urlOverride?: string; ``` Defined in: [src/permissions/popup.ts:15](https://github.com/responsivevoice/core/blob/v2.0.1/src/permissions/popup.ts#L15) Override the origin/hostname shown in the popup *** ### PlatformInfo [Section titled “PlatformInfo”](#platforminfo) Defined in: [src/platform/detector.ts:9](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L9) Information about the current platform and its capabilities #### Properties [Section titled “Properties”](#properties-3) ##### hasIOSAudioUnlockBug [Section titled “hasIOSAudioUnlockBug”](#hasiosaudiounlockbug) ```ts hasIOSAudioUnlockBug: boolean; ``` Defined in: [src/platform/detector.ts:58](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L58) Whether the platform exhibits the iOS silent-unlock bug that blocks `speechSynthesis` until a priming utterance runs. ##### iOSVersion [Section titled “iOSVersion”](#iosversion) ```ts iOSVersion: number; ``` Defined in: [src/platform/detector.ts:36](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L36) Major iOS version, or `0` when not iOS or unparseable. ##### isAndroid [Section titled “isAndroid”](#isandroid) ```ts isAndroid: boolean; ``` Defined in: [src/platform/detector.ts:26](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L26) True on Android. ##### isChrome [Section titled “isChrome”](#ischrome) ```ts isChrome: boolean; ``` Defined in: [src/platform/detector.ts:12](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L12) True when the current browser is Chrome (excluding Edge, which also matches `/chrome/` in UA). ##### isEdge [Section titled “isEdge”](#isedge) ```ts isEdge: boolean; ``` Defined in: [src/platform/detector.ts:18](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L18) True when the current browser is Microsoft Edge. ##### isFirefox [Section titled “isFirefox”](#isfirefox) ```ts isFirefox: boolean; ``` Defined in: [src/platform/detector.ts:16](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L16) True when the current browser is Firefox. ##### isIOS [Section titled “isIOS”](#isios) ```ts isIOS: boolean; ``` Defined in: [src/platform/detector.ts:24](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L24) True on iOS (iPhone/iPad/iPod). ##### isIOS10 [Section titled “isIOS10”](#isios10) ```ts isIOS10: boolean; ``` Defined in: [src/platform/detector.ts:40](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L40) True on iOS 10. ##### isIOS11Plus [Section titled “isIOS11Plus”](#isios11plus) ```ts isIOS11Plus: boolean; ``` Defined in: [src/platform/detector.ts:42](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L42) True on iOS 11 or later. ##### isIOS12 [Section titled “isIOS12”](#isios12) ```ts isIOS12: boolean; ``` Defined in: [src/platform/detector.ts:44](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L44) True on iOS 12. ##### isIOS9 [Section titled “isIOS9”](#isios9) ```ts isIOS9: boolean; ``` Defined in: [src/platform/detector.ts:38](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L38) True on iOS 9. ##### isLinux [Section titled “isLinux”](#islinux) ```ts isLinux: boolean; ``` Defined in: [src/platform/detector.ts:32](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L32) True on desktop Linux (excluding Android). ##### isMacOS [Section titled “isMacOS”](#ismacos) ```ts isMacOS: boolean; ``` Defined in: [src/platform/detector.ts:28](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L28) True on macOS (excluding iOS). ##### isOpera [Section titled “isOpera”](#isopera) ```ts isOpera: boolean; ``` Defined in: [src/platform/detector.ts:20](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L20) True when the current browser is Opera. ##### isSafari [Section titled “isSafari”](#issafari) ```ts isSafari: boolean; ``` Defined in: [src/platform/detector.ts:14](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L14) True when the current browser is Safari (excluding Chrome on iOS, which reports Safari-like UA). ##### isWindows [Section titled “isWindows”](#iswindows) ```ts isWindows: boolean; ``` Defined in: [src/platform/detector.ts:30](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L30) True on Windows. ##### requiresUserInteraction [Section titled “requiresUserInteraction”](#requiresuserinteraction) ```ts requiresUserInteraction: boolean; ``` Defined in: [src/platform/detector.ts:56](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L56) Whether the platform requires a user gesture before speech/audio can play. ##### supportsAudioElement [Section titled “supportsAudioElement”](#supportsaudioelement) ```ts supportsAudioElement: boolean; ``` Defined in: [src/platform/detector.ts:50](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L50) Whether `HTMLAudioElement` is available for fallback playback. ##### supportsSendBeacon [Section titled “supportsSendBeacon”](#supportssendbeacon) ```ts supportsSendBeacon: boolean; ``` Defined in: [src/platform/detector.ts:52](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L52) Whether `navigator.sendBeacon()` is available for analytics. ##### supportsWebSpeech [Section titled “supportsWebSpeech”](#supportswebspeech) ```ts supportsWebSpeech: boolean; ``` Defined in: [src/platform/detector.ts:48](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L48) Whether the Web Speech API (`speechSynthesis`) is available. ##### useTimerForEvents [Section titled “useTimerForEvents”](#usetimerforevents) ```ts useTimerForEvents: boolean; ``` Defined in: [src/platform/detector.ts:60](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L60) Whether engine events must be driven by a local timer rather than the native `onend`/`onboundary` callbacks. *** ### PlatformVersionInfo [Section titled “PlatformVersionInfo”](#platformversioninfo) Defined in: [src/platform/version-extractor.ts:11](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/version-extractor.ts#L11) Extracted platform version information for reporting #### Properties [Section titled “Properties”](#properties-4) ##### browser [Section titled “browser”](#browser) ```ts browser: string; ``` Defined in: [src/platform/version-extractor.ts:13](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/version-extractor.ts#L13) Human-readable browser name (`'Chrome'`, `'Safari'`, `'Firefox'`, `'Edge'`, `'Opera'`, or `'Unknown'`). ##### browserVersion [Section titled “browserVersion”](#browserversion) ```ts browserVersion: string; ``` Defined in: [src/platform/version-extractor.ts:15](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/version-extractor.ts#L15) Browser major version as a string (e.g. `'120'`), or `''` when unparseable. ##### deviceType [Section titled “deviceType”](#devicetype) ```ts deviceType: "desktop" | "mobile" | "tablet"; ``` Defined in: [src/platform/version-extractor.ts:21](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/version-extractor.ts#L21) Form factor inferred from UA and viewport heuristics. ##### os [Section titled “os”](#os) ```ts os: string; ``` Defined in: [src/platform/version-extractor.ts:17](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/version-extractor.ts#L17) Operating system name (`'iOS'`, `'Android'`, `'macOS'`, `'Windows'`, `'Linux'`, or `'Unknown'`). ##### osVersion [Section titled “osVersion”](#osversion) ```ts osVersion: string; ``` Defined in: [src/platform/version-extractor.ts:19](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/version-extractor.ts#L19) OS major version as a string (e.g. `'17'` for iOS 17), or `''` when unparseable. *** ### ResponsiveVoiceInitOptions [Section titled “ResponsiveVoiceInitOptions”](#responsivevoiceinitoptions) Defined in: [src/responsivevoice-core.ts:95](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L95) Options accepted by `init()` — the single configuration entry point. #### Properties [Section titled “Properties”](#properties-5) ##### apiBaseUrl? [Section titled “apiBaseUrl?”](#apibaseurl) ```ts optional apiBaseUrl?: string; ``` Defined in: [src/responsivevoice-core.ts:105](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L105) API base URL (defaults to production) ##### apiKey? [Section titled “apiKey?”](#apikey-1) ```ts optional apiKey?: string; ``` Defined in: [src/responsivevoice-core.ts:97](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L97) API key for authentication ##### apiSecret? [Section titled “apiSecret?”](#apisecret) ```ts optional apiSecret?: string; ``` Defined in: [src/responsivevoice-core.ts:103](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L103) Server credential paired with `apiKey`, sent as `X-API-Secret`. Authenticates directly, skipping the origin-bound handshake. Server-to-server only — **not for the browser**, where it would be exposed to every visitor. ##### autoConnect? [Section titled “autoConnect?”](#autoconnect) ```ts optional autoConnect?: boolean; ``` Defined in: [src/responsivevoice-core.ts:159](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L159) Eagerly open the WebSocket connection at init time instead of waiting for the first `speak()` call. Only meaningful when `transport` is `'websocket'`. The connection is opened in the background (non-blocking) and silently retries on failure. ###### Default Value [Section titled “Default Value”](#default-value-3) ```ts false ``` ##### characterLimit? [Section titled “characterLimit?”](#characterlimit) ```ts optional characterLimit?: number; ``` Defined in: [src/responsivevoice-core.ts:137](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L137) Character limit for text chunks ##### defaultParams? [Section titled “defaultParams?”](#defaultparams-1) ```ts optional defaultParams?: Partial; ``` Defined in: [src/responsivevoice-core.ts:109](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L109) Default speech parameters ##### defaultVoice? [Section titled “defaultVoice?”](#defaultvoice-1) ```ts optional defaultVoice?: string; ``` Defined in: [src/responsivevoice-core.ts:107](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L107) Default voice name ##### enableAnalytics? [Section titled “enableAnalytics?”](#enableanalytics) ```ts optional enableAnalytics?: boolean; ``` Defined in: [src/responsivevoice-core.ts:133](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L133) Enable analytics tracking. Analytics reports character usage per session. Disabling this may cause any elevated rate-limit allowance granted to your API key (account) to be revoked. ###### Default Value [Section titled “Default Value”](#default-value-4) ```ts true ``` ##### enableDOMEvents? [Section titled “enableDOMEvents?”](#enabledomevents) ```ts optional enableDOMEvents?: boolean; ``` Defined in: [src/responsivevoice-core.ts:135](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L135) Enable DOM event dispatch ##### enableVoiceReporting? [Section titled “enableVoiceReporting?”](#enablevoicereporting) ```ts optional enableVoiceReporting?: boolean; ``` Defined in: [src/responsivevoice-core.ts:144](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L144) Enable voice reporting for optimized voice matching. Reports browser voices to the API to receive a personalized voice collection optimized for the user's browser/OS combination and subscription tier. ###### Default Value [Section titled “Default Value”](#default-value-5) ```ts true ``` ##### features? [Section titled “features?”](#features-1) ```ts optional features?: Partial<{ accessibilityNavigation: { enabled: boolean; }; exitIntent: { enabled: boolean; text: string | null; }; paragraphNavigation: { enabled: boolean; }; speakEndPage: { enabled: boolean; text: string | null; }; speakInactivity: { enabled: boolean; text: string | null; }; speakLinks: { enabled: boolean; }; speakSelectedText: { enabled: boolean; }; webPlayer: { controls: { brand: boolean; progress: boolean; skip: boolean; speed: boolean; time: boolean; }; enabled: boolean; layout: { display: "inline" | "block"; mode: "fill" | "shrink"; }; miniPlayer: { animation: "none" | "fade" | "slide" | "pop"; enabled: boolean; position: | "top-left" | "top-right" | "bottom-left" | "bottom-right" | { bottom?: string; left?: string; right?: string; top?: string; }; }; navigation: { paragraphClick: boolean; paragraphHighlight: boolean; }; paragraphSelector: string; pitch?: number; position: | "inline" | "before" | "after" | { at: "before" | "after" | "inside"; target: string; }; rate?: number; sanitize: { enabled: boolean; exclude: string[]; }; selector: string; theme: | "neutral" | "responsivevoice" | { accent?: string; accentSoft?: string; bg?: string; border?: string; fg?: string; fill?: string; hover?: string; muted?: string; track?: string; }; voice?: | string | { flags?: string; regex: string; } | { gender?: "male" | "female" | "f" | "m"; isByok?: boolean; lang?: string; name?: string; provider?: string; }; volume?: number; }; welcomeMessage: { enabled: boolean; text: string | null; }; welcomeMessageOnce: boolean; }>; ``` Defined in: [src/responsivevoice-core.ts:179](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L179) Local overrides for dashboard feature flags. Merged over the server- returned config (or defaults in demo mode) before the feature manager activates, so consumers can turn a feature on or tweak its config without a dashboard round-trip — useful for demos, local QA, and scenarios where the page owns the feature configuration. ##### forceFallback? [Section titled “forceFallback?”](#forcefallback) ```ts optional forceFallback?: boolean; ``` Defined in: [src/responsivevoice-core.ts:111](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L111) Force fallback mode (always use HTTP audio) ##### permissionConfig? [Section titled “permissionConfig?”](#permissionconfig-1) ```ts optional permissionConfig?: PermissionConfig; ``` Defined in: [src/responsivevoice-core.ts:123](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L123) Permission configuration ##### prosodyFallback? [Section titled “prosodyFallback?”](#prosodyfallback-1) ```ts optional prosodyFallback?: boolean; ``` Defined in: [src/responsivevoice-core.ts:121](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L121) Apply client-side prosody (pitch/rate/volume) when the server hasn't applied it natively. When `true` (default), `audio.playbackRate` / `audio.volume` are set for any knob the server omitted from the `RV-Prosody-Applied` header. When `false`, the value is silently dropped for unsupported knobs — useful when consumers want strict provider fidelity. ###### Default Value [Section titled “Default Value”](#default-value-6) ```ts true ``` ##### resolveVoice? [Section titled “resolveVoice?”](#resolvevoice) ```ts optional resolveVoice?: ResolveVoiceHook; ``` Defined in: [src/responsivevoice-core.ts:171](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L171) Hook called before each voice resolution to transform the incoming [VoiceSelector](/api/types/src/#voiceselector). Lets integrating apps reroute `speak()` calls without modifying call sites. Runs after the `params.voice` escape-hatch check, so it never fires when a direct `SpeechSynthesisVoice` override is in use. Return `undefined` to fall through to [defaultVoice](/api/core/src/#defaultvoice). ##### transport? [Section titled “transport?”](#transport) ```ts optional transport?: "chunks" | "stream" | "websocket"; ``` Defined in: [src/responsivevoice-core.ts:151](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L151) Audio transport mode for fallback (HTTP) voices. * `'chunks'` (default): full download per text chunk, then play * `'stream'`: HTTP audio streaming with MSE progressive playback * `'websocket'`: persistent WebSocket connection with MSE progressive playback *** ### TextReplacementRule [Section titled “TextReplacementRule”](#textreplacementrule) Defined in: [src/text/replacements.ts:4](https://github.com/responsivevoice/core/blob/v2.0.1/src/text/replacements.ts#L4) Text replacement rule with optional voice filtering #### Properties [Section titled “Properties”](#properties-6) ##### collectionvoices? [Section titled “collectionvoices?”](#collectionvoices) ```ts optional collectionvoices?: string | string[]; ``` Defined in: [src/text/replacements.ts:10](https://github.com/responsivevoice/core/blob/v2.0.1/src/text/replacements.ts#L10) Optional: Apply only for these collection voice names ##### newvalue [Section titled “newvalue”](#newvalue) ```ts newvalue: string; ``` Defined in: [src/text/replacements.ts:8](https://github.com/responsivevoice/core/blob/v2.0.1/src/text/replacements.ts#L8) Replacement text ##### searchvalue [Section titled “searchvalue”](#searchvalue) ```ts searchvalue: string | RegExp; ``` Defined in: [src/text/replacements.ts:6](https://github.com/responsivevoice/core/blob/v2.0.1/src/text/replacements.ts#L6) String pattern or RegExp to match. Strings support /pattern/flags format ##### systemvoices? [Section titled “systemvoices?”](#systemvoices) ```ts optional systemvoices?: string | string[]; ``` Defined in: [src/text/replacements.ts:12](https://github.com/responsivevoice/core/blob/v2.0.1/src/text/replacements.ts#L12) Optional: Apply only for these system voice names ## Type Aliases [Section titled “Type Aliases”](#type-aliases) ### CacheScope [Section titled “CacheScope”](#cachescope) ```ts type CacheScope = "all" | "voices" | "server" | "config"; ``` Defined in: [src/debug-tools.ts:25](https://github.com/responsivevoice/core/blob/v2.0.1/src/debug-tools.ts#L25) Which persistent cache to clear. * `'voices'` — voice collection + ETag + browser voice hash * `'server'` — assigned TTS server URL * `'config'` — website config payload * `'all'` — all of the above (default) *** ### ResolveVoiceHook [Section titled “ResolveVoiceHook”](#resolvevoicehook) ```ts type ResolveVoiceHook = (selector) => VoiceSelector | undefined; ``` Defined in: [src/responsivevoice-core.ts:90](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice-core.ts#L90) A hook that intercepts and optionally transforms the voice selector before the resolution chain runs. Called once per `speak()` call (never when `params.voice` is set). #### Parameters [Section titled “Parameters”](#parameters-31) | Parameter | Type | Description | | ---------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `selector` | [`VoiceSelector`](/api/types/src/#voiceselector) \| `undefined` | The incoming selector, or `undefined` when no voice was specified (i.e. the default voice would be used). | #### Returns [Section titled “Returns”](#returns-72) [`VoiceSelector`](/api/types/src/#voiceselector) | `undefined` A transformed selector, or `undefined` to fall through to the configured [defaultVoice](/api/core/src/#defaultvoice). ## Functions [Section titled “Functions”](#functions) ### detectPlatform() [Section titled “detectPlatform()”](#detectplatform) ```ts function detectPlatform(): PlatformInfo; ``` Defined in: [src/platform/detector.ts:102](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/detector.ts#L102) Detect the current runtime's platform capabilities. Combines user-agent parsing (browser, OS, iOS version) with feature detection (Web Speech, Audio element, sendBeacon). Falls back to a server-side profile when `window`/`navigator` are absent (SSR). #### Returns [Section titled “Returns”](#returns-73) [`PlatformInfo`](/api/core/src/#platforminfo) *** ### extractPlatformVersionInfo() [Section titled “extractPlatformVersionInfo()”](#extractplatformversioninfo) ```ts function extractPlatformVersionInfo(platformInfo): PlatformVersionInfo; ``` Defined in: [src/platform/version-extractor.ts:152](https://github.com/responsivevoice/core/blob/v2.0.1/src/platform/version-extractor.ts#L152) Extract platform version information for voice reporting #### Parameters [Section titled “Parameters”](#parameters-32) | Parameter | Type | Description | | -------------- | --------------------------------------------- | --------------------------- | | `platformInfo` | [`PlatformInfo`](/api/core/src/#platforminfo) | Platform info from detector | #### Returns [Section titled “Returns”](#returns-74) [`PlatformVersionInfo`](/api/core/src/#platformversioninfo) Platform version information suitable for voice reporting *** ### getResponsiveVoice() [Section titled “getResponsiveVoice()”](#getresponsivevoice) ```ts function getResponsiveVoice(options?): Promise; ``` Defined in: [src/responsivevoice.ts:564](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L564) Get or create the global ResponsiveVoice instance. For ESM consumers, this is the recommended entry point: ```typescript const rv = await getResponsiveVoice({ apiKey: 'your-key' }); rv.speak('Hello'); ``` #### Parameters [Section titled “Parameters”](#parameters-33) | Parameter | Type | Description | | ---------- | ------------------------------------------------------------------------- | ---------------------------------------------------- | | `options?` | [`ResponsiveVoiceInitOptions`](/api/core/src/#responsivevoiceinitoptions) | Init options (apiKey, voice defaults, feature flags) | #### Returns [Section titled “Returns”](#returns-75) `Promise`\<[`ResponsiveVoice`](/api/core/src/#responsivevoice)> Promise that resolves to the initialized ResponsiveVoice instance *** ### resetResponsiveVoice() [Section titled “resetResponsiveVoice()”](#resetresponsivevoice) ```ts function resetResponsiveVoice(): void; ``` Defined in: [src/responsivevoice.ts:580](https://github.com/responsivevoice/core/blob/v2.0.1/src/responsivevoice.ts#L580) Reset the global instance (for testing) #### Returns [Section titled “Returns”](#returns-76) `void` ## References [Section titled “References”](#references) ### default [Section titled “default”](#default) Renames and re-exports [getResponsiveVoice](/api/core/src/#getresponsivevoice) *** ### VoiceSelector [Section titled “VoiceSelector”](#voiceselector) Re-exports [VoiceSelector](/api/types/src/#voiceselector) # @responsivevoice/text > API documentation for @responsivevoice/text Text processing utilities for text-to-speech: intelligent chunking with CJK support, speech-duration estimation, and fast hashing for cache keys. Consumed by `@responsivevoice/core`, `@responsivevoice/api-client`, and `services/tts-api`. ## Interfaces [Section titled “Interfaces”](#interfaces) ### ChunkerOptions [Section titled “ChunkerOptions”](#chunkeroptions) Defined in: [src/chunker.ts:45](https://github.com/responsivevoice/text/blob/v2.0.0/src/chunker.ts#L45) Options for text chunking #### Properties [Section titled “Properties”](#properties) ##### characterLimit? [Section titled “characterLimit?”](#characterlimit) ```ts optional characterLimit?: number; ``` Defined in: [src/chunker.ts:47](https://github.com/responsivevoice/text/blob/v2.0.0/src/chunker.ts#L47) Maximum characters per chunk (default: 100, clamped: 50-300) ##### preserveSentences? [Section titled “preserveSentences?”](#preservesentences) ```ts optional preserveSentences?: boolean; ``` Defined in: [src/chunker.ts:57](https://github.com/responsivevoice/text/blob/v2.0.0/src/chunker.ts#L57) Whether to prioritize sentence boundaries over character limit *** ### TextChunk [Section titled “TextChunk”](#textchunk) Defined in: [src/chunker.ts:31](https://github.com/responsivevoice/text/blob/v2.0.0/src/chunker.ts#L31) Represents a single chunk of text #### Properties [Section titled “Properties”](#properties-1) ##### index [Section titled “index”](#index) ```ts index: number; ``` Defined in: [src/chunker.ts:35](https://github.com/responsivevoice/text/blob/v2.0.0/src/chunker.ts#L35) Zero-based index of this chunk ##### isLast [Section titled “isLast”](#islast) ```ts isLast: boolean; ``` Defined in: [src/chunker.ts:39](https://github.com/responsivevoice/text/blob/v2.0.0/src/chunker.ts#L39) Whether this is the last chunk ##### text [Section titled “text”](#text) ```ts text: string; ``` Defined in: [src/chunker.ts:33](https://github.com/responsivevoice/text/blob/v2.0.0/src/chunker.ts#L33) The text content of the chunk ##### total [Section titled “total”](#total) ```ts total: number; ``` Defined in: [src/chunker.ts:37](https://github.com/responsivevoice/text/blob/v2.0.0/src/chunker.ts#L37) Total number of chunks ## Variables [Section titled “Variables”](#variables) ### BASE\_TIMEOUT\_FALLBACK [Section titled “BASE\_TIMEOUT\_FALLBACK”](#base_timeout_fallback) ```ts const BASE_TIMEOUT_FALLBACK: 1300 = 1300; ``` Defined in: [src/config.ts:46](https://github.com/responsivevoice/text/blob/v2.0.0/src/config.ts#L46) Base timeout in ms for fallback (HTTP audio) short-text estimation. Higher than native to account for network latency. *** ### BASE\_TIMEOUT\_NATIVE [Section titled “BASE\_TIMEOUT\_NATIVE”](#base_timeout_native) ```ts const BASE_TIMEOUT_NATIVE: 700 = 700; ``` Defined in: [src/config.ts:40](https://github.com/responsivevoice/text/blob/v2.0.0/src/config.ts#L40) Base timeout in ms for native TTS (Web Speech API) short-text estimation *** ### DEFAULT\_CHARACTER\_LIMIT [Section titled “DEFAULT\_CHARACTER\_LIMIT”](#default_character_limit) ```ts const DEFAULT_CHARACTER_LIMIT: 100 = 100; ``` Defined in: [src/config.ts:9](https://github.com/responsivevoice/text/blob/v2.0.0/src/config.ts#L9) Default character limit for text chunking Text longer than this will be split into multiple utterances *** ### MAX\_CHARACTER\_LIMIT [Section titled “MAX\_CHARACTER\_LIMIT”](#max_character_limit) ```ts const MAX_CHARACTER_LIMIT: 300 = 300; ``` Defined in: [src/config.ts:14](https://github.com/responsivevoice/text/blob/v2.0.0/src/config.ts#L14) Maximum allowed character limit *** ### MIN\_CHARACTER\_LIMIT [Section titled “MIN\_CHARACTER\_LIMIT”](#min_character_limit) ```ts const MIN_CHARACTER_LIMIT: 50 = 50; ``` Defined in: [src/config.ts:19](https://github.com/responsivevoice/text/blob/v2.0.0/src/config.ts#L19) Minimum character limit *** ### WORDS\_PER\_MINUTE [Section titled “WORDS\_PER\_MINUTE”](#words_per_minute) ```ts const WORDS_PER_MINUTE: 130 = 130; ``` Defined in: [src/config.ts:35](https://github.com/responsivevoice/text/blob/v2.0.0/src/config.ts#L35) Estimated words per minute for duration calculations ## Functions [Section titled “Functions”](#functions) ### chunkText() [Section titled “chunkText()”](#chunktext) ```ts function chunkText(text, options?): TextChunk[]; ``` Defined in: [src/chunker.ts:351](https://github.com/responsivevoice/text/blob/v2.0.0/src/chunker.ts#L351) Splits text into chunks for speech synthesis #### Parameters [Section titled “Parameters”](#parameters) | Parameter | Type | Description | | --------- | ------------------------------------------------- | ----------------- | | `text` | `string` | The text to chunk | | `options` | [`ChunkerOptions`](/api/text/src/#chunkeroptions) | Chunking options | #### Returns [Section titled “Returns”](#returns) [`TextChunk`](/api/text/src/#textchunk)\[] Array of text chunks with metadata #### Example [Section titled “Example”](#example) ```typescript const chunks = chunkText('Hello world. How are you today?', { characterLimit: 20 }); // Returns: // [ // { text: 'Hello world.', index: 0, total: 2, isLast: false }, // { text: 'How are you today?', index: 1, total: 2, isLast: true } // ] ``` *** ### createTextChunker() [Section titled “createTextChunker()”](#createtextchunker) ```ts function createTextChunker(defaultOptions?): (text, options?) => TextChunk[]; ``` Defined in: [src/chunker.ts:418](https://github.com/responsivevoice/text/blob/v2.0.0/src/chunker.ts#L418) Creates a text chunker instance with preset options #### Parameters [Section titled “Parameters”](#parameters-1) | Parameter | Type | Description | | ---------------- | ------------------------------------------------- | ---------------------------------------- | | `defaultOptions` | [`ChunkerOptions`](/api/text/src/#chunkeroptions) | Default options for all chunk operations | #### Returns [Section titled “Returns”](#returns-1) A chunker function with the preset options (`text`, `options?`) => [`TextChunk`](/api/text/src/#textchunk)\[] #### Example [Section titled “Example”](#example-1) ```typescript const chunker = createTextChunker({ characterLimit: 150 }); const chunks = chunker('Long text here...'); ``` *** ### djb2Hash() [Section titled “djb2Hash()”](#djb2hash) ```ts function djb2Hash(str): string; ``` Defined in: [src/hash.ts:5](https://github.com/responsivevoice/text/blob/v2.0.0/src/hash.ts#L5) DJB2 hash function — fast, non-cryptographic string hash. Used for scoping storage keys to API keys and for browser voice fingerprinting. #### Parameters [Section titled “Parameters”](#parameters-2) | Parameter | Type | | --------- | -------- | | `str` | `string` | #### Returns [Section titled “Returns”](#returns-2) `string` *** ### getEstimatedTimeLength() [Section titled “getEstimatedTimeLength()”](#getestimatedtimelength) ```ts function getEstimatedTimeLength( text, multiplier?, options?): number; ``` Defined in: [src/duration.ts:55](https://github.com/responsivevoice/text/blob/v2.0.0/src/duration.ts#L55) Estimate the speech duration for a given text Uses different formulas based on text length: * Short text (fewer than 5 words): character-based formula with a configurable base timeout. * Normal text: words-per-minute calculation (130 WPM). Text is preprocessed (currency/number expansion) before word counting so estimates match what TTS engines actually speak. #### Parameters [Section titled “Parameters”](#parameters-3) | Parameter | Type | Default value | Description | | ---------------------- | ----------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | `string` | `undefined` | The text to estimate duration for | | `multiplier` | `number` | `1` | Optional multiplier for the duration (default: 1) | | `options?` | { `baseTimeout?`: `number`; } | `undefined` | Optional configuration. `options.baseTimeout` is the base timeout in ms for short text (default: 700 for native TTS, use 1300 for fallback/HTTP audio). | | `options.baseTimeout?` | `number` | `undefined` | - | #### Returns [Section titled “Returns”](#returns-3) `number` Estimated duration in milliseconds #### Example [Section titled “Example”](#example-2) ```typescript // Estimate duration for a sentence const duration = getEstimatedTimeLength("Hello, how are you today?"); // With a multiplier (e.g., for slower speech rate) const slowerDuration = getEstimatedTimeLength("Hello world", 1.5); // For fallback engine (HTTP audio) - uses higher base timeout const fallbackDuration = getEstimatedTimeLength("Hi", 1, { baseTimeout: 1300 }); ``` *** ### getEstimatedTimeLengthWithRate() [Section titled “getEstimatedTimeLengthWithRate()”](#getestimatedtimelengthwithrate) ```ts function getEstimatedTimeLengthWithRate(text, rate?): number; ``` Defined in: [src/duration.ts:107](https://github.com/responsivevoice/text/blob/v2.0.0/src/duration.ts#L107) Estimate speech duration with rate adjustment #### Parameters [Section titled “Parameters”](#parameters-4) | Parameter | Type | Default value | Description | | --------- | -------- | ------------- | ------------------------------------------ | | `text` | `string` | `undefined` | The text to estimate duration for | | `rate` | `number` | `1` | Speech rate (0.1 to 10, where 1 is normal) | #### Returns [Section titled “Returns”](#returns-4) `number` Estimated duration in milliseconds *** ### hasCJKContent() [Section titled “hasCJKContent()”](#hascjkcontent) ```ts function hasCJKContent(text): boolean; ``` Defined in: [src/chunker.ts:137](https://github.com/responsivevoice/text/blob/v2.0.0/src/chunker.ts#L137) Checks if text contains any CJK ideographic characters. Exported for use in voice-aware character limit computation (e.g. reducing the limit for Google remote voices with CJK content). #### Parameters [Section titled “Parameters”](#parameters-5) | Parameter | Type | | --------- | -------- | | `text` | `string` | #### Returns [Section titled “Returns”](#returns-5) `boolean` # @responsivevoice/types > API documentation for @responsivevoice/types Shared TypeScript types, Zod schemas, and runtime type guards used across the `@responsivevoice/*` packages. The Zod schemas are the single source of truth for runtime validation; TypeScript types are inferred via `z.infer<>`. ## Type Aliases [Section titled “Type Aliases”](#type-aliases) ### AudioFormat [Section titled “AudioFormat”](#audioformat) ```ts type AudioFormat = z.infer; ``` Defined in: [src/schemas/core.ts:69](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L69) Inferred from [AudioFormatSchema](/api/types/src/#audioformatschema). *** ### AudioResponse [Section titled “AudioResponse”](#audioresponse) ```ts type AudioResponse = z.infer; ``` Defined in: [src/schemas/synthesis.ts:146](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L146) Inferred from [AudioResponseSchema](/api/types/src/#audioresponseschema). *** ### AuthToken [Section titled “AuthToken”](#authtoken) ```ts type AuthToken = z.infer; ``` Defined in: [src/schemas/website.ts:361](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L361) Inferred from [AuthTokenSchema](/api/types/src/#authtokenschema). *** ### BrowserVoiceInfo [Section titled “BrowserVoiceInfo”](#browservoiceinfo) ```ts type BrowserVoiceInfo = z.infer; ``` Defined in: [src/schemas/responses.ts:43](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L43) Inferred from [BrowserVoiceInfoSchema](/api/types/src/#browservoiceinfoschema). *** ### ByLanguageLinks [Section titled “ByLanguageLinks”](#bylanguagelinks) ```ts type ByLanguageLinks = z.infer; ``` Defined in: [src/schemas/responses.ts:244](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L244) Inferred from [ByLanguageLinksSchema](/api/types/src/#bylanguagelinksschema). *** ### CollectionLinks [Section titled “CollectionLinks”](#collectionlinks) ```ts type CollectionLinks = z.infer; ``` Defined in: [src/schemas/responses.ts:231](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L231) Inferred from [CollectionLinksSchema](/api/types/src/#collectionlinksschema). *** ### DeviceType [Section titled “DeviceType”](#devicetype) ```ts type DeviceType = z.infer; ``` Defined in: [src/schemas/responses.ts:18](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L18) Inferred from [DeviceTypeSchema](/api/types/src/#devicetypeschema). *** ### ErrorResponse [Section titled “ErrorResponse”](#errorresponse) ```ts type ErrorResponse = z.infer; ``` Defined in: [src/schemas/responses.ts:133](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L133) Inferred from [ErrorResponseSchema](/api/types/src/#errorresponseschema). *** ### HrefLink [Section titled “HrefLink”](#hreflink) ```ts type HrefLink = z.infer; ``` Defined in: [src/schemas/responses.ts:146](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L146) Inferred from [HrefLinkSchema](/api/types/src/#hreflinkschema). *** ### MiniPlayer [Section titled “MiniPlayer”](#miniplayer) ```ts type MiniPlayer = z.infer; ``` Defined in: [src/schemas/website.ts:170](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L170) Inferred from [MiniPlayerSchema](/api/types/src/#miniplayerschema). *** ### MiniPlayerCorner [Section titled “MiniPlayerCorner”](#miniplayercorner) ```ts type MiniPlayerCorner = z.infer; ``` Defined in: [src/schemas/website.ts:122](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L122) Inferred from [MiniPlayerCornerSchema](/api/types/src/#miniplayercornerschema). *** ### MiniPlayerOffset [Section titled “MiniPlayerOffset”](#miniplayeroffset) ```ts type MiniPlayerOffset = z.infer; ``` Defined in: [src/schemas/website.ts:151](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L151) Inferred from [MiniPlayerOffsetSchema](/api/types/src/#miniplayeroffsetschema). *** ### PlatformReport [Section titled “PlatformReport”](#platformreport) ```ts type PlatformReport = z.infer; ``` Defined in: [src/schemas/responses.ts:67](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L67) Inferred from [PlatformReportSchema](/api/types/src/#platformreportschema). *** ### ProsodyKnob [Section titled “ProsodyKnob”](#prosodyknob) ```ts type ProsodyKnob = typeof PROSODY_KNOBS[number]; ``` Defined in: [src/schemas/prosody.ts:15](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/prosody.ts#L15) Inferred union from [PROSODY\_KNOBS](/api/types/src/#prosody_knobs). *** ### RegexSelector [Section titled “RegexSelector”](#regexselector) ```ts type RegexSelector = z.infer; ``` Defined in: [src/schemas/voice-query.ts:58](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/voice-query.ts#L58) Inferred from [RegexSelectorSchema](/api/types/src/#regexselectorschema). *** ### ResponsiveVoiceConfig [Section titled “ResponsiveVoiceConfig”](#responsivevoiceconfig) ```ts type ResponsiveVoiceConfig = z.infer; ``` Defined in: [src/schemas/synthesis.ts:190](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L190) Inferred from [ResponsiveVoiceConfigSchema](/api/types/src/#responsivevoiceconfigschema). *** ### RVErrorEvent [Section titled “RVErrorEvent”](#rverrorevent) ```ts type RVErrorEvent = z.infer; ``` Defined in: [src/schemas/events.ts:46](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/events.ts#L46) Inferred from [RVErrorEventSchema](/api/types/src/#rverroreventschema). *** ### RVEvent [Section titled “RVEvent”](#rvevent) ```ts type RVEvent = z.infer; ``` Defined in: [src/schemas/events.ts:21](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/events.ts#L21) Inferred from [RVEventSchema](/api/types/src/#rveventschema). *** ### RVEventCallback [Section titled “RVEventCallback”](#rveventcallback) ```ts type RVEventCallback = (event) => void; ``` Defined in: [src/schemas/events.ts:31](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/events.ts#L31) Listener invoked by `ResponsiveVoice` for each dispatched [RVEvent](/api/types/src/#rvevent). #### Parameters [Section titled “Parameters”](#parameters) | Parameter | Type | | --------- | ------------------------------------ | | `event` | [`RVEvent`](/api/types/src/#rvevent) | #### Returns [Section titled “Returns”](#returns) `void` *** ### RVEventType [Section titled “RVEventType”](#rveventtype) ```ts type RVEventType = z.infer; ``` Defined in: [src/schemas/core.ts:142](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L142) Inferred from [RVEventTypeSchema](/api/types/src/#rveventtypeschema). *** ### RVServiceSwitchedEvent [Section titled “RVServiceSwitchedEvent”](#rvserviceswitchedevent) ```ts type RVServiceSwitchedEvent = z.infer; ``` Defined in: [src/schemas/events.ts:68](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/events.ts#L68) Inferred from [RVServiceSwitchedEventSchema](/api/types/src/#rvserviceswitchedeventschema). *** ### ServiceOrNative [Section titled “ServiceOrNative”](#serviceornative) ```ts type ServiceOrNative = z.infer; ``` Defined in: [src/schemas/events.ts:53](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/events.ts#L53) Inferred from [ServiceOrNativeSchema](/api/types/src/#serviceornativeschema). *** ### SpeakParams [Section titled “SpeakParams”](#speakparams) ```ts type SpeakParams = { onboundary?: (charIndex, name) => void; onend?: () => void; onerror?: (error) => void; onstart?: () => void; pitch?: number; prosodyFallback?: boolean; rate?: number; volume?: number; }; ``` Defined in: [src/schemas/synthesis.ts:219](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L219) Parameters accepted by `ResponsiveVoice.speak()`. Controls pitch, rate, volume, and the speech lifecycle event callbacks (`onstart`, `onend`, `onerror`, `onvoiceschanged`, `onboundary`). Defined as a hand-authored TypeScript type rather than `z.infer<>` so callback signatures stay precise. #### Properties [Section titled “Properties”](#properties) ##### onboundary? [Section titled “onboundary?”](#onboundary) ```ts optional onboundary?: (charIndex, name) => void; ``` Defined in: [src/schemas/synthesis.ts:234](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L234) Called when speech crosses a word or sentence boundary ###### Parameters [Section titled “Parameters”](#parameters-1) | Parameter | Type | Description | | ----------- | -------- | --------------------------------------- | | `charIndex` | `number` | Character index in the original text | | `name` | `string` | Type of boundary ('word' or 'sentence') | ###### Returns [Section titled “Returns”](#returns-1) `void` ###### Remarks [Section titled “Remarks”](#remarks) Only supported by native Web Speech API engine, not fallback audio engine ##### onend? [Section titled “onend?”](#onend) ```ts optional onend?: () => void; ``` Defined in: [src/schemas/synthesis.ts:226](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L226) ###### Returns [Section titled “Returns”](#returns-2) `void` ##### onerror? [Section titled “onerror?”](#onerror) ```ts optional onerror?: (error) => void; ``` Defined in: [src/schemas/synthesis.ts:227](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L227) ###### Parameters [Section titled “Parameters”](#parameters-2) | Parameter | Type | | --------- | ------- | | `error` | `Error` | ###### Returns [Section titled “Returns”](#returns-3) `void` ##### onstart? [Section titled “onstart?”](#onstart) ```ts optional onstart?: () => void; ``` Defined in: [src/schemas/synthesis.ts:225](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L225) ###### Returns [Section titled “Returns”](#returns-4) `void` ##### pitch? [Section titled “pitch?”](#pitch) ```ts optional pitch?: number; ``` Defined in: [src/schemas/synthesis.ts:220](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L220) ##### prosodyFallback? [Section titled “prosodyFallback?”](#prosodyfallback) ```ts optional prosodyFallback?: boolean; ``` Defined in: [src/schemas/synthesis.ts:224](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L224) Per-call override for client-side prosody fallback. See [ResponsiveVoiceConfigSchema](/api/types/src/#responsivevoiceconfigschema) for the default. ##### rate? [Section titled “rate?”](#rate) ```ts optional rate?: number; ``` Defined in: [src/schemas/synthesis.ts:221](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L221) ##### volume? [Section titled “volume?”](#volume) ```ts optional volume?: number; ``` Defined in: [src/schemas/synthesis.ts:222](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L222) *** ### SpeechParams [Section titled “SpeechParams”](#speechparams) ```ts type SpeechParams = z.infer; ``` Defined in: [src/schemas/synthesis.ts:50](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L50) Inferred from [SpeechParamsSchema](/api/types/src/#speechparamsschema). *** ### StreamAudioChunk [Section titled “StreamAudioChunk”](#streamaudiochunk) ```ts type StreamAudioChunk = z.infer; ``` Defined in: [src/schemas/streaming.ts:39](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/streaming.ts#L39) Inferred from [StreamAudioChunkSchema](/api/types/src/#streamaudiochunkschema). *** ### StreamChunk [Section titled “StreamChunk”](#streamchunk) ```ts type StreamChunk = | StreamMetadata | StreamAudioChunk | StreamEnd | StreamError; ``` Defined in: [src/schemas/streaming.ts:70](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/streaming.ts#L70) Union of all streaming chunk types *** ### StreamEnd [Section titled “StreamEnd”](#streamend) ```ts type StreamEnd = z.infer; ``` Defined in: [src/schemas/streaming.ts:52](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/streaming.ts#L52) Inferred from [StreamEndSchema](/api/types/src/#streamendschema). *** ### StreamError [Section titled “StreamError”](#streamerror) ```ts type StreamError = z.infer; ``` Defined in: [src/schemas/streaming.ts:65](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/streaming.ts#L65) Inferred from [StreamErrorSchema](/api/types/src/#streamerrorschema). *** ### StreamingTransportMode [Section titled “StreamingTransportMode”](#streamingtransportmode) ```ts type StreamingTransportMode = z.infer; ``` Defined in: [src/schemas/core.ts:173](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L173) Inferred from [StreamingTransportModeSchema](/api/types/src/#streamingtransportmodeschema). *** ### StreamMetadata [Section titled “StreamMetadata”](#streammetadata) ```ts type StreamMetadata = z.infer; ``` Defined in: [src/schemas/streaming.ts:26](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/streaming.ts#L26) Inferred from [StreamMetadataSchema](/api/types/src/#streammetadataschema). *** ### StreamWebsocketLink [Section titled “StreamWebsocketLink”](#streamwebsocketlink) ```ts type StreamWebsocketLink = z.infer; ``` Defined in: [src/schemas/responses.ts:193](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L193) Inferred from [StreamWebsocketLinkSchema](/api/types/src/#streamwebsocketlinkschema). *** ### SynthesizeLink [Section titled “SynthesizeLink”](#synthesizelink) ```ts type SynthesizeLink = z.infer; ``` Defined in: [src/schemas/responses.ts:157](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L157) Inferred from [SynthesizeLinkSchema](/api/types/src/#synthesizelinkschema). *** ### SynthesizeRequest [Section titled “SynthesizeRequest”](#synthesizerequest) ```ts type SynthesizeRequest = z.infer; ``` Defined in: [src/schemas/synthesis.ts:99](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L99) Inferred from [SynthesizeRequestSchema](/api/types/src/#synthesizerequestschema). *** ### SynthesizeResponse [Section titled “SynthesizeResponse”](#synthesizeresponse) ```ts type SynthesizeResponse = z.infer; ``` Defined in: [src/schemas/synthesis.ts:118](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L118) Inferred from [SynthesizeResponseSchema](/api/types/src/#synthesizeresponseschema). *** ### SynthesizeStreamLink [Section titled “SynthesizeStreamLink”](#synthesizestreamlink) ```ts type SynthesizeStreamLink = z.infer; ``` Defined in: [src/schemas/responses.ts:177](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L177) Inferred from [SynthesizeStreamLinkSchema](/api/types/src/#synthesizestreamlinkschema). *** ### SystemVoice [Section titled “SystemVoice”](#systemvoice) ```ts type SystemVoice = z.infer; ``` Defined in: [src/schemas/voice.ts:91](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/voice.ts#L91) Inferred from [SystemVoiceSchema](/api/types/src/#systemvoiceschema). *** ### TextFeature [Section titled “TextFeature”](#textfeature) ```ts type TextFeature = z.infer; ``` Defined in: [src/schemas/website.ts:29](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L29) Inferred from [TextFeatureSchema](/api/types/src/#textfeatureschema). *** ### ToggleFeature [Section titled “ToggleFeature”](#togglefeature) ```ts type ToggleFeature = z.infer; ``` Defined in: [src/schemas/website.ts:36](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L36) Inferred from [ToggleFeatureSchema](/api/types/src/#togglefeatureschema). *** ### TransportMode [Section titled “TransportMode”](#transportmode) ```ts type TransportMode = z.infer; ``` Defined in: [src/schemas/core.ts:162](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L162) Inferred from [TransportModeSchema](/api/types/src/#transportmodeschema). *** ### TTSService [Section titled “TTSService”](#ttsservice) ```ts type TTSService = z.infer; ``` Defined in: [src/schemas/core.ts:56](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L56) Inferred from [TTSServiceSchema](/api/types/src/#ttsserviceschema). *** ### Voice [Section titled “Voice”](#voice) ```ts type Voice = z.infer; ``` Defined in: [src/schemas/voice.ts:45](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/voice.ts#L45) Inferred from [VoiceSchema](/api/types/src/#voiceschema). *** ### VoiceCollection [Section titled “VoiceCollection”](#voicecollection) ```ts type VoiceCollection = z.infer; ``` Defined in: [src/schemas/voice.ts:112](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/voice.ts#L112) Inferred from [VoiceCollectionSchema](/api/types/src/#voicecollectionschema). *** ### VoiceDetailLinks [Section titled “VoiceDetailLinks”](#voicedetaillinks) ```ts type VoiceDetailLinks = z.infer; ``` Defined in: [src/schemas/responses.ts:219](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L219) Inferred from [VoiceDetailLinksSchema](/api/types/src/#voicedetaillinksschema). *** ### VoiceDetailResponse [Section titled “VoiceDetailResponse”](#voicedetailresponse) ```ts type VoiceDetailResponse = z.infer; ``` Defined in: [src/schemas/responses.ts:302](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L302) Inferred from [VoiceDetailResponseSchema](/api/types/src/#voicedetailresponseschema). *** ### VoiceGender [Section titled “VoiceGender”](#voicegender) ```ts type VoiceGender = z.infer; ``` Defined in: [src/schemas/core.ts:26](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L26) Inferred from [VoiceGenderSchema](/api/types/src/#voicegenderschema). *** ### VoiceGenderShort [Section titled “VoiceGenderShort”](#voicegendershort) ```ts type VoiceGenderShort = z.infer; ``` Defined in: [src/schemas/core.ts:36](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L36) Inferred from [VoiceGenderShortSchema](/api/types/src/#voicegendershortschema). *** ### VoiceLinks [Section titled “VoiceLinks”](#voicelinks) ```ts type VoiceLinks = z.infer; ``` Defined in: [src/schemas/responses.ts:205](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L205) Inferred from [VoiceLinksSchema](/api/types/src/#voicelinksschema). *** ### VoiceQuery [Section titled “VoiceQuery”](#voicequery) ```ts type VoiceQuery = z.infer; ``` Defined in: [src/schemas/voice-query.ts:44](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/voice-query.ts#L44) Inferred from [VoiceQuerySchema](/api/types/src/#voicequeryschema). *** ### VoiceReportRequest [Section titled “VoiceReportRequest”](#voicereportrequest) ```ts type VoiceReportRequest = z.infer; ``` Defined in: [src/schemas/responses.ts:88](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L88) Inferred from [VoiceReportRequestSchema](/api/types/src/#voicereportrequestschema). *** ### VoiceReportResponse [Section titled “VoiceReportResponse”](#voicereportresponse) ```ts type VoiceReportResponse = z.infer; ``` Defined in: [src/schemas/responses.ts:106](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L106) Inferred from [VoiceReportResponseSchema](/api/types/src/#voicereportresponseschema). *** ### VoicesByLanguageResponse [Section titled “VoicesByLanguageResponse”](#voicesbylanguageresponse) ```ts type VoicesByLanguageResponse = z.infer; ``` Defined in: [src/schemas/responses.ts:289](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L289) Inferred from [VoicesByLanguageResponseSchema](/api/types/src/#voicesbylanguageresponseschema). *** ### VoiceSelector [Section titled “VoiceSelector”](#voiceselector) ```ts type VoiceSelector = z.infer; ``` Defined in: [src/schemas/voice-query.ts:81](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/voice-query.ts#L81) Post-parse output — what consumers (resolvers, server responses) see. *** ### VoiceSelectorInput [Section titled “VoiceSelectorInput”](#voiceselectorinput) ```ts type VoiceSelectorInput = | string | RegExp | RegexSelector | VoiceQuery; ``` Defined in: [src/schemas/voice-query.ts:86](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/voice-query.ts#L86) Input form callers may write. JS callers can pass a real `RegExp` as sugar for [RegexSelector](/api/types/src/#regexselector); the schema normalizes it on parse. *** ### VoicesListResponse [Section titled “VoicesListResponse”](#voiceslistresponse) ```ts type VoicesListResponse = z.infer; ``` Defined in: [src/schemas/responses.ts:274](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L274) Inferred from [VoicesListResponseSchema](/api/types/src/#voiceslistresponseschema). *** ### VoiceWithLinks [Section titled “VoiceWithLinks”](#voicewithlinks) ```ts type VoiceWithLinks = z.infer; ``` Defined in: [src/schemas/responses.ts:254](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L254) Inferred from [VoiceWithLinksSchema](/api/types/src/#voicewithlinksschema). *** ### WebPlayerControls [Section titled “WebPlayerControls”](#webplayercontrols) ```ts type WebPlayerControls = z.infer; ``` Defined in: [src/schemas/website.ts:96](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L96) Inferred from [WebPlayerControlsSchema](/api/types/src/#webplayercontrolsschema). *** ### WebPlayerFeature [Section titled “WebPlayerFeature”](#webplayerfeature) ```ts type WebPlayerFeature = z.infer; ``` Defined in: [src/schemas/website.ts:266](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L266) Inferred from [WebPlayerFeatureSchema](/api/types/src/#webplayerfeatureschema). *** ### WebPlayerLayout [Section titled “WebPlayerLayout”](#webplayerlayout) ```ts type WebPlayerLayout = z.infer; ``` Defined in: [src/schemas/website.ts:185](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L185) Inferred from [WebPlayerLayoutSchema](/api/types/src/#webplayerlayoutschema). *** ### WebPlayerNavigation [Section titled “WebPlayerNavigation”](#webplayernavigation) ```ts type WebPlayerNavigation = z.infer; ``` Defined in: [src/schemas/website.ts:112](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L112) Inferred from [WebPlayerNavigationSchema](/api/types/src/#webplayernavigationschema). *** ### WebPlayerSanitize [Section titled “WebPlayerSanitize”](#webplayersanitize) ```ts type WebPlayerSanitize = z.infer; ``` Defined in: [src/schemas/website.ts:199](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L199) Inferred from [WebPlayerSanitizeSchema](/api/types/src/#webplayersanitizeschema). *** ### WebPlayerTheme [Section titled “WebPlayerTheme”](#webplayertheme) ```ts type WebPlayerTheme = z.infer; ``` Defined in: [src/schemas/website.ts:75](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L75) Inferred from [WebPlayerThemeSchema](/api/types/src/#webplayerthemeschema). *** ### WebPlayerThemeTokens [Section titled “WebPlayerThemeTokens”](#webplayerthemetokens) ```ts type WebPlayerThemeTokens = z.infer; ``` Defined in: [src/schemas/website.ts:64](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L64) Inferred from [WebPlayerThemeTokensSchema](/api/types/src/#webplayerthemetokensschema). *** ### WebsiteAnalytics [Section titled “WebsiteAnalytics”](#websiteanalytics) ```ts type WebsiteAnalytics = z.infer; ``` Defined in: [src/schemas/website.ts:346](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L346) Inferred from [WebsiteAnalyticsSchema](/api/types/src/#websiteanalyticsschema). *** ### WebsiteConfigResponse [Section titled “WebsiteConfigResponse”](#websiteconfigresponse) ```ts type WebsiteConfigResponse = z.infer; ``` Defined in: [src/schemas/website.ts:380](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L380) Inferred from [WebsiteConfigResponseSchema](/api/types/src/#websiteconfigresponseschema). *** ### WebsiteFeatures [Section titled “WebsiteFeatures”](#websitefeatures) ```ts type WebsiteFeatures = z.infer; ``` Defined in: [src/schemas/website.ts:325](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L325) Inferred from [WebsiteFeaturesSchema](/api/types/src/#websitefeaturesschema). *** ### WebsiteVoice [Section titled “WebsiteVoice”](#websitevoice) ```ts type WebsiteVoice = z.infer; ``` Defined in: [src/schemas/website.ts:337](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L337) Inferred from [WebsiteVoiceSchema](/api/types/src/#websitevoiceschema). *** ### WelcomeMessageFeature [Section titled “WelcomeMessageFeature”](#welcomemessagefeature) ```ts type WelcomeMessageFeature = z.infer; ``` Defined in: [src/schemas/website.ts:21](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L21) Inferred from [WelcomeMessageFeatureSchema](/api/types/src/#welcomemessagefeatureschema). ## Variables [Section titled “Variables”](#variables) ### API\_VERSION [Section titled “API\_VERSION”](#api_version) ```ts const API_VERSION: "v2"; ``` Defined in: [src/schemas/core.ts:12](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L12) Current API version used by the SDK and documented in OpenAPI *** ### AUDIO\_FORMATS [Section titled “AUDIO\_FORMATS”](#audio_formats) ```ts const AUDIO_FORMATS: ("mp3" | "ogg" | "wav")[] = AudioFormatSchema.options; ``` Defined in: [src/schemas/core.ts:72](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L72) Valid audio format values for runtime validation *** ### AudioFormatSchema [Section titled “AudioFormatSchema”](#audioformatschema) ```ts const AudioFormatSchema: ZodEnum<{ mp3: "mp3"; ogg: "ogg"; wav: "wav"; }>; ``` Defined in: [src/schemas/core.ts:64](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L64) Supported audio output formats *** ### AudioResponseSchema [Section titled “AudioResponseSchema”](#audioresponseschema) ```ts const AudioResponseSchema: ZodObject<{ blob: ZodCustom; duration: ZodOptional; format: ZodEnum<{ mp3: "mp3"; ogg: "ogg"; wav: "wav"; }>; prosodyApplied: ZodArray>; url: ZodString; }, $strip>; ``` Defined in: [src/schemas/synthesis.ts:123](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L123) Audio response wrapper with metadata *** ### AuthTokenSchema [Section titled “AuthTokenSchema”](#authtokenschema) ```ts const AuthTokenSchema: ZodObject<{ exp: ZodNumber; token: ZodString; }, $strip>; ``` Defined in: [src/schemas/website.ts:352](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L352) Short-lived bearer token returned by `/v2/config`. The SDK carries it as `Authorization: Bearer ` on subsequent /v2/\* requests. May be absent. *** ### BrowserVoiceInfoSchema [Section titled “BrowserVoiceInfoSchema”](#browservoiceinfoschema) ```ts const BrowserVoiceInfoSchema: ZodObject<{ default: ZodOptional; lang: ZodString; localService: ZodBoolean; name: ZodString; voiceURI: ZodString; }, $strip>; ``` Defined in: [src/schemas/responses.ts:24](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L24) Browser voice information from Web Speech API Represents a SpeechSynthesisVoice as reported by the browser *** ### ByLanguageLinksSchema [Section titled “ByLanguageLinksSchema”](#bylanguagelinksschema) ```ts const ByLanguageLinksSchema: ZodObject<{ allVoices: ZodObject<{ href: ZodString; }, $strip>; self: ZodObject<{ href: ZodString; }, $strip>; }, $strip>; ``` Defined in: [src/schemas/responses.ts:234](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L234) Collection-level HATEOAS links on `GET /v2/voices/by-language/{lang}`. *** ### CollectionLinksSchema [Section titled “CollectionLinksSchema”](#collectionlinksschema) ```ts const CollectionLinksSchema: ZodObject<{ self: ZodObject<{ href: ZodString; }, $strip>; }, $strip>; ``` Defined in: [src/schemas/responses.ts:222](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L222) Collection-level HATEOAS links on GET /v2/voices. *** ### DEFAULT\_ENGINE\_FORMAT [Section titled “DEFAULT\_ENGINE\_FORMAT”](#default_engine_format) ```ts const DEFAULT_ENGINE_FORMAT: Record; ``` Defined in: [src/schemas/core.ts:98](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L98) Default audio format for each TTS engine. Used when no explicit format is requested. *** ### DEFAULT\_WEBSITE\_FEATURES [Section titled “DEFAULT\_WEBSITE\_FEATURES”](#default_website_features) ```ts const DEFAULT_WEBSITE_FEATURES: { accessibilityNavigation: { enabled: false; }; exitIntent: { enabled: false; text: null; }; paragraphNavigation: { enabled: false; }; speakEndPage: { enabled: false; text: null; }; speakInactivity: { enabled: false; text: null; }; speakLinks: { enabled: false; }; speakSelectedText: { enabled: false; }; webPlayer: { controls: { brand: true; progress: true; skip: true; speed: true; time: true; }; enabled: false; layout: { display: "block"; mode: "shrink"; }; miniPlayer: { animation: "slide"; enabled: true; position: "bottom-left"; }; navigation: { paragraphClick: true; paragraphHighlight: true; }; paragraphSelector: "p, h2, h3, li"; position: "before"; sanitize: { enabled: true; exclude: string[]; }; selector: "article"; theme: "neutral"; }; welcomeMessage: { enabled: false; text: null; }; welcomeMessageOnce: false; }; ``` Defined in: [src/schemas/website.ts:269](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L269) Baseline defaults applied when a website config omits a feature flag. #### Type Declaration [Section titled “Type Declaration”](#type-declaration) ##### accessibilityNavigation [Section titled “accessibilityNavigation”](#accessibilitynavigation) ```ts readonly accessibilityNavigation: { enabled: false; }; ``` ###### accessibilityNavigation.enabled [Section titled “accessibilityNavigation.enabled”](#accessibilitynavigationenabled) ```ts readonly enabled: false = false; ``` ##### exitIntent [Section titled “exitIntent”](#exitintent) ```ts readonly exitIntent: { enabled: false; text: null; }; ``` ###### exitIntent.enabled [Section titled “exitIntent.enabled”](#exitintentenabled) ```ts readonly enabled: false = false; ``` ###### exitIntent.text [Section titled “exitIntent.text”](#exitintenttext) ```ts readonly text: null = null; ``` ##### paragraphNavigation [Section titled “paragraphNavigation”](#paragraphnavigation) ```ts readonly paragraphNavigation: { enabled: false; }; ``` ###### paragraphNavigation.enabled [Section titled “paragraphNavigation.enabled”](#paragraphnavigationenabled) ```ts readonly enabled: false = false; ``` ##### speakEndPage [Section titled “speakEndPage”](#speakendpage) ```ts readonly speakEndPage: { enabled: false; text: null; }; ``` ###### speakEndPage.enabled [Section titled “speakEndPage.enabled”](#speakendpageenabled) ```ts readonly enabled: false = false; ``` ###### speakEndPage.text [Section titled “speakEndPage.text”](#speakendpagetext) ```ts readonly text: null = null; ``` ##### speakInactivity [Section titled “speakInactivity”](#speakinactivity) ```ts readonly speakInactivity: { enabled: false; text: null; }; ``` ###### speakInactivity.enabled [Section titled “speakInactivity.enabled”](#speakinactivityenabled) ```ts readonly enabled: false = false; ``` ###### speakInactivity.text [Section titled “speakInactivity.text”](#speakinactivitytext) ```ts readonly text: null = null; ``` ##### speakLinks [Section titled “speakLinks”](#speaklinks) ```ts readonly speakLinks: { enabled: false; }; ``` ###### speakLinks.enabled [Section titled “speakLinks.enabled”](#speaklinksenabled) ```ts readonly enabled: false = false; ``` ##### speakSelectedText [Section titled “speakSelectedText”](#speakselectedtext) ```ts readonly speakSelectedText: { enabled: false; }; ``` ###### speakSelectedText.enabled [Section titled “speakSelectedText.enabled”](#speakselectedtextenabled) ```ts readonly enabled: false = false; ``` ##### webPlayer [Section titled “webPlayer”](#webplayer) ```ts readonly webPlayer: { controls: { brand: true; progress: true; skip: true; speed: true; time: true; }; enabled: false; layout: { display: "block"; mode: "shrink"; }; miniPlayer: { animation: "slide"; enabled: true; position: "bottom-left"; }; navigation: { paragraphClick: true; paragraphHighlight: true; }; paragraphSelector: "p, h2, h3, li"; position: "before"; sanitize: { enabled: true; exclude: string[]; }; selector: "article"; theme: "neutral"; }; ``` ###### webPlayer.controls [Section titled “webPlayer.controls”](#webplayercontrols-1) ```ts readonly controls: { brand: true; progress: true; skip: true; speed: true; time: true; }; ``` ###### webPlayer.controls.brand [Section titled “webPlayer.controls.brand”](#webplayercontrolsbrand) ```ts readonly brand: true = true; ``` ###### webPlayer.controls.progress [Section titled “webPlayer.controls.progress”](#webplayercontrolsprogress) ```ts readonly progress: true = true; ``` ###### webPlayer.controls.skip [Section titled “webPlayer.controls.skip”](#webplayercontrolsskip) ```ts readonly skip: true = true; ``` ###### webPlayer.controls.speed [Section titled “webPlayer.controls.speed”](#webplayercontrolsspeed) ```ts readonly speed: true = true; ``` ###### webPlayer.controls.time [Section titled “webPlayer.controls.time”](#webplayercontrolstime) ```ts readonly time: true = true; ``` ###### webPlayer.enabled [Section titled “webPlayer.enabled”](#webplayerenabled) ```ts readonly enabled: false = false; ``` ###### webPlayer.layout [Section titled “webPlayer.layout”](#webplayerlayout-1) ```ts readonly layout: { display: "block"; mode: "shrink"; }; ``` ###### webPlayer.layout.display [Section titled “webPlayer.layout.display”](#webplayerlayoutdisplay) ```ts readonly display: "block" = 'block'; ``` ###### webPlayer.layout.mode [Section titled “webPlayer.layout.mode”](#webplayerlayoutmode) ```ts readonly mode: "shrink" = 'shrink'; ``` ###### webPlayer.miniPlayer [Section titled “webPlayer.miniPlayer”](#webplayerminiplayer) ```ts readonly miniPlayer: { animation: "slide"; enabled: true; position: "bottom-left"; }; ``` ###### webPlayer.miniPlayer.animation [Section titled “webPlayer.miniPlayer.animation”](#webplayerminiplayeranimation) ```ts readonly animation: "slide" = 'slide'; ``` ###### webPlayer.miniPlayer.enabled [Section titled “webPlayer.miniPlayer.enabled”](#webplayerminiplayerenabled) ```ts readonly enabled: true = true; ``` ###### webPlayer.miniPlayer.position [Section titled “webPlayer.miniPlayer.position”](#webplayerminiplayerposition) ```ts readonly position: "bottom-left" = 'bottom-left'; ``` ###### webPlayer.navigation [Section titled “webPlayer.navigation”](#webplayernavigation-1) ```ts readonly navigation: { paragraphClick: true; paragraphHighlight: true; }; ``` ###### webPlayer.navigation.paragraphClick [Section titled “webPlayer.navigation.paragraphClick”](#webplayernavigationparagraphclick) ```ts readonly paragraphClick: true = true; ``` ###### webPlayer.navigation.paragraphHighlight [Section titled “webPlayer.navigation.paragraphHighlight”](#webplayernavigationparagraphhighlight) ```ts readonly paragraphHighlight: true = true; ``` ###### webPlayer.paragraphSelector [Section titled “webPlayer.paragraphSelector”](#webplayerparagraphselector) ```ts readonly paragraphSelector: "p, h2, h3, li" = 'p, h2, h3, li'; ``` ###### webPlayer.position [Section titled “webPlayer.position”](#webplayerposition) ```ts readonly position: "before" = 'before'; ``` ###### webPlayer.sanitize [Section titled “webPlayer.sanitize”](#webplayersanitize-1) ```ts readonly sanitize: { enabled: true; exclude: string[]; }; ``` ###### webPlayer.sanitize.enabled [Section titled “webPlayer.sanitize.enabled”](#webplayersanitizeenabled) ```ts readonly enabled: true = true; ``` ###### webPlayer.sanitize.exclude [Section titled “webPlayer.sanitize.exclude”](#webplayersanitizeexclude) ```ts readonly exclude: string[]; ``` ###### webPlayer.selector [Section titled “webPlayer.selector”](#webplayerselector) ```ts readonly selector: "article" = 'article'; ``` ###### webPlayer.theme [Section titled “webPlayer.theme”](#webplayertheme-1) ```ts readonly theme: "neutral" = 'neutral'; ``` ##### welcomeMessage [Section titled “welcomeMessage”](#welcomemessage) ```ts readonly welcomeMessage: { enabled: false; text: null; }; ``` ###### welcomeMessage.enabled [Section titled “welcomeMessage.enabled”](#welcomemessageenabled) ```ts readonly enabled: false = false; ``` ###### welcomeMessage.text [Section titled “welcomeMessage.text”](#welcomemessagetext) ```ts readonly text: null = null; ``` ##### welcomeMessageOnce [Section titled “welcomeMessageOnce”](#welcomemessageonce) ```ts readonly welcomeMessageOnce: false = false; ``` *** ### DeviceTypeSchema [Section titled “DeviceTypeSchema”](#devicetypeschema) ```ts const DeviceTypeSchema: ZodEnum<{ desktop: "desktop"; mobile: "mobile"; tablet: "tablet"; }>; ``` Defined in: [src/schemas/responses.ts:16](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L16) Device type classification for voice reporting *** ### ENGINE\_SUPPORTED\_FORMATS [Section titled “ENGINE\_SUPPORTED\_FORMATS”](#engine_supported_formats) ```ts const ENGINE_SUPPORTED_FORMATS: Record; ``` Defined in: [src/schemas/core.ts:84](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L84) Supported audio formats per TTS engine. * Free providers (g1, g2, g3) only produce MP3 * g5 only produces OGG * BYOK providers support multiple formats via their native APIs: * gwn (Google Cloud): MP3 and OGG\_OPUS * msv (Azure): MP3, OGG, and WAV * oai (OpenAI): MP3, OGG (Opus), and WAV *** ### ErrorResponseSchema [Section titled “ErrorResponseSchema”](#errorresponseschema) ```ts const ErrorResponseSchema: ZodObject<{ error: ZodObject<{ code: ZodOptional; errors: ZodOptional; message: ZodString; statusCode: ZodNumber; }, $strip>; }, $strip>; ``` Defined in: [src/schemas/responses.ts:115](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L115) Standard API error response matching error-handler.ts format *** ### EVENT\_TYPES [Section titled “EVENT\_TYPES”](#event_types) ```ts const EVENT_TYPES: ( | "OnLoad" | "OnReady" | "OnStart" | "OnEnd" | "OnError" | "OnPause" | "OnResume" | "OnServiceSwitched" | "OnClickEvent" | "OnAllowSpeechClicked" | "OnPartStart" | "OnPartEnd" | "OnVoiceResolved")[] = RVEventTypeSchema.options; ``` Defined in: [src/schemas/core.ts:145](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L145) Valid event type values for runtime validation *** ### HrefLinkSchema [Section titled “HrefLinkSchema”](#hreflinkschema) ```ts const HrefLinkSchema: ZodObject<{ href: ZodString; }, $strip>; ``` Defined in: [src/schemas/responses.ts:140](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L140) Simple HATEOAS link with an absolute URL. *** ### MiniPlayerCornerSchema [Section titled “MiniPlayerCornerSchema”](#miniplayercornerschema) ```ts const MiniPlayerCornerSchema: ZodEnum<{ bottom-left: "bottom-left"; bottom-right: "bottom-right"; top-left: "top-left"; top-right: "top-right"; }>; ``` Defined in: [src/schemas/website.ts:115](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L115) Mini-player corner placement keywords. *** ### MiniPlayerOffsetSchema [Section titled “MiniPlayerOffsetSchema”](#miniplayeroffsetschema) ```ts const MiniPlayerOffsetSchema: ZodObject<{ bottom: ZodOptional; left: ZodOptional; right: ZodOptional; top: ZodOptional; }, $strip>; ``` Defined in: [src/schemas/website.ts:129](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L129) Mini-player CSS-offset placement. Each side is a CSS length string (e.g. `'80px'`, `'2rem'`, `'5%'`). At least one side is required; `top`+`bottom` and `left`+`right` combinations are rejected. *** ### MiniPlayerSchema [Section titled “MiniPlayerSchema”](#miniplayerschema) ```ts const MiniPlayerSchema: ZodObject<{ animation: ZodDefault>; enabled: ZodDefault; position: ZodDefault, ZodObject<{ bottom: ZodOptional; left: ZodOptional; right: ZodOptional; top: ZodOptional; }, $strip>]>>; }, $strip>; ``` Defined in: [src/schemas/website.ts:157](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L157) Mini-player configuration — visibility and viewport placement. `position` accepts a corner keyword or an offset object; default is `bottom-left`. *** ### PitchSchema [Section titled “PitchSchema”](#pitchschema) ```ts const PitchSchema: ZodNumber; ``` Defined in: [src/schemas/synthesis.ts:26](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L26) Voice pitch range (0–2; 1 = normal). *** ### PlatformReportSchema [Section titled “PlatformReportSchema”](#platformreportschema) ```ts const PlatformReportSchema: ZodObject<{ browser: ZodString; browserVersion: ZodString; deviceType: ZodOptional>; os: ZodString; osVersion: ZodString; }, $strip>; ``` Defined in: [src/schemas/responses.ts:48](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L48) Platform information for voice reporting *** ### PROSODY\_KNOBS [Section titled “PROSODY\_KNOBS”](#prosody_knobs) ```ts const PROSODY_KNOBS: readonly ["pitch", "rate", "volume"]; ``` Defined in: [src/schemas/prosody.ts:12](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/prosody.ts#L12) The complete set of prosody knobs the v2 API recognises. Order is stable and used for deterministic header formatting. *** ### ProsodyAppliedHeaderSchema [Section titled “ProsodyAppliedHeaderSchema”](#prosodyappliedheaderschema) ```ts const ProsodyAppliedHeaderSchema: ZodString; ``` Defined in: [src/schemas/prosody.ts:26](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/prosody.ts#L26) Wire shape for the `RV-Prosody-Applied` response header — a comma-separated subset of the prosody knob alphabet, in any order. Empty string means the server applied none of the requested knobs (client should run its own fallback per its `prosodyFallback` policy). *** ### ProsodyKnobSchema [Section titled “ProsodyKnobSchema”](#prosodyknobschema) ```ts const ProsodyKnobSchema: ZodEnum<{ pitch: "pitch"; rate: "rate"; volume: "volume"; }>; ``` Defined in: [src/schemas/prosody.ts:18](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/prosody.ts#L18) Zod enum over [PROSODY\_KNOBS](/api/types/src/#prosody_knobs). *** ### RateSchema [Section titled “RateSchema”](#rateschema) ```ts const RateSchema: ZodNumber; ``` Defined in: [src/schemas/synthesis.ts:28](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L28) Speech rate range (0–2; 1 = normal). *** ### RegexSelectorSchema [Section titled “RegexSelectorSchema”](#regexselectorschema) ```ts const RegexSelectorSchema: ZodObject<{ flags: ZodOptional; regex: ZodString; }, $strip>; ``` Defined in: [src/schemas/voice-query.ts:51](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/voice-query.ts#L51) JSON-serializable regex literal for [VoiceSelectorSchema](/api/types/src/#voiceselectorschema). Used in place of a runtime `RegExp` so the selector can travel over the wire and appear in OpenAPI / SDKs in every language. *** ### ResponsiveVoiceConfigSchema [Section titled “ResponsiveVoiceConfigSchema”](#responsivevoiceconfigschema) ```ts const ResponsiveVoiceConfigSchema: ZodObject<{ apiKey: ZodString; apiSecret: ZodOptional; baseUrl: ZodOptional; debug: ZodOptional; defaultLang: ZodOptional; defaultVoice: ZodOptional; preferNative: ZodOptional; retryAttempts: ZodOptional; timeout: ZodOptional; }, $strip>; ``` Defined in: [src/schemas/synthesis.ts:155](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L155) ResponsiveVoice client configuration *** ### RVErrorEventSchema [Section titled “RVErrorEventSchema”](#rverroreventschema) ```ts const RVErrorEventSchema: ZodObject<{ code: ZodOptional; message: ZodString; timestamp: ZodNumber; type: ZodLiteral<"OnError">; }, $strip>; ``` Defined in: [src/schemas/events.ts:36](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/events.ts#L36) Error event with additional error information *** ### RVEventCallbackSchema [Section titled “RVEventCallbackSchema”](#rveventcallbackschema) ```ts const RVEventCallbackSchema: ZodFunction<$ZodFunctionArgs, $ZodFunctionOut>; ``` Defined in: [src/schemas/events.ts:29](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/events.ts#L29) Runtime validator for event callbacks. See [RVEventCallback](/api/types/src/#rveventcallback) for the TS signature. *** ### RVEventSchema [Section titled “RVEventSchema”](#rveventschema) ```ts const RVEventSchema: ZodObject<{ timestamp: ZodNumber; type: ZodEnum<{ OnAllowSpeechClicked: "OnAllowSpeechClicked"; OnClickEvent: "OnClickEvent"; OnEnd: "OnEnd"; OnError: "OnError"; OnLoad: "OnLoad"; OnPartEnd: "OnPartEnd"; OnPartStart: "OnPartStart"; OnPause: "OnPause"; OnReady: "OnReady"; OnResume: "OnResume"; OnServiceSwitched: "OnServiceSwitched"; OnStart: "OnStart"; OnVoiceResolved: "OnVoiceResolved"; }>; }, $strip>; ``` Defined in: [src/schemas/events.ts:13](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/events.ts#L13) Base event interface *** ### RVEventTypeSchema [Section titled “RVEventTypeSchema”](#rveventtypeschema) ```ts const RVEventTypeSchema: ZodEnum<{ OnAllowSpeechClicked: "OnAllowSpeechClicked"; OnClickEvent: "OnClickEvent"; OnEnd: "OnEnd"; OnError: "OnError"; OnLoad: "OnLoad"; OnPartEnd: "OnPartEnd"; OnPartStart: "OnPartStart"; OnPause: "OnPause"; OnReady: "OnReady"; OnResume: "OnResume"; OnServiceSwitched: "OnServiceSwitched"; OnStart: "OnStart"; OnVoiceResolved: "OnVoiceResolved"; }>; ``` Defined in: [src/schemas/core.ts:126](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L126) ResponsiveVoice event types *** ### RVServiceSwitchedEventSchema [Section titled “RVServiceSwitchedEventSchema”](#rvserviceswitchedeventschema) ```ts const RVServiceSwitchedEventSchema: ZodObject<{ from: ZodUnion, ZodLiteral<"native">]>; timestamp: ZodNumber; to: ZodUnion, ZodLiteral<"native">]>; type: ZodLiteral<"OnServiceSwitched">; }, $strip>; ``` Defined in: [src/schemas/events.ts:58](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/events.ts#L58) Service switched event *** ### ServiceOrNativeSchema [Section titled “ServiceOrNativeSchema”](#serviceornativeschema) ```ts const ServiceOrNativeSchema: ZodUnion, ZodLiteral<"native">]>; ``` Defined in: [src/schemas/events.ts:51](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/events.ts#L51) Service or native source for service switching *** ### SpeakParamsSchema [Section titled “SpeakParamsSchema”](#speakparamsschema) ```ts const SpeakParamsSchema: ZodObject<{ onend: ZodOptional>; onerror: ZodOptional>; onstart: ZodOptional>; pitch: ZodOptional; prosodyFallback: ZodOptional; rate: ZodOptional; volume: ZodOptional; }, $strip>; ``` Defined in: [src/schemas/synthesis.ts:195](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L195) Speech parameters for speak() method *** ### SpeechParamsSchema [Section titled “SpeechParamsSchema”](#speechparamsschema) ```ts const SpeechParamsSchema: ZodObject<{ pitch: ZodOptional; rate: ZodOptional; volume: ZodOptional; }, $strip>; ``` Defined in: [src/schemas/synthesis.ts:41](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L41) Numeric speech parameters as a reusable, all-optional shape. Spread via `...SpeechParamsSchema.shape` into any schema that wants `pitch` / `rate` / `volume` overrides — `SynthesizeRequestSchema`, `SpeakParamsSchema`, `WebPlayerFeatureSchema`, and any future consumer. Field-level documentation lives here so the constraints and the meaning live in one place; consumer comments only describe context-specific *behavior* (e.g. "inherits website default when omitted"). *** ### StreamAudioChunkSchema [Section titled “StreamAudioChunkSchema”](#streamaudiochunkschema) ```ts const StreamAudioChunkSchema: ZodObject<{ chunkIndex: ZodNumber; data: ZodCustom, Uint8Array>; type: ZodLiteral<"audio">; }, $strip>; ``` Defined in: [src/schemas/streaming.ts:31](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/streaming.ts#L31) A chunk of audio data from the stream *** ### StreamEndSchema [Section titled “StreamEndSchema”](#streamendschema) ```ts const StreamEndSchema: ZodObject<{ totalBytes: ZodNumber; totalChunks: ZodNumber; type: ZodLiteral<"end">; }, $strip>; ``` Defined in: [src/schemas/streaming.ts:44](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/streaming.ts#L44) End-of-stream marker with summary statistics *** ### StreamErrorSchema [Section titled “StreamErrorSchema”](#streamerrorschema) ```ts const StreamErrorSchema: ZodObject<{ message: ZodString; retryable: ZodBoolean; type: ZodLiteral<"error">; }, $strip>; ``` Defined in: [src/schemas/streaming.ts:57](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/streaming.ts#L57) Stream error event *** ### STREAMING\_ACCEPT\_TYPE [Section titled “STREAMING\_ACCEPT\_TYPE”](#streaming_accept_type) ```ts const STREAMING_ACCEPT_TYPE: "text/event-stream"; ``` Defined in: [src/schemas/core.ts:186](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L186) The Accept header value that clients MUST send for streaming synthesis requests. Used by both the client (to set the header) and the server (to validate it). This acts as a protocol-level signal alongside `stream: true` in the body, enabling infrastructure (e.g. Traefik) to route streaming requests correctly and providing defense-in-depth against forged requests. *** ### StreamingTransportModeSchema [Section titled “StreamingTransportModeSchema”](#streamingtransportmodeschema) ```ts const StreamingTransportModeSchema: ZodEnum<{ stream: "stream"; websocket: "websocket"; }>; ``` Defined in: [src/schemas/core.ts:171](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L171) Streaming-only transport modes (excludes 'chunks'). Used when MSE progressive playback is required. *** ### StreamMetadataSchema [Section titled “StreamMetadataSchema”](#streammetadataschema) ```ts const StreamMetadataSchema: ZodObject<{ contentType: ZodString; prosodyApplied: ZodArray>; type: ZodLiteral<"metadata">; }, $strip>; ``` Defined in: [src/schemas/streaming.ts:15](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/streaming.ts#L15) Metadata about a streaming synthesis session. First chunk emitted when streaming begins. *** ### StreamWebsocketLinkSchema [Section titled “StreamWebsocketLinkSchema”](#streamwebsocketlinkschema) ```ts const StreamWebsocketLinkSchema: ZodObject<{ href: ZodString; message: ZodObject<{ lang: ZodOptional; type: ZodString; voice: ZodString; }, $strip>; premium: ZodBoolean; protocol: ZodLiteral<"websocket">; }, $strip>; ``` Defined in: [src/schemas/responses.ts:180](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L180) WebSocket stream action link. *** ### SynthesizeLinkSchema [Section titled “SynthesizeLinkSchema”](#synthesizelinkschema) ```ts const SynthesizeLinkSchema: ZodObject<{ body: ZodObject<{ lang: ZodOptional; voice: ZodString; }, $strip>; href: ZodString; method: ZodLiteral<"POST">; }, $strip>; ``` Defined in: [src/schemas/responses.ts:149](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L149) Synthesize action link on a voice resource. *** ### SynthesizeRequestSchema [Section titled “SynthesizeRequestSchema”](#synthesizerequestschema) ```ts const SynthesizeRequestSchema: ZodObject<{ engine: ZodOptional>; format: ZodOptional>; gender: ZodOptional>; lang: ZodOptional; name: ZodOptional; pitch: ZodOptional; rate: ZodOptional; text: ZodString; voice: ZodOptional; volume: ZodOptional; }, $strip>; ``` Defined in: [src/schemas/synthesis.ts:59](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L59) Request parameters for text-to-speech synthesis *** ### SynthesizeResponseSchema [Section titled “SynthesizeResponseSchema”](#synthesizeresponseschema) ```ts const SynthesizeResponseSchema: ZodObject<{ audio: ZodCustom; contentType: ZodString; duration: ZodOptional; size: ZodNumber; }, $strip>; ``` Defined in: [src/schemas/synthesis.ts:104](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L104) Response from text-to-speech synthesis *** ### SynthesizeStreamLinkSchema [Section titled “SynthesizeStreamLinkSchema”](#synthesizestreamlinkschema) ```ts const SynthesizeStreamLinkSchema: ZodObject<{ accept: ZodLiteral<"text/event-stream">; body: ZodObject<{ lang: ZodOptional; stream: ZodBoolean; voice: ZodString; }, $strip>; href: ZodString; method: ZodLiteral<"POST">; premium: ZodBoolean; }, $strip>; ``` Defined in: [src/schemas/responses.ts:160](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L160) Streaming synthesize action link (HTTP audio streaming). *** ### SystemVoiceSchema [Section titled “SystemVoiceSchema”](#systemvoiceschema) ```ts const SystemVoiceSchema: ZodObject<{ deprecated: ZodOptional; fallbackVoice: ZodOptional; gender: ZodOptional; id: ZodNumber; lang: ZodOptional; name: ZodString; pitch: ZodOptional; rate: ZodOptional; service: ZodOptional>; timerSpeed: ZodOptional; voiceName: ZodOptional; volume: ZodOptional; }, $strip>; ``` Defined in: [src/schemas/voice.ts:51](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/voice.ts#L51) Low-level system voice mapping Represents the actual TTS voice configuration *** ### TextFeatureSchema [Section titled “TextFeatureSchema”](#textfeatureschema) ```ts const TextFeatureSchema: ZodObject<{ enabled: ZodDefault; text: ZodDefault>; }, $strip>; ``` Defined in: [src/schemas/website.ts:24](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L24) Feature toggle with optional custom text (`speakInactivity`, `speakEndPage`, `exitIntent`). *** ### ToggleFeatureSchema [Section titled “ToggleFeatureSchema”](#togglefeatureschema) ```ts const ToggleFeatureSchema: ZodObject<{ enabled: ZodDefault; }, $strip>; ``` Defined in: [src/schemas/website.ts:32](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L32) Simple on/off feature toggle without custom text (`speakSelectedText`, `speakLinks`, etc.). *** ### TRANSPORT\_MODES [Section titled “TRANSPORT\_MODES”](#transport_modes) ```ts const TRANSPORT_MODES: ("chunks" | "stream" | "websocket")[] = TransportModeSchema.options; ``` Defined in: [src/schemas/core.ts:165](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L165) Valid transport mode values for runtime validation *** ### TransportModeSchema [Section titled “TransportModeSchema”](#transportmodeschema) ```ts const TransportModeSchema: ZodEnum<{ chunks: "chunks"; stream: "stream"; websocket: "websocket"; }>; ``` Defined in: [src/schemas/core.ts:157](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L157) Audio transport mode for fallback (HTTP) voices. * `'chunks'` (default): full download per text chunk, then play * `'stream'`: HTTP audio streaming with MSE progressive playback * `'websocket'`: persistent WebSocket connection with MSE progressive playback *** ### TTS\_SERVICES [Section titled “TTS\_SERVICES”](#tts_services) ```ts const TTS_SERVICES: ("g1" | "g2" | "g3" | "g5" | "gwn" | "msv" | "oai")[] = TTSServiceSchema.options; ``` Defined in: [src/schemas/core.ts:59](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L59) Valid TTS service values for runtime validation *** ### TTSServiceSchema [Section titled “TTSServiceSchema”](#ttsserviceschema) ```ts const TTSServiceSchema: ZodEnum<{ g1: "g1"; g2: "g2"; g3: "g3"; g5: "g5"; gwn: "gwn"; msv: "msv"; oai: "oai"; }>; ``` Defined in: [src/schemas/core.ts:51](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L51) Available TTS service backends * g1: Primary fallback service * g2: Secondary fallback service * g3: Male voice fallbacks * g5: Specialty languages (Armenian, Esperanto, Macedonian, Welsh) * gwn: Google Cloud WaveNet (premium, requires BYOK credentials) * msv: Microsoft Azure Speech (premium, requires BYOK credentials) * oai: OpenAI TTS (premium, requires BYOK credentials) *** ### VERSION [Section titled “VERSION”](#version) ```ts const VERSION: string; ``` Defined in: [src/version.ts:14](https://github.com/responsivevoice/types/blob/v2.0.1/src/version.ts#L14) Package version, the source of truth for the OpenAPI contract version. *** ### VOICE\_GENDERS [Section titled “VOICE\_GENDERS”](#voice_genders) ```ts const VOICE_GENDERS: ("male" | "female")[] = VoiceGenderSchema.options; ``` Defined in: [src/schemas/core.ts:29](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L29) Valid voice gender values for runtime validation *** ### VOICE\_GENDERS\_SHORT [Section titled “VOICE\_GENDERS\_SHORT”](#voice_genders_short) ```ts const VOICE_GENDERS_SHORT: ("f" | "m")[] = VoiceGenderShortSchema.options; ``` Defined in: [src/schemas/core.ts:39](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L39) Valid short gender values for runtime validation *** ### VoiceCollectionSchema [Section titled “VoiceCollectionSchema”](#voicecollectionschema) ```ts const VoiceCollectionSchema: ZodObject<{ lastUpdated: ZodString; systemVoices: ZodArray; fallbackVoice: ZodOptional; gender: ZodOptional; id: ZodNumber; lang: ZodOptional; name: ZodString; pitch: ZodOptional; rate: ZodOptional; service: ZodOptional>; timerSpeed: ZodOptional; voiceName: ZodOptional; volume: ZodOptional; }, $strip>>; version: ZodString; voices: ZodArray; flag: ZodString; gender: ZodEnum<{ f: "f"; m: "m"; }>; isByok: ZodOptional; lang: ZodString; name: ZodString; provider: ZodOptional; voiceIDs: ZodArray; }, $strip>>; }, $strip>; ``` Defined in: [src/schemas/voice.ts:96](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/voice.ts#L96) Complete voice collection containing all voices *** ### VoiceDetailLinksSchema [Section titled “VoiceDetailLinksSchema”](#voicedetaillinksschema) ```ts const VoiceDetailLinksSchema: ZodObject<{ byLanguage: ZodObject<{ href: ZodString; }, $strip>; collection: ZodObject<{ href: ZodString; }, $strip>; self: ZodObject<{ href: ZodString; }, $strip>; stream:websocket: ZodObject<{ href: ZodString; message: ZodObject<{ lang: ZodOptional; type: ZodString; voice: ZodString; }, $strip>; premium: ZodBoolean; protocol: ZodLiteral<"websocket">; }, $strip>; synthesize: ZodObject<{ body: ZodObject<{ lang: ZodOptional; voice: ZodString; }, $strip>; href: ZodString; method: ZodLiteral<"POST">; }, $strip>; synthesize:stream: ZodObject<{ accept: ZodLiteral<"text/event-stream">; body: ZodObject<{ lang: ZodOptional; stream: ZodBoolean; voice: ZodString; }, $strip>; href: ZodString; method: ZodLiteral<"POST">; premium: ZodBoolean; }, $strip>; }, $strip>; ``` Defined in: [src/schemas/responses.ts:211](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L211) Voice-detail HATEOAS links: voice-level links plus navigation back to the collection and the by-language list (only present on `GET /v2/voices/{name}`). *** ### VoiceDetailResponseSchema [Section titled “VoiceDetailResponseSchema”](#voicedetailresponseschema) ```ts const VoiceDetailResponseSchema: ZodObject<{ _links: ZodObject<{ byLanguage: ZodObject<{ href: ZodString; }, $strip>; collection: ZodObject<{ href: ZodString; }, $strip>; self: ZodObject<{ href: ZodString; }, $strip>; stream:websocket: ZodObject<{ href: ZodString; message: ZodObject<{ lang: ZodOptional; type: ZodString; voice: ZodString; }, $strip>; premium: ZodBoolean; protocol: ZodLiteral<"websocket">; }, $strip>; synthesize: ZodObject<{ body: ZodObject<{ lang: ZodOptional; voice: ZodString; }, $strip>; href: ZodString; method: ZodLiteral<"POST">; }, $strip>; synthesize:stream: ZodObject<{ accept: ZodLiteral<"text/event-stream">; body: ZodObject<{ lang: ZodOptional; stream: ZodBoolean; voice: ZodString; }, $strip>; href: ZodString; method: ZodLiteral<"POST">; premium: ZodBoolean; }, $strip>; }, $strip>; voice: ZodObject<{ deprecated: ZodOptional; flag: ZodString; gender: ZodEnum<{ f: "f"; m: "m"; }>; isByok: ZodOptional; lang: ZodString; name: ZodString; provider: ZodOptional; voiceIDs: ZodArray; }, $strip>; }, $strip>; ``` Defined in: [src/schemas/responses.ts:292](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L292) Response body for `GET /v2/voices/{name}`. *** ### VoiceGenderSchema [Section titled “VoiceGenderSchema”](#voicegenderschema) ```ts const VoiceGenderSchema: ZodEnum<{ female: "female"; male: "male"; }>; ``` Defined in: [src/schemas/core.ts:21](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L21) Voice gender classification *** ### VoiceGenderShortSchema [Section titled “VoiceGenderShortSchema”](#voicegendershortschema) ```ts const VoiceGenderShortSchema: ZodEnum<{ f: "f"; m: "m"; }>; ``` Defined in: [src/schemas/core.ts:34](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L34) Short form gender used internally *** ### VoiceLinksSchema [Section titled “VoiceLinksSchema”](#voicelinksschema) ```ts const VoiceLinksSchema: ZodObject<{ self: ZodObject<{ href: ZodString; }, $strip>; stream:websocket: ZodObject<{ href: ZodString; message: ZodObject<{ lang: ZodOptional; type: ZodString; voice: ZodString; }, $strip>; premium: ZodBoolean; protocol: ZodLiteral<"websocket">; }, $strip>; synthesize: ZodObject<{ body: ZodObject<{ lang: ZodOptional; voice: ZodString; }, $strip>; href: ZodString; method: ZodLiteral<"POST">; }, $strip>; synthesize:stream: ZodObject<{ accept: ZodLiteral<"text/event-stream">; body: ZodObject<{ lang: ZodOptional; stream: ZodBoolean; voice: ZodString; }, $strip>; href: ZodString; method: ZodLiteral<"POST">; premium: ZodBoolean; }, $strip>; }, $strip>; ``` Defined in: [src/schemas/responses.ts:196](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L196) Voice-level HATEOAS links present on every voice in an API response. *** ### VoiceQuerySchema [Section titled “VoiceQuerySchema”](#voicequeryschema) ```ts const VoiceQuerySchema: ZodObject<{ gender: ZodOptional>; isByok: ZodOptional; lang: ZodOptional; name: ZodOptional; provider: ZodOptional; }, $strip>; ``` Defined in: [src/schemas/voice-query.ts:26](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/voice-query.ts#L26) Declarative voice selection query. All conditions are AND — a voice must match every specified field. #### Examples [Section titled “Examples”](#examples) ```ts // Select Portuguese female voice { lang: "pt", gender: "female" } ``` ```ts // Select a specific BYOK WaveNet voice { lang: "en-GB", gender: "m", provider: "Google Cloud WaveNet", name: "Wavenet-A" } ``` *** ### VoiceReportRequestSchema [Section titled “VoiceReportRequestSchema”](#voicereportrequestschema) ```ts const VoiceReportRequestSchema: ZodObject<{ platform: ZodObject<{ browser: ZodString; browserVersion: ZodString; deviceType: ZodOptional>; os: ZodString; osVersion: ZodString; }, $strip>; sdkVersion: ZodOptional; timestamp: ZodISODateTime; voices: ZodArray; lang: ZodString; localService: ZodBoolean; name: ZodString; voiceURI: ZodString; }, $strip>>; }, $strip>; ``` Defined in: [src/schemas/responses.ts:72](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L72) Voice report request - sent by client to report available browser voices *** ### VoiceReportResponseSchema [Section titled “VoiceReportResponseSchema”](#voicereportresponseschema) ```ts const VoiceReportResponseSchema: ZodObject<{ count: ZodNumber; systemVoices: ZodArray; fallbackVoice: ZodOptional; gender: ZodOptional; id: ZodNumber; lang: ZodOptional; name: ZodString; pitch: ZodOptional; rate: ZodOptional; service: ZodOptional>; timerSpeed: ZodOptional; voiceName: ZodOptional; volume: ZodOptional; }, $strip>>; voices: ZodArray; flag: ZodString; gender: ZodEnum<{ f: "f"; m: "m"; }>; isByok: ZodOptional; lang: ZodString; name: ZodString; provider: ZodOptional; voiceIDs: ZodArray; }, $strip>>; }, $strip>; ``` Defined in: [src/schemas/responses.ts:93](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L93) Voice report response - returns personalized voice collection *** ### VoicesByLanguageResponseSchema [Section titled “VoicesByLanguageResponseSchema”](#voicesbylanguageresponseschema) ```ts const VoicesByLanguageResponseSchema: ZodObject<{ _links: ZodObject<{ allVoices: ZodObject<{ href: ZodString; }, $strip>; self: ZodObject<{ href: ZodString; }, $strip>; }, $strip>; count: ZodNumber; language: ZodString; voices: ZodArray; stream:websocket: ZodObject<{ href: ZodString; message: ZodObject<{ lang: ...; type: ...; voice: ...; }, $strip>; premium: ZodBoolean; protocol: ZodLiteral<"websocket">; }, $strip>; synthesize: ZodObject<{ body: ZodObject<{ lang: ...; voice: ...; }, $strip>; href: ZodString; method: ZodLiteral<"POST">; }, $strip>; synthesize:stream: ZodObject<{ accept: ZodLiteral<"text/event-stream">; body: ZodObject<{ lang: ...; stream: ...; voice: ...; }, $strip>; href: ZodString; method: ZodLiteral<"POST">; premium: ZodBoolean; }, $strip>; }, $strip>; deprecated: ZodOptional; flag: ZodString; gender: ZodEnum<{ f: "f"; m: "m"; }>; isByok: ZodOptional; lang: ZodString; name: ZodString; provider: ZodOptional; voiceIDs: ZodArray; }, $strip>>; }, $strip>; ``` Defined in: [src/schemas/responses.ts:277](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L277) Response body for `GET /v2/voices/by-language/{lang}`. *** ### VoiceSchema [Section titled “VoiceSchema”](#voiceschema) ```ts const VoiceSchema: ZodObject<{ deprecated: ZodOptional; flag: ZodString; gender: ZodEnum<{ f: "f"; m: "m"; }>; isByok: ZodOptional; lang: ZodString; name: ZodString; provider: ZodOptional; voiceIDs: ZodArray; }, $strip>; ``` Defined in: [src/schemas/voice.ts:17](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/voice.ts#L17) High-level ResponsiveVoice voice definition Represents a user-facing voice option *** ### VoiceSelectorSchema [Section titled “VoiceSelectorSchema”](#voiceselectorschema) ```ts const VoiceSelectorSchema: ZodPreprocess; regex: ZodString; }, $strip>, ZodObject<{ gender: ZodOptional>; isByok: ZodOptional; lang: ZodOptional; name: ZodOptional; provider: ZodOptional; }, $strip>]>>; ``` Defined in: [src/schemas/voice-query.ts:76](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/voice-query.ts#L76) Voice selector — declarative grammar for choosing a voice. Three forms after parsing, all JSON-serializable so the same shape works in JS, every SDK language, and server payloads: * `string` — exact name match (e.g. `'UK English Female'`). * [VoiceQuery](/api/types/src/#voicequery) — structured AND-filter (e.g. `{ lang: 'pt', gender: 'female' }`). * [RegexSelector](/api/types/src/#regexselector) — `{ regex, flags? }` for pattern matching. In JS the schema also accepts a real `RegExp` as input — a `preprocess` step normalizes it to the [RegexSelector](/api/types/src/#regexselector) literal form before validation, so the post-parse output is always JSON-clean. The OpenAPI emit only describes the three wire forms (the preprocess is invisible to the schema description), so non-JS SDK consumers get a clean `oneOf` without a phantom `RegExp` branch. *** ### VoicesListResponseSchema [Section titled “VoicesListResponseSchema”](#voiceslistresponseschema) ```ts const VoicesListResponseSchema: ZodObject<{ _links: ZodObject<{ self: ZodObject<{ href: ZodString; }, $strip>; }, $strip>; count: ZodNumber; systemVoices: ZodArray; fallbackVoice: ZodOptional; gender: ZodOptional; id: ZodNumber; lang: ZodOptional; name: ZodString; pitch: ZodOptional; rate: ZodOptional; service: ZodOptional>; timerSpeed: ZodOptional; voiceName: ZodOptional; volume: ZodOptional; }, $strip>>; voices: ZodArray; stream:websocket: ZodObject<{ href: ZodString; message: ZodObject<{ lang: ...; type: ...; voice: ...; }, $strip>; premium: ZodBoolean; protocol: ZodLiteral<"websocket">; }, $strip>; synthesize: ZodObject<{ body: ZodObject<{ lang: ...; voice: ...; }, $strip>; href: ZodString; method: ZodLiteral<"POST">; }, $strip>; synthesize:stream: ZodObject<{ accept: ZodLiteral<"text/event-stream">; body: ZodObject<{ lang: ...; stream: ...; voice: ...; }, $strip>; href: ZodString; method: ZodLiteral<"POST">; premium: ZodBoolean; }, $strip>; }, $strip>; deprecated: ZodOptional; flag: ZodString; gender: ZodEnum<{ f: "f"; m: "m"; }>; isByok: ZodOptional; lang: ZodString; name: ZodString; provider: ZodOptional; voiceIDs: ZodArray; }, $strip>>; }, $strip>; ``` Defined in: [src/schemas/responses.ts:262](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L262) Response body for GET /v2/voices. *** ### VoiceWithLinksSchema [Section titled “VoiceWithLinksSchema”](#voicewithlinksschema) ```ts const VoiceWithLinksSchema: ZodObject<{ _links: ZodObject<{ self: ZodObject<{ href: ZodString; }, $strip>; stream:websocket: ZodObject<{ href: ZodString; message: ZodObject<{ lang: ZodOptional; type: ZodString; voice: ZodString; }, $strip>; premium: ZodBoolean; protocol: ZodLiteral<"websocket">; }, $strip>; synthesize: ZodObject<{ body: ZodObject<{ lang: ZodOptional; voice: ZodString; }, $strip>; href: ZodString; method: ZodLiteral<"POST">; }, $strip>; synthesize:stream: ZodObject<{ accept: ZodLiteral<"text/event-stream">; body: ZodObject<{ lang: ZodOptional; stream: ZodBoolean; voice: ZodString; }, $strip>; href: ZodString; method: ZodLiteral<"POST">; premium: ZodBoolean; }, $strip>; }, $strip>; deprecated: ZodOptional; flag: ZodString; gender: ZodEnum<{ f: "f"; m: "m"; }>; isByok: ZodOptional; lang: ZodString; name: ZodString; provider: ZodOptional; voiceIDs: ZodArray; }, $strip>; ``` Defined in: [src/schemas/responses.ts:247](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/responses.ts#L247) Voice resource as returned by API endpoints — core voice fields plus HATEOAS links. *** ### VolumeSchema [Section titled “VolumeSchema”](#volumeschema) ```ts const VolumeSchema: ZodNumber; ``` Defined in: [src/schemas/synthesis.ts:30](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/synthesis.ts#L30) Volume range (0–1; 1 = full). *** ### WebPlayerControlsSchema [Section titled “WebPlayerControlsSchema”](#webplayercontrolsschema) ```ts const WebPlayerControlsSchema: ZodObject<{ brand: ZodDefault; progress: ZodDefault; skip: ZodDefault; speed: ZodDefault; time: ZodDefault; }, $strip>; ``` Defined in: [src/schemas/website.ts:83](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L83) Toggles for the player's in-line controls. The play / pause button is always shown — without it the widget is not a player. `skip` pairs the skip-back and skip-forward buttons together because hiding one but not the other looks visually broken in the reference design. *** ### WebPlayerFeatureSchema [Section titled “WebPlayerFeatureSchema”](#webplayerfeatureschema) ```ts const WebPlayerFeatureSchema: ZodObject<{ controls: ZodDefault; progress: ZodDefault; skip: ZodDefault; speed: ZodDefault; time: ZodDefault; }, $strip>>; enabled: ZodDefault; layout: ZodDefault>; mode: ZodDefault>; }, $strip>>; miniPlayer: ZodDefault>; enabled: ZodDefault; position: ZodDefault, ZodObject<{ bottom: ...; left: ...; right: ...; top: ...; }, $strip>]>>; }, $strip>>>; navigation: ZodDefault; paragraphHighlight: ZodDefault; }, $strip>>; paragraphSelector: ZodDefault; pitch: ZodOptional; position: ZodDefault, ZodObject<{ at: ZodDefault>; target: ZodString; }, $strip>]>>; rate: ZodOptional; sanitize: ZodDefault; exclude: ZodDefault>; }, $strip>>; selector: ZodDefault; theme: ZodDefault, ZodObject<{ accent: ZodOptional; accentSoft: ZodOptional; bg: ZodOptional; border: ZodOptional; fg: ZodOptional; fill: ZodOptional; hover: ZodOptional; muted: ZodOptional; track: ZodOptional; }, $strip>]>>; voice: ZodOptional; regex: ZodString; }, $strip>, ZodObject<{ gender: ZodOptional>; isByok: ZodOptional; lang: ZodOptional; name: ZodOptional; provider: ZodOptional; }, $strip>]>>>; volume: ZodOptional; }, $strip>; ``` Defined in: [src/schemas/website.ts:211](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L211) Web player feature — an article-scoped player with paragraph highlighting, click-to-jump navigation, and a floating mini-player that appears when the main player scrolls out of view. Per-player playback overrides (`voice`, `rate`, `pitch`, `volume`) mirror the arguments of `core.speak(text, voice, params)`. Each is optional and leaf-merges over the website default voice profile from [WebsiteVoiceSchema](/api/types/src/#websitevoiceschema). *** ### WebPlayerLayoutSchema [Section titled “WebPlayerLayoutSchema”](#webplayerlayoutschema) ```ts const WebPlayerLayoutSchema: ZodObject<{ display: ZodDefault>; mode: ZodDefault>; }, $strip>; ``` Defined in: [src/schemas/website.ts:178](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L178) Player layout — width and how the main pill sits on the page. Defaults to `shrink + block` (player sized to its content, on its own line), which is the safe choice for arbitrary host pages. Use `fill + inline` to reproduce a full-width player that flows with surrounding text. *** ### WebPlayerNavigationSchema [Section titled “WebPlayerNavigationSchema”](#webplayernavigationschema) ```ts const WebPlayerNavigationSchema: ZodObject<{ paragraphClick: ZodDefault; paragraphHighlight: ZodDefault; }, $strip>; ``` Defined in: [src/schemas/website.ts:105](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L105) Toggles for article-level interactions. `paragraphHighlight` is the visual "currently playing" indicator on each paragraph; `paragraphClick` is click-to-jump navigation. They are independent — highlight-only without click is "follow along, no skipping ahead"; click-only without highlight is unusual but valid. *** ### WebPlayerSanitizeSchema [Section titled “WebPlayerSanitizeSchema”](#webplayersanitizeschema) ```ts const WebPlayerSanitizeSchema: ZodObject<{ enabled: ZodDefault; exclude: ZodDefault>; }, $strip>; ``` Defined in: [src/schemas/website.ts:192](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L192) Narration text sanitization. When `enabled`, non-rendered nodes (`script`/`style`), interactive controls, embedded media, and hidden content are excluded from narrated text; `false` narrates raw text. *** ### WebPlayerThemeSchema [Section titled “WebPlayerThemeSchema”](#webplayerthemeschema) ```ts const WebPlayerThemeSchema: ZodUnion, ZodObject<{ accent: ZodOptional; accentSoft: ZodOptional; bg: ZodOptional; border: ZodOptional; fg: ZodOptional; fill: ZodOptional; hover: ZodOptional; muted: ZodOptional; track: ZodOptional; }, $strip>]>; ``` Defined in: [src/schemas/website.ts:70](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L70) Theme input — either a preset name or a partial token record merged over the `neutral` baseline. *** ### WebPlayerThemeTokensSchema [Section titled “WebPlayerThemeTokensSchema”](#webplayerthemetokensschema) ```ts const WebPlayerThemeTokensSchema: ZodObject<{ accent: ZodOptional; accentSoft: ZodOptional; bg: ZodOptional; border: ZodOptional; fg: ZodOptional; fill: ZodOptional; hover: ZodOptional; muted: ZodOptional; track: ZodOptional; }, $strip>; ``` Defined in: [src/schemas/website.ts:43](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L43) Colour tokens that drive the web player's appearance. Each value is a CSS colour string. Applied as CSS custom properties on the player and the article container so paragraph styles inherit them. *** ### WebsiteAnalyticsSchema [Section titled “WebsiteAnalyticsSchema”](#websiteanalyticsschema) ```ts const WebsiteAnalyticsSchema: ZodObject<{ enabled: ZodDefault; }, $strip>; ``` Defined in: [src/schemas/website.ts:342](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L342) Analytics configuration. *** ### WebsiteConfigResponseSchema [Section titled “WebsiteConfigResponseSchema”](#websiteconfigresponseschema) ```ts const WebsiteConfigResponseSchema: ZodObject<{ analytics: ZodDefault; }, $strip>>; auth: ZodOptional>; features: ZodDefault; }, $strip>>; exitIntent: ZodDefault; text: ZodDefault>; }, $strip>>; paragraphNavigation: ZodDefault; }, $strip>>; speakEndPage: ZodDefault; text: ZodDefault>; }, $strip>>; speakInactivity: ZodDefault; text: ZodDefault>; }, $strip>>; speakLinks: ZodDefault; }, $strip>>; speakSelectedText: ZodDefault; }, $strip>>; webPlayer: ZodDefault>; enabled: ZodDefault; layout: ZodDefault>; miniPlayer: ZodDefault>>; navigation: ZodDefault>; paragraphSelector: ZodDefault; pitch: ZodOptional; position: ZodDefault>; rate: ZodOptional; sanitize: ZodDefault>; selector: ZodDefault; theme: ZodDefault>; voice: ZodOptional>>; volume: ZodOptional; }, $strip>>; welcomeMessage: ZodDefault; text: ZodDefault>; }, $strip>>; welcomeMessageOnce: ZodDefault; }, $strip>>; voice: ZodDefault; pitch: ZodDefault; rate: ZodDefault; volume: ZodDefault; }, $strip>>; }, $strip>; ``` Defined in: [src/schemas/website.ts:366](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L366) Full website config response from GET /v2/config. *** ### WebsiteFeaturesSchema [Section titled “WebsiteFeaturesSchema”](#websitefeaturesschema) ```ts const WebsiteFeaturesSchema: ZodObject<{ accessibilityNavigation: ZodDefault; }, $strip>>; exitIntent: ZodDefault; text: ZodDefault>; }, $strip>>; paragraphNavigation: ZodDefault; }, $strip>>; speakEndPage: ZodDefault; text: ZodDefault>; }, $strip>>; speakInactivity: ZodDefault; text: ZodDefault>; }, $strip>>; speakLinks: ZodDefault; }, $strip>>; speakSelectedText: ZodDefault; }, $strip>>; webPlayer: ZodDefault; progress: ZodDefault; skip: ZodDefault; speed: ZodDefault; time: ZodDefault; }, $strip>>; enabled: ZodDefault; layout: ZodDefault>; mode: ZodDefault>; }, $strip>>; miniPlayer: ZodDefault>; enabled: ZodDefault; position: ZodDefault>; }, $strip>>>; navigation: ZodDefault; paragraphHighlight: ZodDefault; }, $strip>>; paragraphSelector: ZodDefault; pitch: ZodOptional; position: ZodDefault, ZodObject<{ at: ZodDefault<...>; target: ZodString; }, $strip>]>>; rate: ZodOptional; sanitize: ZodDefault; exclude: ZodDefault>; }, $strip>>; selector: ZodDefault; theme: ZodDefault, ZodObject<{ accent: ZodOptional<...>; accentSoft: ZodOptional<...>; bg: ZodOptional<...>; border: ZodOptional<...>; fg: ZodOptional<...>; fill: ZodOptional<...>; hover: ZodOptional<...>; muted: ZodOptional<...>; track: ZodOptional<...>; }, $strip>]>>; voice: ZodOptional, ZodObject<{ gender: ...; isByok: ...; lang: ...; name: ...; provider: ...; }, $strip>]>>>; volume: ZodOptional; }, $strip>>; welcomeMessage: ZodDefault; text: ZodDefault>; }, $strip>>; welcomeMessageOnce: ZodDefault; }, $strip>; ``` Defined in: [src/schemas/website.ts:306](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L306) Aggregated per-website feature flags returned by `GET /v2/config`. *** ### WebsiteVoiceSchema [Section titled “WebsiteVoiceSchema”](#websitevoiceschema) ```ts const WebsiteVoiceSchema: ZodObject<{ name: ZodDefault; pitch: ZodDefault; rate: ZodDefault; volume: ZodDefault; }, $strip>; ``` Defined in: [src/schemas/website.ts:330](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L330) Voice profile from the dashboard — curated subset of voice\_profiles table. *** ### WelcomeMessageFeatureSchema [Section titled “WelcomeMessageFeatureSchema”](#welcomemessagefeatureschema) ```ts const WelcomeMessageFeatureSchema: ZodObject<{ enabled: ZodDefault; text: ZodDefault>; }, $strip>; ``` Defined in: [src/schemas/website.ts:16](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/website.ts#L16) Per-feature configuration. Each feature has `enabled` and optional text/settings. ## Functions [Section titled “Functions”](#functions) ### formatProsodyApplied() [Section titled “formatProsodyApplied()”](#formatprosodyapplied) ```ts function formatProsodyApplied(knobs): string; ``` Defined in: [src/schemas/prosody.ts:53](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/prosody.ts#L53) Format a set/iterable of knobs into the comma-separated header value. Output order follows [PROSODY\_KNOBS](/api/types/src/#prosody_knobs) so two calls with the same inputs produce byte-identical headers (cache-key friendly). #### Parameters [Section titled “Parameters”](#parameters-3) | Parameter | Type | | --------- | --------------------------------------------------- | | `knobs` | `Iterable`\<`"pitch"` \| `"rate"` \| `"volume"`> | #### Returns [Section titled “Returns”](#returns-5) `string` *** ### getDefaultFormat() [Section titled “getDefaultFormat()”](#getdefaultformat) ```ts function getDefaultFormat(engine): "mp3" | "ogg" | "wav"; ``` Defined in: [src/schemas/core.ts:119](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L119) Get the default audio format for a TTS engine. #### Parameters [Section titled “Parameters”](#parameters-4) | Parameter | Type | | --------- | --------------------------------------------------------------------- | | `engine` | `"g1"` \| `"g2"` \| `"g3"` \| `"g5"` \| `"gwn"` \| `"msv"` \| `"oai"` | #### Returns [Section titled “Returns”](#returns-6) `"mp3"` | `"ogg"` | `"wav"` *** ### isAudioFormat() [Section titled “isAudioFormat()”](#isaudioformat) ```ts function isAudioFormat(value): value is "mp3" | "ogg" | "wav"; ``` Defined in: [src/guards.ts:65](https://github.com/responsivevoice/types/blob/v2.0.1/src/guards.ts#L65) Check if a value is a valid audio format #### Parameters [Section titled “Parameters”](#parameters-5) | Parameter | Type | | --------- | --------- | | `value` | `unknown` | #### Returns [Section titled “Returns”](#returns-7) value is "mp3" | "ogg" | "wav" *** ### isBrowserVoiceInfo() [Section titled “isBrowserVoiceInfo()”](#isbrowservoiceinfo) ```ts function isBrowserVoiceInfo(value): value is { default?: boolean; lang: string; localService: boolean; name: string; voiceURI: string }; ``` Defined in: [src/guards.ts:157](https://github.com/responsivevoice/types/blob/v2.0.1/src/guards.ts#L157) Check if a value is a valid BrowserVoiceInfo object #### Parameters [Section titled “Parameters”](#parameters-6) | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns [Section titled “Returns”](#returns-8) `value is { default?: boolean; lang: string; localService: boolean; name: string; voiceURI: string }` True if the value is a valid BrowserVoiceInfo object *** ### isFormatSupportedByEngine() [Section titled “isFormatSupportedByEngine()”](#isformatsupportedbyengine) ```ts function isFormatSupportedByEngine(engine, format): boolean; ``` Defined in: [src/schemas/core.ts:111](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/core.ts#L111) Check whether a given audio format is supported by a TTS engine. #### Parameters [Section titled “Parameters”](#parameters-7) | Parameter | Type | | --------- | --------------------------------------------------------------------- | | `engine` | `"g1"` \| `"g2"` \| `"g3"` \| `"g5"` \| `"gwn"` \| `"msv"` \| `"oai"` | | `format` | `"mp3"` \| `"ogg"` \| `"wav"` | #### Returns [Section titled “Returns”](#returns-9) `boolean` *** ### isPlatformReport() [Section titled “isPlatformReport()”](#isplatformreport) ```ts function isPlatformReport(value): value is { browser: string; browserVersion: string; deviceType?: "desktop" | "mobile" | "tablet"; os: string; osVersion: string }; ``` Defined in: [src/guards.ts:166](https://github.com/responsivevoice/types/blob/v2.0.1/src/guards.ts#L166) Check if a value is a valid PlatformReport object #### Parameters [Section titled “Parameters”](#parameters-8) | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns [Section titled “Returns”](#returns-10) value is { browser: string; browserVersion: string; deviceType?: "desktop" | "mobile" | "tablet"; os: string; osVersion: string } True if the value is a valid PlatformReport object *** ### isRVErrorEvent() [Section titled “isRVErrorEvent()”](#isrverrorevent) ```ts function isRVErrorEvent(value): value is { code?: string; message: string; timestamp: number; type: "OnError" }; ``` Defined in: [src/guards.ts:135](https://github.com/responsivevoice/types/blob/v2.0.1/src/guards.ts#L135) Check if a value is a valid RVErrorEvent object #### Parameters [Section titled “Parameters”](#parameters-9) | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns [Section titled “Returns”](#returns-11) `value is { code?: string; message: string; timestamp: number; type: "OnError" }` True if the value is a valid RVErrorEvent object *** ### isRVEvent() [Section titled “isRVEvent()”](#isrvevent) ```ts function isRVEvent(value): value is { timestamp: number; type: "OnLoad" | "OnReady" | "OnStart" | "OnEnd" | "OnError" | "OnPause" | "OnResume" | "OnServiceSwitched" | "OnClickEvent" | "OnAllowSpeechClicked" | "OnPartStart" | "OnPartEnd" | "OnVoiceResolved" }; ``` Defined in: [src/guards.ts:126](https://github.com/responsivevoice/types/blob/v2.0.1/src/guards.ts#L126) Check if a value is a valid RVEvent object #### Parameters [Section titled “Parameters”](#parameters-10) | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns [Section titled “Returns”](#returns-12) value is { timestamp: number; type: "OnLoad" | "OnReady" | "OnStart" | "OnEnd" | "OnError" | "OnPause" | "OnResume" | "OnServiceSwitched" | "OnClickEvent" | "OnAllowSpeechClicked" | "OnPartStart" | "OnPartEnd" | "OnVoiceResolved" } True if the value is a valid RVEvent object *** ### isRVEventType() [Section titled “isRVEventType()”](#isrveventtype) ```ts function isRVEventType(value): value is "OnLoad" | "OnReady" | "OnStart" | "OnEnd" | "OnError" | "OnPause" | "OnResume" | "OnServiceSwitched" | "OnClickEvent" | "OnAllowSpeechClicked" | "OnPartStart" | "OnPartEnd" | "OnVoiceResolved"; ``` Defined in: [src/guards.ts:86](https://github.com/responsivevoice/types/blob/v2.0.1/src/guards.ts#L86) Check if a value is a valid event type #### Parameters [Section titled “Parameters”](#parameters-11) | Parameter | Type | | --------- | --------- | | `value` | `unknown` | #### Returns [Section titled “Returns”](#returns-13) value is "OnLoad" | "OnReady" | "OnStart" | "OnEnd" | "OnError" | "OnPause" | "OnResume" | "OnServiceSwitched" | "OnClickEvent" | "OnAllowSpeechClicked" | "OnPartStart" | "OnPartEnd" | "OnVoiceResolved" *** ### isRVServiceSwitchedEvent() [Section titled “isRVServiceSwitchedEvent()”](#isrvserviceswitchedevent) ```ts function isRVServiceSwitchedEvent(value): value is { from: "g1" | "g2" | "g3" | "g5" | "gwn" | "msv" | "oai" | "native"; timestamp: number; to: "g1" | "g2" | "g3" | "g5" | "gwn" | "msv" | "oai" | "native"; type: "OnServiceSwitched" }; ``` Defined in: [src/guards.ts:144](https://github.com/responsivevoice/types/blob/v2.0.1/src/guards.ts#L144) Check if a value is a valid RVServiceSwitchedEvent object #### Parameters [Section titled “Parameters”](#parameters-12) | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns [Section titled “Returns”](#returns-14) value is { from: "g1" | "g2" | "g3" | "g5" | "gwn" | "msv" | "oai" | "native"; timestamp: number; to: "g1" | "g2" | "g3" | "g5" | "gwn" | "msv" | "oai" | "native"; type: "OnServiceSwitched" } True if the value is a valid RVServiceSwitchedEvent object *** ### isSynthesizeRequest() [Section titled “isSynthesizeRequest()”](#issynthesizerequest) ```ts function isSynthesizeRequest(value): value is { engine?: "g1" | "g2" | "g3" | "g5" | "gwn" | "msv" | "oai"; format?: "mp3" | "ogg" | "wav"; gender?: "male" | "female"; lang?: string; name?: string; pitch?: number; rate?: number; text: string; voice?: string; volume?: number }; ``` Defined in: [src/guards.ts:117](https://github.com/responsivevoice/types/blob/v2.0.1/src/guards.ts#L117) Check if a value is a valid SynthesizeRequest object #### Parameters [Section titled “Parameters”](#parameters-13) | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns [Section titled “Returns”](#returns-15) value is { engine?: "g1" | "g2" | "g3" | "g5" | "gwn" | "msv" | "oai"; format?: "mp3" | "ogg" | "wav"; gender?: "male" | "female"; lang?: string; name?: string; pitch?: number; rate?: number; text: string; voice?: string; volume?: number } True if the value is a valid SynthesizeRequest object *** ### isSystemVoice() [Section titled “isSystemVoice()”](#issystemvoice) ```ts function isSystemVoice(value): value is { deprecated?: boolean; fallbackVoice?: boolean; gender?: string; id: number; lang?: string; name: string; pitch?: number; rate?: number; service?: "g1" | "g2" | "g3" | "g5" | "gwn" | "msv" | "oai"; timerSpeed?: number; voiceName?: string; volume?: number }; ``` Defined in: [src/guards.ts:108](https://github.com/responsivevoice/types/blob/v2.0.1/src/guards.ts#L108) Check if a value is a valid SystemVoice object #### Parameters [Section titled “Parameters”](#parameters-14) | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns [Section titled “Returns”](#returns-16) value is { deprecated?: boolean; fallbackVoice?: boolean; gender?: string; id: number; lang?: string; name: string; pitch?: number; rate?: number; service?: "g1" | "g2" | "g3" | "g5" | "gwn" | "msv" | "oai"; timerSpeed?: number; voiceName?: string; volume?: number } True if the value is a valid SystemVoice object *** ### isTTSService() [Section titled “isTTSService()”](#isttsservice) ```ts function isTTSService(value): value is "g1" | "g2" | "g3" | "g5" | "gwn" | "msv" | "oai"; ``` Defined in: [src/guards.ts:58](https://github.com/responsivevoice/types/blob/v2.0.1/src/guards.ts#L58) Check if a value is a valid TTS service #### Parameters [Section titled “Parameters”](#parameters-15) | Parameter | Type | | --------- | --------- | | `value` | `unknown` | #### Returns [Section titled “Returns”](#returns-17) value is "g1" | "g2" | "g3" | "g5" | "gwn" | "msv" | "oai" *** ### isVoice() [Section titled “isVoice()”](#isvoice) ```ts function isVoice(value): value is { deprecated?: boolean; flag: string; gender: "f" | "m"; isByok?: boolean; lang: string; name: string; provider?: string; voiceIDs: number[] }; ``` Defined in: [src/guards.ts:99](https://github.com/responsivevoice/types/blob/v2.0.1/src/guards.ts#L99) Check if a value is a valid Voice object #### Parameters [Section titled “Parameters”](#parameters-16) | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns [Section titled “Returns”](#returns-18) value is { deprecated?: boolean; flag: string; gender: "f" | "m"; isByok?: boolean; lang: string; name: string; provider?: string; voiceIDs: number\[] } True if the value is a valid Voice object *** ### isVoiceGender() [Section titled “isVoiceGender()”](#isvoicegender) ```ts function isVoiceGender(value): value is "male" | "female"; ``` Defined in: [src/guards.ts:72](https://github.com/responsivevoice/types/blob/v2.0.1/src/guards.ts#L72) Check if a value is a valid voice gender #### Parameters [Section titled “Parameters”](#parameters-17) | Parameter | Type | | --------- | --------- | | `value` | `unknown` | #### Returns [Section titled “Returns”](#returns-19) value is "male" | "female" *** ### isVoiceGenderShort() [Section titled “isVoiceGenderShort()”](#isvoicegendershort) ```ts function isVoiceGenderShort(value): value is "f" | "m"; ``` Defined in: [src/guards.ts:79](https://github.com/responsivevoice/types/blob/v2.0.1/src/guards.ts#L79) Check if a value is a valid short gender #### Parameters [Section titled “Parameters”](#parameters-18) | Parameter | Type | | --------- | --------- | | `value` | `unknown` | #### Returns [Section titled “Returns”](#returns-20) value is "f" | "m" *** ### isVoiceReportRequest() [Section titled “isVoiceReportRequest()”](#isvoicereportrequest) ```ts function isVoiceReportRequest(value): value is { platform: { browser: string; browserVersion: string; deviceType?: "desktop" | "mobile" | "tablet"; os: string; osVersion: string }; sdkVersion?: string; timestamp: string; voices: { default?: boolean; lang: string; localService: boolean; name: string; voiceURI: string }[] }; ``` Defined in: [src/guards.ts:175](https://github.com/responsivevoice/types/blob/v2.0.1/src/guards.ts#L175) Check if a value is a valid VoiceReportRequest object #### Parameters [Section titled “Parameters”](#parameters-19) | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns [Section titled “Returns”](#returns-21) value is { platform: { browser: string; browserVersion: string; deviceType?: "desktop" | "mobile" | "tablet"; os: string; osVersion: string }; sdkVersion?: string; timestamp: string; voices: { default?: boolean; lang: string; localService: boolean; name: string; voiceURI: string }\[] } True if the value is a valid VoiceReportRequest object *** ### isVoiceReportResponse() [Section titled “isVoiceReportResponse()”](#isvoicereportresponse) ```ts function isVoiceReportResponse(value): value is { count: number; systemVoices: { deprecated?: boolean; fallbackVoice?: boolean; gender?: string; id: number; lang?: string; name: string; pitch?: number; rate?: number; service?: "g1" | "g2" | "g3" | "g5" | "gwn" | "msv" | "oai"; timerSpeed?: number; voiceName?: string; volume?: number }[]; voices: { deprecated?: boolean; flag: string; gender: "f" | "m"; isByok?: boolean; lang: string; name: string; provider?: string; voiceIDs: number[] }[] }; ``` Defined in: [src/guards.ts:184](https://github.com/responsivevoice/types/blob/v2.0.1/src/guards.ts#L184) Check if a value is a valid VoiceReportResponse object #### Parameters [Section titled “Parameters”](#parameters-20) | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns [Section titled “Returns”](#returns-22) value is { count: number; systemVoices: { deprecated?: boolean; fallbackVoice?: boolean; gender?: string; id: number; lang?: string; name: string; pitch?: number; rate?: number; service?: "g1" | "g2" | "g3" | "g5" | "gwn" | "msv" | "oai"; timerSpeed?: number; voiceName?: string; volume?: number }\[]; voices: { deprecated?: boolean; flag: string; gender: "f" | "m"; isByok?: boolean; lang: string; name: string; provider?: string; voiceIDs: number\[] }\[] } True if the value is a valid VoiceReportResponse object *** ### parseProsodyApplied() [Section titled “parseProsodyApplied()”](#parseprosodyapplied) ```ts function parseProsodyApplied(value): Set<"pitch" | "rate" | "volume">; ``` Defined in: [src/schemas/prosody.ts:36](https://github.com/responsivevoice/types/blob/v2.0.1/src/schemas/prosody.ts#L36) Parse the `RV-Prosody-Applied` header value into a set of knobs. Tolerates null/undefined (legacy server, no header) and empty string (server applied nothing) by returning an empty set. Unknown tokens are dropped silently — defensive against future server additions an old client doesn't know. #### Parameters [Section titled “Parameters”](#parameters-21) | Parameter | Type | | --------- | --------------------------------- | | `value` | `string` \| `null` \| `undefined` | #### Returns [Section titled “Returns”](#returns-23) `Set`\<`"pitch"` | `"rate"` | `"volume"`>