すべてのプロダクト
Search
ドキュメントセンター

Alibaba Cloud Model Studio:Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-RealTime Python SDK

最終更新日:Sep 02, 2026

このトピックでは、Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime リアルタイム音声認識モデル用の Python SDK のパラメータとインターフェイスについて説明します。

重要Alibaba Cloud Model Studio は、中国 (北京) およびシンガポールの各リージョン向けにワークスペース固有ドメインをリリースしました。これらの新しい専用ドメインにより、推論リクエストのパフォーマンスと安定性が向上します。以下の新しいドメインへの移行を推奨します:

  • 中国 (北京):dashscope.aliyuncs.com から {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • シンガポール:dashscope-intl.aliyuncs.com から {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} を実際の ワークスペース ID に置き換えてください。既存のドメインは引き続き問題なく利用できます。

ユーザーガイド:モデルの説明と選定ガイダンスについては、「音声テキスト変換」をご参照ください。

前提条件

サービスが有効化されており、「API キーの取得」が完了していること。コード漏洩によるセキュリティリスクを防ぐため、コードにハードコーディングするのではなく、「API キーを環境変数として設定」してください。

クイックスタート

Recognition クラスは、非ストリーミング呼び出しと双方向ストリーミング呼び出しの両方のインターフェイスを提供します。ニーズに合わせて呼び出し方法を選択してください:

  • 非ストリーミング呼び出し:ローカルファイルを認識し、1 回のレスポンスで完全な結果を返します。録音済みの音声を処理する場合に適しています。
  • 双方向ストリーミング呼び出し:音声ストリームを直接認識し、結果をリアルタイムで出力します。音声ストリームは、マイクなどの外部デバイスから取得することも、ローカルファイルから読み取ることもできます。即時のフィードバックが必要なシナリオに適しています。

非ストリーミング呼び出し

単一のリアルタイム音声認識タスクを送信し、ローカルファイルを渡すことで認識結果を同期的に取得します。

Recognition クラスをインスタンス化し、リクエストパラメーターをバインドし、call を呼び出して認識または翻訳を実行し、最終的な 認識結果 (RecognitionResult) を取得します。

完全な例の表示

from http import HTTPStatus
import dashscope
from dashscope.audio.asr import Recognition
import os

# API キーは、シンガポールリージョンと北京リージョンで異なります。 API キーの取得: https://www.alibabacloud.com/help/model-studio/get-api-key
# 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# 以下はシンガポールリージョンの設定です。 呼び出す際に、"{WorkspaceId}" を実際のワークスペース ID に置き換えてください。 設定はリージョンによって異なります。
dashscope.base_websocket_api_url='wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference'

recognition = Recognition(model='qwen-audio-3.0-asr-flash-streaming',
                          format='wav',
                          sample_rate=16000,
                          callback=None)
result = recognition.call('{YOUR_AUDIO_FILE}')
if result.status_code == HTTPStatus.OK:
    print('Recognition result:')
    print(result.get_sentence())
else:
    print('Error: ', result.message)

print(
    '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
    .format(
        recognition.get_last_request_id(),
        recognition.get_first_package_delay(),
        recognition.get_last_package_delay(),
    ))

双方向ストリーミング呼び出し

単一のリアルタイム音声認識タスクを送信し、コールバックインターフェイスを実装することで、リアルタイムの認識結果をストリーミングで取得します。

  1. ストリーミング音声認識を開始します。

    Recognition クラス をインスタンス化し、リクエストパラメーターコールバックインターフェイス (RecognitionCallback) をバインドして、start メソッドを呼び出し、ストリーミング音声認識を開始します。

  2. 音声をストリーミングします。

    Recognition クラスsend_audio_frame メソッドをループで呼び出し、バイナリ音声ストリームをセグメントに分けてサーバーに送信します。ストリームは、ローカルファイルまたはマイクなどのデバイスから読み取られます。

    音声の送信中に、サーバーは コールバックインターフェイス (RecognitionCallback)on_event メソッドを通じて、認識結果をリアルタイムでクライアントに返します。

    フレームあたり約 100 ms の音声を送信し、各フレームを 1 KB から 16 KB の間に保ってください。

  3. タスクを終了します。

    Recognition クラスstop メソッドを呼び出して、音声認識を終了します。

    このメソッドは、 コールバックインターフェイス (RecognitionCallback)on_complete または on_error コールバックがトリガーされるまで、現在のスレッドをブロックします。

完全な例の表示

import os
import signal  # キーボードイベント処理用 (「Ctrl+C」を押して録音を終了)
import sys

import dashscope
import pyaudio
from dashscope.audio.asr import *

mic = None
stream = None

# 録音パラメーターの設定
sample_rate = 16000  # サンプリングレート (Hz)
channels = 1  # モノラルチャネル
dtype = 'int16'  # データ型
format_pcm = 'pcm'  # 音声データのフォーマット
block_size = 3200  # バッファあたりのフレーム数

# リアルタイム音声認識コールバック
class Callback(RecognitionCallback):
    def on_open(self) -> None:
        global mic
        global stream
        print('RecognitionCallback open.')
        mic = pyaudio.PyAudio()
        stream = mic.open(format=pyaudio.paInt16,
                          channels=1,
                          rate=16000,
                          input=True)

    def on_close(self) -> None:
        global mic
        global stream
        print('RecognitionCallback close.')
        stream.stop_stream()
        stream.close()
        mic.terminate()
        stream = None
        mic = None

    def on_complete(self) -> None:
        print('RecognitionCallback completed.')  # 認識完了

    def on_error(self, message) -> None:
        print('RecognitionCallback task_id: ', message.request_id)
        print('RecognitionCallback error: ', message.message)
        # 音声ストリームが実行中の場合は停止して閉じます
        if 'stream' in globals() and stream.active:
            stream.stop()
            stream.close()
        # プログラムを強制終了します
        sys.exit(1)

    def on_event(self, result: RecognitionResult) -> None:
        sentence = result.get_sentence()
        if 'text' in sentence:
            print('RecognitionCallback text: ', sentence['text'])
            if RecognitionResult.is_sentence_end(sentence):
                print(
                    'RecognitionCallback sentence end, request_id:%s, usage:%s'
                    % (result.get_request_id(), result.get_usage(sentence)))

def signal_handler(sig, frame):
    print('Ctrl+C pressed, stop recognition ...')
    # 認識を停止
    recognition.stop()
    print('Recognition stopped.')
    print(
        '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
        .format(
            recognition.get_last_request_id(),
            recognition.get_first_package_delay(),
            recognition.get_last_package_delay(),
        ))
    # プログラムを強制終了します
    sys.exit(0)

# メイン関数
if __name__ == '__main__':
    # API キーは、シンガポールリージョンと北京リージョンで異なります。 API キーの取得: https://www.alibabacloud.com/help/model-studio/get-api-key
    # 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください: dashscope.api_key = "sk-xxx"
    dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

    # 以下はシンガポールリージョンの設定です。 呼び出す際に、"{WorkspaceId}" を実際のワークスペース ID に置き換えてください。 設定はリージョンによって異なります。
    dashscope.base_websocket_api_url='wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference'

    # 認識コールバックを作成します
    callback = Callback()

    # 非同期モードで認識サービスを呼び出します。モデル、フォーマット、
    # サンプリングレートなどの認識パラメーターをカスタマイズできます
    recognition = Recognition(
        model='qwen-audio-3.0-asr-flash-streaming',
        format=format_pcm,
        # 'pcm'、'wav'、'opus'、'speex'、'aac'、'amr'。サポートされているフォーマットはドキュメントで確認できます
        sample_rate=sample_rate,
        # 8000、16000 をサポート
        semantic_punctuation_enabled=False,
        callback=callback)

    # 認識を開始
    recognition.start()

    signal.signal(signal.SIGINT, signal_handler)
    print("Press 'Ctrl+C' to stop recording and recognition...")
    # 「Ctrl+C」が押された際の処理を設定します

    while True:
        if stream:
            data = stream.read(3200, exception_on_overflow=False)
            recognition.send_audio_frame(data)
        else:
            break

    recognition.stop()
import os
import time
import dashscope
from dashscope.audio.asr import *

# API キーは、シンガポールリージョンと北京リージョンで異なります。 API キーの取得: https://www.alibabacloud.com/help/model-studio/get-api-key
# 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# 以下はシンガポールリージョンの設定です。 呼び出す際に、"{WorkspaceId}" を実際のワークスペース ID に置き換えてください。 設定はリージョンによって異なります。
dashscope.base_websocket_api_url='wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference'

from datetime import datetime

def get_timestamp():
    now = datetime.now()
    formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
    return formatted_timestamp

class Callback(RecognitionCallback):
    def on_complete(self) -> None:
        print(get_timestamp() + ' Recognition completed')  # 認識完了

    def on_error(self, result: RecognitionResult) -> None:
        print('Recognition task_id: ', result.request_id)
        print('Recognition error: ', result.message)
        exit(0)

    def on_event(self, result: RecognitionResult) -> None:
        sentence = result.get_sentence()
        if 'text' in sentence:
            print(get_timestamp() + ' RecognitionCallback text: ', sentence['text'])
        if RecognitionResult.is_sentence_end(sentence):
            print(get_timestamp() +
                  'RecognitionCallback sentence end, request_id:%s, usage:%s'
                  % (result.get_request_id(), result.get_usage(sentence)))

callback = Callback()

recognition = Recognition(model='qwen-audio-3.0-asr-flash-streaming',
                          format='wav',
                          sample_rate=16000,
                          callback=callback)

try:
    audio_data: bytes = None
    f = open("{YOUR_AUDIO_FILE}", 'rb')
    if os.path.getsize("{YOUR_AUDIO_FILE}"):
        # ファイルデータを一度にすべてバッファに読み込みます
        file_buffer = f.read()
        f.close()
        print("Start Recognition")
        recognition.start()

        # バッファから一度に 3200 バイトを送信します
        buffer_size = len(file_buffer)
        offset = 0
        chunk_size = 3200

        while offset < buffer_size:
            # 今回送信するデータチャンクのサイズを計算します
            remaining_bytes = buffer_size - offset
            current_chunk_size = min(chunk_size, remaining_bytes)

            # バッファから現在のデータチャンクを抽出します
            audio_data = file_buffer[offset:offset + current_chunk_size]

            # 音声データフレームを送信します
            recognition.send_audio_frame(audio_data)
            # オフセットを更新します
            offset += current_chunk_size

            # リアルタイム伝送をシミュレートするために遅延を追加します
            time.sleep(0.1)

        recognition.stop()
    else:
        raise Exception(
            'The supplied file was empty (zero bytes long)')
except Exception as e:
    raise e

print(
    '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
    .format(
        recognition.get_last_request_id(),
        recognition.get_first_package_delay(),
        recognition.get_last_package_delay(),
    ))

リクエストパラメーター

リクエストパラメーターは、Recognition クラスのコンストラクター (init) で設定します。

パラメータータイプ必須説明

model

str

はい

モデル名。 Qwen-Audio-3.0-ASR-Flash-Streaming および Fun-ASR-Realtime モデルシリーズがサポートされています。詳細については、「サポートされているモデルとリージョン」をご参照ください。

sample_rate

int

はい

サンプリングレート (Hz)。

有効な値: 8 kHz モデルは 8000 Hz のみをサポートします。その他のモデルは任意のサンプリングレートをサポートします。

format

str

はい

オーディオフォーマット。

有効な値:

  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr

重要opus/speex: Ogg カプセル化を使用する必要があります。

wav: PCM エンコーディングを使用する必要があります。

amr: AMR-NB タイプのみをサポートしています。

vocabulary_id

str

いいえ

事前コンパイル済みのホットワードリストのID。

ホットワードリスト作成 API を呼び出して、この ID を事前に生成します。認識時に ID を渡して、リスト内のホットワードを使用します。

語彙が既知で比較的安定しており、リクエスト間で同じ単語リストを再利用する必要があるシナリオに適しています。

使用法の詳細については、「事前コンパイル済みホットワード」をご参照ください。

vocabulary

dict

いいえ

インスタントホットワード。

キーと値のペアとして渡します。キーはホットワードのテキスト (文字列)、値はホットワードの重み (整数) です。事前にホットワードリストを作成する必要はありません。重みの範囲は [1, 5] または 50 に設定します。値が [1, 5] の範囲内である場合、値が大きくなるほどモデルがその単語を出力する可能性が高くなります。値が 50 の場合はスーパーホットワードを指定し、再現率が大幅に向上しますが、スーパーホットワードの数は 50 を超えることはできません。

一時的なセッションレベルのホットワードの最適化に適しています。

事前コンパイル済みのホットワードと一緒に設定した場合、インスタントホットワードのみが有効になります。使用法の詳細については、「インスタントホットワード」をご参照ください。

重要qwen-audio-3.0-asr-flash-streaming のみがインスタントホットワードをサポートします。

例:

from dashscope.audio.asr import Recognition

vocab = {"John Smith": 5, "Jane Doe": 5}
recognition = Recognition(
    model='qwen-audio-3.0-asr-flash-streaming',
    format='wav',
    sample_rate=16000,
    vocabulary=vocab,
    callback=None)

semantic_punctuation_enabled

bool

いいえ

セマンティックセグメンテーションを有効にするかどうか。

デフォルト:False。

  • True:セマンティックセグメンテーションを有効にし、VAD セグメンテーションを無効にします。
  • False (デフォルト):VAD セグメンテーションを有効にし、セマンティックセグメンテーションを無効にします。

セマンティックセグメンテーションはより正確で、会議の文字起こしに適しています。音声アクティビティ検出 (VAD) セグメンテーションはレイテンシーが低く、対話型のシナリオに適しています。

max_sentence_silence

int

いいえ

セグメンテーションのための VAD の無音しきい値 (ミリ秒)。音声セグメントの後の無音時間がこのしきい値を超えると、システムは文が終了したと判断します。semantic_punctuation_enabledtrue に設定されている場合、このパラメーターは sentence_end を返す基準として使用されませんが、低すぎる値を設定すると認識性能に影響を与える可能性があります。

デフォルト値: 1300。

有効な値: [200, 6000]。

multi_threshold_mode_enabled

bool

いいえ

重要semantic_punctuation_enabled が false の場合にのみ有効です。

マルチしきい値モードを有効にするかどうか。有効にすると、VAD セグメンテーションが長すぎるセグメントを生成するのを防ぎます。

デフォルト:False。

punctuation_prediction_enabled

bool

いいえ

認識結果に句読点を自動的に追加するかどうか:

  • True (デフォルト):有効。この値は変更できません。

heartbeat

bool

いいえ

ハートビートパケットを有効にするかどうか。

デフォルト:False。

  • True:無音音声が継続的に送信されている間、サーバーへの接続を維持します。
  • False (デフォルト):無音音声が継続的に送信されていても、接続は一定時間後にタイムアウトして切断されます。

無音オーディオとは、オーディオファイルまたはデータストリーム内で音声信号を含まないコンテンツを指します。 Audacity や Adobe Audition のような音声編集ソフトウェアを使用したり、FFmpeg のようなコマンドラインツールを使用したりするなど、いくつかの方法で無音のオーディオを生成できます。

このフィールドには SDK バージョン 1.23.1 以降が必要です。

language_hints

list[str]

いいえ

認識する音声の言語。デフォルト値はありません。設定しない場合、モデルは自動的に言語を検出します。

Qwen-Audio-3.0-ASR-Flash-Streaming モデルシリーズでは、最大 4 つの値を設定できます。4 つ以上設定した場合、最初の 4 つのみが有効になります。Fun-ASR-Realtime モデルシリーズでは、1 つの値しか設定できません。複数の値を設定した場合、最初の値のみが有効になります。

クリックしてサポートされている言語コードを表示

  • qwen-audio-3.0-asr-flash-streaming, fun-asr-realtime, fun-asr-realtime-2025-11-07:

    • zh: 中国語
    • en: 英語
    • ja: 日本語
    • ko: 韓国語
    • vi: ベトナム語
    • th: タイ語
    • id: インドネシア語
    • ms: マレー語
    • tl: フィリピノ語
    • hi: ヒンディー語
    • ar: アラビア語
    • fr: フランス語
    • de: ドイツ語
    • es: スペイン語
    • pt: ポルトガル語
    • ru: ロシア語
    • it: イタリア語
    • nl: オランダ語
    • sv: スウェーデン語
    • da: デンマーク語
    • fi: フィンランド語
    • no: ノルウェー語
    • el: ギリシャ語
    • pl: ポーランド語
    • cs: チェコ語
    • hu: ハンガリー語
    • ro: ルーマニア語
    • bg: ブルガリア語
    • hr: クロアチア語
    • sk: スロバキア語
  • fun-asr-realtime-2026-02-28:

    • zh: 中国語
    • en: 英語
    • ja: 日本語
  • fun-asr-realtime-2025-09-15:

    • zh: 中国語
    • en: 英語
  • fun-asr-flash-8k-realtime, fun-asr-flash-8k-realtime-2026-01-28:

    • zh: 中国語

speech_noise_threshold

float

いいえ

音声とノイズを区別するためのしきい値であり、VAD (音声アクティビティ検出) の感度調整に使用します。

有効な値: [-1.0, 1.0]。

値の説明:

  • 値が -1 に近いほど: ノイズしきい値が低下するため、ノイズが音声として認識されやすくなり、より多くのノイズが文字起こしされる可能性があります。
  • 値が +1 に近いほど: ノイズしきい値が上昇するため、音声がノイズとして誤って判断されやすくなり、一部の音声がフィルタリングされる可能性があります。

これは高度な設定パラメーターです。調整すると認識結果に大きな影響を与える可能性があります。推奨事項:

  • 調整する前に、結果を十分にテストおよび検証してください。
  • 実際の音声環境に基づいて、少しずつ調整してください (0.1 のステップを推奨します)。

special_word_filter

str

いいえ

音声認識中に処理するセンシティブな単語を指定し、単語ごとに異なる処理方法を設定できます。詳細については、「センシティブな単語のフィルタリング」をご参照ください。

callback

RecognitionCallback

いいえ

コールバックインターフェイス (RecognitionCallback)

以下のパラメーターを、Recognition インスタンスの call または start メソッドにキーワード引数として渡します。

パラメータータイプ必須説明

raw_input

dict

いいえ

会話コンテキストを渡すために使用される入力オブジェクト。コンテキスト強化により、ドメイン固有の用語の認識精度が向上します。使用方法については、「クイックスタート」をご参照ください。

重要コンテキストパラメーターは、qwen-audio-3.0-asr-flash-streamingfun-asr-realtime、および fun-asr-realtime-2025-11-07 モデルでのみサポートされています。

dict には、値がメッセージのリスト (list[dict]) である context キーを含める必要があります。各メッセージには、次のフィールドが含まれます:

  • role (str, 必須):メッセージのロール。user は、以前のユーザーの会話ターンからの認識結果またはドメイン固有の単語リストを表します。assistant は、以前のターンからの大規模言語モデルのレスポンスを表します。
  • content (list[dict], 必須):メッセージコンテンツのリスト。各要素には type (str; ロールが user の場合は input_text、ロールが assistant の場合は text に設定) と text (str, テキストコンテンツ) が含まれます。

重要制限:input_text および text タイプのコンテキストメッセージは、それぞれ 5 メッセージに制限されます。制限を超えた場合、最新の 5 メッセージのみが保持されます。コンテキストターンあたりの合計テキスト長は 400 文字を超えることはできず、超過分は末尾から切り捨てられます。

重要コンテキストを渡す際、context 内のメッセージは特定の順序に従う必要があります。コンテキストメッセージは会話ターンごとに配置する必要があり、各ターン内で user メッセージ (input_text タイプ) は、対応する assistant メッセージ (text タイプ) の前に置く必要があります。

注記このフィールドには SDK バージョン 1.25.23 以降が必要です。

raw_inputRecognition インスタンスの start または call メソッドに渡します:

# 渡すための入力を構築します
input_context = {
    "context": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Hello there"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, I am Qwen. How can I help you?"
                }
            ]
        }
    ]
}

