deepgram-java-conversational-stt

name

deepgram-java-conversational-stt

description

Use when writing or reviewing Java code in this repo that calls Deepgram Conversational STT v2 / Flux over `/v2/listen`. Covers `client.listen().v2().v2WebSocket()`, `V2ConnectOptions`, `onTurnInfo`, and turn-aware close handling. Use `deepgram-java-speech-to-text` for standard v1 transcription and `deepgram-java-voice-agent` for fully interactive assistants. Triggers include "flux", "conversational stt", "listen v2", "turn detection", "end of turn", and "eot".

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

import com.deepgram.DeepgramClient;

DeepgramClient client = DeepgramClient.builder()
        .apiKey(System.getenv("DEEPGRAM_API_KEY"))
        .build();

Quick start

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:

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).