Skip to main content

Python SDK

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 キーを取得した一時認証トークンに置き換えます。

モデル一覧

paraformer-realtime-v2paraformer-realtime-8k-v2
シナリオライブ配信、会議などのシナリオ電話オペレーターやボイスメールなどの 8 kHz 音声の認識
サンプリングレート任意8kHz
言語中国語(標準中国語および各種方言)、英語、日本語、韓国語、ドイツ語、フランス語、ロシア語サポートされる中国語方言: 上海語、呉語、閩南語、東北弁、甘粛弁、貴州弁、河南弁、湖北弁、湖南弁、江西弁、寧夏弁、山西弁、陝西弁、山東弁、四川弁、天津弁、雲南弁、広東語中国語
句読点予測デフォルトでサポートされています。設定は不要です。デフォルトでサポートされています。設定は不要です。
逆テキスト正規化 (ITN)デフォルトでサポートされています。設定は不要です。デフォルトでサポートされています。設定は不要です。
カスタム語彙詳細については、「ホットワードをカスタマイズする」をご参照ください。「ホットワードのカスタマイズ」をご参照ください。
認識言語の指定language_hints パラメーターを使用して言語を指定します。非対応
感情認識非対応
感情認識には以下の制約があります:
  • paraformer-realtime-8k-v2 モデルにのみ適用されます。
  • セマンティック句読点を無効にする必要があります (リクエストパラメーター semantic_punctuation_enabled で制御)。セマンティック句読点はデフォルトで無効になっています。
  • 感情認識結果は、RecognitionResult の is_sentence_end メソッドが True を返す場合にのみ表示されます。
現在の文の感情と感情の信頼度は、一文ごとの情報 (Sentence) の emo_tag フィールドと emo_confidence フィールドからそれぞれ取得します。

開始方法

コアリソース(client.audio.asr)は、非ストリーミングコールと双方向ストリーミングコールのインターフェイスを提供します。実際の要件に応じて、適切な呼び出し方法を選択してください:
  • 非ストリーミングコール(recognize_file):ローカルファイルを認識します。SDK が自動的に音声を分割送信し、タスクの終了までドライブします。事前に録音された音声の処理に適しています。
  • 双方向ストリーミングコール:音声ストリームを認識し、結果をリアルタイムで出力します。音声ストリームは、マイクなどの外部デバイスから取得することも、ローカルファイルから読み取ることもできます。即時のフィードバックを必要とするシナリオに適しています。

非ストリーミングコール

1 つのリアルタイム音声テキスト変換タスクを送信し、ローカルファイルを渡す方式で同期的にブロックして文字起こし結果を取得します。
image
コアリソース(client.audio.asr)の recognize_file メソッドを呼び出してリクエストパラメーターをバインドし、ローカルファイルのパスを渡します。サーバーイベントを反復処理して認識結果(RecognitionResult)を取得します。
import os
import dashscope

# China (Beijing):{WorkspaceId} を実際のワークスペース ID に置き換えてください。設定はリージョンによって異なります。
client = dashscope.Client(
    # 環境変数に API キーを設定していない場合は、次の行を実際の API キーに置き換えてください:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# ローカル音声ファイルを認識します:recognize_file が自動的に音声を分割送信し、タスクの終了までドライブします
for event in client.audio.asr.recognize_file(
        '{YOUR_AUDIO_FILE}',
        model='paraformer-realtime-v2',
        format='wav',
        sample_rate=16000,
        # 「language_hints」パラメーターは、paraformer-realtime-v2 モデルでのみサポートされています。
        parameters={'language_hints': ['zh', 'en']}):
    payload = event.get('payload') or {}
    sentence = (payload.get('output') or {}).get('sentence') or {}
    if sentence.get('text') and not sentence.get('heartbeat'):
        print('Recognition result: ', sentence['text'])
recognize_file はサーバーイベント(Dict[str, Any])を 1 つずつ産出します:イベントタイプは event['header']['event']、認識テキストは event['payload']['output']['sentence'] にあります(sentence_end が true の場合はその文が終了したことを示します。begin_time / end_time はタイムスタンプ、words は単語ごとのタイムスタンプであり、その他のフィールドについては単文情報(Sentence)をご参照ください)。ハートビートおよび空テキストのイベントも産出されるため、必要に応じて無視できます。双方向ストリーミングセッションでは、events() のほかに、results() で認識結果フレームのみを反復処理することもできます(型付きの認識結果(RecognitionResult)を返し、ハートビートフレームはフィルタリング済み)。詳細は get_sentence メソッドの説明をご参照ください。

双方向ストリーミングコール

1 つのリアルタイム音声テキスト変換タスクを送信し、イベントを反復処理する方式でリアルタイム認識結果をストリーミング出力します。
image
  1. ストリーミング音声認識の開始 コアリソース(client.audio.asr)の recognize メソッドを呼び出して認識セッションを作成しリクエストパラメーターをバインドします。with コンテキストに入ると(start メソッドが自動的に呼び出され、接続の確立とタスクの送信が行われます)、ストリーミング音声認識が開始されます。
  2. ストリーミング セッションの send_audio_frame メソッドを繰り返し呼び出して、ローカルファイルまたはデバイス (マイクなど) から読み取ったバイナリ音声ストリームをセグメント単位でサーバーに送信します。送信と受信は並行して行う必要があります:受信スレッドはイベント反復(events()/results())でサーバーイベントを反復処理し、認識結果をリアルタイムでクライアントに返します。 送信する各音声セグメントの長さは約 100 ミリ秒、データサイズは 1 KB から 16 KB の範囲にすることを推奨します。
  3. 処理の終了 セッションの stop メソッドを呼び出して音声認識を終了します。 このメソッドはサーバーに入力の終了のみを通知します。受信スレッドは events() を task-finished イベントまで消費し続け、最後の認識結果と統計情報を取得する必要があります。ws 層のエラーは DashScopeError 例外としてスローされるため、送信/受信処理で try/except で捕捉できます。
import os
import signal  # キーボードイベントの処理用 (「Ctrl+C」を押して録音を終了)
import sys

import dashscope
import pyaudio
from concurrent.futures import ThreadPoolExecutor

# China (Beijing):{WorkspaceId} を実際のワークスペース ID に置き換えてください。設定はリージョンによって異なります。
client = dashscope.Client(
    # 環境変数に API キーを設定していない場合は、次の行を実際の API キーに置き換えてください:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

mic = None
stream = None

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

# リアルタイム音声認識イベントレシーバー
def receive_events(rec):
    for event in rec.events():
        payload = event.get('payload') or {}
        sentence = (payload.get('output') or {}).get('sentence') or {}
        if sentence.get('text') and not sentence.get('heartbeat'):
            print('Recognition text: ', sentence['text'])
            if sentence.get('sentence_end'):
                print(
                    'Recognition sentence end, request_id:%s, usage:%s'
                    % (rec.request_id, rec.usage))

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.request_id,
            recognition.first_package_delay,
            recognition.last_package_delay,
        ))
    # プログラムを強制的に終了します
    sys.exit(0)

# main 関数
if __name__ == '__main__':
    print('Initializing ...')

    signal.signal(signal.SIGINT, signal_handler)
    print("Press 'Ctrl+C' to stop recording and recognition...")

    # 認識サービスをコールします。モデル、フォーマット、
    # サンプリングレートなどの認識パラメーターをカスタマイズできます
    with client.audio.asr.recognize(
            model='paraformer-realtime-v2',
            format=format_pcm,
            # 'pcm'、'wav'、'opus'、'speex'、'aac'、'amr'。サポートされているフォーマットはドキュメントで確認できます。
            sample_rate=sample_rate,
            # 8000 または 16000 がサポートされています。
            parameters={'semantic_punctuation_enabled': False},
    ) as recognition:
        # マイクを開きます
        mic = pyaudio.PyAudio()
        stream = mic.open(format=pyaudio.paInt16,
                          channels=1,
                          rate=16000,
                          input=True)
        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events, recognition)
            try:
                # 「Ctrl+C」が押されるまでマイクから音声を送信します
                while stream:
                    data = stream.read(3200, exception_on_overflow=False)
                    recognition.send_audio_frame(data)
                recognition.stop()
                receiver.result()
            finally:
                # close はプールのコンテキスト内で実行する必要があります(レシーバーのブロックを解除するため)
                recognition.close()
        stream.stop_stream()
        stream.close()
        mic.terminate()
        stream = None
        mic = None

同時コール

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

リクエストパラメーター

