amivoice-client-library-python

AmiVoice API を利用して音声認識アプリケーションを開発するための Python クライアントライブラリと、そのサンプルプログラムを提供しています。 本ライブラリは MIT License で提供します。

パッケージ構成

src/
└── amivoice/
    ├── __init__.py           # 公開API
    ├── client.py             # 同期HTTP・WebSocket音声認識
    ├── async_client.py       # 非同期HTTP音声認識（同期メソッド提供）
    ├── _*.py                 # 標準ライブラリによるHTTP・WebSocket通信と設定の処理
    ├── constants.py          # 接続エンジンと音声フォーマット
    ├── models.py             # 認識結果とイベント
    ├── async_models.py       # 非同期HTTPジョブと認識結果モデル
    ├── dictionary.py         # ユーザー辞書の管理
    ├── api_key.py            # APIキーの発行
    ├── sentiment_analysis.py # 感情パラメータの定義取得
    ├── grammar.py            # ルールグラマの指定
    ├── settings.py           # 認識設定とクライアント既定値の継承指定
    └── exceptions.py         # 公開例外

クイックスタート

Python 3.11 以降に対応しています。アプリケーションから利用する場合は、配布パッケージをインストールします。

pip install amivoice-api-client

API キーを環境変数AMIVOICE_API_KEYに設定してから実行してください。 クライアントは環境変数からキーを読み取るため、ソースコードや実行時の引数にキーを書く必要はありません。

from amivoice import AmiVoiceClient, Engine, RecognitionSettings

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

認識設定はRecognitionSettingsにまとめてsettingsへ渡します。旧 API の個別の認識引数は使用できません。 RecognitionSettings.grammar_file_namesは HTTP と WebSocket の両方で必須です。HTTP ではヘッダ付き音声であればcodecを省略できます。 WebSocket ではcodecも必ず指定してください。

長時間の音声やバッチ処理には、非同期 HTTP 音声認識 API（v2）を利用できる AmiVoiceAsyncClient も用意されています。 Python の async / await 構文ではなく通常の同期（ブロッキング）メソッドを提供し、ジョブの登録（submit）、状態取得（get_job）、完了待機（wait）を行えます。 非同期 HTTP（v2）では、話者ダイアライゼーションや感情分析（RecognitionSettings.sentiment_analysis）の指定および結果取得にも対応しています。

詳細な利用方法は以下のガイドを参照してください。

• 共通利用ガイド（インストール・認証・共通設定・辞書管理）
• 同期 HTTP 音声認識ガイド
• 非同期 HTTP 音声認識（v2）ガイド
• WebSocket ストリーミング認識ガイド

クライアント既定値の継承（USE_CLIENT_DEFAULT）

コンストラクタ（AmiVoiceClient、AmiVoiceAsyncClient）では、settingsを省略するかsettings=Noneを指定すると空の認識設定を表します。 モジュール関数transcribe()のsettingsはRecognitionSettings型の必須キーワード引数です。省略するとTypeErrorになり、NoneやUSE_CLIENT_DEFAULTなどのRecognitionSettings以外の値を指定するとクライアント生成や通信の前にConfigurationErrorを送出します。空のRecognitionSettings()は型として有効ですが、必須のgrammar_file_namesが不足するためConfigurationErrorになります。 クライアントインスタンスの認識メソッド（client.transcribe()、client.stream()、client.submit()）では、settingsを省略するかUSE_CLIENT_DEFAULT（型はUseClientDefault）を指定すると、クライアントの設定を継承します。空のRecognitionSettings()もすべての項目を継承します。 インスタンスメソッドの呼び出し時にsettings=Noneは指定できず、通信する前にConfigurationErrorを送出します。クライアントの設定とは別の設定で認識する場合は、新しいクライアントを作成するか、RecognitionSettings(...)で必要な項目を明示して上書きしてください。

RecognitionSettingsの各項目は、省略またはUSE_CLIENT_DEFAULTで継承し、Noneで解除します。Falseや0は解除ではなく明示値です。 プロキシ、通信タイムアウト、接続 URL、raise_on_error、完了待機の引数は、引き続き独立した引数です。 同期クライアントのコンストラクタでは、URL 引数にUSE_CLIENT_DEFAULTを指定すると既定 URL を選択します。 非同期クライアントのコンストラクタのapi_urlは URL 文字列のみを受け付けます。 呼び出し時のapi_url=USE_CLIENT_DEFAULTは、カスタム URL も含めてクライアントの接続先を継承し、既定 URL へリセットしません。URL にNoneは指定できません。

ラッパー関数などで引数をそのまま転送する場合も、未指定の既定値にUSE_CLIENT_DEFAULTを使用します。

from amivoice import (
    USE_CLIENT_DEFAULT,
    AmiVoiceClient,
    Engine,
    RecognitionResult,
    RecognitionSettings,
    UseClientDefault,
)


def recognize_speech(
    audio: bytes,
    *,
    client: AmiVoiceClient,
    confidence_level: float | None | UseClientDefault = USE_CLIENT_DEFAULT,
) -> RecognitionResult:
    return client.transcribe(audio, settings=RecognitionSettings(confidence_level=confidence_level))


client = AmiVoiceClient(
    settings=RecognitionSettings(grammar_file_names=Engine.A_GENERAL, confidence_level=0.2)
)
result = recognize_speech(b"RIFF...", client=client)

公式仕様

最新の公式仕様は以下のマニュアルをご確認ください。

• AmiVoice API マニュアル（概要・同期HTTP・WebSocket）
• 非同期HTTP音声認識API（非同期HTTPインタフェース）