tktts プログラム仕様

tktts.py - 複数のテキスト読み上げ（TTS）エンジンを統合し、音声生成・再生・保存を行うモジュール

概要:

本モジュールは、複数のテキスト読み上げ（TTS）エンジン（pyttsx3, VoiceVox, AquesTalkPlayer, OpenAIなど）を統一されたインターフェースで利用するための機能を提供します。テキストファイルの読み込み、話者ごとの音声マッピング、音声ファイルの生成、結合、一時ファイルの管理、そして最終的な音声の保存または再生までの一連の処理をサポートします。

詳細説明:

必要なライブラリのチェックと不足時の案内機能。
各TTSエンジンモジュールを安全にインポートする機構。
テキスト入力元（ファイルまたはクリップボード）からのデータ読み込みと、対話形式/独話形式の解析。
話者ごとの音声割り当て（デフォルト音声、指定音声、話者マッピングの更新）。
選択されたTTSエンジンによる音声生成（各エンジン固有のパラメータ対応）。
生成された複数の音声ファイルの時間間隔を考慮した結合。
最終的な音声ファイルの指定フォーマットでの保存またはインメモリ再生（pyttsx3の場合）。
一時ディレクトリおよび一時ファイルの自動クリーンアップ。
`tkTTS`クラスによる、よりオブジェクト指向的なTTS操作の提供。

関連リンク:

tktts.py ライブラリ技術ドキュメント

ai.tktts.apply_replacements(text, replacements)[ソース]

置換辞書に基づいてテキスト内の指定された文字列を置換します。

詳細:: 置換は大文字小文字を無視して行われます。

パラメータ:

text (str) -- 置換を適用する元のテキスト文字列。
replacements (dict) -- {置換前の文字列: 置換後の文字列}形式の辞書。

戻り値:

置換が適用されたテキスト文字列。

戻り値の型:

str

ai.tktts.create_temp_dir(temp_dir)[ソース]

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

詳細:: ディレクトリが存在しない場合にのみ作成されます。

パラメータ:: temp_dir (str) -- 作成する一時ディレクトリのパス。
戻り値:: 作成または確認された一時ディレクトリのパス。
戻り値の型:: str

ai.tktts.get_available_voices(endpoint=None)[ソース]

現在選択されているTTSエンジンが利用可能な音声名のリストを取得します。

詳細:: 内部で`get_tts`を呼び出し、取得したTTSモジュールの`get_available_voices`メソッドを呼び出します。

パラメータ:: endpoint (str or None) -- (VoiceVoxなどで使用) TTSエンジンのAPIエンドポイントURL。
戻り値:: 利用可能な音声名のリスト、またはエラーの場合はNone。
戻り値の型:: list[str] or None

ai.tktts.get_available_voices_info(endpoint=None)[ソース]

現在選択されているTTSエンジンが利用可能な音声の詳細情報を取得します。

詳細:: 内部で`get_tts`を呼び出し、取得したTTSモジュールの`get_available_voices_info`メソッドを呼び出します。

パラメータ:: endpoint (str or None) -- (VoiceVoxなどで使用) TTSエンジンのAPIエンドポイントURL。
戻り値:: 利用可能な音声の詳細情報（エンジン依存の形式）、またはエラーの場合はNone。
戻り値の型:: list or dict or None

ai.tktts.get_speaker_dict(tts_engine, dialogue, voices, default_voicevox_voice='四国めたん', default_pyttsx3_voice='Zira', default_aqt_preset='れいむ', default_optnai_voice='alloy')[ソース]

対話データと指定された音声設定に基づいて、話者ごとの音声マッピング辞書を生成します。

詳細:

`voices`引数でセミコロン区切りで指定された音声リストを優先的に使用します。
指定がない場合、TTSエンジンごとのデフォルト音声が使用されます。
独話（話者なし）の場合やファイル内で定義されていない話者には、デフォルト音声が割り当てられます。

パラメータ:

tts_engine (str) -- 使用するTTSエンジンの名前（例: "pyttsx3", "voicevox"）。
dialogue (list[tuple[str or None, str]]) -- (speaker, text)のタプルのリスト。
voices (str) -- セミコロン区切りの音声名リスト（例: "voice1;voice2"）。
default_voicevox_voice (str) -- VoiceVoxのデフォルト音声名。
default_pyttsx3_voice (str) -- pyttsx3のデフォルト音声名。
default_aqt_preset (str) -- AquesTalkPlayerのデフォルトプリセット名。
default_optnai_voice (str) -- OpenAIのデフォルト音声名。

戻り値:

{話者名: 音声名}形式のマッピング辞書。

戻り値の型:

dict[str or None, str]

ai.tktts.get_tts(tts_engine)[ソース]