リクエストパラメーターは、コアリソース(client.audio.asr)の recognize/recognize_file メソッドで設定します:model、format、sample_rate、vocabulary_id、disfluency_removal_enabled は具名パラメーターで、その他のパラメーター(language_hints、semantic_punctuation_enabled など)は parameters ディクショナリで渡します。

パラメーター

タイプ

デフォルト

必須

説明

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)セグメンテーションのサイレンス持続時間しきい値(ms 単位)を設定します。

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

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

このパラメーターは、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(デフォルト): サイレント音声を継続的に送信しても、一定時間後に接続がタイムアウトして閉じられます。

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

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

このフィールドは SDK 1.23.1 で導入され、2.0.1 以降のバージョンに含まれています。

inverse_text_normalization_enabled

bool

True

いいえ

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

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

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

主要なインターフェイス

コアリソース(client.audio.asr)

リアルタイム音声認識能力は client.audio.asr リソースにマウントされています:recognize は双方向ストリーミング認識セッション(Recognition)を作成し、recognize_file はローカルファイルを一度に認識します。
メンバーメソッドメソッドシグネチャ説明
recognize
def recognize(self,
              *,
              model: str,
              format: str = "pcm",
              sample_rate: int = 16000,
              vocabulary_id: str = None,
              disfluency_removal_enabled: bool = None,
              diarization_enabled: bool = None,
              parameters: Dict = None,
              input: Dict = None,
              phrase_id: str = None,
              ...) -> Recognition
双方向ストリーミング認識セッションを作成します。with コンテキストに入ると start が自動的に呼び出され、接続の確立とタスクの送信が行われます。音声の送信とイベントの消費は並行して行う必要があります(send_audio_frame、events()/results()、stop と組み合わせて使用します)。
recognize_file
def recognize_file(self,
                   path: str,
                   *,
                   model: str,
                   format: str = "pcm",
                   sample_rate: int = 16000,
                   ...) -> Iterator[Dict]
ローカルファイルをベースとした非ストリーミング呼び出しです:SDK が自動的に音声を分割送信し、タスクの終了までドライブして、サーバーイベントを 1 つずつ産出します。このメソッドは、認識対象のファイルに読み取り権限があることを要求します。
start
def start(self)
音声認識を開始します:接続を確立し、タスクを送信して task-started を待機します。with コンテキストに入ると自動的に呼び出され、起動に成功した後に音声を送信できます。
send_audio_frame
def send_audio_frame(self, buffer: bytes)
音声をプッシュします。毎回プッシュされる音声ストリームは、大きすぎたり小さすぎたりしないようにしてください。各音声パケットの長さは約 100 ms、サイズは 1 KB~16 KB の間にすることを推奨します。認識結果はイベント反復(events()/results())で取得します。
stop
def stop(self)
音声認識を停止します:サーバーに入力の終了のみを通知します。受信スレッドは events() を task-finished イベントまで消費し続ける必要があります。
events / results
def events(self) -> Iterator[Dict]
def results(self) -> Iterator[RecognitionResult]
サーバーイベントを反復処理します:events() は原始イベント dict を産出します(認識テキストは payload.output.sentence にあります)。results() は認識結果フレームのみを産出し、認識結果(RecognitionResult)の型付きオブジェクトを返します(ハートビートフレームはフィルタリング済み)。
close
def close(self)
認識セッションを閉じます。with コンテキストから抜けるときに自動的に呼び出されます。
request_id / first_package_delay / last_package_delay
rec.request_id
rec.first_package_delay
rec.last_package_delay
request_id、最初のパケットのレイテンシー(最初の音声パケットの送信から最初の認識結果パケットの受信までのレイテンシー)、最後のパケットのレイテンシー(stop 指令の送信から最後の認識結果パケットの受信までの所要時間)を取得します。タスク完了後に使用します。セッションを閉じた後も読み取り可能です。

イベント反復(events()/results())

双方向ストリーミング呼び出しでは、サーバーはイベントの方式で主要なプロセス情報とデータをクライアントに返します。受信スレッドでセッションの events()(原始イベント dict)または results()(型付き認識結果フレーム)を反復処理し、サーバーから返された情報やデータを処理する必要があります。
# 原始イベントを反復処理します:認識テキストは payload.output.sentence にあります
def receive_events(rec):
    for event in rec.events():
        payload = event.get('payload') or {}
        sentence = (payload.get('output') or {}).get('sentence') or {}
        if sentence.get('text') and not sentence.get('heartbeat'):
            print('Recognition text: ', sentence['text'])


