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

このドキュメントは、Pythonライブラリ tktts.py の機能、使い方、および内部構造について説明します。

ライブラリの機能や目的

tktts.py は、複数のText-to-Speech（TTS）エンジンを抽象化し、統一されたインターフェースを通じて音声合成を行うためのPythonライブラリです。様々なTTSバックエンド（例えば、pyttsx3、WindowsのWinRT、VOICEVOX、Qwen3、Irodori TTS、AquesTalk Player、OpenAI、ElevenLabs、Gemini）をサポートしており、ユーザーは簡単な設定でこれらのエンジンを切り替えて利用できます。

主な機能

  • マルチTTSエンジンサポート: 複数のTTSエンジンを動的にインポートし、利用可能なものを登録します。各エンジンのオプション依存関係は、利用時まで遅延ロードされます。

  • テキスト入力の柔軟性: クリップボードまたは指定されたテキストファイルから、モノローグ（独話）またはダイアログ（対話）形式のテキストを読み込みます。

  • 話者と音声のマッピング: 対話形式のテキストから話者を抽出し、各話者に特定のTTSエンジンと音声（ボイス）を割り当てる機能を提供します。

  • 音声合成と結合: 各話者のテキストを個別に音声合成し、必要に応じて複数の音声ファイルを結合して一つのオーディオファイルとして出力します。

  • 一時ファイルの管理: 音声合成中に生成される一時ファイルを効率的に管理し、処理完了後に自動的にクリーンアップします。

  • 音声情報の取得: 各TTSエンジンが利用可能な音声の一覧や詳細情報を取得する機能を提供します。

解決する課題

このライブラリは、異なるTTSエンジンを使用するアプリケーション開発者が直面する以下の課題を解決します。

  • APIの複雑性: 各TTSエンジンが持つ異なるAPIや設定方法を統一されたインターフェースでラップし、開発の複雑さを軽減します。

  • エンジン選択の柔軟性: ユーザーがアプリケーション内で簡単にTTSエンジンを切り替えられるようにし、多様な要件に対応できるようにします。

  • 対話テキストの処理: 複数の話者が登場する対話形式のテキストに対して、話者ごとに異なる音声を設定し、自然な会話として合成するプロセスを簡素化します。

  • 環境依存性の管理: 各TTSエンジンの依存ライブラリをオプションとして扱い、特定の環境で利用可能なエンジンのみを安全にロードすることで、ライブラリ全体の堅牢性を高めます。

importする方法

tktts.py はPythonモジュールとして設計されています。このライブラリを他のPythonプログラムから利用するには、標準的な import ステートメントを使用します。

# ライブラリ全体をインポートする場合
import tktts

# tkTTS クラスのみをインポートする場合
from tktts import tkTTS

このファイルを tktts.py という名前で保存し、import するPythonスクリプトと同じディレクトリ、またはPythonのパスが通っているディレクトリに配置してください。

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

tktts.py はいくつかの非標準ライブラリと外部ツールに依存しています。

必須のコアライブラリ

以下のPythonライブラリは tktts.py の基本的な機能に必須です。

  • pydub: 音声ファイルの操作（結合、形式変換など）に必要です。

  • pyperclip: クリップボードからのテキスト取得に必要です。

  • chardet: テキストファイルのエンコーディング検出に必要です。

これらは pip を使ってインストールできます。

pip install pydub pyperclip chardet