指定されたTTSエンジンのモジュールオブジェクトを取得します。

詳細:: `TTS_ENGINES`辞書から対応するエンジンモジュールを検索します。モジュールがインポートに失敗している場合、エラーメッセージを出力しNoneを返します。

パラメータ:: tts_engine (str) -- 取得したいTTSエンジンの名前。
戻り値:: TTSエンジンモジュールオブジェクト、または見つからない/インポート失敗の場合はNone。
戻り値の型:: ModuleType or None

ai.tktts.list_available_voices(tts_engine, endpoint=None)[ソース]

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

詳細:: `get_tts`を呼び出し、TTSモジュールに`list_available_voices`メソッドがあればそれを呼び出して結果を表示します。 VoiceVoxの場合、`endpoint`引数を使用します。

パラメータ:

tts_engine (str) -- 音声リストを取得するTTSエンジンの名前。
endpoint (str or None) -- (VoiceVoxなどで使用) TTSエンジンのAPIエンドポイントURL。

戻り値:

`list_available_voices`メソッドの実行結果（通常はTrue/False）、またはエラーの場合はFalse。

戻り値の型:

bool

ai.tktts.load_text(input_path, monologue=False, wait_for_clipboard=True)[ソース]

指定された入力元（ファイルまたはクリップボード）からテキストを読み込み、話者とテキストのペアのリストを返します。

詳細:

`input_path`が"clip"の場合、クリップボードからテキストを取得します。
ファイルパスの場合、ファイルを読み込み、`chardet`でエンコーディングを自動判別します。
読み込まれたテキストを行ごとに処理し、対話形式または独話形式（モノローグ）に応じて`(speaker, text)`のリストを生成します。
独話モードでは`speaker`は`None`になります。
コメント行（`#`で始まる行）や空行はスキップされます。

パラメータ:

input_path (str) -- テキストの入力元。"clip"またはファイルパス。
monologue (bool) -- Trueの場合、すべての行を独話として扱い、話者をNoneとします。
wait_for_clipboard (bool) -- input_pathが"clip"の場合、クリップボードへのコピーを待機するかどうか。

戻り値:

(speaker, text)のタプルのリスト、またはエラーが発生した場合はNone。

戻り値の型:

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

ai.tktts.normalize_speaker(speaker, tts_engine)[ソース]

話者名を正規化します。

詳細:: 話者名からスタイル情報（例: (元気)）や括弧を除去し、基本となる話者名のみを抽出します。現在の実装では、空白で区切られた最初の部分を話者名としています。

パラメータ:

speaker (str or None) -- 正規化する話者名文字列。
tts_engine (str) -- 使用するTTSエンジンの名前（現在は使用されていませんが、将来的な拡張性のため保持）。

戻り値:

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

戻り値の型:

str or None

ai.tktts.parse_kv_string(kv_string, keys=[], allow_no_key_kv_string=False)[ソース]

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

詳細:

セミコロンで区切られた各項目を処理します。
`=`を含む項目は`key: val`として辞書に追加します。
`allow_no_key_kv_string`がTrueの場合、`=`を含まない項目は`keys`リストの対応するインデックス、または連番のインデックスで辞書に追加します。
`keys`引数で指定された話者が`kv_string`で設定されていない場合、その話者名をそのまま値として追加します。

パラメータ:

kv_string (str) -- "key=val;key=val"形式の入力文字列。
keys (list[str]) -- `=`を含まない項目に値を割り当てる際に使用するキーのリスト。
allow_no_key_kv_string (bool) -- `=`を含まない項目を許可するかどうか。

戻り値:

変換された辞書。

戻り値の型:

dict

ai.tktts.speak_dialogue(args, dialogue, voice_map=None, speakers={}, replacements=None, default_voicevox_voice='四国めたん', default_pyttsx3_voice='Zira', default_aqt_preset='れいむ', default_optnai_voice='alloy', endpoint=None, output_format='mp3')[ソース]

指定されたTTSエンジンを使用して、対話データから音声を生成し、結合して保存または再生します。

詳細:

`args.tts`で指定されたTTSエンジンを選択します。
`voice_map`が指定されていない場合、`get_speaker_dict`を呼び出して話者と音声のマッピングを生成します。
pyttsx3以外のエンジンは一時ファイルへの保存が必須なため、`--outfile`の指定がなければエラーとなります。
一時ディレクトリを作成し、各テキストセグメントの音声ファイルを生成します。
生成された音声ファイルを`pydub`で結合し、指定された間隔（args.tinterval）を挿入します。
最終的な音声を`args.outfile`に保存し、一時ファイルを削除します。

パラメータ:

args (argparse.Namespace) -- コマンドライン引数を格納するオブジェクト（tts, outfile, monologue, speak_rate, tinterval, temp_dirなどを保持）。
dialogue (list[tuple[str or None, str]]) -- (speaker, text)のタプルのリスト。
voice_map (dict[str or None, str] or None) -- {話者名: 音声名}形式のマッピング辞書。Noneの場合、自動生成されます。
speakers (list[str]) -- ファイルから検出された話者のリスト。
replacements (dict or None) -- テキスト置換ルールを定義する辞書。
default_voicevox_voice (str) -- VoiceVoxのデフォルト音声名。
default_pyttsx3_voice (str) -- pyttsx3のデフォルト音声名。
default_aqt_preset (str) -- AquesTalkPlayerのデフォルトプリセット名。
default_optnai_voice (str) -- OpenAIのデフォルト音声名。
endpoint (str or None) -- (VoiceVoxなどで使用) TTSエンジンのAPIエンドポイントURL。
output_format (str) -- 出力オーディオファイルのフォーマット（例: 'mp3', 'wav'）。

戻り値:

成功した場合は出力ファイルのパス、失敗した場合はFalse。

戻り値の型:

str or bool

class ai.tktts.tkTTS(tts_name=None, config={})[ソース]

ベースクラス: object

複数のテキスト読み上げ（TTS）エンジンを抽象化し、一貫したインターフェースを提供するクラス。

詳細:: 内部で各TTSエンジンのモジュールを管理し、話者マッピング、音声リストの取得、音声生成などの機能を提供します。set_engine`で利用するTTSエンジンを切り替えることができます。各種ヘルパー関数（`load_text, `normalize_speaker`など）をラップしています。

パラメータ:

tts_name (str or None) -- 初期化時に設定するTTSエンジンの名前。
config (object or dict) -- TTSエンジン設定を含む設定オブジェクト（または辞書）。

get_default_voice(tts_name=None)[ソース]

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

パラメータ:: tts_name (str or None) -- デフォルト音声名を取得するTTSエンジンの名前。Noneの場合、インスタンスに設定されているエンジンのデフォルトを返します。
戻り値:: デフォルト音声名、またはTTSエンジンが見つからない場合はNone。
戻り値の型:: str or None

get_speakers_from_dialogue(dialogue)[ソース]

対話データからユニークな話者のリストを抽出します。

パラメータ:: dialogue (list[tuple[str or None, str]]) -- (speaker, text)のタプルのリスト。
戻り値:: 対話に含まれるユニークな話者名のリスト。
戻り値の型:: list[str or None]

get_tts_name(tts_name=None)[ソース]

現在設定されているTTSエンジンの名前、または指定されたTTSエンジンの名前を返します。

パラメータ:: tts_name (str or None) -- 取得したいTTSエンジンの名前（Noneの場合、インスタンスに設定されている名前を返します）。
戻り値:: TTSエンジンの名前。
戻り値の型:: str

list_available_voices(tts_name=None, endpoint=None)[ソース]

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

詳細:: クラスのインスタンスメソッドとして、モジュールレベルの`list_available_voices`関数を呼び出します。

パラメータ:

tts_name (str or None) -- 音声リストを取得するTTSエンジンの名前。Noneの場合、インスタンスに設定されているエンジンの音声リストを表示します。
endpoint (str or None) -- (VoiceVoxなどで使用) TTSエンジンのAPIエンドポイントURL。Noneの場合、インスタンスに設定されているエンドポイントを使用します。

戻り値:

`list_available_voices`メソッドの実行結果（通常はTrue/False）、またはエラーの場合はFalse。

戻り値の型:

bool

load_text(input_path, monologue=False, wait_for_clipboard=True)[ソース]

指定された入力元からテキストを読み込み、話者とテキストのペアのリストを返します。

詳細:: クラスのインスタンスメソッドとして、モジュールレベルの`load_text`関数を呼び出します。

パラメータ:

input_path (str) -- テキストの入力元。"clip"またはファイルパス。
monologue (bool) -- Trueの場合、すべての行を独話として扱い、話者をNoneとします。
wait_for_clipboard (bool) -- input_pathが"clip"の場合、クリップボードへのコピーを待機するかどうか。

戻り値:

(speaker, text)のタプルのリスト、またはエラーが発生した場合はNone。

戻り値の型:

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

normalize_speaker(speaker, tts_name=None)[ソース]

話者名を正規化します。

詳細:: クラスのインスタンスメソッドとして、モジュールレベルの`normalize_speaker`関数を呼び出します。

パラメータ:

speaker (str or None) -- 正規化する話者名文字列。
tts_name (str) -- 使用するTTSエンジンの名前（現在は使用されていませんが、将来的な拡張性のため保持）。

戻り値:

正規化された話者名。

戻り値の型:

str or None

