Using Deepgram Speech-to-Text (JavaScript / TypeScript SDK)
Basic transcription for prerecorded audio (REST) or live audio (WebSocket) via /v1/listen.
When to use this product
- REST (
client.listen.v1.media.transcribeUrl / transcribeFile) — one-shot transcription of a finished URL or file. Good for batch jobs, caption generation, offline processing.
- WebSocket (
client.listen.v1.createConnection() / connect()) — continuous streaming transcription. Good for live captions, microphone audio, telephony streams, browser or Node realtime apps.
Use a different skill when:
- You also want summaries, topics, intents, sentiment, language detection, or redaction guidance on the same
/v1/listen call → deepgram-js-audio-intelligence.
- You need Flux turn-taking and end-of-turn events on
/v2/listen → deepgram-js-conversational-stt.
- You need a full interactive assistant with STT + LLM + TTS over one socket →
deepgram-js-voice-agent.
Authentication
require("dotenv").config();
const { DeepgramClient } = require("@deepgram/sdk");
const deepgramClient = new DeepgramClient({
apiKey: process.env.DEEPGRAM_API_KEY,
});
Use the exported DeepgramClient from src/CustomClient.ts, not DefaultDeepgramClient. The wrapper adds the required Token auth prefix, session headers, and patched WebSocket behavior.
Quick start — REST (prerecorded URL)
From examples/04-transcription-prerecorded-url.ts:
const data = await deepgramClient.listen.v1.media.transcribeUrl({
url: "https://dpgr.am/spacewalk.wav",
model: "nova-3",
language: "en",
punctuate: true,
paragraphs: true,
utterances: true,
});
console.log(
"Transcription:",
data.results?.channels?.[0]?.alternatives?.[0]?.transcript,
);
Quick start — REST (prerecorded file)
From examples/05-transcription-prerecorded-file.ts:
const { createReadStream } = require("fs");
const data = await deepgramClient.listen.v1.media.transcribeFile(
createReadStream("./examples/spacewalk.wav"),
{
model: "nova-3",
language: "en",
punctuate: true,
paragraphs: true,
utterances: true,
smart_format: true,
}
);
transcribeFile(...) accepts multiple upload shapes in this SDK: fs.ReadStream, Buffer, ReadableStream, Blob, File, ArrayBuffer, and Uint8Array (see examples/23-file-upload-types.ts).
Quick start — WebSocket (live streaming)
From examples/07-transcription-live-websocket.ts:
const deepgramConnection = await deepgramClient.listen.v1.createConnection({
model: "nova-3",
language: "en",
punctuate: "true",
interim_results: "true",
});
deepgramConnection.on("message", (data) => {
if (data.type === "Results") {
console.log("Transcript:", data);
}
});
deepgramConnection.connect();
await deepgramConnection.waitForOpen();
// Swap this for a mic capture (e.g. `node-microphone` / `MediaRecorder`)
// in real apps; the repo examples use `createReadStream` over a sample WAV.
const { createReadStream } = require("node:fs");
const audioStream = createReadStream("samples/spacewalk.wav");
audioStream.on("data", (chunk) => {
deepgramConnection.sendMedia(chunk);
});
audioStream.on("end", () => {
deepgramConnection.sendFinalize({ type: "Finalize" });
});
The repo examples use the two-step socket flow: createConnection() → register handlers → connect() → waitForOpen().
Key parameters / API surface
- REST:
model, language, punctuate, smart_format, paragraphs, utterances, multichannel, numerals, search, keyterm, keywords, encoding, sample_rate, callback, tag.
- WSS connect args (
src/api/resources/listen/resources/v1/client/Client.ts): model is required; common realtime flags include language, interim_results, endpointing, utterance_end_ms, vad_events, encoding, sample_rate, multichannel, punctuate, smart_format.
- WSS client messages (
src/api/resources/listen/resources/v1/client/Socket.ts): sendMedia(...), sendFinalize(...), sendCloseStream(...), sendKeepAlive(...).
- WSS server events:
Results, Metadata, UtteranceEnd, SpeechStarted.
API reference (layered)
- In-repo reference:
reference.md → Listen V1 Media for REST; WSS behavior lives in src/CustomClient.ts and src/api/resources/listen/resources/v1/client/{Client,Socket}.ts.
- Canonical OpenAPI (REST): https://developers.deepgram.com/openapi.yaml
- Canonical AsyncAPI (WSS): https://developers.deepgram.com/asyncapi.yaml
- Context7: library ID
/llmstxt/developers_deepgram_llms_txt
- Product docs:
Gotchas
- Use
DeepgramClient, not DefaultDeepgramClient. The custom wrapper adds Token auth, session IDs, browser WS auth protocols, and patched sockets.
- Repo examples are two-stage for WSS.
createConnection() does not open the socket; call connect() and usually waitForOpen().
- Finalize before closing v1 streams.
sendFinalize({ type: "Finalize" }) flushes the final partial.
- Keep idle streams alive. Use audio or
sendKeepAlive({ type: "KeepAlive" }) on long pauses.
- Raw audio metadata must match reality. If you send PCM,
encoding and sample_rate must match the bytes.
- Browser auth differs from Node auth. In browsers, the wrapper moves auth/session info into WebSocket subprotocols because custom headers are unavailable.
- Use
/v2/listen only for Flux. If you need turn-aware conversational STT, switch skills instead of forcing v1.
Example files in this repo
examples/04-transcription-prerecorded-url.ts
examples/05-transcription-prerecorded-file.ts
examples/06-transcription-prerecorded-callback.ts
examples/07-transcription-live-websocket.ts
examples/08-transcription-captions.ts
examples/23-file-upload-types.ts
examples/27-deepgram-session-header.ts
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).
1---2name: deepgram-js-speech-to-text3description: Use when writing or reviewing JavaScript/TypeScript in this repo that calls Deepgram Speech-to-Text v1 (`/v1/listen`) for prerecorded or live audio transcription. Covers `client.listen.v1.media.transcribeUrl` / `transcribeFile` (REST) plus `client.listen.v1.createConnection()` / `connect()` (WebSocket). Use `deepgram-js-audio-intelligence` for summarize/sentiment/topics/diarize overlays, `deepgram-js-conversational-stt` for Flux turn-taking on `/v2/listen`, and `deepgram-js-voice-agent` for full-duplex assistants. Triggers include "transcribe", "speech to text", "STT", "listen.v1", "nova-3", "live transcription", and "websocket transcription".4metadata:5 source: https://skillmd.com/skills/deepgram/deepgram-js-speech-to-text6---78# Using Deepgram Speech-to-Text (JavaScript / TypeScript SDK)910Basic transcription for prerecorded audio (REST) or live audio (WebSocket) via `/v1/listen`.1112## When to use this product1314- **REST (`client.listen.v1.media.transcribeUrl` / `transcribeFile`)** — one-shot transcription of a finished URL or file. Good for batch jobs, caption generation, offline processing.15- **WebSocket (`client.listen.v1.createConnection()` / `connect()`)** — continuous streaming transcription. Good for live captions, microphone audio, telephony streams, browser or Node realtime apps.1617**Use a different skill when:**18- You also want summaries, topics, intents, sentiment, language detection, or redaction guidance on the same `/v1/listen` call → `deepgram-js-audio-intelligence`.19- You need Flux turn-taking and end-of-turn events on `/v2/listen` → `deepgram-js-conversational-stt`.20- You need a full interactive assistant with STT + LLM + TTS over one socket → `deepgram-js-voice-agent`.2122## Authentication2324```js25require("dotenv").config();2627const { DeepgramClient } = require("@deepgram/sdk");2829const deepgramClient = new DeepgramClient({30 apiKey: process.env.DEEPGRAM_API_KEY,31});32```3334Use the exported `DeepgramClient` from `src/CustomClient.ts`, not `DefaultDeepgramClient`. The wrapper adds the required `Token` auth prefix, session headers, and patched WebSocket behavior.3536## Quick start — REST (prerecorded URL)3738From `examples/04-transcription-prerecorded-url.ts`:3940```js41const data = await deepgramClient.listen.v1.media.transcribeUrl({42 url: "https://dpgr.am/spacewalk.wav",43 model: "nova-3",44 language: "en",45 punctuate: true,46 paragraphs: true,47 utterances: true,48});4950console.log(51 "Transcription:",52 data.results?.channels?.[0]?.alternatives?.[0]?.transcript,53);54```5556## Quick start — REST (prerecorded file)5758From `examples/05-transcription-prerecorded-file.ts`:5960```js61const { createReadStream } = require("fs");6263const data = await deepgramClient.listen.v1.media.transcribeFile(64 createReadStream("./examples/spacewalk.wav"),65 {66 model: "nova-3",67 language: "en",68 punctuate: true,69 paragraphs: true,70 utterances: true,71 smart_format: true,72 }73);74```7576`transcribeFile(...)` accepts multiple upload shapes in this SDK: `fs.ReadStream`, `Buffer`, `ReadableStream`, `Blob`, `File`, `ArrayBuffer`, and `Uint8Array` (see `examples/23-file-upload-types.ts`).7778## Quick start — WebSocket (live streaming)7980From `examples/07-transcription-live-websocket.ts`:8182```js83const deepgramConnection = await deepgramClient.listen.v1.createConnection({84 model: "nova-3",85 language: "en",86 punctuate: "true",87 interim_results: "true",88});8990deepgramConnection.on("message", (data) => {91 if (data.type === "Results") {92 console.log("Transcript:", data);93 }94});9596deepgramConnection.connect();97await deepgramConnection.waitForOpen();9899// Swap this for a mic capture (e.g. `node-microphone` / `MediaRecorder`)100// in real apps; the repo examples use `createReadStream` over a sample WAV.101const { createReadStream } = require("node:fs");102const audioStream = createReadStream("samples/spacewalk.wav");103104audioStream.on("data", (chunk) => {105 deepgramConnection.sendMedia(chunk);106});107108audioStream.on("end", () => {109 deepgramConnection.sendFinalize({ type: "Finalize" });110});111```112113The repo examples use the two-step socket flow: `createConnection()` → register handlers → `connect()` → `waitForOpen()`.114115## Key parameters / API surface116117- REST: `model`, `language`, `punctuate`, `smart_format`, `paragraphs`, `utterances`, `multichannel`, `numerals`, `search`, `keyterm`, `keywords`, `encoding`, `sample_rate`, `callback`, `tag`.118- WSS connect args (`src/api/resources/listen/resources/v1/client/Client.ts`): `model` is required; common realtime flags include `language`, `interim_results`, `endpointing`, `utterance_end_ms`, `vad_events`, `encoding`, `sample_rate`, `multichannel`, `punctuate`, `smart_format`.119- WSS client messages (`src/api/resources/listen/resources/v1/client/Socket.ts`): `sendMedia(...)`, `sendFinalize(...)`, `sendCloseStream(...)`, `sendKeepAlive(...)`.120- WSS server events: `Results`, `Metadata`, `UtteranceEnd`, `SpeechStarted`.121122## API reference (layered)1231241. **In-repo reference**: `reference.md` → `Listen V1 Media` for REST; WSS behavior lives in `src/CustomClient.ts` and `src/api/resources/listen/resources/v1/client/{Client,Socket}.ts`.1252. **Canonical OpenAPI (REST)**: https://developers.deepgram.com/openapi.yaml1263. **Canonical AsyncAPI (WSS)**: https://developers.deepgram.com/asyncapi.yaml1274. **Context7**: library ID `/llmstxt/developers_deepgram_llms_txt`1285. **Product docs**:129 - https://developers.deepgram.com/reference/speech-to-text/listen-pre-recorded130 - https://developers.deepgram.com/reference/speech-to-text/listen-streaming131132## Gotchas1331341. **Use `DeepgramClient`, not `DefaultDeepgramClient`.** The custom wrapper adds `Token` auth, session IDs, browser WS auth protocols, and patched sockets.1352. **Repo examples are two-stage for WSS.** `createConnection()` does not open the socket; call `connect()` and usually `waitForOpen()`.1363. **Finalize before closing v1 streams.** `sendFinalize({ type: "Finalize" })` flushes the final partial.1374. **Keep idle streams alive.** Use audio or `sendKeepAlive({ type: "KeepAlive" })` on long pauses.1385. **Raw audio metadata must match reality.** If you send PCM, `encoding` and `sample_rate` must match the bytes.1396. **Browser auth differs from Node auth.** In browsers, the wrapper moves auth/session info into WebSocket subprotocols because custom headers are unavailable.1407. **Use `/v2/listen` only for Flux.** If you need turn-aware conversational STT, switch skills instead of forcing v1.141142## Example files in this repo143144- `examples/04-transcription-prerecorded-url.ts`145- `examples/05-transcription-prerecorded-file.ts`146- `examples/06-transcription-prerecorded-callback.ts`147- `examples/07-transcription-live-websocket.ts`148- `examples/08-transcription-captions.ts`149- `examples/23-file-upload-types.ts`150- `examples/27-deepgram-session-header.ts`151152## Central product skills153154For 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:155156```bash157npx skills add deepgram/skills158```159160This SDK ships language-idiomatic code skills; `deepgram/skills` ships cross-language product knowledge (see `api`, `docs`, `recipes`, `examples`, `starters`, `setup-mcp`).