README.md

https://koemotion.rinna.co.jp/

本リポジトリは、Koemotionを利用される方に向けたPythonライブラリと、関連する情報等を提供します。

準備

本リポジトリに含まれるコードは、以下の環境で動作を確認しています。

• Python 3.8.13
• Windows 11 / macOS Sonoma 14.3.1 / Ubuntu 22.04 (on WSL2)

関連パッケージのインストール

本ライブラリはpyaudioライブラリを利用するため、事前にportaudioのインストールが必要になります。

# macOS
brew install portaudio
# Ubuntu
sudo apt install portaudio19-dev

Facemotionに関連したツールを利用する場合には、ffmpegが必要となります。

# macOS
brew install ffmpeg
# Ubuntu
sudo apt install ffmpeg

Pythonライブラリのインストール

以下のコマンドでPythonライブラリをインストールできます。事前にPython仮想環境を用意し、有効化しておくことをおすすめします。

# python3 -m venv venv
# source venv/bin/activate
pip install git+https://github.com/rinnakk/Koemotion

以下のPythonスクリプトやコマンドラインツールを利用してAPIコールを行う場合、環境変数KOEMOTION_API_KEYにAPIキーを登録してください。Koemotionへの登録方法はdocs/subscription.mdを参照ください。

export KOEMOTION_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

使い方

Koemotionクラスのインスタンスを作成します。ここで環境変数KOEMOTION_API_KEYに登録したAPIキーが内部的に読み込まれます。

from koemotion import Koemotion

client = Koemotion()

環境変数の登録がうまくいかない場合など、明示的にAPIキーを指定したい場合は以下のように指定することもできます。

client = Koemotion(api_key="yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy")

通常の音声合成

合成用のパラメータを定義し、request()メソッドに与えます。request()メソッドの呼び出しによりAPIがコールされ、Koemotion Light/Standard/Businessプランでは課金が発生します。料金の詳細についてはこちらをご確認ください。

params = {
  "text": "今日はいい天気ですね",
  "speaker_x": 2.0,
  "speaker_y": 3.0,
}
response = client.request(params)

responseはKoemotionJsonResponseオブジェクトで返されます。結果をファイルに保存する場合は以下のようにsave_json()またはsave_audio()メソッドを呼び出します。

response.save_json("result.json")
response.save_audio("result.mp3")

ストリーミング音声合成

Koemotion Standard/Businessプランに登録している場合、ストリーミング音声合成が利用できます。パラメータに"output_format": "wav"と"streaming": Trueを指定し、同様にrequest()メソッドをコールします。

params = {
  "text": "今日はいい天気ですね",
  "speaker_x": 2.0,
  "speaker_y": 3.0,
  "output_format": "wav",
  "streaming": True,
}
response = client.request(params)

responseはKoemotionStreamingResponseオブジェクトとなります。

ストリーミング音声合成の利点は「音声全体の合成が完了する前に音声のダウンロードが開始される」点にあります。この利点を活かす一つの機能として、stream_audio()メソッドを呼ぶことでローカルデバイスで音声を逐次再生することができます。

response.stream_audio()

より高度な処理を行いたい場合には、response.response.iter_content()から実際に受け取った音声データのバイナリ列にアクセスすることも可能です。 ストリーミング音声合成の場合にもsave_audio()メソッドから音声を保存することができますが、このメソッドは音声全体のダウンロードを待つ（ストリーミングの利点は失われる） ことにご注意ください。

response.save_audio("result_streaming.wav")  # wait until the entire audio is downloaded

CLIツール

Pythonライブラリのインストール、および環境変数KOEMOTION_API_KEYの登録ができている場合、以下のようにコマンドラインから直接APIをコールすることができます。結果はデフォルトでresult.jsonに保存されます。

koemotion-request -d "{\"text\": \"こんにちは\"}"

-a/--output-audioを指定することで、音声をファイルに書き出すことができます。

koemotion-request -d "{\"text\": \"こんにちは\"}" -a result.mp3 

ストリーミング音声合成を利用する場合（Koemotion Standard/Businessプランへの登録が必要です）は、jsonファイルは保存されず、代わりにデフォルトでresult_streaming.wavに音声が保存されます。--autoplayを指定することで、音声全体のダウンロードを待たずにローカルの音声デバイスで再生を始めることができます。

koemotion-request -d "{\"text\": \"こんにちは\", \"output_format\": \"wav\", \"streaming\": true}" --autoplay

利用例

• examples/facemotion: Koemotionから返ってきた音声および顔のキーポイントを動画化する
• examples/streaming/streaming_demo.py: ストリーミング音声合成をPythonから実行する
• examples/streaming/realtime_chat_demo.py: GPT-4o APIとKoemotionを利用して、リアルタイムな音声応答を得る（OpenAIのAPIキーの登録、およびopenaiライブラリのインストールが必要です）