deepgram-js-speech-to-text

Deepgram Speech-to-Text の使用（JavaScript / TypeScript SDK）

/v1/listen を介した、録音済み音声の基本的な文字起こし（REST）またはライブ音声の文字起こし（WebSocket）です。

この製品を使用する場面

• REST（client.listen.v1.media.transcribeUrl / transcribeFile） — 完成した URL またはファイルを一度だけ文字起こしします。バッチジョブ、字幕の生成、オフライン処理に適しています。
• WebSocket（client.listen.v1.createConnection() / connect()） — 継続的なストリーミング文字起こしを行います。ライブ字幕、マイク音声、電話ストリーム、ブラウザーまたは Node のリアルタイムアプリに適しています。

次の場合は別のスキルを使用してください：

• 同じ /v1/listen 呼び出しで、要約、トピック、インテント、センチメント、言語検出、または編集のガイダンスも必要な場合 → deepgram-js-audio-intelligence。
• /v2/listen で Flux のターンテイキングとターン終了イベントが必要な場合 → deepgram-js-conversational-stt。
• 1 つのソケットで 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,
});

DefaultDeepgramClient ではなく、src/CustomClient.ts からエクスポートされた DeepgramClient を使用してください。このラッパーは、必要な 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,
  }
);

transcribeFile(...) は、この SDK で複数のアップロード形式を受け付けます：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" });
});

リポジトリのサンプルでは、2 段階のソケットフローを使用します：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. DefaultDeepgramClient ではなく、DeepgramClient を使用してください。 カスタムラッパーは、Token 認証、セッション ID、ブラウザーの WS 認証プロトコル、パッチ適用済みソケットを追加します。
2. このリポジトリの WSS の例は 2 段階です。 createConnection() はソケットを開きません。connect() を呼び出し、通常は waitForOpen() も呼び出してください。
3. v1 ストリームを閉じる前に確定してください。 sendFinalize({ type: "Finalize" }) を呼び出すと、最後の未完了部分がフラッシュされます。
4. アイドル状態のストリームを維持してください。 長い無音状態が続く場合は、音声を送信するか、sendKeepAlive({ type: "KeepAlive" }) を使用してください。
5. 生音声のメタデータは実際のデータと一致させてください。 PCM を送信する場合、encoding と sample_rate をバイト列に合わせる必要があります。
6. ブラウザーと Node では認証方法が異なります。 ブラウザーではカスタムヘッダーを使用できないため、ラッパーは認証情報とセッション情報を WebSocket のサブプロトコルに移します。
7. /v2/listen は Flux にのみ使用してください。 ターンを考慮した会話型 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 を参照）。