@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

Error thrown when an API request fails

Extends

• ResponsiveVoiceError

Extended by

• AuthError
• NotFoundError
• RateLimitError
• ValidationError

Constructors

Constructor

new ApiError(
   message,
   status,
   statusText,
   url,
   body?,
   cause?): ApiError;

Defined in: src/errors.ts:41

Parameters

Parameter	Type
message	string
status	number
statusText	string
url	string
body?	unknown
cause?	Error

Returns

ApiError

Overrides

ResponsiveVoiceError.constructor

Properties

body?

readonly optional body?: unknown;

Defined in: src/errors.ts:36

Response body, if available

cause?

readonly optional cause?: Error;

Defined in: src/errors.ts:11

Original error that caused this error, if any

Inherited from

ResponsiveVoiceError.cause

message

message: string;

Defined in: lib.es5.d.ts:1075

Inherited from

ResponsiveVoiceError.message

name

name: string;

Defined in: lib.es5.d.ts:1074

Inherited from

ResponsiveVoiceError.name

stack?

optional stack?: string;

Defined in: lib.es5.d.ts:1076

Inherited from

ResponsiveVoiceError.stack

status

readonly status: number;

Defined in: src/errors.ts:30

HTTP status code of the failed request

statusText

readonly statusText: string;

Defined in: src/errors.ts:33

HTTP status text

url

readonly url: string;

Defined in: src/errors.ts:39

Request URL that failed

Accessors

isClientError

Get Signature

get isClientError(): boolean;

Defined in: src/errors.ts:60

Check if this error is a client error (4xx)

Returns

boolean

isRetryable

Get Signature

get isRetryable(): boolean;

Defined in: src/errors.ts:75

Check if this error is retryable Server errors (5xx) and rate limits (429) are retryable

Returns

boolean

isServerError

Get Signature

get isServerError(): boolean;

Defined in: src/errors.ts:67

Check if this error is a server error (5xx)

Returns

boolean

---

AuthError

Defined in: src/errors.ts:83

Error thrown when authentication fails (401/403)

Extends

• ApiError

Constructors

Constructor

new AuthError(
   message,
   status,
   statusText,
   url,
   body?): AuthError;

Defined in: src/errors.ts:84

Parameters

Parameter	Type
message	string
status	number
statusText	string
url	string
body?	unknown

Returns

AuthError

Overrides

ApiError.constructor

Properties

body?

readonly optional body?: unknown;

Defined in: src/errors.ts:36

Response body, if available

Inherited from

ApiError.body

cause?

readonly optional cause?: Error;

Defined in: src/errors.ts:11

Original error that caused this error, if any

Inherited from

ApiError.cause

message

message: string;

Defined in: lib.es5.d.ts:1075

Inherited from

ApiError.message

name

name: string;

Defined in: lib.es5.d.ts:1074

Inherited from

ApiError.name

stack?

optional stack?: string;

Defined in: lib.es5.d.ts:1076

Inherited from

ApiError.stack

status

readonly status: number;

Defined in: src/errors.ts:30

HTTP status code of the failed request

Inherited from

ApiError.status

statusText

readonly statusText: string;

Defined in: src/errors.ts:33

HTTP status text

Inherited from

ApiError.statusText

url

readonly url: string;

Defined in: src/errors.ts:39

Request URL that failed

Inherited from

ApiError.url

Accessors

isClientError

Get Signature

get isClientError(): boolean;

Defined in: src/errors.ts:60

Check if this error is a client error (4xx)

Returns

boolean

Inherited from

ApiError.isClientError

isRetryable

Get Signature

get isRetryable(): boolean;

Defined in: src/errors.ts:75

Check if this error is retryable Server errors (5xx) and rate limits (429) are retryable

Returns

boolean

Inherited from

ApiError.isRetryable

isServerError

Get Signature

get isServerError(): boolean;

Defined in: src/errors.ts:67

Check if this error is a server error (5xx)

Returns

boolean

Inherited from

ApiError.isServerError

---

ClientVoiceCache

Defined in: src/voice-cache.ts:77

Client-side voice cache with multi-environment storage support.

Constructors

Constructor

new ClientVoiceCache(config?): ClientVoiceCache;

Defined in: src/voice-cache.ts:88

Parameters

Parameter	Type
config	VoiceCacheConfig

Returns

ClientVoiceCache

Properties

enabled

readonly enabled: boolean;

Defined in: src/voice-cache.ts:86

Whether caching is active; mirrors VoiceCacheConfig.enabled.

Methods

clear()

clear(): Promise<void>;

Defined in: src/voice-cache.ts:349

Clear the voice cache.

Returns

Promise<void>

getBrowserVoiceHash()

