版本：v1.2.0

监听器与回调数据

`TmkTranslationListener`

interface TmkTranslationListener {
    fun onRecognized(
        fromEngine: AbstractChannelEngine?,
        r: Result<String>?,
        isFinal: Boolean,
    )

    fun onTranslate(
        fromEngine: AbstractChannelEngine?,
        r: Result<String>?,
        isFinal: Boolean,
    )

    fun onAudioDataReceive(
        fromEngine: AbstractChannelEngine?,
        r: Result<String>?,
        data: ByteArray,
        channelCount: Int,
    )

    fun onError(code: Int, msg: String)
    fun onEvent(eventName: String, args: Any?)
    fun onStateChanged(
        fromEngine: AbstractChannelEngine?,
        snapshot: TmkTranslationChannelStateSnapshot,
    )
}

`onRecognized(...)`

识别文本回调。

参数	说明
`r.data`	ASR 文本
`isFinal` / `r.isLast`	是否为最终结果
`r.srcCode`	源语言
`r.extraData["channel"]`	一对一模式下的声道标识，通常 `"1"` 为左，`"2"` 为右
`r.extraData["bubble_id"]`	文本气泡 ID；在线来自服务端，离线由 SDK 独立生成
`r.extraData["chunk_id"]`	文本分片 ID；在线来自服务端，离线由 SDK 生成
`r.extraData["offset"]`	本段 ASR 语音在音频流中的起始偏移（`Long`，纳秒）；服务端未下发时不存在；MT 翻译回调不携带
`r.extraData["duration"]`	本段 ASR 语音时长（`Long`，纳秒）；服务端未下发时不存在；MT 翻译回调不携带

`onTranslate(...)`

翻译文本回调。

参数	说明
`r.data`	MT 文本
`isFinal` / `r.isLast`	是否为最终结果
`r.srcCode` / `r.dstCode`	源语言与目标语言
`r.extraData["channel"]`	一对一模式下的声道标识
`r.extraData["bubble_id"]`	文本气泡 ID；在线来自服务端，离线由 SDK 独立生成
`r.extraData["chunk_id"]`	文本分片 ID；在线来自服务端，离线由 SDK 生成

`onAudioDataReceive(...)`

翻译后的 TTS PCM 音频回调。

参数	说明
`data`	PCM 16-bit 音频数据
`channelCount`	本次回调音频声道数
`r.extraData["channel"]`	一对一模式下的来源声道
`r.extraData["audio_route"]`	当本次回调为双声道 PCM 且上游未提供该字段时，SDK 补充为 `"stereo"`；单声道回调不强制补充
`r.extraData["bubble_id"]`	离线 TTS 对应文本气泡 ID
`r.extraData["chunk_id"]`	离线 TTS 对应文本分片 ID

离线一对一如果配置 TmkOfflineAudioChannelMode.STEREO，SDK 会按双声道输出；如果配置 MONO，业务侧需要自行按声道缓存和播放。

`onError(code, msg)`

翻译链路错误回调。业务侧应结合错误码、onStateChanged 中的 snapshot.reason 和当前模式决定恢复方式。

`onEvent(eventName, args)`

事件回调用于诊断、弱提示和补充状态，不应替代识别、翻译、音频和状态回调。在线 online_bubble_end 事件表示服务端下发了某个 bubble_id 的结束标记，args 为 Result<String>，可从 result.bubbleId 或 result.extraData["bubble_id"] 读取气泡 ID。该事件仅建议用于业务展示态标记，不阻止后续同一 bubble 的文本更新；未收到该事件也不代表 bubble 一定未结束。

在线 online_tts_state 事件表示服务端下发的 TTS 播放状态。args 为 Result<String>，常见字段如下：

字段	说明
`result.sessionId` / `extraData["session_id"]`	在线语音段 ID，可用于源文片段高亮
`result.bubbleId` / `extraData["bubble_id"]`	在线气泡 ID
`extraData["chunk_id"]`	在线翻译片段 ID，可用于译文片段高亮
`extraData["is_end"]` / `result.isLast`	是否结束本次 TTS 高亮；`true` 时业务侧应取消对应高亮

