TmkTranslationSDK 架构及业务流程说明

概述

Tmk Translation SDK 统一封装在线翻译链路与离线翻译链路，向 App 提供初始化、语言列表获取、鉴权、建房、建通道、PCM 推流、ASR/MT/TTS 结果回调、释放通道、运行状态、错误、事件、离线模型管理与资源释放能力。

SDK 负责引擎选择、鉴权、房间/通道生命周期、在线 RTC/RTM 链路、离线模型资源检查、状态/错误/事件归一化和主线程回调；Demo/App 负责 UI 展示、麦克风采集、播放策略、用户弹窗和重试决策。

核心功能

• 音频输入：接收 PCM 音频流，默认 16000 Hz、16 bit，按平台通道配置推送。

• 音频输出：输出 PCM 原始音频，由 App/Demo 按业务策略播放。

• ASR / MT / TTS：提供语音识别、文本翻译及语音合成链路。

• 在线/离线统一接入：通过同一套 sdkInit、verifyAuth、createTmkTranslationRoom、createTranslationChannel、TmkTranslationListener 消费结果。

• 离线模型管理：支持模型包状态查询、下载、取消、进度、解压、就绪和错误回调。

• 统一运行契约：通过 onStateChanged、onError、onEvent 输出状态、错误和事件，App/Demo 按契约处理。

下表汇总当前 SDK 对外提供的能力域：

能力域	当前 SDK 对外能力
LocaleList	在线/离线语言列表获取
ASR	在线、离线、流式识别，中间/最终结果回调
MT	在线、离线翻译，中间/最终结果回调
TTS	在线、离线语音合成，PCM 音频回调
Session	在线建房、建通道；离线建通道；Listen / One-to-One 等场景
Offline Model	模型包状态、下载/取消、下载进度、解压进度、就绪、错误事件
Runtime Contract	状态、错误、事件统一回调与推荐处理

架构图

交互流程

初始化与鉴权流程

1. App 构建全局配置，传入 appId、appSecret、网络环境、日志/诊断开关等。

2. App 调用 sdkInit，SDK 保存配置并初始化日志、诊断和基础组件；此时不等同于鉴权完成。

3. App 调用 SDK 提供的在线/离线语言列表，获取 SDK 支持的 ASR、MT、TTS 的语言。

4. App 调用 verifyAuth。SDK 执行在线鉴权，并同步离线 License 能力状态。

5. verifyAuth 成功后，App 可读取 isOfflineTranslationSupported()，再决定是否展示离线能力和模型下载入口。

6. 鉴权失败通过统一错误码返回，App 按错误处理契约提示重新鉴权、检查配置或离开。

在线翻译流程

1. App 创建 TmkTranslationRoomConfig 后，调用 createTmkTranslationRoom 创建在线房间，获取服务端 dialog、订阅 uid、消息通道和 token 信息。

2. App 使用房间对象构建 TmkTranslationChannelConfig / TmkTransChannelConfig，配置场景、语言、模式、PCM 参数、音色、消息通道等。

3. App 调用 createTranslationChannel(config, listener, callback)。预绑定 listener 后，启动阶段的状态、错误、事件也能被 App 收到。

4. SDK 创建在线引擎，建立 RTC/RTM/TTS 链路，并通过 onStateChanged 输出 starting/running/degraded/reconnecting/failed 等状态。

5. 通道 running 后，App 开始采集并调用 pushStreamAudioData 推送 PCM。

6. SDK 通过 onRecognized、onTranslate、onAudioDataReceive 返回识别、翻译和 TTS 音频。

7. App 退出页面或重建对话时调用 releaseChannel 销毁/释放翻译通道、调用 destroy 释放资源。

离线模型与离线翻译流程

1. App 先完成 sdkInit + verifyAuth，并确认 isOfflineTranslationSupported() 为 true。

2. App 通过 getOfflineModelPackageInfos 或 isOfflineModelReady 检查指定语言对和场景的模型资源状态。

3. 模型未就绪时，调用 downloadOfflineModels，通过 TmkOfflineModelDownloadListener 接收模型事件、下载进度、解压进度、包状态变化、就绪和错误。

4. 所有必需模型 ready 后，App 构建离线通道配置，必须提供 modelRootDirectory、源语言、目标语言和场景。

5. App 调用 createTranslationChannel(config, listener, callback) 创建离线通道，SDK 校验 License、模型资源与离线 pipeline。

6. 通道进入 running 后推送 PCM；离线引擎输出 ASR、MT、TTS 和 offline_* 诊断事件。

7. 失败时按契约区分模型未就绪、语言不支持、离线 License 未通过、pipeline 失败或用户取消。

具体 API 文档

Android: Android SDK API