getBrowserVoiceHash(): Promise<string | null>;

Defined in: src/voice-cache.ts:321

Get the stored browser voice hash. Stored separately from voice data so it persists across API URL changes.

Returns

Promise<string | null>

getVoices()

getVoices(): Promise<CachedVoiceData | null>;

Defined in: src/voice-cache.ts:260

Get cached voice data.

Returns

Promise<CachedVoiceData | null>

Cached voice data or null if not cached / cache disabled

isFresh()

isFresh(data): boolean;

Defined in: src/voice-cache.ts:284

Check whether cached data is still fresh (within TTL).

Parameters

Parameter	Type
data	CachedVoiceData

Returns

boolean

migrateVoiceCache()

migrateVoiceCache(): Promise<void>;

Defined in: src/voice-cache.ts:113

Migrate legacy unscoped cache entries to API-key-scoped keys. Should be called once during initialization when apiKey is available.

Returns

Promise<void>

setBrowserVoiceHash()

setBrowserVoiceHash(hash): Promise<void>;

Defined in: src/voice-cache.ts:335

Store the browser voice hash.

Parameters

Parameter	Type
hash	string

Returns

Promise<void>

setVoices()

setVoices(
   etag,
   voices,
systemVoices): Promise<void>;

Defined in: src/voice-cache.ts:296

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

static create(config):
  | ClientVoiceCache
  | NoOpCache;

Defined in: src/voice-cache.ts:364

Create a ClientVoiceCache or NoOpCache based on configuration.

Parameters

Parameter	Type
config	| VoiceCacheConfig | undefined

Returns

| ClientVoiceCache | NoOpCache

---

FileStorage

Defined in: src/file-storage.ts:11

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

Constructors

Constructor

new FileStorage(fileId): FileStorage;

Defined in: src/file-storage.ts:26

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

Methods

getItem()

getItem(key): Promise<string | null>;

Defined in: src/file-storage.ts:56

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.getItem

removeItem()

removeItem(key): Promise<void>;

Defined in: src/file-storage.ts:97

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.removeItem

setItem()

setItem(key, value): Promise<void>;

Defined in: src/file-storage.ts:73

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.setItem

---

MemoryStorage

Defined in: src/voice-cache.ts:13

In-memory storage adapter. Lives for the process/page lifetime.

Implements

• CacheStorageAdapter

Constructors

Constructor

new MemoryStorage(): MemoryStorage;

Returns

MemoryStorage

Methods

getItem()

getItem(key): string | null;

Defined in: src/voice-cache.ts:17

Retrieve a stored value by key, or null if absent.

Parameters

Parameter	Type
key	string

Returns

string | null

Implementation of

CacheStorageAdapter.getItem

removeItem()

removeItem(key): void;

Defined in: src/voice-cache.ts:27

Remove the value stored under key. No-op if absent.

Parameters

Parameter	Type
key	string

Returns

void

Implementation of

CacheStorageAdapter.removeItem

setItem()

setItem(key, value): void;

Defined in: src/voice-cache.ts:22

Store value under key, overwriting any existing entry.

Parameters

Parameter	Type
key	string
value	string

Returns

void

Implementation of

CacheStorageAdapter.setItem

---

NetworkError

Defined in: src/errors.ts:156

Error thrown when a network error occurs

Extends

• ResponsiveVoiceError

Extended by

• TimeoutError

Constructors

Constructor

new NetworkError(
   message,
   url,
   cause?): NetworkError;

Defined in: src/errors.ts:160

Parameters

Parameter	Type
message	string
url	string
cause?	Error

Returns

NetworkError

Overrides

ResponsiveVoiceError.constructor

Properties

cause?

readonly optional cause?: Error;

Defined in: src/errors.ts:11

Original error that caused this error, if any

Inherited from

ResponsiveVoiceError.cause

message

message: string;

Defined in: lib.es5.d.ts:1075

Inherited from

ResponsiveVoiceError.message

name

name: string;

Defined in: lib.es5.d.ts:1074

Inherited from

ResponsiveVoiceError.name

stack?

optional stack?: string;

Defined in: lib.es5.d.ts:1076

Inherited from

ResponsiveVoiceError.stack

url

readonly url: string;

Defined in: src/errors.ts:158

Request URL that failed

Accessors

isRetryable

Get Signature

get isRetryable(): boolean;

Defined in: src/errors.ts:169

Network errors are always retryable

Returns

boolean

---

NotFoundError

Defined in: src/errors.ts:93

Error thrown when a resource is not found (404)

Extends

• ApiError

Constructors

Constructor

new NotFoundError(
   message,
   resource,
   status,
   statusText,
   url,
   body?): NotFoundError;

Defined in: src/errors.ts:97

Parameters

Parameter	Type
message	string
resource	string
status	number
statusText	string
url	string
body?	unknown

Returns

NotFoundError

Overrides

ApiError.constructor

Properties

body?

readonly optional body?: unknown;

Defined in: src/errors.ts:36

Response body, if available

Inherited from

ApiError.body

cause?

readonly optional cause?: Error;

Defined in: src/errors.ts:11

Original error that caused this error, if any

Inherited from

ApiError.cause

message

message: string;

Defined in: lib.es5.d.ts:1075

Inherited from

ApiError.message

name

name: string;

Defined in: lib.es5.d.ts:1074

Inherited from

ApiError.name

resource

readonly resource: string;

Defined in: src/errors.ts:95

The resource that was not found

stack?

optional stack?: string;

Defined in: lib.es5.d.ts:1076

Inherited from

ApiError.stack

status

readonly status: number;

Defined in: src/errors.ts:30

HTTP status code of the failed request

Inherited from

ApiError.status

statusText

readonly statusText: string;

Defined in: src/errors.ts:33

HTTP status text

Inherited from

ApiError.statusText

url

readonly url: string;

Defined in: src/errors.ts:39

Request URL that failed

Inherited from

ApiError.url

Accessors

isClientError

Get Signature

get isClientError(): boolean;

Defined in: src/errors.ts:60

Check if this error is a client error (4xx)

Returns

boolean

Inherited from

ApiError.isClientError

isRetryable

Get Signature

get isRetryable(): boolean;

Defined in: src/errors.ts:75

Check if this error is retryable Server errors (5xx) and rate limits (429) are retryable

Returns

boolean

Inherited from

ApiError.isRetryable

isServerError

Get Signature

get isServerError(): boolean;

Defined in: src/errors.ts:67

Check if this error is a server error (5xx)

Returns

boolean

Inherited from

ApiError.isServerError

---

RateLimitError

Defined in: src/errors.ts:114

Error thrown when rate limited (429)

Extends

• ApiError

Constructors

Constructor

new RateLimitError(
   message,
   status,
   statusText,
   url,
   retryAfter?,
   body?): RateLimitError;

Defined in: src/errors.ts:118

Parameters

Parameter	Type
message	string
status	number
statusText	string
url	string
retryAfter?	number
body?	unknown

Returns

RateLimitError

Overrides

ApiError.constructor

Properties

body?

readonly optional body?: unknown;

Defined in: src/errors.ts:36

Response body, if available

Inherited from

ApiError.body

cause?

readonly optional cause?: Error;

Defined in: src/errors.ts:11

Original error that caused this error, if any

Inherited from

ApiError.cause

message

message: string;

Defined in: lib.es5.d.ts:1075

Inherited from

ApiError.message

name

name: string;

Defined in: lib.es5.d.ts:1074

Inherited from

ApiError.name

retryAfter?

readonly optional retryAfter?: number;

Defined in: src/errors.ts:116

Time in seconds to wait before retrying, if provided by the API

stack?

optional stack?: string;

Defined in: lib.es5.d.ts:1076

Inherited from

ApiError.stack

status

readonly status: number;

Defined in: src/errors.ts:30

HTTP status code of the failed request

Inherited from

ApiError.status

statusText

readonly statusText: string;

Defined in: src/errors.ts:33

HTTP status text

Inherited from

ApiError.statusText

url

readonly url: string;

Defined in: src/errors.ts:39

Request URL that failed

Inherited from

ApiError.url

Accessors

isClientError

Get Signature

get isClientError(): boolean;

Defined in: src/errors.ts:60

Check if this error is a client error (4xx)

Returns

boolean

Inherited from

ApiError.isClientError

isRetryable

Get Signature

get isRetryable(): boolean;

Defined in: src/errors.ts:75

Check if this error is retryable Server errors (5xx) and rate limits (429) are retryable

Returns

boolean

Inherited from

ApiError.isRetryable

isServerError

Get Signature

get isServerError(): boolean;

Defined in: src/errors.ts:67

Check if this error is a server error (5xx)

Returns

boolean

Inherited from

ApiError.isServerError

---

ResponseValidationError

Defined in: src/errors.ts:210

Error thrown when API response validation fails This is for client-side validation of response data against expected schemas

Extends

• ResponsiveVoiceError

Constructors

Constructor

new ResponseValidationError(
   message,
   issues,
   data): ResponseValidationError;

Defined in: src/errors.ts:217

Parameters

Parameter	Type
message	string
issues	{ message: string; path: string; }[]
data	unknown

Returns

ResponseValidationError

Overrides

ResponsiveVoiceError.constructor

Properties

cause?