高亮属于 App/Demo 展示逻辑，SDK 只负责透传事件和稳定字段。建议源文按 session_id 命中，译文按 chunk_id 命中。

`onStateChanged(...)`

通道状态回调。App 应以该回调作为通道 UI 状态的单一来源，不要自行把 STARTING 伪造为 RUNNING，也不要因单次弱网事件主动销毁通道。

Result<T>

字段	说明
`sessionId`	会话 ID；在线优先取服务端 `session_id`，缺失时回退 `chunk_id`，仍缺失为 `"0"`；离线由 SDK 生成
`bubbleId`	结果气泡 ID；在线取服务端 `bubble_id`，缺失时回退 `sid_<sessionId>`；离线由 SDK 独立生成
`data`	结果数据
`srcCode`	源语言
`dstCode`	目标语言
`isLast`	是否为最终结果
`extraData`	附加数据，例如一对一声道、trace 信息、`bubble_id`、`chunk_id`、TTS `audio_route` 等

离线结果 ID 生成规则：

sessionId、bubbleId、extraData["chunk_id"] 均由 SDK 使用“毫秒级时间戳 + 同毫秒内递增序号”生成。
bubbleId 独立生成，不等同于 sessionId。
同一段离线 ASR/MT/TTS 结果复用同一组公开 ID；一对一左右声道按声道和原始离线 session 维度分别生成，避免同时产出时冲突。
在线 extraData 只保留服务端/翻译结果实际携带的数据，不会为了补齐 sessionId 合成 extraData["session_id"]。

通道状态模型

data class TmkTranslationChannelStateSnapshot(
    val state: TmkTranslationChannelState,
    val reason: TmkTranslationChannelStateReason,
    val code: Int? = null,
    val message: String = "",
    val isRecoverable: Boolean = true,
    val updatedAtMs: Long = System.currentTimeMillis(),
)

TmkTranslationChannelState：

state	说明
`IDLE`	空闲
`STARTING`	启动中
`RUNNING`	正常运行
`RECONNECTING`	网络或在线链路正在恢复
`DEGRADED`	降级可用
`STOPPING`	停止中
`STOPPED`	已停止
`FAILED`	已失败

常见 TmkTranslationChannelStateReason：

reason	说明
`NONE`	无特殊原因
`START_REQUESTED` / `STARTED`	启动请求或启动完成
`STOP_REQUESTED` / `STOPPED`	停止请求或停止完成
`NETWORK_UNAVAILABLE` / `NETWORK_RESTORED`	网络不可用或恢复
`RTC_CONNECTING` / `RTC_CONNECTED` / `RTC_INTERRUPTED` / `RTC_LOST`	在线 RTC 状态
`RTC_KEEP_ALIVE_TIMEOUT`	在线保活超时
`RTC_TOKEN_REQUESTED` / `RTC_TOKEN_WILL_EXPIRE`	在线 token 续期相关状态
`SESSION_EXPIRED`	在线会话过期
`INVALID_CONFIGURATION`	配置错误
`PERMISSION_DENIED`	权限不足
`BANNED_BY_SERVER` / `SERVICE_REJECTED`	服务端拒绝或对话不可继续
`MESSAGE_CHANNEL_FAILURE`	在线消息通道异常
`ENGINE_ERROR`	引擎内部错误

状态回调处理契约