# raw_input パラメーターで渡します
recognition.start(raw_input=input_context)
# または
recognition.call(raw_input=input_context)

主要なインターフェイス

Recognition クラス

"from dashscope.audio.asr import *" を使用して Recognition をインポートします。

メンバーメソッドメソッドシグネチャ説明

call

def call(self, file: str, phrase_id: str = None, **kwargs) -> RecognitionResult

ローカルファイルに基づく非ストリーミング呼び出しです。このメソッドは、すべての音声が読み取られるまで現在のスレッドをブロックし、ファイルに対する読み取り権限も必要です。

認識結果は RecognitionResult オブジェクトとして返されます。

start

def start(self, phrase_id: str = None, **kwargs)

音声認識を開始します。

コールバックベースのストリーミングによるリアルタイム認識です。このメソッドは現在のスレッドをブロックしません。 send_audio_frame および stop と併用してください。

send_audio_frame

def send_audio_frame(self, buffer: bytes)

音声を送信します。送信するオーディオフレームは大きすぎず小さすぎないようにしてください。目安はフレームあたり約 100 ms、サイズは 1 KB ~ 16 KB です。

認識結果は、 コールバックインターフェイス (RecognitionCallback) の on_event メソッドで取得します。

stop

def stop(self)

音声認識を停止します。サーバーが受信済みのすべての音声の認識を完了するまで呼び出しをブロックし、その後タスクを終了します。

