deepgram-python-text-to-speech

# Using Deepgram Text-to-Speech (Python SDK) Convert text to audio: one-shot REST download or low-latency streaming synthesis via `/v1/speak`. ## When to use this product - **REST (`speak.v1.audio.generate`)** — one-shot synthesis, returns audio bytes. Use for rendered files, pre-generated prompts, anything where you have the full text upfront. - **WebSocket (`speak.v1.connect`)** — incremental text input, streaming audio output. Use for low-latency playback while an LLM is still producing tokens. **Use a different skill when:** - You need the agent to also listen and converse (full-duplex) → `deepgram-python-voice-agent`. ## Authentication ```python from dotenv import load_dotenv load_dotenv() from deepgram import DeepgramClient client = DeepgramClient() # reads DEEPGRAM_API_KEY ``` Header: `Authorization: Token <api_key>` (NOT `Bearer`). ## Quick start — REST (one-shot) ```python audio_iter = client.speak.v1.audio.generate( text="Hello, this is a text to speech example.", model="aura-2-asteria-en", encoding="linear16", sample_rate=24000, ) with open("output.raw", "wb") as f: for chunk in audio_iter: f.write(chunk) ``` Returns an iterator of `bytes` (streaming audio response). The response body is `audio/*`, NOT JSON. Useful response headers: `dg-model-name`, `dg-char-count`, `dg-request-id`. ## Quick start — WebSocket (streaming) ```python from deepgram.core.events import EventType from deepgram.speak.v1.types import SpeakV1Text with client.speak.v1.connect( model="aura-2-asteria-en", encoding="linear16", sample_rate=24000, ) as conn: def on_message(m): if isinstance(m, bytes): # audio chunk — write to file or audio output ... else: print(f"event: {getattr(m, 'type', 'Unknown')}") conn.on(EventType.OPEN, lambda _: print("open")) conn.on(EventType.MESSAGE, on_message) conn.on(EventType.CLOSE, lambda _: print("close")) conn.on(EventType.ERROR, lambda e: print(f"err: {e}")) conn.send_text(SpeakV1Text(text="Hello, this is streaming TTS.")) conn.send_flush() conn.send_close() conn.start_listening() # blocks until server closes ``` In **sync** mode, `start_listening()` blocks — send all text + flush + close BEFORE calling it, OR run it in a thread. In **async** mode, run `start_listening()` as a task and send concurrently. ## TextBuilder helper (Flux batch controls) `deepgram.helpers.TextBuilder` is a hand-maintained helper (NOT Fern-generated) for English Flux batch requests. Pronunciation controls apply to Flux batch, Flux WebSocket, and Aura-2 `/v1/speak`; pauses are Flux batch-only and a Flux WebSocket rejects them with `DATA-0002`. ```python from deepgram.helpers import TextBuilder final_text = ( TextBuilder() .text("Hello,") .text(" this is built incrementally.") .pronunciation("Deepgram", "ˈdiːpɡɹæm") .build() ) ``` The fluent API is `.text(...)` (append raw text), `.pronunciation(word, ipa)` (insert a `\{\"word\": \"...\", \"pronounce\": \"...\"\}` marker), `.pause(duration_ms)` (insert a `\{pause:<N>ms\}` marker), and `.build()` (return the batch request text). Pauses must be 500-3000 ms in 100 ms increments, with at most eight per request. Pronunciation and pause cannot be combined in one request; Flux rejects the combination with `CONTROL_COMBINATION_INVALID`. There is no `.add(...)` method. Use the output with `client.speak.v2.audio.generate(model="flux-alexis-en", text=final_text)`. See `docs/FluxTtsControls.md`, `examples/22-text-builder-demo.py`, and `examples/23-text-builder-helper.py`. ## Async equivalents ```python from deepgram import AsyncDeepgramClient client = AsyncDeepgramClient() # REST audio_iter = await client.speak.v1.audio.generate(text=..., model="aura-2-asteria-en") async for chunk in audio_iter: ... # WSS async with client.speak.v1.connect(model="aura-2-asteria-en", ...) as conn: listen_task = asyncio.create_task(conn.start_listening()) await conn.send_text(SpeakV1Text(text="...")) await conn.send_flush() await conn.send_close() await listen_task ``` ## Key parameters REST & WSS: `model` (e.g. `aura-2-asteria-en`), `encoding` (`linear16`, `mulaw`, `alaw`, `opus`, `flac`, `mp3`, `aac`), `sample_rate`, `bit_rate`, `container`, `callback` (REST async), `tag`, `mip_opt_out`. WSS client messages: `SpeakV1Text`, `Flush`, `Clear`, `Close`. ## API reference (layered) 1. **In-repo reference**: `reference.md` — sections "Speak V1 Audio" (REST) and "Speak V1 Connect" (WSS). 2. **OpenAPI (REST)**: https://developers.deepgram.com/openapi.yaml 3. **AsyncAPI (WSS)**: https://developers.deepgram.com/asyncapi.yaml 4. **Context7**: library ID `/llmstxt/developers_deepgram_llms_txt`. 5. **Product docs**: - https://developers.deepgram.com/reference/text-to-speech/speak-request - https://developers.deepgram.com/reference/text-to-speech/speak-streaming - https://developers.deepgram.com/docs/tts-models ## Gotchas 1. **`Token` auth, not `Bearer`.** 2. **REST response is audio bytes, not JSON.** Iterate the response; don't `.json()` it. 3. **Flush before close (WSS).** `send_close()` without `send_flush()` may drop trailing audio. 4. **Sync `start_listening()` blocks.** Queue all messages first, or use async. 5. **`SpeakV1Text` is required** for WSS text input — don't send raw strings. 6. **`encoding`/`sample_rate`/`container` must match your playback path.** Mismatches cause silent failure or distortion. 7. **`TextBuilder` helpers are hand-maintained** (listed in `.fernignore` as permanently frozen). Don't move them under `src/deepgram/` auto-generated paths. ## Example files in this repo - `examples/20-text-to-speech-single.py` — REST one-shot - `examples/21-text-to-speech-streaming.py` — WSS streaming - `examples/22-text-builder-demo.py` — TextBuilder (no API key) - `examples/23-text-builder-helper.py` — TextBuilder + REST - `examples/24-text-builder-streaming.py` — plain-text WSS; Flux pause controls are batch-only - `tests/wire/test_speak_v1_audio.py` — REST wire test - `tests/manual/speak/v1/connect/main.py` — live WSS test ## Central product skills For cross-language Deepgram product knowledge — the consolidated API reference, documentation finder, focused runnable recipes, third-party integration examples, and MCP setup — install the central skills: ```bash npx skills add deepgram/skills ``` This SDK ships language-idiomatic code skills; `deepgram/skills` ships cross-language product knowledge (see `api`, `docs`, `recipes`, `examples`, `starters`, `setup-mcp`).