Android SDK 概览

本次更新

当前版本更新内容：

• 新增网络请求统一超时配置 setNetworkTimeout(seconds: Long)，作用于鉴权、建房、建通道、语言列表等所有网络请求；未设置时默认 15 秒，超时处理与 SDK 的 watchdog 保持一致。

• TmkTranslationRoomConfig 新增 dialogConversationAudioMode 字段与 Builder.setDialogConversationAudioMode(...) 方法，用于设置在线一对一对话音频模式（STANDARD / LOW_LATENCY），与 iOS 行为对齐。

• Android 在线一对一低延迟模式使用双 UID、左右独立单声道；离线一对一低延迟模式支持通过 SpeakerChannel.LEFT/RIGHT 分别推送两路单声道 PCM。

• 在线/离线一对一统一使用 sourceLang=右路/对方、targetLang=左路/本机的业务字段语义；低延迟 TTS 应以 audio_route 选择本机播放路，speaker_channel 仅用于关联原始说话侧。

• SDK 可同时保留一个在线和一个离线运行时；releaseChannel() 会一次释放两者。Android 原生产物已适配 16 KB page-size 设备。

• TmkTransChannelConfig.Builder 新增 setTranslateMode(mode)，用于离线通道设置翻译下发模式（partial 中间态 / stable 断句后），在线引擎忽略此配置。

• 新增 channel.updateLanguages(sourceLang, targetLang, callback)：运行时切换通道语言，在线/离线统一入口；在线为可超时、可取消的真实句柄，离线为流式切换，不打断音频流且不可取消。

• channel.updateTranslateMode(mode, callback?) 现在返回 Cancelable；一参旧调用保持兼容，传入 callback 时在线通道回调 ENGINE_NOT_SUPPORTED。channel.updateTranslateEngine(engine, callback) 复用房间更新链路并返回可取消句柄。

• createTranslationChannel 的原有重载现在返回 Cancelable；旧代码可忽略返回值，取消会阻止尚未执行的后续动作和回调，并释放新建通道，旧通道不会恢复。

• 新增 channel.updateScenario(scenario, callback)：运行时切换能力档位（在线/离线统一入口）；在线走服务端热切，离线升档前校验模型就绪后按需加载或卸载 MT/TTS。

• onRecognized 回调的 r.extraData 新增 offset（Long，纳秒）和 duration（Long，纳秒），表示本段 ASR 语音在音频流中的起始偏移与时长；服务端未下发时不存在，MT 翻译回调不携带这些字段。

• 新增离线气泡结束事件 offline_bubble_end，语义与在线 online_bubble_end 对齐。

• 离线 TTS 公共数据目录从 tts/espeak-ng-data 改名为 tts/tmk-tts-data，下载相关路径同步更新。

简介

TmkTranslationSDK 用于将业务侧采集的 PCM 音频接入翻译能力，并向业务侧返回：

• 识别文本

• 翻译文本

• 翻译后的 PCM 音频

• 通道状态与错误信息

• 诊断日志与离线模型状态

当前 SDK 同时支持：

• 在线翻译

• 离线翻译

• 收听模式（单声道）

• 一对一模式（双声道）

本文面向外部接入方，重点说明：

• SDK 初始化与鉴权

• 在线/离线接入流程

• 所有公开接口与数据模型

• 常见使用方式与注意事项

---

接入前准备

环境要求

项目	说明
最低系统版本	minSdk 28
Java/Kotlin 目标版本	11
发布产物	co.timekettle.translation:tmk-translation-sdk
运行环境	Android 真机或可访问音频/网络能力的测试设备

权限要求

在线模式需要网络权限：

<uses-permission android:name="android.permission.INTERNET" />

如果业务侧自行录音并向 SDK 推送 PCM，需要声明麦克风权限：

<uses-permission android:name="android.permission.RECORD_AUDIO" />

note

SDK 负责消费业务侧传入的 PCM 数据；录音权限申请、录音器管理和用户授权提示由宿主 App 负责。

依赖配置

通过 Maven Central 安装

可通过 Maven Central 安装，以具体版本号为准

dependencies {
    implementation("co.timekettle.translation:tmk-translation-sdk:1.3.1")
}

如具体发布版本与本文不一致，请以发布说明为准。

通过下载安装

AAR 下载地址：

https://github.com/timekettle/tmk-translation-sdk/releases/download/v\{version\}/tmk-translation-sdk-\{version\}.aar

请替换 version 为具体版本号，如下：

https://github.com/timekettle/tmk-translation-sdk/releases/download/v1.2.0-rc3/tmk-translation-sdk-1.2.0-rc3.aar

设置必要的 Android 依赖库

网络配置

生产环境建议使用 HTTPS。若联调环境使用 HTTP，需要按 Android 要求配置 networkSecurityConfig 允许明文流量：

<network-security-config>
    <base-config cleartextTrafficPermitted="true" />
</network-security-config>

核心流程总览

startInitAfter 解释

startInitAfter 是内部属性，createTranslationChannel 传 listener 时 startInitAfter 就是 true，接口关系具体可参数以下表格

重载签名	内部	行为
createTranslationChannel(context, config, callback)	false	只 init + join，不自动 start
createTranslationChannel(context, config, callback, options)	false	同上，可配置超时
createTranslationChannel(context, config, listener, callback)	true	init + join + 自动 start，创建即可推流
createTranslationChannel(context, config, listener, callback, options)	true	同上，可配置超时

在线翻译

在线模式典型流程：

1. sdkInit

2. getOnlineSupportedLanguages(version, callback)

3. verifyAuth

4. createTmkTranslationRoom

5. createTranslationChannel 需要 startInitAfter = true

6. channel.pushStreamAudioData

7. releaseChannel

8. destroy

离线翻译

离线模式典型流程：

1. sdkInit

2. getOfflineSupportedLanguages(version, callback)

3. verifyAuth

4. isOfflineTranslationSupported

5. isOfflineModelReady 或 downloadOfflineModels

6. 可选：创建 TranslationMode.OFFLINE 的本地 Room（与 Android Demo 的会话生命周期一致）

7. createTranslationChannel（config.mode = TranslationMode.OFFLINE）

8. pushStreamAudioData

9. releaseChannel

10. destroy

Android 离线通道通过统一的 createTranslationChannel 入口创建，config.room 可为空。Android Demo 会先创建 TranslationMode.OFFLINE 的本地 Room 并关联到通道，用于统一在线、离线会话的生命周期；该步骤不访问在线建房接口，也不建立 RTC/RTM 链路。离线模式不会使用在线 RTC/RTM 状态原因，但通道生命周期和回调入口与在线保持一致。

回调线程说明

SDK 对外异步回调会切回主线程后再回调业务方，包括：

• verifyAuth

• createTranslationChannel 的启动型重载

• TmkOfflineModelDownloadListener

• checkOfflineModelReadyAsync

• updateSpeaker 结果回调

TmkTranslationListener 的状态、文本、音频、事件回调可直接用于更新 UI；业务侧仍应避免在回调中执行耗时任务。

在线与离线的主要区别

项目	在线翻译	离线翻译
是否依赖 verifyAuth	是	建议先鉴权，用于确认离线能力
是否需要房间对象	需要	不需要；Android Demo 可选创建本地 Room 以统一会话生命周期
是否需要离线模型	不需要	需要
通道创建接口	createTranslationChannel	createTranslationChannel
运行状态原因	包含 RTC/RTM、网络、服务端原因	主要来自模型、pipeline、离线鉴权和引擎状态

---