Skip to main content

Fun-ASR-Realtime Java SDK

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

前提条件

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

クイックスタート

Recognition クラスは、同期呼び出しと双方向ストリーミング呼び出しの両方のインターフェイスを提供します。ニーズに合ったアプローチを選択してください:
  • 同期呼び出し:ローカルファイルを認識し、完全な結果を一度に返します。録音済みの音声を処理するのに最適です。
  • 双方向ストリーミング呼び出し:音声ストリームを直接認識し、リアルタイムで結果を返します。音声ストリームは、マイクなどの外部デバイスから取得することも、ローカルファイルから読み取ることもできます。即時のフィードバックが必要なシナリオに最適です。
  • 同期呼び出し
  • 双方向ストリーミング呼び出し:コールバックベース
  • 双方向ストリーミング呼び出し:Flowable ベース
ローカルファイルを渡すことで、単一のリアルタイム音声認識タスクを送信し、認識結果を同期的に取得します。この呼び出しは、結果が返されるまでブロックされます。Recognition クラスをインスタンス化し、call メソッドを呼び出してリクエストパラメーターと認識するファイルをバインドします。このメソッドは認識を実行し、最終結果を返します。
import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;
import com.alibaba.dashscope.utils.Constants;

import java.io.File;

public class Main {
    public static void main(String[] args) {
        // 以下はシンガポールリージョンの設定です。呼び出す際は、"{WorkspaceId}" を実際のワークスペース ID に置き換えてください。設定はリージョンによって異なります。
        Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference";
        // Recognition インスタンスを作成
        Recognition recognizer = new Recognition();
        // RecognitionParam を作成
        RecognitionParam param =
                RecognitionParam.builder()
                        .model("fun-asr-realtime")
                        // API キーはシンガポールリージョンと北京リージョンで異なります。API キーの取得:https://www.alibabacloud.com/help/ja/model-studio/get-api-key
                        // 環境変数を設定していない場合は、次の行を Model Studio の API キーに置き換えてください:.apiKey("sk-xxx")
                        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                        .format("wav")
                        .sampleRate(16000)
                        //.parameter("language_hints", new String[]{"zh"})
                        .build();

        try {
            System.out.println("Recognition result: " + recognizer.call(param, new File("{YOUR_AUDIO_FILE}")));
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            // タスク完了後、WebSocket 接続を閉じる
            recognizer.getDuplexApi().close(1000, "bye");
        }
        System.out.println(
                "[Metric] requestId: "
                        + recognizer.getLastRequestId()
                        + ", first package delay ms: "
                        + recognizer.getFirstPackageDelay()
                        + ", last package delay ms: "
                        + recognizer.getLastPackageDelay());
        System.exit(0);
    }
}

高い同時実行性呼び出し

DashScope Java SDK は、OkHttp3 のコネクションプーリングを使用して、接続を繰り返し確立するオーバーヘッドを削減します。詳細については、「高同時実行時のベストプラクティス」をご参照ください。

リクエストパラメーター

RecognitionParam のチェーンメソッドを使用して、モデル、サンプルレート、音声フォーマット、その他のパラメーターを設定します。設定したパラメーターオブジェクトを Recognition クラスの call/streamCall メソッドに渡します。
RecognitionParam param = RecognitionParam.builder()
  .model("fun-asr-realtime")
  .format("pcm")
  .sampleRate(16000)
  //.parameter("language_hints", new String[]{"zh"})
  .build();
パラメータータイプ必須説明
modelStringはいモデル名。
sampleRateIntegerはいサンプルレート (Hz)。有効値:8 kHz モデルは 8000 Hz のみをサポートします。その他のモデルは任意のサンプルレートをサポートします。
formatStringはい音声フォーマット。有効値:
  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr
opus/speex:Ogg カプセル化を使用する必要があります。wav:PCM エンコーディングを使用する必要があります。amr:AMR-NB タイプのみがサポートされています。
vocabularyIdStringいいえプリコンパイルされたホットワードリストの ID。この ID は、ホットワードリスト作成 API を呼び出して事前に生成します。認識時に ID を渡して、リスト内のホットワードを使用します。語彙が既知で比較的安定しており、同じ単語リストをリクエスト間で再利用する必要があるシナリオに適しています。使用方法の詳細については、「プリコンパイルされたホットワード」をご参照ください。
max_sentence_silenceIntegerいいえセグメンテーションのための VAD 無音しきい値 (ms)。音声セグメントの後の無音がこのしきい値を超えると、システムは文が終了したと判断します。デフォルト値:1300。有効値:[200, 6000]。max_sentence_silence は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定します:
RecognitionParam param = RecognitionParam.builder()
 .model("fun-asr-realtime")
 .format("pcm")
 .sampleRate(16000)
 .parameter("max_sentence_silence", 800)
 .build();