get_last_request_id

def get_last_request_id(self)

リクエスト ID を取得します。コンストラクターの呼び出し (オブジェクトの作成) 後に利用できます。

get_first_package_delay

def get_first_package_delay(self)

初回パケット遅延を取得します。これは、最初の音声パケットを送信してから最初の認識結果を受信するまでのレイテンシーです。タスク完了後に使用してください。

get_last_package_delay

def get_last_package_delay(self)

最終パケット遅延を取得します。これは、 stop コマンドを送信してから最後の認識結果を受信するまでの時間です。タスク完了後に使用してください。

get_response

def get_response(self)

最後のメッセージを取得します。タスク失敗時のエラーを取得するために使用します。

コールバックインターフェイス (RecognitionCallback)

双方向ストリーミング 呼び出しでは、サーバーはコールバックを通じて、主要なプロセス情報とデータをクライアントに返します。コールバックメソッドを実装して、サーバーから返される情報とデータを処理してください。

例を表示

class Callback(RecognitionCallback):
    def on_open(self) -> None:
        print('Connection established')

    def on_event(self, result: RecognitionResult) -> None:
        # 認識結果を受信するロジックを実装します
        pass

    def on_complete(self) -> None:
        print('Task completed')

    def on_error(self, result: RecognitionResult) -> None:
        print('An error occurred:', result)

    def on_close(self) -> None:
        print('Connection closed')

