tktts_voicevox.py ライブラリ技術ドキュメント
ライブラリの機能や目的
tktts_voicevox.py は、PythonアプリケーションからVOICEVOXエンジンを介してテキストを音声合成するためのライブラリです。VOICEVOX REST APIと連携し、テキストを音声ファイル（WAV形式）として出力する機能を提供します。
主な目的と機能は以下の通りです。
VOICEVOXエンジンとの連携: VOICEVOXエンジンのREST API (
/speakers,/audio_query,/synthesis) を利用して、テキスト音声合成を行います。利用可能な話者の取得と解決: VOICEVOXエンジンで利用可能な話者情報（名前、スタイル、ID）を取得し、ユーザーが指定した話者名（部分一致含む）からVOICEVOXのspeaker IDを解決します。
テキスト音声合成: 指定されたテキストと話者IDに基づき、VOICEVOXエンジンで音声合成を実行し、結果をWAVファイルとして保存します。話速やピッチの調整も可能です。
対話形式のテキスト処理: 複数の話者による対話テキストを解析し、話者ごとに適切な音声合成を行い、個々の一時音声ファイルとして出力する機能を提供します。これにより、複雑な対話シナリオでの音声生成を容易にします。
依存関係チェック: 必要な非標準ライブラリ（
requests）がインストールされているかを起動時にチェックし、不足している場合はユーザーにインストール方法を案内して終了します。
本ライブラリは、VOICEVOXをバックエンドとするテキスト音声合成機能を、他のPythonプログラムに組み込むことを目的としています。
importする方法
tktts_voicevox.py ライブラリを他のPythonプログラムから利用するには、通常のPythonモジュールと同様に import 文を使用します。
import tktts_voicevox
あるいは、特定の関数のみをインポートすることも可能です。
from tktts_voicevox import speak, get_available_voices
必要な非標準ライブラリとインストール方法
このライブラリは、以下の非標準ライブラリに依存しています。
requests: HTTPリクエストを送信するために使用されます。VOICEVOXエンジンのREST APIとの通信に必須です。
これらのライブラリは、pip コマンドを使用してインストールできます。
pip install requests
また、このライブラリは tktts_base という別のライブラリから以下の関数をインポートしています。tktts_base も別途インストールまたは利用可能な状態にしておく必要がありますが、そのインストール方法はこのドキュメントの範囲外です。
apply_replacementsnormalize_speakersplit_dialogue
importできる変数と関数
変数
TTS_ENGINE_NAME: VOICEVOXエンジンの名前を示す文字列。常に'voicevox'です。DEFAULT_VOICEVOX_VOICE: デフォルトで使用されるVOICEVOXの話者名。初期値は"四国めたん"です。DEFAULT_ENDPOINT: VOICEVOXエンジンのREST APIエンドポイントのデフォルトURL。初期値は"http://127.0.0.1:50021"です。
関数
get_available_voices_info(endpoint=DEFAULT_ENDPOINT)
VOICEVOXエンジンから利用可能な話者（ボイススタイルを含む）の情報を取得します。
動作: 指定されたVOICEVOXエンドポイントの
/speakersAPIにGETリクエストを送信し、利用可能な話者の詳細情報を取得してリスト形式で返します。引数:
endpoint(str, オプション): VOICEVOX APIのエンドポイントURL。デフォルトはDEFAULT_ENDPOINTです。
戻り値:
list: 各要素が話者の名前、スタイル、IDを含む辞書であるリストです。 例:[{"name": "四国めたん", "style": "ノーマル", "id": 2}, ...]
get_available_voices(endpoint=DEFAULT_ENDPOINT)
利用可能な話者名を「話者名（スタイル名）」の形式で取得します。
動作:
get_available_voices_infoを呼び出して話者情報を取得し、ユーザーフレンドリーな形式の文字列リストに変換します。引数:
endpoint(str, オプション): VOICEVOX APIのエンドポイントURL。デフォルトはDEFAULT_ENDPOINTです。
戻り値:
listofstr: 利用可能な話者名とスタイルを組み合わせた文字列のリストです。 例:["四国めたん（ノーマル）", "ずんだもん（ノーマル）", ...]利用可能なボイスがない場合は
Falseを返します。
list_available_voices(endpoint=DEFAULT_ENDPOINT)
利用可能なVOICEVOXの話者をコンソールに出力します。
動作:
get_available_voices_infoを使用して話者情報を取得し、それぞれの話者の名前、スタイル、IDを整形して標準出力に表示します。引数:
endpoint(str, オプション): VOICEVOX APIのエンドポイントURL。デフォルトはDEFAULT_ENDPOINTです。
戻り値:
bool: 利用可能な話者がある場合はTrue、ない場合はFalseを返します。
resolve_speaker_id(speaker_name, endpoint=DEFAULT_ENDPOINT, speakers_dict = None)
与えられた話者名（フルネームまたは部分文字列）から、最初に一致したVOICEVOXのspeaker IDを解決します。
動作: 指定された
speaker_nameが、利用可能な話者名またはスタイル名に含まれるかを検索します。大文字小文字は区別されません。speakers_dictが提供されていればそれを使用し、なければget_available_voices_infoを呼び出して取得します。normalize_speaker関数を使用してspeaker_nameを正規化します。引数:
speaker_name(str): 検索する話者名またはスタイル名。endpoint(str, オプション): VOICEVOX APIのエンドポイントURL。デフォルトはDEFAULT_ENDPOINTです。speakers_dict(list of dict, オプション): 既に取得済みの話者情報辞書のリスト。API呼び出しの最適化に使用されます。
戻り値:
(list, int):(speakers_dict, speaker_id)のタプル。speakers_dictは更新された（または既存の）話者情報リスト、speaker_idは見つかった話者のVOICEVOX IDです。
例外:
ValueError: 指定された話者が見つからない場合に発生します。
speak(outfile, text, voice, speak_rate = None, speak_pitch = None, endpoint = DEFAULT_ENDPOINT)
指定されたテキストをVOICEVOXで音声合成し、ファイルに保存します。
動作:
VOICEVOXの
/audio_queryAPIを呼び出し、音声合成クエリを生成します。speak_rateやspeak_pitchが指定されていれば、クエリにそれらを適用します。VOICEVOXの
/synthesisAPIを呼び出し、音声データを生成します。生成された音声データをバイナリ形式で指定された
outfileに書き込みます。
引数:
outfile(str): 音声データを保存するファイルのパス。text(str): 音声合成するテキスト。voice(int): VOICEVOXのspeaker ID。speak_rate(float, オプション): 話速のスケールファクター。デフォルトはNone（VOICEVOXのデフォルトを使用）。speak_pitch(float, オプション): ピッチのスケールファクター。デフォルトはNone（VOICEVOXのデフォルトを使用）。endpoint(str, オプション): VOICEVOX APIのエンドポイントURL。デフォルトはDEFAULT_ENDPOINTです。
戻り値:
str: 成功した場合、出力ファイルのパスを返します。None: 音声合成またはファイル保存に失敗した場合。
speak_dialogue(dialogue, replacements, target_voices, speakers = {}, temp_dir=".", outfile=None, ext="wav", endpoint=DEFAULT_ENDPOINT, cfg = None)
対話形式のテキストを解析し、複数の話者で音声合成を行い、一時ファイルに保存します。
動作:
入力された対話テキストのリストを反復処理し、
split_dialogueを使用して個々のセリフと話者に分割します。replacementsがあれば、apply_replacementsを使用してテキストを置換します。target_voicesが文字列型の場合、すべてのセリフにその話者を強制的に適用します。resolve_speaker_idを使用して話者名からVOICEVOXのspeaker IDを解決します。speak関数を呼び出し、各セリフを個々の一時音声ファイルとしてtemp_dirに保存します。cfgオブジェクトがあれば、そこからfspeak_rate,fspeak_pitch,monologueの設定を読み込み、話速やピッチの調整、モノローグモードの判断に使用します。
引数:
dialogue(list of str): 対話テキストのリスト。replacements(dict): テキスト置換ルールを定義する辞書。tktts_base.apply_replacementsに渡されます。target_voices(str or list): 音声合成に使用する話者を指定します。文字列の場合、全てのセリフがその話者で合成されます。リストの場合、split_dialogueが話者を決定します。speakers(dict, オプション): 話者名のマッピング辞書。tktts_base.split_dialogueに渡されます。デフォルトは空の辞書です。temp_dir(str, オプション): 生成される一時音声ファイルを保存するディレクトリパス。デフォルトは"."(カレントディレクトリ) です。outfile(str, オプション): 最終的な結合ファイルパス。現在の実装では一時ファイルのリストを返すため、直接的な使用は限定的です。デフォルトはNoneです。ext(str, オプション): 出力音声ファイルの拡張子（例:"wav"）。デフォルトは"wav"です。endpoint(str, オプション): VOICEVOX APIのエンドポイントURL。デフォルトはDEFAULT_ENDPOINTです。cfg(object, オプション): 設定オブジェクト。fspeak_rate,fspeak_pitch,monologueなどの属性を持つことが期待されます。
戻り値:
(bool, list):(success, tmpfiles)のタプル。successは処理が成功したかどうかを示すブール値、tmpfilesは生成された一時音声ファイルのパスのリストです。
main scriptとして実行したときの動作
tktts_voicevox.py には if __name__ == "__main__": ブロックが存在しないため、このファイルを直接Pythonインタプリタで実行しても、特別なスクリプトとしての動作は定義されていません。
ただし、ファイルの冒頭で requests ライブラリの存在チェックが行われます。もし requests がインストールされていない状態でこのファイルを直接実行したり、他のスクリプトからインポートしたりしようとすると、以下のエラーメッセージが表示され、ユーザーの入力待ち（Press ENTER to terminate>>）の後にプログラムが終了します。
Error: Missing libraries:
requests
install: pip install requests
Press ENTER to terminate>>
これは、ライブラリの依存関係を明示し、不足している場合に適切な指示をユーザーに提供するための仕組みです。