multi_threshold_mode_enabledbooleanいいえマルチしきい値モードを有効にするかどうか。有効にすると、VAD セグメントが長くなりすぎるのを防ぎます。デフォルト値:false。multi_threshold_mode_enabled は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定します:
RecognitionParam param = RecognitionParam.builder()
 .model("fun-asr-realtime")
 .format("pcm")
 .sampleRate(16000)
 .parameter("multi_threshold_mode_enabled", true)
 .build();
punctuation_prediction_enabledbooleanいいえ認識結果に句読点を自動的に追加するかどうかを設定します:
  • true (デフォルト):はい。この値は変更できません。
punctuation_prediction_enabled は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定します:
RecognitionParam param = RecognitionParam.builder()
 .model("fun-asr-realtime")
 .format("pcm")
 .sampleRate(16000)
 .parameter("punctuation_prediction_enabled", false)
 .build();
heartbeatbooleanいいえハートビートパケットを有効にするかどうか。デフォルト値:false。
  • true:無音音声を継続的に送信しても、サーバーへの接続を維持します。
  • false (デフォルト):無音音声を継続的に送信しても、一定時間後に接続がタイムアウトして閉じられます。
無音音声とは、音声ファイルまたはデータストリームに音響信号が含まれていないコンテンツを指します。Audacity や Adobe Audition などの音声編集ソフトウェア、または FFmpeg などのコマンドラインツールを使用して、いくつかの方法で無音音声を生成できます。
このフィールドを使用するには、SDK バージョンが 2.19.1 以降である必要があります。
heartbeat は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定します:
RecognitionParam param = RecognitionParam.builder()
 .model("fun-asr-realtime")
 .format("pcm")
 .sampleRate(16000)
 .parameter("heartbeat", true)
 .build();
language_hintsString[]いいえ認識する音声の言語。デフォルト値はありません。設定しない場合、モデルは自動的に言語を検出します。1 つの値を設定できます。複数設定した場合は、最初の値のみが有効です。
  • fun-asr-realtime:
    • 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-flash-8k-realtime, fun-asr-flash-8k-realtime-2026-01-28:
    • zh: 中国語
language_hints は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定します:
RecognitionParam param = RecognitionParam.builder()
 .model("fun-asr-realtime")
 .format("pcm")
 .sampleRate(16000)
 .parameter("language_hints", new String[]{"zh"})
 .build();
speech_noise_thresholdfloatいいえ音声とノイズを区別するためのしきい値で、音声アクティビティ検出 (VAD) の感度を調整するために使用されます。有効値:[-1.0, 1.0]。値の説明:
  • 値が -1 に近いほど:ノイズしきい値が低下するため、ノイズが音声として認識されやすくなり、より多くのノイズが文字起こしされる可能性があります。
  • 値が +1 に近いほど:ノイズしきい値が上昇するため、音声がノイズと誤判定されやすくなり、一部の音声がフィルタリングされる可能性があります。
これは詳細設定パラメーターです。調整すると認識結果に大きな影響を与える可能性があります。推奨事項:
  • 調整する前に、結果を十分にテストおよび検証してください。
  • 実際の音声環境に基づいて、小さな増分で調整してください (0.1 のステップを推奨)。
speech_noise_threshold は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定します:
RecognitionParam param = RecognitionParam.builder()
 .model("fun-asr-realtime")
 .format("pcm")
 .sampleRate(16000)
 .parameter("speech_noise_threshold", -0.5)
 .build();
special_word_filterStringいいえ音声認識中に処理する禁止用語を指定し、異なる禁止用語に対して異なる処理方法を設定することをサポートします。詳細については、「禁止用語フィルター」をご参照ください。special_word_filter は、RecognitionParam インスタンスの parameter メソッドまたは parameters メソッドを通じて設定します:
// 1. 最も外側のオブジェクトを構築
JSONObject root = new JSONObject();
root.put("system_reserved_filter", true);

// 2. 「結果から完全に削除」設定を構築
JSONObject root1 = new JSONObject();
JSONArray array1 = new JSONArray();
array1.put("start");
array1.put("proceed");
root1.put("word_list", array1);

// 3. 「同じ長さの * に置き換え」設定を構築
JSONObject root2 = new JSONObject();
JSONArray array2 = new JSONArray();
array2.put("test");
root2.put("word_list", array2);

// 4. 組み立て
root.put("filter_with_empty", root1);
root.put("filter_with_signed", root2);

RecognitionParam param = RecognitionParam.builder()
 .model("fun-asr-realtime")
 .format("pcm")
 .sampleRate(16000)
 .parameter("special_word_filter", root.toString())
 .build();