readonly optional cause?: Error;

Defined in: src/errors.ts:11

Original error that caused this error, if any

Inherited from

ResponsiveVoiceError.cause

data

readonly data: unknown;

Defined in: src/errors.ts:215

The raw response data that failed validation

issues

readonly issues: {
  message: string;
  path: string;
}[];

Defined in: src/errors.ts:212

Detailed validation issues from Zod

message

message: string;

path

path: string;

message

message: string;

Defined in: lib.es5.d.ts:1075

Inherited from

ResponsiveVoiceError.message

name

name: string;

Defined in: lib.es5.d.ts:1074

Inherited from

ResponsiveVoiceError.name

stack?

optional stack?: string;

Defined in: lib.es5.d.ts:1076

Inherited from

ResponsiveVoiceError.stack

Accessors

formattedIssues

Get Signature

get formattedIssues(): string;

Defined in: src/errors.ts:227

Get a formatted string of all validation issues

Returns

string

---

ResponsiveVoiceAPIClient

Defined in: src/client.ts:93

ResponsiveVoice API Client

Provides methods to interact with the ResponsiveVoice TTS API:

• Synthesize text to speech
• List available voices
• Get specific voice information

Example

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

new ResponsiveVoiceAPIClient(config): ResponsiveVoiceAPIClient;

Defined in: src/client.ts:112

Create a new ResponsiveVoice API client

Parameters

Parameter	Type	Description
config	ResponsiveVoiceAPIClientConfig	Client configuration

Returns

ResponsiveVoiceAPIClient

Throws

Error if apiKey is not provided

Accessors

baseUrl

Get Signature

get baseUrl(): string;

Defined in: src/client.ts:169

Get the current base URL

Returns

string

Methods

clearVoiceCache()

clearVoiceCache(): Promise<void>;

Defined in: src/client.ts:456

Clear the client-side voice cache

Returns

Promise<void>

getBrowserVoiceHash()

getBrowserVoiceHash(): Promise<string | null>;

Defined in: src/client.ts:471

Get the stored browser voice hash. Used by core to check if browser voices changed since last report.

Returns

Promise<string | null>

getCachedVoiceData()

getCachedVoiceData(): Promise<CachedVoiceData | null>;

Defined in: src/client.ts:463

Get the raw cached voice data.

Returns

Promise<CachedVoiceData | null>

getConfig()

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

Fetch the per-website configuration (features, voice profile, analytics). Returns a typed WebsiteConfigResponse validated against the Zod schema.

Parameters

Parameter	Type
requestOptions?	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()

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

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

const voice = await client.getVoice('UK English Female');
console.log(`Voice service: ${voice.service}`);

getVoices()

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

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	Optional filters to apply
requestOptions?	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

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

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

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

const germanVoices = await client.getVoicesByLanguage('de-DE');
const frenchVoices = await client.getVoicesByLanguage('fr');

refreshAuth()

refreshAuth(requestOptions?): Promise<{
  exp: number;
  token: string;
}>;

Defined in: src/client.ts:645

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

Returns

Promise<{ exp: number; token: string; }>

