tktts_qwen3.py
このドキュメントは、Pythonライブラリ tktts_qwen3.py の機能、使用方法、および関連情報を提供します。
ライブラリの機能や目的
tktts_qwen3.py は、tktts_* ライブラリ群のためのQwen3-TTSバックエンドを提供するモジュールです。
このライブラリの主な目的は、tktts_voicevox.py と互換性のあるインターフェースを提供しながら、公式の qwen-tts Pythonパッケージを通じてQwen3-TTSをローカルで実行できるようにすることです。モデルは必要に応じてロードされ、一度ロードされるとキャッシュされるため、連続する呼び出しでモデルが再ロードされることはありません。これにより、音声合成の効率が向上します。
importする方法
このライブラリを他のPythonプログラムからインポートするには、以下のステートメントを使用します。
import tktts_qwen3
必要な非標準ライブラリとインストール方法
tktts_qwen3.py を実行するには、いくつかの非標準ライブラリが必要です。これらは pip コマンドを使用してインストールできます。
qwen-tts: Qwen3-TTSモデルを操作するための主要なライブラリです。torch: PyTorchディープラーニングフレームワーク。Qwen3-TTSのバックエンドとして必要です。soundfile: 音声ファイルを読み書きするためのライブラリです。
これらのライブラリは、以下のコマンドでインストールできます。
pip install qwen-tts soundfile torch
また、このライブラリは tktts_base.py に依存しています。tktts_base.py は、このライブラリと同じディレクトリまたはPythonのパスからインポート可能である必要があります。
importできる変数と関数
変数
このモジュールからインポートできる主な変数は以下の通りです。
TTS_ENGINE_NAME:TTSエンジンの名前を表す文字列。デフォルト値は
"qwen3"です。
DEFAULT_QWEN3_MODEL:Qwen3-TTSモデルのデフォルトIDを表す文字列。モデルはHugging Face Hubからロードされます。デフォルト値は
"Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice"です。
DEFAULT_QWEN3_VOICE:音声合成に使用するデフォルトの話者名を表す文字列。デフォルト値は
"Ono_Anna"です。
DEFAULT_LANGUAGE:音声合成に使用するデフォルトの言語を表す文字列。デフォルト値は
"Japanese"です。
DEFAULT_DEVICE:モデルをロードするデフォルトのデバイスを表す文字列。デフォルト値は
"auto"です。"auto"は、利用可能な場合はcuda:0(GPU)、そうでなければcpuに自動的に解決されます。
DEFAULT_DTYPE:モデルのデータ型を表す文字列または
torch.dtype。デフォルト値は"auto"です。"auto"は、デバイスに応じてtorch.bfloat16、torch.float16、またはtorch.float32に自動的に解決されます。
関数
このモジュールからインポートできる主な関数は以下の通りです。
load_model(model_id: str = DEFAULT_QWEN3_MODEL, device: str = DEFAULT_DEVICE, dtype: str | torch.dtype = DEFAULT_DTYPE, *, force_reload: bool = False) -> Qwen3TTSModel
動作: Qwen3-TTSモデルをロードし、キャッシュします。FlashAttentionは意図的に要求されません。通常のPyTorchアテンションパスは、別途CUDA SDKをインストールしなくてもWindowsで動作します。
引数:
model_id(str): ロードするモデルのID。デフォルトはDEFAULT_QWEN3_MODELです。device(str): モデルをロードするデバイス。デフォルトはDEFAULT_DEVICEです。"auto"は利用可能なCUDAデバイスまたはCPUに解決されます。dtype(str |torch.dtype): モデルのデータ型。デフォルトはDEFAULT_DTYPEです。"auto"はデバイスに応じて適切なデータ型に解決されます。force_reload(bool):Trueの場合、キャッシュされているモデルを強制的に再ロードします。デフォルトはFalseです。
戻り値: ロードされた
Qwen3TTSModelのインスタンス。
unload_models() -> None
動作: このモジュールによってキャッシュされたすべてのモデルを解放します。利用可能な場合はCUDAキャッシュをクリアします。
引数: なし。
戻り値: なし。
get_available_voices_info(model: Qwen3TTSModel | None = None)
動作: 利用可能な話者名とその説明を返します。モデルインスタンスが提供された場合、そのモデルが報告する話者リストが使用されるため、将来のCustomVoiceチェックポイントとの互換性が保たれます。
引数:
model(Qwen3TTSModel| None): モデルインスタンス。デフォルトはNoneです。
戻り値: 話者の情報を含む辞書のリスト。各辞書は
"name","native_language","description"のキーを含みます。
get_available_voices(model: Qwen3TTSModel | None = None)
動作: 利用可能な話者名のリストを返します。
引数:
model(Qwen3TTSModel| None): モデルインスタンス。デフォルトはNoneです。
戻り値: 利用可能な話者名の文字列リスト。
list_available_voices(model: Qwen3TTSModel | None = None) -> bool
動作: 利用可能な話者をコンソールに出力します。
引数:
model(Qwen3TTSModel| None): モデルインスタンス。デフォルトはNoneです。
戻り値: 話者が出力された場合は
True、そうでなければFalse。
resolve_speaker_id(speaker_name: str, voices_info=None, model: Qwen3TTSModel | None = None)
動作: 完全または部分的な話者名を、Qwen3-TTSが認識する話者名に解決します。
引数:
speaker_name(str): 解決したい話者名。voices_info: 利用可能な話者情報のリスト。デフォルトはNoneで、その場合はget_available_voices_info()を使用します。model(Qwen3TTSModel| None): モデルインスタンス。デフォルトはNoneです。
戻り値:
(voices_info, target_voice_name)のタプル。target_voice_nameは解決された話者名です。例外: 話者名が空の場合、または見つからない場合に
ValueErrorを発生させます。
speak(outfile, text, voice=DEFAULT_QWEN3_VOICE, speak_rate=None, speak_pitch=None, *, language: str = DEFAULT_LANGUAGE, model: Qwen3TTSModel | None = None, model_id: str = DEFAULT_QWEN3_MODEL, device: str = DEFAULT_DEVICE, dtype: str | torch.dtype = DEFAULT_DTYPE, instruct: str | None = None)
動作: Qwen3-TTS CustomVoiceモデルを使用して、一つの音声ファイルを生成します。
speak_rateとspeak_pitchはtktts_voicevoxとのインターフェース互換性のために保持されていますが、CustomVoiceでは同等のパラメータが公開されていないため、非デフォルト値は現在無視されます。引数:
outfile: 生成された音声ファイルを保存するパス。text: 読み上げるテキスト。voice: 使用する話者名。デフォルトはDEFAULT_QWEN3_VOICEです。speak_rate: 読み上げ速度。互換性のため保持されていますが、Qwen3-TTS CustomVoiceでは無視されます。speak_pitch: 読み上げピッチ。互換性のため保持されていますが、Qwen3-TTS CustomVoiceでは無視されます。language(str): テキストの言語。デフォルトはDEFAULT_LANGUAGEです。model(Qwen3TTSModel| None): モデルインスタンス。デフォルトはNoneで、その場合はload_modelを呼び出してモデルをロードします。model_id(str): ロードするモデルのID。デフォルトはDEFAULT_QWEN3_MODELです。device(str): モデルをロードするデバイス。デフォルトはDEFAULT_DEVICEです。dtype(str |torch.dtype): モデルのデータ型。デフォルトはDEFAULT_DTYPEです。instruct(str | None): Qwen3-TTSモデルに渡す指示文字列。デフォルトはNoneです。
戻り値: 生成された音声ファイルのパス (str)、またはエラーの場合は
None。
speak_dialogue(dialogue, replacements, target_voices, speakers=None, temp_dir=".", outfile=None, ext="wav", cfg=None, *, language: str = DEFAULT_LANGUAGE, model: Qwen3TTSModel | None = None, model_id: str = DEFAULT_QWEN3_MODEL, device: str = DEFAULT_DEVICE, dtype: str | torch.dtype = DEFAULT_DTYPE)
動作:
tkttsのダイアログシーケンスに対して一時的な音声ファイルを生成します。引数:
dialogue: ダイアログアイテムのリスト。各アイテムはテキストと話者情報を含みます。replacements: テキスト置換ルールを定義する辞書。target_voices: ダイアログ内で使用するターゲット話者の情報。speakers: 話者名のマッピング。デフォルトは{}です。temp_dir: 一時ファイルを保存するディレクトリ。デフォルトは"."です。outfile: 互換性のために署名に残されていますが、この関数では無視されます。ext: 出力音声ファイルの拡張子。デフォルトは"wav"です。cfg: 設定オブジェクト。fspeak_rate,fspeak_pitch,qwen3_instruct,monologueなどの属性を持つことが期待されます。language(str): テキストの言語。デフォルトはDEFAULT_LANGUAGEです。model(Qwen3TTSModel| None): モデルインスタンス。デフォルトはNoneで、その場合はload_modelを呼び出してモデルをロードします。model_id(str): ロードするモデルのID。デフォルトはDEFAULT_QWEN3_MODELです。device(str): モデルをロードするデバイス。デフォルトはDEFAULT_DEVICEです。dtype(str |torch.dtype): モデルのデータ型。デフォルトはDEFAULT_DTYPEです。
戻り値:
(success, list_of_tmpfiles)のタプル。successはTrueまたはFalse(音声生成が成功したかどうか)、list_of_tmpfilesは生成された一時ファイルのパスのリストです。
main scriptとして実行したときの動作
tktts_qwen3.py がメインスクリプトとして直接実行された場合（例: python tktts_qwen3.py）、list_available_voices() 関数が呼び出されます。
これにより、Qwen3-TTSモデルで利用可能な話者名、話者の母国語、および簡単な説明がコンソールに一覧表示されます。これは、スクリプトが正しく動作し、利用可能な話者を素早く確認するための便利な方法です。
=== 利用可能な qwen3 voices ===
Name: Vivian, Native language: Chinese, Description: Bright, slightly edgy young female voice
Name: Serena, Native language: Chinese, Description: Warm, gentle young female voice
Name: Uncle_Fu, Native language: Chinese, Description: Seasoned male voice with a low, mellow timbre
Name: Dylan, Native language: Chinese, Description: Youthful Beijing male voice with a clear timbre
Name: Eric, Native language: Chinese, Description: Lively Chengdu male voice with husky brightness
Name: Ryan, Native language: English, Description: Dynamic male voice with strong rhythmic drive
Name: Aiden, Native language: English, Description: Sunny American male voice with a clear midrange
Name: Ono_Anna, Native language: Japanese, Description: Playful Japanese female voice with a light timbre
Name: Sohee, Native language: Korean, Description: Warm Korean female voice with rich emotion