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に設定推奨)

外部ドキュメントへのリンク:

tktts.py Documentation

ai.tktts.apply_replacements(text: str, replacements: dict)

置換辞書を使ってテキストを置換(大文字小文字無視)します。

パラメータ:
  • text (str) -- 置換処理を適用する元のテキスト。

  • replacements (dict or None) -- キーを正規表現パターン、値を置換後の文字列とする辞書。 キーのマッチングは大文字小文字を無視します。

戻り値:

置換後のテキスト。

戻り値の型:

str

ai.tktts.check_ffmpeg_available() → bool

FFmpeg と FFprobe がシステムPATHで利用可能かを確認します。

戻り値:

FFmpeg と FFprobe の両方が利用可能であればTrue、そうでなければFalse。

戻り値の型:

bool

ai.tktts.create_temp_dir(temp_dir: str)

指定されたパスに一時ディレクトリを作成します。

既に存在する場合は何もしません。

パラメータ:

temp_dir (str) -- 作成する一時ディレクトリのパス。

戻り値:

作成または確認された一時ディレクトリのパス。

戻り値の型:

str

ai.tktts.get_available_engines(available_only: bool = True)

登録されているTTSエンジン名を返します。

GUIのプルダウンメニュー生成などにも利用できます。

パラメータ:

available_only (bool) -- 利用可能なエンジンのみを返すかどうか。Trueの場合、 依存ライブラリがロードできたエンジンのみを返します。 Falseの場合、全ての登録済みエンジン名を返します。

戻り値:

利用可能な(または全ての)TTSエンジン名のリスト。

戻り値の型:

list[str]

ai.tktts.get_available_voices(tts_engine: str, endpoint: str = None, api_key: str = None)

指定されたTTSエンジンで利用可能な音声のリストを取得します。

各TTSバックエンドの get_available_voices 関数を呼び出します。

パラメータ:
  • tts_engine (str) -- 音声リストを取得するTTSエンジンの名前。

  • endpoint (str, optional) -- APIベースのTTSエンジンで使用するエンドポイントURL。

  • api_key (str, optional) -- APIベースのTTSエンジンで使用するAPIキー。

戻り値:

利用可能な音声名のリスト。エンジンが利用不可、または対応する関数がない場合はNone。

戻り値の型:

list[str] or None

ai.tktts.get_available_voices_info(tts_engine: str, endpoint: str = None, api_key: str = None)

指定されたTTSエンジンで利用可能な音声の詳細情報を取得します。

各TTSバックエンドの get_available_voices_info 関数を呼び出します。

パラメータ:
  • tts_engine (str) -- 音声情報を取得するTTSエンジンの名前。

  • endpoint (str, optional) -- APIベースのTTSエンジンで使用するエンドポイントURL。

  • api_key (str, optional) -- APIベースのTTSエンジンで使用するAPIキー。

戻り値:

利用可能な音声の詳細情報。エンジンが利用不可、または対応する関数がない場合はNone。 形式はエンジンによって異なりますが、通常は辞書のリストなど。

戻り値の型:

Any or None

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を返します。

戻り値の型:

dict[str or None, str] or 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 関数を呼び出します。

パラメータ:
  • tts_engine (str) -- 音声リストを表示するTTSエンジンの名前。

  • endpoint (str, optional) -- APIベースのTTSエンジンで使用するエンドポイントURL。

  • api_key (str, optional) -- APIベースのTTSエンジンで使用するAPIキー。

戻り値:

処理が成功した場合はTrue、失敗した場合はFalse。

戻り値の型:

bool

ai.tktts.load_text(input_path: str, monologue: bool = False, wait_for_clipboard: bool = True)

入力元 ('clip' またはファイルパス) からテキストを取得し、(speaker, text) リストを返します。

テキストファイルはchardetでエンコードを自動判別します。 ファイル内の空行、コメント行(#で始まる行)、および記号のみの行は無視されます。

パラメータ:
  • input_path (str) -- テキストの入力元。'clip' の場合はクリップボードから、 それ以外の文字列はファイルパスとして扱います。

  • monologue (bool) -- テキストが独話形式(話者指定なし)かどうか。Trueの場合、 全ての話者がNoneとして扱われます。

  • wait_for_clipboard (bool) -- input_pathが'clip'の場合、クリップボードにテキストが コピーされるまで待機するかどうか。

戻り値:

(話者名, テキスト) のタプルを要素とするリスト。 読み込みに失敗した場合はNoneを返します。

戻り値の型:

list[tuple[str or None, str]] or None

ai.tktts.normalize_speaker(speaker, tts_engine: str = None)

話者ラベルを正規化します。

半角スペースでは分割しない。WinRTなどの音声表示名には Microsoft Ayumi ... のように空白が含まれるためである。 明示的なスタイル表記 話者(style) / 話者(style) のみ除去します。

パラメータ:
  • speaker (str or None) -- 正規化する話者名または音声名。

  • tts_engine (str, optional) -- 使用するTTSエンジンの名前(現在は未使用ですが、将来の拡張性のため)。

戻り値:

正規化された話者名。入力がNoneの場合はNone。

戻り値の型:

str or None

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 引数のインデックスに基づいて辞書に追加されます。

パラメータ:
  • kv_string (str) -- "key=val;key=val" 形式の文字列、またはセミコロン区切りの値の文字列。

  • keys (list) -- kv_string が "key=val" 形式でない場合に、値に割り当てるキーのリスト。

  • allow_no_key_kv_string (bool) -- "=" を含まないアイテムを許容し、keys に基づいて処理するかどうか。

戻り値:

キーと値をマッピングした辞書。

戻り値の型:

dict

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。

戻り値の型:

str or bool

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) を使用します。

