deepgram-python-speech-to-text
/deepgram-python-speech-to-text
Use when writing or reviewing Python code in this repo that calls Deepgram Speech-to-Text v1 (`/v1/listen`) for prerecorded or live audio transcription. Covers `client.listen.v1.media.transcribe_url` / `transcribe_file` (REST) and `client.listen.v1.connect` (WebSocket). Use this skill for basic ASR; use `deepgram-python-audio-intelligence` for summarize/sentiment/topics/diarize overlays, `deepgram-python-conversational-stt` for turn-taking v2/Flux, and `deepgram-python-voice-agent` for full-duplex assistants. Triggers include "transcribe", "live transcription", "speech to text", "STT", "listen
- Author
- deepgram ↗
- Repository
- deepgram-python-sdk ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 10
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when writing or reviewing Python code in this repo that calls Deepgram Speech-to-Text v1 (`/v1/listen`) for prerecorded or live audio transcription. Covers `client.listen.v1.media.transcribe_url` / `transcribe_file` (REST) and `client.listen.v1.connect` (WebSocket). Use this skill for basic ASR; use `deepgram-python-audio-intelligence` for summarize/sentiment/topics/diarize overlays, `deepgram-python-conversational-stt` for turn-taking v2/Flux, and `deepgram-python-voice-agent` for full-duplex assistants. Triggers include "transcribe", "live transcription", "speech to text", "STT", "listen
Triggers from the description
Original author description
Use when writing or reviewing Python code in this repo that calls Deepgram Speech-to-Text v1 (`/v1/listen`) for prerecorded or live audio transcription. Covers `client.listen.v1.media.transcribe_url` / `transcribe_file` (REST) and `client.listen.v1.connect` (WebSocket). Use this skill for basic ASR; use `deepgram-python-audio-intelligence` for summarize/sentiment/topics/diarize overlays, `deepgram-python-conversational-stt` for turn-taking v2/Flux, and `deepgram-python-voice-agent` for full-duplex assistants. Triggers include "transcribe", "live transcription", "speech to text", "STT", "listen
How it works
- When to use this product
- Authentication
- Quick start — REST (prerecorded URL)
- Quick start — REST (prerecorded file)
- Quick start — WebSocket (live streaming with interim results)
- Async equivalents
- Async / deferred result patterns
- Key parameters
- API reference (layered)
- Gotchas
SKILL.md preview
---
name: deepgram-python-speech-to-text
description: Use when writing or reviewing Python code in this repo that calls Deepgram Speech-to-Text v1 (`/v1/listen`) for prerecorded or live audio transcription. Covers `client.listen.v1.media.transcribe_url` / `transcribe_file` (REST) and `client.listen.v1.connect` (WebSocket). Use this skill for basic ASR; use `deepgram-python-audio-intelligence` for summarize/sentiment/topics/diarize overlays, `deepgram-python-conversational-stt` for turn-taking v2/Flux, and `deepgram-python-voice-agent` for full-duplex assistants. Triggers include "transcribe", "live transcription", "speech to text", "STT", "listen endpoint", "nova-3", "listen.v1".
---
# Using Deepgram Speech-to-Text (Python SDK)
Basic transcription (ASR) for prerecorded audio (REST) or live audio (WebSocket) via `/v1/listen`.
## When to use this product
- **REST (`transcribe_url` / `transcribe_file`)** — one-shot transcription of a complete file or URL. Use for batch jobs, captioning pipelines, offline analysis.
- **WebSocket (`listen.v1.connect`)** — continuous streaming transcription. Use for live captions, real-time microphone input, phone audio.
**Use a different skill when:**
- You want summaries, sentiment, topics, intents, diarization, or redaction on the audio → `deepgram-python-audio-intelligence` (same endpoint, different params).
- You need turn-taking / end-of-turn events → `deepgram-python-conversational-stt` (v2 / Flux).
- You need a full-duplex interactive assistant (STT + LLM + TTS + function calls) → `deepgram-python-voice-agent`.
## Authentication
```python
import os
from dotenv import load_dotenv
load_dotenv()
from deepgram import DeepgramClient
client = DeepgramClient() # reads DEEPGRAM_API_KEY from env
# or: DeepgramClient(api_key=os.environ["DEEPGRAM_API_KEY"])
```
Header sent on every request: `Authorization: Token <api_key>` (NOT `Bearer`).
## Quick start — REST (prerecorded URL)
```python
response = client.listen.v1.media.transcribe_url(
url="https://dpgr.am/spacewalk.wav",
model="nova-3",
smart_format=True,
punctuate=True,
)
transcript = response.results.channels[0].alternatives[0].transcript
```
## Quick start — REST (prerecorded file)
```python
with open("audio.wav", "rb") as f:
audio_bytes = f.read()
response = client.listen.v1.media.transcribe_file(
request=audio_bytes,
model="nova-3",
)
```
`request=` accepts raw `bytes` or an iterator of `bytes` (stream large files chunk-by-chunk). Do NOT pass a file handle.
## Quick start — WebSocket (live streaming with interim results)
Live transcription emits **interim** (partial) and **final** results. Pass `interim_results=True` and switch on `is_final` to display partial text in real time, then overwrite it with the final transcript when the speaker pauses.
```python
import threading
from deepgram.core.events import EventType
from deepgram.listen.v1.types import (
ListenV1Results, ListenV1Metadata,
ListenV1SpeechStarted, ListenV1UtteranceEnd,
)
with client.listen.v1.connect(
model="nova-3",
interim_results=True, # ← emit partial results while user is still speaking
utterance_end_ms=1000, # silence (ms) before server emits UtteranceEnd
vad_events=True, # SpeechStarted events
smart_format=True,
) as conn:
# Mutable container so the on_message closure can update state without `global`
state = {"last_interim_len": 0}
def on_message(m):
if isinstance(m, ListenV1Results) and m.channel and m.channel.alternatives:
transcript = m.channel.alternatives[0].transcript
if not transcript:
return
if m.is_final:
# Final segment: overwrite the running interim line, newline if utterance ended
pad = " " * max(0, state["last_interim_len"] - len(transcript))
end = "\n" if m.speech_final else ""
print(f"\r{transcript}{pad}", end=end, flush=True)
state["last_interim_len"] = 0
else:
# Interim: keep overwriting the same console line as the user speaks
print(f"\r{transcript}", end="", flush=True)
state["last_interim_len"] = len(transcript)
elif isinstance(m, ListenV1UtteranceEnd):
print() # newline; UtteranceEnd fires after final results when audio goes silent
elif isinstance(m, ListenV1SpeechStarted):
pass # optional: reset UI when a new utterance begins
conn.on(EventType.OPEN, lambda _: print("connected"))
conn.on(EventType.MESSAGE, on_message)
conn.on(EventType.CLOSE, lambda _: print("\nclosed"))
conn.on(EventType.ERROR, lambda e: print(f"\nerr: {e}"))
# Start receive loop in background so we can send concurrently
threading.Thread(target=conn.start_listening, daemon=True).start()
for chunk in audio_chunks: # raw PCM bytes at declared encoding/sample_rate
conn.send_media(chunk)
conn.send_finalize() # flush final partial before closing
```
### Interim vs. final flag semantics
- **`is_final = False`** — interim hypothesis. Will be revised. Display in a non-committal style (lighter colour, italic) and overwrite when the next message arrives.
- **`is_final = True`, `speech_final = False`** — confirmed segment, but the speaker is still talking. Append to the transcript; another final will follow.
- **`is_final = True`, `speech_final = True`** — confirmed segment AND the utterance ended (silence detected). Commit the line and start a new one.
- **`from_finalize = True`** — this final was triggered by your explicit `send_finalize()` call (vs natural endpointing). Useful to distinguish "I asked for a flush" from "the speaker paused".
Send `send_finalize()` to force the server to emit final results immediately (e.g. user clicks "stop"). Send `send_close_stream()` after `send_finalize` to terminate cleanly.
WSS message types live under `deepgram.listen.v1.types`.
## Async equivalents
```python
from deepgram import AsyncDeepgramClient
client = AsyncDeepgramClient()
response = await client.listen.v1.media.transcribe_url(url=..., model="nova-3")
async with client.listen.v1.connect(model="nova-3") as conn:
# same .on(...) handlers, then:
await conn.start_listening()
```
## Async / deferred result patterns
There are **two distinct** notions of "async" — don't confuse them.
### 1. Python `async/await` (sync-style, immediate result)
`AsyncDeepgramClient` returns `Awaitable[<full response>]`. The result is delivered when you `await`, not later. Use this when integrating with FastAPI, aiohttp, or any asyncio app.
```python
import asyncio
from deepgram import AsyncDeepgramClient
client = AsyncDeepgramClient()
async def transcribe(url: str) -> str:
response = await client.listen.v1.media.transcribe_url(
url=url,
model="nova-3",
smart_format=True,
)
# `response` is the FULL transcription — no polling, no callback, just await.
return response.results.channels[0].alternatives[0].transcript
text = asyncio.run(transcribe("https://dpgr.am/spacewalk.wav"))
```
### 2. Deferred via callback URL (webhook, results posted later)
Pass `callback="https://your.app/webhook"` and the request **returns immediately** with a `request_id`. Deepgram processes the audio in the background and POSTs the final result to your webhook URL. There is **no polling endpoint** — your server must be reachable to receive the result.
```python
response = client.listen.v1.media.transcribe_url(
url="https://dpgr.am/spacewalk.wav",
callback="https://your.app/deepgram-webhook",
callback_method="POST", # or "PUT"
model="nova-3",
smart_format=True,
)
print(f"Accepted; tracking id: {response.request_id}")
# response is a "listen accepted" — NOT the transcript. Wait for your webhook.
```
The webhook receives the same JSON body you would have received from a synchronous `transcribe_url` call. Use this for very long files or when you don't want the request hanging open.
| Pattern | Returns | When to use |
|---|---|---|
| `client.listen.v1.media.transcribe_url(...)` | full transcription synchronously | files up to ~10 min; HTTP timeout-bound |
| `await AsyncDeepgramClient().listen.v1.media.transcribe_url(...)` | full transcription, non-blocking | inside asyncio apps |
| `transcribe_url(..., callback="https://...")` | `{request_id}` immediately, transcription POSTs to webhook later | very long files; no long-lived HTTP connection |
| `client.listen.v1.connect(...)` (WebSocket) | streaming events as audio is sent | live audio (mic, telephony) |
See `examples/12-transcription-prerecorded-callback.py` for a working callback example.
## Key parameters
`model`, `language`, `encoding`, `sample_rate`, `channels`, `multichannel`, `punctuate`, `smart_format`, `diarize`, `endpointing`, `interim_results`, `utterance_end_ms`, `vad_events`, `keywords`, `search`, `redact`, `numerals`, `paragraphs`, `utterances`.
## API reference (layered)
1. **In-repo Fern-generated reference**: `reference.md` — sections "Listen V1 Media" (REST) and "Listen V1 Connect" (WSS).
2. **Canonical OpenAPI (REST)**: https://developers.deepgram.com/openapi.yaml
3. **Canonical AsyncAPI (WSS)**: https://developers.deepgram.com/asyncapi.yaml
4. **Context7** — natural-language queries over the full Deepgram docs corpus. Library ID: `/llmstxt/developers_deepgram_llms_txt`.
5. **Product docs**:
- https://developers.deepgram.com/reference/speech-to-text/listen-pre-recorded
- https://developers.deepgram.com/reference/speech-to-text/listen-streaming
## Gotchas
1. **Use the right auth scheme for the credential type.** API keys use `Authorization: Token <api_key>`. Temporary / access tokens (from `client.auth.v1.tokens.grant()` or an equivalent server) use `Authorization: Bearer <access_token>` — the custom `DeepgramClient` installs a Bearer override when you pass `access_token=...` (see `src/deepgram/client.py`). Sending `Bearer <api_key>` with a long-lived API key is what fails.
2. **Encoding must match the audio.** Declaring `encoding="linear16"` but sending Opus → garbage output or 400.
3. **Close streams cleanly.** Call `send_finalize()` before exiting the WSS context — otherwise the last partial is dropped.
4. **Keepalive on long WSS sessions.** If idle > ~10s, the server closes. Send `KeepAlive` messages or audio chunks.
5. **Intelligence features are REST-only.** `summarize`, `topics`, `intents`, `sentiment`, `detect_language` do NOT work over WSS — see `deepgram-python-audio-intelligence`.
6. **`transcribe_file(request=...)` takes bytes or an iterator**, not a file handle.
7. **`nova-3` is the current flagship STT model.** Check `client.manage.v1.models.list()` for the live set.
8. **Sync `connection.start_listening()` blocks.** Run it in a thread (sync) or as a task (async) so you can send audio concurrently.
## Example files in this repo
- `examples/10-transcription-prerecorded-url.py`
- `examples/11-transcription-prerecorded-file.py`
- `examples/12-transcription-prerecorded-callback.py`
- `examples/13-transcription-live-websocket.py`
- `tests/wire/test_listen_v1_media.py` — wire-level fixtures
- `tests/manual/listen/v1/connect/main.py` — live WSS connection 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`).
Versions
The database has no other skills named deepgram-python-speech-to-text.
Database snapshot: 13.11.2026 · package version 9b10eb136d58 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 1 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100deepgram-js-speech-to-text
Use when writing or reviewing JavaScript/TypeScript in this repo that calls Deepgram Speech-to-Text v1 (`/v1/listen`) for prerecorded or live audio transcription. Covers `client.listen.v1.media.transcribeUrl` / `transcribeFile` (REST) plus `client.listen.v1.createConnection()` /… - 100deepgram-java-speech-to-text
Use when writing or reviewing Java code in this repo that calls Deepgram Speech-to-Text v1 (`/v1/listen`) for prerecorded or live transcription. Covers `client.listen().v1().media().transcribeUrl` / `transcribeFile` (REST) and `client.listen().v1().v1WebSocket()` (WebSocket).… - 100deepgram-python-audio-intelligence
Use when writing or reviewing Python code in this repo that calls Deepgram audio analytics overlays on `/v1/listen` - summarize, topics, intents, sentiment, diarize, redact, detect_language, entity detection. Same endpoint as plain STT but with analytics params. Covers both REST… - 100deepgram-go-speech-to-text
Use when writing or reviewing Go code in this repo that transcribes prerecorded audio with Listen v1 REST or streams live audio with Listen v1 WebSockets. Route text generation to deepgram-go-text-to-speech, text analysis to deepgram-go-text-intelligence, audio analytics… - 100deepgram-python-conversational-stt
Use when writing or reviewing Python code in this repo that calls Deepgram Conversational STT v2 / Flux (`/v2/listen`) for turn-aware streaming transcription. Covers `client.listen.v2.connect(...)`, Flux models, end-of-turn detection. Use `deepgram-python-speech-to-text` for… - 100deepgram-js-audio-intelligence
Use when writing or reviewing JavaScript/TypeScript in this repo that calls Deepgram audio analytics overlays on `/v1/listen` - summarize, topics, intents, sentiment, diarize, redact, detect_language, and entity detection. Same endpoint as plain STT, different params. Covers…