tktts_openai.py ライブラリ ドキュメント
このドキュメントは、Pythonライブラリ tktts_openai.py の技術的な側面を詳細に記述します。
ライブラリの機能や目的
tktts_openai.py ライブラリは、OpenAIが提供するテキスト読み上げ（Text-to-Speech; TTS）APIをPythonプログラムから簡単に利用するためのインターフェースを提供します。主な目的は、テキストデータを自然な音声に変換し、ファイルとして保存することです。
主な機能:
OpenAI TTS APIへのアクセス: 指定されたテキストと音声モデル、話者設定に基づいて音声ファイルを生成します。
利用可能な音声の管理: OpenAIが提供する利用可能な音声（ボイスID）のリストを取得し、表示する機能を提供します。
ダイアログ処理のサポート: 外部の
tktts_baseモジュールと連携し、複数の話者が登場するダイアログ形式のテキストを解析し、話者ごとに異なる音声で合成する高度な処理をサポートします。依存ライブラリのチェック: ライブラリの実行に必要な非標準ライブラリ（
openai）がインストールされているかを起動時に確認し、不足している場合はユーザーに通知して終了します。
解決する課題:
OpenAI TTS APIを直接呼び出す際の煩雑な手順を簡素化します。
特に複数の話者が登場するスクリプトや物語の音声化において、話者ごとの声の割り当てやテキストの置換といった前処理を効率的に行えるよう支援します。
importする方法
このライブラリを他のPythonプログラムから利用するには、標準的な import ステートメントを使用します。
ライブラリ全体をインポートする場合：
import tktts_openai
特定の関数や変数を直接インポートする場合：
from tktts_openai import speak, get_available_voices, DEFAULT_OPENAI_VOICE
必要な非標準ライブラリとインストール方法
tktts_openai.py ライブラリが動作するために、以下の非標準ライブラリが必要です。
openai: OpenAI APIへのアクセスを提供します。インストール方法:
pip install openai
tktts_base: ダイアログの分割やテキストの置換といった共通処理を提供するモジュールです。このモジュールは
tktts_openai.pyのコードには含まれておらず、別途用意する必要があります。通常、同じプロジェクト内に配置されるか、pipでインストールされるライブラリとして提供されます（ただし、このドキュメントの範囲内ではインストール方法は提供されていません）。
重要: openai ライブラリがインストールされていない場合、tktts_openai.py を実行またはインポートしようとすると、以下のようなメッセージが表示され、プログラムが終了します。
Error: Missing libraries:
openai
install: pip install openai
Press ENTER to terminate>>
importできる変数と関数
tktts_openai.py から import できる主な変数と関数は以下の通りです。
変数
TTS_ENGINE_NAME:strこのTTSエンジンが使用する名前を示します。常に
'openai'です。
tts_model:str現在設定されているデフォルトのTTSモデル名です。デフォルト値は
"tts-1"です。
DEFAULT_TTS_MODEL:strこのライブラリで利用されるデフォルトのTTSモデル名です。デフォルト値は
"tts-1"です。他の選択肢として"tts-1-hd","gpt-4o-mini-tts"などが利用可能です。
voices_available:List[str]OpenAI TTS APIで現在利用可能な標準的な音声IDのリストです。例:
["alloy", "echo", "fable", "onyx", "nova", "shimmer"]。
DEFAULT_OPENAI_VOICE:strデフォルトで使用されるOpenAIの音声IDです。デフォルト値は
"alloy"です。
関数
get_available_voices_info()
機能: OpenAI TTS APIで利用可能な音声の情報をリスト形式で取得します。各音声は辞書形式で、現時点では
'name'キーのみを含みます。引数: なし
戻り値:
List[Dict[str, str]]利用可能な音声情報のリスト。例:
[{"name": "alloy"}, {"name": "echo"}]
get_available_voices()
機能: OpenAI TTS APIで利用可能な音声IDのリストを取得します。
引数: なし
戻り値:
List[str]利用可能な音声IDのリスト。例:
["alloy", "echo"]
list_available_voices()
機能: 利用可能なOpenAIの音声名をコンソールに出力します。
引数: なし
戻り値:
bool音声情報が出力された場合は
True、利用可能な音声がない場合はFalse。
speak(outfile, text, voice, tts_model = DEFAULT_TTS_MODEL, instruction = "", output_format = "mp3")
機能: 指定されたテキストをOpenAI TTS APIを使用して音声合成し、指定されたファイルに保存します。
引数:
outfile(str): 生成された音声ファイルを保存するパス。text(str): 音声合成するテキスト。voice(str): 使用するOpenAIの音声ID（例:"alloy","nova"）。voices_availableのいずれかである必要があります。tts_model(str, オプション): 使用するTTSモデル名。デフォルトはDEFAULT_TTS_MODEL("tts-1")。instruction(str, オプション): OpenAI APIへの追加指示。現在のOpenAI APIのopenai.audio.speech.createメソッドにはこの引数は存在しないため、指定しても効果がないか、APIエラーを引き起こす可能性があります。output_format(str, オプション): 出力音声ファイルのフォーマット。デフォルトは"mp3"。
戻り値:
str: 音声ファイルが正常に保存された場合、そのファイルパスを返します。None: APIエラーやその他の例外により音声ファイルの生成または保存に失敗した場合。
speak_dialogue(dialogue, replacements, target_voices, speakers = {}, instruction = "", temp_dir = None, outfile = None, ext = "wav", tts_model = DEFAULT_TTS_MODEL, cfg = None)
機能: 複数の発話（ダイアログ）を処理し、話者ごとに適切なOpenAI音声モデルを使用して音声合成を行い、一時ファイルとして保存します。この関数は
tktts_baseモジュールのsplit_dialogueおよびapply_replacements関数と連携します。引数:
dialogue(List[str]): 処理するダイアログの各発話を含む文字列のリスト。replacements(Dict[str, str]): テキスト内の特定の文字列を置換するためのルールを定義した辞書。tktts_base.apply_replacementsに渡されます。target_voices(Union[str, Dict[str, str]]):str: 全ての発話で単一のOpenAI音声IDを使用する場合。Dict[str, str]: 話者名と対応するOpenAI音声IDのマッピング。例:{"Alice": "alloy", "Bob": "nova"}。
speakers(Dict[str, str], オプション): 話者名とその内部IDのマッピング。tktts_base.split_dialogueに渡されます。デフォルトは空の辞書。instruction(str, オプション): 各speak呼び出しに渡される指示文字列。speak関数と同様に、OpenAI APIでは効果がない可能性があります。temp_dir(str, オプション): 生成される一時音声ファイルを保存するディレクトリのパス。指定しない場合、一時ファイルはカレントディレクトリに作成される可能性がありますが、通常は指定することが推奨されます。outfile(str, オプション): 最終的に生成される結合音声ファイルのパス。この関数自体は複数の音声ファイルを結合する機能を持たないため、この引数は現在の実装では直接使用されません。一時ファイル群のパスが戻り値として提供されます。ext(str, オプション): 生成される一時音声ファイルの拡張子。デフォルトは"wav"。tts_model(str, オプション): 使用するTTSモデル名。デフォルトはDEFAULT_TTS_MODEL("tts-1")。cfg(object, オプション): 設定オブジェクト。cfg.monologue属性 (bool) がtktts_base.split_dialogueに渡され、モノローグとして扱うかどうかを制御します。
戻り値:
Tuple[bool, List[str]]: 処理が成功した場合は(True, tmpfiles)、失敗した場合は(False, tmpfiles)を返します。tmpfilesは生成された一時音声ファイルのパスのリストです。
main scriptとして実行したときの動作
tktts_openai.py は、if __name__ == "__main__": ブロックを持たないため、このスクリプトを直接実行した場合でも、特定のスクリプトとしての動作は定義されていません。
ただし、スクリプトの冒頭でライブラリの依存関係チェックが行われます。openai ライブラリがインストールされていない場合は、エラーメッセージを表示し、インストール方法を案内した上でプログラムが終了します。これは、ライブラリを利用する上での前提条件を強制するための動作です。