deepgram-js-speech-to-text

使用 Deepgram 语音转文本（JavaScript / TypeScript SDK）

通过 /v1/listen 为预录制音频（REST）或实时音频（WebSocket）生成基础转录文本。

何时使用此产品

• REST（client.listen.v1.media.transcribeUrl / transcribeFile） — 对已完成的 URL 或文件进行一次性转录。适用于批处理任务、字幕生成和离线处理。
• WebSocket（client.listen.v1.createConnection() / connect()） — 连续流式转录。适用于实时字幕、麦克风音频、电话流，以及浏览器或 Node 实时应用。

以下情况请使用其他 skill：

• 如果你还希望在同一次 /v1/listen 调用中获取摘要、主题、意图、情感、语言检测或脱敏建议 → deepgram-js-audio-intelligence。
• 如果你需要在 /v2/listen 上使用 Flux 轮流发言和回合结束事件 → deepgram-js-conversational-stt。
• 如果你需要通过一个套接字实现包含 STT + LLM + TTS 的完整交互式助手 → deepgram-js-voice-agent。

身份验证

require("dotenv").config();

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

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

请使用 src/CustomClient.ts 中导出的 DeepgramClient，而非 DefaultDeepgramClient。该包装器会添加必需的 Token 身份验证前缀、会话标头以及经过修补的 WebSocket 行为。

快速入门 — REST（预录制 URL）

来自 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,
);

快速入门 — REST（预录制文件）

来自 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,
  }
);

在此 SDK 中，transcribeFile(...) 接受多种上传类型：fs.ReadStream、Buffer、ReadableStream、Blob、File、ArrayBuffer 和 Uint8Array（参见 examples/23-file-upload-types.ts）。

快速入门 — WebSocket（实时流）

来自 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" });
});

仓库中的示例采用两步套接字流程：createConnection() → 注册处理程序 → connect() → waitForOpen()。

关键参数 / API 接口

• REST：model、language、punctuate、smart_format、paragraphs、utterances、multichannel、numerals、search、keyterm、keywords、encoding、sample_rate、callback、tag。
• WSS 连接参数（src/api/resources/listen/resources/v1/client/Client.ts）：model 为必填项；常见的实时标志包括 language、interim_results、endpointing、utterance_end_ms、vad_events、encoding、sample_rate、multichannel、punctuate、smart_format。
• WSS 客户端消息（src/api/resources/listen/resources/v1/client/Socket.ts）：sendMedia(...)、sendFinalize(...)、sendCloseStream(...)、sendKeepAlive(...)。
• WSS 服务端事件：Results、Metadata、UtteranceEnd、SpeechStarted。

API 参考（分层）

1. 仓库内参考：REST 相关内容见 reference.md → Listen V1 Media；WSS 行为见 src/CustomClient.ts 和 src/api/resources/listen/resources/v1/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-pre-recorded
   • https://developers.deepgram.com/reference/speech-to-text/listen-streaming

注意事项

1. 使用 DeepgramClient，不要使用 DefaultDeepgramClient。 自定义包装器添加了 Token 身份验证、会话 ID、浏览器 WS 身份验证协议和经过修补的套接字。
2. 仓库中的 WSS 示例分为两个阶段。 createConnection() 不会打开套接字；请调用 connect()，通常还要调用 waitForOpen()。
3. 关闭 v1 流之前先完成处理。 sendFinalize({ type: "Finalize" }) 会刷新最后一段部分结果。
4. 保持空闲流处于活动状态。 长时间暂停时，请发送音频或调用 sendKeepAlive({ type: "KeepAlive" })。
5. 原始音频元数据必须与实际情况一致。 如果发送 PCM，encoding 和 sample_rate 必须与字节数据相符。
6. 浏览器身份验证与 Node 身份验证不同。 在浏览器中，由于无法使用自定义标头，包装器会将身份验证和会话信息移入 WebSocket 子协议。
7. 仅对 Flux 使用 /v2/listen。 如果需要支持轮次感知的对话式 STT，请切换技能，不要强行使用 v1。

此仓库中的示例文件

• 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

核心产品技能

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

npx skills add deepgram/skills

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