@ottervoice/provider-azure-speech

Documentation / @ottervoice/provider-azure-speech

@ottervoice/provider-azure-speech

Azure Cognitive Services text-to-speech provider for OtterVoice, using REST and SSML.

Install

npm install @ottervoice/core @ottervoice/provider-azure-speech

Usage

import { createAzureTTS } from '@ottervoice/provider-azure-speech';

const tts = createAzureTTS({
  region: 'eastus',
  voice: 'en-US-AvaMultilingualNeural',
  tokenBrokerUrl: '/api/voice-token',
  tokenBrokerHeaders: { authorization: `Bearer ${applicationSessionToken}` },
  tokenBrokerSessionId: voiceSessionId,
});

This is an explicit direct-client mode: Azure’s short-lived STS token avoids shipping the subscription key but does not lock voice, route, or budget. The standard production mode keeps this provider and voice on your application server. subscriptionKey is for trusted server-side code only.

Links

Documentation · GitHub

License

MIT

Interfaces

AzureTTSOptions

Defined in: provider-azure-speech/src/index.ts:33

Options for createAzureTTS. Region and neural voice are required; authenticate with subscriptionKey on a trusted server. tokenBrokerUrl enables an explicit direct-client mode only; Azure STS tokens do not enforce voice, route, or budget policy. Shares broker/fetch fields from CredentialOptions (use subscriptionKey instead of apiKey).

Extends

Omit<CredentialOptions, "apiKey">

Properties

Property	Type	Description	Inherited from	Defined in
`defaultFormat?`	`TTSFormat`	Default audio container when the request omits `format`.	-	provider-azure-speech/src/index.ts:43
`endpoint?`	`string`	Override the synthesis endpoint (defaults to the region host).	-	provider-azure-speech/src/index.ts:45
`fetch?`	`FetchLike`	Custom `fetch` implementation (tests / React Native polyfills).	`Omit.fetch`	provider-utils/dist/credential.d.ts:50
`language?`	`string`	BCP-47 language tag for SSML. Defaults to `en-US`.	-	provider-azure-speech/src/index.ts:41
`now?`	() => `number`	Clock override for deterministic expiry checks in tests.	`Omit.now`	provider-utils/dist/credential.d.ts:52
`region`	`string`	Azure region, e.g. `eastus`.	-	provider-azure-speech/src/index.ts:35
`subscriptionKey?`	`string`	Subscription key (server-side). Mutually exclusive with `tokenBrokerUrl`.	-	provider-azure-speech/src/index.ts:37
`tokenBrokerCredentials?`	`RequestCredentials`	Browser credential mode for the broker request. Use `include` for a cross-origin cookie session.	`Omit.tokenBrokerCredentials`	provider-utils/dist/credential.d.ts:48
`tokenBrokerHeaders?`	`Readonly`<`Record`<`string`, `string`>>	Application-authentication headers sent only to the token broker, such as a short-lived user session bearer token. Use browser-compatible characters.	`Omit.tokenBrokerHeaders`	provider-utils/dist/credential.d.ts:44
`tokenBrokerSessionId?`	`string`	Application voice-session id sent to the broker for ownership checks, audit, and quotas.	`Omit.tokenBrokerSessionId`	provider-utils/dist/credential.d.ts:46
`tokenBrokerUrl?`	`string`	Endpoint that mints short-lived, least-privilege tokens; broad provider bearer tokens are not client-safe.	`Omit.tokenBrokerUrl`	provider-utils/dist/credential.d.ts:39
`voice`	`string`	Neural voice name, e.g. `zh-CN-XiaoxiaoNeural`. Keep server-owned in standard mode.	-	provider-azure-speech/src/index.ts:39

SSMLOptions

Defined in: provider-azure-speech/src/ssml.ts:56

Default voice / language when TTSInput omits them.

Properties

Property	Type	Description	Defined in
`language`	`string`	BCP-47 language for the `<voice xml:lang>` attribute.	provider-azure-speech/src/ssml.ts:60
`voice`	`string`	Azure neural voice name (e.g. `zh-CN-XiaoxiaoNeural`).	provider-azure-speech/src/ssml.ts:58

Functions

azureOutputFormat()

function azureOutputFormat(format): string;

Defined in: provider-azure-speech/src/ssml.ts:26

Map a core TTSFormat to an Azure X-Microsoft-OutputFormat value.

Parameters

Parameter	Type	Description
`format`	`TTSFormat`	OtterVoice TTS format.

Returns

string

Azure output-format header value.

buildSSML()

function buildSSML(input, defaults): string;

Defined in: provider-azure-speech/src/ssml.ts:69

Build an SSML document for a synthesis request.

Parameters

Parameter	Type	Description
`input`	`TTSInput`	Text plus optional voice / rate / pitch overrides.
`defaults`	`SSMLOptions`	Adapter defaults when `input` omits voice or language.

Returns

string

createAzureTTS()

function createAzureTTS(options): TTSProvider;

Defined in: provider-azure-speech/src/index.ts:62

Azure Cognitive Services Text-to-Speech provider (REST + SSML).

Parameters

Parameter	Type	Description
`options`	`AzureTTSOptions`	Region, voice, and credentials (`subscriptionKey` or broker).

Returns

TTSProvider

escapeXml()

function escapeXml(text): string;

Defined in: provider-azure-speech/src/ssml.ts:40

Escape the five XML predefined entities so user text is SSML-safe.

Parameters

Parameter	Type
`text`	`string`

Returns

string

mimeTypeForFormat()

function mimeTypeForFormat(format): string;

Defined in: provider-azure-speech/src/ssml.ts:35

MIME type for a synthesized TTSFormat.

Parameters

Parameter	Type	Description
`format`	`TTSFormat`	OtterVoice TTS format.

Returns

string

ratePercent()

function ratePercent(speed): string;

Defined in: provider-azure-speech/src/ssml.ts:50

Convert a 0.5–2.0 multiplier into an Azure prosody rate percentage.

Parameters

Parameter	Type
`speed`	`number`

Returns

string