@ottervoice/provider-deepgram

Documentation / @ottervoice/provider-deepgram

@ottervoice/provider-deepgram

Deepgram real-time streaming ASR provider for OtterVoice over WebSocket.

Install

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

Usage

import { createDeepgramASR } from '@ottervoice/provider-deepgram';

const asr = createDeepgramASR({
  tokenBrokerUrl: '/api/voice-token',
  tokenBrokerHeaders: { authorization: `Bearer ${applicationSessionToken}` },
  tokenBrokerSessionId: voiceSessionId,
  model: 'nova-3',
  language: 'en-US',
});

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

DeepgramOptions

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

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

Extends

CredentialOptions.DeepgramQueryOptions

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 listen endpoint.	-	provider-deepgram/src/index.ts:25
`encoding?`	`string`	Raw audio encoding when not inferred from the runtime (e.g. `linear16`).	`DeepgramQueryOptions`.`encoding`	provider-deepgram/src/decode.ts:14
`fetch?`	`FetchLike`	Custom `fetch` implementation (tests / React Native polyfills).	`CredentialOptions`.`fetch`	provider-utils/dist/credential.d.ts:50
`interimResults?`	`boolean`	Request interim (`is_final: false`) Results; default from session options.	`DeepgramQueryOptions`.`interimResults`	provider-deepgram/src/decode.ts:18
`language?`	`string`	BCP-47 language; overridden by ASRSessionOptions.language when set.	`DeepgramQueryOptions`.`language`	provider-deepgram/src/decode.ts:12
`model?`	`string`	Deepgram model id (e.g. `nova-2`, `nova-3`).	`DeepgramQueryOptions`.`model`	provider-deepgram/src/decode.ts:10
`now?`	() => `number`	Clock override for deterministic expiry checks in tests.	`CredentialOptions`.`now`	provider-utils/dist/credential.d.ts:52
`punctuate?`	`boolean`	Ask Deepgram to add punctuation to transcripts.	`DeepgramQueryOptions`.`punctuate`	provider-deepgram/src/decode.ts:20
`sampleRate?`	`number`	Sample rate in Hz for PCM encodings; overridden by session options when set.	`DeepgramQueryOptions`.`sampleRate`	provider-deepgram/src/decode.ts:16
`smartFormat?`	`boolean`	Enable Deepgram smart formatting (numbers, dates, etc.).	`DeepgramQueryOptions`.`smartFormat`	provider-deepgram/src/decode.ts:22
`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-deepgram/src/index.ts:27

DeepgramQueryOptions

Defined in: provider-deepgram/src/decode.ts:8

Query knobs mapped onto Deepgram’s /v1/listen WebSocket URL.

Extended by

DeepgramOptions

Properties

Property	Type	Description	Defined in
`encoding?`	`string`	Raw audio encoding when not inferred from the runtime (e.g. `linear16`).	provider-deepgram/src/decode.ts:14
`interimResults?`	`boolean`	Request interim (`is_final: false`) Results; default from session options.	provider-deepgram/src/decode.ts:18
`language?`	`string`	BCP-47 language; overridden by ASRSessionOptions.language when set.	provider-deepgram/src/decode.ts:12
`model?`	`string`	Deepgram model id (e.g. `nova-2`, `nova-3`).	provider-deepgram/src/decode.ts:10
`punctuate?`	`boolean`	Ask Deepgram to add punctuation to transcripts.	provider-deepgram/src/decode.ts:20
`sampleRate?`	`number`	Sample rate in Hz for PCM encodings; overridden by session options when set.	provider-deepgram/src/decode.ts:16
`smartFormat?`	`boolean`	Enable Deepgram smart formatting (numbers, dates, etc.).	provider-deepgram/src/decode.ts:22

Variables

DEFAULT_BASE_URL

const DEFAULT_BASE_URL: "wss://api.deepgram.com/v1/listen" = 'wss://api.deepgram.com/v1/listen';

Defined in: provider-deepgram/src/decode.ts:5

Default Deepgram live listen WebSocket endpoint.

Functions

buildDeepgramUrl()

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

Defined in: provider-deepgram/src/decode.ts:33

Build the Deepgram listen WebSocket URL with query parameters.

Parameters

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

Returns

string

Fully qualified wss:// URL including search params.

createDeepgramASR()

function createDeepgramASR(options): ASRProvider;

Defined in: provider-deepgram/src/index.ts:45

Deepgram streaming ASR provider over WebSocket.

Parameters

Parameter	Type	Description
`options`	`DeepgramOptions`	Credentials plus listen URL / query options. Keep query policy server-owned unless a broker-signed URL locks it.

Returns

ASRProvider

decodeDeepgram()

function decodeDeepgram(data):
  | ASRDecodeResult
  | undefined;

Defined in: provider-deepgram/src/decode.ts:68

Decode Deepgram Results messages into transcript segments.

Parameters

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

Returns

| ASRDecodeResult | undefined

A decoded transcript result, or undefined for unrelated frames.