voice-router-dev

v0.1.7

Published

10 hours ago

[DEV] Universal speech-to-text router for Gladia, AssemblyAI, Deepgram, Azure, OpenAI Whisper, and Speechmatics

Downloads

666

Voice Router SDK

Universal speech-to-text router for 6+ transcription providers with a single, unified API.

Why Voice Router?

Switch between speech-to-text providers without changing your code. One API for Gladia, AssemblyAI, Deepgram, Azure, OpenAI Whisper, and Speechmatics.

import { VoiceRouter } from 'voice-router-dev';

const router = new VoiceRouter({
  providers: {
    gladia: { apiKey: process.env.GLADIA_KEY },
    deepgram: { apiKey: process.env.DEEPGRAM_KEY }
  }
});

// Same code works with ANY provider
const result = await router.transcribe(audio, {
  provider: 'gladia'  // Switch to 'deepgram' anytime
});

Features

🔄 Provider-Agnostic - Switch providers with one line
🎯 Unified API - Same interface for all providers
📦 Webhook Normalization - Auto-detect and parse webhooks
🔊 Real-time Streaming - WebSocket support (Gladia, AssemblyAI, Deepgram)
📊 Advanced Features - Diarization, sentiment, summarization
🔒 Type-Safe - Full TypeScript support
⚡ Provider Fallback - Automatic failover strategies
🎨 Zero Config - Works out of the box

Supported Providers

| Provider | Batch | Streaming | Webhooks | Special Features | |----------|-------|-----------|----------|------------------| | Gladia | ✅ | ✅ WebSocket | ✅ | Multi-language, code-switching | | AssemblyAI | ✅ | ✅ Real-time | ✅ HMAC | Auto chapters, content moderation | | Deepgram | ✅ Sync | ✅ WebSocket | ✅ | PII redaction, keyword boosting | | Azure STT | ✅ Async | ❌ | ✅ HMAC | Custom models, language ID | | OpenAI Whisper | ✅ Sync | ❌ | ❌ | gpt-4o, multi-model support | | Speechmatics | ✅ Async | ❌ | ✅ Query params | High accuracy, enhanced mode |

Installation

npm install voice-router-dev
# or
pnpm add voice-router-dev
# or
yarn add voice-router-dev

Quick Start

Basic Transcription

import { VoiceRouter, GladiaAdapter } from 'voice-router-dev';

// Initialize router
const router = new VoiceRouter({
  providers: {
    gladia: { apiKey: 'YOUR_GLADIA_KEY' }
  },
  defaultProvider: 'gladia'
});

// Register adapter
router.registerAdapter(new GladiaAdapter());

// Transcribe from URL
const result = await router.transcribe({
  type: 'url',
  url: 'https://example.com/audio.mp3'
}, {
  language: 'en',
  diarization: true
});

if (result.success) {
  console.log('Transcript:', result.data.text);
  console.log('Speakers:', result.data.speakers);
}

Multi-Provider with Fallback

import {
  VoiceRouter,
  GladiaAdapter,
  AssemblyAIAdapter,
  DeepgramAdapter
} from 'voice-router-dev';

const router = new VoiceRouter({
  providers: {
    gladia: { apiKey: process.env.GLADIA_KEY },
    assemblyai: { apiKey: process.env.ASSEMBLYAI_KEY },
    deepgram: { apiKey: process.env.DEEPGRAM_KEY }
  },
  selectionStrategy: 'round-robin'  // Auto load-balance
});

// Register all providers
router.registerAdapter(new GladiaAdapter());
router.registerAdapter(new AssemblyAIAdapter());
router.registerAdapter(new DeepgramAdapter());

// Automatically rotates between providers
await router.transcribe(audio1);  // Uses Gladia
await router.transcribe(audio2);  // Uses AssemblyAI
await router.transcribe(audio3);  // Uses Deepgram

Real-time Streaming

import { VoiceRouter, DeepgramAdapter } from 'voice-router-dev';

