跳转到主要内容
千问云 home page
开放平台文档
实时

Fun-ASR实时语音识别Android SDK

本文档提供了Fun-ASR实时语音识别Android SDK的详细使用指南，帮助您将语音转换为文本。

用户指南： 关于模型介绍和选型建议，请参见实时语音识别。

快速开始

前提条件

  1. 获取API Key — 请获取API Key并配置到环境变量，而非硬编码在代码中，以防止因代码泄露导致的安全风险。
    当您需要为第三方应用或用户提供临时访问权限，或者希望严格控制敏感数据访问等高风险操作时，建议使用临时鉴权Token。与长期有效的API Key相比，临时鉴权Token具备时效性短（60秒）、安全性高的特点，适用于临时调用场景，能有效降低API Key泄露的风险。
  2. 下载SDK并运行示例代码：
    • 下载最新SDK整合包。
    • 解压ZIP包。在app/libs目录中获取AAR格式SDK，并添加到项目依赖。需要Android CPP接入时，使用ZIP包内的android_libs与android_include获取动态库和头文件。
    • 用Android Studio打开工程。示例代码位于DashFunAsrSpeechTranscriberActivity.java，替换API Key后体验功能。

调用步骤

1

初始化SDK

调用initialize方法完成SDK初始化。SDK采用单例模式，在release之前不得重复初始化。该方法会阻塞当前线程，须在非UI线程中调用。
2

设置参数

通过initialize的parameters参数设置连接与控制参数，通过setParams的params参数设置语音识别效果参数。
3

调用startDialog启动识别

调用startDialog方法启动语音识别。
4

在onNuiAudioStateChanged中开启录音

实现onNuiAudioStateChanged回调，在收到STATE_OPEN状态时开启麦克风录音。
5

在onNuiNeedAudioData中持续提供音频数据

实现onNuiNeedAudioData回调，持续向SDK填充从麦克风采集的PCM音频数据。
6

在onNuiEventCallback中监听事件和获取结果

实现onNuiEventCallback回调，监听识别事件并获取实时识别结果。
7

停止识别

调用stopDialog停止识别。服务端返回最终识别结果后，将触发EVENT_TRANSCRIBER_COMPLETE事件。
8

释放资源

调用release释放所有内部资源。释放后如需再次使用，须重新调用initialize进行初始化。

请求参数

连接与控制参数