inputMap<String, Object>いいえ会話コンテキストを渡す入力オブジェクト。コンテキストは認識を助け、固有名詞の認識精度を向上させます。使用方法については、「クイックスタート」をご参照ください。
fun-asr-realtime モデルのみがコンテキストパラメーターをサポートしています。
Map には、List<Map<String, Object>> 型のメッセージ配列である context キーが含まれている必要があります。各メッセージには次のフィールドが含まれます:
  • role (String, 必須):メッセージのロール。user は、以前のラウンドのユーザーの発話の認識結果またはドメイン固有の単語リストを示します。assistant は、以前のラウンドの大規模言語モデルの応答を示します。
  • content (List<Map>, 必須):メッセージのコンテンツリスト。各要素には type (String; role が user の場合は input_text、role が assistant の場合は text に設定) と text (String, テキストコンテンツ) が含まれます。
使用制限:input_text および text タイプのコンテキストメッセージはそれぞれ 5 つに制限されます。制限を超えた場合、最新の 5 つが保持されます。コンテキストの各ラウンドの合計テキスト長は 400 文字を超えることはできず、超過分は末尾から切り捨てられます。
コンテキストを渡す場合、context 内のメッセージは特定の順序に従う必要があります:コンテキストメッセージは会話ラウンドごとに配置し、各ラウンド内で user メッセージ (input_text タイプ) は対応する assistant メッセージ (text タイプ) の前に配置する必要があります。
このフィールドを使用するには、SDK バージョンが 2.22.23 以降である必要があります。
input は、RecognitionParam インスタンスの input メソッドを通じて設定します:
// 1. 入力構造体を構築
      Map<String, Object> userContent = new HashMap<>();
      userContent.put("type", "input_text");
      userContent.put("text", "こんにちは");

      Map<String, Object> assistantContent = new HashMap<>();
      assistantContent.put("type", "text");
      assistantContent.put("text", "こんにちは、私は Qwen です。何かお手伝いできることはありますか?");

      Map<String, Object> userMessage = new HashMap<>();
      userMessage.put("role", "user");
      userMessage.put("content", Arrays.asList(userContent));

      Map<String, Object> assistantMessage = new HashMap<>();
      assistantMessage.put("role", "assistant");
      assistantMessage.put("content", Arrays.asList(assistantContent));

      Map<String, Object> input = new HashMap<>();
      input.put("context", Arrays.asList(userMessage, assistantMessage));

      // 2. input メソッドを通じて渡す
      RecognitionParam param = RecognitionParam.builder()
       .model("fun-asr-realtime")
       .format("pcm")
       .sampleRate(16000)
       .input(input)
       .build();
apiKeyStringいいえご利用の API キー。

主要なインターフェイス

Recognition クラス

import com.alibaba.dashscope.audio.asr.recognition.Recognition; で Recognition をインポートします。その主要なインターフェイスは次のとおりです:
インターフェイス/メソッドパラメーター戻り値説明
public void call(RecognitionParam param, final ResultCallback<RecognitionResult> callback)
  • param:リクエストパラメーター
  • callback:コールバックインターフェイス (ResultCallback)
なしコールバックベースのストリーミングリアルタイム認識。このメソッドは現在のスレッドをブロックしません。
public String call(RecognitionParam param, File file)
  • param:リクエストパラメーター
  • file:認識する音声ファイル。
認識結果。ローカルファイルの非ストリーミング認識。このメソッドは、音声ファイル全体が読み取られるまで現在のスレッドをブロックします。ファイルは読み取り可能でなければなりません。
public Flowable<RecognitionResult> streamCall(RecognitionParam param, Flowable<ByteBuffer> audioFrame)
  • param:リクエストパラメーター
  • audioFrame:Flowable<ByteBuffer> インスタンス。
Flowable<RecognitionResult>Flowable ベースのストリーミングリアルタイム認識。
public void sendAudioFrame(ByteBuffer audioFrame)
  • audioFrame:ByteBuffer 型のバイナリ音声ストリーム。