reportVoices()

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

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 & { 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

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

synthesize(options, requestOptions?): Promise<{
  blob: Blob;
  duration?: number;
  format: "mp3" | "ogg" | "wav";
  prosodyApplied: ("pitch" | "rate" | "volume")[];
  url: string;
}>;

Defined in: src/client.ts:194

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

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

synthesizeStream(options, requestOptions?): AsyncGenerator<StreamChunk>;

Defined in: src/client.ts:250

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	Optional request configuration (timeout, signal)

Returns

AsyncGenerator<StreamChunk>

AsyncGenerator yielding StreamChunk objects

Example

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

updateBaseUrl(newUrl): void;

Defined in: src/client.ts:162

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

verifyOrigin(token, requestOptions?): Promise<VerifyOriginResponse>;

Defined in: src/client.ts:674

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

Returns

Promise<VerifyOriginResponse>

---

ResponsiveVoiceError

Defined in: src/errors.ts:9

Base error class for all API client errors

Extends

• Error

Extended by

• ApiError
• NetworkError
• ResponseValidationError
• RetryExhaustedError

Constructors

Constructor

new ResponsiveVoiceError(message, cause?): ResponsiveVoiceError;

Defined in: src/errors.ts:13

Parameters

Parameter	Type
message	string
cause?	Error

Returns

ResponsiveVoiceError

Overrides

Error.constructor

Properties

cause?

readonly optional cause?: Error;

Defined in: src/errors.ts:11

Original error that caused this error, if any

Overrides

Error.cause

message

message: string;

Defined in: lib.es5.d.ts:1075

Inherited from

Error.message

name

name: string;

Defined in: lib.es5.d.ts:1074

Inherited from

Error.name

stack?

optional stack?: string;

Defined in: lib.es5.d.ts:1076

Inherited from

Error.stack

---

RetryExhaustedError

Defined in: src/errors.ts:191

Error thrown when all retry attempts are exhausted

Extends

• ResponsiveVoiceError

Constructors

Constructor

new RetryExhaustedError(
   message,
   attempts,
   lastError): RetryExhaustedError;

Defined in: src/errors.ts:198

Parameters

Parameter	Type
message	string
attempts	number
lastError	Error

Returns

RetryExhaustedError

Overrides

ResponsiveVoiceError.constructor

Properties

attempts

readonly attempts: number;

Defined in: src/errors.ts:193

Number of attempts made

cause?

readonly optional cause?: Error;

Defined in: src/errors.ts:11

Original error that caused this error, if any

Inherited from

ResponsiveVoiceError.cause

lastError

readonly lastError: Error;

Defined in: src/errors.ts:196

The last error that occurred

message

message: string;

Defined in: lib.es5.d.ts:1075

Inherited from

ResponsiveVoiceError.message

name

name: string;

Defined in: lib.es5.d.ts:1074

Inherited from

ResponsiveVoiceError.name

stack?

optional stack?: string;

Defined in: lib.es5.d.ts:1076

Inherited from

ResponsiveVoiceError.stack

---

TimeoutError

Defined in: src/errors.ts:177

Error thrown when a request times out

Extends

• NetworkError

Constructors

Constructor

new TimeoutError(
   message,
   url,
   timeout,
   cause?): TimeoutError;

Defined in: src/errors.ts:181

Parameters

Parameter	Type
message	string
url	string
timeout	number
cause?	Error

Returns

TimeoutError

Overrides

NetworkError.constructor

Properties

cause?

readonly optional cause?: Error;

Defined in: src/errors.ts:11

Original error that caused this error, if any

Inherited from

NetworkError.cause

message

message: string;

Defined in: lib.es5.d.ts:1075

Inherited from

NetworkError.message

name

name: string;

Defined in: lib.es5.d.ts:1074

Inherited from

NetworkError.name

stack?

optional stack?: string;

Defined in: lib.es5.d.ts:1076

Inherited from

NetworkError.stack

timeout

readonly timeout: number;

Defined in: src/errors.ts:179

Timeout duration in milliseconds

url

readonly url: string;

Defined in: src/errors.ts:158

Request URL that failed

Inherited from

NetworkError.url

Accessors

isRetryable

Get Signature

get isRetryable(): boolean;

Defined in: src/errors.ts:169

Network errors are always retryable

Returns

boolean

Inherited from

NetworkError.isRetryable

---

ValidationError

Defined in: src/errors.ts:135

Error thrown when request validation fails (400)

Extends

• ApiError

Constructors

Constructor

new ValidationError(
   message,
   status,
   statusText,
   url,
   errors?,
   body?): ValidationError;

Defined in: src/errors.ts:139

Parameters

Parameter	Type
message	string
status	number
statusText	string
url	string
errors?	Record<string, string[]>
body?	unknown

Returns

ValidationError

Overrides

ApiError.constructor

Properties

body?

readonly optional body?: unknown;

Defined in: src/errors.ts:36

Response body, if available

Inherited from

ApiError.body

cause?

readonly optional cause?: Error;

Defined in: src/errors.ts:11

Original error that caused this error, if any

Inherited from

ApiError.cause

errors?

readonly optional errors?: Record<string, string[]>;

Defined in: src/errors.ts:137

Validation error details, if provided by the API

message

message: string;

Defined in: lib.es5.d.ts:1075

Inherited from

ApiError.message

name

name: string;

Defined in: lib.es5.d.ts:1074

Inherited from

ApiError.name

stack?

optional stack?: string;

Defined in: lib.es5.d.ts:1076

Inherited from

ApiError.stack

status

readonly status: number;

Defined in: src/errors.ts:30

HTTP status code of the failed request

Inherited from

ApiError.status

statusText

readonly statusText: string;

Defined in: src/errors.ts:33

HTTP status text

Inherited from

ApiError.statusText

url

readonly url: string;

Defined in: src/errors.ts:39

Request URL that failed

Inherited from

ApiError.url

Accessors

isClientError

Get Signature

get isClientError(): boolean;

Defined in: src/errors.ts:60

Check if this error is a client error (4xx)

Returns

boolean

Inherited from

ApiError.isClientError

isRetryable

Get Signature

get isRetryable(): boolean;

Defined in: src/errors.ts:75

Check if this error is retryable Server errors (5xx) and rate limits (429) are retryable

Returns

boolean

Inherited from

ApiError.isRetryable

isServerError

Get Signature

get isServerError(): boolean;

Defined in: src/errors.ts:67

Check if this error is a server error (5xx)

Returns

boolean

Inherited from

ApiError.isServerError

---

WebSocketConnection

Defined in: src/websocket.ts:125

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 iterator shape as the HTTP synthesizeStream() fallback so consumers can swap transports without reshaping their audio pipeline.

Instantiate via 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

new WebSocketConnection(config): WebSocketConnection;

Defined in: src/websocket.ts:136

Parameters

Parameter	Type
config	WebSocketConnectionConfig

Returns

WebSocketConnection

Accessors

connected

Get Signature

get connected(): boolean;

Defined in: src/websocket.ts:158

Whether the WebSocket is currently open and ready

Returns

boolean

Methods

cancel()

cancel(requestId): void;

Defined in: src/websocket.ts:319

Cancel an in-flight synthesis request.

Parameters

Parameter	Type
requestId	string

Returns

void

close()

close(): void;

Defined in: src/websocket.ts:228

Close the connection gracefully.

Returns

void

connect()

connect(): Promise<void>;

Defined in: src/websocket.ts:166

Open the WebSocket connection. Resolves when the connection is open. If already connected, returns immediately.

Returns

Promise<void>

synthesizeStream()

synthesizeStream(request): AsyncGenerator<StreamChunk>;

Defined in: src/websocket.ts:248

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>

Interfaces

CachedVoiceData

Defined in: src/types.ts:55

Cached voice data stored in the client-side cache.

Properties

cachedAt

cachedAt: number;

Defined in: src/types.ts:63

Timestamp when the data was cached

etag

etag: string;

Defined in: src/types.ts:57

ETag from the server response

systemVoices?

optional systemVoices?: SystemVoiceResponse[];

Defined in: src/types.ts:61

Cached system voices (dense; reachable from voices[*].voiceIDs chains)

voices

voices: VoiceData[];

Defined in: src/types.ts:59

Cached voice collection

---

CacheStorageAdapter

Defined in: src/types.ts:10

Storage adapter interface for plugging in custom cache backends. All methods may return synchronously or asynchronously.

Methods

getItem()

getItem(key): string | Promise<string | null> | null;

Defined in: src/types.ts:12

Retrieve a value by key, or null if not present.

Parameters

Parameter	Type
key	string

Returns

string | Promise<string | null> | null

removeItem()

removeItem(key): void | Promise<void>;

Defined in: src/types.ts:16

Remove the value stored under key. No-op if absent.

Parameters

Parameter	Type
key	string

Returns

void | Promise<void>

setItem()

setItem(key, value): void | Promise<void>;

Defined in: src/types.ts:14

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

Rate-limit headers surfaced from a response; a field is null when absent.

Properties

limit

limit: number | null;

Defined in: src/types.ts:131

X-RateLimit-Limit — max requests per window.

remaining

remaining: number | null;

Defined in: src/types.ts:133

X-RateLimit-Remaining — requests left in the current window.

retryAfter

retryAfter: number | null;

Defined in: src/types.ts:135

Retry-After — seconds to wait, present on 429.

---

RequestOptions

Defined in: src/types.ts:191

Request options for API calls

Properties

signal?

optional signal?: AbortSignal;

Defined in: src/types.ts:196

Custom signal for abort control

skipRetry?

optional skipRetry?: boolean;

Defined in: src/types.ts:199

Skip retry logic for this request

timeout?

optional timeout?: number;

Defined in: src/types.ts:193

Custom timeout for this request

---

ResolvedClientConfig

Defined in: src/types.ts:141

Resolved configuration with all defaults applied

Properties

apiKey

apiKey: string;

Defined in: src/types.ts:143

API key used to authenticate every request.

apiSecret

apiSecret: string | null;

Defined in: src/types.ts:145

Server-issued secret; null when unset (browser callers).

authHeaders

authHeaders:
  | (() =>
  | Record<string, string>
  | Promise<Record<string, string>>)
  | null;

Defined in: src/types.ts:147

Auth-header injection hook; null when unset (server callers using only apiKey+secret).

baseUrl

baseUrl: string;

Defined in: src/types.ts:151

Fully-resolved base URL for the TTS API (no trailing slash).

fetch

fetch: (input, init?) => Promise<Response>;

Defined in: src/types.ts:159

Fetch implementation (defaults to the global fetch).

MDN Reference

Parameters

Parameter	Type
input	RequestInfo | URL
init?	RequestInit

Returns

Promise<Response>

onRateLimit

onRateLimit: ((info) => void) | null;

Defined in: src/types.ts:165

Rate-limit header observer; null when unset.

onServerUrlChange

onServerUrlChange: ((newUrl) => void) | null;

Defined in: src/types.ts:163

Callback invoked when the server assigns a new base URL (X-RV-Server-URL header).

onTokenRenewed

onTokenRenewed: ((renewed) => void) | null;

Defined in: src/types.ts:149

Sliding-renewal pickup callback; null when unset.

retryAttempts

retryAttempts: number;

Defined in: src/types.ts:155

Max retry attempts for transient failures.

retryDelay

retryDelay: number;

Defined in: src/types.ts:157

Base delay between retries in milliseconds (exponential backoff multiplies this).

timeout

timeout: number;

Defined in: src/types.ts:153

Per-request timeout in milliseconds.

voiceCache

voiceCache: VoiceCacheConfig;

Defined in: src/types.ts:161

Voice-cache configuration resolved with defaults applied.

---

ResponsiveVoiceAPIClientConfig

Defined in: src/types.ts:69

Configuration for the ResponsiveVoice API client

Properties

apiKey

apiKey: string;

Defined in: src/types.ts:71

API key — account identifier; never used as a credential alone.

apiSecret?

optional apiSecret?: string;

Defined in: src/types.ts:79

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?

optional authHeaders?: () =>
  | Record<string, string>
| Promise<Record<string, string>>;

Defined in: src/types.ts:89

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 <jwt> 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?

optional baseUrl?: string;

Defined in: src/types.ts:99

Base URL for the API (default: https://texttospeech.responsivevoice.org/v2)

fetch?

optional fetch?: (input, init?) => Promise<Response>;

Defined in: src/types.ts:111

Custom fetch implementation (for testing or server-side usage)

MDN Reference

Parameters

Parameter	Type
input	RequestInfo | URL
init?	RequestInit

Returns

Promise<Response>

onRateLimit?

optional onRateLimit?: (info) => void;

Defined in: src/types.ts:125

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

Returns

void

onServerUrlChange?

optional onServerUrlChange?: (newUrl) => void;

Defined in: src/types.ts:117

Callback invoked when the server assigns a different URL via X-Server-URL header

Parameters

Parameter	Type
newUrl	string

Returns

void

onTokenRenewed?

optional onTokenRenewed?: (renewed) => void;

Defined in: src/types.ts:96

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?

optional retryAttempts?: number;

Defined in: src/types.ts:105

Number of retry attempts for transient errors (default: 3)

retryDelay?

optional retryDelay?: number;

Defined in: src/types.ts:108

Base delay between retries in milliseconds (default: 1000)

timeout?

optional timeout?: number;

Defined in: src/types.ts:102

Request timeout in milliseconds (default: 30000)

voiceCache?

optional voiceCache?: VoiceCacheConfig;

Defined in: src/types.ts:114

Voice cache configuration (enabled by default)

---

RetryConfig

Defined in: src/retry.ts:10

Configuration for retry behavior

Properties

backoffMultiplier

backoffMultiplier: number;

Defined in: src/retry.ts:21

Multiplier for exponential backoff

baseDelay

baseDelay: number;

Defined in: src/retry.ts:15

Base delay between retries in milliseconds

jitter

jitter: boolean;

Defined in: src/retry.ts:24

Whether to add jitter to delay times

maxAttempts

maxAttempts: number;

Defined in: src/retry.ts:12

Maximum number of retry attempts (not including the initial request)

maxDelay

maxDelay: number;

Defined in: src/retry.ts:18

Maximum delay between retries in milliseconds

---

RetryDecision

Defined in: src/retry.ts:41

Result of checking if an error is retryable

Properties

delay?

optional delay?: number;

Defined in: src/retry.ts:46

Suggested delay before retrying, in milliseconds

shouldRetry

shouldRetry: boolean;

Defined in: src/retry.ts:43

Whether the operation should be retried

---

VerifyOriginResponse

Defined in: src/client.ts:63

Response from POST /v2/auth/verify-origin.

Properties

origin

origin: string;

Defined in: src/client.ts:67

The proven origin (scheme://host[:port]).

verified

verified: boolean;

Defined in: src/client.ts:65

Whether the request origin was verified for the apiKey.

---

VoiceCacheConfig

Defined in: src/types.ts:32

Configuration for the client-side voice cache.

Properties

apiKey?

optional apiKey?: string;

Defined in: src/types.ts:49

API key used to scope cache keys per-website (prevents cross-site cache collisions on same domain)

customStorage?

optional customStorage?: CacheStorageAdapter;

Defined in: src/types.ts:40

Custom storage adapter — overrides storage when provided

enabled?

optional enabled?: boolean;

Defined in: src/types.ts:34

Whether caching is enabled (default: true)

keyPrefix?

optional keyPrefix?: string;

Defined in: src/types.ts:43

Key prefix for cache entries (default: 'rv-voice-cache')

storage?

optional storage?: CacheStorageType;

Defined in: src/types.ts:37

Storage backend selection (default: 'auto')

ttl?

optional ttl?: number;

Defined in: src/types.ts:46

Cache TTL in seconds — cached data within this window is served without a network request (default: 300)

---

VoiceFilters

Defined in: src/types.ts:171

Filters for listing voices

Properties

browser?

optional browser?: string;

Defined in: src/types.ts:179

Platform context for personalized voice selection (not a filter for cache bypass)

browserVersion?

optional browserVersion?: string;

Defined in: src/types.ts:181

Browser version (paired with browser for platform-aware voice resolution)

gender?

optional gender?: "male" | "female";

Defined in: src/types.ts:176

Filter by gender

lang?

optional lang?: string;

Defined in: src/types.ts:173

Filter by language code

os?

optional os?: string;

Defined in: src/types.ts:183

Operating system name (paired with os_version for platform-aware voice resolution)

osVersion?

optional osVersion?: string;

Defined in: src/types.ts:185

Operating system version (paired with os for platform-aware voice resolution)

---

WebSocketConnectionConfig

Defined in: src/websocket.ts:39

Configuration for constructing a 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?

optional apiKey?: string;

Defined in: src/websocket.ts:43

API key for authentication

autoReconnect?

optional autoReconnect?: boolean;

Defined in: src/websocket.ts:53

Auto-reconnect on unexpected close.

Default Value

true

baseUrl

baseUrl: string;

Defined in: src/websocket.ts:41

Base URL of the TTS API (https://...) — will be converted to wss://

getAuthToken?

optional getAuthToken?: () => Promise<string | undefined>;

Defined in: src/websocket.ts:49

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?

optional maxReconnectAttempts?: number;

Defined in: src/websocket.ts:55

Max reconnect attempts before giving up.

Default Value

5

pingInterval?

optional pingInterval?: number;

Defined in: src/websocket.ts:51

Ping interval in ms to keep the connection alive.

Default Value

25000

reconnectDelay?

optional reconnectDelay?: number;

Defined in: src/websocket.ts:57

Base delay between reconnect attempts in ms (exponential backoff).

Default Value

1000

WebSocket?

optional WebSocket?: (url) => WebSocket;

Defined in: src/websocket.ts:68

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

import WebSocket from 'ws';
new WebSocketConnection({ baseUrl: '...', WebSocket });

Type Aliases

CacheStorageType

type CacheStorageType = "auto" | "localStorage" | "sessionStorage" | "filesystem" | "memory";

Defined in: src/types.ts:27

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

const DEFAULT_RETRY_CONFIG: RetryConfig;

Defined in: src/retry.ts:30

Default retry configuration

Functions

calculateRetryDelay()

function calculateRetryDelay(
   attempt,
   config,
   suggestedDelay?): number;

Defined in: src/retry.ts:90

Calculate delay for a retry attempt using exponential backoff

Parameters

Parameter	Type	Description
attempt	number	The retry attempt number (1-based)
config	RetryConfig	Retry configuration
suggestedDelay?	number	Optional suggested delay (e.g., from Retry-After header)

Returns

number

Delay in milliseconds

---

createRetryWrapper()

function createRetryWrapper(config?): <T>(fn) => Promise<T>;

Defined in: src/retry.ts:178

Create a retry wrapper with pre-configured settings

Parameters

Parameter	Type
config	Partial<RetryConfig>

Returns

<T>(fn) => Promise<T>

---

isRetryableError()

function isRetryableError(error): RetryDecision;

Defined in: src/retry.ts:52

Determine if an error is retryable

Parameters

Parameter	Type
error	unknown

Returns

RetryDecision

---

withRetry()

function withRetry<T>(fn, config?): Promise<T>;

Defined in: src/retry.ts:130

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

---

AudioResponse

Re-exports AudioResponse

---

StreamAudioChunk

Re-exports StreamAudioChunk

---

StreamChunk

Re-exports StreamChunk

---

StreamEnd

Re-exports StreamEnd

---

StreamError

Re-exports StreamError

---

StreamMetadata

Re-exports StreamMetadata

---

SynthesizeRequest

Re-exports SynthesizeRequest

---

SynthesizeResponse

Re-exports SynthesizeResponse

---

SystemVoice

Re-exports SystemVoice

---

TTSService

Re-exports TTSService

---

Voice

Re-exports Voice

---

VoiceGender

Re-exports VoiceGender