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

ライブラリの機能や目的

tktts_gemini.py は、Google Gemini の Text-to-Speech (TTS) 機能を利用して、テキストから音声を生成するためのPythonライブラリです。主に、単一のテキストの音声合成や、複数話者の対話形式のテキストを処理し、話者ごとに異なる声で音声を合成・保存する機能を提供します。

このライブラリの主な目的は以下の通りです。

Gemini TTS APIのラッパー: Google Gemini APIを直接操作する手間を省き、シンプルなインターフェースで音声合成を実現します。
多様な音声のサポート: Geminiで利用可能な複数のプリセット音声（ボイス）の中から選択して音声合成を行います。
対話形式の音声合成: tktts_base ライブラリの機能と連携し、複数話者の対話テキストを解析し、それぞれの話者に割り当てられた音声で個別に合成し、音声ファイルを生成します。
エラーハンドリング: 必須ライブラリの不足やAPI接続エラーが発生した場合に、適切なメッセージを表示します。

本ライブラリは、複雑な音声合成処理、特に複数話者のテキストを扱うアプリケーションの開発において、GeminiのTTS機能を簡単に組み込むことを可能にします。

importする方法

このライブラリを他のPythonプログラムから利用するには、標準的なimport文を使用します。

ライブラリ全体をimportする場合：

import tktts_gemini

特定の関数や変数を直接importする場合：

from tktts_gemini import speak, get_available_voices, DEFAULT_GEMINI_VOICE

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

このライブラリは、Google Gemini APIと連携するために、以下の非標準ライブラリに依存しています。

google-genai

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

pip install google-genai

注意: 本ライブラリは、内部で tktts_base から apply_replacements, normalize_speaker, split_dialogue をimportしています。これらが利用可能な環境に配置されていることを前提とします。

importできる変数と関数

変数

TTS_ENGINE_NAME
- 説明: 利用しているTTSエンジンの名前を示す文字列です。このライブラリでは 'gemini' が設定されています。
- 型: str
- デフォルト値: 'gemini'
DEFAULT_TTS_MODEL
- 説明: 音声合成に使用されるデフォルトのGeminiモデルIDです。
- 型: str
- デフォルト値: "gemini-3.8-flash-tts"
voices_available
- 説明: Geminiで利用可能なプリセット音声（ボイス）の名前をリスト化したものです。
- 型: list of str
- デフォルト値: ["Kore", "Puck", "Aoede", "Charon", "Fenrir"]
DEFAULT_GEMINI_VOICE
- 説明: 音声合成時にデフォルトとして使用されるボイスの名前です。
- 型: str
- デフォルト値: "Kore"

関数

get_available_voices_info()
- 動作: Geminiで利用可能なプリセット音声の詳細情報を取得します。
- 引数: なし
- 戻り値: 利用可能な各音声の名前を含む辞書のリストを返します。リストが空の場合は、利用可能な音声がないことを示します。
  - 例: [{"name": "Kore"}, {"name": "Puck"}, ...]
get_available_voices()
- 動作: Geminiで利用可能なプリセット音声の名前のリストを取得します。
- 引数: なし
- 戻り値: 利用可能な音声の名前（文字列）のリストを返します。
list_available_voices()
- 動作: get_available_voices_info() から取得した情報を整形し、利用可能なGeminiの音声をコンソールに出力します。
- 引数: なし
- 戻り値: 音声のリスト表示に成功した場合は True、利用可能な音声がない場合は False を返します。
speak(outfile, text, voice, tts_model=DEFAULT_TTS_MODEL, instruction="", output_format="wav")
- 動作: 指定されたテキストをGeminiのTTS機能で音声合成し、指定されたファイルに保存します。
- 引数:
  - outfile (str): 音声データを保存するファイルのパス。
  - text (str): 音声合成するテキスト。
  - voice (str): 使用する音声の名前（例: "Kore"）。
  - tts_model (str, オプション): 使用するGemini TTSモデルのID。デフォルトは DEFAULT_TTS_MODEL。
  - instruction (str, オプション): テキストに追加する指示（プロンプト）。TTS専用モデルの場合、この指示も音声合成される可能性があるため注意が必要です。
  - output_format (str, オプション): 出力音声ファイルの形式（例: "wav"）。Gemini APIがサポートする形式に限られます。
- 戻り値: 音声合成とファイル保存に成功した場合は、保存されたファイルのパス (str) を返します。エラーが発生した場合は None を返します。
speak_dialogue(dialogue, replacements, target_voices, speakers={}, instruction="", temp_dir=None, outfile=None, ext="wav", tts_model=DEFAULT_TTS_MODEL, cfg=None)
- 動作: 対話形式のテキスト（複数の話者とセリフ）を処理し、話者ごとに割り当てられた音声を使用して個別に音声合成を行い、複数の音声ファイルとして保存します。この関数は、tktts_base ライブラリのテキスト処理機能と連携します。
- 引数:
  - dialogue (list of str): 各要素が1つの対話（話者とセリフ）を表す文字列のリスト。
  - replacements (dict): テキスト内で置換を行うための辞書。tktts_base.apply_replacements に渡されます。
  - target_voices (dict or str): 各話者に割り当てる音声の名前を示す辞書、または全ての対話に適用する単一の音声の名前。
  - speakers (dict, オプション): 話者の正規化ルール。tktts_base.split_dialogue に渡されます。デフォルトは空の辞書。
  - instruction (str, オプション): 各音声合成に適用する指示（プロンプト）。
  - temp_dir (str, オプション): 生成された一時音声ファイルを保存するディレクトリのパス。指定しない場合、カレントディレクトリに保存されます。
  - outfile (str, オプション): 全ての生成された一時ファイルを結合して保存する最終的な出力ファイルのパス。現在、このライブラリ内では結合処理は実装されておらず、単にこの引数の存在で保存モードが決定されます。
  - ext (str, オプション): 生成する音声ファイルの拡張子（形式）。デフォルトは "wav"。
  - tts_model (str, オプション): 使用するGemini TTSモデルのID。デフォルトは DEFAULT_TTS_MODEL。
  - cfg (object, オプション): 設定オブジェクト。cfg.monologue 属性が存在する場合、対話の分割方法に影響を与えます。
- 戻り値:
  - tuple: (bool, list)
    - 最初の要素 (bool): 全ての音声合成処理が成功した場合は True、途中で失敗した場合は False。
    - 二番目の要素 (list): 生成された一時音声ファイルのパスのリスト。

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

tktts_gemini.py は、単独でスクリプトとして実行された場合の特別な機能（例: テスト実行やデモンストレーション）は提供していません。

しかし、ライブラリの冒頭で以下の初期チェックを実行します。

必須ライブラリである google-genai がimportできるかを確認します。
もし google-genai が見つからない場合、エラーメッセージを表示し、インストール方法を案内します。
ユーザーがEnterキーを押すと、プログラムは sys.exit(1) で終了します。

この動作は、本ライブラリが他のプログラムからimportされることを前提としており、実行環境が必要な依存関係を満たしていることを保証するためのものです。

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