Voice Router SDK - Speechmatics Provider / adapters/speechmatics-adapter

adapters/speechmatics-adapter

Classes

SpeechmaticsAdapter

Speechmatics transcription provider adapter

Implements transcription for Speechmatics API with support for:

Batch transcription (async processing)
Speaker diarization
Enhanced accuracy models
Multi-language support
Sentiment analysis
Summarization
Custom vocabulary

Types are generated from the Speechmatics SDK batch spec.

See

src/generated/speechmatics/schema for type definitions
https://docs.speechmatics.com/ Speechmatics Documentation
https://docs.speechmatics.com/introduction/batch-guide Batch API Guide

Examples

import { SpeechmaticsAdapter } from '@meeting-baas/sdk';

const adapter = new SpeechmaticsAdapter();
adapter.initialize({
  apiKey: process.env.SPEECHMATICS_API_KEY
});

const result = await adapter.transcribe({
  type: 'url',
  url: 'https://example.com/audio.mp3'
}, {
  language: 'en'
});

console.log(result.data.text);

import { SpeechmaticsAdapter, SpeechmaticsRegion } from '@meeting-baas/sdk';

const adapter = new SpeechmaticsAdapter();
adapter.initialize({
  apiKey: process.env.SPEECHMATICS_API_KEY,
  region: SpeechmaticsRegion.us1  // USA endpoint
});

const result = await adapter.transcribe({
  type: 'url',
  url: 'https://example.com/meeting.mp3'
}, {
  language: 'en',
  diarization: true,
  metadata: {
    operating_point: 'enhanced'  // Higher accuracy model
  }
});

console.log('Speakers:', result.data.speakers);
console.log('Utterances:', result.data.utterances);

// Submit transcription
const submission = await adapter.transcribe({
  type: 'url',
  url: 'https://example.com/audio.mp3'
}, {
  language: 'en',
  summarization: true
});

const jobId = submission.data?.id;
console.log('Job ID:', jobId);

// Poll for completion
const poll = async () => {
  const status = await adapter.getTranscript(jobId);
  if (status.data?.status === 'completed') {
    console.log('Transcript:', status.data.text);
    console.log('Summary:', status.data.summary);
  } else if (status.data?.status === 'processing') {
    setTimeout(poll, 3000);
  }
};
await poll();

Extends

BaseAdapter

Methods

createErrorResponse()

protected createErrorResponse(error, statusCode?, code?): UnifiedTranscriptResponse

Helper method to create error responses with stack traces

Parameters

Parameter	Type	Description
`error`	`unknown`	Error object or unknown error
`statusCode?`	`number`	Optional HTTP status code
`code?`	`ErrorCode`	Optional error code (defaults to extracted or UNKNOWN_ERROR)

Returns

UnifiedTranscriptResponse

Inherited from

BaseAdapter.createErrorResponse

deleteTranscript()

deleteTranscript(transcriptId, force): Promise<{ success: boolean; }>

Delete a transcription job and its associated data

Removes the job and all associated resources from Speechmatics' servers. This action is irreversible.

Parameters

Parameter	Type	Default value	Description
`transcriptId`	`string`	`undefined`	The job ID to delete
`force`	`boolean`	`false`	Force delete even if job is still running (default: false)

Returns

Promise<{ success: boolean; }>

Promise with success status

Examples

const result = await adapter.deleteTranscript('job-abc123');
if (result.success) {
  console.log('Job deleted successfully');
}

const result = await adapter.deleteTranscript('job-abc123', true);

See

https://docs.speechmatics.com/

getAxiosConfig()

protected getAxiosConfig(authHeaderName, authHeaderValue?): object

Build axios config for generated API client functions

Parameters

Parameter	Type	Default value	Description
`authHeaderName`	`string`	`"Authorization"`	Header name for API key (e.g., "Authorization", "x-gladia-key")
`authHeaderValue?`	(`apiKey`) => `string`	`undefined`	Optional function to format auth header value (defaults to raw API key)

Returns

object

Axios config object

baseURL

baseURL: string

headers

headers: Record<string, string>

timeout

timeout: number

Inherited from

BaseAdapter.getAxiosConfig

getRegion()

getRegion(): string

Get the current regional endpoint being used

Returns

string

The current base URL

getRegionalBaseUrl()

private getRegionalBaseUrl(region?): string

Build base URL from region

Parameters

Parameter	Type	Description
`region?`	`SpeechmaticsRegionType`	Regional endpoint identifier

Returns

string

Full base URL for the API

getTranscript()

