deepgram-js-text-to-speech

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

/v1/speak を使用して、テキストを一括 REST 生成で音声に変換するか、低レイテンシのストリーミング合成を行います。

この製品を使用する場面

• REST（client.speak.v1.audio.generate） — 完成したテキストを音声レスポンスに変換します。ダウンロード可能なファイル、事前生成するプロンプト、一括合成に最適です。
• WebSocket（client.speak.v1.createConnection() / connect()） — テキストをストリーミングで送信し、より低いレイテンシで音声を受信します。LLM がまだトークンを生成中の場合に最適です。

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

• エージェントに、音声を聞き、考え、割り込みにも対応させる必要がある場合 → deepgram-js-voice-agent

認証

require("dotenv").config();

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

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

リポジトリの例では require("../dist/cjs/index.js") を使用していますが、アプリケーションコードでは通常 @deepgram/sdk からインポートします。

クイックスタート — REST（一括処理）

examples/10-text-to-speech-single.ts より：

const data = await deepgramClient.speak.v1.audio.generate({
  text: "Hello, this is a test of Deepgram's text-to-speech API.",
  model: "aura-2-thalia-en",
  encoding: "linear16",
  container: "wav",
});

console.log("Audio generated successfully", data);

generate(...) は JSON ではなく BinaryResponse を返します。.stream()、.arrayBuffer()、.blob()、.bytes() の処理については、examples/25-binary-response.ts を参照してください。

クイックスタート — WebSocket（ストリーミング）

examples/11-text-to-speech-streaming.ts より：

const deepgramConnection = await deepgramClient.speak.v1.createConnection({
  model: "aura-2-thalia-en",
  encoding: "linear16",
});

deepgramConnection.on("message", (data) => {
  if (typeof data === "string" || data instanceof ArrayBuffer || data instanceof Blob) {
    console.log("Audio received");
  } else if (data.type === "Flushed") {
    deepgramConnection.close();
  }
});

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

deepgramConnection.sendText({ type: "Speak", text: "Hello from streaming TTS." });
deepgramConnection.sendFlush({ type: "Flush" });

主なパラメーター／API サーフェス

• REST と WSS：model、encoding、sample_rate、container、bit_rate、callback、callback_method、tag、mip_opt_out。
• REST レスポンスのサーフェス（examples/25-binary-response.ts）：response.stream()、response.arrayBuffer()、response.blob()、response.bytes()、response.bodyUsed。
• WSS クライアントメッセージ（src/api/resources/speak/resources/v1/client/Socket.ts）：sendText(...)、sendFlush(...)、sendClear(...)、sendClose(...)。
• WSS サーバーイベント：バイナリー音声ペイロードに加え、Metadata、Flushed、Cleared、Warning。

制限事項

Python SDK とは異なり、このリポジトリには手書きの TextBuilder ヘルパーは含まれていません。sendText(...) の前にトークンを段階的にバッファリングする場合は、アプリケーション層でそのヘルパーを実装してください。

API リファレンス（階層別）

1. リポジトリ内のリファレンス：REST については reference.md の Speak V1 Audio を参照してください。WSS の動作については src/CustomClient.ts および src/api/resources/speak/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/text-to-speech/speak-request
   • https://developers.deepgram.com/reference/text-to-speech/speak-streaming
   • https://developers.deepgram.com/docs/tts-models

注意点

1. REST は JSON ではなくバイナリーを返します。 結果はストリーミング／バイナリーボディーとして扱ってください。
2. カスタムクライアントのラッパーを使用してください。 src/CustomClient.ts はバイナリーの WebSocket 処理をパッチしています。生成されたソケットは JSON を過剰に前提としています。
3. createConnection() は遅延実行されます。 ハンドラーを登録してから connect() と waitForOpen() を呼び出してください。
4. テキストを送信した後に Flush を送信してください。 sendFlush({ type: "Flush" }) を呼び出さないと、音声の末尾がすぐに出力されない場合があります。
5. ストリーミングテキストは構造化 JSON です。 生の文字列ではなく、{ type: "Speak", text } を送信してください。
6. 音声ペイロードの形式はランタイムによって異なります。 同じハンドラーが string、ArrayBuffer、または Blob を受け取る場合があります。
7. 出力先に合ったエンコーディング、コンテナー、サンプルレートを選択してください。 形式が一致しないと、ノイズ、無音、または再生できないファイルが発生します。

このリポジトリ内のサンプルファイル

• examples/10-text-to-speech-single.ts
• examples/11-text-to-speech-streaming.ts
• examples/25-binary-response.ts

中核となる製品スキル

言語をまたいで Deepgram 製品の知識（統合された API リファレンス、ドキュメント検索、目的に特化した実行可能なレシピ、サードパーティ統合の例、MCP のセットアップ）を利用するには、中核スキルをインストールしてください：

npx skills add deepgram/skills

この SDK には、各言語の慣習に沿ったコードスキルが含まれています。deepgram/skills には、言語をまたいだ製品知識が含まれています（api、docs、recipes、examples、starters、setup-mcp を参照）。