callback = Callback()
メソッドパラメーター戻り値説明
def on_open(self) -> None

None

None

サーバーへの接続が確立された直後に呼び出されます。

def on_event(self, result: RecognitionResult) -> None

resultRecognitionResult オブジェクト

None

サーバーから応答があった場合に呼び出されます。

def on_complete(self) -> None

None

None

すべての認識結果が返された後に呼び出されます。

def on_error(self, result: RecognitionResult) -> None

resultRecognitionResult オブジェクト

None

エラーが発生した場合に呼び出されます。

def on_close(self) -> None

None

None

サーバーが接続を閉じた後に呼び出されます。

応答

認識結果 (RecognitionResult)

RecognitionResult は、双方向ストリーミング呼び出しにおける 1 回のリアルタイム認識の結果、または非ストリーミング呼び出しの結果を表します。

メンバーメソッドメソッドシグネチャ説明

get_sentence

def get_sentence(self) -> Union[Dict[str, Any], List[Any]]

現在認識されている文と、そのタイムスタンプ情報を取得します。コールバックは 1 文ずつ返すため、このメソッドは Dict[str, Any] を返します。

詳細については、「文 (Sentence)」をご参照ください。

get_request_id

def get_request_id(self) -> str

リクエスト ID を取得します。

is_sentence_end

