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

Alibaba Cloud Model Studio:Python SDK

最終更新日:Jul 03, 2026

Paraformer リアルタイム音声認識 Python SDK のパラメーターおよびインターフェイスについて説明します。

重要

このドキュメントは 中国 (北京) リージョンにのみ適用されます。モデルを使用するには、中国 (北京) リージョンの API キー を使用する必要があります。

重要

Alibaba Cloud Model Studio は、中国 (北京) リージョン向けにワークスペース専用ドメインをリリースしました。この新しい専用ドメインは、推論リクエストに対して優れたパフォーマンスと高い安定性を提供します。dashscope.aliyuncs.com から {WorkspaceId}.cn-beijing.maas.aliyuncs.com への移行を推奨します。

{WorkspaceId} は、実際の ワークスペース ID に置き換えてください。既存のドメインは引き続き完全に機能します。

ユーザーガイド: モデルの概要および選定に関する推奨事項については、「リアルタイム音声認識 - Fun-ASR/Paraformer」をご参照ください。

前提条件

  • サービスを有効化し、API キーを取得 してください。セキュリティリスクを回避するため、コード内に API キーをハードコードせず、環境変数として API キーを構成 することを推奨します。

    説明

    サードパーティ製アプリケーションやユーザーに一時的なアクセス権を付与する場合、または機密データへのアクセスや削除など高リスク操作を厳密に制御したい場合は、一時認証トークン の使用を推奨します。

    長期的な API キーよりも、一時認証トークンは有効期間が短く(60 秒)、セキュリティが高いため、一時的な呼び出しシナリオに適しており、API キー漏洩のリスクを効果的に低減できます。

    使用方法: コード内で、認証に使用していた API キーを取得した一時認証トークンに置き換えます。

  • 最新の DashScope SDK をインストール してください。

モデル一覧

paraformer-realtime-v2

paraformer-realtime-8k-v2

シナリオ

ライブ配信、会議などのシナリオ

電話オペレーターやボイスメールなどの 8 kHz 音声認識

サンプルレート

任意

8kHz

言語

中国語(標準中国語および各種方言)、英語、日本語、韓国語、ドイツ語、フランス語、ロシア語

サポートされる中国語方言: 上海語、呉語、閩南語、東北弁、甘粛弁、貴州弁、河南弁、湖北弁、湖南弁、江西弁、寧夏弁、山西弁、陝西弁、山東弁、四川弁、天津弁、雲南弁、広東語

中国語

句読点予測

✅ デフォルトでサポートされています。追加の設定は不要です。

✅ デフォルトでサポートされています。追加の設定は不要です。

逆テキスト正規化(ITN)

✅ デフォルトでサポートされています。追加の設定は不要です。

✅ デフォルトでサポートされています。追加の設定は不要です。

カスタム語彙

✅ 「ホットワードのカスタマイズ」をご参照ください。

✅ 「ホットワードのカスタマイズ」をご参照ください。

認識言語の指定

language_hints パラメーターを使用して言語を指定します。

感情認識

✅(クリックして使用方法を表示)

感情認識には以下の制約があります。

  • paraformer-realtime-8k-v2 モデルにのみ適用されます。

  • セマンティック句読点を無効にする必要があります(リクエストパラメーター semantic_punctuation_enabled で制御)。セマンティック句読点はデフォルトで無効になっています。

  • 感情認識の結果は、RecognitionResultis_sentence_end メソッドが True を返す場合にのみ表示されます。

感情検出結果を取得するには、単文情報(Sentence)emo_tag フィールドおよび emo_confidence フィールドから、それぞれ現在の文の感情および感情の信頼度を取得します。

クイックスタート

Recognition クラス は、非ストリーミング呼び出しと双方向ストリーミング呼び出しの両方に対応するメソッドを提供します。要件に応じて適切なメソッドを選択してください。

  • 非ストリーミング呼び出し: ローカルファイルを認識し、一度に完全な結果を返します。事前に録音された音声の処理に適しています。

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

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

このメソッドは、ローカルファイルに対してリアルタイム音声テキスト変換タスクを送信します。完全な文字起こし結果が返されるまで処理はブロックされます。

Recognition クラス をインスタンス化し、リクエストパラメーター を設定してから、call メソッドを呼び出して認識または翻訳を実行し、RecognitionResult を取得します。

完全なサンプルコードを表示

サンプルで使用する音声ファイル:asr_example.wav

from http import HTTPStatus
from dashscope.audio.asr import Recognition
# 中国 (北京): {WorkspaceId} を実際のワークスペース ID に置き換えてください。リージョンによって構成が異なります。
dashscope.base_websocket_api_url = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

# 環境変数に API キーを構成していない場合は、次の行のコメントを外し、apiKey をご自身の API キーに置き換えてください。
# import dashscope
# dashscope.api_key = "apiKey"

recognition = Recognition(model='paraformer-realtime-v2',
                          format='wav',
                          sample_rate=16000,
                          # language_hints パラメーターは paraformer-realtime-v2 モデルでのみサポートされます。
                          language_hints=['zh', 'en'],
                          callback=None)
result = recognition.call('asr_example.wav')
if result.status_code == HTTPStatus.OK:
    print('認識結果:')
    print(result.get_sentence())
else:
    print('エラー: ', 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 ミリ秒、データサイズは 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 *
# 中国 (北京): {WorkspaceId} を実際のワークスペース ID に置き換えてください。リージョンによって構成が異なります。
dashscope.base_websocket_api_url = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

mic = None
stream = None

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


def init_dashscope_api_key():
    """
        DashScope API キーを設定します。詳細については以下をご参照ください:
        https://github.com/aliyun/alibabacloud-bailian-speech-demo/blob/master/PREREQUISITES.md
    """

    if 'DASHSCOPE_API_KEY' in os.environ:
        dashscope.api_key = os.environ[
            'DASHSCOPE_API_KEY']  # 環境変数 DASHSCOPE_API_KEY から API キーを読み込み
    else:
        dashscope.api_key = '<your-dashscope-api-key>'  # 手動で API キーを設定


# リアルタイム音声認識コールバック
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 が押されました。認識を停止中...')
    # 認識を停止
    recognition.stop()
    print('認識が停止されました。')
    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)


# main function
if __name__ == '__main__':
    init_dashscope_api_key()
    print('初期化中...')

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

    # 非同期モードで認識サービスを呼び出します。model、format、sample_rate などの認識パラメーターをカスタマイズできます。
    recognition = Recognition(
        model='paraformer-realtime-v2',
        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("「Ctrl+C」を押して録音および認識を停止してください...")
    # 「Ctrl+C」が押されるまでキーボードリスナーを維持

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

    recognition.stop()

ローカル音声ファイルの認識

サンプルで使用する音声ファイル:asr_example.wav

import os
import time
from dashscope.audio.asr import *
# 中国 (北京): {WorkspaceId} を実際のワークスペース ID に置き換えてください。リージョンによって構成が異なります。
dashscope.base_websocket_api_url = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

# 環境変数に API キーを構成していない場合は、次の行のコメントを外し、apiKey をご自身の API キーに置き換えてください。
# import dashscope
# dashscope.api_key = "apiKey"

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() + ' 認識完了')  # 認識完了

    def on_error(self, result: RecognitionResult) -> None:
        print('認識 task_id: ', result.request_id)
        print('認識エラー: ', 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='paraformer-realtime-v2',
                          format='wav',
                          sample_rate=16000,
                          # language_hints パラメーターは paraformer-realtime-v2 モデルでのみサポートされます。
                          language_hints=['zh', 'en'],
                          callback=callback)

recognition.start()

try:
    audio_data: bytes = None
    f = open("asr_example.wav", 'rb')
    if os.path.getsize("asr_example.wav"):
        while True:
            audio_data = f.read(3200)
            if not audio_data:
                break
            else:
                recognition.send_audio_frame(audio_data)
            time.sleep(0.1)
    else:
        raise Exception(
            '指定されたファイルは空です(サイズが 0 バイト)')
    f.close()
except Exception as e:
    raise e

recognition.stop()

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(),
    ))

同時呼び出し

Python では、グローバルインタープリターロック(GIL) の影響により、一度に 1 つのスレッドしか Python コードを実行できません(ただし、一部のパフォーマンス重視のライブラリではこの制限が解除される場合があります)。マルチコアコンピューターの計算リソースをより有効に活用したい場合は、multiprocessing または concurrent.futures.ProcessPoolExecutor の使用を推奨します。高い同時実行性の下では、マルチスレッドが SDK 呼び出しの遅延を大幅に増加させる可能性があります。

リクエストパラメーター

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

パラメーター

デフォルト

必須

説明

model

str

-

はい

リアルタイム音声認識に使用するモデル。詳細については、「モデル一覧」をご参照ください。

sample_rate

int

-

はい

認識対象の音声のサンプルレート(Hz 単位)を設定します。

モデルごとに異なります。

  • paraformer-realtime-v2 は任意のサンプルレートをサポートします。

  • paraformer-realtime-8k-v2 は 8000 Hz サンプルレートのみをサポートします。

format

str

-

はい

認識対象の音声フォーマットを設定します。

サポートされる音声フォーマット: pcm、wav、mp3、opus、speex、aac、amr。

重要

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

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

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

vocabulary_id

str

-

いいえ

ホットワード ID を設定します。設定しない場合、ホットワードは有効になりません。v2 以降のモデルでは、このフィールドを使用してホットワード ID を設定します。

現在の音声認識セッションでは、このホットワード ID に対応するホットワード情報が適用されます。詳細な使用方法については、「カスタムホットワード」をご参照ください。

disfluency_removal_enabled

bool

False

いいえ

言い淀みのフィルタリングを有効にするかどうかを設定します。

  • true: 言い淀みをフィルタリング

  • false(デフォルト): フィラー語をフィルターしない

language_hints

list[str]

["zh", "en"]

いいえ

認識対象の言語コードを設定します。事前に言語を特定できない場合は、このパラメーターを未設定のままにしておくと、モデルが自動的に言語を検出します。

現在サポートされている言語コード:

  • zh: 中国語

  • en: 英語

  • ja: 日本語

  • yue: 広東語

  • ko: 韓国語

  • de: ドイツ語

  • fr: フランス語

  • ru: ロシア語

このパラメーターは多言語モデルにのみ適用されます。詳細については、「モデル一覧」をご参照ください。

semantic_punctuation_enabled

bool

False

いいえ

セマンティックセグメンテーションを有効にするかどうかを設定します。デフォルトでは無効です。

  • true: セマンティックセグメンテーションを有効にし、VAD(Voice Activity Detection)セグメンテーションを無効にします。

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

セマンティックセグメンテーションは精度が高く、会議の文字起こしなどのシナリオに適しています。VAD(Voice Activity Detection)セグメンテーションは遅延が少なく、インタラクティブなシナリオに適しています。

semantic_punctuation_enabled パラメーターを調整することで、異なるシナリオに応じて音声認識のセグメンテーション方法を柔軟に切り替えることができます。

このパラメーターは、モデルが v2 以降の場合にのみ有効になります。

max_sentence_silence

int

800

いいえ

VAD(Voice Activity Detection)セグメンテーションのサイレンス持続時間しきい値(ミリ秒単位)を設定します。

発話セグメント後のサイレンス持続時間がこのしきい値を超えると、システムは文が終了したと判断します。

パラメーターの範囲は 200 ミリ秒~6000 ミリ秒で、デフォルト値は 800 ミリ秒です。

このパラメーターは、semantic_punctuation_enabled パラメーターが false(VAD セグメンテーション)で、かつモデルが v2 以降の場合にのみ有効になります。

multi_threshold_mode_enabled

bool

False

いいえ

このスイッチを有効にすると(true)、VAD セグメンテーションによる長すぎる文の切断を防止します。デフォルトでは無効です。

このパラメーターは、semantic_punctuation_enabled パラメーターが false(VAD セグメンテーション)で、かつモデルが v2 以降の場合にのみ有効になります。

punctuation_prediction_enabled

bool

True

いいえ

認識結果に自動的に句読点を追加するかどうかを設定します。

  • true(デフォルト): はい

  • false: いいえ

このパラメーターは、モデルが v2 以降の場合にのみ有効になります。

heartbeat

bool

False

いいえ

サーバーとの長時間接続を維持する必要がある場合、このスイッチを使用して動作を制御します。

  • true: サイレント音声を継続的に送信しても、サーバーとの接続が途切れることなく維持されます。

  • false(デフォルト): サイレント音声を継続的に送信していても、60 秒後にタイムアウトにより接続が切断されます。

    サイレント音声とは、音声信号を含まない音声ファイルまたはデータストリームを指します。サイレント音声は、Audacity や Adobe Audition などの音声編集ソフトウェア、または FFmpeg などのコマンドラインツールを使用して生成できます。

このパラメーターは、モデルが v2 以降の場合にのみ有効になります。

このフィールドを使用する場合、SDK バージョンは 1.23.1 以降である必要があります。

inverse_text_normalization_enabled

bool

True

いいえ

ITN(逆テキスト正規化)を有効にするかどうかを設定します。

デフォルトでは有効(true)です。有効にすると、漢数字がアラビア数字に変換されます。

このパラメーターは、モデルが v2 以降の場合にのみ有効になります。

callback

RecognitionCallback

-

いいえ

RecognitionCallback インターフェイス

主要インターフェイス

Recognition クラス

Recognition クラスは、from dashscope.audio.asr import * を使用してインポートします。

メンバーメソッド

メソッドシグネチャ

説明

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 ミリ秒、サイズを 1 KB ~ 16 KB 程度にすることを推奨します。

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

stop

def stop(self)

音声認識を停止します。このメソッドは、サービスが受信したすべての音声を認識し、タスクが完了するまでブロックします。

get_last_request_id

def get_last_request_id(self)

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

get_first_package_delay

def get_first_package_delay(self)

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

get_last_package_delay

def get_last_package_delay(self)

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

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

双方向ストリーミング呼び出し 中、サーバーはコールバックを使用して重要なプロセス情報およびデータをクライアントに返します。返された情報およびデータを処理するために、コールバックメソッドを実装する必要があります。

サンプルコードを表示

class Callback(RecognitionCallback):
    def on_open(self) -> None:
        print('接続成功')

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

    def on_complete(self) -> None:
        print('タスク完了')

    def on_error(self, result: RecognitionResult) -> None:
        print('例外が発生しました: ', result)

    def on_close(self) -> None:
        print('接続が閉じられました')


callback = Callback()

メソッド

パラメーター

戻り値

説明

def on_open(self) -> None

なし

なし

サーバーとの接続が確立された直後にこのメソッドが呼び出されます。

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

resultRecognitionResult

なし

サービスが応答を送信する際にこのメソッドが呼び出されます。

def on_complete(self) -> None

なし

なし

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

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

result認識結果

なし

例外が発生した際にこのメソッドが呼び出されます。

def on_close(self) -> None

なし

なし

サービスが接続を閉じた後にこのメソッドが呼び出されます。

応答結果

認識結果(RecognitionResult

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

メンバーメソッド

メソッドシグネチャ

説明

get_sentence

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

現在認識された文およびタイムスタンプ情報を取得します。コールバックでは単一の文が返されるため、このメソッドは Dict[str, Any] 型を返します。

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

get_request_id

def get_request_id(self) -> str

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

is_sentence_end

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

指定された文が終了しているかどうかを判定します。

Sentence(Sentence

Sentence クラスのメンバーは以下のとおりです。

パラメーター

説明

begin_time

int

文の開始時刻(ミリ秒単位)。

end_time

int

文の終了時刻(ミリ秒単位)。

text

str

認識されたテキスト。

words

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

単語タイムスタンプ情報。

emo_tag

str

現在の文の感情:

  • positive: 喜びや満足などポジティブな感情

  • negative: 怒りや悲しみなどネガティブな感情

  • neutral: 明らかな感情なし

感情認識には以下の制約があります。

  • paraformer-realtime-8k-v2 モデルにのみ適用されます。

  • セマンティック句読点を無効にする必要があります(リクエストパラメーター semantic_punctuation_enabled で制御)。セマンティック句読点はデフォルトで無効になっています。

  • 感情認識の結果は、RecognitionResultis_sentence_end メソッドが True を返す場合にのみ表示されます。

emo_confidence

float

現在の文の認識された感情の信頼度。値の範囲は 0.0 ~ 1.0 で、値が大きいほど信頼度が高くなります。

感情認識には以下の制約があります。

  • paraformer-realtime-8k-v2 モデルにのみ適用されます。

  • セマンティック句読点を無効にする必要があります(リクエストパラメーター semantic_punctuation_enabled で制御)。セマンティック句読点はデフォルトで無効になっています。

  • 感情認識の結果は、RecognitionResultis_sentence_end メソッドが True を返す場合にのみ表示されます。

単語タイムスタンプ情報(Word

Word クラスのメンバーは以下のとおりです。

パラメーター

説明

begin_time

int

単語の開始時刻(ミリ秒単位)。

end_time

int

単語の終了時刻(ミリ秒単位)。

text

str

単語。

punctuation

str

句読点。

エラーコード

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

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

その他のサンプル

その他のサンプルについては、GitHub をご参照ください。

よくある質問

機能

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: 各文の時間範囲を確認できますか?

はい。音声認識結果には各文の開始および終了タイムスタンプが含まれているため、各文の時間範囲を確認できます。

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
  2. paraformer-realtime-v2 モデルを使用する場合、language_hints で設定された言語が音声の実際の言語と一致しているかどうかを確認してください。

    例: 音声は実際には中国語ですが、language_hintsen(英語)に設定されている。

  3. 上記のすべてのチェックに合格すれば、特定の単語の認識精度を向上させるためにカスタムホットワードを使用できます。