なし音声を送信します。プッシュされる各音声チャンクを適切なサイズに保ちます。推奨されるチャンクは、約 100 ms の音声を保持し、サイズは 1 KB から 16 KB です。認識結果は、コールバックインターフェイス (ResultCallback) の onEvent メソッドを通じて配信されます。
public void stop()
なしなしリアルタイム認識を停止します。このメソッドは、ResultCallback コールバックの onComplete または onError が呼び出されるまで現在のスレッドをブロックします。
boolean getDuplexApi().close(int code, String reason)
code:WebSocket のクローズコード。reason:クローズの理由。これら 2 つのパラメーターの設定に関するガイダンスについては、「The WebSocket Protocol」をご参照ください。trueタスクが終了した後、例外が発生したかどうかに関わらず、常に WebSocket 接続を閉じて、接続リークを回避してください。接続を再利用して効率を向上させるには、「Paraformer リアルタイム音声認識の高い同時実行性のための最適化」をご参照ください。
public String getLastRequestId()
なしrequestId現在のタスクの requestId を取得します。call または streamingCall で新しいタスクが開始された後に利用可能です。
このメソッドは、SDK バージョン 2.18.0 以降でのみ利用可能です。
public long getFirstPackageDelay()
なし最初のパケットのレイテンシ。最初のパケットのレイテンシ、つまり最初の音声パケットを送信してから最初の認識結果を受信するまでの遅延を取得します。タスク完了後に使用します。
このメソッドは、SDK バージョン 2.18.0 以降でのみ利用可能です。
public long getLastPackageDelay()
なし最後のパケットのレイテンシ。最後のパケットのレイテンシ、つまり stop コマンドを送信してから最終的な認識結果を受信するまでの時間を取得します。タスク完了後に使用します。
このメソッドは、SDK バージョン 2.18.0 以降でのみ利用可能です。

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

双方向ストリーミング呼び出し中、サーバーはコールバックを通じて主要なプロセス情報とデータをクライアントに返します。コールバックメソッドを実装して、サーバーから返された情報やデータを処理します。 抽象クラス ResultCallback を拡張してコールバックメソッドを実装します。このクラスを拡張する際、ジェネリック型を RecognitionResult に設定できます。RecognitionResult は、サーバーから返されたデータ構造をラップします。 Java は接続の再利用をサポートしているため、onClose や onOpen はありません。
ResultCallback<RecognitionResult> callback = new ResultCallback<RecognitionResult>() {
    @Override
    public void onEvent(RecognitionResult result) {
        System.out.println("RequestId: " + result.getRequestId());
        // ここに音声認識結果を処理するロジックを追加します。
    }

    @Override
    public void onComplete() {
        System.out.println("Task complete");
    }

    @Override
    public void onError(Exception e) {
        System.out.println("Task failed: " + e.getMessage());
    }
};
インターフェイス/メソッドパラメーター戻り値説明
public void onEvent(RecognitionResult result)
result:リアルタイム認識結果 (RecognitionResult)なしサーバーが応答を送信したときに呼び出されます。
public void onComplete()
なしなしタスク完了後に呼び出されます。
public void onError(Exception e)
e:例外情報。なし例外が発生したときに呼び出されます。

応答

リアルタイム認識結果 (RecognitionResult)

RecognitionResult は、単一のリアルタイム認識の結果を表します。
インターフェイス/メソッドパラメーター戻り値説明
public String getRequestId()
なしrequestIdrequestId を取得します。
public boolean isSentenceEnd()
なし完全な文が形成されたかどうか、つまり文の境界が検出されたかどうか。与えられた文が終了したかどうかを判断します。
public Sentence getSentence()
なし文情報 (Sentence)タイムスタンプやテキストを含む文情報を取得します。

文情報 (Sentence)

インターフェイス/メソッドパラメーター戻り値説明
public Long getBeginTime()
なし文の開始時刻 (ms)。文の開始時刻を返します。
public Long getEndTime()
なし文の終了時刻 (ms)。文の終了時刻を返します。
public String getText()
なし認識されたテキスト。認識されたテキストを返します。
public List<Word> getWords()
なし単語レベルのタイムスタンプ情報 (Word) オブジェクトのリスト。単語レベルのタイムスタンプ情報を返します。

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

インターフェイス/メソッドパラメーター戻り値説明
public long getBeginTime()
なし単語の開始時刻 (ms)。単語の開始時刻を返します。
public long getEndTime()
なし単語の終了時刻 (ms)。単語の終了時刻を返します。
public String getText()
なし単語。認識された単語を返します。
public String getPunctuation()
なし句読点。句読点を返します。

エラーコード

エラーが発生した場合は、「エラーコード」を参照してトラブルシューティングを行ってください。 問題が解決しない場合は、開発者コミュニティに参加して問題を報告し、詳細な調査のためにリクエスト 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 encoder_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 クラスの sendAudioFrame メソッドを通じてバイナリストリームをサーバーに送信して認識します。
    • 「双方向ストリーミング呼び出し:Flowable ベース」を参照し、Recognition クラスの streamCall メソッドを通じてバイナリストリームをサーバーに送信して認識します。

トラブルシューティング

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. language_hints で設定された言語が、音声の実際の言語と一致していることを確認してください。 たとえば、音声は実際には中国語ですが、language_hints は en (英語) に設定されています。
  2. 上記のチェックで問題が見つからない場合は、カスタムホットワードを設定して特定の用語の認識を向上させてください。