@staticmethod
def is_sentence_end(sentence: Dict[str, Any]) -> bool

指定した文が終了しているかどうかを判断します。このメソッドは、sentence 内の end_time フィールドが None かどうかを確認します。end_timeNone でない場合は、文が終了したことを示します。RecognitionResult.is_sentence_end(sentence) として呼び出してください。ここでの sentence は、get_sentence() が返す 1 文の dict であり、Sentence インスタンスのブール値フィールドではありません。

文情報 (Sentence)

Sentence クラスのメンバーは次のとおりです:

パラメーター

説明

begin_time

int

文の開始時刻 (ms) です。

end_time

int

文の終了時刻 (ms) です。

text

str

認識されたテキストです。

words

単語レベルのタイムスタンプ情報 (Word) のリスト

単語レベルのタイムスタンプ情報です。

単語レベルのタイムスタンプ情報 (Word)

Word クラスのメンバーは次のとおりです:

パラメーター

説明

begin_time

int

単語の開始時刻 (ms) です。

end_time

int

単語の終了時刻 (ms) です。

text

str

単語です。

punctuation

str

句読点です。

エラーコード

エラーが発生した場合は、「エラーコード」を参照してトラブルシューティングを行ってください。

問題が解決しない場合は、開発者コミュニティ に参加し、問題を報告して Request ID を提供してください。

