deepgram

1# Deepgram
2 
3## Purpose
4Transcribe prerecorded audio files to text (with optional diarization, summaries, topics, sentiment) and synthesize speech with Deepgram's Aura voices. Reach for this when the user has an audio file to transcribe or wants spoken audio generated from text.
5 
6## Tooling
7All commands go through `bin/deepgram.py`. Auth uses exactly `Authorization: Token <api_key>` (not Bearer); the CLI wires it through the credential surrogate.
8 
9```bash
10bin/deepgram.py auth
11# {"ok": true, "projects": 2} on success
12 
13bin/deepgram.py projects
14# list Deepgram projects (id, name)
15 
16bin/deepgram.py transcribe --file meeting.wav
17# upload a local audio file, print the transcript JSON
18 
19bin/deepgram.py transcribe --file call.mp3 --model nova-3 --diarize --summarize --topics --sentiment
20# transcript with speaker labels plus summary, topics and sentiment
21 
22bin/deepgram.py tts --text "Thanks for listening." --out thanks.mp3
23# synthesize with an Aura voice to a local MP3 file; prints the saved path
24```
25 
26Notes:
27- `transcribe` reads a local audio file, posts the bytes to `POST /v1/listen`, and prints the full transcript JSON. Content type is guessed from the file extension (wav, mp3, m4a, flac, ogg supported).
28- `tts` posts `{"text": "..."}` to `POST /v1/speak?model=<model>&encoding=mp3` (default model `aura-2-thalia-en`, 2,000-char limit) and saves the audio to `--out` (default `deepgram-output.mp3`).
29- Live WebSocket STT (`/v1/listen` streaming) is real-time and outside CLI scope.
30 
31## Auth
32…