@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

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

new ResponsiveVoice(options?): ResponsiveVoice;

Defined in: src/responsivevoice-core.ts:357

Parameters

Parameter	Type
options	ResponsiveVoiceInitOptions

Returns

ResponsiveVoice

Inherited from

ResponsiveVoiceCore.constructor

Properties

features

features: FeatureManager;

Defined in: src/responsivevoice-core.ts:306

Feature manager for dashboard features (welcome message, speak links, etc.)

Inherited from

ResponsiveVoiceCore.features

version

readonly version: string = __RV_CORE_VERSION__;

Defined in: src/responsivevoice.ts:34

Package version of @responsivevoice/core, injected at build time.

services

readonly static services: {
  FALLBACK_AUDIO: 1;
  NATIVE_TTS: 0;
};

Defined in: src/responsivevoice-core.ts:260

Service type constants for backward compatibility.

FALLBACK_AUDIO

FALLBACK_AUDIO: 1;

NATIVE_TTS

NATIVE_TTS: 0;

Inherited from

ResponsiveVoiceCore.services

Accessors

allowPermissionPopupEverywhere

Get Signature

get allowPermissionPopupEverywhere(): boolean;

Defined in: src/responsivevoice.ts:318

Force showing popup everywhere (not just mobile/Safari)

Returns

boolean

Set Signature

set allowPermissionPopupEverywhere(value): void;

Defined in: src/responsivevoice.ts:322

Parameters

Parameter	Type
value	boolean

Returns

void

clickEventDetected

Get Signature

get clickEventDetected(): boolean;

Defined in: src/responsivevoice.ts:350

Check if a click event has been detected

Returns

boolean

debug

Get Signature

get debug(): boolean;

Defined in: src/responsivevoice.ts:474

Debug flag — enable/disable debug logging

Returns

boolean

Set Signature

set debug(enabled): void;

Defined in: src/responsivevoice.ts:478

Parameters

Parameter	Type
enabled	boolean

Returns

void

debugTools

Get Signature

get debugTools(): DebugTools | undefined;

Defined in: src/responsivevoice.ts:495

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

responsiveVoice.debug = true;
await responsiveVoice.debugTools?.clearCache('voices');

Returns

DebugTools | undefined

disablePermissionPopup

Get Signature

get disablePermissionPopup(): boolean;

Defined in: src/responsivevoice.ts:294

Disable the permission popup entirely

Returns

boolean

Set Signature

set disablePermissionPopup(value): void;

Defined in: src/responsivevoice.ts:298

Parameters

Parameter	Type
value	boolean

Returns

void

enableEstimationTimeout

Get Signature

get enableEstimationTimeout(): boolean;

Defined in: src/responsivevoice.ts:459

Whether estimation-based timeout is enabled for speech playback.

Default Value

true

Returns

boolean

Set Signature

set enableEstimationTimeout(value): void;

Defined in: src/responsivevoice.ts:463

Parameters

Parameter	Type
value	boolean

Returns

void

fallbackMode

Get Signature

get fallbackMode(): boolean;

Defined in: src/responsivevoice.ts:236

Check if currently using fallback mode. Returns true if the fallback (HTTP audio) engine is currently active.

Returns

boolean

outputDevice

Get Signature

get outputDevice(): string | null;

Defined in: src/responsivevoice.ts:153

Output device property (getter/setter). Note: Setter is fire-and-forget; prefer setOutputDevice() for async handling.

Returns

string | null

Set Signature

set outputDevice(deviceId): void;

Defined in: src/responsivevoice.ts:157

Parameters

Parameter	Type
deviceId	string | null

Returns

void

prosodyFallback

Get Signature

get prosodyFallback(): boolean;

Defined in: src/responsivevoice.ts:307

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

set prosodyFallback(value): void;

Defined in: src/responsivevoice.ts:311

Parameters

Parameter	Type
value	boolean

Returns

void

speechAllowedByUser

Get Signature

get speechAllowedByUser(): boolean | null;

Defined in: src/responsivevoice.ts:287

User's speech permission state (null if not yet asked)

Returns

boolean | null

webPlayer

Get Signature

