跳到主要内容

Android STT SDK 对外接入文档

SDK Version: 1.0.0

适用模块：STT SDK 1.0.0 入口类：com.xtalk.mesh.sdk.stt.XTalkStt 当前实现：Android 离线 Vosk 引擎，模型随 SDK assets 打包。

能力概览​

Android STT SDK 提供离线语音转文字能力。业务侧只需要传入 WAV 文件 URI 和语言标签，SDK 会准备本地模型并返回转写文本。

能力接口说明
预热模型XTalkStt.prepare(context, languageTag)可选；提前解压并加载模型
转写 WAVXTalkStt.transcribeWavUri(context, wavUri, languageTag)返回 XTalkSttResult(text)
分类错误XTalkSttException(code, message, cause)用 XTalkSttErrorCode 区分打包、模型、音频和引擎错误

Gradle 集成​

工程内 app 依赖：

dependencies {
}

构建 AAR：

./gradlew :stt-sdk:assembleRelease

产物：

音频要求​

当前 Android 实现只支持：

条件要求
容器WAV / RIFF
编码PCM 16-bit
声道单声道
采样率16 kHz
URIContentResolver 可打开的 URI 字符串

如果音频不是这个格式，SDK 会抛出 XTalkSttException(code = AUDIO_UNSUPPORTED)。调用方应在录音导出阶段保证格式一致，或者在调用前完成转码。

基本调用​

import android.content.Context
import android.net.Uri
import com.xtalk.mesh.sdk.stt.XTalkStt
import com.xtalk.mesh.sdk.stt.XTalkSttException
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext

suspend fun transcribeMessage(
  context: Context,
  wavUri: Uri,
): String {
  return withContext(Dispatchers.IO) {
    try {
      val result =
        XTalkStt.transcribeWavUri(
          context = context,
          wavUri = wavUri.toString(),
          languageTag = "zh-CN",
        )
      result.text
    } catch (e: XTalkSttException) {
      throw e
    }
  }
}

可选预热​

首次转写会自动准备模型。为了减少用户点击后的等待，可以在应用启动后、进入转写页面前或录音完成前预热：

XTalkStt.prepare(
  context = context,
  languageTag = "zh-CN",
)

预热会触发模型解压和加载。prepare() 与 transcribeWavUri() 都是 suspend API，应在协程中调用。

语言标签​

当前内置模型：

languageTag模型
以 zh 开头，例如 zh-CNvosk-model-small-cn-0.22.zip
其他或 nullvosk-model-small-en-us-0.15.zip

错误处理​

try {
  val text = XTalkStt.transcribeWavUri(context, wavUri.toString(), "zh-CN").text
} catch (e: XTalkSttException) {
  when (e.code) {
    XTalkSttErrorCode.ENGINE_NATIVE_MISSING -> showMessage("语音识别引擎未正确打包")
    XTalkSttErrorCode.MODEL_MISSING -> showMessage("离线模型缺失")
    XTalkSttErrorCode.MODEL_CORRUPT -> showMessage("离线模型解压失败")
    XTalkSttErrorCode.AUDIO_UNSUPPORTED -> showMessage("音频格式不支持")
    XTalkSttErrorCode.TRANSCRIBE_FAILED -> showMessage("转写失败")
  }
}

错误码：

code含义
ENGINE_NATIVE_MISSINGVosk/JNA native library 缺失或 ABI 不匹配
MODEL_MISSINGAPK assets 中没有对应模型 zip
MODEL_CORRUPT模型解压、移动或加载目录异常
AUDIO_UNSUPPORTEDWAV 不是 mono/16-bit/16kHz PCM
TRANSCRIBE_FAILED引擎执行或结果解析失败

SDK 边界​

STT SDK 负责：

  • 准备离线模型。
  • 从 WAV URI 读取音频。
  • 校验 WAV 基本格式。
  • 调用离线识别引擎。
  • 返回纯文本和分类错误。

STT SDK 不负责：

  • 录音权限申请。
  • 录音采集。