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 専用の 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. sendFinalize ではなく sendCloseStream で閉じてください。 Finalize は v1 のパターンです。
4. ping() は Node 専用です。 ブラウザーの WS ping フレームはユーザーから利用できないため、src/CustomClient.ts はブラウザーで例外をスローします。
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 を参照）。