This is the full developer documentation for ResponsiveVoice # ResponsiveVoice > TypeScript-first, from the browser to the server. Quickstart ## Speak in a few lines * npm (browser) ```bash npm install @responsivevoice/core ``` ```ts import { getResponsiveVoice } from '@responsivevoice/core'; const rv = await getResponsiveVoice({ apiKey: 'YOUR_API_KEY' }); rv.speak('Hello, world!'); ``` * CDN (browser) ```html ``` * REST (Node.js) ```bash npm install @responsivevoice/api-client ``` ```ts 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 world', voice: 'UK English Female', format: 'mp3', }); ``` Packages ## Modular by design ### @responsivevoice/core The heart — and lungs — of ResponsiveVoice: the browser client that speaks text aloud, with a familiar API. ### @responsivevoice/api-client REST API client with retry logic, response validation, and beautiful error handling. ### @responsivevoice/types Shared schemas and types used across the entire ecosystem. Why ResponsiveVoice ## Built for the modern web ### TypeScript First Full TypeScript support with strict types and IntelliSense. ### Universal builds 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. Integrations ## Prefer no code? [ Add text-to-speech to WordPress The official plugin — a floating WebPlayer, Listen buttons, and a Gutenberg block. No code required. Get the plugin ](/integrations/wordpress/) *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 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 * [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 ```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 * [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 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 * **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 * [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 * 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 | 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 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 * [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 ```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 | 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 ```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 * [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 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 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 Any element carrying `data-rv-skip` is excluded from narration: ```html

Read this paragraph.

This block is skipped.

Continue reading from here.

