tktts_irodori.py Documentation

ライブラリの機能や目的

tktts_irodori.py は、tktts_* ライブラリファミリーのための Irodori-TTS バックエンドを提供するモジュールです。tktts_voicevox.py や tktts_qwen3.py といった他のバックエンドと互換性のあるインターフェースに準拠しています。

このライブラリの主な目的は、Irodori-TTS の公式 InferenceRuntime API を介して直接音声合成を行うことです。これにより、Gradio UI や HTTP サーバーを別途実行する必要なく、Irodori-TTS の強力な音声合成機能を Python プログラムから直接利用できます。

ロードされた Irodori-TTS ランタイムは内部でキャッシュされ、以降のすべての音声合成リクエストで再利用されるため、効率的な運用が可能です。

主な機能:

  • Irodori-TTS モデルのロードとキャッシュ管理。

  • テキストからWAVファイルへの音声合成。

  • キャプション (caption) や参照WAVファイル (ref_wav/ref_wavs) を用いた音声スタイルの制御。

  • ダイアログ形式のテキストを処理し、複数の発話を連続して合成する機能。

  • tktts_base モジュールのテキスト置換や話者正規化機能との連携。

このライブラリは、Irodori-TTSにおけるテキストの分割や読み上げ/発音変換といった処理を意図的に呼び出し元に任せています。speak_dialogue 関数は、他のバックエンドと同様に、tktts から渡された置換辞書のみを適用します。

importする方法

このライブラリは、Pythonの標準的な import 文でインポートできます。

import tktts_irodori

あるいは、特定の関数や変数を直接インポートすることも可能です。

from tktts_irodori import speak, load_model, TTS_ENGINE_NAME

必要な非標準ライブラリとインストール方法

tktts_irodori.py を実行するには、以下の非標準ライブラリが必要です。

  • torch: PyTorchライブラリ。

  • irodori_tts: Irodori-TTSの推論ランタイム。

これらのライブラリは、通常 pip を使用してインストールできますが、Irodori-TTS は uv ツールによる環境構築が推奨されています。特に irodori_tts は特定のPyTorchバージョンに依存する可能性があるため、Irodori-TTS の公式ドキュメントに従うことが最も確実です。

tktts_irodori.py のコード内では、不足しているライブラリがある場合に uv sync --extra cu128 コマンドの実行が推奨されています。これはCUDA 12.8環境向けのインストール例です。ご自身の環境に合わせて適切なCUDAバージョンまたはCPU版を選択してください。

推奨されるインストール方法(uvを使用):

1Irodori-TTS の推奨環境設定ツール uv を使用して、必要なライブラリをインストールします。GPU環境 (CUDA 12.8) の場合:

uv sync --extra cu128

CPU環境の場合(uvが対応していれば):

uv sync --extra cpu

手動インストール (pipを使用):

上記の方法が利用できない場合、または特定の理由で pip を使用する場合は、以下のコマンドで個別にインストールできます。

pip install torch irodori-tts

依存モジュール:

このライブラリは、tktts_base.py というモジュールにも依存しています。これは同じ tktts プロジェクトの一部であると想定されており、pip でインストールする一般的なライブラリではありません。tktts_irodori.py を使用する際は、tktts_base.py がPythonのパスからインポート可能であることを確認してください(通常は同じディレクトリまたは PYTHONPATH に含まれるディレクトリに配置します)。

importできる変数と関数