通过initialize()方法的parameters参数传入，格式为JSON字符串。 
{
    "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}
参数类型是否必须说明
urlString是服务地址，固定为 wss://dashscope.aliyuncs.com/api-ws/v1/inference。
apikeyString是API Key。建议使用临时鉴权Token。
service_modeString是运行模式，实时语音识别固定为 "1"。
device_idString是用于标识终端用户的唯一字符串，可设为应用内用户ID或客户端生成的设备唯一标识符。此ID主要用于日志追踪和问题排查。
debug_pathString否日志文件存储路径，save_log=true时生效，本地最多保留两个日志文件。
save_wavString否是否保存调试音频，默认 "false"。需save_log=true且debug_path已设置时生效。
max_log_file_sizeint否日志文件最大字节数，默认 104857600（100MiB），save_log=true时生效。
log_track_levelint否onNuiLogTrackCallback过滤级别，默认 2，取值 0--5（VERBOSE/DEBUG/INFO/WARNING/ERROR/NONE），与initialize的level参数共同决定回调日志。

语音识别效果参数

通过setParams()方法的params参数传入，格式为JSON字符串。 
{
    "service_type": 4,
    "nls_config": {
        "model": "fun-asr-realtime",
        "sr_format": "pcm",
        "sample_rate": "16000",
        "parameters": {
            "speech_noise_threshold": 0.0
        }
    }
}
参数类型是否必须说明
service_typeint是固定为 4。
nls_configobject是语音识别核心配置。
nls_config.modelstring是识别模型，参见模型列表。
nls_config.sr_formatstring是音频格式，支持 pcm、wav、opus。
nls_config.sample_rateint是待识别音频采样率（Hz），仅支持16000。
nls_config.semantic_punctuation_enabledboolean否是否开启语义断句模式，默认 false（使用VAD断句）。语义断句准确性更高，适合会议转写场景；VAD断句延迟较低，适合实时交互场景。
nls_config.max_sentence_silenceint否VAD断句静音阈值（ms），默认 800，范围 200--6000。当一段语音后的静音时长超过该阈值时，系统判定该句结束。semantic_punctuation_enabled=false时生效。
nls_config.multi_threshold_mode_enabledboolean否是否启用多阈值模式，防止过长句子被切断，默认 false。semantic_punctuation_enabled=false时生效。
nls_config.heartbeatboolean否是否开启长连接保持，默认 false。true时持续发送静音可保持连接；false时60秒超时断开。
nls_config.vocabulary_idstring否热词词表ID，参见定制热词。
nls_config.language_hintsarray[string]否识别语言代码。不设置时自动检测。支持的语言代码：zh（中文）、en（英文）、ja（日文）。
nls_config.parametersobject否其他参数配置，内容为JSON Object格式。
nls_config.parameters.speech_noise_thresholdfloat否语音噪声检测阈值，用于调节VAD灵敏度。取值范围：[-1.0, 1.0]。接近 -1：更多噪声可能被识别为语音。接近 +1：部分语音可能被过滤为噪声。这是高级参数，调整会显著影响识别质量，建议以 0.1 为步长逐步调整并充分测试。
sr_format为opus时，须向SDK提供原始PCM数据，由SDK负责编码为Opus格式；sr_format为wav或pcm时，须提供PCM编码数据。

关键接口

NativeNui

initialize

初始化SDK。SDK采用单例模式，release之前禁止重复初始化。该方法会阻塞当前线程，须在非UI线程中调用。 
public synchronized int initialize(final INativeNuiCallback callback,
                                   String parameters,
                                   final Constants.LogLevel level,
                                   final boolean save_log)
参数类型说明
callbackINativeNuiCallback回调接口实例，参见 INativeNuiCallback。
parametersString连接与控制参数的JSON字符串，参见连接与控制参数。
levelConstants.LogLevel日志级别。
save_logboolean是否保存日志，true时须在parameters中设置debug_path。
返回值： 错误码，参见错误信息。

setParams

以JSON格式设置语音识别效果参数，须在startDialog之前调用。 
public synchronized int setParams(String params)
参数类型说明
paramsString语音识别效果参数的JSON字符串，参见语音识别效果参数。
返回值： 错误码，参见错误信息。

startDialog

开始语音识别。 
public synchronized int startDialog(VadMode vad_mode, String dialog_params)
参数类型说明
vad_modeVadMode固定传入 VadMode.TYPE_P2T。
dialog_paramsString用于临时鉴权Token过期时更新apikey的JSON字符串。
dialog_params格式： 
{"apikey": "st-****"}
返回值： 错误码，参见错误信息。

stopDialog

结束语音识别。服务端返回最终识别结果后任务结束。 
public synchronized int stopDialog();
返回值： 错误码，参见错误信息。

cancelDialog

立即结束语音识别，不等待服务端返回最终识别结果。 
public synchronized int cancelDialog();
返回值： 错误码，参见错误信息。

release

释放所有内部资源。释放后如需再次使用，须重新调用initialize进行初始化。 
public synchronized int release();
返回值： 错误码，参见错误信息。

GetVersion

获取当前SDK版本信息。 
public synchronized String GetVersion();
返回值： SDK版本信息字符串。

INativeNuiCallback

实现此接口以监听SDK回调事件。

onNuiEventCallback

监听事件和语音识别结果。 
void onNuiEventCallback(NuiEvent event, final int resultCode, final int arg2, KwsResult kwsResult, AsrResult asrResult);
参数类型说明
eventNuiEvent事件类型，参见 NuiEvent。
resultCodeint错误码，仅EVENT_ASR_ERROR事件时有效，参见错误信息。
asrResultAsrResult语音识别结果。
kwsResultKwsResult语音唤醒结果，实时语音识别场景无需关注。
arg2int保留参数。

onNuiAudioStateChanged

监听音频状态变化。SDK通过此回调通知应用何时开启或停止录音。 
void onNuiAudioStateChanged(AudioState state);
AudioState说明
STATE_OPEN交互启动，应打开录音。
STATE_PAUSE交互停止，应停止录音。
STATE_CLOSESDK实例释放，应彻底关闭录音。

onNuiNeedAudioData

持续提供待识别的音频数据。开始识别后，SDK会连续触发此回调。 
int onNuiNeedAudioData(byte[] buffer, int len);
参数类型说明
bufferbyte[]需填充的音频数据缓冲区。
lenint需填充的字节数。
返回值： 实际填充的字节数。

onNuiLogTrackCallback

监听SDK内部追踪日志。 
default void onNuiLogTrackCallback(Constants.LogLevel level, String log)

NuiEvent

语音识别事件类型。
事件说明
EVENT_TRANSCRIBER_STARTED任务启动成功。
EVENT_VAD_START任务启动后即触发，不代表检测到人声起点。
EVENT_VAD_END检测到人声终点。
EVENT_ASR_PARTIAL_RESULT返回中间识别结果（非最终结果）。
EVENT_ASR_ERROR识别过程出错。
EVENT_MIC_ERROR连续2秒未收到音频数据。
EVENT_SENTENCE_END检测到一句话结束，返回完整识别结果。
EVENT_TRANSCRIBER_COMPLETE语音识别结束（调用stopDialog后触发）。

错误码

如遇报错问题，请参见错误信息进行排查。
Fun-ASR实时语音识别Android SDK - 千问云