``` ## 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 * **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 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 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 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 `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 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 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 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 * [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 The main client library for browser text-to-speech. Both paths deliver the same package — pick the one that fits your project: * **Browser bundle (CDN)** — no build step; add one script tag and use the global `responsiveVoice`. Best for plain HTML, prototypes, CMS sites, and legacy pages. Call `init()` with your API key — without it you get demo mode (browser default voice only). * **npm** — for apps with a bundler (Vite, webpack, Next). Install and import. - Browser bundle (CDN) ```html ``` - npm ```bash npm install @responsivevoice/core # or: pnpm add @responsivevoice/core # or: yarn add @responsivevoice/core ``` ```typescript import { getResponsiveVoice } from '@responsivevoice/core'; const rv = await getResponsiveVoice({ apiKey: 'YOUR_API_KEY' }); ``` ## API client REST API client for direct server communication. * npm ```bash npm install @responsivevoice/api-client ``` * pnpm ```bash pnpm add @responsivevoice/api-client ``` * yarn ```bash yarn add @responsivevoice/api-client ``` ## Types package `@responsivevoice/types` (TypeScript types + Zod schemas) ships automatically as a dependency of the packages above, and `api-client` re-exports the common ones — so you rarely install it directly. If you want the schemas standalone: `npm install @responsivevoice/types`. ## Requirements ### Browsers The browser bundle (CDN) is Babel + core-js polyfilled and works in Chrome 69+, Firefox 65+, Safari 12+, Edge 79+, iOS Safari 12+, Chrome Android 69+, Android WebView 69+ without any additional setup. ESM/CJS packages are syntax-compatible but leave browser polyfilling to your bundler; see [Browser Support](/guides/browser-support/) for each package's minimum browser versions. ### Node.js | Package | Minimum | Full functionality | | ----------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `@responsivevoice/types` | 14+ | All features | | `@responsivevoice/text` | 14+ | All features | | `@responsivevoice/api-client` | 16+ | HTTP synthesis requires Node 18+ for native `fetch` and `Blob`. On Node 16–17, pass a `fetch` implementation via the `fetch` config option (e.g. `node-fetch` or `undici`). | | `@responsivevoice/core` | 16+ | Browser-only (Web Speech API + audio playback); Node is the build environment (bundle with Vite/webpack), not a runtime target | | `@responsivevoice/features` | 14+ | Browser-only (DOM APIs) | WebSocket streaming requires Node 22+ for the native `WebSocket` global, or pass any W3C-compatible WebSocket implementation (e.g. the `ws` package) via the `WebSocket` config option. ### TypeScript 5.0+ (optional, but recommended). Full type definitions included in all packages. # Migration Guide > Upgrade from legacy responsivevoice.js to @responsivevoice/core This guide helps you migrate from the legacy `responsivevoice.js` script to the modern `@responsivevoice/core` package. ## What's New The new package provides: * **TypeScript support** with full type definitions * **Modern build formats** (ESM, CJS, browser bundle) * **Tree-shakeable exports** * **Better error handling** * **API-first architecture** (voice data fetched at runtime) * **Full backward compatibility** with the legacy API * **Access to Premium neural voices** from several specialized TTS Providers (via bring-your-own-keys) * **New UI features** — see the new [ResponsiveVoice WebPlayer](/guides/web-player/) in action in the [live example](https://examples.responsivevoice.org/browser/web-player/) and [how to customize it](https://examples.responsivevoice.org/browser/web-player-customization/). Tip The migration is designed to be a drop-in replacement. Most code will work without changes. ## Installation Changes ### Before ```html ``` ### After The closest migration keeps a script tag — load the browser bundle from the CDN and move your key into an `init()` call. Use npm instead if your app has a bundler. * Browser bundle (CDN) ```html ``` * npm ```bash npm install @responsivevoice/core ``` ```typescript import { getResponsiveVoice } from '@responsivevoice/core'; const rv = await getResponsiveVoice({ apiKey: 'YOUR_KEY' }); ``` ## API Mapping The core API remains the same: | Legacy | Modern | Notes | | ----------------------------- | ---------------- | -------------- | | `responsiveVoice.speak()` | `rv.speak()` | Same signature | | `responsiveVoice.cancel()` | `rv.cancel()` | Same behavior | | `responsiveVoice.pause()` | `rv.pause()` | Same behavior | | `responsiveVoice.resume()` | `rv.resume()` | Same behavior | | `responsiveVoice.getVoices()` | `rv.getVoices()` | Same behavior | | `responsiveVoice.isPlaying()` | `rv.isPlaying()` | Same behavior | In the browser bundle the global stays `responsiveVoice`; with npm you call the same methods on the `rv` instance from `getResponsiveVoice()`. The signatures are identical either way. ## Configuration Changes ### Before ```javascript // Global configuration via URL parameter ; // Or via global variable window.responsiveVoice.setDefaultVoice('UK English Female'); ``` ### After * Browser bundle (CDN) ```html ``` * npm ```typescript import { getResponsiveVoice } from '@responsivevoice/core'; const rv = await getResponsiveVoice({ apiKey: 'YOUR_KEY', defaultVoice: 'UK English Female', }); ``` ## Event System Per-call event callbacks are unchanged from the legacy script: * Browser bundle (CDN) ```javascript responsiveVoice.speak('Hello', 'UK English Female', { onstart: () => console.log('Started'), onend: () => console.log('Ended'), }); ``` * npm ```typescript rv.speak('Hello', 'UK English Female', { onstart: () => console.log('Started'), onend: () => console.log('Ended'), }); ``` ## Breaking Changes Caution The following changes may require code updates: ### 1. Voice Data is Fetched at Runtime Voice mappings are no longer bundled in the JavaScript file — `init()` fetches them from the API and caches them locally. **Impact:** First initialization needs a network connection to fetch the voice catalog. There's nothing to pre-fetch — `init()` already loads voices before it resolves. ### 2. No Internet Explorer Support The browser bundle (CDN) ships the polyfills modern browsers need and targets Chrome 69+, Firefox 65+, Safari 12+, Edge 79+, iOS Safari 12+, Chrome Android 69+, Android WebView 69+. Internet Explorer 11 is not supported. **Impact:** If you need to support IE11 or similarly old browsers, stay on the legacy `responsivevoice.js` (v1). ## TypeScript Support The new package includes full TypeScript definitions: ```typescript import { getResponsiveVoice, type ResponsiveVoiceInitOptions, } from '@responsivevoice/core'; import type { SpeakParams } from '@responsivevoice/types'; const options: ResponsiveVoiceInitOptions = { apiKey: 'YOUR_KEY', }; const rv = await getResponsiveVoice(options); const params: SpeakParams = { pitch: 1.0, rate: 1.0, onend: () => console.log('Done'), }; rv.speak('Hello', 'UK English Female', params); ``` ## Troubleshooting ### "Voice not found" Error Ensure the voice name exactly matches an available voice: ```typescript const voices = rv.getVoices(); console.log(voices.map((v) => v.name)); ``` ### "API key required" Error Make sure to initialize with an API key: ```typescript const rv = await getResponsiveVoice({ apiKey: 'YOUR_KEY' }); ``` ### Audio Not Playing on iOS Mobile browsers (iOS, and Android Chrome) block autoplay, but ResponsiveVoice handles this automatically with a built-in permission prompt that captures the first tap and unlocks audio. If you've disabled the prompt, trigger speech from your own gesture handler instead: ```typescript button.addEventListener('click', () => { rv.speak('Hello'); }); ``` See the [FAQ](/guides/faq/#does-responsivevoice-work-on-ios) for details. ## Need Help? * [API Reference](/api/core/src/) * [Support](https://responsivevoice.org/support) # Quick Start > Get up and running with ResponsiveVoice in minutes ## Basic Usage Drop in the script tag or install from npm — both reach the same API: * Browser bundle (CDN) ```html ``` * npm ```bash npm install @responsivevoice/core # or: pnpm add @responsivevoice/core / yarn add @responsivevoice/core ``` ```typescript import { getResponsiveVoice } from '@responsivevoice/core'; const rv = await getResponsiveVoice({ apiKey: 'YOUR_API_KEY' }); rv.speak('Hello, world!'); ``` Note The examples below use the `rv` instance returned by `getResponsiveVoice()` (npm). With the browser bundle, call the same methods on the global `responsiveVoice`. ## Voice Selection ```typescript // Get available voices const voices = rv.getVoices(); console.log(voices); // Speak with a specific voice rv.speak('Hello', 'UK English Female'); rv.speak('Hello', 'US English Male'); rv.speak('Hallo', 'Deutsch Female'); ``` ## Playback Control ```typescript // Pause speech rv.pause(); // Resume speech rv.resume(); // Cancel speech rv.cancel(); // Check if speaking if (rv.isPlaying()) { console.log('Currently speaking'); } ``` ## Events ```typescript // Per-call callbacks — bound to this speak() call rv.speak('Hello with events', 'UK English Female', { onstart: () => console.log('Speech started'), onend: () => console.log('Speech ended'), onerror: (error) => console.error('Speech error:', error), onboundary: (charIndex, name) => console.log('Word boundary:', charIndex, name), }); // Global events — fire across every speak() call (pause/resume live here) rv.addEventListener('OnPause', () => console.log('Speech paused')); rv.addEventListener('OnResume', () => console.log('Speech resumed')); ``` Tip For more advanced usage, see the [Voice Selection](/guides/voice-selection/) and [Events](/guides/events/) guides. # 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 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 Fetching one topic? Use a section bundle or `/llms-small.txt`. Reserve `/llms-full.txt` for whole-corpus ingestion — it is large and ends with the full generated API reference. [/llms.txt ](/llms.txt)Index of the documentation sets, following the llmstxt.org convention. Start here. [Section bundles ](/_llms-txt/getting-started.txt)One topic per file: getting-started, guides, sdks, examples, rest-api at /\_llms-txt/.txt. Smallest fetch for a single topic. [/llms-small.txt ](/llms-small.txt)Abridged build, API reference removed. Best for conceptual queries on a budget. [/llms-full.txt ](/llms-full.txt)The complete documentation as a single text file, including the generated API reference. Large. [/llms.md ](/llms.md)A Markdown index of every page. ## Per-page Markdown Append `.md` to any documentation URL to get its Markdown source — for example, `/getting-started/installation.md`. ## Discovery You don't need to know these URLs in advance — agents and crawlers can find them automatically: * **Every page links to them.** Each page's `` includes `` tags pointing to `/llms.txt` and `/llms.md`, so fetching any page reveals the machine-readable versions. * **`/llms.txt` sits at the site root**, following the [llmstxt.org](https://llmstxt.org) convention — the standard place agents look first. * **`robots.txt` allows crawling** and lists the sitemap (`/sitemap-index.xml`) and the `llms.*` files. # 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 | 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 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 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 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 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 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 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 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 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 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 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 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 ![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* | Before, after, or inline with the content, 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 ![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 ![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 ![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 #### The player doesn't 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 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 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 Confirm **Floating mini-player** is on, then scroll until the main player leaves view while it is playing. ### 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 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 targets modern evergreen browsers (released \~2020 onward), with automatic fallback. Base text-to-speech needs the Web Speech API or a `fetch`-capable runtime; some features require newer browsers — see [Feature requirements](#feature-requirements). Support is shown per delivery method. The **browser bundle (CDN)** is Babel + core-js polyfilled, so it reaches the widest range; **`@responsivevoice/core`** and **`@responsivevoice/api-client`** are raw npm packages whose minimum versions reflect the browser APIs they use — your bundler supplies any transpilation. [Browser bundle (CDN)](/getting-started/quick-start/) * ![Chrome](/_astro/chrome.CRByiUFQ_ZIwTCu.svg)Chrome69+ * ![Firefox](/_astro/firefox.1bWoP6pv_ZXpkDg.svg)Firefox65+ * ![Safari](/_astro/safari.na3_-uQk_PMAUK.svg)Safari12+ * ![Edge](/_astro/edge.HDH_c98u_1zCODK.svg)Edge79+ * ![iOS Safari](/_astro/safari.na3_-uQk_PMAUK.svg)iOS Safari12+ * ![Chrome Android](/_astro/chrome.CRByiUFQ_ZIwTCu.svg)Chrome Android69+ * ![Android WebView](/_astro/android-webview_64x64._FpYT5CQ_1iPoo.webp)Android WebView69+ Polyfilled via Babel + core-js — the widest supported tier. [@responsivevoice/core](/getting-started/installation/#core-package) * ![Chrome](/_astro/chrome.CRByiUFQ_ZIwTCu.svg)Chrome69+ * ![Firefox](/_astro/firefox.1bWoP6pv_ZXpkDg.svg)Firefox65+ * ![Safari](/_astro/safari.na3_-uQk_PMAUK.svg)Safari14+ * ![Edge](/_astro/edge.HDH_c98u_1zCODK.svg)Edge79+ * ![iOS Safari](/_astro/safari.na3_-uQk_PMAUK.svg)iOS Safari14+ * ![Chrome Android](/_astro/chrome.CRByiUFQ_ZIwTCu.svg)Chrome Android69+ * ![Android WebView](/_astro/android-webview_64x64._FpYT5CQ_1iPoo.webp)Android WebView69+ [@responsivevoice/api-client](/sdks/typescript/) * ![Chrome](/_astro/chrome.CRByiUFQ_ZIwTCu.svg)Chrome66+ * ![Firefox](/_astro/firefox.1bWoP6pv_ZXpkDg.svg)Firefox65+ * ![Safari](/_astro/safari.na3_-uQk_PMAUK.svg)Safari12+ * ![Edge](/_astro/edge.HDH_c98u_1zCODK.svg)Edge79+ * ![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+ *Minimum versions are generated from the APIs each package actually uses ([MDN Browser Compat Data](https://github.com/mdn/browser-compat-data)). npm packages are raw and unpolyfilled; the bundle's reflect its Babel + core-js polyfills.* Note These npm minimum versions are raw and unpolyfilled. To support older browsers, load the CDN bundle (already polyfilled) or add polyfills in your build — see [Polyfilling for older browsers](#polyfilling-for-older-browsers). Tip `@responsivevoice/types` is pure TypeScript with no browser runtime requirements. ## Feature requirements Some capabilities need newer browsers than the base minimum. All are degradable — when the API is missing, ResponsiveVoice falls back automatically. | Feature | Requires | Minimum | | -------------------------- | ----------------- | -------------------------------------------------- | | HTTP/WebSocket streaming | MediaSource | iOS Safari 13+ | | Web player (in-page UI) | Shadow DOM | Firefox 63+, Edge 79+ | | Native (Web Speech) voices | `speechSynthesis` | unavailable in Android WebView (falls back to API) | Note Firefox has limited native voice support. ResponsiveVoice automatically uses the fallback API when needed. ## Polyfilling for older browsers The npm packages ship modern JavaScript and leave transpilation to your bundler — the common convention. To support older browsers, add [core-js](https://github.com/zloirock/core-js) through [@babel/preset-env](https://babeljs.io/docs/babel-preset-env) with a browserslist target: babel.config.js ```js module.exports = { presets: [['@babel/preset-env', { useBuiltIns: 'usage', corejs: '3' }]], }; ``` This polyfills JavaScript built-ins like `URLSearchParams` and `Promise`. DOM and platform APIs (Shadow DOM, MediaSource) can't be polyfilled — those features need their listed browsers, but base text-to-speech still works without them. ## How Fallback Works ![Diagram](/d2/docs/guides/browser-support-0.svg) ## 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 ### 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 * Apple voices with "(Enhanced)" variants * Good offline voice quality * iOS requires user gesture to begin playback * Some voices locked to specific iOS versions ### Firefox * Limited native voice support * Falls back to API more frequently * No boundary events when using fallback * Full functionality with API fallback ### Edge * Windows voices available (David, Zira, etc.) * Good Web Speech API support * Microsoft neural voices on Windows 10+ ## Mobile Considerations ### 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 * 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 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 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) 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 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 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 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 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 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 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 ```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 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 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 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 Pass the same handler reference you registered: ```typescript const handler = () => console.log('Speech started'); rv.addEventListener('OnStart', handler); rv.removeEventListener('OnStart', handler); ``` ## 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 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 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 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? 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? 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? 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? 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? The base catalog includes 100+ voices across 50+ 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? 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? 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? 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? 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 ResponsiveVoice automatically splits long text into smaller chunks for optimal playback. This ensures reliable speech synthesis even with large amounts of text. ## 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 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 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 | 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 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 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 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 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 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 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 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 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 ```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 ```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 | 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 ### 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 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 Observe what selectors are being passed without changing behavior: ```typescript resolveVoice: (selector) => { console.log('[RV] resolving voice:', selector); return selector; }, ``` ## 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 Layout controls where the player appears and how much space it uses. | Config option | Default | What it does | | ---------------- | ---------- | -------------------------------------------------------------------------------------------------------------- | | `position` | `'before'` | Keyword (`before` / `after` / `inline`) relative to `selector`, or `{ target, at }` for a custom mount 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 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 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 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 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 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 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 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 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 ### The player doesn't 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` 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 * `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 `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 Call `handle.unmount()` before removing the host element — the player keeps listeners on the article and document until you do. ## 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 * **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 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 * **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 * [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. # WordPress Plugin > Add text-to-speech to WordPress posts and pages with the ResponsiveVoice plugin — the v2 WebPlayer, classic Listen buttons, and a Gutenberg block. ![ResponsiveVoice for WordPress — "Give your pages a voice", the text-to-speech toolkit for WordPress, showing the WebPlayer control and a v2 badge on a purple gradient.](/img/wordpress/banner.png) The [**ResponsiveVoice Text To Speech**](https://wordpress.org/plugins/responsivevoice-text-to-speech/) plugin adds spoken audio to WordPress posts and pages. There are two ways to use it: * **The WebPlayer** — an automatic floating audio player that reads a post aloud, with paragraph highlighting and playback controls. No per-post markup required. * **Listen buttons** — classic "read this" buttons you place with a shortcode or a Gutenberg block. With a free API key, both speak in **100+ voices across 50+ languages**. They work on smartphone, tablet, and desktop, with nothing extra to install on your server. ## Requirements | Requirement | Minimum | | ----------- | -------------- | | WordPress | 6.3 | | PHP | 7.4 | | License | GPLv2 or later | An API key is optional but recommended — without one the plugin runs in a limited [demo mode](#get-an-api-key). ## Install and activate 1. Install **ResponsiveVoice Text To Speech** from the [WordPress plugin directory](https://wordpress.org/plugins/responsivevoice-text-to-speech/), or upload the plugin ZIP under **Plugins → Add New → Upload Plugin**. 2. Activate it through the **Plugins** menu. 3. Open the **ResponsiveVoice** admin page from the WordPress sidebar. ## Get an API key Your API key is a **public website identifier**, not a secret — it names your site to the ResponsiveVoice service so the right voice catalog and configuration load. 1. [Register for a free account](https://responsivevoice.org/register). 2. Copy your API key from the [ResponsiveVoice dashboard](https://app.responsivevoice.org). 3. Paste it into the **ResponsiveVoice** admin page in WordPress. Demo mode With no API key the listen buttons and shortcodes still work, speaking with the browser's built-in voice, and the plugin's admin page shows a prompt to register. Adding a free API key unlocks the full voice catalog and the WebPlayer once your domain is verified — its controls appear on the settings page as soon as the key is in place. ![The ResponsiveVoice settings page without an API key: a "Get started" prompt with a Register your website button above the empty API Key field.](/img/wordpress/settings-demo-mode.png) ## Verify your website With an API key set, text to speech activates once your site's domain is verified in the [ResponsiveVoice dashboard](https://app.responsivevoice.org) — on an unverified site the listen buttons and the WebPlayer stay silent. Verification is detected in the visitor's browser — no secret is stored in WordPress. Until your domain is verified, the plugin shows a **"verify your website"** prompt in place of the player, and wp-admin shows a dashboard notice and admin-bar reminder. ![The WordPress dashboard with a ResponsiveVoice warning notice and admin-bar badge prompting to verify the website's domain.](/img/wordpress/verify-cta-notice.png) ## The WebPlayer The WebPlayer is a drop-in article reader — paragraph highlighting, click-to-jump, playback controls, and a floating mini-player that follows the reader once the main controls scroll out of view. Try it live: the [Web Player example](https://examples.responsivevoice.org/browser/web-player/) shows the full player in action. ![A WordPress page on the front end with the WebPlayer pill control sitting above the content, ready to read the page aloud.](/img/wordpress/webplayer-reading-post.png) ### Enable modes The single **ResponsiveVoice** settings page holds your API key and a **WebPlayer** control at the top, with a collapsed **Advanced** section below. The WebPlayer control is a segmented switch: * **Account default** — follow your ResponsiveVoice account setting. * **Enabled** — show the WebPlayer on this site. * **Disabled** — hide the WebPlayer on this site. ### Advanced delivery The **Advanced** section also controls how the ResponsiveVoice library is delivered: from `cdn.responsivevoice.org` (default, always current), pinned to an exact version, or **bundled** — served from your own site, for CSP-strict setups. ### Choose where it shows The WebPlayer switch sets the site-wide default; two finer levels narrow it down: * **Per content type** — the **Show the WebPlayer on** setting toggles it for posts, pages, and custom content types. * **Per post** — a **ResponsiveVoice WebPlayer** panel in the editor sidebar overrides the default for a single post: **Use default**, **Enabled**, or **Disabled**. ![The WordPress page editor sidebar with a ResponsiveVoice WebPlayer panel offering a per-page override dropdown set to Use default.](/img/wordpress/per-post-override.png) ### Customizer The admin page includes a live **customizer** with an instant preview. It surfaces a curated set of the player's options — the rest come from your dashboard configuration, which the plugin's settings layer over: * **Theme** — presets plus custom colors. * **Layout** — how the player sits relative to the content. * **Controls** — which buttons and readouts appear. * **Voice** — the default voice for the player. * **Position** — where the player is placed; it aligns to your theme's content column. ![The ResponsiveVoice settings page in wp-admin: API key, WebPlayer switches, per-content-type toggles, and the customizer with a live preview of the player.](/img/wordpress/settings-customizer.png) For a re-themed player in action, see the [customization example](https://examples.responsivevoice.org/browser/web-player-customization/). For everything the player can do beyond these, see the [Web Player guide](/guides/web-player/) and [dashboard configuration](/guides/app-features/#web-player). ## Listen buttons Prefer a tap-to-listen button over an automatic player? Place one anywhere with a shortcode or the Gutenberg block. Buttons speak with your account's default voice unless you set the `voice` attribute. Output is CSP-clean — the buttons carry `data-*` attributes with no inline JavaScript. ### Shortcodes * Read the whole post Adds a button that reads the entire post or page. ```text [responsivevoice_button] [responsivevoice_button voice="US English Female" buttontext="Play"] ``` Aliases: `[ListenToPostButton]`, `[RVListenButton]`. Defaults: `buttontext="Listen to this"`. * Read a section Wraps a passage; only the enclosed text is read. ```text [responsivevoice]Text you want read aloud[/responsivevoice] [responsivevoice buttonposition="after"]Text read aloud, button after[/responsivevoice] ``` Alias: `[ResponsiveVoice]`. Defaults: `buttontext="Play"`, `buttonposition="before"`. #### Shortcode attributes | Attribute | Applies to | Description | | ---------------- | --------------- | ----------------------------------------- | | `voice` | all | Voice name, e.g. `US English Female`. | | `buttontext` | button, section | Label shown on the button. | | `buttonposition` | section | `before` (default) or `after` the text. | | `class` | button, section | Extra CSS classes on the rendered button. | | `rate` | button, section | Speech rate. | | `pitch` | button, section | Speech pitch. | | `volume` | button, section | Speech volume. | Note `rate`, `pitch`, and `volume` are optional and take a numeric value; leave them off to use the default. Their ranges are those of the underlying ResponsiveVoice library. Voice names come from the same catalog as the rest of ResponsiveVoice — browse it in the [Gutenberg block's](#gutenberg-block) **Voice** picker or the [customizer's](#customizer) **Voice** dropdown, or call `responsiveVoice.getVoices()`. See [Voice Selection](/guides/voice-selection/) for how fallback works and the broader speech options. ### Gutenberg block In the block editor, add the **Listen Button** block (`rvtts/listen-button`) — a server-rendered listen button. Its settings panel offers: * **Voice** — a live picker of your account's voice catalog, with a **Default (account voice)** option. * **Preview voice** — hear the selected voice without leaving the editor. * **Button text** — the button label. * **Playback** — rate, pitch, and volume sliders. The block also supports WordPress's native styling controls — color (including gradients), typography, spacing, and border. ![The Listen Button block in the Gutenberg editor: the block settings sidebar shows a voice picker with a Default (account voice) option, a Preview voice button, and a Button text field.](/img/wordpress/block-voice-picker.png) ## Languages and voices The full catalog — **100+ voices across 50+ languages** — is resolved through the ResponsiveVoice [voice resolution chain](/guides/voice-selection/) (native Web Speech where available, server fallback otherwise). Bring-Your-Own-Key providers add [premium neural voices](#can-i-use-premium-neural-voices) on top. The catalog is fetched and cached at runtime, so it improves without updating the plugin. Browse the current list in the [Gutenberg block's](#gutenberg-block) **Voice** picker or the [customizer's](#customizer) **Voice** dropdown — both always reflect your account's catalog — or call `responsiveVoice.getVoices()`. ## Upgrading from 1.7.x Version 2.0 upgrades in place — your API key, settings, and existing shortcodes carry over with no changes required. * All 1.x shortcode tags and attributes keep working. * Buttons now use a neutral style with the ResponsiveVoice icon; restyle them with the `class` attribute or your own CSS. * The `[responsivevoice_box]` voicebox shortcode (and its aliases) was removed. * v1 (legacy) accounts keep Listen buttons and shortcodes in full — the WebPlayer needs a v2 account (see [the FAQ](#im-on-a-v1-legacy-account--what-do-i-get)). ## FAQ ### Do I need an API key? No, but you'll want one. Without a key, the listen buttons speak with the browser's built-in voice and the WebPlayer is unavailable. A free API key unlocks the full voice catalog — delivered through a fast text-to-speech API for high-quality voices — plus the WebPlayer; both activate once your domain is [verified](#verify-your-website). It also opens the door to audio streaming and premium neural voices (Google Cloud, Microsoft Azure, OpenAI) via [Bring Your Own Key](#can-i-use-premium-neural-voices). The key is a public website identifier, not a secret. ### Why isn't the WebPlayer playing? First make sure an API key is set — the WebPlayer's controls appear on the settings page only once a key is in place. Then check that your domain is [verified](#verify-your-website) — an unverified site silences all text to speech, listen buttons included. If both are in order, one of the [three visibility levels](#choose-where-it-shows) may be hiding it. ### I upgraded from 1.7.x — will my existing shortcodes keep working? Yes — all 1.x shortcode tags and attributes keep working, and your API key and settings carry over. See [Upgrading from 1.7.x](#upgrading-from-17x) for the two visible changes. ### How do I show the WebPlayer only on some content? Three levels — the site-wide switch, per-content-type toggles, and a per-post override in the editor. Details in [Choose where it shows](#choose-where-it-shows). ### Can I control where the player appears on the page? Yes — the customizer's **Position** control places it before, after, or inside your content, aligned to your theme's content column, or attaches it to any CSS selector you choose. For everything beyond the customizer, see the [Web Player guide](/guides/web-player/). ### I'm on a v1 (legacy) account — what do I get? Listen buttons and shortcodes work fully. The WebPlayer needs a v2 account — the settings page offers a reversible **Try the v2 WebPlayer** preview, and upgrading is free. ### Can I use premium neural voices? Yes — on ResponsiveVoice v2, Bring Your Own Key (BYOK) connects premium providers (Google Cloud, Microsoft Azure, OpenAI and more) through your dashboard, adding thousands of neural voices to your catalog. Voices you add appear in the plugin automatically — in the block's voice picker and the WebPlayer — with no plugin configuration. ### Does it work with page builders and the Classic editor? Yes — the shortcodes work in any editor or page builder that renders WordPress shortcodes (the Classic editor, Elementor, and the like), and the WebPlayer attaches to your rendered content no matter what built it. The Listen Button block needs the block editor. More editor integrations are planned. ### What data is sent to ResponsiveVoice? When a visitor plays audio, the text to read and your site's public API key are sent to the ResponsiveVoice API from their browser. Full detail in [External services and privacy](#external-services-and-privacy). ### Will the plugin slow my site down? It's built not to — its scripts load at the end of the page and don't block rendering, and speech is synthesized only when a visitor presses play. Sites with strict CSP or asset policies can switch to bundled delivery or pin a library version — see [Advanced delivery](#advanced-delivery). ## External services and privacy This plugin relies on the ResponsiveVoice service to synthesize speech, so text and your API key are sent to it from visitors' browsers. * The ResponsiveVoice SDK loads from `cdn.responsivevoice.org`, or, in **bundled** delivery mode, is served from your own site. * When a visitor plays audio, the **text to read** and your site's **public API key** are sent to the ResponsiveVoice Text-To-Speech API to generate audio. The plugin also reads your site configuration from the API to enable the WebPlayer. See the [Terms of Service](https://responsivevoice.org/terms/) and [Privacy Policy](https://responsivevoice.org/privacy-policy/). ## Support and links [ResponsiveVoice Text To Speech on WordPress.org ](https://wordpress.org/plugins/responsivevoice-text-to-speech/) [Register for a free API key ](https://responsivevoice.org/register) [ResponsiveVoice dashboard ](https://app.responsivevoice.org) [Web Player guide ](/guides/web-player/) [Voice Selection ](/guides/voice-selection/) [Support ](https://responsivevoice.org/support) # Authentication > API key and secret authentication for the ResponsiveVoice REST API ## 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 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 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 | 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 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 | 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 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 * **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 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 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 REST client with full typing, retry logic, WebSocket streaming, and Node.js/browser support. Source: [`api-client`](https://github.com/responsivevoice/api-client). ## Installation ```bash npm install @responsivevoice/api-client ``` ## 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 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 * **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 * [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 ### 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 * [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror) #### 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 ##### 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 | Parameter | Type | | ------------ | --------- | | `message` | `string` | | `status` | `number` | | `statusText` | `string` | | `url` | `string` | | `body?` | `unknown` | | `cause?` | `Error` | ###### Returns [`ApiError`](/api/api-client/src/#apierror) ###### Overrides [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`constructor`](/api/api-client/src/#constructor-10) #### Properties ##### 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? ```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 [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`cause`](/api/api-client/src/#cause-6) ##### 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 [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`message`](/api/api-client/src/#message-6) ##### 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 [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`name`](/api/api-client/src/#name-6) ##### 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 [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`stack`](/api/api-client/src/#stack-6) ##### 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 ```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 ```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 ##### isClientError ###### 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 `boolean` ##### isRetryable ###### Get Signature ```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 `boolean` ##### isServerError ###### Get Signature ```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 `boolean` *** ### 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 * [`ApiError`](/api/api-client/src/#apierror) #### Constructors ##### Constructor ```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 | Parameter | Type | | ------------ | --------- | | `message` | `string` | | `status` | `number` | | `statusText` | `string` | | `url` | `string` | | `body?` | `unknown` | ###### Returns [`AuthError`](/api/api-client/src/#autherror) ###### Overrides [`ApiError`](/api/api-client/src/#apierror).[`constructor`](/api/api-client/src/#constructor) #### Properties ##### 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 ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`body`](/api/api-client/src/#body) ##### 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 [`ApiError`](/api/api-client/src/#apierror).[`cause`](/api/api-client/src/#cause) ##### 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 [`ApiError`](/api/api-client/src/#apierror).[`message`](/api/api-client/src/#message) ##### 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 [`ApiError`](/api/api-client/src/#apierror).[`name`](/api/api-client/src/#name) ##### 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 [`ApiError`](/api/api-client/src/#apierror).[`stack`](/api/api-client/src/#stack) ##### 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 ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`status`](/api/api-client/src/#status) ##### 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 ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`statusText`](/api/api-client/src/#statustext) ##### 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 ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`url`](/api/api-client/src/#url) #### Accessors ##### isClientError ###### 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 `boolean` ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`isClientError`](/api/api-client/src/#isclienterror) ##### isRetryable ###### Get Signature ```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 `boolean` ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`isRetryable`](/api/api-client/src/#isretryable) ##### isServerError ###### Get Signature ```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 `boolean` ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`isServerError`](/api/api-client/src/#isservererror) *** ### 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 ##### Constructor ```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 | Parameter | Type | | --------- | ----------------------------------------------------------- | | `config` | [`VoiceCacheConfig`](/api/api-client/src/#voicecacheconfig) | ###### Returns [`ClientVoiceCache`](/api/api-client/src/#clientvoicecache) #### Properties ##### 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 ##### 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 `Promise`\<`void`> ##### 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 `Promise`\<`string` | `null`> ##### 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 `Promise`\<[`CachedVoiceData`](/api/api-client/src/#cachedvoicedata) | `null`> Cached voice data or null if not cached / cache disabled ##### 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 | Parameter | Type | | --------- | --------------------------------------------------------- | | `data` | [`CachedVoiceData`](/api/api-client/src/#cachedvoicedata) | ###### Returns `boolean` ##### 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 `Promise`\<`void`> ##### 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 | Parameter | Type | | --------- | -------- | | `hash` | `string` | ###### Returns `Promise`\<`void`> ##### 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 | Parameter | Type | Description | | -------------- | --------------------------------------- | ----------------------------- | | `etag` | `string` | ETag from the server response | | `voices` | `VoiceData`\[] | Voice collection to cache | | `systemVoices` | `SystemVoiceResponse`\[] \| `undefined` | System voices to cache | ###### Returns `Promise`\<`void`> ##### 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 | Parameter | Type | | --------- | ----------------------------------------------------------------------------- | | `config` | \| [`VoiceCacheConfig`](/api/api-client/src/#voicecacheconfig) \| `undefined` | ###### Returns \| [`ClientVoiceCache`](/api/api-client/src/#clientvoicecache) | `NoOpCache` *** ### 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 * [`CacheStorageAdapter`](/api/api-client/src/#cachestorageadapter) #### Constructors ##### Constructor ```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 | 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 [`FileStorage`](/api/api-client/src/#filestorage) #### Methods ##### 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 | Parameter | Type | | --------- | -------- | | `key` | `string` | ###### Returns `Promise`\<`string` | `null`> ###### Implementation of [`CacheStorageAdapter`](/api/api-client/src/#cachestorageadapter).[`getItem`](/api/api-client/src/#getitem-2) ##### 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 | Parameter | Type | | --------- | -------- | | `key` | `string` | ###### Returns `Promise`\<`void`> ###### Implementation of [`CacheStorageAdapter`](/api/api-client/src/#cachestorageadapter).[`removeItem`](/api/api-client/src/#removeitem-2) ##### 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 | Parameter | Type | | --------- | -------- | | `key` | `string` | | `value` | `string` | ###### Returns `Promise`\<`void`> ###### Implementation of [`CacheStorageAdapter`](/api/api-client/src/#cachestorageadapter).[`setItem`](/api/api-client/src/#setitem-2) *** ### 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 * [`CacheStorageAdapter`](/api/api-client/src/#cachestorageadapter) #### Constructors ##### Constructor ```ts new MemoryStorage(): MemoryStorage; ``` ###### Returns [`MemoryStorage`](/api/api-client/src/#memorystorage) #### Methods ##### getItem() ```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 | Parameter | Type | | --------- | -------- | | `key` | `string` | ###### Returns `string` | `null` ###### Implementation of [`CacheStorageAdapter`](/api/api-client/src/#cachestorageadapter).[`getItem`](/api/api-client/src/#getitem-2) ##### removeItem() ```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 | Parameter | Type | | --------- | -------- | | `key` | `string` | ###### Returns `void` ###### Implementation of [`CacheStorageAdapter`](/api/api-client/src/#cachestorageadapter).[`removeItem`](/api/api-client/src/#removeitem-2) ##### setItem() ```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 | Parameter | Type | | --------- | -------- | | `key` | `string` | | `value` | `string` | ###### Returns `void` ###### Implementation of [`CacheStorageAdapter`](/api/api-client/src/#cachestorageadapter).[`setItem`](/api/api-client/src/#setitem-2) *** ### 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 * [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror) #### Extended by * [`TimeoutError`](/api/api-client/src/#timeouterror) #### Constructors ##### Constructor ```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 | Parameter | Type | | --------- | -------- | | `message` | `string` | | `url` | `string` | | `cause?` | `Error` | ###### Returns [`NetworkError`](/api/api-client/src/#networkerror) ###### Overrides [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`constructor`](/api/api-client/src/#constructor-10) #### Properties ##### 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 [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`cause`](/api/api-client/src/#cause-6) ##### 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 [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`message`](/api/api-client/src/#message-6) ##### 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 [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`name`](/api/api-client/src/#name-6) ##### 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 [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`stack`](/api/api-client/src/#stack-6) ##### url ```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 ##### isRetryable ###### Get Signature ```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 `boolean` *** ### 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 * [`ApiError`](/api/api-client/src/#apierror) #### Constructors ##### Constructor ```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 | Parameter | Type | | ------------ | --------- | | `message` | `string` | | `resource` | `string` | | `status` | `number` | | `statusText` | `string` | | `url` | `string` | | `body?` | `unknown` | ###### Returns [`NotFoundError`](/api/api-client/src/#notfounderror) ###### Overrides [`ApiError`](/api/api-client/src/#apierror).[`constructor`](/api/api-client/src/#constructor) #### Properties ##### 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 ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`body`](/api/api-client/src/#body) ##### 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 [`ApiError`](/api/api-client/src/#apierror).[`cause`](/api/api-client/src/#cause) ##### 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 [`ApiError`](/api/api-client/src/#apierror).[`message`](/api/api-client/src/#message) ##### 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 [`ApiError`](/api/api-client/src/#apierror).[`name`](/api/api-client/src/#name) ##### 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? ```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 [`ApiError`](/api/api-client/src/#apierror).[`stack`](/api/api-client/src/#stack) ##### 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 ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`status`](/api/api-client/src/#status) ##### 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 ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`statusText`](/api/api-client/src/#statustext) ##### 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 ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`url`](/api/api-client/src/#url) #### Accessors ##### isClientError ###### 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 `boolean` ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`isClientError`](/api/api-client/src/#isclienterror) ##### isRetryable ###### Get Signature ```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 `boolean` ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`isRetryable`](/api/api-client/src/#isretryable) ##### isServerError ###### Get Signature ```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 `boolean` ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`isServerError`](/api/api-client/src/#isservererror) *** ### 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 * [`ApiError`](/api/api-client/src/#apierror) #### Constructors ##### Constructor ```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 | Parameter | Type | | ------------- | --------- | | `message` | `string` | | `status` | `number` | | `statusText` | `string` | | `url` | `string` | | `retryAfter?` | `number` | | `body?` | `unknown` | ###### Returns [`RateLimitError`](/api/api-client/src/#ratelimiterror) ###### Overrides [`ApiError`](/api/api-client/src/#apierror).[`constructor`](/api/api-client/src/#constructor) #### Properties ##### 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 ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`body`](/api/api-client/src/#body) ##### 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 [`ApiError`](/api/api-client/src/#apierror).[`cause`](/api/api-client/src/#cause) ##### 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 [`ApiError`](/api/api-client/src/#apierror).[`message`](/api/api-client/src/#message) ##### 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 [`ApiError`](/api/api-client/src/#apierror).[`name`](/api/api-client/src/#name) ##### 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? ```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 [`ApiError`](/api/api-client/src/#apierror).[`stack`](/api/api-client/src/#stack) ##### 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 ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`status`](/api/api-client/src/#status) ##### 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 ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`statusText`](/api/api-client/src/#statustext) ##### 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 ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`url`](/api/api-client/src/#url) #### Accessors ##### isClientError ###### 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 `boolean` ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`isClientError`](/api/api-client/src/#isclienterror) ##### isRetryable ###### Get Signature ```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 `boolean` ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`isRetryable`](/api/api-client/src/#isretryable) ##### isServerError ###### Get Signature ```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 `boolean` ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`isServerError`](/api/api-client/src/#isservererror) *** ### 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 * [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror) #### Constructors ##### Constructor ```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 | Parameter | Type | | --------- | --------------------------------------------- | | `message` | `string` | | `issues` | { `message`: `string`; `path`: `string`; }\[] | | `data` | `unknown` | ###### Returns [`ResponseValidationError`](/api/api-client/src/#responsevalidationerror) ###### Overrides [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`constructor`](/api/api-client/src/#constructor-10) #### Properties ##### 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 [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`cause`](/api/api-client/src/#cause-6) ##### 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 ```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 ```ts message: string; ``` ###### path ```ts path: string; ``` ##### 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 [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`message`](/api/api-client/src/#message-6) ##### 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 [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`name`](/api/api-client/src/#name-6) ##### 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 [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`stack`](/api/api-client/src/#stack-6) #### Accessors ##### formattedIssues ###### Get Signature ```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 `string` *** ### 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 ```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 ##### Constructor ```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 | Parameter | Type | Description | | --------- | --------------------------------------------------------------------------------------- | -------------------- | | `config` | [`ResponsiveVoiceAPIClientConfig`](/api/api-client/src/#responsivevoiceapiclientconfig) | Client configuration | ###### Returns [`ResponsiveVoiceAPIClient`](/api/api-client/src/#responsivevoiceapiclient) ###### Throws Error if apiKey is not provided #### Accessors ##### baseUrl ###### Get Signature ```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 `string` #### Methods ##### 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 `Promise`\<`void`> ##### getBrowserVoiceHash() ```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 `Promise`\<`string` | `null`> ##### 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 `Promise`\<[`CachedVoiceData`](/api/api-client/src/#cachedvoicedata) | `null`> ##### 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 | Parameter | Type | | ----------------- | ------------------------------------------------------- | | `requestOptions?` | [`RequestOptions`](/api/api-client/src/#requestoptions) | ###### Returns `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() ```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 | Parameter | Type | Description | | ----------------- | ------------------------------------------------------- | ------------------------------ | | `name` | `string` | The voice name to look up | | `requestOptions?` | [`RequestOptions`](/api/api-client/src/#requestoptions) | Optional request configuration | ###### Returns `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 ```typescript const voice = await client.getVoice('UK English Female'); console.log(`Voice service: ${voice.service}`); ``` ##### getVoices() ```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 | 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 `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 ```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() ```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 | 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 `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 ```typescript const germanVoices = await client.getVoicesByLanguage('de-DE'); const frenchVoices = await client.getVoicesByLanguage('fr'); ``` ##### 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 | Parameter | Type | | ----------------- | ------------------------------------------------------- | | `requestOptions?` | [`RequestOptions`](/api/api-client/src/#requestoptions) | ###### Returns `Promise`\<{ `exp`: `number`; `token`: `string`; }> ##### 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 | 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 `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 ```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() ```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 | 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 `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 ```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() ```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 | 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 `AsyncGenerator`\<[`StreamChunk`](/api/types/src/#streamchunk)> AsyncGenerator yielding StreamChunk objects ###### Example ```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() ```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 | Parameter | Type | | --------- | -------- | | `newUrl` | `string` | ###### Returns `void` ##### 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 | Parameter | Type | | ----------------- | ------------------------------------------------------- | | `token` | `string` | | `requestOptions?` | [`RequestOptions`](/api/api-client/src/#requestoptions) | ###### Returns `Promise`\<[`VerifyOriginResponse`](/api/api-client/src/#verifyoriginresponse)> *** ### 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 * `Error` #### Extended by * [`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 ##### Constructor ```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 | Parameter | Type | | --------- | -------- | | `message` | `string` | | `cause?` | `Error` | ###### Returns [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror) ###### Overrides ```ts Error.constructor ``` #### Properties ##### 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 ###### Overrides ```ts Error.cause ``` ##### 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 ```ts Error.message ``` ##### 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 ```ts Error.name ``` ##### 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 ```ts Error.stack ``` *** ### 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 * [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror) #### Constructors ##### Constructor ```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 | Parameter | Type | | ----------- | -------- | | `message` | `string` | | `attempts` | `number` | | `lastError` | `Error` | ###### Returns [`RetryExhaustedError`](/api/api-client/src/#retryexhaustederror) ###### Overrides [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`constructor`](/api/api-client/src/#constructor-10) #### Properties ##### 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? ```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 [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`cause`](/api/api-client/src/#cause-6) ##### 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 ```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 [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`message`](/api/api-client/src/#message-6) ##### 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 [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`name`](/api/api-client/src/#name-6) ##### 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 [`ResponsiveVoiceError`](/api/api-client/src/#responsivevoiceerror).[`stack`](/api/api-client/src/#stack-6) *** ### 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 * [`NetworkError`](/api/api-client/src/#networkerror) #### Constructors ##### Constructor ```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 | Parameter | Type | | --------- | -------- | | `message` | `string` | | `url` | `string` | | `timeout` | `number` | | `cause?` | `Error` | ###### Returns [`TimeoutError`](/api/api-client/src/#timeouterror) ###### Overrides [`NetworkError`](/api/api-client/src/#networkerror).[`constructor`](/api/api-client/src/#constructor-5) #### Properties ##### 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 [`NetworkError`](/api/api-client/src/#networkerror).[`cause`](/api/api-client/src/#cause-2) ##### 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 [`NetworkError`](/api/api-client/src/#networkerror).[`message`](/api/api-client/src/#message-2) ##### 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 [`NetworkError`](/api/api-client/src/#networkerror).[`name`](/api/api-client/src/#name-2) ##### 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 [`NetworkError`](/api/api-client/src/#networkerror).[`stack`](/api/api-client/src/#stack-2) ##### 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 ```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 [`NetworkError`](/api/api-client/src/#networkerror).[`url`](/api/api-client/src/#url-2) #### Accessors ##### isRetryable ###### Get Signature ```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 `boolean` ###### Inherited from [`NetworkError`](/api/api-client/src/#networkerror).[`isRetryable`](/api/api-client/src/#isretryable-2) *** ### 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 * [`ApiError`](/api/api-client/src/#apierror) #### Constructors ##### Constructor ```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 | Parameter | Type | | ------------ | ----------------------------------- | | `message` | `string` | | `status` | `number` | | `statusText` | `string` | | `url` | `string` | | `errors?` | `Record`\<`string`, `string`\[]> | | `body?` | `unknown` | ###### Returns [`ValidationError`](/api/api-client/src/#validationerror) ###### Overrides [`ApiError`](/api/api-client/src/#apierror).[`constructor`](/api/api-client/src/#constructor) #### Properties ##### 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 ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`body`](/api/api-client/src/#body) ##### 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 [`ApiError`](/api/api-client/src/#apierror).[`cause`](/api/api-client/src/#cause) ##### 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 ```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 [`ApiError`](/api/api-client/src/#apierror).[`message`](/api/api-client/src/#message) ##### 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 [`ApiError`](/api/api-client/src/#apierror).[`name`](/api/api-client/src/#name) ##### 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 [`ApiError`](/api/api-client/src/#apierror).[`stack`](/api/api-client/src/#stack) ##### 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 ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`status`](/api/api-client/src/#status) ##### 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 ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`statusText`](/api/api-client/src/#statustext) ##### 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 ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`url`](/api/api-client/src/#url) #### Accessors ##### isClientError ###### 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 `boolean` ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`isClientError`](/api/api-client/src/#isclienterror) ##### isRetryable ###### Get Signature ```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 `boolean` ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`isRetryable`](/api/api-client/src/#isretryable) ##### isServerError ###### Get Signature ```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 `boolean` ###### Inherited from [`ApiError`](/api/api-client/src/#apierror).[`isServerError`](/api/api-client/src/#isservererror) *** ### 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 ##### Constructor ```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 | Parameter | Type | | --------- | ----------------------------------------------------------------------------- | | `config` | [`WebSocketConnectionConfig`](/api/api-client/src/#websocketconnectionconfig) | ###### Returns [`WebSocketConnection`](/api/api-client/src/#websocketconnection) #### Accessors ##### connected ###### Get Signature ```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 `boolean` #### Methods ##### 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 | Parameter | Type | | ----------- | -------- | | `requestId` | `string` | ###### Returns `void` ##### 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 `void` ##### 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 `Promise`\<`void`> ##### synthesizeStream() ```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 | 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 `AsyncGenerator`\<[`StreamChunk`](/api/types/src/#streamchunk)> ## Interfaces ### 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 ##### 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 ```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? ```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 ```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 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 ##### getItem() ```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 | Parameter | Type | | --------- | -------- | | `key` | `string` | ###### Returns `string` | `Promise`\<`string` | `null`> | `null` ##### removeItem() ```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 | Parameter | Type | | --------- | -------- | | `key` | `string` | ###### Returns `void` | `Promise`\<`void`> ##### setItem() ```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 | Parameter | Type | | --------- | -------- | | `key` | `string` | | `value` | `string` | ###### Returns `void` | `Promise`\<`void`> *** ### 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 ##### 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 ```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 ```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 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 ##### 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? ```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? ```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 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 ##### 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 ```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 ```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 ```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 ```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 | Parameter | Type | | --------- | ---------------------- | | `input` | `RequestInfo` \| `URL` | | `init?` | `RequestInit` | ###### Returns `Promise`\<`Response`> ##### 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 ```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 ```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 ```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 ```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 ```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 ```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 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 ##### apiKey ```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? ```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? ```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 \| `Record`\<`string`, `string`> | `Promise`\<`Record`\<`string`, `string`>> ##### baseUrl? ```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? ```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 | Parameter | Type | | --------- | ---------------------- | | `input` | `RequestInfo` \| `URL` | | `init?` | `RequestInit` | ###### Returns `Promise`\<`Response`> ##### onRateLimit? ```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 | Parameter | Type | | --------- | ----------------------------------------------------- | | `info` | [`RateLimitInfo`](/api/api-client/src/#ratelimitinfo) | ###### Returns `void` ##### onServerUrlChange? ```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 | Parameter | Type | | --------- | -------- | | `newUrl` | `string` | ###### Returns `void` ##### onTokenRenewed? ```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 | Parameter | Type | | --------------- | --------------------------------------- | | `renewed` | { `exp`: `number`; `token`: `string`; } | | `renewed.exp` | `number` | | `renewed.token` | `string` | ###### Returns `void` ##### retryAttempts? ```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? ```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? ```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? ```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 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 ##### 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 ```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 ```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 ```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 ```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 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 ##### 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 ```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 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 ##### 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 ```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 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 ##### apiKey? ```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? ```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? ```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? ```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? ```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? ```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 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 ##### 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? ```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? ```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? ```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? ```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? ```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 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 ##### apiKey? ```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? ```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 ```ts true ``` ##### baseUrl ```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? ```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 `Promise`\<`string` | `undefined`> ##### 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 ```ts 5 ``` ##### 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 ```ts 25000 ``` ##### 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 ```ts 1000 ``` ##### 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 | Parameter | Type | | --------- | ----------------- | | `url` | `string` \| `URL` | ###### Returns `WebSocket` ###### Example ```typescript import WebSocket from 'ws'; new WebSocketConnection({ baseUrl: '...', WebSocket }); ``` ## Type Aliases ### 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 ### 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 ### 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 | 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 `number` Delay in milliseconds *** ### 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 | Parameter | Type | | --------- | ---------------------------------------------------------------- | | `config` | `Partial`\<[`RetryConfig`](/api/api-client/src/#retryconfig)> | #### Returns \<`T`>(`fn`) => `Promise`\<`T`> *** ### 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 | Parameter | Type | | --------- | --------- | | `error` | `unknown` | #### Returns [`RetryDecision`](/api/api-client/src/#retrydecision) *** ### 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 | Type Parameter | | -------------- | | `T` | #### Parameters | 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 `Promise`\<`T`> The result of the function #### Throws RetryExhaustedError if all retries fail ## References ### AudioFormat Re-exports [AudioFormat](/api/types/src/#audioformat) *** ### AudioResponse Re-exports [AudioResponse](/api/types/src/#audioresponse) *** ### StreamAudioChunk Re-exports [StreamAudioChunk](/api/types/src/#streamaudiochunk) *** ### StreamChunk Re-exports [StreamChunk](/api/types/src/#streamchunk) *** ### StreamEnd Re-exports [StreamEnd](/api/types/src/#streamend) *** ### StreamError Re-exports [StreamError](/api/types/src/#streamerror) *** ### StreamMetadata Re-exports [StreamMetadata](/api/types/src/#streammetadata) *** ### SynthesizeRequest Re-exports [SynthesizeRequest](/api/types/src/#synthesizerequest) *** ### SynthesizeResponse Re-exports [SynthesizeResponse](/api/types/src/#synthesizeresponse) *** ### SystemVoice Re-exports [SystemVoice](/api/types/src/#systemvoice) *** ### TTSService Re-exports [TTSService](/api/types/src/#ttsservice) *** ### Voice Re-exports [Voice](/api/types/src/#voice) *** ### 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 ### 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 * `ResponsiveVoiceCore` #### Constructors ##### 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 | Parameter | Type | | --------- | ------------------------------------------------------------------------- | | `options` | [`ResponsiveVoiceInitOptions`](/api/core/src/#responsivevoiceinitoptions) | ###### Returns [`ResponsiveVoice`](/api/core/src/#responsivevoice) ###### Inherited from ```ts ResponsiveVoiceCore.constructor ``` #### Properties ##### 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 ```ts ResponsiveVoiceCore.features ``` ##### 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 ```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 ```ts FALLBACK_AUDIO: 1; ``` ###### NATIVE\_TTS ```ts NATIVE_TTS: 0; ``` ###### Inherited from ```ts ResponsiveVoiceCore.services ``` #### Accessors ##### allowPermissionPopupEverywhere ###### 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 `boolean` ###### 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 | Parameter | Type | | --------- | --------- | | `value` | `boolean` | ###### Returns `void` ##### clickEventDetected ###### Get Signature ```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 `boolean` ##### debug ###### Get Signature ```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 `boolean` ###### Set Signature ```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 | Parameter | Type | | --------- | --------- | | `enabled` | `boolean` | ###### Returns `void` ##### debugTools ###### Get Signature ```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 ```ts responsiveVoice.debug = true; await responsiveVoice.debugTools?.clearCache('voices'); ``` ###### Returns [`DebugTools`](/api/core/src/#debugtools-1) | `undefined` ##### disablePermissionPopup ###### Get Signature ```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 `boolean` ###### Set Signature ```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 | Parameter | Type | | --------- | --------- | | `value` | `boolean` | ###### Returns `void` ##### enableEstimationTimeout ###### Get Signature ```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 ```ts true ``` ###### Returns `boolean` ###### Set Signature ```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 | Parameter | Type | | --------- | --------- | | `value` | `boolean` | ###### Returns `void` ##### fallbackMode ###### Get Signature ```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 `boolean` ##### outputDevice ###### Get Signature ```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 `string` | `null` ###### Set Signature ```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 | Parameter | Type | | ---------- | ------------------ | | `deviceId` | `string` \| `null` | ###### Returns `void` ##### prosodyFallback ###### Get Signature ```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 `boolean` ###### Set Signature ```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 | Parameter | Type | | --------- | --------- | | `value` | `boolean` | ###### Returns `void` ##### speechAllowedByUser ###### Get Signature ```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 `boolean` | `null` ##### webPlayer ###### Get Signature ```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 `WebPlayerFeature` | `undefined` ###### Inherited from ```ts ResponsiveVoiceCore.webPlayer ``` #### Methods ##### 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 | Parameter | Type | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `event` | \| `"OnLoad"` \| `"OnReady"` \| `"OnStart"` \| `"OnEnd"` \| `"OnError"` \| `"OnPause"` \| `"OnResume"` \| `"OnServiceSwitched"` \| `"OnClickEvent"` \| `"OnAllowSpeechClicked"` \| `"OnPartStart"` \| `"OnPartEnd"` \| `"OnVoiceResolved"` | | `callback` | `GenericEventCallback` | ###### Returns `void` ##### 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 | Parameter | Type | | --------- | --------- | | `allowed` | `boolean` | ###### Returns `void` ##### 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 | Parameter | Type | Description | | --------- | -------- | --------------------- | | `text` | `string` | The text to transform | ###### Returns `string` The text with all matching replacement rules applied ##### 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 `void` ###### Inherited from ```ts ResponsiveVoiceCore.cancel ``` ##### 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 | Parameter | Type | | --------- | ----------------------------------------------------------------- | | `options` | [`PermissionPopupOptions`](/api/core/src/#permissionpopupoptions) | ###### Returns `boolean` ###### Inherited from ```ts ResponsiveVoiceCore.checkSpeechAllowed ``` ##### 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 | Parameter | Type | Description | | ------------------------- | -------------------------------- | ---------------------------------------- | | `text` | `string` | The text to chunk | | `options?` | { `characterLimit?`: `number`; } | Optional overrides (e.g. characterLimit) | | `options.characterLimit?` | `number` | - | ###### Returns [`TextChunk`](/api/text/src/#textchunk)\[] Array of TextChunk objects ##### 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 `void` ##### 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 `void` ##### 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 `void` ###### Inherited from ```ts ResponsiveVoiceCore.dispose ``` ##### 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 `void` ##### 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 `string`\[] ##### 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 `number` ##### 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 `SpeechSynthesisVoice`\[] Array of SpeechSynthesisVoice objects (may be empty on some platforms) ##### 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 `number` ##### 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 ```ts { apiKey: string; defaultParams: SpeakParams; defaultVoice: string; } ``` ###### apiKey ```ts apiKey: string; ``` ###### defaultParams ```ts defaultParams: SpeakParams; ``` ###### defaultVoice ```ts defaultVoice: string; ``` ##### 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 `string` ##### 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 | 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 `number` Estimated duration in milliseconds ##### 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 `string` | `null` Device ID or null if using default device ##### 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 [`PlatformInfo`](/api/core/src/#platforminfo) ##### 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 [`PlatformVersionInfo`](/api/core/src/#platformversioninfo) Browser name/version, OS name/version, and device type ##### 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 | Parameter | Type | | --------- | -------- | | `service` | `number` | ###### Returns `boolean` ##### 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 `number`\[] ##### 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 ##### 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 `number` ##### 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 `void` ##### 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 | Parameter | Type | Description | | --------- | ------------------------------------------------------------------------- | ------------------------------------------ | | `options` | [`ResponsiveVoiceInitOptions`](/api/core/src/#responsivevoiceinitoptions) | API key, voice defaults, and feature flags | ###### Returns `Promise`\<`void`> Promise that resolves when ready ###### Example ```typescript await rv.init({ apiKey: 'your-api-key' }); rv.speak('Hello world'); ``` ###### Inherited from ```ts ResponsiveVoiceCore.init ``` ##### 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 `boolean` ##### 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 `boolean` ##### 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 `boolean` ##### 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 `Promise`\<`boolean`> ##### 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 `boolean` ##### 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 `boolean` ###### Inherited from ```ts ResponsiveVoiceCore.isPaused ``` ##### 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 `boolean` ###### Inherited from ```ts ResponsiveVoiceCore.isPlaying ``` ##### 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 `boolean` ##### 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 | Parameter | Type | | --------- | -------- | | `message` | `string` | ###### Returns `void` ##### 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 `void` ###### Inherited from ```ts ResponsiveVoiceCore.pause ``` ##### 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 `Promise`\<`void`> ###### Inherited from ```ts ResponsiveVoiceCore.refreshAuthToken ``` ##### 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 | Parameter | Type | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `event` | \| `"OnLoad"` \| `"OnReady"` \| `"OnStart"` \| `"OnEnd"` \| `"OnError"` \| `"OnPause"` \| `"OnResume"` \| `"OnServiceSwitched"` \| `"OnClickEvent"` \| `"OnAllowSpeechClicked"` \| `"OnPartStart"` \| `"OnPartEnd"` \| `"OnVoiceResolved"` | | `callback` | `GenericEventCallback` | ###### Returns `void` ##### 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 `void` ###### Inherited from ```ts ResponsiveVoiceCore.resume ``` ##### 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 | Parameter | Type | Description | | --------- | -------- | ---------------------------------------------------- | | `limit` | `number` | Character limit (clamped to 50–300 at chunking time) | ###### Returns `void` ##### 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 | Parameter | Type | Description | | --------- | -------- | ------------------------ | | `rate` | `number` | Speech rate (0.1 to 1.5) | ###### Returns `void` ##### 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 | Parameter | Type | | --------- | -------- | | `voice` | `string` | ###### Returns `void` ##### 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 | Parameter | Type | | --------- | --------- | | `force` | `boolean` | ###### Returns `void` ##### 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 | Parameter | Type | Description | | ---------- | -------- | -------------------------------------------------------- | | `deviceId` | `string` | Device ID from navigator.mediaDevices.enumerateDevices() | ###### Returns `Promise`\<`void`> ##### 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 | Parameter | Type | Description | | --------- | --------- | ------------------------------------------------------------ | | `service` | `number` | Service type constant (NATIVE\_TTS = 0, FALLBACK\_AUDIO = 1) | | `enabled` | `boolean` | Whether the service should be enabled | ###### Returns `void` ##### 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 | Parameter | Type | Description | | ---------- | ----------- | ---------------------------------------------------------- | | `priority` | `number`\[] | Array of service types in priority order (first = highest) | ###### Returns `void` ##### 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 | Parameter | Type | Description | | --------- | ------------------------------------------------------------------------ | -------------------------------------------- | | `rules` | [`TextReplacementRule`](/api/core/src/#textreplacementrule)\[] \| `null` | Array of replacement rules, or null to clear | ###### Returns `void` ##### 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 | Parameter | Type | | --------- | -------- | | `volume` | `number` | ###### Returns `void` ##### 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 | Parameter | Type | | --------- | ----------------------------------------------------------------- | | `options` | [`PermissionPopupOptions`](/api/core/src/#permissionpopupoptions) | ###### Returns `void` ##### speak() ###### 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 | 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 `void` ###### Inherited from ```ts ResponsiveVoiceCore.speak ``` ###### Call Signature ```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 | Parameter | Type | Description | | --------- | -------------- | ------------------------------- | | `text` | `string` | Text to speak | | `params?` | `SpeakOptions` | Speech parameters and callbacks | ###### Returns `void` ###### Inherited from ```ts ResponsiveVoiceCore.speak ``` ##### 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 `boolean` ## Interfaces ### DebugTools 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 ##### 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 | Parameter | Type | | --------- | ----------------------------------------- | | `scope?` | [`CacheScope`](/api/core/src/#cachescope) | ###### Returns `Promise`\<`void`> *** ### 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 ##### allowPermissionPopupEverywhere? ```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 ```ts false ``` ##### disablePermissionPopup? ```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 ```ts false ``` *** ### 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 ##### 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? ```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? ```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? ```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? ```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? ```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 | Parameter | Type | | --------- | ------------ | | `onAllow` | () => `void` | | `onDeny` | () => `void` | ###### Returns `HTMLElement` ##### 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? ```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 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 ##### 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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 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 ##### 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 ```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 ```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 ```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 ```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 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 ##### 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? ```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? ```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? ```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 ```ts false ``` ##### 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? ```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? ```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? ```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 ```ts true ``` ##### 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? ```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 ```ts true ``` ##### features? ```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? ```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? ```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? ```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 ```ts true ``` ##### 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? ```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 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 ##### 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 ```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 ```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? ```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 ### 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 ```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 | 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 [`VoiceSelector`](/api/types/src/#voiceselector) | `undefined` A transformed selector, or `undefined` to fall through to the configured [defaultVoice](/api/core/src/#defaultvoice). ## Functions ### 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 [`PlatformInfo`](/api/core/src/#platforminfo) *** ### 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 | Parameter | Type | Description | | -------------- | --------------------------------------------- | --------------------------- | | `platformInfo` | [`PlatformInfo`](/api/core/src/#platforminfo) | Platform info from detector | #### Returns [`PlatformVersionInfo`](/api/core/src/#platformversioninfo) Platform version information suitable for voice reporting *** ### 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 | Parameter | Type | Description | | ---------- | ------------------------------------------------------------------------- | ---------------------------------------------------- | | `options?` | [`ResponsiveVoiceInitOptions`](/api/core/src/#responsivevoiceinitoptions) | Init options (apiKey, voice defaults, feature flags) | #### Returns `Promise`\<[`ResponsiveVoice`](/api/core/src/#responsivevoice)> Promise that resolves to the initialized ResponsiveVoice instance *** ### 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 `void` ## References ### default Renames and re-exports [getResponsiveVoice](/api/core/src/#getresponsivevoice) *** ### 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 ### 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 ##### 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? ```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 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 ##### 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 ```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 ```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 ```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 ### 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 ```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 ```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 ```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 ```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 ```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 ### 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 | Parameter | Type | Description | | --------- | ------------------------------------------------- | ----------------- | | `text` | `string` | The text to chunk | | `options` | [`ChunkerOptions`](/api/text/src/#chunkeroptions) | Chunking options | #### Returns [`TextChunk`](/api/text/src/#textchunk)\[] Array of text chunks with metadata #### 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() ```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 | Parameter | Type | Description | | ---------------- | ------------------------------------------------- | ---------------------------------------- | | `defaultOptions` | [`ChunkerOptions`](/api/text/src/#chunkeroptions) | Default options for all chunk operations | #### Returns A chunker function with the preset options (`text`, `options?`) => [`TextChunk`](/api/text/src/#textchunk)\[] #### Example ```typescript const chunker = createTextChunker({ characterLimit: 150 }); const chunks = chunker('Long text here...'); ``` *** ### 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 | Parameter | Type | | --------- | -------- | | `str` | `string` | #### Returns `string` *** ### 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 | 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 `number` Estimated duration in milliseconds #### Example ```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() ```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 | 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 `number` Estimated duration in milliseconds *** ### 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 | Parameter | Type | | --------- | -------- | | `text` | `string` | #### Returns `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 ### 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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 | Parameter | Type | | --------- | ------------------------------------ | | `event` | [`RVEvent`](/api/types/src/#rvevent) | #### Returns `void` *** ### 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 ```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 ```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 ```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 ##### 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 | Parameter | Type | Description | | ----------- | -------- | --------------------------------------- | | `charIndex` | `number` | Character index in the original text | | `name` | `string` | Type of boundary ('word' or 'sentence') | ###### Returns `void` ###### Remarks Only supported by native Web Speech API engine, not fallback audio engine ##### 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 `void` ##### 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 | Parameter | Type | | --------- | ------- | | `error` | `Error` | ###### Returns `void` ##### 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 `void` ##### 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? ```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? ```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? ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ### 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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ##### accessibilityNavigation ```ts readonly accessibilityNavigation: { enabled: false; }; ``` ###### accessibilityNavigation.enabled ```ts readonly enabled: false = false; ``` ##### exitIntent ```ts readonly exitIntent: { enabled: false; text: null; }; ``` ###### exitIntent.enabled ```ts readonly enabled: false = false; ``` ###### exitIntent.text ```ts readonly text: null = null; ``` ##### paragraphNavigation ```ts readonly paragraphNavigation: { enabled: false; }; ``` ###### paragraphNavigation.enabled ```ts readonly enabled: false = false; ``` ##### speakEndPage ```ts readonly speakEndPage: { enabled: false; text: null; }; ``` ###### speakEndPage.enabled ```ts readonly enabled: false = false; ``` ###### speakEndPage.text ```ts readonly text: null = null; ``` ##### speakInactivity ```ts readonly speakInactivity: { enabled: false; text: null; }; ``` ###### speakInactivity.enabled ```ts readonly enabled: false = false; ``` ###### speakInactivity.text ```ts readonly text: null = null; ``` ##### speakLinks ```ts readonly speakLinks: { enabled: false; }; ``` ###### speakLinks.enabled ```ts readonly enabled: false = false; ``` ##### speakSelectedText ```ts readonly speakSelectedText: { enabled: false; }; ``` ###### speakSelectedText.enabled ```ts readonly enabled: false = false; ``` ##### 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 ```ts readonly controls: { brand: true; progress: true; skip: true; speed: true; time: true; }; ``` ###### webPlayer.controls.brand ```ts readonly brand: true = true; ``` ###### webPlayer.controls.progress ```ts readonly progress: true = true; ``` ###### webPlayer.controls.skip ```ts readonly skip: true = true; ``` ###### webPlayer.controls.speed ```ts readonly speed: true = true; ``` ###### webPlayer.controls.time ```ts readonly time: true = true; ``` ###### webPlayer.enabled ```ts readonly enabled: false = false; ``` ###### webPlayer.layout ```ts readonly layout: { display: "block"; mode: "shrink"; }; ``` ###### webPlayer.layout.display ```ts readonly display: "block" = 'block'; ``` ###### webPlayer.layout.mode ```ts readonly mode: "shrink" = 'shrink'; ``` ###### webPlayer.miniPlayer ```ts readonly miniPlayer: { animation: "slide"; enabled: true; position: "bottom-left"; }; ``` ###### webPlayer.miniPlayer.animation ```ts readonly animation: "slide" = 'slide'; ``` ###### webPlayer.miniPlayer.enabled ```ts readonly enabled: true = true; ``` ###### webPlayer.miniPlayer.position ```ts readonly position: "bottom-left" = 'bottom-left'; ``` ###### webPlayer.navigation ```ts readonly navigation: { paragraphClick: true; paragraphHighlight: true; }; ``` ###### webPlayer.navigation.paragraphClick ```ts readonly paragraphClick: true = true; ``` ###### webPlayer.navigation.paragraphHighlight ```ts readonly paragraphHighlight: true = true; ``` ###### webPlayer.paragraphSelector ```ts readonly paragraphSelector: "p, h2, h3, li" = 'p, h2, h3, li'; ``` ###### webPlayer.position ```ts readonly position: "before" = 'before'; ``` ###### webPlayer.sanitize ```ts readonly sanitize: { enabled: true; exclude: string[]; }; ``` ###### webPlayer.sanitize.enabled ```ts readonly enabled: true = true; ``` ###### webPlayer.sanitize.exclude ```ts readonly exclude: string[]; ``` ###### webPlayer.selector ```ts readonly selector: "article" = 'article'; ``` ###### webPlayer.theme ```ts readonly theme: "neutral" = 'neutral'; ``` ##### welcomeMessage ```ts readonly welcomeMessage: { enabled: false; text: null; }; ``` ###### welcomeMessage.enabled ```ts readonly enabled: false = false; ``` ###### welcomeMessage.text ```ts readonly text: null = null; ``` ##### welcomeMessageOnce ```ts readonly welcomeMessageOnce: false = false; ``` *** ### 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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ### 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 | Parameter | Type | | --------- | --------------------------------------------------- | | `knobs` | `Iterable`\<`"pitch"` \| `"rate"` \| `"volume"`> | #### Returns `string` *** ### 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 | Parameter | Type | | --------- | --------------------------------------------------------------------- | | `engine` | `"g1"` \| `"g2"` \| `"g3"` \| `"g5"` \| `"gwn"` \| `"msv"` \| `"oai"` | #### Returns `"mp3"` | `"ogg"` | `"wav"` *** ### 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 | Parameter | Type | | --------- | --------- | | `value` | `unknown` | #### Returns value is "mp3" | "ogg" | "wav" *** ### 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 | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns `value is { default?: boolean; lang: string; localService: boolean; name: string; voiceURI: string }` True if the value is a valid BrowserVoiceInfo object *** ### 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 | Parameter | Type | | --------- | --------------------------------------------------------------------- | | `engine` | `"g1"` \| `"g2"` \| `"g3"` \| `"g5"` \| `"gwn"` \| `"msv"` \| `"oai"` | | `format` | `"mp3"` \| `"ogg"` \| `"wav"` | #### Returns `boolean` *** ### 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 | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns value is { browser: string; browserVersion: string; deviceType?: "desktop" | "mobile" | "tablet"; os: string; osVersion: string } True if the value is a valid PlatformReport object *** ### 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 | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns `value is { code?: string; message: string; timestamp: number; type: "OnError" }` True if the value is a valid RVErrorEvent object *** ### 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 | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns 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() ```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 | Parameter | Type | | --------- | --------- | | `value` | `unknown` | #### Returns value is "OnLoad" | "OnReady" | "OnStart" | "OnEnd" | "OnError" | "OnPause" | "OnResume" | "OnServiceSwitched" | "OnClickEvent" | "OnAllowSpeechClicked" | "OnPartStart" | "OnPartEnd" | "OnVoiceResolved" *** ### 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 | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns 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() ```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 | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns 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() ```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 | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns 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() ```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 | Parameter | Type | | --------- | --------- | | `value` | `unknown` | #### Returns value is "g1" | "g2" | "g3" | "g5" | "gwn" | "msv" | "oai" *** ### 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 | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns 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() ```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 | Parameter | Type | | --------- | --------- | | `value` | `unknown` | #### Returns value is "male" | "female" *** ### 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 | Parameter | Type | | --------- | --------- | | `value` | `unknown` | #### Returns value is "f" | "m" *** ### 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 | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns 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() ```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 | Parameter | Type | Description | | --------- | --------- | ------------------ | | `value` | `unknown` | The value to check | #### Returns 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() ```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 | Parameter | Type | | --------- | --------------------------------- | | `value` | `string` \| `null` \| `undefined` | #### Returns `Set`\<`"pitch"` | `"rate"` | `"volume"`>