# または認識結果フレームのみを反復処理します(RecognitionResult を返し、ハートビートフレームはフィルタリング済み)
def receive_results(rec):
    for result in rec.results():
        sentence = result.get_sentence()
        if sentence and 'text' in sentence:
            print('Recognition text: ', sentence['text'])
イベント/反復メソッド産出内容戻り値説明
event["header"]["event"] == "task-started"
task-started イベントなしstart() 内部で読み取られ、起動の戻り時に last_response に保存されます。events() から再度産出されることはありません。
def events(self) -> Iterator[Dict]
event: サーバーイベント dictイテレーターサーバーからの返信があるときにイベントを産出します。認識結果は payload.output.sentence にあり、ハートビートや空テキストのイベントである場合があります。アプリケーションは必要に応じて無視できます。1 つの受信スレッドで消費し続けてください。複数の読み取り者を並行して作成しないでください。
def results(self) -> Iterator[RecognitionResult]
result: 認識結果(RecognitionResult)イテレーター認識結果フレームのみを産出します(ハートビートフレームはフィルタリング済み)。すべての認識結果が返された後に反復処理が終了します。
try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)
DashScopeError 例外なし異常発生時に送信/受信スレッドでスローされます。try/except で捕捉できます。
event["header"]["event"] == "task-finished"
task-finished イベントなしサーバーがすべての認識を完了した後に events() から産出され、その後反復処理が終了します。stop() を送信した後もこのイベントを読み取る必要があります。

応答結果

認識結果(RecognitionResult)

RecognitionResult は、セッションの results() の反復処理で産出される 1 回の認識結果フレームを表します(双方向ストリーミング呼び出しと非ストリーミング呼び出しのどちらでも使用できます。events() が産出するのは原始イベント dict であるため、この型付きビューが必要な場合は results() を使用してください)。
メンバーメソッドメソッドシグネチャ説明
get_sentence
def get_sentence(self) -> Union[Dict[str, Any], List[Any]]
現在認識されている文とタイムスタンプ情報を取得します。このメソッドは、Dict[str, Any] 型(単文情報)を返します。詳細については、「単文情報 (Sentence)」をご参照ください。
request_id
result.request_id
現在のイベントに対応するリクエストの request_id。
is_sentence_end
def is_sentence_end(self) -> bool
現在の文が終了したかどうかを判定します(文に end_time がある場合に True)。

文 (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 で制御)。セマンティック句読点はデフォルトで無効になっています。

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

emo_confidence

浮動小数点数

現在の文で認識された感情の信頼度。値の範囲は 0.0 から 1.0 です。値が大きいほど、信頼度が高いことを示します。

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

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

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

  • 感情認識結果は、RecognitionResult の is_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 が wav に設定されている(不正確なパラメーター設定)。
    • 音声のサンプルレートが 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. paraformer-realtime-v2 モデルを使用する場合、language_hints で設定された言語が音声の実際の言語と一致しているか確認してください。 例: 音声は実際に中国語ですが、language_hints が en(英語)に設定されている。
  2. 上記のすべてのチェックに合格すれば、特定の単語に対する認識精度を向上させるためにカスタムホットワードを使用できます。

Q: 音声フォーマットパラメーターの設定が誤っているために認識結果が得られない場合、どうすればよいですか?

format は必須パラメーターで、音声の実際のフォーマットに合わせて設定する必要があります。たとえば、実際のフォーマットが MP3 で、拡張子が .wav の音声ファイルには、format='mp3' を設定します。
  1. 音声の実際のフォーマットを確認する: ffprobe を使用して、音声のコンテナ、コーデック、サンプルレート、チャンネル情報を確認します。
    ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 your_audio_file
    
  2. リクエストパラメーターを設定する: format を音声の実際のフォーマットに設定します。sample_rate を実際のサンプルレートに設定し、使用するモデルの要件を満たしていることを確認します。
  3. 必要に応じて音声フォーマットを変換する: WAV 音声が必要な場合は、次のコマンドを使用して、PCM エンコード、16 kHz、モノラルの WAV ファイルを生成します。
    ffmpeg -i input_file -c:a pcm_s16le -ar 16000 -ac 1 output.wav
    
    変換後は、format='wav' と sample_rate=16000 を設定します。
format='wav' を使用する場合、音声は PCM エンコードされた WAV ファイルである必要があります。