Using Deepgram Audio Intelligence (JavaScript / TypeScript SDK)
Analytics overlays applied to /v1/listen: summaries, topics, intents, sentiment, language detection, diarization, redaction, entities. Same client surface as STT; turn features on with parameters.
When to use this product
- You have audio and want analytics returned alongside the transcript.
- REST is the primary path; the WebSocket path supports only a subset of intelligence features.
Use a different skill when:
- You just want transcript output →
deepgram-js-speech-to-text.
- You already have text and want analytics on that text →
deepgram-js-text-intelligence.
- You need Flux turn-taking →
deepgram-js-conversational-stt.
- You need a full interactive voice agent →
deepgram-js-voice-agent.
Feature availability: REST vs WSS
| Feature |
REST |
WSS |
diarize |
yes |
yes |
redact |
yes |
yes |
detect_entities |
yes |
yes |
punctuate, smart_format |
yes |
yes |
summarize |
yes |
no in current WSS connect args |
topics |
yes |
no |
intents |
yes |
no |
sentiment |
yes |
no |
detect_language |
yes |
no |
Authentication
require("dotenv").config();
const { DeepgramClient } = require("@deepgram/sdk");
const deepgramClient = new DeepgramClient({
apiKey: process.env.DEEPGRAM_API_KEY,
});
Quick start — REST with analytics
From examples/22-transcription-advanced-options.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,
smart_format: true,
sentiment: true,
topics: true,
custom_topic: "custom_topic",
custom_topic_mode: "extended",
intents: true,
custom_intent: "custom_intent",
custom_intent_mode: "extended",
detect_entities: true,
detect_language: true,
diarize: true,
keyterm: ["keyword1", "keyword2"],
redact: ["pci", "ssn"],
});
Quick start — WSS subset
Start from examples/07-transcription-live-websocket.ts and keep the same socket flow, but only use WSS-supported intelligence flags such as diarize, redact, and detect_entities in the connection args.
const deepgramConnection = await deepgramClient.listen.v1.createConnection({
model: "nova-3",
diarize: true,
redact: "pci",
detect_entities: true,
});
Key parameters / API surface
- Analytics flags:
summarize, topics, intents, sentiment, detect_language, detect_entities, diarize, redact, custom_topic, custom_topic_mode, custom_intent, custom_intent_mode.
- Standard STT flags still apply:
model, language, encoding, sample_rate, punctuate, smart_format, utterances, paragraphs, multichannel.
- Nova-3-specific biasing in repo examples uses
keyterm, not keywords.
API reference (layered)
- In-repo reference:
reference.md → Listen V1 Media; WSS subset 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
summarize on /v1/listen is versioned, not plain boolean. The generated REST surface and examples point at "v2".
- Most intelligence flags are REST-only. Current WSS connect args do not expose
topics, intents, sentiment, summarize, or detect_language.
redact typing is looser in practice than in the generated alias. Examples pass arrays like ["pci", "ssn"], even though ListenV1Redact itself is just a string alias.
- Use
keyterm for Nova-3 biasing. examples/22-transcription-advanced-options.ts explicitly notes keywords are not supported for Nova-3.
- Model/feature support is product-side.
nova-3 is the safest choice when mixing many overlays.
- Diarization quality depends on audio quality and duration. Short or noisy clips churn speakers.
Example files in this repo
examples/22-transcription-advanced-options.ts
examples/04-transcription-prerecorded-url.ts
examples/05-transcription-prerecorded-file.ts
examples/07-transcription-live-websocket.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-audio-intelligence3description: Use when writing or reviewing JavaScript/TypeScript in this repo that calls Deepgram audio analytics overlays on `/v1/listen` - summarize, topics, intents, sentiment, diarize, redact, detect_language, and entity detection. Same endpoint as plain STT, different params. Covers REST via `client.listen.v1.media.transcribeUrl` / `transcribeFile` and the WebSocket-supported subset on `client.listen.v1.createConnection()` / `connect()`. Use `deepgram-js-speech-to-text` for plain transcription and `deepgram-js-text-intelligence` for analytics on already-transcribed text. Triggers include "audio intelligence", "summarize audio", "diarize", "sentiment from audio", "redact PII", and "detect language audio".4metadata:5 source: https://skillmd.com/skills/deepgram/deepgram-js-audio-intelligence6---78# Using Deepgram Audio Intelligence (JavaScript / TypeScript SDK)910Analytics overlays applied to `/v1/listen`: summaries, topics, intents, sentiment, language detection, diarization, redaction, entities. Same client surface as STT; turn features on with parameters.1112## When to use this product1314- You have **audio** and want analytics returned alongside the transcript.15- REST is the primary path; the WebSocket path supports only a subset of intelligence features.1617**Use a different skill when:**18- You just want transcript output → `deepgram-js-speech-to-text`.19- You already have text and want analytics on that text → `deepgram-js-text-intelligence`.20- You need Flux turn-taking → `deepgram-js-conversational-stt`.21- You need a full interactive voice agent → `deepgram-js-voice-agent`.2223## Feature availability: REST vs WSS2425| Feature | REST | WSS |26|---|---|---|27| `diarize` | yes | yes |28| `redact` | yes | yes |29| `detect_entities` | yes | yes |30| `punctuate`, `smart_format` | yes | yes |31| `summarize` | yes | no in current WSS connect args |32| `topics` | yes | no |33| `intents` | yes | no |34| `sentiment` | yes | no |35| `detect_language` | yes | no |3637## Authentication3839```js40require("dotenv").config();4142const { DeepgramClient } = require("@deepgram/sdk");4344const deepgramClient = new DeepgramClient({45 apiKey: process.env.DEEPGRAM_API_KEY,46});47```4849## Quick start — REST with analytics5051From `examples/22-transcription-advanced-options.ts`:5253```js54const data = await deepgramClient.listen.v1.media.transcribeUrl({55 url: "https://dpgr.am/spacewalk.wav",56 model: "nova-3",57 language: "en",58 punctuate: true,59 paragraphs: true,60 utterances: true,61 smart_format: true,62 sentiment: true,63 topics: true,64 custom_topic: "custom_topic",65 custom_topic_mode: "extended",66 intents: true,67 custom_intent: "custom_intent",68 custom_intent_mode: "extended",69 detect_entities: true,70 detect_language: true,71 diarize: true,72 keyterm: ["keyword1", "keyword2"],73 redact: ["pci", "ssn"],74});75```7677## Quick start — WSS subset7879Start from `examples/07-transcription-live-websocket.ts` and keep the same socket flow, but only use WSS-supported intelligence flags such as `diarize`, `redact`, and `detect_entities` in the connection args.8081```js82const deepgramConnection = await deepgramClient.listen.v1.createConnection({83 model: "nova-3",84 diarize: true,85 redact: "pci",86 detect_entities: true,87});88```8990## Key parameters / API surface9192- Analytics flags: `summarize`, `topics`, `intents`, `sentiment`, `detect_language`, `detect_entities`, `diarize`, `redact`, `custom_topic`, `custom_topic_mode`, `custom_intent`, `custom_intent_mode`.93- Standard STT flags still apply: `model`, `language`, `encoding`, `sample_rate`, `punctuate`, `smart_format`, `utterances`, `paragraphs`, `multichannel`.94- Nova-3-specific biasing in repo examples uses `keyterm`, not `keywords`.9596## API reference (layered)97981. **In-repo reference**: `reference.md` → `Listen V1 Media`; WSS subset behavior lives in `src/CustomClient.ts` and `src/api/resources/listen/resources/v1/client/{Client,Socket}.ts`.992. **Canonical OpenAPI (REST)**: https://developers.deepgram.com/openapi.yaml1003. **Canonical AsyncAPI (WSS)**: https://developers.deepgram.com/asyncapi.yaml1014. **Context7**: library ID `/llmstxt/developers_deepgram_llms_txt`1025. **Product docs**:103 - https://developers.deepgram.com/docs/stt-intelligence-feature-overview104 - https://developers.deepgram.com/docs/summarization105 - https://developers.deepgram.com/docs/topic-detection106 - https://developers.deepgram.com/docs/intent-recognition107 - https://developers.deepgram.com/docs/sentiment-analysis108 - https://developers.deepgram.com/docs/language-detection109 - https://developers.deepgram.com/docs/redaction110 - https://developers.deepgram.com/docs/diarization111112## Gotchas1131141. **`summarize` on `/v1/listen` is versioned, not plain boolean.** The generated REST surface and examples point at `"v2"`.1152. **Most intelligence flags are REST-only.** Current WSS connect args do not expose `topics`, `intents`, `sentiment`, `summarize`, or `detect_language`.1163. **`redact` typing is looser in practice than in the generated alias.** Examples pass arrays like `["pci", "ssn"]`, even though `ListenV1Redact` itself is just a string alias.1174. **Use `keyterm` for Nova-3 biasing.** `examples/22-transcription-advanced-options.ts` explicitly notes keywords are not supported for Nova-3.1185. **Model/feature support is product-side.** `nova-3` is the safest choice when mixing many overlays.1196. **Diarization quality depends on audio quality and duration.** Short or noisy clips churn speakers.120121## Example files in this repo122123- `examples/22-transcription-advanced-options.ts`124- `examples/04-transcription-prerecorded-url.ts`125- `examples/05-transcription-prerecorded-file.ts`126- `examples/07-transcription-live-websocket.ts`127128## Central product skills129130For 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:131132```bash133npx skills add deepgram/skills134```135136This SDK ships language-idiomatic code skills; `deepgram/skills` ships cross-language product knowledge (see `api`, `docs`, `recipes`, `examples`, `starters`, `setup-mcp`).