getTranscript(transcriptId): Promise<UnifiedTranscriptResponse<TranscriptionProvider>>

Get transcription result by job ID

Poll this method to check job status and retrieve completed transcription.

Parameters

Parameter	Type	Description
`transcriptId`	`string`	Job ID from Speechmatics

Returns

Promise<UnifiedTranscriptResponse<TranscriptionProvider>>

Transcription response with status and results

Overrides

BaseAdapter.getTranscript

initialize()

initialize(config): void

Initialize the adapter with configuration

Parameters

Parameter	Type
`config`	`SpeechmaticsConfig`

Returns

void

Overrides

BaseAdapter.initialize

normalizeResponse()

private normalizeResponse(response): UnifiedTranscriptResponse

Normalize Speechmatics response to unified format

Parameters

Parameter	Type
`response`	`RetrieveTranscriptResponse`

Returns

UnifiedTranscriptResponse

normalizeStatus()

private normalizeStatus(status): "queued" | "processing" | "completed" | "error"

Normalize Speechmatics status to unified status Uses generated JobDetailsStatus enum values

Parameters

Parameter	Type
`status`	`string`

Returns

"queued" | "processing" | "completed" | "error"

pollForCompletion()

protected pollForCompletion(transcriptId, options?): Promise<UnifiedTranscriptResponse<TranscriptionProvider>>

Generic polling helper for async transcription jobs

Polls getTranscript() until job completes or times out.

Parameters

Parameter	Type	Description
`transcriptId`	`string`	Job/transcript ID to poll
`options?`	{ `intervalMs?`: `number`; `maxAttempts?`: `number`; }	Polling configuration
`options.intervalMs?`	`number`	-
`options.maxAttempts?`	`number`	-

Returns

Promise<UnifiedTranscriptResponse<TranscriptionProvider>>

Final transcription result

Inherited from

BaseAdapter.pollForCompletion

setRegion()

setRegion(region): void

Change the regional endpoint dynamically

Useful for testing different regions or switching based on user location. Preserves all other configuration (apiKey, timeout, headers).

Parameters

Parameter	Type	Description
`region`	`SpeechmaticsRegionType`	New regional endpoint to use

Returns

void

Example

import { SpeechmaticsRegion } from 'voice-router-dev/constants'

// Test EU endpoint
adapter.setRegion(SpeechmaticsRegion.eu1)
await adapter.transcribe(audio)

// Switch to US for comparison
adapter.setRegion(SpeechmaticsRegion.us1)
await adapter.transcribe(audio)

transcribe()

transcribe(audio, options?): Promise<UnifiedTranscriptResponse<TranscriptionProvider>>

Submit audio for transcription

Speechmatics uses async batch processing. Returns a job ID immediately. Poll getTranscript() to retrieve results.

Parameters

Parameter	Type	Description
`audio`	`AudioInput`	Audio input (URL or file)
`options?`	`TranscribeOptions`	Transcription options

Returns

Promise<UnifiedTranscriptResponse<TranscriptionProvider>>

Job submission response with ID for polling

Overrides

BaseAdapter.transcribe

validateConfig()

protected validateConfig(): void

Helper method to validate configuration

Returns

void

Inherited from

BaseAdapter.validateConfig

Constructors

Constructor

new SpeechmaticsAdapter(): SpeechmaticsAdapter

Returns

SpeechmaticsAdapter

Inherited from

BaseAdapter.constructor

Properties

baseUrl

protected baseUrl: string = "https://eu1.asr.api.speechmatics.com/v2"

Base URL for provider API (must be defined by subclass)

Overrides

BaseAdapter.baseUrl

capabilities

readonly capabilities: ProviderCapabilities

Provider capabilities

Overrides

BaseAdapter.capabilities

name

readonly name: "speechmatics"

Provider name

Overrides

BaseAdapter.name

client?

private optional client: AxiosInstance

config?

protected optional config: ProviderConfig

Inherited from

BaseAdapter.config

Functions

createSpeechmaticsAdapter()

createSpeechmaticsAdapter(config): SpeechmaticsAdapter

Factory function to create a Speechmatics adapter

Parameters

Parameter	Type
`config`	`SpeechmaticsConfig`

Returns

SpeechmaticsAdapter

Example

import { createSpeechmaticsAdapter, SpeechmaticsRegion } from 'voice-router-dev'

const adapter = createSpeechmaticsAdapter({
  apiKey: process.env.SPEECHMATICS_API_KEY,
  region: SpeechmaticsRegion.us1
})