よくある質問

機能

Q:長時間の無音状態でも接続を維持するにはどうすればよいですか?

heartbeat リクエストパラメーターを true に設定し、サーバーに無音オーディオを送信し続けます。

無音オーディオは、オーディオファイルまたはストリームに含まれる音響信号のないコンテンツです。無音オーディオは、Audacity や Adobe Audition などのオーディオ編集ソフトウェア、または FFmpeg などのコマンドラインツールを使用して、いくつかの方法で生成できます。

Q:オーディオをサポートされているフォーマットに変換するにはどうすればよいですか?

FFmpeg を使用します。詳しい使い方については、FFmpeg の公式サイトをご参照ください。

# 基本的な変換コマンド (汎用テンプレート)
# -i: 入力ファイルパス。例: audio.wav
# -c:a: オーディオコーデック。例: aac、libmp3lame、pcm_s16le
# -b:a: ビットレート (音質制御)。例: 192k、320k
# -ar: サンプルレート。例: 44100 (CD)、48000、16000
# -ac: チャンネル数。例: 1 (モノラル)、2 (ステレオ)
# -y: 既存のファイルを上書き (値は不要)
ffmpeg -i input_audio.ext -c:a codec_name -b:a bitrate -ar sample_rate -ac channels output.ext

# 例:WAV から MP3 へ (元の品質を維持)
ffmpeg -i input.wav -c:a libmp3lame -q:a 0 output.mp3
# 例:MP3 から WAV へ (16 ビット PCM 標準フォーマット)
ffmpeg -i input.mp3 -c:a pcm_s16le -ar 44100 -ac 2 output.wav
# 例:M4A から AAC へ (Apple オーディオの抽出または変換)
ffmpeg -i input.m4a -c:a copy output.aac  # 再エンコードせずに直接抽出
ffmpeg -i input.m4a -c:a aac -b:a 256k output.aac  # 品質を向上させるために再エンコード
# 例:FLAC ロスレスから Opus へ (高圧縮)
ffmpeg -i input.flac -c:a libopus -b:a 128k -vbr on output.opus

