tktts_irodori.py ドキュメント
ライブラリの機能や目的
tktts_irodori.py は、tktts ライブラリ群の一部として、Irodori-TTSのバックエンド機能を提供します。このモジュールは、tktts_voicevox.py や tktts_qwen3.py と同様のインターフェースに準拠しており、Irodori-TTSの公式 InferenceRuntime API を直接呼び出すことで音声合成を行います。これにより、Gradio UI や HTTP サーバーを別途実行する必要がありません。
ロードされたIrodori-TTSランタイムは内部でキャッシュされ、後続のすべての音声合成リクエストで再利用されるため、効率的な処理が可能です。
テキストの分割や読み方・発音の変換は意図的に呼び出し元に委ねられており、speak_dialogue 関数は他のバックエンドと同様に tktts によって渡される置換辞書を適用するのみです。
importする方法
このライブラリを他のPythonプログラムからインポートするには、以下のように記述します。
import tktts_irodori
# または特定の関数をインポート
from tktts_irodori import speak, speak_dialogue
必要な非標準ライブラリとインストール方法
tktts_irodori.py は以下の非標準ライブラリに依存しています。
torch: PyTorchライブラリ。ディープラーニングモデルの実行に必要です。
irodori_tts: Irodori-TTSの公式ライブラリ。音声合成のコア機能を提供します。
さらに、tktts ライブラリの基本機能を提供する tktts_base.py も必要となりますが、これは tktts ライブラリファミリーの一部として提供されることが想定されています。
これらのライブラリをインストールするには、Irodori-TTSの uv 環境内で以下のコマンドを実行することが推奨されます。
uv sync --extra cu128
もし uv 環境を使用しない場合は、pip を使用して個別にインストールできます。Irodori-TTSのインストール手順については、公式ドキュメントを参照してください。通常、GPUを最大限に活用するためにCUDA対応版のPyTorchをインストールすることをお勧めします。
pip install torch irodori-tts
importできる変数と関数
変数
tktts_irodori.py でimportできる主要な定数および変数です。
TTS_ENGINE_NAME:このTTSエンジンの名前を表す文字列です。値は
"irodori"です。
DEFAULT_IRODORI_MODEL:デフォルトで使用されるIrodori-TTSモデルのHugging FaceリポジトリIDです。値は
"Aratako/Irodori-TTS-v4.1-Small"です。
DEFAULT_IRODORI_VOICE:Irodori-TTSで使用される仮想的なデフォルトボイス名です。値は
"default"です。
DEFAULT_CAPTION:音声合成時に使用されるデフォルトのキャプションです。これは音声のスタイルや感情を制御するために利用できます。値は
"落ち着いた自然な声で、明瞭に読み上げる。"です。
DEFAULT_DEVICE:デフォルトで使用される推論デバイスです。値は
"auto"で、Irodori-TTSが利用可能な最適なデバイス（例: CUDAまたはCPU）を自動的に選択します。
DEFAULT_PRECISION:デフォルトで使用される計算精度です。値は
"auto"で、デバイスに応じてbf16またはfp32が自動的に選択されます。
DEFAULT_NUM_STEPS:デフォルトのサンプリングステップ数です。音声合成の品質と速度に影響を与えます。値は
40です。
DEFAULT_CFG_SCALE_TEXT:テキスト条件付けのデフォルトCFG（Classifier-Free Guidance）スケールです。値は
3.5です。
DEFAULT_CFG_SCALE_CAPTION:キャプション条件付けのデフォルトCFGスケールです。値は
3.0です。
DEFAULT_CFG_SCALE_SPEAKER:話者条件付けのデフォルトCFGスケールです。値は
5.0です。
DEFAULT_SEED:音声合成に使用されるデフォルトの乱数シードです。値は
0です。
_AVAILABLE_VOICES:Irodori-TTSが提供する仮想的な声の情報を格納する内部リストです。Irodori-TTSは固定の話者リストを持たないため、「default」という仮想エントリが定義されています。この情報は
get_available_voices_info関数で利用されます。
関数
load_model(
model_id: str = DEFAULT_IRODORI_MODEL,
device: str = DEFAULT_DEVICE,
precision: str = DEFAULT_PRECISION,
*,
codec_device: str | None = None,
codec_precision: str | None = None,
force_reload: bool = False,
)
動作: Irodori-TTSの推論ランタイムをロードし、キャッシュします。すでにロードされている場合はキャッシュされたインスタンスを再利用します。
引数:
model_id(str): ロードするIrodori-TTSモデルのID（Hugging FaceリポジトリIDまたはローカルパス）。デフォルトはDEFAULT_IRODORI_MODEL。device(str): モデルが実行されるデバイス（例:"cuda","cpu","auto"）。デフォルトはDEFAULT_DEVICE。precision(str): モデルの計算精度（例:"bf16","fp32","auto"）。デフォルトはDEFAULT_PRECISION。codec_device(str | None): コーデックが実行されるデバイス。Noneの場合、deviceに従います。codec_precision(str | None): コーデックの計算精度。Noneの場合、precisionに従います。force_reload(bool):Trueに設定すると、既存のキャッシュされたランタイムをクリアし、強制的にモデルを再ロードします。
戻り値: ロードされたIrodori-TTSの
InferenceRuntimeオブジェクト。
unload_models() -> None
動作: Irodori-TTSによってキャッシュされたランタイムを解放し、利用可能な場合はCUDAメモリキャッシュをクリアします。
引数: なし
戻り値: なし
get_available_voices_info(model=None)
動作: Irodori-TTSが提供する仮想的なデフォルト音声の情報を返します。Irodori-TTSは固定の話者リストを持たず、音声の同一性は参照オーディオによって、スタイルはキャプションによって制御されるため、仮想的な「default」エントリが提供されます。
model引数はtkttsインターフェース互換性のために受け入れられますが、内部では使用されません。引数:
model:tkttsインターフェース互換性のためのダミー引数。
戻り値: 仮想的な音声情報を含む辞書のリスト。例:
[{"name": "default", "description": "..."}]
get_available_voices(model=None)
動作:
tkttsの音声セレクターと互換性のある音声名（仮想的なデフォルト音声名）のリストを返します。引数:
model:tkttsインターフェース互換性のためのダミー引数。
戻り値: 利用可能な音声名の文字列のリスト。例:
["default"]
list_available_voices(model=None) -> bool
動作: Irodori-TTSの仮想的な音声エントリを標準出力に表示します。
引数:
model:tkttsインターフェース互換性のためのダミー引数。
戻り値: 表示された音声エントリがあれば
True、なければFalse。
resolve_speaker_id(speaker_name, voices_info=None, model=None)
動作: 与えられた話者名（例:
"default","irodori"）を、Irodori-TTSの仮想的なデフォルト音声に解決します。Irodori-TTSは固定の話者を持たないため、ほとんどの入力はデフォルトに解決されます。引数:
speaker_name: 解決する話者の名前。voices_info: 利用可能な音声情報（通常はget_available_voices_info()の結果）。Noneの場合は内部で取得されます。model:tkttsインターフェース互換性のためのダミー引数。
戻り値:
(voices_info, 解決された話者名)のタプル。例外: 話者が見つからない場合、
ValueErrorを発生させます。
speak(
outfile,
text,
voice=DEFAULT_IRODORI_VOICE,
speak_rate=None,
speak_pitch=None,
*,
caption: str | None = DEFAULT_CAPTION,
ref_wav: str | os.PathLike | None = None,
ref_wavs: Iterable[str | os.PathLike] | str | None = None,
model=None,
model_id: str = DEFAULT_IRODORI_MODEL,
device: str = DEFAULT_DEVICE,
precision: str = DEFAULT_PRECISION,
codec_device: str | None = None,
codec_precision: str | None = None,
num_steps: int = DEFAULT_NUM_STEPS,
cfg_scale_text: float = DEFAULT_CFG_SCALE_TEXT,
cfg_scale_caption: float = DEFAULT_CFG_SCALE_CAPTION,
cfg_scale_speaker: float = DEFAULT_CFG_SCALE_SPEAKER,
duration_scale: float = 1.0,
seed: int | str | None = DEFAULT_SEED,
lora_adapter: str | None = None,
)
動作: 指定されたテキストをIrodori-TTS v4.1-Smallモデルを使用して音声合成し、WAVファイルとして出力します。
引数:
outfile: 生成されたWAVファイルの出力パス。text: 読み上げるテキスト文字列。voice: 使用する音声の名前。Irodori-TTSでは仮想的な"default"が主に使われます。speak_rate,speak_pitch: 音声の速度とピッチ。Irodori-TTSでは直接制御できないため無視されます。caption(str | None): 音声のスタイルを制御するためのキャプション。Noneの場合はDEFAULT_CAPTIONが使用されます。ref_wav(str | os.PathLike | None): 参照オーディオファイルへのパス。音声の同一性を制御するために使用されます。複数のファイルを指定することも可能です。ref_wavs(Iterable[str | os.PathLike] | str | None):ref_wavと同様に参照オーディオファイルを指定します。セミコロン区切りの文字列またはパスのイテラブルとして指定できます。model: 既にロードされたIrodori-TTSランタイムオブジェクト。Noneの場合、内部でload_modelが呼び出されます。model_id: モデルのID。modelがNoneの場合に使用されます。device,precision,codec_device,codec_precision:modelがNoneの場合、load_modelに渡されるデバイスと精度設定。num_steps: サンプリングステップ数。cfg_scale_text,cfg_scale_caption,cfg_scale_speaker: CFGスケール。duration_scale: 音声の全体的な長さを調整するスケールファクター。seed: 乱数シード。Noneの場合はランダムなシードが使用されます。lora_adapter: LoRAアダプターのパスまたはID。
戻り値: 生成されたWAVファイルのパス (
str)。テキストが空の場合や生成に失敗した場合はNone。
speak_dialogue(
dialogue,
replacements,
target_voices,
speakers=None,
temp_dir=".",
outfile=None,
ext="wav",
cfg=None,
*,
caption: str | None = None,
ref_wav: str | os.PathLike | None = None,
ref_wavs: Iterable[str | os.PathLike] | str | None = None,
model=None,
model_id: str = DEFAULT_IRODORI_MODEL,
device: str = DEFAULT_DEVICE,
precision: str = DEFAULT_PRECISION,
)
動作:
tkttsの対話シーケンスを受け取り、各セリフをIrodori-TTSで音声合成し、一時的なWAVファイルとして出力します。この関数は、tktts_baseのsplit_dialogueおよびapply_replacementsと連携します。引数:
dialogue: 読み上げる対話シーケンスのリスト。replacements: テキストに適用する置換辞書。target_voices: ターゲットとなる音声（speak関数に渡されます）。speakers: 話者名の辞書。temp_dir: 一時WAVファイルを保存するディレクトリ。デフォルトは"."。outfile:tkttsバックエンド互換性のためのダミー引数。ext: 出力する一時ファイルの拡張子。デフォルトは"wav"。cfg: グローバル設定オブジェクト（属性としてIrodori-TTS関連のパラメータを含むことができます）。caption,ref_wav,ref_wavs: 個々のspeak呼び出しに渡されるキャプションと参照WAVファイル。Noneの場合、cfgから値が取得される可能性があります。model,model_id,device,precision:load_modelおよびspeakに渡されるモデルとデバイス設定。
戻り値:
(成功フラグ: bool, 生成された一時ファイルのパスリスト: list[str])のタプル。
main scriptとして実行したときの動作
tktts_irodori.py をメインスクリプトとして直接実行した場合（例: python tktts_irodori.py）、list_available_voices() 関数が呼び出されます。
この動作により、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.