変数

  • TTS_ENGINE_NAME: str

    • このTTSバックエンドの名前。"irodori"。

  • DEFAULT_IRODORI_MODEL: str

    • デフォルトで使用されるIrodori-TTSモデルのHugging FaceリポジトリID。"Aratako/Irodori-TTS-v4.1-Small"。

  • DEFAULT_IRODORI_VOICE: str

    • デフォルトで使用される仮想的なIrodori-TTS音声の名前。"default"。

  • DEFAULT_CAPTION: str

    • 音声合成時にデフォルトで適用されるキャプション。"落ち着いた自然な声で、明瞭に読み上げる。"。

  • DEFAULT_DEVICE: str

    • モデルの推論に使用するデフォルトデバイス。"auto"。

  • DEFAULT_PRECISION: str

    • モデルの推論に使用するデフォルト精度。"auto"。

  • DEFAULT_NUM_STEPS: int

    • サンプリングステップ数のデフォルト値。40。

  • DEFAULT_CFG_SCALE_TEXT: float

    • テキストに対するCFGスケールのデフォルト値。3.5。

  • DEFAULT_CFG_SCALE_CAPTION: float

    • キャプションに対するCFGスケールのデフォルト値。3.0。

  • DEFAULT_CFG_SCALE_SPEAKER: float

    • 話者に対するCFGスケール(参照WAVがある場合のみ有効)のデフォルト値。5.0。

  • DEFAULT_SEED: int

    • 乱数シードのデフォルト値。0。

関数

load_model(model_id=DEFAULT_IRODORI_MODEL, device=DEFAULT_DEVICE, precision=DEFAULT_PRECISION, *, codec_device=None, codec_precision=None, force_reload=False)

Irodori-TTS推論ランタイムをロードし、キャッシュします。

この関数は、指定されたモデル、デバイス、精度に基づいてIrodori-TTSのランタイムを初期化します。ランタイムはIrodori-TTSの内部キャッシュメカニズムによって管理され、同じ設定が再度要求された場合は既存のインスタンスが再利用されます。

  • 引数:

    • model_id: ロードするIrodori-TTSモデルのHugging FaceリポジトリIDまたはローカルパス。デフォルトは DEFAULT_IRODORI_MODEL。

    • device: モデルの推論に使用するデバイス ("cpu", "cuda", "auto" など)。デフォルトは DEFAULT_DEVICE。

    • precision: モデルの推論に使用する精度 ("fp32", "bf16", "auto" など)。デフォルトは DEFAULT_PRECISION。

    • codec_device: コーデックの推論に使用するデバイス。指定されない場合は device が使用されます。

    • codec_precision: コーデックの推論に使用する精度。指定されない場合は precision が使用されます。

    • force_reload: Trueの場合、既存のキャッシュされたランタイムをクリアして強制的に再ロードします。

  • 戻り値:

    • irodori_tts.inference_runtime.InferenceRuntime: ロードされたIrodori-TTSの InferenceRuntime インスタンス。

unload_models()

Irodori-TTSによってキャッシュされたランタイムを解放します。

これにより、Irodori-TTSの推論ランタイムがキャッシュからクリアされ、GPUメモリを使用している場合はGPUキャッシュも空にされます。

  • 引数: なし

  • 戻り値: None

get_available_voices_info(model=None)

Irodori-TTSが使用する仮想的なデフォルト音声の情報を返します。

Irodori-TTSは固定された話者リストを持っていません。声の同一性は参照オーディオによって制御され、スタイルはキャプションによっても制御できます。model 引数はtkttsインターフェースの互換性のために受け入れられますが、内部では使用されません。

  • 引数:

    • model: tkttsインターフェース互換性のため。実際には使用されません。

  • 戻り値:

    • list[dict[str, str]]: 仮想的なデフォルト音声の詳細情報を含む辞書のリスト。

get_available_voices(model=None)

tkttsの音声セレクタと互換性のある音声名を返します。

  • 引数:

    • model: tkttsインターフェース互換性のため。実際には使用されません。

  • 戻り値:

    • list[str]: 利用可能な仮想音声名のリスト。

list_available_voices(model=None)

Irodori-TTSの仮想的な音声エントリを表示します。

  • 引数:

    • model: tkttsインターフェース互換性のため。実際には使用されません。

  • 戻り値:

    • bool: 利用可能な音声がある場合はTrue、ない場合はFalse。

resolve_speaker_id(speaker_name, voices_info=None, model=None)

default/irodori を仮想的なIrodori音声に解決します。