parse_kv_string(kv_string, keys=[], allow_no_key_kv_string=False)[ソース]

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

詳細:: クラスのインスタンスメソッドとして、モジュールレベルの`parse_kv_string`関数を呼び出し、話者名の正規化を適用します。

パラメータ:

kv_string (str) -- "key=val;key=val"形式の入力文字列。
keys (list[str]) -- `=`を含まない項目に値を割り当てる際に使用するキーのリスト（ファイルから検出された話者など）。
allow_no_key_kv_string (bool) -- `=`を含まない項目を許可するかどうか。

戻り値:

変換された辞書。

戻り値の型:

dict

set_aquestalk_path(aquestalk_path)[ソース]

AquesTalkPlayerの実行可能ファイルのパスを設定します。

パラメータ:: aquestalk_path (str) -- AquesTalkPlayerの実行可能ファイルへのパス。
戻り値:: None
戻り値の型:: None

set_endpoint(endpoint)[ソース]

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

パラメータ:: endpoint (str) -- 設定するAPIエンドポイントURL。
戻り値:: None
戻り値の型:: None

set_engine(tts_name)[ソース]

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

パラメータ:: tts_name (str) -- 設定するTTSエンジンの名前。
戻り値:: None
戻り値の型:: None

show_voice_map(infile, voices, VOICE_MAPS, is_monologue, tts_name=None, endpoint=None)[ソース]

入力ファイルから話者を抽出し、指定された音声マッピングと組み合わせて、最終的な話者-音声マッピングを表示します。

詳細:

入力ファイル（infile）から話者を検出し、その話者リストを表示します。
`VOICE_MAPS`と`voices`引数に基づいて`update_voice_map`を呼び出し、最終的な音声マッピングを生成し表示します。

パラメータ:

infile (str) -- テキスト入力ファイルのパス。
voices (str) -- セミコロン区切りの音声指定文字列（例: "speaker1=voiceA;speaker2=voiceB"）。
VOICE_MAPS (dict) -- 既存の音声マッピング辞書。
is_monologue (bool) -- 入力テキストが独話形式かどうか。
tts_name (str or None) -- 使用するTTSエンジンの名前。
endpoint (str or None) -- (VoiceVoxなどで使用) TTSエンジンのAPIエンドポイントURL。

戻り値:

テキストデータの取得に成功した場合はTrue、失敗した場合はFalse。

戻り値の型:

bool

speak_dialogue(dialogue=None, voice_map=None, speakers={}, replacements=None, endpoint=None, output_format='mp3', config=None)[ソース]

指定されたTTSエンジンと設定を使用して、対話データから音声を生成し、結合して保存または再生します。

詳細:: クラスのインスタンスメソッドとして、モジュールレベルの`speak_dialogue`関数を呼び出します。インスタンスに設定されている`endpoint`や`config`を自動的に渡します。

パラメータ:

dialogue (list[tuple[str or None, str]] or None) -- (speaker, text)のタプルのリスト。
voice_map (dict[str or None, str] or None) -- {話者名: 音声名}形式のマッピング辞書。Noneの場合、自動生成されます。
speakers (list[str]) -- ファイルから検出された話者のリスト。
replacements (dict or None) -- テキスト置換ルールを定義する辞書。
endpoint (str or None) -- (VoiceVoxなどで使用) TTSエンジンのAPIエンドポイントURL。Noneの場合、インスタンスに設定されているエンドポイントを使用します。
output_format (str) -- 出力オーディオファイルのフォーマット（例: 'mp3', 'wav'）。
config (object or None) -- コマンドライン引数を格納するオブジェクト。Noneの場合、インスタンスに設定されているconfigを使用します。

戻り値:

成功した場合は出力ファイルのパス、失敗した場合はFalse。

戻り値の型:

str or bool

update_voice_map(voice_map={}, voices='', speakers={})[ソース]

既存の音声マッピング辞書を更新し、指定された音声設定と話者リストを適用します。

詳細:

`voice_map`引数で与えられた現在のTTSエンジンのマッピングをコピーします。
`voices`文字列が空でない場合、`parse_kv_string`を使用して`voices`からマッピングを生成し、既存のマッピングに上書きします。
`voices`が空の場合、`speakers`リストから話者名を取得し、話者名をそのまま音声名としてマッピングに追加します。
独話（Noneまたは空文字列）の場合のデフォルト音声も設定します。

パラメータ:

voice_map (dict) -- 既存の音声マッピング辞書。
voices (str) -- セミコロン区切りの音声指定文字列（例: "speaker1=voiceA;speaker2=voiceB"）。
speakers (list[str or None]) -- ファイルから検出された話者のリスト。

戻り値:

更新された音声マッピング辞書。

戻り値の型:

dict[str or None or int, str]