Q:ローカルファイル (録音) を認識するにはどうすればよいですか?

ローカルファイルを認識するには 2 つの方法があります:

  • ローカルファイルパスを直接渡す:この方法では、認識が完了した後にのみ完全な結果が返されるため、即時のフィードバックが必要なシナリオには適していません。

    非ストリーミング呼び出し」を参照し、Recognition クラスcall メソッドにファイルパスを渡して録音を直接認識します。

  • ローカルファイルをバイナリストリームに変換して認識する:この方法では、結果をストリーミングしながらファイルを認識するため、即時のフィードバックが必要なシナリオに適しています。

    双方向ストリーミングコール」を参照し、Recognition クラスsend_audio_frame メソッドを使用して、バイナリ ストリームをサーバーに送信して認識を行います。

トラブルシューティング

Q:音声が認識されない (認識結果がない) のはなぜですか?

  1. リクエストパラメーターの音声フォーマット (format) とサンプルレート (sampleRate/sample_rate) が正しいこと、およびパラメーターの制約を満たしていることを確認してください。 よくあるエラーとして、以下が挙げられます。

    • 音声ファイルの拡張子は .wav ですが、実際は MP3 形式であり、format リクエストパラメーターは mp3 に設定されています(パラメーター設定が正しくありません)。
    • 音声サンプルレートは 3600 Hz ですが、sampleRate/sample_rate リクエストパラメーターは 48000 に設定されています (不正なパラメーター設定)。

    ffprobe ツールを使用して、オーディオのコンテナ、コーデック、サンプルレート、チャンネル数、その他の情報を取得します:

ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx
  1. 上記のいずれのチェックでも問題が解決しない場合は、カスタムホットワードを追加して特定の用語の認識を向上させてください。