Irodori-TTSは固定の話者IDを持たないため、指定された話者名が default またはそのエイリアスであれば、仮想的なIrodori-TTS音声として扱われます。

  • 引数:

    • speaker_name: 解決する話者名。

    • voices_info: 利用可能な音声情報のリスト。Noneの場合は get_available_voices_info() から取得されます。

    • model: tkttsインターフェース互換性のため。実際には使用されません。

  • 戻り値:

    • tuple[list[dict[str, str]], str]: (voices_info, 解決された話者名) のタプル。

  • 例外:

    • ValueError: 話者名が見つからない場合。

speak(outfile, text, voice=DEFAULT_IRODORI_VOICE, speak_rate=None, speak_pitch=None, *, caption=DEFAULT_CAPTION, ref_wav=None, ref_wavs=None, model=None, model_id=DEFAULT_IRODORI_MODEL, device=DEFAULT_DEVICE, precision=DEFAULT_PRECISION, codec_device=None, codec_precision=None, num_steps=DEFAULT_NUM_STEPS, cfg_scale_text=DEFAULT_CFG_SCALE_TEXT, cfg_scale_caption=DEFAULT_CFG_SCALE_CAPTION, cfg_scale_speaker=DEFAULT_CFG_SCALE_SPEAKER, duration_scale=1.0, seed=DEFAULT_SEED, lora_adapter=None)

Irodori-TTS v4.1-Smallを使用して1つのWAVファイルを生成します。

テキストを音声に変換し、指定された出力ファイルに保存します。Irodori-TTSは固定話者を持たないため、voice 引数は主に情報として扱われます。音声のスタイルや同一性は、caption および/または ref_wav/ref_wavs を使用して制御されます。

  • 引数:

    • outfile: 生成されたWAVファイルを保存するパス。

    • text: 読み上げるテキスト。

    • voice: 読み上げに使用する音声名。Irodori-TTSでは仮想的な音声であり、 default が推奨されます。デフォルトは DEFAULT_IRODORI_VOICE。

    • speak_rate: 音声の速さ。Irodori-TTSでは直接制御できないため無視されます。

    • speak_pitch: 音声のピッチ。Irodori-TTSでは直接制御できないため無視されます。

    • caption: 音声のスタイルを制御するためのキャプション。例: "落ち着いた自然な声で、明瞭に読み上げる。"。デフォルトは DEFAULT_CAPTION。

    • ref_wav: スタイル参照に使用する単一のWAVファイルのパス。 ref_wavs と同時に指定された場合、結合されます。

    • ref_wavs: スタイル参照に使用する複数のWAVファイルのパスのイテラブルまたはセミコロン区切りの文字列。

    • model: ロード済みのIrodori-TTSランタイムインスタンス。指定されない場合、 load_model を使って新規にロードされます。

    • model_id: ロードするIrodori-TTSモデルID (model がNoneの場合にのみ使用されます)。デフォルトは DEFAULT_IRODORI_MODEL。

    • device: モデルの推論に使用するデバイス (model がNoneの場合にのみ使用されます)。デフォルトは DEFAULT_DEVICE。

    • precision: モデルの推論に使用する精度 (model がNoneの場合にのみ使用されます)。デフォルトは DEFAULT_PRECISION。

    • codec_device: コーデックの推論に使用するデバイス (model がNoneの場合にのみ使用されます)。

    • codec_precision: コーデックの推論に使用する精度 (model がNoneの場合にのみ使用されます)。

    • num_steps: サンプリングステップ数。デフォルトは DEFAULT_NUM_STEPS。

    • cfg_scale_text: テキストに対するCFGスケール。デフォルトは DEFAULT_CFG_SCALE_TEXT。

    • cfg_scale_caption: キャプションに対するCFGスケール。デフォルトは DEFAULT_CFG_SCALE_CAPTION。

    • cfg_scale_speaker: 話者に対するCFGスケール (参照WAVがある場合のみ有効)。デフォルトは DEFAULT_CFG_SCALE_SPEAKER。

    • duration_scale: 音声の全体的な長さを調整するスケールファクター。デフォルトは 1.0。

    • seed: 乱数シード。None, "random" または空文字列の場合、シードはランダムに生成されます。デフォルトは DEFAULT_SEED。

    • lora_adapter: 使用するLoRAアダプターのパス。

  • 戻り値:

    • str | None: 生成されたWAVファイルの絶対パス。生成に失敗した場合はNone。

