deepgram-js-conversational-stt

使用 Deepgram Conversational STT / Flux（JavaScript / TypeScript SDK）

通过 /v2/listen 为对话音频提供可感知轮次的流式 STT，并支持显式轮次事件。

何时使用此产品

• 你需要可感知轮次的转写，而不只是词语流。
• 你想使用 TurnInfo 和 Connected 等 Flux 风格的事件。
• 你正在构建对话界面，但不想使用完整的 Voice Agent 运行时。

以下情况请使用其他技能：

• 你需要通用的 v1 转写或预录音频 REST → deepgram-js-speech-to-text。
• 你需要内置思考和语音功能的托管助手 → deepgram-js-voice-agent。
• 你需要情感分析和摘要等分析叠加功能 → deepgram-js-audio-intelligence。

身份验证

require("dotenv").config();

const { DeepgramClient } = require("@deepgram/sdk");

const deepgramClient = new DeepgramClient({
  apiKey: process.env.DEEPGRAM_API_KEY,
});

快速开始

来自 examples/26-transcription-live-websocket-v2.ts：

const deepgramConnection = await deepgramClient.listen.v2.createConnection({
  model: "flux-general-en",
});

deepgramConnection.on("message", (data) => {
  if (data.type === "Connected") {
    console.log("Connected:", data);
  } else if (data.type === "TurnInfo") {
    console.log("Turn Info:", data);
  } else if (data.type === "FatalError") {
    deepgramConnection.close();
  }
});

deepgramConnection.connect();
await deepgramConnection.waitForOpen();

// Swap this for a live mic capture in real apps; the repo example uses
// `createReadStream` over a sample file.
const { createReadStream } = require("node:fs");
const audioStream = createReadStream("samples/spacewalk.wav");

audioStream.on("data", (chunk) => {
  deepgramConnection.sendMedia(chunk);
});

audioStream.on("end", () => {
  deepgramConnection.sendCloseStream({ type: "CloseStream" });
});

关键参数 / API 接口

• 来自 src/api/resources/listen/resources/v2/client/Client.ts 的连接参数：model、encoding、sample_rate、eager_eot_threshold、eot_threshold、eot_timeout_ms、keyterm、tag、mip_opt_out。
• 来自 src/api/resources/listen/resources/v2/client/Socket.ts 的套接字方法：sendMedia(...)、sendCloseStream(...)、sendListenV2Configure(...)、waitForOpen()。
• 来自 src/CustomClient.ts 的自定义封装新增项：createConnection(...) 别名和仅限 Node.js 的 ping(...) 辅助方法。

限制

• 当前生成的 ListenV2Model 类型仅支持 "flux-general-en"。
• 产品文档提到了更广泛的 Flux 功能，但目前此仓库生成的类型尚未提供 flux-general-multi / language_hint。

API 参考（分层）

1. 仓库内参考：reference.md 目前未记录 listen.v2；请将 src/CustomClient.ts 和 src/api/resources/listen/resources/v2/client/{Client,Socket}.ts 作为仓库内的权威参考。
2. 规范 OpenAPI（REST）：https://developers.deepgram.com/openapi.yaml
3. 规范 AsyncAPI（WSS）：https://developers.deepgram.com/asyncapi.yaml
4. Context7：库 ID /llmstxt/developers_deepgram_llms_txt
5. 产品文档：
   • 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

注意事项

1. 这里没有 REST 路径。 此技能仅支持 /v2/listen WebSocket。
2. 当前仓库的类型定义仅允许 flux-general-en。 将多语言 Flux 支持视为产品功能，SDK 接口目前尚未体现此能力。
3. 使用 sendCloseStream 关闭，而不是 sendFinalize。 Finalize 是 v1 的模式。
4. ping() 仅限 Node.js。 src/CustomClient.ts 会在浏览器中抛出异常，因为浏览器 WS 的 ping 帧不会向用户开放。
5. createConnection() 是惰性调用。 注册处理程序后再调用 connect()。
6. 示例明确提示了访问权限 / 可用性问题。 400 可能表示你的账户或端点尚未启用，而不是套接字代码有误。
7. 对于容器化音频，请省略 encoding。 对于原始 PCM / Opus 流，则应保留。

此仓库中的示例文件

• examples/26-transcription-live-websocket-v2.ts
• examples/27-deepgram-session-header.ts

核心产品技能

如需跨语言的 Deepgram 产品知识——整合后的 API 参考、文档查找工具、专注且可运行的示例方案、第三方集成示例以及 MCP 设置，请安装核心技能：

npx skills add deepgram/skills

此 SDK 提供符合语言惯例的代码技能；deepgram/skills 提供跨语言产品知识（参见 api、docs、recipes、examples、starters、setup-mcp）。