state	常见 reason	App 推荐处理
`IDLE`	`NONE`	显示待启动或初始化状态，不推流。
`STARTING`	`START_REQUESTED` / `RTC_CONNECTING` / `RTC_CONNECTED`	显示“通道连接中/正在加载”，禁止重复创建。`RTC_CONNECTED` 不代表完整业务链路已 ready。
`RUNNING`	`STARTED` / `RTC_CONNECTED` / `NETWORK_RESTORED`	显示通道可用，允许采集，清除弱网或重连提示。
`DEGRADED`	`NETWORK_UNAVAILABLE` / `MESSAGE_CHANNEL_FAILURE` / `RTC_TOKEN_REQUESTED` / `RTC_TOKEN_WILL_EXPIRE`	显示非阻塞弱网或能力受损提示，不停止录音/播放。
`RECONNECTING`	`NETWORK_UNAVAILABLE` / `RTC_INTERRUPTED` / `RTC_LOST` / `MESSAGE_CHANNEL_FAILURE`	显示连接恢复中，禁止重复创建，等待 SDK 恢复或升级为失败。
`STOPPING`	`STOP_REQUESTED`	禁用操作按钮，等待停止完成。
`STOPPED`	`STOPPED`	清理 UI 状态或离开页面。
`FAILED`	`SESSION_EXPIRED` / `INVALID_CONFIGURATION` / `PERMISSION_DENIED` / `BANNED_BY_SERVER` / `SERVICE_REJECTED` / `RTC_KEEP_ALIVE_TIMEOUT` / `ENGINE_ERROR`	停止录音/播放，按错误码提示用户重新创建、重新初始化、下载模型、重新鉴权或离开。

离线通道不产生 RTC_CONNECTING、RTC_CONNECTED、RTC_INTERRUPTED、RTC_LOST、RTC_KEEP_ALIVE_TIMEOUT、MESSAGE_CHANNEL_FAILURE 等 RTC/RTM 原因。

事件回调处理契约

事件类型	常见事件	App 推荐处理
在线运行事件	`online_started`、`online_stopped`、`online_runtime_state_changed`	日志和 UI 辅助；UI 状态以 `onStateChanged` 为准。
在线消息事件	`online_stream_message_raw`、`online_stream_message_parsed`、`online_notification`、`notification`、`online_bubble_end`	诊断为主；`close_room` 类通知需要停止当前会话引用，并提示用户重新创建或离开；`online_bubble_end` 仅标记对应 `bubble_id` 已收到结束信号，不改变原有 bubble 划分，也不阻止后续内容更新。
在线 TTS 高亮事件	`online_tts_state`	按 `session_id` / `chunk_id` 更新播放高亮，诊断为主。
在线弱网事件	`online_network_quality`、`online_rtc_stats`、`online_remote_audio_stats`、`online_local_audio_stats`	连续采样后显示弱网提示，不直接释放通道。
在线远端离线事件	`online_remote_user_offline`	当 `is_expected_service_uid=true` 时，说明服务端音频/翻译订阅 uid 离线，对话不可继续，应提示重新创建或离开。
离线 pipeline 事件	`offline_pipeline_state`、`offline_stream_message_parsed`、`offline_audio_metadata`	诊断和日志为主；UI 仍以 `onStateChanged` 和业务结果回调为准。
离线结果辅助事件	`offline_asr_partial`、`offline_asr_final`、`offline_mt_partial`、`offline_mt_final`、`offline_tts_output`、`offline_tts_state`、`offline_recognition_failure`、`offline_bubble_end`	可用于诊断或弱提示；正式文本和音频展示以识别、翻译、音频回调为准。`offline_bubble_end` 语义与在线 `online_bubble_end` 对齐，`args` 为 `Result<String>`，可从 `result.bubbleId` 读取气泡 ID。
模型下载事件	`offline_model_cancelled`、`offline_model_update_required`、下载进度、解压进度、模型包状态变化	更新模型列表和进度；取消不弹错误框，需更新时禁止直接启动离线通道。

离线模型包状态处理契约

package state	App 推荐处理
`READY`	显示已就绪；所有必需包 ready 后可创建离线通道。
`NEEDS_DOWNLOAD`	显示待下载，禁止启动离线通道。
`NEEDS_UPDATE`	显示需更新，引导重新下载。
`RESUMABLE`	显示可续传，点击下载继续。
`DOWNLOADING`	显示下载进度，允许取消。
`UNZIPPING`	显示解压进度，避免重复触发下载。
`FAILED`	显示失败，允许重试。
`CANCELLED`	显示已取消，允许重新下载，不弹错误框。