tktts プログラム仕様
tkttsモジュール
このモジュールは、複数のTTS(Text-to-Speech)エンジンを統合し、テキストからの音声合成機能を提供します。 クリップボードまたはファイルからテキストを読み込み、指定された話者と音声設定で音声を生成し、 ファイルとして保存または直接再生できます。
- 対応TTSエンジン:
pyttsx3: ローカルのOS提供音声エンジンを利用
winrt (onecore): WindowsのOneCore音声エンジンを利用
voicevox: Voicevoxエンジンを利用 (要Voicevox Engine稼働)
qwen3 (qwen): Qwen TTSモデルを利用 (ローカル)
qwen_api (qwen-api): Qwen TTS APIを利用
irodori (irodori-tts): Irodori TTSモデルを利用 (ローカル)
irodori_api (irodori-api): Irodori TTS APIを利用
aquestalkplayer (atp): AquesTalk Playerを利用
openai: OpenAI TTS APIを利用
elevenlabs (eleven): ElevenLabs TTS APIを利用
gemini: Google Gemini TTS APIを利用
edge (edge_tts, edge-tts): Microsoft Edge TTSを利用
- 必要なコアライブラリ:
pydub: 音声ファイルの操作(結合、フォーマット変換など)
pyperclip: クリップボードへのアクセス
chardet: ファイルのエンコード検出
FFmpeg: 音声ファイルのエンコード/デコードに必要(PATHに設定推奨)
- 外部ドキュメントへのリンク:
- ai.tktts.check_ffmpeg_available() bool
FFmpeg と FFprobe がシステムPATHで利用可能かを確認します。
- 戻り値:
FFmpeg と FFprobe の両方が利用可能であればTrue、そうでなければFalse。
- 戻り値の型:
- ai.tktts.get_available_engines(available_only: bool = True)
登録されているTTSエンジン名を返します。
GUIのプルダウンメニュー生成などにも利用できます。
- ai.tktts.get_available_voices(tts_engine: str, endpoint: str = None, api_key: str = None)
指定されたTTSエンジンで利用可能な音声のリストを取得します。
各TTSバックエンドの get_available_voices 関数を呼び出します。
- ai.tktts.get_available_voices_info(tts_engine: str, endpoint: str = None, api_key: str = None)
指定されたTTSエンジンで利用可能な音声の詳細情報を取得します。
各TTSバックエンドの get_available_voices_info 関数を呼び出します。
- ai.tktts.get_speaker_dict(tts_engine: str, dialogue: list, voices: str, default_voicevox_voice: str = '四国めたん', default_pyttsx3_voice: str = 'Zira', default_winrt_voice: str = 'Ayumi', default_aqt_preset: str = 'れいむ', default_optnai_voice: str = 'alloy', default_elevenlabs_voice: str = 'Rachel', default_gemini_voice: str = 'Kore')
話者名とそれに割り当てる音声名をマッピングした辞書を作成します。
voices 引数で明示的に指定された音声が優先され、指定がない場合はエンジンのデフォルト音声が使用されます。
- パラメータ:
tts_engine (str) -- 使用するTTSエンジンの名前(例: "voicevox", "pyttsx3")。
dialogue (list[tuple[str or None, str]]) -- (話者名, テキスト) のタプルからなるリスト。
voices (str or None) -- 話者と音声の割り当てをセミコロン区切りで指定する文字列。 例: "話者A=Voice1;話者B=Voice2" または、カンマ区切りで音声名を直接指定する文字列。 例: "Voice1,Voice2,Voice3"
default_voicevox_voice (str) -- Voicevoxのデフォルト音声名。
default_pyttsx3_voice (str) -- pyttsx3のデフォルト音声名。
default_winrt_voice (str) -- WinRTのデフォルト音声名。
default_aqt_preset (str) -- AquesTalk Playerのデフォルトプリセット名。
default_optnai_voice (str) -- OpenAIのデフォルト音声名。
default_elevenlabs_voice (str) -- ElevenLabsのデフォルト音声名。
default_gemini_voice (str) -- Geminiのデフォルト音声名。
- 戻り値:
話者名(またはNone)をキー、音声名を値とする辞書。 無効なTTSエンジンが指定された場合はNoneを返します。
- 戻り値の型:
- ai.tktts.get_tts(tts_engine: str)
指定されたTTSエンジン名に対応するモジュールオブジェクトを取得します。
- パラメータ:
tts_engine (str) -- 取得するTTSエンジンの名前。
- 戻り値:
TTSモジュールオブジェクト。利用できない場合はNone。
- 戻り値の型:
types.ModuleType or None
- ai.tktts.list_available_voices(tts_engine: str, endpoint: str = None, api_key: str = None)
指定されたTTSエンジンで利用可能な音声のリストを標準出力に表示します。
各TTSバックエンドの list_available_voices 関数を呼び出します。
- ai.tktts.load_text(input_path: str, monologue: bool = False, wait_for_clipboard: bool = True)
入力元 ('clip' またはファイルパス) からテキストを取得し、(speaker, text) リストを返します。
テキストファイルはchardetでエンコードを自動判別します。 ファイル内の空行、コメント行(#で始まる行)、および記号のみの行は無視されます。
- パラメータ:
- 戻り値:
(話者名, テキスト) のタプルを要素とするリスト。 読み込みに失敗した場合はNoneを返します。
- 戻り値の型:
- ai.tktts.normalize_speaker(speaker, tts_engine: str = None)
話者ラベルを正規化します。
半角スペースでは分割しない。WinRTなどの音声表示名には
Microsoft Ayumi ...のように空白が含まれるためである。 明示的なスタイル表記話者(style)/話者(style)のみ除去します。
- ai.tktts.parse_kv_string(kv_string: str, keys: list = [], allow_no_key_kv_string: bool = False)
"key=val;key=val" 形式の文字列を辞書に変換します。
allow_no_key_kv_string がTrueの場合、"=" が含まれないアイテムも、 keys 引数のインデックスに基づいて辞書に追加されます。
- ai.tktts.speak_dialogue(args: SimpleNamespace, dialogue: list, voice_map: dict = None, speakers: dict = None, replacements: dict = None, default_voicevox_voice: str = '四国めたん', default_pyttsx3_voice: str = 'Zira', default_winrt_voice: str = 'Ayumi', default_aqt_preset: str = 'れいむ', default_optnai_voice: str = 'alloy', default_elevenlabs_voice: str = 'Rachel', default_gemini_voice: str = 'Kore', endpoint: str = None, api_key: str = None, output_format: str = None)
選択されたTTSエンジンで音声生成を行い、結合して保存または直接再生します。
この関数は、指定されたダイアログデータと設定に基づいて、適切なTTSバックエンドを呼び出し、 生成された音声ファイルを一時ディレクトリに保存し、必要に応じてそれらを結合して最終的な 出力ファイルとして保存します。
- パラメータ:
args (SimpleNamespace) -- TTSエンジンの設定値を含むNamespaceオブジェクト。 tts (str), outfile (str), monologue (bool), speak_rate (int), tinterval (float), voices (str), temp_dir (str) など、 および各エンジン固有の設定(例: qwen3_language, elevenlabs_api_key) を含みます。
dialogue (list[tuple[str or None, str]]) -- (話者名, テキスト) のタプルを要素とするリスト。
voice_map (dict[str or None, str], optional) -- 話者名と音声名のマッピング辞書。Noneの場合は args.voices から生成されます。
speakers (dict, optional) -- (未使用) 話者リスト。
replacements (dict, optional) -- テキストの置換ルールを定義する辞書。
default_voicevox_voice (str) -- Voicevoxのデフォルト音声名。
default_pyttsx3_voice (str) -- pyttsx3のデフォルト音声名。
default_winrt_voice (str) -- WinRTのデフォルト音声名。
default_aqt_preset (str) -- AquesTalk Playerのデフォルトプリセット名。
default_optnai_voice (str) -- OpenAIのデフォルト音声名。
default_elevenlabs_voice (str) -- ElevenLabsのデフォルト音声名。
default_gemini_voice (str) -- Geminiのデフォルト音声名。
endpoint (str, optional) -- APIベースのTTSエンジンで使用するエンドポイントURL。 args の設定よりも優先されます。
api_key (str, optional) -- APIベースのTTSエンジンで使用するAPIキー。 args の設定よりも優先されます。
output_format (str, optional) -- 出力ファイルのフォーマット。args の設定よりも優先されます。
- 戻り値:
音声出力に成功した場合、ファイル保存モードでは出力ファイルのパス、 直接再生モードではTrue。失敗した場合はFalse。
- 戻り値の型:
- class ai.tktts.tkTTS(tts_name: str = None, config: SimpleNamespace = None)
ベースクラス:
object複数のTTSエンジンを扱うためのラッパークラス。
選択されたTTSエンジンを初期化し、音声合成関連の様々なユーティリティ機能を提供します。 設定はSimpleNamespaceオブジェクトを通じて管理されます。
- get_available_voices(tts_name: str = None, endpoint: str = None, api_key: str = None)
指定されたTTSエンジンで利用可能な音声のリストを取得します。
モジュールレベルの get_available_voices 関数を呼び出します。 引数がNoneの場合、インスタンスの設定 (self.tts_name, self.endpoint, self.api_key) を使用します。
- get_available_voices_info(tts_name: str = None, endpoint: str = None, api_key: str = None)
指定されたTTSエンジンで利用可能な音声の詳細情報を取得します。
モジュールレベルの get_available_voices_info 関数を呼び出します。 引数がNoneの場合、インスタンスの設定 (self.tts_name, self.endpoint, self.api_key) を使用します。
- list_available_voices(tts_name: str = None, endpoint: str = None, api_key: str = None)
指定されたTTSエンジンで利用可能な音声のリストを標準出力に表示します。
モジュールレベルの list_available_voices 関数を呼び出します。 引数がNoneの場合、インスタンスの設定 (self.tts_name, self.endpoint, self.api_key) を使用します。
- load_text(input_path: str, monologue: bool = False, wait_for_clipboard: bool = True)
入力元 ('clip' またはファイルパス) からテキストを取得し、(speaker, text) リストを返します。
モジュールレベルの load_text 関数を呼び出します。
- パラメータ:
- 戻り値:
(話者名, テキスト) のタプルを要素とするリスト。 読み込みに失敗した場合はNoneを返します。
- 戻り値の型:
- normalize_speaker(speaker, tts_name: str = None)
話者ラベルを正規化します。
モジュールレベルの normalize_speaker 関数を呼び出します。
- parse_kv_string(kv_string: str, keys: list = [], allow_no_key_kv_string: bool = False)
"key=val;key=val" 形式の文字列を辞書に変換します。
モジュールレベルの parse_kv_string 関数とは異なり、話者名と音声名のマッピングに特化しています。 "=" が含まれないアイテムも、keys 引数のインデックスに基づいて辞書に追加されます。 また、正規化された話者名と、それに対応する音声名をマップします。
- set_api_key(api_key: str)
APIベースのTTSエンジンで使用するAPIキーを設定します。
このAPIキーはElevenLabsとGeminiの設定にも反映されます。
- パラメータ:
api_key (str) -- 設定するAPIキー。
- set_aquestalk_path(aquestalk_path: str)
AquesTalk Playerの実行パスを設定します。
- パラメータ:
aquestalk_path (str) -- AquesTalk Playerの実行ファイルパス。
- show_voice_map(infile: str, voices: str, VOICE_MAPS: dict, is_monologue: bool, tts_name: str = None, endpoint: str = None)
入力ファイルから話者を解析し、現在の音声マップを表示します。
これは主にデバッグや設定確認のために使用されます。
- パラメータ:
infile (str) -- 解析対象の入力ファイルパス。'clip' も指定可能です。
voices (str) -- 話者と音声の割り当てをセミコロン区切りで指定する文字列。 例: "話者A=Voice1;話者B=Voice2" または、カンマ区切りで音声名を直接指定する文字列。 例: "Voice1,Voice2,Voice3"
VOICE_MAPS (dict) -- TTSエンジンごとの音声マップを格納する辞書。 例: {"pyttsx3": {"speaker1": "Zira"}, "voicevox": {"speaker2": "四国めたん"}}
is_monologue (bool) -- テキストが独話形式(話者指定なし)かどうか。
tts_name (str, optional) -- 使用するTTSエンジンの名前。Noneの場合、インスタンスの現在のエンジン名を使用します。
endpoint (str, optional) -- APIベースのTTSエンジンで使用するエンドポイントURL。
- 戻り値:
処理が成功した場合はTrue、失敗した場合はFalse。
- 戻り値の型:
- speak_dialogue(dialogue: list = None, voice_map: dict = None, speakers: dict = None, replacements: dict = None, endpoint: str = None, api_key: str = None, output_format: str = None, config: SimpleNamespace = None)
現在のTTSエンジンで音声生成を行い、結合して保存または直接再生します。
モジュールレベルの speak_dialogue 関数を呼び出します。 引数がNoneの場合、インスタンスの設定 (self.config, self.endpoint, self.api_key) を使用します。
- パラメータ:
dialogue (list[tuple[str or None, str]], optional) -- (話者名, テキスト) のタプルを要素とするリスト。
voice_map (dict[str or None, str], optional) -- 話者名と音声名のマッピング辞書。
speakers (dict, optional) -- (未使用) 話者リスト。
replacements (dict, optional) -- テキストの置換ルールを定義する辞書。
endpoint (str, optional) -- APIベースのTTSエンジンで使用するエンドポイントURL。
api_key (str, optional) -- APIベースのTTSエンジンで使用するAPIキー。
output_format (str, optional) -- 出力ファイルのフォーマット。
config (types.SimpleNamespace, optional) -- TTSエンジンの設定値を含むNamespaceオブジェクト。
- 戻り値:
音声出力に成功した場合、ファイル保存モードでは出力ファイルのパス、 直接再生モードではTrue。失敗した場合はFalse。
- 戻り値の型: