Skip to main content

Python 向けクライアントライブラリ

Python で AmiVoice API を利用するアプリケーションを開発するためのクライアントライブラリとして、PyPI でamivoice-api-clientを提供しています。

amivoice-api-clientは、従来の各言語共通クライアントライブラリ（Hrp/Wrp）とは独立した Python 専用のライブラリです。同期 HTTP・非同期 HTTP（v2）・WebSocket の 3 つの音声認識インタフェースに対応しています。 Python の標準ライブラリのみで動作し、外部パッケージへの依存はありません。

ソースコードやサンプルプログラム、詳細な利用ガイドは、以下のパッケージページおよびリポジトリで公開しています。

インストール​

Python 3.11 以上に対応しており、pipでインストールできます。

pip install amivoice-api-client

pipでインストールされるパッケージには、サンプルプログラム（examples/）やサンプル音声ファイルは含まれません。サンプルプログラムやテスト音声を試す場合は、上記の GitHub リポジトリから別途取得してください（テスト音声の例: audio/test.wav）。

認証の設定​

API キーは環境変数AMIVOICE_API_KEYに設定して利用することを推奨します。クライアントのコンストラクタでapi_keyを省略すると、環境変数AMIVOICE_API_KEYから自動的に読み取ります。ソースコードやコマンドライン引数に API キーを直接記述しないようにしてください。

export AMIVOICE_API_KEY="your-api-key"

基本的な使い方​

認識設定はRecognitionSettingsにまとめ、クライアントのコンストラクタや各メソッドのsettings引数に渡します。接続エンジン名（grammar_file_names）はEngine定数で、音声フォーマット（codec）はCodec定数で指定できます。

同期 HTTP 音声認識​

16 MB 以下の録音済み音声ファイルを 1 回のリクエストで認識する場合は、AmiVoiceClient.transcribe()（またはモジュール関数transcribe()）を使用します。ヘッダ付き音声であればcodecは省略できます。

from amivoice import AmiVoiceClient, Engine, RecognitionSettings

client = AmiVoiceClient(
    settings=RecognitionSettings(grammar_file_names=Engine.A_GENERAL),
)
result = client.transcribe("audio.wav")
print(result.text)

非同期 HTTP 音声認識（v2）​

長時間の音声ファイルやバッチ処理にはAmiVoiceAsyncClientを使用します。

from amivoice import AmiVoiceAsyncClient, Engine, RecognitionSettings

client = AmiVoiceAsyncClient(
    settings=RecognitionSettings(grammar_file_names=Engine.A_GENERAL),
)
submission = client.submit("audio.wav")
snapshot = client.wait(submission.session_id)
if snapshot.recognition is not None:
    print(snapshot.recognition.text)

WebSocket ストリーミング音声認識​

リアルタイムに音声を送信して逐次結果を受け取る場合は、AmiVoiceClient.stream()を使用します。WebSocket ではgrammar_file_namesとcodecの両方の指定が必須です。

from amivoice import AmiVoiceClient, Codec, Engine, RecognitionSettings

client = AmiVoiceClient(
    settings=RecognitionSettings(
        grammar_file_names=Engine.A_GENERAL,
        codec=Codec.HEADER_16K,
    ),
)
with open("audio.wav", "rb") as audio, client.stream() as session:
    for chunk in iter(lambda: audio.read(4096), b""):
        session.write(chunk)
        for event in session.poll():
            if event.is_final and event.result is not None and not event.result.is_error:
                print("確定:", event.result.text)
    session.end()
    for event in session.poll():
        if event.is_final and event.result is not None and not event.result.is_error:
            print("確定:", event.result.text)

その他の機能と詳細ガイド​

ユーザー辞書の管理（UserDictionaryClient）や API キーの発行（ApiKeyIssuanceClient）にも対応しています。また、感情パラメータの定義取得（SentimentAnalysisClient）も利用できます。 各種リクエストパラメータの詳細やエラーハンドリングについては、GitHub リポジトリの各ガイドを参照してください。