Deepgram

OverviewCopy Anchor Link

Deepgram streams transcripts over a WebSocket. pipedog ports both of Pipecat's Deepgram speech-to-text services:

• DeepgramSTTService: Deepgram's /v1/listen API (Nova models), with interim results, smart formatting, keyterms and the other Deepgram query options.
• DeepgramFluxSTTService: Deepgram Flux (/v2/listen), which also detects the end of the user's turn, with optional eager end-of-turn events.

InstallationCopy Anchor Link

bun add @pipedog/deepgram

import { DeepgramSTTService } from "@pipedog/deepgram/stt";
import { DeepgramFluxSTTService } from "@pipedog/deepgram/flux/stt";

PrerequisitesCopy Anchor Link

• A Deepgram account and an API key from the Deepgram console.
• Pass the key as apiKey. The examples read it from DEEPGRAM_API_KEY.

DeepgramSTTServiceCopy Anchor Link

ConfigurationCopy Anchor Link

SettingsCopy Anchor Link

Runtime-updatable settings, passed as settings: new DeepgramSTTService.Settings({...}). Any setting you leave out keeps the default below. Other Deepgram query parameters can go in extra.

UsageCopy Anchor Link

import { STTUpdateSettingsFrame } from "@pipedog/core/frames/frames";
import { Language } from "@pipedog/core/transcriptions/language";
import { DeepgramSTTService } from "@pipedog/deepgram/stt";

const stt = new DeepgramSTTService({
  apiKey: process.env.DEEPGRAM_API_KEY ?? "",
  settings: new DeepgramSTTService.Settings({
    model: "nova-3-general",
    language: Language.EN,
    smartFormat: true,
    keyterm: ["pipedog", "Pipecat"],
  }),
});

Change settings mid-call with an STTUpdateSettingsFrame. The service reconnects with the new settings:

// Queue it on the worker, or push it from a processor upstream of the service.
const update = new STTUpdateSettingsFrame({
  delta: new DeepgramSTTService.Settings({ language: Language.ES }),
});

NotesCopy Anchor Link

• Emits InterimTranscriptionFrame while the user speaks and TranscriptionFrame for final results. A VADUserStoppedSpeakingFrame from the user aggregator's VAD makes it finalize early.
• sampleRate defaults to the pipeline's input rate.
• If the connection keeps failing quickly (an invalid key, say), the service stops retrying and pushes an error.

DeepgramFluxSTTServiceCopy Anchor Link

ConfigurationCopy Anchor Link

SettingsCopy Anchor Link

UsageCopy Anchor Link

import { Language } from "@pipedog/core/transcriptions/language";
import { DeepgramFluxSTTService } from "@pipedog/deepgram/flux/stt";

const stt = new DeepgramFluxSTTService({
  apiKey: process.env.DEEPGRAM_API_KEY ?? "",
  settings: new DeepgramFluxSTTService.Settings({
    model: "flux-general-en",
    eagerEotThreshold: 0.5,
    eotThreshold: 0.8,
  }),
});

stt.addEventHandler("on_end_of_turn", async (_service, transcript: string) => {
  console.log("end of turn:", transcript);
});

Multilingual, with language hints:

const multilingual = new DeepgramFluxSTTService({
  apiKey: process.env.DEEPGRAM_API_KEY ?? "",
  settings: new DeepgramFluxSTTService.Settings({
    model: "flux-general-multi",
    languageHints: [Language.EN, Language.ES],
  }),
});

Event handlersCopy Anchor Link

NotesCopy Anchor Link

• Emits an InterimTranscriptionFrame on every Flux update and a TranscriptionFrame at the end of the turn.
• Flux needs linear16 audio, which is what pipedog transports produce.

Runtime notesCopy Anchor Link

Generated from pipecat.runtimes and pipecat.compat in packages/deepgram/package.json: ✅ means the compat smoke test passes on that runtime.

Both services use the global WebSocket and send the key as an Authorization header on the handshake. That works on Bun, Node, Deno and Cloudflare Workers (where the socket is opened through fetch). Pass webSocketFactory to open the socket some other way, through a proxy for example. A standard WebSocket doesn't expose the HTTP status of a refused handshake, so DeepgramApiError is only raised when the runtime's error carries one.