voice-router-dev 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -5,6 +5,175 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.2] - 2026-03-15
+
+### Fixed
+
+- Pin Deepgram streaming SDK source to v4.11.3 tag (v5.0.0 Fern rewrite removed `TranscriptionSchema.ts`)
+- Fix ElevenLabs FormData append for object/array fields (`additional_formats`, `webhook_metadata`, `entity_detection`)
+- Add `elevenlabs` to `ProviderWebhookPayloadMap` for typed webhook payloads
+
+### Added
+
+- Documentation generation for ElevenLabs and Soniox providers (typedoc configs + scripts)
+- Speechmatics and ElevenLabs webhook handlers added to webhook documentation
+
+## [0.8.1] - 2026-03-13
+
+#### ElevenLabs ScribeV2 — 9th Provider
+
+New adapter for [ElevenLabs](https://elevenlabs.io) speech-to-text with batch and real-time streaming support:
+
+```typescript
+import { createElevenLabsAdapter, ElevenLabsModel, ElevenLabsRegion } from 'voice-router-dev'
+
+const adapter = createElevenLabsAdapter({
+  apiKey: process.env.ELEVENLABS_API_KEY,
+  model: ElevenLabsModel.scribe_v2,
+  region: ElevenLabsRegion.eu  // global, us, eu, in
+})
+
+// Batch transcription (synchronous)
+const result = await adapter.transcribe({
+  type: 'url',
+  url: 'https://example.com/audio.mp3'
+}, {
+  language: 'en',
+  diarization: true,
+  customVocabulary: ['ElevenLabs', 'ScribeV2'],
+  entityDetection: true,
+  elevenlabs: {
+    tag_audio_events: true,
+    no_verbatim: true,
+    temperature: 0.1
+  }
+})
+
+// Real-time streaming (WebSocket)
+const session = await adapter.transcribeStream({
+  elevenlabsStreaming: {
+    model: 'scribe_v2_realtime',
+    audioFormat: 'pcm_16000',
+    commitStrategy: 'vad',
+    includeTimestamps: true
+  }
+}, {
+  onTranscript: (event) => console.log(event.text),
+  onUtterance: (utterance) => console.log(utterance.text),
+  onError: (error) => console.error(error)
+})
+
+// Retrieve transcript by ID
+const transcript = await adapter.getTranscript('abc123')
+```
+
+**Features:**
+- Batch transcription via URL or file upload (synchronous — result returned directly)
+- Real-time WebSocket streaming with base64-encoded audio
+- Speaker diarization with configurable threshold and speaker count
+- Word-level timestamps with logprob-based confidence
+- Entity detection (PII, PHI, PCI) with character positions
+- Audio event tagging (laughter, footsteps, music)
+- Custom vocabulary (keyterms) boosting (up to 100 terms)
+- 99 supported languages (ISO 639-1/3)
+- 4 regional endpoints (global, US, EU, India)
+- No-verbatim mode (removes filler words and false starts)
+
+**Spec pipeline:**
+- `fix-elevenlabs-spec.js` filters monolithic API spec (210 paths) to 2 STT endpoints, 18 schemas
+- `generate-elevenlabs-languages.js` generates 99 language codes
+- `generate-elevenlabs-models.js` extracts batch models from spec + adds realtime model
+
+**New exports:**
+
+| Export | Description |
+|--------|-------------|
+| `ElevenLabsModel` | Batch models: `scribe_v1`, `scribe_v2` |
+| `ElevenLabsRealtimeModel` | Realtime: `scribe_v2_realtime` |
+| `ElevenLabsLanguage` | 99 language codes with labels |
+| `ElevenLabsRegion` | `global`, `us`, `eu`, `in` |
+| `ElevenLabsAudioFormat` | PCM sample rates + ulaw |
+| `ElevenLabsTypes` | Generated schema types |
+| `ElevenLabsZodSchemas` | Zod schemas for runtime validation |
+
+**Webhook handler:** Auto-detects ElevenLabs payloads via `words` + `language_code` + `logprob` fields. Extracts words, speakers, utterances, entities, and language detection results.
+
+---
+
+## [0.8.2] - 2026-02-28
+
+### Fixed
+
+#### AssemblyAI Webhook Handler — Parse Full Transcript Body
+
+Previously, the AssemblyAI webhook handler only accepted the lightweight notification format (`{ transcript_id, status }`) and returned just the transcript ID — no text, words, or utterances.
+
+Now it also accepts the full transcript response body (`{ id, status, audio_url, text, words, utterances, ... }`) and extracts all available data:
+
+- Text, confidence, duration, language
+- Word-level timestamps (converted from ms to seconds)
+- Speaker-segmented utterances with per-word timing
+- Summary, speaker list, and provider metadata
+
+The handler auto-detects which format was received. Existing notification-format integrations continue to work unchanged.
+
+#### Speechmatics Webhook Handler — Word and Utterance Extraction
+
+The Speechmatics webhook handler now extracts word-level data and builds speaker-grouped utterances from the transcript body:
+
+- Words with `start`/`end` timestamps, `confidence`, and `speaker` ID
+- Utterances grouped by consecutive speaker (same algorithm as the batch adapter)
+
+Previously, only the full text and speaker set were extracted.
+
+#### Speechmatics Adapter — Utterances Now Include Words
+
+The Speechmatics batch adapter's utterance construction now includes word-level data in each utterance, matching the `Utterance.words: Word[]` contract.
+
+#### Speechmatics Text Now Preserves Punctuation
+
+Both the Speechmatics adapter and webhook handler were stripping all punctuation from transcript text by filtering to `type === "word"` and joining with spaces, producing `"Hello world"` instead of `"Hello, world."`.
+
+Now uses a shared `buildTextFromSpeechmaticsResults()` helper that reads the `attaches_to` field on punctuation results:
+- `previous` (`.`, `,`, `?`, `!`) — appended directly to previous word
+- `next` (opening quotes) — prepended to next word
+- `both` (hyphens) — no space on either side
+- `none` or missing — space-separated token
+
+#### Deepgram Webhook — Speaker Deduplication
+
+The Deepgram webhook handler mapped every utterance 1:1 to a "speaker" entry, so 10 utterances from 2 speakers produced 10 entries with duplicate IDs. Now correctly deduplicates via `Set<string>` and returns proper `{ id, label }` objects matching other providers.
+
+Also added `speaker` field to utterance word mappings — the generated Deepgram type has `speaker?: number` on utterance words but it wasn't being mapped through.
+
+#### Soniox Adapter — Utterances No Longer Include Interim Tokens
+
+`normalizeResponse` was building utterances from all tokens (including non-final/interim), while `words` and `text` correctly filtered by `is_final`. This could cause utterance text to contain partial words not present in the words array. Now filters to `is_final` tokens before building utterances.
+
+#### Speechmatics Adapter — Utterance End Time Fix
+
+Utterance end times used `prevResult?.end_time || result.start_time` (falling back to the *next* word's start time), which could produce incorrect values. Now uses `currentWords[last].end` — the actual end time of the last word in the utterance, matching the Speechmatics webhook and Soniox adapter behavior.
+
+#### Deepgram Webhook — Language Field Was Returning Model ID
+
+`data.language` was set to `response.metadata.models[0]`, which is a model UUID — not a language code. Now correctly reads `channel.detected_language` from the first channel (set when `detect_language=true`).
+
+#### Deepgram Webhook — Utterance `id` and `channel` Now Extracted
+
+The Deepgram schema includes `id` and `channel` on utterances but they weren't mapped through. Now populated in the unified response.
+
+#### Consistent Speaker `label` Across All Webhooks
+
+AssemblyAI and Gladia webhook handlers returned Speaker objects without a `label` field (`{ id }`), while Deepgram and Speechmatics included `{ id, label: "Speaker ..." }`. All handlers now consistently include the `label` field.
+
+### Changed
+
+#### `Utterance.words` Is Now Non-Optional
+
+`Utterance.words` changed from `words?: Word[]` to `words: Word[]`. Providers that don't supply word-level data now return an empty array instead of `undefined`. This removes the need for null checks when iterating utterance words.
+
+All adapters and webhook handlers have been updated accordingly (Deepgram, Gladia, OpenAI, Speechmatics, AssemblyAI).
+
 ## [0.8.0] - 2026-01-27
 
 ### Fixed

package/README.md

@@ -8,7 +8,7 @@
 
 ## Why Voice Router?
 
-Switch between speech-to-text providers **without changing your code**. One API for Gladia, AssemblyAI, Deepgram, Azure, OpenAI Whisper, Speechmatics, and Soniox.
+Switch between speech-to-text providers **without changing your code**. One API for Gladia, AssemblyAI, Deepgram, Azure, OpenAI Whisper, Speechmatics, Soniox, and ElevenLabs.
 
 ```typescript
 import { VoiceRouter } from 'voice-router-dev';
@@ -31,7 +31,7 @@ const result = await router.transcribe(audio, {
 - **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, Soniox, OpenAI Realtime)
+- **Real-time Streaming** - WebSocket support (Gladia, AssemblyAI, Deepgram, Soniox, OpenAI Realtime, ElevenLabs)
 - **Advanced Features** - Diarization, sentiment, summarization, chapters, entities
 - **Type-Safe** - Full TypeScript support with OpenAPI-generated types
 - **Typed Extended Data** - Access provider-specific features with full autocomplete
@@ -49,6 +49,7 @@ const result = await router.transcribe(audio, {
 | **OpenAI** | Sync | Realtime | No | gpt-4o, diarization, Realtime API |
 | **Speechmatics** | Async | No | Query params | High accuracy, summarization |
 | **Soniox** | Yes | WebSocket | No | 60+ languages, translation, regions |
+| **ElevenLabs** | Sync | WebSocket | Yes | Entity detection, audio events, 99 languages |
 
 ## Installation
 
@@ -376,6 +377,7 @@ Provider-specific implementations:
 - `OpenAIWhisperAdapter` - OpenAI Whisper + Realtime API
 - `SpeechmaticsAdapter` - Speechmatics transcription
 - `SonioxAdapter` - Soniox transcription (batch + streaming)
+- `ElevenLabsAdapter` - ElevenLabs transcription (batch + streaming)
 
 ## TypeScript Support
 
@@ -787,6 +789,23 @@ router.registerAdapter(new SonioxAdapter());
 
 Get your API key: https://soniox.com
 
+### ElevenLabs
+```typescript
+import { VoiceRouter, ElevenLabsAdapter, ElevenLabsRegion } from 'voice-router-dev';
+
+const router = new VoiceRouter({
+  providers: {
+    elevenlabs: {
+      apiKey: 'YOUR_KEY',
+      region: ElevenLabsRegion.global  // or 'us', 'eu', 'in'
+    }
+  }
+});
+router.registerAdapter(new ElevenLabsAdapter());
+```
+
+Get your API key: https://elevenlabs.io
+
 ## Contributing
 
 Contributions welcome! Please read our [Contributing Guide](CONTRIBUTING.md).