const router = new VoiceRouter({
  providers: {
    deepgram: { apiKey: process.env.DEEPGRAM_KEY }
  }
});

router.registerAdapter(new DeepgramAdapter());

// Start streaming session
const session = await router.transcribeStream({
  provider: 'deepgram',
  encoding: 'linear16',
  sampleRate: 16000,
  language: 'en',
  interimResults: true
}, {
  onTranscript: (event) => {
    if (event.isFinal) {
      console.log('Final:', event.text);
    } else {
      console.log('Interim:', event.text);
    }
  },
  onError: (error) => console.error(error)
});

// Send audio chunks
const audioStream = getMicrophoneStream();
for await (const chunk of audioStream) {
  await session.sendAudio({ data: chunk });
}

await session.close();

Webhook Normalization

import express from 'express';
import { WebhookRouter } from 'voice-router-dev';

const app = express();
const webhookRouter = new WebhookRouter();

// Single endpoint handles ALL providers
app.post('/webhooks/transcription', express.json(), (req, res) => {
  // Auto-detect provider from payload
  const result = webhookRouter.route(req.body, {
    queryParams: req.query,
    userAgent: req.headers['user-agent'],
    verification: {
      signature: req.headers['x-signature'],
      secret: process.env.WEBHOOK_SECRET
    }
  });

  if (!result.success) {
    return res.status(400).json({ error: result.error });
  }

  // Unified format across all providers
  console.log('Provider:', result.provider);  // 'gladia' | 'assemblyai' | etc
  console.log('Event:', result.event?.eventType);  // 'transcription.completed'
  console.log('ID:', result.event?.data?.id);
  console.log('Text:', result.event?.data?.text);

  res.json({ received: true });
});

Advanced Usage

Provider-Specific Features

// Gladia - Multi-language detection
const result = await router.transcribe(audio, {
  provider: 'gladia',
  languageDetection: true,
  summarization: true,
  sentimentAnalysis: true
});

// AssemblyAI - Content moderation
const result = await router.transcribe(audio, {
  provider: 'assemblyai',
  entityDetection: true,
  metadata: {
    content_safety: true,
    auto_chapters: true
  }
});

// Deepgram - PII redaction
const result = await router.transcribe(audio, {
  provider: 'deepgram',
  piiRedaction: true,
  customVocabulary: ['technical', 'terms']
});

// OpenAI Whisper - Model selection
const result = await router.transcribe(audio, {
  provider: 'openai-whisper',
  metadata: {
    model: 'gpt-4o-transcribe',  // or 'whisper-1'
    temperature: 0.2
  }
});

// Speechmatics - Enhanced accuracy
const result = await router.transcribe(audio, {
  provider: 'speechmatics',
  metadata: {
    operating_point: 'enhanced',  // Higher accuracy
    enable_sentiment_analysis: true
  }
});

Error Handling

const result = await router.transcribe(audio, {
  provider: 'gladia',
  language: 'en'
});

if (!result.success) {
  console.error('Provider:', result.provider);
  console.error('Error:', result.error);
  console.error('Details:', result.data);

  // Implement fallback strategy
  const fallbackResult = await router.transcribe(audio, {
    provider: 'assemblyai'  // Try different provider
  });
}

Custom Provider Selection

// Explicit provider selection
const router = new VoiceRouter({
  providers: {
    gladia: { apiKey: '...' },
    deepgram: { apiKey: '...' }
  },
  selectionStrategy: 'explicit'  // Must specify provider
});

// Round-robin load balancing
const router = new VoiceRouter({
  providers: { /* ... */ },
  selectionStrategy: 'round-robin'
});

// Default fallback
const router = new VoiceRouter({
  providers: { /* ... */ },
  defaultProvider: 'gladia',
  selectionStrategy: 'default'
});

API Reference

VoiceRouter

Main class for provider-agnostic transcription.

Constructor:

new VoiceRouter(config: VoiceRouterConfig)

