Pythonで音声合成：音声をWAVファイルに保存する

Pythonで音声合成するには、原稿を音声モデルへ送り、返された音声を保存します。本記事ではCartesia Python SDKを使い、SonicでWAVファイルを生成します。

Python 3.9以降、インターネット接続、APIアクセスのあるCartesiaアカウントが必要です。以下の例はSDK 4.2.0を対象とします。¹ ホストされたAPIを呼び出すため、テキストは端末外に送信されます。オフラインでの合成が必要なら、ローカルの音声エンジンを使ってください。

Python SDKをインストールする

プロジェクトのディレクトリで仮想環境を作成します。

python -m venv .venv

macOSまたはLinuxでは、次で有効にします。

source .venv/bin/activate

Windows PowerShellでは、次を使います。

.venv\Scripts\Activate.ps1

続いて、本記事で使うバージョンをインストールします。

python -m pip install "cartesia==4.2.0"

システムでpythonではなくpython3を使っている場合は、そちらで環境を作成してください。SDKを固定すると、例のメソッド名を同じ状態に保てます。更新時はSDKのリリースノートを確認しましょう。

APIキーを設定する

Cartesia PlaygroundでAPIキーを作成し、音声合成に必要な権限を付与します。Pythonを実行するターミナルでキーを設定してください。

macOSまたはLinuxの場合：

export CARTESIA_API_KEY="your-api-key"

Windows PowerShellの場合：

$env:CARTESIA_API_KEY = "your-api-key"

your-api-keyを自分のキーに置き換えます。パスワードと同様に扱い、Gitへコミットしたり、公開ノートブックへ貼ったり、ブラウザーのコードに入れたりしないでください。デプロイするアプリケーションでは、サーバーのシークレット管理機能に保存します。流出したキーは取り消し、新しく作成してください。

WAVファイルを生成・保存する

次をspeak.pyとして保存します。原文の英語音声を生成するサンプルコードです。

import os
from pathlib import Path

from cartesia import Cartesia

api_key = os.environ.get("CARTESIA_API_KEY")
if not api_key:
    raise SystemExit("Set CARTESIA_API_KEY before running this script.")

output_path = Path("hello.wav")

with Cartesia(api_key=api_key) as client:
    response = client.tts.generate(
        model_id="sonic-latest",
        transcript="Hello from Python. Your first audio file is ready.",
        voice="e07c00bc-4134-4eae-9ea4-1a55fb45746b",
        output_format={
            "container": "wav",
            "encoding": "pcm_f32le",
            "sample_rate": 44100,
        },
    )
    response.write_to_file(output_path)

print(f"Saved audio to {output_path.resolve()}")

同じターミナルから実行します。

python speak.py

リクエストが成功したら、浮動小数点PCM WAVに対応したプレーヤーでhello.wavを開きます。スクリプトが絶対パスを表示するため、保存先を推測する必要はありません。音声を保存しますが、自動再生はしません。もう一度実行すると、hello.wavを上書きし、APIリクエストも再度行います。

リクエストはSDKで公開されている利用例に従っています。¹ 音声IDも、その例のものです。アカウントで利用できる別の音声IDに置き換えられます。

声、モデル、音声形式を選ぶ

transcriptはSonicに読み上げさせるテキストです。長い文書を送る前に、1文から始めましょう。APIに送信して差し支えない文章を使い、非公開の原稿をアプリケーションのログに記録しないようにします。

voiceは話す声を選びます。音声ジェネレーターで1文を試し、選んだ声のIDを指定してください。表示名は音声IDではありません。クローンした声を使う場合は、話者の声を利用する許可が必要です。

サンプルはSDKの文書と同じsonic-latestを使います。モデルのエイリアスは、インストールしたSDKとは独立して変わる場合があります。本番のテストを再現可能にするには、モデルのドキュメントから対応する特定のモデルIDを選び、音声IDとテスト原稿とともに記録してください。

出力形式は、音声ファイルを次のように指定します。

生のPCMにはWAVヘッダーがありません。拡張子を.wavに変えてもWAVファイルにはなりません。電話システムや別のサービスへ送る場合、生成前に必要なコンテナ、エンコーディング、サンプルレートを確認してください。

よくあるエラーを直す

問い合わせには、PythonとSDKのバージョン、ステータスコード、エラーとともに返されたリクエストIDを含めてください。APIキーや非公開のテキストは先に取り除きます。

ストリーミングを使う場面

WAV保存は、ナレーション、ボイスオーバー、連携の確認に役立ちます。会話アプリケーションでは、返答全体が完成する前に再生したり、LLMが生成するテキストを順に受け付けたりする必要があるでしょう。

その場合は、同じ環境にWebSocket対応をインストールします。

python -m pip install "cartesia[websockets]==4.2.0"

SDKのWebSocketによるストリーミング入力例から始めてください。¹ 再生、バッファリング、割り込み処理も必要です。届いたチャンクをディスクに書くだけでは、リアルタイムに話すアプリケーションにはなりません。

短い例が動いたら、実際のアプリケーションの文章に置き換えます。大量生成の前に、名前、数字、略語を聞いて確認しましょう。API料金を確認し、テスト結果とともにモデル・音声IDを残してください。