tktts_openai.py ライブラリ ドキュメント
1. ライブラリの機能や目的
tktts_openai.py ライブラリは、OpenAIのText-to-Speech (TTS) APIを利用してテキストを音声に変換する機能を提供します。
主な機能:
テキスト音声合成: 指定されたテキストをOpenAIのTTSモデルで合成し、音声ファイルとして保存します。
複数の話者による対話合成: 対話形式のテキストを解析し、話者ごとに異なる音声で個別の音声ファイルを合成できます。これは、特に複数人が登場する会話シーンの音声化に適しています。
解決する課題:
このライブラリは、テキストコンテンツを多様なOpenAIの音声モデルと話者で音声化したいユーザー向けに、APIとの連携を簡素化し、単一のテキストから対話形式のテキストまで柔軟に対応できるツールとして機能します。
2. importする方法
このライブラリを他のPythonプログラムから利用するには、以下の import 文を使用します。
import tktts_openai
3. 必要な非標準ライブラリとインストール方法
tktts_openai.py ライブラリは、以下の非標準ライブラリに依存しています。
openai
これらのライブラリは、Pythonのパッケージマネージャーである pip を使用してインストールできます。
pip install openai
4. importできる変数と関数
4.1. 変数
以下の変数がライブラリ内で定義され、外部からアクセス可能です。
TTS_ENGINE_NAME説明: 使用しているTTSエンジンの名前を表す文字列。このライブラリでは常に
'openai'です。
tts_model説明: 現在選択されているOpenAI TTSモデルの名前。デフォルト値は
"tts-1"です。
DEFAULT_TTS_MODEL説明: デフォルトで使用されるOpenAI TTSモデルの名前。デフォルト値は
"tts-1"です。他の選択肢として"tts-1-hd","gpt-4o-mini-tts"などがあります。
voices_available説明: OpenAI TTSで利用可能な音声の名前のリスト。現在は
"alloy","echo","fable","onyx","nova","shimmer"が含まれています。
DEFAULT_OPENAI_VOICE説明: デフォルトで使用されるOpenAI TTS音声の名前。デフォルト値は
"alloy"です。
4.2. 関数
get_available_voices_info()
利用可能なOpenAI TTS音声の情報を取得します。
動作:
voices_available変数に定義されている音声の名前を基に、各音声の名前情報を含む辞書のリストを作成して返します。引数: なし
戻り値:
list[dict]: 利用可能なOpenAI TTS音声の名前と追加情報を含む辞書のリスト。
get_available_voices()
利用可能なOpenAI TTS音声の名前リストを取得します。
動作:
voices_available変数に定義されている音声の名前をそのままリストとして返します。引数: なし
戻り値:
list[str]: 利用可能なOpenAI TTS音声の名前のリスト。
list_available_voices()
利用可能なOpenAI TTS音声の名前をコンソールに表示します。
動作:
get_available_voices_info()を呼び出して音声情報を取得し、その内容をコンソールに出力します。引数: なし
戻り値:
bool: 音声がリストされた場合はTrue、それ以外はFalse。
speak(outfile, text, voice, tts_model = DEFAULT_TTS_MODEL, instruction = "", output_format = "mp3")
指定されたテキストをOpenAI TTSで音声ファイルとして保存します。
動作: OpenAI APIを呼び出し、指定されたモデルと音声でテキストを合成し、出力ファイルに書き込みます。APIエラーやその他の接続エラーが発生した場合はコンソールにエラーメッセージを表示します。
引数:
outfile(str): 出力音声ファイルのパス。text(str): 合成するテキスト。voice(str): 使用するOpenAI音声の名前(例:"alloy","fable")。tts_model(str, オプション): 使用するOpenAI TTSモデル(例:"tts-1","tts-1-hd")。デフォルトはDEFAULT_TTS_MODEL。instruction(str, オプション): 音声合成時にOpenAIに渡す指示文字列。現在OpenAI TTS APIには存在しないが、コードに定義されているため含められています。output_format(str, オプション): 出力音声ファイルの形式(例:"mp3","opus","aac","flac")。
戻り値:
strまたはNone: 成功した場合は出力ファイルのパス、APIエラーやその他のエラーが発生した場合はNone。
speak_dialogue(dialogue, replacements, target_voices, speakers = {}, instruction = "", temp_dir = None, outfile = None, ext = "wav", tts_model = DEFAULT_TTS_MODEL, cfg = None)
対話形式のテキストを複数の音声ファイルとしてOpenAI TTSで合成します。
動作: 入力された対話テキストを話者ごとに分割し、指定されたOpenAI音声で個別の音声ファイルを一時ディレクトリに生成します。この関数は、単一の最終出力ファイルではなく、複数の短い一時音声ファイルを生成することを目的としています。テキストの置換 (
replacements) や話者の正規化 (speakers) も適用されます。引数:
dialogue(list[str]): 合成する対話テキストのリスト。replacements(dict): テキスト内で置換を行うための辞書。target_voices(dictまたはstr): 話者名とOpenAI音声名のマッピング辞書、または全ての対話に適用する単一のOpenAI音声名。speakers(dict, オプション): 話者名の正規化に使用される辞書。デフォルトは空の辞書。instruction(str, オプション):speak関数に渡される指示文字列。現在OpenAI TTS APIには存在しないが、コードに定義されているため含められています。temp_dir(str, オプション): 一時音声ファイルを保存するディレクトリのパス。outfile(str, オプション): この関数内ではis_save_modeの判定にのみ使用され、最終的な出力ファイルには使われません。ext(str, オプション): 生成される一時音声ファイルの拡張子(例:"mp3","wav")。tts_model(str, オプション): 使用するOpenAI TTSモデル(例:"tts-1","tts-1-hd")。デフォルトはDEFAULT_TTS_MODEL。cfg(object, オプション): 設定オブジェクト。cfg.monologueプロパティを持つことを想定しています。
戻り値:
tuple[bool, list[str]]: 成功した場合は(True, 生成された一時ファイルパスのリスト)、エラーが発生した場合は(False, 生成に成功した一時ファイルパスのリスト)。
5. main scriptとして実行したときの動作
tktts_openai.py は、if __name__ == "__main__": ブロックを持たないため、単体でPythonスクリプトとして直接実行された場合の特別な動作は定義されていません。このライブラリは、他のプログラムから import され、その機能を利用されることを想定して設計されています。