Methods:

registerAdapter(adapter: TranscriptionAdapter) - Register a provider adapter
transcribe(audio: AudioInput, options?: TranscribeOptions) - Transcribe audio
transcribeStream(options: StreamingOptions, callbacks: StreamingCallbacks) - Stream audio
getTranscript(id: string, provider: string) - Get transcript by ID
getProviderCapabilities(provider: string) - Get provider features

WebhookRouter

Automatic webhook detection and normalization.

Methods:

route(payload: unknown, options?: WebhookRouterOptions) - Parse webhook
detectProvider(payload: unknown) - Detect provider from payload
validate(payload: unknown) - Validate webhook structure

Adapters

Provider-specific implementations:

GladiaAdapter - Gladia transcription
AssemblyAIAdapter - AssemblyAI transcription
DeepgramAdapter - Deepgram transcription
AzureSTTAdapter - Azure Speech-to-Text
OpenAIWhisperAdapter - OpenAI Whisper
SpeechmaticsAdapter - Speechmatics transcription

TypeScript Support

Full type definitions included:

import type {
  VoiceRouter,
  VoiceRouterConfig,
  AudioInput,
  TranscribeOptions,
  UnifiedTranscriptResponse,
  StreamingSession,
  StreamingOptions,
  UnifiedWebhookEvent,
  TranscriptionProvider
} from 'voice-router-dev';

Requirements

Node.js: 20.0.0 or higher
TypeScript: 5.0+ (optional)
Package Managers: npm, pnpm, or yarn

Documentation

Full API Docs: Generated TypeDoc
Provider Integration Guide: See PROVIDER_INTEGRATION_PLAN.md
Examples: See examples/ directory

Provider Setup Guides

Gladia

import { VoiceRouter, GladiaAdapter } from 'voice-router-dev';

const router = new VoiceRouter({
  providers: { gladia: { apiKey: 'YOUR_KEY' } }
});
router.registerAdapter(new GladiaAdapter());

Get your API key: https://gladia.io

AssemblyAI

import { VoiceRouter, AssemblyAIAdapter } from 'voice-router-dev';

const router = new VoiceRouter({
  providers: { assemblyai: { apiKey: 'YOUR_KEY' } }
});
router.registerAdapter(new AssemblyAIAdapter());

Get your API key: https://assemblyai.com

Deepgram

import { VoiceRouter, DeepgramAdapter } from 'voice-router-dev';

const router = new VoiceRouter({
  providers: { deepgram: { apiKey: 'YOUR_KEY' } }
});
router.registerAdapter(new DeepgramAdapter());

Get your API key: https://deepgram.com

Azure Speech-to-Text

import { VoiceRouter, AzureSTTAdapter } from 'voice-router-dev';

const router = new VoiceRouter({
  providers: {
    'azure-stt': {
      apiKey: 'YOUR_KEY',
      region: 'eastus'  // Required
    }
  }
});
router.registerAdapter(new AzureSTTAdapter());

Get your credentials: https://azure.microsoft.com/en-us/services/cognitive-services/speech-to-text/

OpenAI Whisper

import { VoiceRouter, OpenAIWhisperAdapter } from 'voice-router-dev';

const router = new VoiceRouter({
  providers: { 'openai-whisper': { apiKey: 'YOUR_KEY' } }
});
router.registerAdapter(new OpenAIWhisperAdapter());

Get your API key: https://platform.openai.com

Speechmatics

import { VoiceRouter, SpeechmaticsAdapter } from 'voice-router-dev';

const router = new VoiceRouter({
  providers: { speechmatics: { apiKey: 'YOUR_KEY' } }
});
router.registerAdapter(new SpeechmaticsAdapter());

Get your API key: https://speechmatics.com

Contributing

Contributions welcome! Please read our Contributing Guide.

License

Support

Issues: GitHub Issues
Repository: GitHub

Note: This is a development version (voice-router-dev). The stable release will be published as voice-router.