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

Paraformer 实时语音识别 Android SDK

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

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

快速开始

前提条件

  1. 获取API Key — 请获取API Key并配置到环境变量，而非硬编码在代码中，以防止因代码泄露导致的安全风险。
    当您需要为第三方应用或用户提供临时访问权限，或者希望严格控制敏感数据访问等高风险操作时，建议使用临时鉴权Token。与长期有效的API Key相比，临时鉴权Token具备时效性短（60秒）、安全性高的特点，适用于临时调用场景，能有效降低API Key泄露的风险。
  2. 下载SDK — 下载Android SDK压缩包，解压后将AAR文件置于工程的app/libs目录下，打开DashParaformerSpeechTranscriberActivity.java文件参考示例。

调用步骤

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是唯一标识终端用户的字符串。
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": "paraformer-realtime-v2",
        "sr_format": "pcm",
        "sample_rate": "16000"
    }
}
参数类型是否必须说明
service_typeint是固定为 4。
nls_configobject是语音识别核心配置。
nls_config.modelstring是识别模型，参见模型列表。
nls_config.sr_formatstring是音频格式，支持 pcm、wav、opus。
nls_config.sample_rateint是采样率（Hz）。paraformer-realtime-v2支持任意采样率；paraformer-realtime-v1仅支持16000；paraformer-realtime-8k-v2和paraformer-realtime-8k-v1仅支持8000。
nls_config.disfluency_removal_enabledboolean否是否过滤语气词（如"嗯"、"啊"等），默认 false。
nls_config.language_hintsarray[string]否语言代码列表，指定待识别语种，支持 zh/en/ja/yue/ko/de/fr/ru，仅多语言模型生效。
nls_config.semantic_punctuation_enabledboolean否是否开启语义断句模式，默认 false（使用VAD断句）。仅 paraformer-realtime-v2 及以上版本支持。
nls_config.max_sentence_silenceint否VAD断句静音阈值（ms），默认 800，范围 200–6000。semantic_punctuation_enabled=false且 v2+ 时生效。
nls_config.multi_threshold_mode_enabledboolean否是否启用多阈值模式，防止过长句子被切断，默认 false。semantic_punctuation_enabled=false且 v2+ 时生效。
nls_config.punctuation_prediction_enabledboolean否是否自动添加标点，默认 true。仅 paraformer-realtime-v2 及以上版本支持。
nls_config.heartbeatboolean否是否开启长连接保持，默认 false。true时持续发送静音可保持连接；false时60秒超时断开。仅 paraformer-realtime-v2 及以上版本支持。
nls_config.inverse_text_normalization_enabledboolean否是否开启逆文本正则化（ITN），将中文数字转为阿拉伯数字，默认 true。仅 paraformer-realtime-v2 及以上版本支持。
nls_config.vocabulary_idstring否热词词表ID，参见定制热词。仅 paraformer-realtime-v2 及以上版本支持。
nls_config.resourcesarray[object]否v1版本热词配置，每个元素包含resource_id和resource_type（固定为"asr_phrase"）。参见Paraformer语音识别热词定制与管理。
sr_format为opus时，须向SDK提供原始PCM数据，由SDK负责编码为Opus格式；sr_format为wav或pcm时，须提供PCM编码数据。
v1版本热词配置示例： 
{
    "nls_config": {
        "resources": [
            {
                "resource_id": "xxxx",
                "resource_type": "asr_phrase"
            }
        ]
    }
}

关键接口

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后触发）。

错误码

如遇报错问题，请参见错误信息进行排查。