[Example] 300 — Spring Boot Real-Time Transcription with Deepgram Java SDK

[github-actions]

New example: Spring Boot Real-Time Transcription with Deepgram Java SDK

Integration: Spring Boot | Language: Java | Products: STT

What this shows

A Spring Boot 3 application with a WebSocket endpoint that accepts browser audio, proxies it to Deepgram's live STT WebSocket (Nova-3) via the deepgram-java-sdk, and streams transcription results back in real time. Includes a built-in HTML/JS test page for browser-based microphone capture and a health check endpoint via Spring Boot Actuator.

Required secrets

None — only DEEPGRAM_API_KEY required

Closes #35

---

Built by Engineer on 2026-04-02

[github-actions]

Code Review

Overall: APPROVED

Tests ran ✅

--- Compilation OK ---
PASS: Received transcript — "and didn't get the same opportunities that we have today"

Test downloads spacewalk.wav, streams it to Deepgram via the Java SDK's live WebSocket, and verifies a non-empty final transcript is returned. Credential check runs first (exit 2 on missing vars). Transcript assertion checks presence only — no specific word list — which is correct for non-deterministic STT.

Integration genuineness

Pass.

• Spring Boot SDK is imported and used: spring-boot-starter-web, spring-boot-starter-websocket, spring-boot-starter-actuator
• Real Spring Boot WebSocket handler (BinaryWebSocketHandler) opens a live Deepgram connection per browser session
• .env.example lists DEEPGRAM_API_KEY (Spring Boot is a framework, not a third-party API, so no additional platform credentials are needed)
• Test makes a real Deepgram API call — not mocked, not hardcoded

Code quality

• ✅ Official deepgram-java-sdk:0.2.0 used (matches required Java SDK version v0.2.0)
• ✅ tag("deepgram-examples") present on every Deepgram API call (handler line 79, test line 75)
• ✅ No hardcoded credentials — System.getenv("DEEPGRAM_API_KEY") throughout
• ✅ Error handling: null/blank API key check before SDK init, null-safe transcript parsing, onError handler, try-catch around forwarding
• ✅ Credential check runs FIRST before any SDK usage (handler line 36-41, test lines 24-39)
• ✅ Transcript assertion uses boolean presence check — no flaky word-list assertions
• ✅ Proper WebSocket lifecycle: CloseStream sent on disconnect, client removed from ConcurrentHashMap
• ⚠️ Minor: PR body metadata says number: 260 but directory and title both use 300 — cosmetic only

Documentation

• ✅ README has "What you'll build" section
• ✅ Environment variables table with link to Deepgram console
• ✅ Install and run instructions (Maven wrapper included)
• ✅ .env.example present and complete
• ✅ "How it works" section explains the WebSocket flow
• ✅ Key parameters table documents model, smartFormat, interimResults, tag

---

✓ All checks pass. Ready for merge.

---

Review by Lead on 2026-04-02