パラメータ:
  • tts_name (str, optional) -- 音声リストを取得するTTSエンジンの名前。

  • endpoint (str, optional) -- APIベースのTTSエンジンで使用するエンドポイントURL。

  • api_key (str, optional) -- APIベースのTTSエンジンで使用するAPIキー。

戻り値:

利用可能な音声名のリスト。

戻り値の型:

list[str] or None

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) を使用します。

パラメータ:
  • tts_name (str, optional) -- 音声情報を取得するTTSエンジンの名前。

  • endpoint (str, optional) -- APIベースのTTSエンジンで使用するエンドポイントURL。

  • api_key (str, optional) -- APIベースのTTSエンジンで使用するAPIキー。

戻り値:

利用可能な音声の詳細情報。

戻り値の型:

Any or None

get_default_voice(tts_name: str = None)

指定されたTTSエンジンのデフォルトの音声名を返します。

パラメータ:

tts_name (str, optional) -- デフォルト音声名を取得するTTSエンジン。Noneの場合、インスタンスの現在のエンジン名を使用します。

戻り値:

デフォルトの音声名、またはNone(エンジンが見つからない場合)。

戻り値の型:

str or None

get_speakers_from_dialogue(dialogue: list)

ダイアログリストからユニークな話者名のリストを抽出します。

パラメータ:

dialogue (list[tuple[str or None, str]]) -- (話者名, テキスト) のタプルを要素とするリスト。

戻り値:

ダイアログに含まれるユニークな話者名のリスト。

戻り値の型:

list[str or None]

get_tts_name(tts_name: str = None)

現在のTTSエンジン名、または引数で指定されたTTSエンジン名を返します。

パラメータ:

tts_name (str, optional) -- 返すTTSエンジン名。Noneの場合、インスタンスの現在のエンジン名を返します。

戻り値:

TTSエンジンの名前。

戻り値の型:

str

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) を使用します。

パラメータ:
  • tts_name (str, optional) -- 音声リストを表示するTTSエンジンの名前。

  • endpoint (str, optional) -- APIベースのTTSエンジンで使用するエンドポイントURL。

  • api_key (str, optional) -- APIベースのTTSエンジンで使用するAPIキー。

戻り値:

処理が成功した場合はTrue、失敗した場合はFalse。

戻り値の型:

bool

load_text(input_path: str, monologue: bool = False, wait_for_clipboard: bool = True)

入力元 ('clip' またはファイルパス) からテキストを取得し、(speaker, text) リストを返します。

モジュールレベルの load_text 関数を呼び出します。

パラメータ:
  • input_path (str) -- テキストの入力元。'clip' の場合はクリップボードから、 それ以外の文字列はファイルパスとして扱います。

  • monologue (bool) -- テキストが独話形式(話者指定なし)かどうか。

  • wait_for_clipboard (bool) -- input_pathが'clip'の場合、クリップボードにテキストが コピーされるまで待機するかどうか。

戻り値:

(話者名, テキスト) のタプルを要素とするリスト。 読み込みに失敗した場合はNoneを返します。

戻り値の型:

list[tuple[str or None, str]] or None

normalize_speaker(speaker, tts_name: str = None)

話者ラベルを正規化します。

モジュールレベルの normalize_speaker 関数を呼び出します。

パラメータ:
  • speaker (str or None) -- 正規化する話者名または音声名。

  • tts_name (str, optional) -- 使用するTTSエンジンの名前(現在は未使用)。

戻り値:

正規化された話者名。入力がNoneの場合はNone。

戻り値の型:

str or None

parse_kv_string(kv_string: str, keys: list = [], allow_no_key_kv_string: bool = False)

"key=val;key=val" 形式の文字列を辞書に変換します。

モジュールレベルの parse_kv_string 関数とは異なり、話者名と音声名のマッピングに特化しています。 "=" が含まれないアイテムも、keys 引数のインデックスに基づいて辞書に追加されます。 また、正規化された話者名と、それに対応する音声名をマップします。

パラメータ:
  • kv_string (str) -- "key=val;key=val" 形式の文字列、またはセミコロン区切りの音声名の文字列。

  • keys (list) -- kv_string が "key=val" 形式でない場合に、値に割り当てるキーのリスト。 (読み上げファイルから抽出された話者リストなど)

  • allow_no_key_kv_string (bool) -- "=" を含まないアイテムを許容し、keys に基づいて処理するかどうか。

戻り値:

話者名と音声名をマッピングした辞書。

戻り値の型:

dict[str or int, str]

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の実行ファイルパス。

set_endpoint(endpoint: str)

TTSエンジンのエンドポイントURLを設定します。

パラメータ:

endpoint (str) -- 設定するエンドポイントURL。

set_engine(tts_name: str)

使用するTTSエンジンを設定します。

パラメータ:

tts_name (str) -- 設定するTTSエンジンの名前。

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。

戻り値の型:

bool

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。

戻り値の型:

str or bool

update_voice_map(voice_map: dict = {}, voices: str = '', speakers: list = {})

現在のTTSエンジンの音声マップを更新します。

voices 文字列によって明示的に指定された割り当てが優先され、 その後、speakers リストに基づいてデフォルトの割り当てが適用されます。

パラメータ:
  • voice_map (dict) -- 既存のTTSエンジンごとの音声マップ。

  • voices (str) -- 話者と音声の割り当てをセミコロン区切りで指定する文字列。 例: "話者A=Voice1;話者B=Voice2" または、カンマ区切りで音声名を直接指定する文字列。 例: "Voice1,Voice2,Voice3"

  • speakers (list[str or None]) -- ダイアログから検出された話者名のリスト。 voices で指定されていない話者にデフォルトの音声名を割り当てるために使用されます。

戻り値:

更新された話者名と音声名のマッピング辞書。

戻り値の型:

dict[str or None or int, str]