tktts.py Documentation
ライブラリの機能や目的
tktts.pyは、多様なテキスト読み上げ(TTS)エンジンを統一されたインターフェースで利用するためのPythonライブラリです。複数のTTSバックエンド(pyttsx3、Windows標準TTS、VOICEVOX、Qwen-TTS、Irodori TTS、AquestalkPlayer、OpenAI、ElevenLabs、Gemini、Edge-TTSなど)を抽象化し、テキストからの音声生成、結合、保存、または直接再生を容易に行えるように設計されています。
主な目的は以下の通りです。
TTSエンジンの抽象化: ユーザーは異なるTTSエンジンの複雑なAPIや設定を意識することなく、一貫した方法で音声生成タスクを実行できます。
柔軟なテキスト入力: クリップボードまたは指定されたファイルからテキストを読み込み、対話形式または独話形式のテキストを処理します。
音声のカスタマイズ: 話者ごとの音声設定、読み上げ速度、一時停止間隔、および特定のエンジンの詳細設定(APIキー、エンドポイント、モデルIDなど)をサポートします。
音声ファイルの結合と管理: 生成された短い音声ファイルを一時ディレクトリに保存し、結合して単一の出力ファイルとしてエクスポートします。不要な一時ファイルは自動的にクリーンアップされます。
安全なバックエンドの読み込み: 各TTSエンジンはオプションの依存関係として扱われ、必要なライブラリがインストールされていない場合でも、エラーでプログラム全体が停止することなく、利用可能なエンジンのみが登録されます。
このライブラリを使用することで、開発者はTTSエンジンの選択や切り替え、テキストの事前処理、音声の結合といった煩雑な作業から解放され、アプリケーションに簡単に音声機能を組み込むことができます。
importする方法
このライブラリを他のPythonプログラムから利用するには、標準のimport文を使用します。
import tktts
# tkTTSクラスのインスタンス化
# 設定はSimpleNamespaceオブジェクトとして渡すことができます。
# 例: config = SimpleNamespace(tts="voicevox", endpoint="http://localhost:50021")
tts_instance = tktts.tkTTS(tts_name="voicevox", config=None)
# 利用可能なTTSエンジンのリストを取得
available_engines = tktts.get_available_engines()
print(f"利用可能なTTSエンジン: {available_engines}")
# tkTTSインスタンスを通じて機能を利用
tts_instance.set_engine("pyttsx3")
print(f"現在のエンジン: {tts_instance.get_tts_name()}")
必要な非標準ライブラリとインストール方法
tktts.pyは、その機能の一部としていくつかの非標準ライブラリに依存しています。これらは大きく「コアライブラリ」と「オプションのTTSバックエンドライブラリ」に分けられます。
コアライブラリ(必須)
これらのライブラリは、tktts.pyが動作するために必須です。これらがインストールされていない場合、ライブラリのインポート時にSystemExitが発生します。
pydub: 音声ファイルの処理(結合、フォーマット変換など)に使用されます。pyperclip: クリップボードからのテキスト読み込みに使用されます。chardet: テキストファイルのエンコードを自動検出するために使用されます。
インストール方法:
pip install pydub pyperclip chardet
FFmpeg (必須)
pydubがMP3などの音声ファイルを処理するために、FFmpegという外部ツールが必要です。FFmpegはPythonライブラリではなく、システムにインストールし、その実行ファイルへのパスをシステムのPATH環境変数に設定する必要があります。
インストール方法:
FFmpegの公式サイト (https://ffmpeg.org/download.html) から、お使いのOSに合ったバイナリをダウンロードします。
ダウンロードしたファイルを解凍し、
ffmpeg.exe(Windowsの場合)やffmpeg(macOS/Linuxの場合)が含まれるディレクトリをシステムのPATH環境変数に追加します。
オプションのTTSバックエンドライブラリ
tktts.pyは、様々なTTSエンジンをサポートしていますが、各エンジンの機能を利用するためには、それぞれのバックエンドライブラリを個別にインストールする必要があります。これらは必須ではなく、インストールされていないバックエンドは単に利用不可として扱われます。
TTSエンジン名 |
Pythonライブラリ名 |
インストールコマンド例 |
|---|---|---|
|
|
|
|
|
|
|
(外部プロセス/API) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(外部ツール) |
(別途AquesTalkPlayerのインストールとパス設定が必要) |
これらのライブラリは、必要なエンジンを使用する場合にのみインストールしてください。
importできる変数と関数
変数
CORE_LIBS:説明:
pydub,pyperclip,chardetといった、tktts.pyの動作に必須のコアライブラリ名を格納する文字列のリスト。型:
list[str]
TTS_ENGINES:説明: サポートされている全てのTTSエンジンとその設定を定義する辞書。キーはエンジンの名前(例:
"pyttsx3","voicevox")で、値は以下の情報を含む辞書です。"engine": 対応するTTSバックエンドモジュール(利用可能な場合)。"default_voice": そのエンジンのデフォルトの音声名。"ext": 生成される音声ファイルのデフォルト拡張子(例:"wav","mp3")。"direct_playback": 音声生成後に直接再生をサポートするかどうかを示すブール値。
型:
dict[str, dict[str, Any]]
default_pyttsx3_voice,default_winrt_voice,default_voicevox_voice, ...:説明: 各TTSエンジンのデフォルトの音声名を保持する文字列変数。
TTS_ENGINES辞書で参照されます。
関数
check_ffmpeg_available() -> bool:動作: システムのPATH環境変数に
ffmpegとffprobeの実行ファイルが存在するかどうかを確認します。引数: なし
戻り値:
ffmpegが見つかった場合はTrue、そうでない場合はFalseを返します。ffprobeが見つからない場合は警告が表示されます。
_safe_import(module_name: str, dependency: str | None = None) -> ModuleType | None:動作: 指定されたモジュールを安全にインポートしようとします。オプションの依存関係が指定されており、それがインストールされていない場合、またはインポート中に
SystemExitやその他の例外が発生した場合は、警告を表示してNoneを返します。引数:
module_name(str): インポートするモジュールの名前。dependency(str | None): モジュールが依存する非標準ライブラリの名前。この依存関係がインストールされていない場合、モジュールはインポートされません。
戻り値: インポートに成功した場合はモジュールオブジェクト、失敗した場合は
None。
get_available_engines(available_only: bool = True) -> list[str]:動作:
TTS_ENGINESに登録されているTTSエンジンの名前のリストを返します。引数:
available_only(bool):Trueの場合、実際にインポート可能で利用できるエンジンのみを返します。Falseの場合、登録されている全てのエンジン名を返します。
戻り値: 利用可能な(または登録されている全ての)TTSエンジン名のリスト。
_supported_kwargs(func: Callable, kwargs: dict) -> dict:動作: 指定された関数
funcが受け入れ可能なキーワード引数のみをkwargs辞書から抽出し、新しい辞書として返します。関数が可変キーワード引数(**kwargs)を受け入れる場合は、全ての引数をそのまま返します。引数:
func(Callable): 引数をチェックする関数。kwargs(dict): フィルタリング対象のキーワード引数辞書。
戻り値:
funcが受け入れ可能なキーワード引数のみを含む辞書。
_call_backend(func: Callable, **kwargs) -> Any:動作:
_supported_kwargsを使用して関数に渡すキーワード引数をフィルタリングし、その関数を実行します。引数:
func(Callable): 呼び出す関数。**kwargs:funcに渡されるキーワード引数。
戻り値:
funcの実行結果。
apply_replacements(text: str, replacements: dict | None) -> str:動作: 指定された置換辞書
replacements(キーが正規表現、値が置換文字列)を使用して、テキスト内で大文字小文字を無視して置換を実行します。引数:
text(str): 置換を適用する元のテキスト。replacements(dict | None): 置換ルールを含む辞書。
戻り値: 置換が適用されたテキスト。
load_text(input_path: str, monologue: bool = False, wait_for_clipboard: bool = True) -> list[tuple[str | None, str]] | None:動作: 入力元(
"clip"またはファイルパス)からテキストを読み込み、(speaker, text)のリストとして返します。ファイルの場合はエンコーディングを自動検出します。引数:
input_path(str): テキストの入力元。"clip"を指定するとクリップボードから読み込みます。monologue(bool):Trueの場合、全ての行を独話(話者None)として処理します。Falseの場合、行をカンマで分割して(speaker, text)形式として解釈します。wait_for_clipboard(bool):input_pathが"clip"の場合、ユーザーがクリップボードにコピーするのを待つかどうか。
戻り値:
(speaker, text)のタプルリスト、またはエラー発生時にNone。
create_temp_dir(temp_dir: str) -> str:動作: 指定されたパスに一時ディレクトリを作成します(既に存在する場合は何もしません)。
引数:
temp_dir(str): 作成する一時ディレクトリのパス。
戻り値: 作成された一時ディレクトリのパス。
get_speaker_dict(tts_engine: str, dialogue: list[tuple[str | None, str]] | None, voices: str | None, default_voicevox_voice: str = "四国めたん", ...) -> dict | None:動作: 対話リストとユーザーが指定した音声設定に基づいて、話者名と使用する音声名のマッピング辞書を作成します。
引数:
tts_engine(str): 使用するTTSエンジンの名前。dialogue(list):(speaker, text)形式の対話リスト。voices(str | None): ユーザーが指定した音声設定(セミコロン区切り)。default_voicevox_voice,default_pyttsx3_voice, ...: 各エンジンのデフォルト音声名。
戻り値: 話者名から音声名へのマッピング辞書、またはエラー発生時に
None。
get_tts(tts_engine: str) -> ModuleType | None:動作: 指定されたTTSエンジン名のモジュールオブジェクトを返します。エンジンが利用できない場合はエラーメッセージを表示し
Noneを返します。引数:
tts_engine(str): 取得するTTSエンジンの名前。
戻り値: TTSバックエンドモジュール、または
None。
get_available_voices_info(tts_engine: str, endpoint: str | None = None, api_key: str | None = None) -> Any:動作: 指定されたTTSエンジンが提供する利用可能な音声の詳細情報を取得します。バックエンドモジュールに
get_available_voices_info関数がある場合のみ動作します。引数:
tts_engine(str): TTSエンジンの名前。endpoint(str | None): APIベースのTTSエンジンのエンドポイントURL。api_key(str | None): APIベースのTTSエンジンのAPIキー。
戻り値: 音声情報のリストまたは辞書、または
None。
get_available_voices(tts_engine: str, endpoint: str | None = None, api_key: str | None = None) -> list[str] | None:動作: 指定されたTTSエンジンが提供する利用可能な音声名のリストを取得します。バックエンドモジュールに
get_available_voices関数がある場合のみ動作します。引数:
tts_engine(str): TTSエンジンの名前。endpoint(str | None): APIベースのTTSエンジンのエンドポイントURL。api_key(str | None): APIベースのTTSエンジンのAPIキー。
戻り値: 利用可能な音声名のリスト、または
None。
list_available_voices(tts_engine: str, endpoint: str | None = None, api_key: str | None = None) -> bool:動作: 指定されたTTSエンジンが提供する利用可能な音声名をコンソールに出力します。バックエンドモジュールに
list_available_voices関数がある場合のみ動作します。引数:
tts_engine(str): TTSエンジンの名前。endpoint(str | None): APIベースのTTSエンジンのエンドポイントURL。api_key(str | None): APIベースのTTSエンジンのAPIキー。
戻り値: 処理が成功した場合は
True、失敗した場合はFalse。
normalize_speaker(speaker: str | None, tts_engine: str | None = None) -> str | None:動作: 話者ラベルを正規化します。
"話者(スタイル)"のような形式からスタイル部分を除去します。引数:
speaker(str | None): 正規化する話者名。tts_engine(str | None): (現在未使用だが将来の互換性のため残されている)
戻り値: 正規化された話者名、または
None。
parse_kv_string(kv_string: str, keys: list = [], allow_no_key_kv_string: bool = False) -> dict:動作:
"key=val;key=val"形式の文字列を辞書に変換します。key=がない場合は、keysリストの要素または整数インデックスをキーとして使用します。引数:
kv_string(str): 解析するキーと値のペア文字列。keys(list):key=がない場合に順次使用するキーのリスト。allow_no_key_kv_string(bool):key=がない形式を許可するかどうか。
戻り値: 解析結果の辞書。
_get_attr(args: SimpleNamespace | None, name: str, default: Any = None) -> Any:動作:
SimpleNamespaceオブジェクトから属性を安全に取得します。オブジェクトがNoneの場合や属性が存在しない場合はデフォルト値を返します。引数:
args(SimpleNamespace | None): 属性を取得するオブジェクト。name(str): 取得する属性の名前。default(Any): 属性が見つからない場合に返すデフォルト値。
戻り値: 取得した属性の値、またはデフォルト値。
_effective_pyttsx3_rate(args: SimpleNamespace) -> int:動作:
pyttsx3エンジンの実際の読み上げ速度を計算します。ベース速度と倍率を考慮します。引数:
args(SimpleNamespace): 設定を含むオブジェクト。speak_rateとfspeak_rate属性を使用。
戻り値: 最終的な読み上げ速度(整数)。
_effective_winrt_rate(args: SimpleNamespace) -> float | int:動作: WinRTエンジンの実際の読み上げ速度を計算します。
引数:
args(SimpleNamespace): 設定を含むオブジェクト。fspeak_rateとspeak_rate属性を使用。
戻り値: 最終的な読み上げ速度。
_elevenlabs_voice_settings(args: SimpleNamespace) -> dict | None:動作:
ElevenLabsエンジンに渡す音声設定(stability, similarity_boostなど)をargsオブジェクトから抽出して辞書として返します。引数:
args(SimpleNamespace): 設定を含むオブジェクト。elevenlabs_voice_settingsなどの属性を使用。
戻り値:
ElevenLabsの音声設定辞書、またはNone。
_infer_output_format(outfile: str, requested_format: str | None, default_format: str) -> str:動作: 出力ファイルパス、要求されたフォーマット、デフォルトフォーマットに基づいて、最終的な出力音声フォーマットを推測します。
引数:
outfile(str): 出力ファイルパス。requested_format(str | None): ユーザーが要求した出力フォーマット。default_format(str): エンジンが提供するデフォルトのフォーマット。
戻り値: 推測された出力フォーマット(例:
"wav","mp3")。
speak_dialogue(args: SimpleNamespace, dialogue: list[tuple[str | None, str]], voice_map: dict | str | None = None, speakers: dict | None = None, replacements: dict | None = None, endpoint: str | None = None, api_key: str | None = None, output_format: str | None = None) -> str | bool:動作: 選択されたTTSエンジンを使用して、対話テキストから音声ファイルを生成し、結合し、保存または直接再生します。
引数:
args(SimpleNamespace):tts、outfile、temp_dirなどの主要な設定を含むオブジェクト。dialogue(list):(speaker, text)形式の対話リスト。voice_map(dict | str | None): 話者から音声へのマッピング。文字列の場合、voices引数として扱われます。speakers(dict | None): (現在未使用だが将来の互換性のため残されている)replacements(dict | None): テキストの置換ルール。endpoint(str | None): APIベースのTTSエンジンのエンドポイントURL。api_key(str | None): APIベースのTTSエンジンのAPIキー。output_format(str | None): 希望する出力音声フォーマット。
戻り値: 出力されたファイルパス(保存モードの場合)、または処理が成功した場合は
True、失敗した場合はFalse。
クラス
tkTTS クラス
tkTTSクラスは、tktts.pyライブラリの中心的なインターフェースを提供し、TTSエンジンの設定、管理、および音声生成をオブジェクト指向的に扱えるようにします。
__init__(self, tts_name: str | None = None, config: SimpleNamespace | None = None) -> None:動作:
tkTTSインスタンスを初期化します。指定されたTTSエンジン名と設定(SimpleNamespaceオブジェクト)に基づいて、TTSバックエンドを準備します。引数:
tts_name(str | None): 初期設定するTTSエンジンの名前。config(SimpleNamespace | None): APIキー、エンドポイントなどの設定を格納するオブジェクト。
_default_endpoint(self) -> str | None:動作: 現在設定されているTTSエンジンに基づいて、デフォルトのエンドポイントURLを返します。
引数: なし
戻り値: エンドポイントURL、または
None。
set_engine(self, tts_name: str) -> None:動作: 現在のTTSエンジンを設定または変更します。
引数:
tts_name(str): 新しく設定するTTSエンジンの名前。
戻り値: なし
set_endpoint(self, endpoint: str) -> None:動作: APIベースのTTSエンジンのエンドポイントURLを設定します。
引数:
endpoint(str): エンドポイントURL。
戻り値: なし
set_aquestalk_path(self, aquestalk_path: str) -> None:動作: AquestalkPlayerの実行ファイルパスを設定します。
引数:
aquestalk_path(str): AquestalkPlayerのパス。
戻り値: なし
set_api_key(self, api_key: str) -> None:動作: APIベースのTTSエンジンのAPIキーを設定します。
引数:
api_key(str): APIキー。
戻り値: なし
get_tts_name(self, tts_name: str | None = None) -> str | None:動作: 現在設定されているTTSエンジンの名前、または引数で指定されたTTSエンジンの名前を返します。
引数:
tts_name(str | None): 取得するTTSエンジンの名前。指定しない場合はインスタンスの現在のエンジン名。
戻り値: TTSエンジンの名前。
get_default_voice(self, tts_name: str | None = None) -> str | None:動作: 指定されたTTSエンジンのデフォルトの音声名を返します。
引数:
tts_name(str | None): デフォルト音声を取得するTTSエンジンの名前。指定しない場合はインスタンスの現在のエンジン名。
戻り値: デフォルトの音声名、または
None。
normalize_speaker(self, speaker: str | None, tts_name: str | None = None) -> str | None:動作: 親モジュールの
normalize_speaker関数を呼び出して話者ラベルを正規化します。引数:
speaker(str | None): 正規化する話者名。tts_name(str | None): (現在未使用だが将来の互換性のため残されている)
戻り値: 正規化された話者名、または
None。
get_available_voices_info(self, tts_name: str | None = None, endpoint: str | None = None, api_key: str | None = None) -> Any:動作: 親モジュールの
get_available_voices_info関数を呼び出して、利用可能な音声の詳細情報を取得します。引数:
tts_name(str | None): 情報を取得するTTSエンジンの名前。endpoint(str | None): APIベースのTTSエンジンのエンドポイントURL。api_key(str | None): APIキー。
戻り値: 音声情報、または
None。
get_available_voices(self, tts_name: str | None = None, endpoint: str | None = None, api_key: str | None = None) -> list[str] | None:動作: 親モジュールの
get_available_voices関数を呼び出して、利用可能な音声名のリストを取得します。引数:
tts_name(str | None): リストを取得するTTSエンジンの名前。endpoint(str | None): APIベースのTTSエンジンのエンドポイントURL。api_key(str | None): APIキー。
戻り値: 音声名のリスト、または
None。
list_available_voices(self, tts_name: str | None = None, endpoint: str | None = None, api_key: str | None = None) -> bool:動作: 親モジュールの
list_available_voices関数を呼び出して、利用可能な音声名をコンソールに出力します。引数:
tts_name(str | None): リストを出力するTTSエンジンの名前。endpoint(str | None): APIベースのTTSエンジンのエンドポイントURL。api_key(str | None): APIキー。
戻り値: 処理が成功した場合は
True、失敗した場合はFalse。
show_voice_map(self, infile: str, voices: str, VOICE_MAPS: dict, is_monologue: bool, tts_name: str | None = None, endpoint: str | None = None) -> bool:動作: 指定された入力ファイルから話者を解析し、現在の音声マッピングを表示します。デバッグや設定確認に役立ちます。
引数:
infile(str): 入力ファイルパス。voices(str): ユーザーが指定した音声設定文字列。VOICE_MAPS(dict): 全TTSエンジンに対する既存の音声マッピング。is_monologue(bool): 独話モードかどうか。tts_name(str | None): 使用するTTSエンジンの名前。endpoint(str | None): エンドポイントURL。
戻り値: 処理が成功した場合は
True、失敗した場合はFalse。
load_text(self, input_path: str, monologue: bool = False, wait_for_clipboard: bool = True) -> list[tuple[str | None, str]] | None:動作: 親モジュールの
load_text関数を呼び出すラッパーです。引数:
load_text関数と同じ。戻り値:
load_text関数の戻り値。
get_speakers_from_dialogue(self, dialogue: list[tuple[str | None, str]]) -> list[str | None]:動作: 対話リストから一意な話者のリストを抽出します。
引数:
dialogue(list):(speaker, text)形式の対話リスト。
戻り値: 一意な話者名のリスト。
parse_kv_string(self, kv_string: str, keys: list = [], allow_no_key_kv_string: bool = False) -> dict:動作: 親モジュールの
parse_kv_string関数を呼び出すラッパーです。引数:
parse_kv_string関数と同じ。戻り値:
parse_kv_string関数の戻り値。
update_voice_map(self, voice_map: dict = {}, voices: str = "", speakers: list = {}) -> dict:動作: 既存の音声マッピングを更新し、指定された音声設定や話者リストを適用します。
引数:
voice_map(dict): 更新する既存の音声マッピング辞書。voices(str): ユーザーが指定した音声設定文字列。speakers(list): 読み上げファイルから抽出された話者のリスト。
戻り値: 更新された音声マッピング辞書。
speak_dialogue(self, dialogue: list[tuple[str | None, str]] | None = None, voice_map: dict | str | None = None, speakers: dict | None = None, replacements: dict | None = None, endpoint: str | None = None, api_key: str | None = None, output_format: str | None = None, config: SimpleNamespace | None = None) -> str | bool:動作: 親モジュールの
speak_dialogue関数を呼び出すラッパーです。インスタンスの設定値(tts_name,endpoint,api_keyなど)を自動的にspeak_dialogueに渡します。引数:
speak_dialogue関数と同じ、またはインスタンスから引き継がれる。戻り値:
speak_dialogue関数の戻り値。
main scriptとして実行したときの動作
tktts.pyは、if __name__ == "__main__":ブロックを持たないため、単体でPythonスクリプトとして直接実行された場合でも、特定のユーザーインターフェースやコマンドラインツールとしての動作は提供されません。
しかし、モジュールがロードされる際に、冒頭の初期化処理が実行されます。この処理には以下のステップが含まれます。
コアライブラリのチェック:
pydub,pyperclip,chardetがシステムにインストールされているかを確認します。いずれかのライブラリが見つからない場合、エラーメッセージを表示し、SystemExit(1)でプログラムを終了します。Error: Missing core libraries: pydub, pyperclip, chardet install: pip install pydub pyperclip chardet MP3などを扱う場合は FFmpeg もPATHに設定してください。
FFmpegのチェック:
ffmpegとffprobeの実行ファイルがシステムのPATH環境変数に存在するかを確認します。ffmpegが見つからない場合、エラーメッセージを表示し、SystemExit(1)でプログラムを終了します。ffprobeが見つからない場合は警告が表示されますが、処理は継続します。❌ ffmpeg が見つかりません。 tktts.py: ffmpeg が見つかりません
オプションTTSバックエンドの安全なインポート:
tktts_pyttsx3,tktts_winrtなどの各TTSバックエンドモジュールを_safe_import関数を使って読み込もうとします。この際、各バックエンドが依存するライブラリがインストールされているかどうかもチェックされます。依存ライブラリが見つからない場合や、インポート中にエラーが発生した場合は、そのバックエンドは無効化され、警告メッセージが表示されますが、プログラムは停止しません。
したがって、tktts.pyを直接実行することは、主に初期セットアップや依存関係の確認の目的で使用され、ライブラリとしての機能を提供するのみで、インタラクティブな操作やコマンドライン引数を受け取るような動作は行いません。 通常は他のPythonスクリプトからimportして利用されることを想定しています。