DeepgramFlux

:::caution[Currently Disabled] DeepgramFlux is currently disabled and will throw an error on construction. The V2 Flux API integration is not yet available. This guide documents the intended API for when it becomes available. :::

Use DeepgramFlux for the lowest-latency voice pipelines. It connects to Deepgram’s V2 (Flux) streaming API, which delivers turn-based transcription with eager end-of-turn signals — the key ingredient for the eager LLM pipeline.

Prerequisites

• A Deepgram API key

No extra packages needed — DeepgramFlux uses a native WebSocket connection directly to the Deepgram V2 API.

For production, set up a proxy server so your API key stays server-side.

Basic setup

import { CompositeVoice, MicrophoneInput, DeepgramFlux, AnthropicLLM, DeepgramTTS, BrowserAudioOutput } from '@lukeocodes/composite-voice';

const agent = new CompositeVoice({
  providers: [
    new MicrophoneInput(),
    new DeepgramFlux({
      proxyUrl: '/api/proxy/deepgram',
      options: {
        model: 'flux-general-en',
        eagerEotThreshold: 0.5,
      },
    }),
    new AnthropicLLM({
      proxyUrl: '/api/proxy/anthropic',
      model: 'claude-haiku-4-5',
      systemPrompt: 'You are a helpful voice assistant. Keep responses brief.',
    }),
    new DeepgramTTS({
      proxyUrl: '/api/proxy/deepgram',
      voice: 'aura-2-thalia-en',
    }),
    new BrowserAudioOutput(),
  ],
  eagerLLM: {
    enabled: true,
    cancelOnTextChange: true,
    similarityThreshold: 0.8,
  },
});

await agent.initialize();
await agent.startListening();

Configuration options

See the API reference for the full list.

How Flux differs from DeepgramSTT

DeepgramFlux uses Deepgram’s V2 API (listen.v2), which is fundamentally different from the V1 API used by DeepgramSTT:

Use DeepgramFlux when: you want the lowest latency via the eager LLM pipeline, or you prefer the turn-based conversation model.

Use DeepgramSTT when: you need Nova-3’s broader language support, domain-specific models (medical, finance), or V1-specific features like diarization.

TurnInfo events

Flux delivers transcription through TurnInfo events that map to the CompositeVoice transcription model:

Eager LLM pipeline

The killer feature of DeepgramFlux is the EagerEndOfTurn signal. When Deepgram predicts that the speaker is about to stop talking, it fires this event early — before the final EndOfTurn confirmation. The SDK uses it to start LLM generation speculatively.

Configure the threshold to balance speed vs. accuracy:

const stt = new DeepgramFlux({
  proxyUrl: '/api/proxy/deepgram',
  options: {
    model: 'flux-general-en',
    eagerEotThreshold: 0.5,  // lower = faster but more false positives
    eotThreshold: 0.7,       // higher = more certain before confirming end-of-turn
  },
});

Enable the eager pipeline in CompositeVoice:

const agent = new CompositeVoice({
  providers: [
    new MicrophoneInput(),
    stt,
    new AnthropicLLM({ proxyUrl: '/api/proxy/anthropic' }),
    new DeepgramTTS({ proxyUrl: '/api/proxy/deepgram' }),
    new BrowserAudioOutput(),
  ],
  eagerLLM: {
    enabled: true,
    cancelOnTextChange: true,
    similarityThreshold: 0.8,  // accept if >=80% word overlap
  },
});

The similarityThreshold controls how different the final text can be from the preflight text before the speculative response is cancelled. A value of 0.8 means that if 80%+ of the words match (in order), the response is kept. See textSimilarity for details on how similarity is computed.

Complete example

import { CompositeVoice, MicrophoneInput, DeepgramFlux, AnthropicLLM, DeepgramTTS, BrowserAudioOutput } from '@lukeocodes/composite-voice';

const agent = new CompositeVoice({
  providers: [
    new MicrophoneInput(),
    new DeepgramFlux({
      proxyUrl: '/api/proxy/deepgram',
      language: 'en',
      options: {
        model: 'flux-general-en',
        eagerEotThreshold: 0.5,
        eotThreshold: 0.7,
        eotTimeoutMs: 5000,
        keyterms: ['CompositeVoice'],
      },
    }),
    new AnthropicLLM({
      proxyUrl: '/api/proxy/anthropic',
      model: 'claude-haiku-4-5',
      maxTokens: 256,
      systemPrompt: 'You are a helpful voice assistant. Keep responses under two sentences.',
    }),
    new DeepgramTTS({
      proxyUrl: '/api/proxy/deepgram',
      voice: 'aura-2-thalia-en',
    }),
    new BrowserAudioOutput(),
  ],
  eagerLLM: {
    enabled: true,
    cancelOnTextChange: true,
    similarityThreshold: 0.8,
  },
  conversationHistory: { enabled: true, maxTurns: 10 },
  logging: { enabled: true, level: 'info' },
});

agent.on('transcription.preflight', (event) => {
  console.log('Eager end-of-turn:', event.text);
});

agent.on('transcription.speechFinal', (event) => {
  console.log('Confirmed:', event.text);
});

await agent.initialize();
await agent.startListening();

Tips and gotchas

• Always use a proxy in production. Pass proxyUrl instead of apiKey so your Deepgram key never reaches the browser. The SDK converts http(s) to ws(s) automatically.
• No peer dependencies. DeepgramFlux connects directly to the Deepgram V2 WebSocket API using native WebSocket — no @deepgram/sdk required.
• Set eagerEotThreshold to enable preflight. Without this option, DeepgramFlux will not emit EagerEndOfTurn events, and the eager LLM pipeline will have no preflight signals to work with.
• Connection timeout. The WebSocket connection defaults to a 10-second timeout. Adjust with timeout in the config if your network is slow.
• Keep-alive. Use sendKeepAlive() to prevent the V2 WebSocket from timing out during long pauses.

Related resources

• Eager pipeline example — preflight signals with speculative LLM
• Deepgram pipeline example — full Deepgram STT + TTS pipeline
• Proxy server example — secure your API key server-side
• Pipeline architecture — how the eager pipeline works
• API reference: DeepgramFlux
• API reference: DeepgramFluxConfig
• Providers reference