本文档提供了Qwen-Audio-ASR-Filetrans非实时语音识别Android SDK的详细使用指南,帮助您将语音转换为文本。
关于支持的音频格式、文件大小限制、时长限制等输入要求,请参见音频规格。
通过在
参数说明
通过
参数说明
初始化语音识别SDK实例。SDK为单例模式,在调用
参数说明
此接口用于独立设置或更新
参数说明
开始识别。
方法签名
参数说明
此接口用于主动查询一个异步任务的当前状态和结果。调用成功后,结果将通过
方法签名
参数说明
立即取消当前任务。
方法签名
参数说明
释放SDK所有内部资源。此方法调用后,SDK实例将变为不可用状态,如需再次使用,必须重新调用
获得当前SDK版本信息。
方法签名
返回值说明
当前SDK版本信息。
方法签名
参数说明
此回调用于接收 SDK 内部的详细日志,方便进行问题定位和调试。
快速开始
- 获取API Key:获取API Key,为安全起见,推荐将API Key配置到环境变量。
-
下载SDK并运行示例代码:
- 下载最新SDK整合包。
- 解压 ZIP 包。在
app/libs目录中获取 AAR 格式 SDK,并添加到项目依赖。
需要 Android CPP 接入时,使用 ZIP 包内的android_libs与android_include获取动态库和头文件。 - 用 Android Studio 打开工程。示例代码位于
DashFunAsrFileTranscriberActivity.java,替换 API Key 后体验功能。
调用步骤
- 同步模式
- 异步模式
- 初始化 SDK
- 按业务需求配置相关参数
- 当
async_request设为false时,调用startFileTranscriber发送非实时语音识别请求,并等待结果返回。 - 在
onFileTransEventCallback接口中监听EVENT_FILE_TRANS_RESULT事件,获取最终识别结果 - 调用
release释放 SDK 资源
请求参数
连接与控制参数
通过在initialize接口的parameters参数中传入一个JSON字符串来配置。
参数示例
以下为 JSON 字符串示例,参数未完整列出。请按实际需求在编码时补充:
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
url | String | 是 | 服务地址:
{WorkspaceId} 替换为真实的 Workspace ID。 |
apikey | String | 是 | API Key。 |
service_mode | String | 是 | 运行模式。非实时语音识别固定为 "1"。 |
device_id | String | 是 | 用于标识终端用户的唯一字符串,可设为应用内用户ID或客户端生成的设备唯一标识符。此ID主要用于日志追踪和问题排查。 |
debug_path | String | 否 | 日志文件的存储路径。此参数仅在调用initialize接口时将save_log设为true时生效。此时必须设置日志文件路径,否则将报错。本地最多保留两个日志文件。 |
max_log_file_size | int | 否 | 设定日志文件的最大字节数。此参数仅在调用initialize接口时将save_log设为true时生效。默认值:104857600(100 * 1024 * 1024 字节, 即 100MiB)。 |
log_track_level | int | 否 | 控制通过日志回调(onFileTransLogTrackCallback)对外发送的日志内容的过滤级别。默认值:2。取值范围:
log_track_level与level(通过initialize接口设置)共同决定最终回调的日志。一条日志的级别数值必须同时大于或等于log_track_level和level的值,才会被回调。例如,log_track_level设为2 (INFO),level设为3 (WARNING),则只有WARNING及以上级别(数值>=3)的日志才会被回调。 |
语音识别效果参数
通过startFileTranscriber接口配置所有语音识别效果参数。
参数示例
以下为 JSON 字符串示例,参数未完整列出。请按实际需求在编码时补充:
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
file_urls | array[string] | 是 | 音视频文件转写的URL列表,支持HTTP / HTTPS协议,单次请求仅支持1个URL。关于支持的音频格式、文件大小限制、时长限制等输入要求,请参见音频规格。若录音文件存储在阿里云OSS,使用RESTful API方式支持使用以oss://为前缀的临时 URL,使用SDK方式不支持使用以 oss://为前缀的临时 URL。 |
async_request | boolean | 否 | 语音识别是否为异步请求。默认值:false。取值范围:
|
apikey | string | 否 | 如果连接与控制参数的apikey使用的是临时API Key,可在此处进行更新,以免超时失效。 |
nls_config | object | 是 | 语音识别核心配置对象,包含模型选择、识别效果控制等关键参数。 |
nls_config.model | string | 是 | 模型名称。 |
nls_config.special_word_filter | object | 否 | 指定在语音识别过程中需要处理的敏感词,并支持对不同敏感词设置不同的处理方式。详情请参见敏感词过滤。 |
nls_config.channel_id | array[integer] | 否 | 指定在多音轨音频文件中需要识别的音轨索引,索引从 0 开始。例如,[0] 表示识别第一个音轨,[0, 1] 表示同时识别第一和第二个音轨。如果省略此参数,则默认处理第一个音轨。默认值:[0]。 |
nls_config.diarization_enabled | boolean | 否 | 是否启用说话人分离,默认关闭。仅适用于单声道音频,多声道音频不支持说话人分离。启用该功能后,识别结果中将显示speaker_id字段,用于区分不同说话人。如果启用说话人分离功能,建议音频时长不超过2小时,否则可能导致识别失败或超时。 speaker_id的示例,请参见识别结果说明。 |
nls_config.speaker_count | integer | 否 | 说话人数量参考值。取值范围为2至100的整数(包含2和100)。默认自动判断说话人数量,如果配置此项,只能辅助算法尽量输出指定人数,无法保证一定会输出此人数。无默认值。 |
nls_config.vocabulary_id | string | 否 | 预编译热词列表 ID。需预先调用创建热词列表接口生成,识别时传入该 ID 即可使用列表中的热词。适用于词汇已知且相对稳定、需要跨请求复用同一词表的场景。使用方法请参见预编译热词。 |
nls_config.input_context | array | 否 | 消息列表,包含用于提升识别效果的可选对话上下文。 |
nls_config.instant_vocabulary | object | 否 | 即时热词,以键值对形式传入:键为热词文本(string),值为热词权重(integer),无需预先创建热词列表。适用于临时性、会话级别的热词优化。权重取值范围为 1 至 5 或 50。取 1 至 5 时,值越大,模型越倾向于输出该词;取 50 时为超级热词,召回率大幅提升,但超级热词最多不超过 50 个。与预编译热词同时配置时,系统会合并两类热词;合并后超过 2000 个时,随机选择 2000 个使用。使用方法请参见即时热词。 |
nls_config.language_hints | array[string] | 否 | 设置待识别语言代码。如果无法提前确定语种,可不设置,模型会自动识别语种。最多支持设置 4 个值,超出时仅前 4 个生效。
点击查看支持的语言代码
|
关键接口
NativeNui
initialize
初始化语音识别SDK实例。SDK为单例模式,在调用release前禁止重复初始化。
此接口会引起阻塞,应在非UI线程调用。
方法签名
| 参数 | 类型 | 说明 |
|---|---|---|
callback | INativeFileTransCallback | 事件和数据回调接口的实现。 |
parameters | String | JSON字符串,包含鉴权、连接和调试参数。参见连接与控制参数。 |
level | Constants.LogLevel | 控制SDK自身日志的打印级别。 |
save_log | boolean | 是否保存本地日志。若为true,须在连接与控制参数中通过debug_path指定路径,并可通过max_log_file_size设置文件大小。 |
setParams
此接口用于独立设置或更新 nls_config 参数。如果所有参数都在startFileTranscriber中一次性提供,则无需调用此方法。
方法签名
| 参数 | 类型 | 说明 |
|---|---|---|
params | String | 语音识别效果参数中的nls_config参数,nls_config之外的参数不支持通过该方法进行设置。示例: |
startFileTranscriber
开始识别。
方法签名
| 参数 | 类型 | 说明 |
|---|---|---|
params | String | 语音识别效果参数。示例: |
task_id | byte[] | 任务ID,SDK内部生成随机字符串,在此接口调用成功后可获得task_id。 |
queryFileTranscriber
此接口用于主动查询一个异步任务的当前状态和结果。调用成功后,结果将通过onFileTransEventCallback回调中的 EVENT_FILE_TRANS_QUERY_RESULT 事件返回。
此处传入的
task_id 从 EVENT_FILE_TRANS_UPLOADED 事件中获取。| 参数 | 类型 | 说明 |
|---|---|---|
task_id | String | 待查询的任务 ID,从 EVENT_FILE_TRANS_UPLOADED 事件中获取。 |
cancelFileTranscriber
立即取消当前任务。
方法签名
| 参数 | 类型 | 说明 |
|---|---|---|
task_id | String | 待取消的任务 ID,从 EVENT_FILE_TRANS_UPLOADED 事件中获取。 |
release
释放SDK所有内部资源。此方法调用后,SDK实例将变为不可用状态,如需再次使用,必须重新调用initialize进行初始化。
方法签名
GetVersion
获得当前SDK版本信息。
方法签名
INativeFileTransCallback:监听回调
onFileTransEventCallback:监听事件和语音识别结果
方法签名
| 参数 | 类型 | 说明 |
|---|---|---|
event | NuiEvent | 回调事件。 |
resultCode | int | 仅在出现 EVENT_ASR_ERROR 事件时有效。 |
asrResult | AsrResult | 语音识别结果。 |
taskId | String | 任务ID。 |
arg2 | int | 保留参数。 |
onFileTransLogTrackCallback:监听追踪日志
此回调用于接收 SDK 内部的详细日志,方便进行问题定位和调试。
NuiEvent:事件类型
| 事件 | 说明 |
|---|---|
EVENT_FILE_TRANS_CONNECTED | 连接服务成功。 |
EVENT_FILE_TRANS_UPLOADED | 上传待识别音频文件成功,此时可获得当前任务的 task_id。 |
EVENT_FILE_TRANS_QUERY_RESULT | 查询任务结果。 |
EVENT_FILE_TRANS_RESULT | 识别最终结果。 |
EVENT_ASR_ERROR | 语音识别过程中出现错误。 |