tktts_winrt.py 技術ドキュメント
ライブラリの機能や目的
tktts_winrt.pyは、tkttsライブラリのバックエンドとして設計されたPythonモジュールです。特にWindows環境での音声合成に特化しており、Windows.Media.SpeechSynthesis機能をPythonのwinsdkパッケージを介して利用します。
このライブラリの主な目的と機能は以下の通りです。
WinRTバックエンド:
tkttsの他のバックエンド（例:tktts_pyttsx3.py）と同様に、ドロップイン形式で利用できるWinRT（Windows Runtime）ベースの音声合成機能を提供します。WAVオーディオストリームの生成: WinRTのSpeechSynthesizerを使用して、テキストからWAV形式のオーディオストリームを生成し、これをファイルとして保存したり、直接再生したりできます。
レートの互換性: 発話レート(
speak_rate)は、pyttsx3のようなWPM（Words Per Minute）形式（150WPMが1.0倍速に相当）と、WinRTの相対レート（1.0が通常速度）の両方に対応するよう変換されます。音声の選択: システムにインストールされている利用可能なWinRT音声（例: 「Nanami」などの日本語音声）を列挙し、名前、ID、言語などによる部分一致で選択する機能を提供します。
対話形式の音声合成: 複数の話し手による対話形式のテキストブロックを解析し、それぞれの話し手に応じた音声で合成する機能を持っています。
Windows専用:
winsdkパッケージとWinRT APIを使用するため、本ライブラリはWindowsオペレーティングシステム上でのみ動作します。
本ライブラリは、Windows環境で高品質なシステム組み込みの音声合成機能を手軽に利用し、テキストから音声ファイルを生成したり、即座に再生したりする課題を解決します。
importする方法
tktts_winrt.pyを他のPythonプログラムからインポートするには、通常の方法でモジュールをインポートします。
import tktts_winrt
特定の関数や変数を直接インポートすることも可能です。
from tktts_winrt import speak, list_available_voices, TTS_ENGINE_NAME
必要な非標準ライブラリとインストール方法
tktts_winrt.pyが動作するためには、以下の非標準ライブラリが必要です。
winsdk: Windows Runtime APIへのPythonバインディングを提供します。
インストール方法
winsdkパッケージはpipを使用してインストールできます。コマンドプロンプトやターミナルで以下のコマンドを実行してください。
pip install winsdk
このライブラリはWindows固有の機能に依存しているため、Windows以外のオペレーティングシステムでは動作しません。
importできる変数と関数
このセクションでは、tktts_winrt.pyから外部に公開されている主要な変数と関数、および内部で利用される重要な関数について説明します。
グローバル変数
TTS_ENGINE_NAME:str音声合成エンジンの名前を表す文字列です。このライブラリでは
"winrt"となります。
DEFAULT_WINRT_VOICE:strWinRT音声合成でデフォルトとして使用される音声の名前です。通常は
"Nanami"ですが、システムにその音声がない場合はフォールバックロジックにより他の音声が選択されます。
DEFAULT_PYTTSX3_COMPAT_RATE:floatpyttsx3互換の発話レート（WPM: Words Per Minute）のデフォルト値です。通常は \(150.0\) WPMが標準速度 \(1.0\) 倍として扱われます。
公開関数
get_available_voices_info()動作: 利用可能なWinRT音声に関する詳細情報を辞書のリストとして返します。各辞書には、音声の
name、id、lang、gender、descriptionが含まれます。引数: なし
戻り値:
list[dict[str, Any]]: 利用可能な音声情報のリスト。False: 初期化またはインポートに失敗した場合。
get_available_voices()動作: 利用可能なWinRT音声の名前のリストを返します。
引数: なし
戻り値:
list[str]: 利用可能な音声名のリスト。False: 初期化またはインポートに失敗した場合。
list_available_voices()動作: 利用可能なWinRT音声のリストと詳細情報をコンソールに出力します。
引数: なし
戻り値:
True: 正常に情報を出力した場合。False: 初期化またはインポートに失敗した場合。
speak(outfile: str | None, text: str, voice: str | None, speak_rate: float | int | None = None)動作: 指定されたテキストを発話するか、WAVファイルとして保存します。
outfileが指定された場合、テキストはWAVファイルとして保存されます。outfileがNoneまたは空文字列の場合、一時的なWAVファイルが生成され、winsoundモジュールを使用して再生されます。
引数:
outfile:str | None- 出力WAVファイルのパス。指定しない場合は再生モードとなります。text:str- 発話または保存するテキスト。voice:str | None- 使用する音声の名前、ID、または言語。Noneの場合、DEFAULT_WINRT_VOICEが使用されます。speak_rate:float | int | None- 発話レート。pyttsx3互換のWPM（\(150\)が標準）またはWinRT相対レート（\(1.0\)が標準）として解釈されます。
戻り値:
str | None: ファイル保存モードの場合、保存されたファイルのパス（成功時）またはNone（失敗時）。bool: 再生モードの場合、再生の成否。
speak_dialogue(dialogue: Any, replacements: Any, target_voices: Any, speakers: dict = {}, speak_rate: float | int = 150, temp_dir: str | None = None, outfile: str | None = None, ext: str = "wav", cfg: Any = None)動作: 対話ブロック内のテキストに対して音声ファイルを生成します。
tktts_pyttsx3.speak_dialogue()と同様の機能を提供します。WinRTのAPIが非同期ストリームベースであるため、各発話は個別に合成されます。outfileが指定された場合、各発話の一時ファイルがtemp_dirに生成され、そのリストが返されます。outfileが指定されない場合、すべてのテキストが結合され、一度に再生されます。
引数:
dialogue:Any- 対話テキストのリストまたはイテラブル。replacements:Any- テキスト置換ルール。target_voices:Any- 話し手と音声のマッピング。speakers:dict- 話し手の辞書。speak_rate:float | int- 発話レート。デフォルトは \(150\)。temp_dir:str | None- 一時ファイルが保存されるディレクトリ。Noneの場合、システムの標準一時ディレクトリが使用されます。outfile:str | None- 最終出力ファイルのパス。指定されない場合、音声は再生されます。ext:str- 生成される一時ファイルの拡張子。WinRTはWAVを出力するため、"wav"に強制されます。cfg:Any- 設定オブジェクト。monologue属性を持つ場合、対話の処理に影響します。
戻り値:
(bool, list[str]): ファイル保存モードの場合、成否と生成された一時ファイルのパスのリスト。(bool, dict): 再生モードの場合、成否と空の辞書。
内部関数（通常は直接呼び出すことは想定されていません）
_import_winrt()動作:
winsdkパッケージのWinRTクラス（SpeechSynthesizer,Buffer,DataReader,InputStreamOptions）を遅延インポートします。これにより、モジュールインポート時にwinsdkがない環境やWindows以外のOSでエラーとなるのを防ぎます。引数: なし
戻り値:
tuple- インポートされたWinRTクラスのタプル。
_run_async(coro: Any)動作: 非同期コルーチンを同期コードから実行します。すでにイベントループが実行中の場合は、新しいスレッドでコルーチンを実行することで
RuntimeError（"There is already a running event loop"）を回避します。引数:
coro:Any- 実行する非同期コルーチンオブジェクト。
戻り値: コルーチンの結果。
_safe_attr(obj: Any, name: str, default: Any = "")動作: オブジェクトから指定された属性を安全に取得します。属性が存在しない、または取得中にエラーが発生した場合は、デフォルト値を返します。
引数:
obj:Any- 属性を取得するオブジェクト。name:str- 取得する属性の名前。default:Any- 属性が見つからない場合に返すデフォルト値。
戻り値: 属性の値またはデフォルト値。
_voice_gender_text(voice: Any)動作: WinRTの音声オブジェクトから性別情報を文字列として取得します。
引数:
voice:Any- WinRTのVoiceInformationオブジェクト。
戻り値:
str- 性別を表す文字列。
_voice_to_dict(voice: Any)動作: WinRTの
VoiceInformationオブジェクトを、pyttsx3の音声情報に似た辞書形式に変換します。引数:
voice:Any- WinRTのVoiceInformationオブジェクト。
戻り値:
dict[str, Any]- 音声情報の辞書。
_voice_match_text(voice: Any)動作: 音声のマッチングに使用するために、音声情報を結合した小文字のテキスト文字列を生成します。
引数:
voice:Any- WinRTのVoiceInformationオブジェクト。
戻り値:
str- マッチング用のテキスト。
_select_voice(synthesizer: Any, target_voice: str | None)動作: 指定された
SpeechSynthesizerオブジェクトに対して、target_voiceに最もよく一致するWinRT音声を選択して設定します。表示名、ID、言語、性別、説明などから部分一致を試みます。引数:
synthesizer:Any- WinRTのSpeechSynthesizerオブジェクト。target_voice:str | None- 選択したい音声の名前、ID、言語などの部分文字列。
戻り値:
Any- 選択されたWinRTのVoiceInformationオブジェクト、またはシステムデフォルトの音声。
_convert_speak_rate(speak_rate: float | int | None)動作:
pyttsx3のようなWPM形式の発話レートを、WinRTが解釈する相対レート（\(1.0\)が通常速度）に変換します。\(10.0\)より大きい値はWPMとして解釈されます。引数:
speak_rate:float | int | None- 入力レート。
戻り値:
float- WinRT互換の相対レート（\(0.5\)～\(6.0\)の範囲に制限されます）。
_stream_to_bytes(stream: Any)動作: WinRTの
SpeechSynthesisStreamオブジェクトから音声データを読み込み、バイト列に変換します。引数:
stream:Any- WinRTのSpeechSynthesisStreamオブジェクト。
戻り値:
bytes- ストリームから読み込まれたWAVデータ。
_synthesize_wav_bytes(text: str, target_voice: str | None, speak_rate: float | int | None)動作: 指定されたテキスト、音声、レートで音声を合成し、WAV形式のバイト列として返します。これは非同期関数です。
引数:
text:str- 合成するテキスト。target_voice:str | None- 使用する音声。speak_rate:float | int | None- 発話レート。
戻り値:
bytes- 合成されたWAVデータ。
_write_wav(outfile: str, text: str, target_voice: str | None, speak_rate: float | int | None)動作: 指定されたテキストを音声合成し、WAVファイルとして保存します。
引数:
outfile:str- 出力ファイルのパス。text:str- 合成するテキスト。target_voice:str | None- 使用する音声。speak_rate:float | int | None- 発話レート。
戻り値:
str | None- 成功した場合にファイルのパス、失敗した場合にNone。
_play_wav_file(wavfile: str)動作: 指定されたWAVファイルを
winsoundモジュールを使用して再生します。Windows環境でのみ動作します。引数:
wavfile:str- 再生するWAVファイルのパス。
戻り値:
bool- 再生の成否。
main scriptとして実行したときの動作
tktts_winrt.pyをPythonスクリプトとして直接実行すると、コマンドライン引数に基づいてWinRT音声合成のテストを実行します。これは、利用可能な音声のリスト表示、指定されたテキストの発話、またはWAVファイルへの保存機能を提供します。
コマンドライン引数
以下の引数が利用可能です。
--list {0, 1}:1を指定すると、利用可能なWinRT音声のリストを表示します。デフォルトは
0（リスト表示しない）。
--voice TEXT:使用する音声の名前、ID、または言語の部分一致を指定します。
デフォルトは
DEFAULT_WINRT_VOICE(通常 "Nanami")。
--text TEXT:発話または保存するテキストを指定します。
デフォルトは
"こんにちは。これは WinRT 音声合成のテストです。"。
--outfile TEXT:出力WAVファイルのパスを指定します。この引数を省略すると、音声は直接再生されます。
デフォルトは
""（ファイル出力なし、再生）。
--rate FLOAT:発話レートを指定します。
pyttsx3のようなWPM（例: \(150.0\)）またはWinRTの相対レートとして解釈されます。デフォルトは \(150.0\)。
実行例
利用可能な音声のリストを表示する:
python tktts_winrt.py --list 1
デフォルトの音声でテキストを再生する:
python tktts_winrt.py --text "Hello, this is a test of WinRT speech synthesis."
特定の音声でテキストを再生する:
python tktts_winrt.py --text "こんにちは、ななみです。" --voice "Nanami"
特定の音声でテキストをWAVファイルに保存する:
python tktts_winrt.py --text "Save this speech to a file." --voice "Microsoft Zira" --outfile output.wav
発話レートを変更して再生する:
python tktts_winrt.py --text "This is a slower speech." --rate 100 python tktts_winrt.py --text "This is a faster speech." --rate 200