リアルタイム Text-to-Speech クイックスタート

Cartesia WebSocket APIを使用すると、テキスト入力と音声出力を同時にストリーミングできます。これは、LLMから逐次テキストが生成される場合のボイスエージェントなどのリアルタイムユースケースに最適です。テキストをチャンクに分けてCartesiaにストリーミングし、音声チャンクをリアルタイムで受け取ります。これは、LLMからのように逐次テキストが生成される場合に理想的です。

前提条件

Cartesia APIキー。こちらで作成し、.bashrc または .zshrc に追加してください:
```
export CARTESIA_API_KEY=<your api key here>
```
ブラウザからCartesia APIにアクセスする際は、APIキーを安全に保つため、認証には短期間有効なアクセストークンを使用してください。クライアントアプリケーションを認証するを参照してください。
ffplay(FFmpegの一部)。音声出力を再生するために使用されます: オペレーティングシステム用のFFmpeg実行可能パッケージを FFmpegダウンロードページからダウンロードしてください。
言語ランタイムとパッケージマネージャー:
- Python: Python 3 と pip
- JavaScript: Node.js(npmを含む)

テキストをストリーミングして音声を再生する

Python
TypeScript

クライアントライブラリをインストールする

pip install 'cartesia[websockets]'

詳細は Cartesia Pythonクライアントライブラリを参照してください。

WebSocket経由でテキストをストリーミングする

realtime-tts.py

from cartesia import Cartesia
import subprocess
import os

client = Cartesia(api_key=os.getenv("CARTESIA_API_KEY"))

print("Starting ffplay to play streaming audio output...")
player = subprocess.Popen(
    ["ffplay", "-f", "f32le", "-ar", "44100", "-probesize", "32", "-analyzeduration", "0", "-nodisp", "-autoexit", "-loglevel", "quiet", "-"],
    stdin=subprocess.PIPE,
    bufsize=0,
)

print("Connecting to Cartesia via websockets...")
with client.tts.websocket_connect() as connection:
    ctx = connection.context(
        model_id="sonic-3.5",
        voice={"mode": "id", "id": "f786b574-daa5-4673-aa0c-cbe3e8534c02"},
        output_format={
            "container": "raw",
            "encoding": "pcm_f32le",
            "sample_rate": 44100,
        },
    )

    print("Sending chunked text input...")
    transcript_chunks = ["Hi there! ", "Welcome to ", "Cartesia Sonic."]
    for part in transcript_chunks:
        ctx.push(part)

    ctx.no_more_inputs()

    for response in ctx.receive():
        if response.type == "chunk" and response.audio:
            print(f"Received audio chunk ({len(response.audio)} bytes)")
            # Here we pipe audio to ffplay. In a production app you might play audio in
            # a client, or forward it to another service, eg, a telephony provider.
            player.stdin.write(response.audio)
        elif response.type == "done":
            break

player.stdin.close()
player.wait()

クイックスタートを実行する

python3 realtime-tts.py

これにより、テキスト入力がCartesiaにストリーミングされ、ffplay を使用してストリーミング音声出力が再生されます。(デバイスの音量がオンになっていることを確認してください!)

クライアントライブラリをインストールする

npm init -y
npm pkg set type=module
npm install @cartesia/cartesia-js ws
npm install --save-dev tsx typescript @types/node

ws パッケージはNode.jsランタイムでのみ必要です。ブラウザでは ws パッケージをインストールしないでください — ネイティブのWebSocket APIで十分です。

詳細は Cartesia JavaScriptクライアントライブラリを参照してください。

WebSocket経由でテキストをストリーミングする

realtime-tts.ts という名前のファイルを作成し、以下のコードを記述します。コードの説明は下記にあります。

realtime-tts.ts

import Cartesia from "@cartesia/cartesia-js";
import { spawn } from "child_process";

const apiKey = process.env["CARTESIA_API_KEY"];
if (!apiKey) {
  throw new Error("Missing CARTESIA_API_KEY");
}

const client = new Cartesia({ apiKey });

console.log("Starting ffplay to play streaming audio output...");
const { stdin } = spawn("ffplay", ["-f", "f32le", "-ar", "44100", "-probesize", "32", "-analyzeduration", "0", "-nodisp", "-autoexit", "-loglevel", "quiet", "-"], {
  stdio: ["pipe", "ignore", "ignore"],
});
if (!stdin) {
  throw new Error("ffplay stdin not available");
}

console.log("Connecting to Cartesia via websockets...");
const ws = await client.tts.websocket();

const ctx = ws.context({
  model_id: "sonic-3.5",
  voice: { mode: "id", id: "f786b574-daa5-4673-aa0c-cbe3e8534c02" },
  output_format: { container: "raw", encoding: "pcm_f32le", sample_rate: 44100 },
});

console.log("Sending chunked text input...");
const transcriptChunks = ["Hi there! ", "Welcome to ", "Cartesia Sonic."];
for (const part of transcriptChunks) {
  await ctx.push({ transcript: part });
}

await ctx.no_more_inputs();

for await (const event of ctx.receive()) {
  if (event.type === "chunk" && event.audio) {
    console.log(`Received audio chunk (${event.audio.length} bytes)`);
    // Here we pipe audio to ffplay. In a production app you might play audio in
    // a client, or forward it to another service, eg, a telephony provider.
    stdin.write(event.audio);
  } else if (event.type === "done") {
    break;
  }
}
stdin.end();
ws.close();

クイックスタートを実行する

npx tsx realtime-tts.ts

仕組み

WebSocket接続は複数の コンテキスト を管理でき、各コンテキストは全二重の連続したストリームです。テキストチャンクをプッシュし、生成された音声チャンクをリアルタイムで受け取ります。これは、LLMからリアルタイムでテキストを生成する場合にうまく機能します: CartesiaのTTSシステムはコンテキスト履歴を保持し、新しいチャンクを順次そこに追加していきます。これにより、生成された音声がトーンと韻律で連続性と一貫性を保ち、完全なトランスクリプトが準備できるのを待つ必要がないため、レイテンシを最小限に抑えます。要約すると、WebSocket接続を確立した後、コードは以下のことを行います:

context() で コンテキストを作成 します。
push() で逐次 テキストをプッシュ します。各呼び出しは continue: true でチャンクを送信し、さらにテキストが続くことをモデルに伝えます。詳細は continuations を参照してください。
no_more_inputs() で 完了を通知 します。これは continue: false を送信して、これ以上テキストが来ないことをモデルに伝えます。
生成された 音声チャンクを受信 します。

これは、リアルタイムLLM WebSocket APIに似たストリーミングパターンを使用しています: テキストフラグメントが到着するたびに送信し、生成された出力(この場合は音声チャンク)を逐次受信します。

次のステップ

プレイグラウンドでボイスを選ぶ

音声を選択するか、自分の音声を複製して、音声IDをこのクイックスタートにコピーします。

WebSocketリクエストパラメータを調整する

voice、model_id、または output_format を変更し、再実行して出力品質と挙動を比較します。

Continuationsを使用して入力をストリーミングする

チャンクをまたいだ自然な流れを保ちつつ逐次テキストを送信し、長文やLLM駆動の音声をよりスムーズに生成します。

​前提条件

​テキストをストリーミングして音声を再生する

​仕組み

​次のステップ

プレイグラウンドでボイスを選ぶ

WebSocketリクエストパラメータを調整する

Continuationsを使用して入力をストリーミングする

前提条件

テキストをストリーミングして音声を再生する

仕組み

次のステップ