@ottervoice/provider-elevenlabs

Documentation / @ottervoice/provider-elevenlabs

@ottervoice/provider-elevenlabs

ElevenLabs Scribe real-time streaming ASR provider for OtterVoice over WebSocket.

Install

npm install @ottervoice/core @ottervoice/provider-elevenlabs

Usage

import { createElevenLabsASR } from '@ottervoice/provider-elevenlabs';

const asr = createElevenLabsASR({
  tokenBrokerUrl: '/api/voice-token',
  tokenBrokerHeaders: { authorization: `Bearer ${applicationSessionToken}` },
  tokenBrokerSessionId: voiceSessionId,
  modelId: 'scribe_v2_realtime',
});

Use this direct-client mode only when the broker returns a short-lived, least-privilege credential or a signed URL that already locks route/model policy. Otherwise keep the provider and its configuration behind your application server.

Links

Documentation · GitHub

License

MIT

Interfaces

ElevenLabsASROptions

Defined in: provider-elevenlabs/src/index.ts:23

Options for createElevenLabsASR. Extends CredentialOptions and ElevenLabsQueryOptions. Direct-client broker use is appropriate only for a short-lived scoped credential or a server-locked signed URL.

Extends

CredentialOptions.ElevenLabsQueryOptions

Properties

Property	Type	Description	Inherited from	Defined in
`apiKey?`	`string`	A long-lived key (server-side only — never ship to clients).	`CredentialOptions`.`apiKey`	provider-utils/dist/credential.d.ts:37
`baseUrl?`	`string`	Override the realtime listen endpoint.	-	provider-elevenlabs/src/index.ts:25
`fetch?`	`FetchLike`	Custom `fetch` implementation (tests / React Native polyfills).	`CredentialOptions`.`fetch`	provider-utils/dist/credential.d.ts:50
`language?`	`string`	BCP-47 language code; overridden by ASRSessionOptions.language when set.	`ElevenLabsQueryOptions`.`language`	provider-elevenlabs/src/decode.ts:16
`modelId?`	`string`	ElevenLabs STT model id (e.g. `scribe_v2_realtime`).	`ElevenLabsQueryOptions`.`modelId`	provider-elevenlabs/src/decode.ts:14
`now?`	() => `number`	Clock override for deterministic expiry checks in tests.	`CredentialOptions`.`now`	provider-utils/dist/credential.d.ts:52
`tokenBrokerCredentials?`	`RequestCredentials`	Browser credential mode for the broker request. Use `include` for a cross-origin cookie session.	`CredentialOptions`.`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.	`CredentialOptions`.`tokenBrokerHeaders`	provider-utils/dist/credential.d.ts:44
`tokenBrokerSessionId?`	`string`	Application voice-session id sent to the broker for ownership checks, audit, and quotas.	`CredentialOptions`.`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.	`CredentialOptions`.`tokenBrokerUrl`	provider-utils/dist/credential.d.ts:39
`webSocket?`	`WebSocketCtor`	Inject a WebSocket constructor (defaults to the global).	-	provider-elevenlabs/src/index.ts:27

ElevenLabsQueryOptions

Defined in: provider-elevenlabs/src/decode.ts:12

Query knobs mapped onto ElevenLabs realtime /v1/speech-to-text/realtime WebSocket URL.

Extended by

ElevenLabsASROptions

Properties

Property	Type	Description	Defined in
`language?`	`string`	BCP-47 language code; overridden by ASRSessionOptions.language when set.	provider-elevenlabs/src/decode.ts:16
`modelId?`	`string`	ElevenLabs STT model id (e.g. `scribe_v2_realtime`).	provider-elevenlabs/src/decode.ts:14

Variables

DEFAULT_BASE_URL

const DEFAULT_BASE_URL: "wss://api.elevenlabs.io/v1/speech-to-text/realtime" = 'wss://api.elevenlabs.io/v1/speech-to-text/realtime';

Defined in: provider-elevenlabs/src/decode.ts:6

Default ElevenLabs realtime speech-to-text WebSocket endpoint.

Functions

buildElevenLabsUrl()

function buildElevenLabsUrl(
   baseUrl,
   options,
   asr): string;

Defined in: provider-elevenlabs/src/decode.ts:30

Build the realtime STT URL. NOTE: ElevenLabs’ realtime ASR wire format is evolving — verify parameter and message names against the current docs. In a direct-client deployment, prefer a broker URL that returns a signed URL with the route/model already locked by the server.

Parameters

Parameter	Type	Description
`baseUrl`	`string`	Listen endpoint; usually DEFAULT_BASE_URL or a broker-signed URL.
`options`	`ElevenLabsQueryOptions`	Provider defaults for model / language.
`asr`	`ASRSessionOptions`	Per-session overrides from ASRSessionOptions.

Returns

string

Fully qualified wss:// URL including search params.

createElevenLabsASR()

function createElevenLabsASR(options): ASRProvider;

Defined in: provider-elevenlabs/src/index.ts:62

ElevenLabs Scribe realtime ASR provider over WebSocket. A broker-signed URL may be used when it locks the route/model policy server-side.

Parameters

Parameter	Type	Description
`options`	`ElevenLabsASROptions`	Credentials and optional listen endpoint / query overrides.

Returns

ASRProvider

decodeElevenLabs()

function decodeElevenLabs(data):
  | ASRDecodeResult
  | undefined;

Defined in: provider-elevenlabs/src/decode.ts:64

Decode one ElevenLabs realtime STT event, keeping provisional and final transcripts separate.

Parameters

Parameter	Type	Description
`data`	`string`	One ElevenLabs WebSocket text frame.

Returns

| ASRDecodeResult | undefined

A decoded transcript/error, or undefined for unrelated frames.