必須の外部ツール

  • FFmpeg: 音声ファイルの結合や形式変換に不可欠な外部ツールです。tktts.py はシステムPATHにFFmpegが設定されていることを前提としています。

    インストール方法:

    1. FFmpegの公式サイト (https://ffmpeg.org/download.html) からお使いのOSに応じたバイナリをダウンロードします。

    2. ダウンロードしたファイルを解凍し、ffmpeg および ffprobe 実行ファイルが含まれるディレクトリをシステム環境変数 PATH に追加してください。

    tktts.py がインポートされる際に、FFmpegの存在がチェックされ、見つからない場合はエラーで終了します。

オプションのTTSバックエンドライブラリ

tktts.py は、以下のTTSエンジンをサポートしていますが、それぞれのライブラリは必要に応じてインストールします。これらは必須ではありませんが、特定のTTSエンジンを利用したい場合に必要となります。

  • pyttsx3: OSに組み込まれたTTSエンジン（Windows SAPI5, macOS NSSpeechSynthesizer, Linux eSpeak）を利用します。

    pip install pyttsx3

  • winsdk (WinRT/OneCore TTS): Windows環境で利用可能な高品質なTTSエンジンです。

    pip install winsdk

  • VOICEVOX: 日本語に特化した高品質な音声合成ソフトウェアVOICEVOXのエンジンを利用します。

    • Pythonライブラリとしては直接指定されていませんが、tktts_voicevox モジュールがVOICEVOXのAPIにアクセスします。VOICEVOXのサーバーが別途実行されている必要があります。

  • Qwen3 (qwen_tts): Alibaba Cloudが提供するQwen-Audioモデルの一部であるTTS機能を利用します。

    pip install qwen_tts

  • Irodori TTS (irodori_tts): 多様な感情表現を持つ日本語音声合成エンジンです。

    pip install irodori_tts

  • AquesTalk Player (tktts_aquestalkplayer): AquesTalkの音声合成エンジンを利用します。

    • Pythonライブラリとしては直接指定されていませんが、tktts_aquestalkplayer モジュールがAquesTalk Playerの実行ファイルにアクセスします。AquesTalk Playerのアプリケーションが別途インストールされている必要があります。

  • OpenAI (openai): OpenAIのテキスト読み上げAPIを利用します。

    pip install openai

  • ElevenLabs (elevenlabs): ElevenLabsの高品質な音声合成APIを利用します。

    pip install elevenlabs

  • Gemini (google.genai): Google Geminiのテキスト読み上げAPIを利用します。

    pip install google-generativeai

importできる変数と関数

tktts.py ライブラリは、直接アクセス可能なグローバル変数、関数、および主要なクラス tkTTS を提供します。

グローバル変数

  • CORE_LIBS: 必須のコアライブラリ名（文字列）のリストです。ライブラリがロードされる際に、これらの存在がチェックされます。

    CORE_LIBS = ["pydub", "pyperclip", "chardet"]

  • default_pyttsx3_voice: pyttsx3 エンジン使用時のデフォルトの音声名（例: "Zira"）。

  • default_winrt_voice: WinRT エンジン使用時のデフォルトの音声名（例: "Ayumi"）。

  • default_voicevox_voice: VOICEVOX エンジン使用時のデフォルトの音声名（例: "四国めたん"）。

  • default_qwen3_voice: Qwen3 エンジン使用時のデフォルトの音声名（例: "Ono_Anna"）。

  • default_irodori_voice: Irodori TTS エンジン使用時のデフォルトの音声名（例: "default"）。

  • default_aqt_preset: AquesTalk Player エンジン使用時のデフォルトのプリセット名（例: "れいむ"）。

  • default_openai_voice: OpenAI エンジン使用時のデフォルトの音声名（例: "alloy"）。

  • default_optnai_voice: default_openai_voice と同じ。旧コードとの互換性のために残されています。

  • default_elevenlabs_voice: ElevenLabs エンジン使用時のデフォルトの音声名（例: "Rachel"）。

  • default_gemini_voice: Gemini エンジン使用時のデフォルトの音声名（例: "Kore"）。

  • TTS_ENGINES: 各TTSエンジンの設定を保持する辞書です。キーはエンジン名（文字列）、値はそのエンジンの設定を含む辞書です。設定には、エンジンのモジュール ("engine")、デフォルト音声 ("default_voice")、出力拡張子 ("ext")、直接再生の可否 ("direct_playback") などが含まれます。

関数

  • check_ffmpeg_available() -> bool: システムに ffmpeg と ffprobe が存在するかを確認します。 存在する場合は True を、見つからない場合は False を返します。

  • _safe_import(module_name: str, dependency: Optional[str] = None) -> Any: オプションのTTSバックエンドモジュールを安全にインポートします。 dependency が指定されており、それがインストールされていない場合は、モジュールのインポートをスキップし None を返します。 インポート中に SystemExit やその他の例外が発生した場合も None を返し、警告メッセージを出力します。

  • get_available_engines(available_only: bool = True) -> List[str]: 現在登録されているTTSエンジン名のリストを返します。 available_only が True の場合、正常にインポートされ利用可能なエンジンのみを返します。False の場合は、登録されているすべてのエンジン名を返します。

  • _supported_kwargs(func: Callable, kwargs: Dict[str, Any]) -> Dict[str, Any]: 指定された関数 func が受け取れるキーワード引数 (kwargs) のみを抽出し、辞書として返します。 これにより、バックエンド関数のシグネチャに存在しない引数を誤って渡すことを防ぎます。

  • _call_backend(func: Callable, **kwargs) -> Any: _supported_kwargs を使用して引数をフィルタリングした後、指定されたバックエンド関数 func を呼び出すヘルパー関数です。

  • apply_replacements(text: str, replacements: Optional[Dict[str, str]]) -> str: 置換辞書 replacements を使用して、入力テキスト text 内の文字列を置換します。置換は大文字小文字を区別せずに行われます。

  • load_text(input_path: str, monologue: bool = False, wait_for_clipboard: bool = True) -> Optional[List[Tuple[Optional[str], str]]]: 指定された input_path からテキストを読み込みます。input_path が "clip" の場合、クリップボードからテキストを読み込みます。それ以外の場合はファイルから読み込みます。 monologue が True の場合、すべての行を単一話者のテキストとして扱います。 wait_for_clipboard が True の場合、クリップボードからの読み込み時にユーザーに入力を促します。 読み込まれたテキストは、(話者名, テキスト) のタプルリストとして返されます。話者名がない場合は None となります。

  • create_temp_dir(temp_dir: str) -> str: 指定されたパス temp_dir に一時ディレクトリを作成します。既に存在する場合は何もしません。作成されたディレクトリのパスを返します。

  • get_speaker_dict(tts_engine: str, dialogue: List[Tuple[Optional[str], str]], voices: Optional[str], ...) -> Optional[Dict[Optional[str], str]]: 対話リスト dialogue から話者名を抽出し、voices 引数で指定された情報に基づいて、各話者に割り当てる音声のマッピング辞書を作成します。 voices はセミコロン区切りの音声名リスト、または 話者名=音声名 形式の文字列です。 default_*_voice 引数は、各TTSエンジンのデフォルト音声名を指定するために使用されます。

  • get_tts(tts_engine: str) -> Any: 指定された tts_engine 名に対応するTTSバックエンドモジュールを返します。 エンジンが利用できない場合（未インポートまたは設定ミス）は None を返します。

  • get_available_voices_info(tts_engine: str, endpoint: Optional[str] = None, api_key: Optional[str] = None) -> Any: 指定されたTTSエンジン tts_engine が提供する利用可能な音声の詳細情報を取得します。 endpoint や api_key はクラウドベースのTTSサービスで必要となる場合があります。

  • get_available_voices(tts_engine: str, endpoint: Optional[str] = None, api_key: Optional[str] = None) -> Any: 指定されたTTSエンジン tts_engine が提供する利用可能な音声名のリストを取得します。 endpoint や api_key はクラウドベースのTTSサービスで必要となる場合があります。

  • list_available_voices(tts_engine: str, endpoint: Optional[str] = None, api_key: Optional[str] = None) -> bool: 指定されたTTSエンジン tts_engine の利用可能な音声情報をコンソールに出力します。 情報取得に成功した場合は True を、失敗した場合は False を返します。

  • normalize_speaker(speaker: Optional[str], tts_engine: Optional[str] = None) -> Optional[str]: 話者ラベルを正規化します。具体的には、話者名に含まれるスタイル表記（例: 話者（style））を除去し、空白文字をトリムします。

  • parse_kv_string(kv_string: Optional[str], keys: List[str] = [], allow_no_key_kv_string: bool = False) -> Dict[str, Any]: key=val;key=val 形式の文字列を辞書に変換します。 allow_no_key_kv_string が True の場合、= が含まれないアイテムもキーなしの値として処理し、keys リストのインデックスに基づいて割り当てを試みます。

  • _get_attr(args: Any, name: str, default: Any = None) -> Any: args オブジェクトから指定された name の属性を安全に取得します。属性が存在しない場合は default 値を返します。

  • _effective_pyttsx3_rate(args: Any) -> int: pyttsx3 エンジンのための実効的な音声速度を計算します。args オブジェクトの speak_rate と fspeak_rate (相対倍率) を考慮します。

  • _effective_winrt_rate(args: Any) -> Any: WinRT エンジンのための実効的な音声速度を計算します。args オブジェクトの fspeak_rate または speak_rate を使用します。

  • _elevenlabs_voice_settings(args: Any) -> Optional[Dict[str, Any]]: ElevenLabs エンジンのための音声設定（stability, similarity_boost など）を args オブジェクトから抽出し、辞書として返します。

  • _infer_output_format(outfile: str, requested_format: Optional[str], default_format: str) -> str: 出力ファイルパス outfile、要求された形式 requested_format、デフォルト形式 default_format に基づいて、最終的な出力ファイル形式を推測します。

  • speak_dialogue(args: Any, dialogue: List[Tuple[Optional[str], str]], voice_map: Optional[Union[Dict[Optional[str], str], str]] = None, ...) -> Union[str, bool]: ライブラリのコア機能であり、選択されたTTSエンジンで音声生成、結合、保存、または直接再生を行います。 args オブジェクトは、様々な設定（TTSエンジン、出力ファイル、話速、一時ディレクトリなど）を含みます。 dialogue は (話者名, テキスト) のタプルリストです。 voice_map は話者と音声のマッピングを定義します。 成功した場合は出力ファイルパス（保存モードの場合）または True（直接再生モードの場合）を、失敗した場合は False を返します。

クラス

  • class tkTTS: tktts.py ライブラリの主要なインターフェースを提供するクラスです。このクラスのインスタンスを通じて、TTSエンジンの設定、音声合成、音声情報の取得などを行います。

    • __init__(self, tts_name: Optional[str] = None, config: Optional[SimpleNamespace] = None): tkTTS オブジェクトを初期化します。 tts_name で初期のTTSエンジンを設定できます。config オブジェクトは、エンドポイントやAPIキーなどの設定を保持するために使用されます。

    • set_engine(self, tts_name: str): 使用するTTSエンジンを設定します。

    • set_endpoint(self, endpoint: str): TTSエンジンがAPIエンドポイントを必要とする場合（例: VOICEVOX）に、そのエンドポイントURLを設定します。

    • set_aquestalk_path(self, aquestalk_path: str): AquesTalk Playerの実行ファイルパスを設定します。

    • set_api_key(self, api_key: str): TTSエンジンがAPIキーを必要とする場合（例: ElevenLabs）に、そのAPIキーを設定します。

    • get_tts_name(self, tts_name: Optional[str] = None) -> Optional[str]: 現在のTTSエンジン名、または指定された tts_name を返します。

    • get_default_voice(self, tts_name: Optional[str] = None) -> Optional[str]: 指定されたTTSエンジン、または現在のTTSエンジンのデフォルト音声名を返します。

    • normalize_speaker(self, speaker: Optional[str], tts_name: Optional[str] = None) -> Optional[str]: normalize_speaker グローバル関数を呼び出すラッパーです。話者ラベルを正規化します。

    • get_available_voices_info(self, tts_name: Optional[str] = None, endpoint: Optional[str] = None, api_key: Optional[str] = None) -> Any: get_available_voices_info グローバル関数を呼び出すラッパーです。利用可能な音声の詳細情報を取得します。

    • get_available_voices(self, tts_name: Optional[str] = None, endpoint: Optional[str] = None, api_key: Optional[str] = None) -> Any: get_available_voices グローバル関数を呼び出すラッパーです。利用可能な音声名のリストを取得します。

    • list_available_voices(self, tts_name: Optional[str] = None, endpoint: Optional[str] = None, api_key: Optional[str] = None) -> bool: list_available_voices グローバル関数を呼び出すラッパーです。利用可能な音声情報をコンソールに出力します。

    • show_voice_map(self, infile: str, voices: str, VOICE_MAPS: Dict[str, Dict[Any, Any]], is_monologue: bool, tts_name: Optional[str] = None, endpoint: Optional[str] = None) -> bool: 入力ファイル infile を解析し、そこから検出された話者と、設定された voices および VOICE_MAPS に基づく音声マッピングをコンソールに表示します。

    • load_text(self, input_path: str, monologue: bool = False, wait_for_clipboard: bool = True) -> Optional[List[Tuple[Optional[str], str]]]: load_text グローバル関数を呼び出すラッパーです。テキストファイルまたはクリップボードからテキストを読み込みます。

    • get_speakers_from_dialogue(self, dialogue: List[Tuple[Optional[str], str]]) -> List[Optional[str]]: 対話リスト dialogue から、重複のない話者名のリストを抽出して返します。

    • parse_kv_string(self, kv_string: Optional[str], keys: List[str] = [], allow_no_key_kv_string: bool = False) -> Dict[str, Any]: parse_kv_string グローバル関数を呼び出すラッパーです。key=val;... 形式の文字列を辞書に変換します。

    • update_voice_map(self, voice_map: Dict[str, Dict[Any, Any]] = {}, voices: str = "", speakers: Dict[Any, Any] = {}) -> Dict[Any, Any]: 指定された voice_map、voices 文字列、および speakers リストに基づいて、現在のTTSエンジンの音声マッピング辞書を更新します。

    • speak_dialogue(self, dialogue: Optional[List[Tuple[Optional[str], str]]] = None, voice_map: Optional[Union[Dict[Optional[str], str], str]] = None, ...) -> Union[str, bool]: speak_dialogue グローバル関数を呼び出すラッパーです。音声合成を実行し、ファイルを保存または直接再生します。

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

tktts.py ライブラリは、if __name__ == "__main__": ブロックを持たないため、このライブラリファイルを main script として直接実行されることを意図していません。

しかし、モジュールがPythonインタープリタによってロードされる際には、冒頭のインポート処理とFFmpegの存在チェックが実行されます。

  1. コアライブラリのチェック: pydub, pyperclip, chardet の3つのコアライブラリがシステムにインストールされているかを確認します。いずれかが不足している場合、エラーメッセージを出力し、インストール方法を案内した上で SystemExit によりプログラムを終了します。

  2. FFmpegのチェック: ffmpeg および ffprobe コマンドがシステムPATHから検出できるかを確認します。ffmpeg が見つからない場合、エラーメッセージを出力し SystemExit によりプログラムを終了します。ffprobe が見つからない場合は警告メッセージが表示されますが、プログラムは続行します。

  3. オプションTTSバックエンドのロード: 各TTSエンジンのモジュール（例: tktts_pyttsx3, tktts_winrt など）が _safe_import 関数によって安全にロードされます。対応する依存ライブラリ（例: pyttsx3, winsdk）がインストールされていない場合、そのTTSエンジンはロードされず、警告メッセージが出力されますが、プログラムは続行されます。

これらのチェックとロード処理は、他のスクリプトから import tktts とされる際にも自動的に実行されます。