get webPlayer(): WebPlayerFeature | undefined;

Defined in: src/responsivevoice-core.ts:316

Imperative API for the web player feature. Returns the active orchestrator when webPlayer.enabled: true was passed to init (or Partial<WebsiteFeatures> 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

ResponsiveVoiceCore.webPlayer

Methods

addEventListener()

addEventListener(event, callback): void;

Defined in: src/responsivevoice.ts:393

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()

allowSpeechClicked(allowed): void;

Defined in: src/responsivevoice.ts:329

Programmatically set speech permission response

Parameters

Parameter	Type
allowed	boolean

Returns

void

applyTextReplacements()

applyTextReplacements(text): string;

Defined in: src/responsivevoice.ts:423

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()

cancel(): void;

Defined in: src/responsivevoice-core.ts:944

Cancel current speech and clear queue

Returns

void

Inherited from

ResponsiveVoiceCore.cancel

checkSpeechAllowed()

checkSpeechAllowed(options?): boolean;

Defined in: src/responsivevoice-core.ts:1028

Check if speech is allowed and show permission popup if needed

Parameters

Parameter	Type
options	PermissionPopupOptions

Returns

boolean

Inherited from

ResponsiveVoiceCore.checkSpeechAllowed

chunkText()

chunkText(text, options?): TextChunk[];

Defined in: src/responsivevoice.ts:434

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[]

Array of TextChunk objects

clearFallbackPool()

clearFallbackPool(): void;

Defined in: src/responsivevoice.ts:165

Clear the fallback audio pool. Stops all playing audio and resets the pool to empty state.

Returns

void

clickEvent()

clickEvent(): void;

Defined in: src/responsivevoice.ts:366

Manually trigger the click event handler. Simulates a user interaction event for permission initialization.

Returns

void

dispose()

dispose(): void;

Defined in: src/responsivevoice-core.ts:1043

Clean up resources

Returns

void

Inherited from

ResponsiveVoiceCore.dispose

enableWindowClickHook()

enableWindowClickHook(): void;

Defined in: src/responsivevoice.ts:358

Enable window click hook for user interaction detection. Called automatically on iOS, Android, and Safari.

Returns

void

getAvailableVoices()

getAvailableVoices(): string[];

Defined in: src/responsivevoice.ts:50

Get voices with availability information

Returns

string[]

getBrowserVoiceCount()

getBrowserVoiceCount(): number;

Defined in: src/responsivevoice.ts:66

Get the count of available browser voices.

Returns

number

getBrowserVoices()

getBrowserVoices(): SpeechSynthesisVoice[];

Defined in: src/responsivevoice.ts:59

Get browser's native SpeechSynthesis voices.

Returns

SpeechSynthesisVoice[]

Array of SpeechSynthesisVoice objects (may be empty on some platforms)

getCharacterLimit()

getCharacterLimit(): number;

Defined in: src/responsivevoice.ts:126

Get the current character limit for text chunking.

Returns

number

getConfig()

getConfig(): {
  apiKey: string;
  defaultParams: SpeakParams;
  defaultVoice: string;
};

Defined in: src/responsivevoice.ts:535

Get current configuration

Returns

{
  apiKey: string;
  defaultParams: SpeakParams;
  defaultVoice: string;
}

apiKey

apiKey: string;

defaultParams

defaultParams: SpeakParams;

defaultVoice

defaultVoice: string;

getDefaultVoice()

getDefaultVoice(): string;

Defined in: src/responsivevoice.ts:80

Get the default voice

Returns

string

getEstimatedTimeLength()

getEstimatedTimeLength(text, multiplier?): number;

Defined in: src/responsivevoice.ts:451

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()

getOutputDevice(): string | null;

Defined in: src/responsivevoice.ts:145

Get the current audio output device ID

Returns

string | null

Device ID or null if using default device

getPlatformInfo()

getPlatformInfo(): PlatformInfo;

Defined in: src/responsivevoice.ts:519

Get platform information (boolean flags for browser/OS detection)

Returns

PlatformInfo

getPlatformVersionInfo()

getPlatformVersionInfo(): PlatformVersionInfo;

Defined in: src/responsivevoice.ts:528

Get human-readable platform version information.

Returns

PlatformVersionInfo

Browser name/version, OS name/version, and device type

getServiceEnabled()

getServiceEnabled(service): boolean;

Defined in: src/responsivevoice.ts:212

Check if a TTS service is enabled

Parameters

Parameter	Type
service	number

Returns

boolean

getServicePriority()

getServicePriority(): number[];

Defined in: src/responsivevoice.ts:228

Get the current service priority order

Returns

number[]

getVoices()

getVoices(): {
  deprecated?: boolean;
  flag: string;
  gender: "f" | "m";
  isByok?: boolean;
  lang: string;
  name: string;
  provider?: string;
  voiceIDs: number[];
}[];

Defined in: src/responsivevoice.ts:43

Get all available voices

Returns

getVolume()

getVolume(): number;

Defined in: src/responsivevoice.ts:100

Get the current volume setting

Returns

number

hidePermissionPopup()

hidePermissionPopup(): void;

Defined in: src/responsivevoice.ts:343

Hide the permission popup

Returns

void

init()

init(options?): Promise<void>;

Defined in: src/responsivevoice-core.ts:472

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 key, voice defaults, and feature flags

Returns

Promise<void>

Promise that resolves when ready

Example

await rv.init({ apiKey: 'your-api-key' });
rv.speak('Hello world');

Inherited from

ResponsiveVoiceCore.init

isDemoMode()

isDemoMode(): boolean;

Defined in: src/responsivevoice.ts:276

Check if running in demo mode (no API key)

Returns

boolean

isFallbackAudioPlaying()

isFallbackAudioPlaying(): boolean;

Defined in: src/responsivevoice.ts:172

Check if fallback audio is currently playing

Returns

boolean

isForceFallback()

isForceFallback(): boolean;

Defined in: src/responsivevoice.ts:195

Check if fallback mode is forced

Returns

boolean

isNativeAvailable()

isNativeAvailable(): Promise<boolean>;

Defined in: src/responsivevoice.ts:254

Check if native TTS is available

Returns

Promise<boolean>

isNativeSupported()

isNativeSupported(): boolean;

Defined in: src/responsivevoice.ts:247

Check if native TTS is supported

Returns

boolean

isPaused()

isPaused(): boolean;

Defined in: src/responsivevoice-core.ts:1021

Check if speech is paused

Returns

boolean

Inherited from

ResponsiveVoiceCore.isPaused

isPlaying()

isPlaying(): boolean;

Defined in: src/responsivevoice-core.ts:1014

Check if speech is currently playing

Returns

boolean

Inherited from

ResponsiveVoiceCore.isPlaying

isReady()

isReady(): boolean;

Defined in: src/responsivevoice.ts:269

Check if ResponsiveVoice is initialized

Returns

boolean

log()

log(message): void;

Defined in: src/responsivevoice.ts:512

Log a debug message (only outputs if debug is enabled)

Parameters

Parameter	Type
message	string

Returns

void

pause()

pause(): void;

Defined in: src/responsivevoice-core.ts:964

Pause current speech

Note: Paused speech will auto-cancel after 60 seconds (browser limitation)

Returns

void

Inherited from

ResponsiveVoiceCore.pause

refreshAuthToken()

refreshAuthToken(): Promise<void>;

Defined in: src/responsivevoice-core.ts:829

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

ResponsiveVoiceCore.refreshAuthToken

removeEventListener()

removeEventListener(event, callback): void;

Defined in: src/responsivevoice.ts:400

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()

resume(): void;

Defined in: src/responsivevoice-core.ts:984

Resume paused speech

If pause timed out, re-queues remaining text automatically.

Returns

void

Inherited from

ResponsiveVoiceCore.resume

setCharacterLimit()

setCharacterLimit(limit): void;

Defined in: src/responsivevoice.ts:119

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()

setDefaultRate(rate): void;

Defined in: src/responsivevoice.ts:109

Set the default speech rate

Parameters

Parameter	Type	Description
rate	number	Speech rate (0.1 to 1.5)

Returns

void

setDefaultVoice()

setDefaultVoice(voice): void;

Defined in: src/responsivevoice.ts:73

Set the default voice

Parameters

Parameter	Type
voice	string

Returns

void

setForceFallback()

setForceFallback(force): void;

Defined in: src/responsivevoice.ts:183

Force fallback mode (always use HTTP audio)

Parameters

Parameter	Type
force	boolean

Returns

void

setOutputDevice()

setOutputDevice(deviceId): Promise<void>;

Defined in: src/responsivevoice.ts:136

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()

setServiceEnabled(service, enabled): void;

Defined in: src/responsivevoice.ts:205

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()

setServicePriority(priority): void;

Defined in: src/responsivevoice.ts:221

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()

setTextReplacements(rules): void;

Defined in: src/responsivevoice.ts:413

Set text replacement rules for custom text transformations.

Parameters

Parameter	Type	Description
rules	TextReplacementRule[] | null	Array of replacement rules, or null to clear

Returns

void

setVolume()

setVolume(volume): void;

Defined in: src/responsivevoice.ts:91

Set the global volume (0-1)

Parameters

Parameter	Type
volume	number

Returns

void

showPermissionPopup()

showPermissionPopup(options?): void;

Defined in: src/responsivevoice.ts:336

Show the permission popup manually

Parameters

Parameter	Type
options	PermissionPopupOptions

Returns

void

speak()

Call Signature

speak(
   text,
   voice?,
   params?): void;

Defined in: src/responsivevoice-core.ts:847

Speak text using TTS.

Parameters

Parameter	Type	Description
text	string	Text to speak
voice?	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

ResponsiveVoiceCore.speak

Call Signature

speak(text, params?): void;

Defined in: src/responsivevoice-core.ts:853

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

ResponsiveVoiceCore.speak

voiceSupport()

voiceSupport(): boolean;

Defined in: src/responsivevoice.ts:262

Check if Web Speech API is supported. Legacy compatibility method — prefer isNativeSupported().

Returns

boolean

Interfaces

DebugTools

Defined in: src/debug-tools.ts:33

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()

clearCache(scope?): Promise<void>;

Defined in: src/debug-tools.ts:45

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

Returns

Promise<void>

---

PermissionConfig

Defined in: src/permissions/manager.ts:44

Permission manager configuration

Properties

allowPermissionPopupEverywhere?

optional allowPermissionPopupEverywhere?: boolean;

Defined in: src/permissions/manager.ts:55

Show permission UI on all platforms (not just iOS)

Default Value

false

disablePermissionPopup?

optional disablePermissionPopup?: boolean;

Defined in: src/permissions/manager.ts:49

Disable permission popup/prompts

Default Value

false

---

PermissionPopupOptions

Defined in: src/permissions/popup.ts:13

Options for the permission popup (per-call overrides)

Properties

allowLabel?

optional allowLabel?: string;

Defined in: src/permissions/popup.ts:19

Override the ALLOW button label (default: "ALLOW")

appendTo?

optional appendTo?: HTMLElement;

Defined in: src/permissions/popup.ts:25

Append popup to a specific container instead of document.body

classPrefix?

optional classPrefix?: string;

Defined in: src/permissions/popup.ts:27

CSS class prefix to replace the default "rv" prefix (e.g. "myapp" → "myappNotification")

denyLabel?

optional denyLabel?: string;

Defined in: src/permissions/popup.ts:21

Override the DENY button label (default: "DENY")

position?

optional position?: "top" | "bottom";

Defined in: src/permissions/popup.ts:23

Position of the popup bar (default: "bottom")

renderPopup?

optional renderPopup?: (onAllow, onDeny) => HTMLElement;

Defined in: src/permissions/popup.ts:32

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?

optional textOverride?: string;

Defined in: src/permissions/popup.ts:17

Override the action text (default: "wants to play speech")

urlOverride?

optional urlOverride?: string;

Defined in: src/permissions/popup.ts:15

Override the origin/hostname shown in the popup

---

PlatformInfo

Defined in: src/platform/detector.ts:9

Information about the current platform and its capabilities

Properties

hasIOSAudioUnlockBug

hasIOSAudioUnlockBug: boolean;

Defined in: src/platform/detector.ts:58

Whether the platform exhibits the iOS silent-unlock bug that blocks speechSynthesis until a priming utterance runs.

iOSVersion

iOSVersion: number;

Defined in: src/platform/detector.ts:36

Major iOS version, or 0 when not iOS or unparseable.

isAndroid

isAndroid: boolean;

Defined in: src/platform/detector.ts:26

True on Android.

isChrome

isChrome: boolean;

Defined in: src/platform/detector.ts:12

True when the current browser is Chrome (excluding Edge, which also matches /chrome/ in UA).

isEdge

isEdge: boolean;

Defined in: src/platform/detector.ts:18

True when the current browser is Microsoft Edge.

isFirefox

isFirefox: boolean;

Defined in: src/platform/detector.ts:16

True when the current browser is Firefox.

isIOS

isIOS: boolean;

Defined in: src/platform/detector.ts:24

True on iOS (iPhone/iPad/iPod).

isIOS10

isIOS10: boolean;

Defined in: src/platform/detector.ts:40

True on iOS 10.

isIOS11Plus

isIOS11Plus: boolean;

Defined in: src/platform/detector.ts:42

True on iOS 11 or later.

isIOS12

isIOS12: boolean;

Defined in: src/platform/detector.ts:44

True on iOS 12.

isIOS9

isIOS9: boolean;

Defined in: src/platform/detector.ts:38

True on iOS 9.

isLinux

isLinux: boolean;

Defined in: src/platform/detector.ts:32

True on desktop Linux (excluding Android).

isMacOS

isMacOS: boolean;

Defined in: src/platform/detector.ts:28

True on macOS (excluding iOS).

isOpera

isOpera: boolean;

Defined in: src/platform/detector.ts:20

True when the current browser is Opera.

isSafari

isSafari: boolean;

Defined in: src/platform/detector.ts:14

True when the current browser is Safari (excluding Chrome on iOS, which reports Safari-like UA).

isWindows

isWindows: boolean;

Defined in: src/platform/detector.ts:30

True on Windows.

requiresUserInteraction

requiresUserInteraction: boolean;

Defined in: src/platform/detector.ts:56

Whether the platform requires a user gesture before speech/audio can play.

supportsAudioElement

supportsAudioElement: boolean;

Defined in: src/platform/detector.ts:50

Whether HTMLAudioElement is available for fallback playback.

supportsSendBeacon

supportsSendBeacon: boolean;

Defined in: src/platform/detector.ts:52

Whether navigator.sendBeacon() is available for analytics.

supportsWebSpeech

supportsWebSpeech: boolean;

Defined in: src/platform/detector.ts:48

Whether the Web Speech API (speechSynthesis) is available.

useTimerForEvents

useTimerForEvents: boolean;

Defined in: src/platform/detector.ts:60

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

Extracted platform version information for reporting

Properties

browser

browser: string;

Defined in: src/platform/version-extractor.ts:13

Human-readable browser name ('Chrome', 'Safari', 'Firefox', 'Edge', 'Opera', or 'Unknown').

browserVersion

browserVersion: string;

Defined in: src/platform/version-extractor.ts:15

Browser major version as a string (e.g. '120'), or '' when unparseable.

deviceType

deviceType: "desktop" | "mobile" | "tablet";

Defined in: src/platform/version-extractor.ts:21

Form factor inferred from UA and viewport heuristics.

os

os: string;

Defined in: src/platform/version-extractor.ts:17

Operating system name ('iOS', 'Android', 'macOS', 'Windows', 'Linux', or 'Unknown').

osVersion

osVersion: string;

Defined in: src/platform/version-extractor.ts:19

OS major version as a string (e.g. '17' for iOS 17), or '' when unparseable.

---

ResponsiveVoiceInitOptions

Defined in: src/responsivevoice-core.ts:95

Options accepted by init() — the single configuration entry point.

Properties

apiBaseUrl?

optional apiBaseUrl?: string;

Defined in: src/responsivevoice-core.ts:105

API base URL (defaults to production)

apiKey?

optional apiKey?: string;

Defined in: src/responsivevoice-core.ts:97

API key for authentication

apiSecret?

optional apiSecret?: string;

Defined in: src/responsivevoice-core.ts:103

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?

optional autoConnect?: boolean;

Defined in: src/responsivevoice-core.ts:159

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

false

characterLimit?

optional characterLimit?: number;

Defined in: src/responsivevoice-core.ts:137

Character limit for text chunks

defaultParams?

optional defaultParams?: Partial<SpeakParams>;

Defined in: src/responsivevoice-core.ts:109

Default speech parameters

defaultVoice?

optional defaultVoice?: string;

Defined in: src/responsivevoice-core.ts:107

Default voice name

enableAnalytics?

optional enableAnalytics?: boolean;

Defined in: src/responsivevoice-core.ts:133

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

true

enableDOMEvents?

optional enableDOMEvents?: boolean;

Defined in: src/responsivevoice-core.ts:135

Enable DOM event dispatch

enableVoiceReporting?

optional enableVoiceReporting?: boolean;

Defined in: src/responsivevoice-core.ts:144

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

true

features?

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

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?

optional forceFallback?: boolean;

Defined in: src/responsivevoice-core.ts:111

Force fallback mode (always use HTTP audio)

permissionConfig?

optional permissionConfig?: PermissionConfig;

Defined in: src/responsivevoice-core.ts:123

Permission configuration

prosodyFallback?

optional prosodyFallback?: boolean;

Defined in: src/responsivevoice-core.ts:121

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

true

resolveVoice?

optional resolveVoice?: ResolveVoiceHook;

Defined in: src/responsivevoice-core.ts:171

Hook called before each voice resolution to transform the incoming 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.

transport?

optional transport?: "chunks" | "stream" | "websocket";

Defined in: src/responsivevoice-core.ts:151

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

Text replacement rule with optional voice filtering

Properties

collectionvoices?

optional collectionvoices?: string | string[];

Defined in: src/text/replacements.ts:10

Optional: Apply only for these collection voice names

newvalue

newvalue: string;

Defined in: src/text/replacements.ts:8

Replacement text

searchvalue

searchvalue: string | RegExp;

Defined in: src/text/replacements.ts:6

String pattern or RegExp to match. Strings support /pattern/flags format

systemvoices?

optional systemvoices?: string | string[];

Defined in: src/text/replacements.ts:12

Optional: Apply only for these system voice names

Type Aliases

CacheScope

type CacheScope = "all" | "voices" | "server" | "config";

Defined in: src/debug-tools.ts:25

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

type ResolveVoiceHook = (selector) => VoiceSelector | undefined;

Defined in: src/responsivevoice-core.ts:90

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 | undefined	The incoming selector, or undefined when no voice was specified (i.e. the default voice would be used).

Returns

VoiceSelector | undefined

A transformed selector, or undefined to fall through to the configured defaultVoice.

Functions

detectPlatform()

function detectPlatform(): PlatformInfo;

Defined in: src/platform/detector.ts:102

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

---

extractPlatformVersionInfo()

function extractPlatformVersionInfo(platformInfo): PlatformVersionInfo;

Defined in: src/platform/version-extractor.ts:152

Extract platform version information for voice reporting

Parameters

Parameter	Type	Description
platformInfo	PlatformInfo	Platform info from detector

Returns

PlatformVersionInfo

Platform version information suitable for voice reporting

---

getResponsiveVoice()

function getResponsiveVoice(options?): Promise<ResponsiveVoice>;

Defined in: src/responsivevoice.ts:564

Get or create the global ResponsiveVoice instance.

For ESM consumers, this is the recommended entry point:

const rv = await getResponsiveVoice({ apiKey: 'your-key' });
rv.speak('Hello');

Parameters

Parameter	Type	Description
options?	ResponsiveVoiceInitOptions	Init options (apiKey, voice defaults, feature flags)

Returns

Promise<ResponsiveVoice>

Promise that resolves to the initialized ResponsiveVoice instance

---

resetResponsiveVoice()

function resetResponsiveVoice(): void;

Defined in: src/responsivevoice.ts:580

Reset the global instance (for testing)

Returns

void

References

default

Renames and re-exports getResponsiveVoice

---

VoiceSelector

Re-exports VoiceSelector