tktts_edge.py ドキュメント

このドキュメントは、Pythonライブラリ tktts_edge.py の機能と使用方法について説明します。

ライブラリの機能や目的

tktts_edge.py は、tktts モジュール用のバックエンドとして機能し、Microsoft Edge Text-to-Speech (TTS) サービスを利用してテキストを音声に変換します。このライブラリの主な目的は、tktts フレームワーク内で Edge TTS の音声合成機能を提供することです。Microsoft のオンラインサービスから直接音声を取得するため、API キーは不要です。

主な機能は以下の通りです。

  • Edge TTS の利用可能な音声の一覧を取得する。

  • 指定されたテキスト、音声、話速、音量、ピッチで音声ファイルを生成する。

  • 対話形式のスクリプトを解析し、複数の話者とテキストに対応した音声ファイルを合成する。

これにより、ユーザーは tktts プロジェクトにおいて、高品質な Edge TTS 音声を手軽に利用できるようになります。

importする方法

tktts_edge.py を他のPythonプログラムからインポートするには、以下のように記述します。

import tktts_edge

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

from tktts_edge import speak, get_available_voices

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

tktts_edge.py が動作するためには、以下の非標準ライブラリが必要です。

  • edge-tts: Microsoft Edge Text-to-Speech サービスと通信するためのライブラリ。

これらのライブラリは pip を使用してインストールできます。

pip install edge-tts

importできる変数と関数

このライブラリからインポートして利用できる主な変数と関数は以下の通りです。

変数

  • TTS_ENGINE_NAME

    • 説明: このTTSエンジンを識別するための名前。値は "edge" です。

  • DEFAULT_EDGE_VOICE

    • 説明: Edge TTS におけるデフォルトの音声名。値は "Nanami" です。

関数

  • get_available_voices_info()

    • 動作: Edge TTS で利用可能な音声の情報を取得し、共通の tktts 音声情報形式でリストを返します。この情報は、音声の名前、ロケール、性別を含みます。

    • 引数: なし

    • 戻り値: 各音声の情報を辞書として含むリスト。 例:[{"name": "ja-JP-NanamiNeural", "locale": "ja-JP", "gender": "Female"}, ...]

  • get_available_voices()

    • 動作: Edge TTS で利用可能な音声の名前のみのリストを返します。

    • 引数: なし

    • 戻り値: 利用可能な音声のショートネーム(例: "ja-JP-NanamiNeural")の文字列リスト。

  • list_available_voices()

    • 動作: Edge TTS で利用可能な音声の一覧を標準出力に整形して表示します。音声の取得に失敗した場合はエラーメッセージを表示します。

    • 引数: なし

    • 戻り値: 音声の一覧表示が成功した場合は True、失敗した場合は False。

  • speak(outfile, text, voice, rate="+0%", volume="+0%", pitch="+0Hz")

    • 動作: 指定されたテキストを Edge TTS を使用して音声合成し、指定されたファイルに保存します。話速、音量、ピッチを調整できます。

    • 引数:

      • outfile (str): 生成された音声ファイルを保存するパス。

      • text (str): 音声合成するテキスト。

      • voice (str): 使用するEdge TTSの音声名(例: "ja-JP-NanamiNeural")。

      • rate (str, オプション): 音声の再生速度。パーセンテージ(例: "+10%")またはHz(例: "-50Hz")で指定します。デフォルトは "+0%"。

      • volume (str, オプション): 音声の音量。パーセンテージ(例: "+20%")で指定します。デフォルトは "+0%"。

      • pitch (str, オプション): 音声のピッチ。パーセンテージ(例: "+0%")またはHz(例: "+50Hz")で指定します。デフォルトは "+0Hz"。

    • 戻り値: 音声ファイルが正常に生成された場合は outfile のパス、失敗した場合は None。

  • speak_dialogue(dialogue, replacements, target_voices, speakers=None, temp_dir=None, outfile=None, ext="mp3", cfg=None)

    • 動作: 対話形式のセグメントを解析し、それぞれのセグメントに対して音声合成を実行します。テキスト置換、話者マッピング、デフォルト音声設定などを適用し、一時的な音声ファイルを生成します。

    • 引数:

      • dialogue (list): 処理する対話セグメントのリスト。各セグメントはテキストと話者情報を含む形式です。

      • replacements (dict): テキストに適用する置換ルールを含む辞書。

      • target_voices (dictまたはstr): 話者名と音声名のマッピング、または単一のデフォルト音声名。

      • speakers (dict, オプション): 話者に関する追加情報(現時点では利用されていません)。デフォルトは None。

      • temp_dir (str, オプション): 一時的な音声ファイルを保存するディレクトリ。デフォルトは None(現在のディレクトリに保存)。

      • outfile (str, オプション): (この関数では使用されません。ファイル結合は tktts.py で処理されます)。デフォルトは None。

      • ext (str, オプション): 生成される音声ファイルの拡張子。デフォルトは "mp3"。

      • cfg (object, オプション): edge_rate, edge_volume, edge_pitch, monologue などの設定属性を持つ設定オブジェクト。デフォルトは None。

    • 戻り値: 成功した場合は (True, tmpfiles) (tmpfiles は生成された一時ファイルのパスのリスト)、失敗した場合は (False, tmpfiles)。

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

tktts_edge.py は if __name__ == "__main__": ブロックを持たないため、このファイルを直接実行しても何も処理は行われません。ライブラリとして他のPythonスクリプトからインポートされることを意図しています。