iOS: iOS SDK API

状态处理契约

App/Demo 必须以 SDK 的 onStateChanged 为状态单一来源，不自行伪造 running、failed 等状态。状态契约同步自《SDK 运行状态、错误、事件处理契约》。

state	典型 reason	处理契约
idle	none	通道未启动或初始化完成等待启动；不推流，显示待启动/初始化。
starting	startRequested、rtcConnecting、rtcConnected	通道启动、媒体链路连接或离线 pipeline 准备中；显示连接中/加载中，禁止重复创建，不开始采集。
running	started、rtcConnected、networkRestored	完整链路可用；清除重连/弱网提示，允许采集和播放。
degraded	networkUnavailable、messageChannelFailure、rtcTokenRequested、rtcTokenWillExpire	能力受损但通道未终止；只做弱提示或日志，不弹 fatal，不主动释放通道。
reconnecting	networkUnavailable、rtcInterrupted、rtcLost、messageChannelFailure	在线链路恢复中；显示连接恢复中，禁止重复创建，等待 SDK 最终恢复或失败。
stopping	stopRequested	用户退出、主动停止或页面销毁；停止采集/播放，禁用按钮，等待释放完成。
stopped	stopped	通道已停止；清理 UI 状态或离开页面。
failed	sessionExpired、invalidConfiguration、permissionDenied、bannedByServer、serviceRejected、rtcKeepAliveTimeout、engineError	进入失败态，需要 App 显式处理；在线通常重新创建对话，离线通常重新初始化通道或检查模型资源。

补充约束：

• 离线实现不产生 rtcConnecting、rtcConnected、rtcInterrupted、rtcLost、rtcKeepAliveTimeout、messageChannelFailure 等在线 RTC/RTM 原因。

• degraded 和弱网/丢包事件只用于提示和诊断，不直接关闭通道。

• REQUEST_CANCELLED、页面退出和用户主动停止不弹错误框。

• OFFLINE_MODEL_NOT_READY 先引导下载、更新或重新鉴权，不直接启动离线通道。

事件处理契约

onEvent 和离线模型下载回调用于诊断、弱提示和资源状态同步。业务文本展示以 onRecognized、onTranslate、onAudioDataReceive 为准；通道 UI 状态以 onStateChanged 为准。

事件/回调范围	代表事件	处理契约
online lifecycle	online_started、online_stopped、online_runtime_state_changed	更新或记录在线链路状态；UI 仍以 onStateChanged 为准。
online message	online_stream_message_raw、online_stream_message_parsed、online_notification、notification	诊断和通知消费；kind=close_room 时停止当前会话引用并弹“重新创建/离开”。
online network stats	online_network_quality、online_rtc_stats、online_remote_audio_stats、online_local_audio_stats	连续采样后做弱网/丢包提示；不直接弹 fatal，不直接重建通道。
online remote user	online_remote_user_offline	is_expected_service_uid=true 表示服务端订阅 uid 离线，对话不可继续；停止当前会话引用并弹“重新创建/离开”。
offline pipeline	offline_pipeline_state、offline_stream_message_parsed、offline_asr_partial/final、offline_mt_partial/final、offline_tts_output	诊断和链路追踪；业务展示以正式结果回调为准。
offline failure/state	offline_recognition_failure、offline_tts_state、offline_notification、offline_audio_metadata	单句失败或 TTS 状态可弱提示/日志；通道失败仍以 onStateChanged(.failed) 和 onError 为准。
Android metadata	tts_metadata_received	Android 当前 TTS trace metadata 事件，Demo 可记录耗时日志。
model events	offline_model_cancelled、offline_model_update_required、下载/解压进度、onOfflineModelReady、onOfflineModelError、onOfflineModelPackageInfosChanged	刷新模型列表和下载按钮；取消不弹错误框，需更新时禁止直接启动离线通道，错误按错误码处理。

全局错误码

错误码规范

规范定义：BB-CC-DDD，BB 代表服务/模块，CC 代表子模块，DDD 代表具体错误。

错误域	定义
BB	00-19 为客户端错误，20-59 为服务端错误，60-69 为嵌入式错误
CC	各自模块，如客户端登录模块、设备模块、翻译模块，服务端 Eve 中的 ASR 模块等
DDD	具体错误码

示例：0101103 代表客户端登录模块注册错误 103；3101103 代表登录服务注册模块错误 103。2001 代表服务端 RTC 模块 linker 相关错误码开头。

错误码与错误处理契约

错误处理契约同步自《SDK 运行状态、错误、事件处理契约》。App/Demo 应优先消费统一错误码；离线引擎或离线 License 组件码用于诊断和内部归因。

完整错误码与处理契约见 错误码速查。