[Example] 350 — Asterisk / FreeSWITCH PBX to Deepgram Streaming STT (Python)

[github-actions]

New example: Asterisk / FreeSWITCH PBX to Deepgram Streaming STT

Integration: Asterisk / FreeSWITCH | Language: Python | Products: STT

What this shows

A Python WebSocket bridge server that receives real-time phone call audio from Asterisk (via AudioSocket) or FreeSWITCH (via mod_audio_stream) and forwards it to Deepgram's live streaming STT API for real-time transcription. Includes proper AudioSocket TLV frame parsing, telephony-optimised Deepgram settings (nova-3-phonecall, 8/16 kHz), and example dialplan configurations for both PBX platforms.

Required secrets

None — only DEEPGRAM_API_KEY required

Closes #67

---

Built by Engineer on 2026-04-02

[github-actions]

Code Review

Overall: APPROVED

Tests ran ✅

============================= test session starts ==============================
platform linux -- Python 3.11.15, pytest-9.0.2, pluggy-1.6.0
collected 5 items

tests/test_example.py::test_parse_audiosocket_uuid_frame PASSED          [ 20%]
tests/test_example.py::test_parse_audiosocket_audio_frame PASSED         [ 40%]
tests/test_example.py::test_parse_audiosocket_hangup_frame PASSED        [ 60%]
tests/test_example.py::test_parse_audiosocket_malformed PASSED           [ 80%]
tests/test_example.py::test_deepgram_prerecorded_stt PASSED              [100%]

======================== 5 passed, 2 warnings in 2.10s =========================

Transcript preview: 'Yeah. As as much as, it's worth celebrating, the first, spacewalk, with an all f...'

Integration genuineness

Pass — This is a WebSocket bridge that receives audio from Asterisk (AudioSocket TLV protocol) and FreeSWITCH (mod_audio_stream raw PCM) and forwards it to Deepgram Live STT. The bridge implements real AudioSocket TLV frame parsing (type/length/value), real FreeSWITCH raw PCM handling, and makes real Deepgram API calls via the official SDK. No Asterisk/FreeSWITCH SDK is needed since the bridge acts as a WebSocket server that receives PBX connections. The test verifies the Deepgram API key works with a real pre-recorded transcription call.

Code quality

• ✅ Official Deepgram SDK used (deepgram-sdk==6.1.1 — current required version)
• ✅ tag="deepgram-examples" present on all Deepgram API calls (bridge.py:104, test_example.py:84)
• ✅ No hardcoded credentials — uses os.environ["DEEPGRAM_API_KEY"]
• ✅ Error handling: WebSocket ConnectionClosed caught, Deepgram error events registered, finally blocks for cleanup with send_close_stream()
• ✅ Credential check runs FIRST in tests (lines 7–20, before any SDK imports)
• ✅ bridge.py checks DEEPGRAM_API_KEY at startup before opening connections
• ✅ .env.example present and complete

Documentation

• ✅ README explains what you'll build (WebSocket bridge between PBX and Deepgram)
• ✅ Environment variables table with link to Deepgram console
• ✅ Install and run instructions with both Asterisk and FreeSWITCH dialplan configs
• ✅ Architecture diagram showing the full audio flow
• ✅ Key parameters table explaining Deepgram settings

---

✓ All checks pass. Ready for merge.

---

Review by Lead on 2026-04-02