speak_dialogue(dialogue, replacements, target_voices, speakers=None, temp_dir='.', outfile=None, ext='wav', cfg=None, *, caption=None, ref_wav=None, ref_wavs=None, model=None, model_id=DEFAULT_IRODORI_MODEL, device=DEFAULT_DEVICE, precision=DEFAULT_PRECISION)

tkttsダイアログシーケンスのための一時WAVファイルを生成します。

与えられたダイアログ(会話のリスト)を処理し、各発話に対してIrodori-TTSを使用して一時的なWAVファイルを生成します。cfg オブジェクトを介してIrodori-TTS固有のパラメータ(例: irodori_caption, irodori_seed)を細かく制御できます。

  • 引数:

    • dialogue: 処理するダイアログアイテムのリスト。各アイテムは split_dialogue が処理できる形式です。

    • replacements: テキストに適用する置換辞書。

    • target_voices: ターゲットとする音声名のリストまたは単一の音声名。

    • speakers: 話者IDと音声名のマッピング辞書。デフォルトは空の辞書。

    • temp_dir: 一時的なWAVファイルを保存するディレクトリ。デフォルトはカレントディレクトリ。

    • outfile: tkttsインターフェース互換性のため。実際には使用されません。

    • ext: 生成される音声ファイルの拡張子。デフォルトは "wav"。

    • cfg: 設定オブジェクト。このオブジェクトの属性(例: cfg.irodori_caption)を通じて、Irodori-TTSの各種パラメータをオーバーライドできます。

    • caption: 音声のスタイルを制御するためのキャプション。 cfg.irodori_caption が設定されている場合はそちらが優先されます。

    • ref_wav: スタイル参照に使用する単一のWAVファイルのパス。 cfg.irodori_ref_wav が設定されている場合はそちらが優先されます。

    • ref_wavs: スタイル参照に使用する複数のWAVファイルのパス。 cfg.irodori_ref_wavs が設定されている場合はそちらが優先されます。

    • model: ロード済みのIrodori-TTSランタイムインスタンス。指定されない場合、 load_model を使って新規にロードされます。

    • model_id: ロードするIrodori-TTSモデルID (model がNoneの場合にのみ使用されます)。 cfg.irodori_model_id が設定されている場合はそちらが優先されます。

    • device: モデルの推論に使用するデバイス (model がNoneの場合にのみ使用されます)。 cfg.irodori_device が設定されている場合はそちらが優先されます。

    • precision: モデルの推論に使用する精度 (model がNoneの場合にのみ使用されます)。 cfg.irodori_precision が設定されている場合はそちらが優先されます。

    • codec_device: コーデックの推論に使用するデバイス (model がNoneの場合にのみ使用されます)。 cfg.irodori_codec_device が設定されている場合はそちらが優先されます。

    • codec_precision: コーデックの推論に使用する精度 (model がNoneの場合にのみ使用されます)。 cfg.irodori_codec_precision が設定されている場合はそちらが優先されます。

  • 戻り値:

    • tuple[bool, list[str]]: 生成が成功したかを示す真偽値と、生成された一時ファイルのパスのリストのタプル。

main scriptとして実行したときの動作

tktts_irodori.py をメインスクリプトとして直接実行した場合(例: python tktts_irodori.py)、list_available_voices() 関数が呼び出されます。

この関数は、現在利用可能な Irodori-TTS の仮想的な音声エントリをコンソールに表示します。Irodori-TTSは固定された話者リストを持たないため、これはIrodori-TTSがサポートする「デフォルト」の音声構成に関する情報を提供します。

=== 利用可能な irodori voices ===
  Name: default, Description: Irodori-TTS voice. Use irodori_caption and/or reference WAV files to define voice identity and speaking style.