deepgram-java-conversational-stt

# Using Deepgram Conversational STT / Flux (Java SDK) Turn-aware streaming transcription over `/v2/listen` for conversational audio. ## When to use this product - You want explicit turn events, not just regular interim/final transcript chunks. - You are building conversational UX where end-of-turn timing matters. **Use a different skill when:** - You need general-purpose STT over REST or classic streaming → `deepgram-java-speech-to-text`. - You need a hosted interactive assistant → `deepgram-java-voice-agent`. ## Authentication ```java import com.deepgram.DeepgramClient; DeepgramClient client = DeepgramClient.builder() .apiKey(System.getenv("DEEPGRAM_API_KEY")) .build(); ``` ## Quick start ```java import com.deepgram.resources.listen.v2.types.ListenV2CloseStream; import com.deepgram.resources.listen.v2.types.ListenV2CloseStreamType; import com.deepgram.resources.listen.v2.websocket.V2ConnectOptions; import com.deepgram.resources.listen.v2.websocket.V2WebSocketClient; import java.util.concurrent.TimeUnit; V2WebSocketClient wsClient = client.listen().v2().v2WebSocket(); wsClient.onConnected(connected -> System.out.println("request_id=" + connected.getRequestId())); wsClient.onTurnInfo(turnInfo -> { System.out.printf("[%s] turn=%.0f transcript=\"%s\"%n", turnInfo.getEvent(), turnInfo.getTurnIndex(), turnInfo.getTranscript()); }); wsClient.connect(V2ConnectOptions.builder() .model("flux-general-en") .build()) .get(10, TimeUnit.SECONDS); // wsClient.sendMedia(okio.ByteString.of(audioChunk)); wsClient.sendCloseStream(ListenV2CloseStream.builder() .type(ListenV2CloseStreamType.CLOSE_STREAM) .build()); ``` ## Key parameters / API surface - Entry point: `client.listen().v2().v2WebSocket()` - Required connect field: `model(String)` - Verified connect options in source: `encoding`, `sampleRate`, `eagerEotThreshold`, `eotThreshold`, `eotTimeoutMs`, `keyterm`, `mipOptOut`, `tag` - Send methods: `sendMedia(...)`, `sendCloseStream(...)` - Event handlers: `onConnected(Consumer<ListenV2Connected>)`, `onTurnInfo(...)`, `onErrorMessage(...)`, plus generic connection/error hooks ## API reference (layered) 1. **In-repo source of truth**: `src/main/java/com/deepgram/resources/listen/v2/` and `examples/listen/LiveStreamingV2.java`. No `reference.md` exists in this checkout. 2. **Canonical AsyncAPI**: https://developers.deepgram.com/asyncapi.yaml 3. **Context7**: `/llmstxt/developers_deepgram_llms_txt` 4. **Product docs**: - https://developers.deepgram.com/reference/speech-to-text/listen-flux - https://developers.deepgram.com/docs/flux/quickstart - https://developers.deepgram.com/docs/flux/language-prompting ## Gotchas 1. **This is WebSocket-only in the Java SDK.** There is no REST helper for `/v2/listen` here. 2. **`model` is a plain `String`, not an enum.** Use Flux model IDs such as `flux-general-en` exactly. 3. **Close with `sendCloseStream(...)`, not Listen V1 finalize.** The message type is different from v1. 4. **The current Java connect options do not expose `language_hint`.** Do not assume the Python surface exists here. 5. **Turn events are the main payload.** Handle `onTurnInfo(...)`, not Listen V1 `onResults(...)`. 6. **You still need to stream binary audio manually.** The example only wires handlers and close flow. 7. **Wait for `connect(...).get(...)` before sending media.** The client is async but not fire-and-forget. ## Example files in this repo - `examples/listen/LiveStreamingV2.java` ## 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`).