生命周期与工具

资源释放与生命周期

TmkTranslationChannel.destroy()

停止通道、释放底层资源、清除 listener，并从全局通道集合中移除。该方法只作用于单个通道对象；页面退出、切换模式、切换房间或切换语言对时，建议使用 TmkTranslationSDK.releaseChannel() 作为会话级释放入口。

TmkTranslationSDK.releaseChannel()

释放当前翻译通道和当前会话相关资源：

fun releaseChannel()

行为说明：

• 停止并销毁当前通道，清空当前房间引用。

• 如果当前在线房间已创建成功，SDK 会异步调用关房流程，避免服务端遗留预建房间。

• 不会清空 sdkInit(context, config) 的全局配置，也不会清空鉴权状态。

• 释放后可以直接重新创建房间与通道。

建议

• 页面退出、切换模式、切换房间或切换语言对时，优先调用 TmkTranslationSDK.releaseChannel()。
• 调用 releaseChannel() 后，业务侧不需要再对同一房间重复触发关房。

TmkTranslationSDK.destroy()

释放 SDK 全局资源：

fun destroy()

行为说明：

• 销毁当前所有 TmkTranslationChannel。

• 释放在线共享资源和埋点会话。

• 清空全局配置并重置初始化状态。

• 后续如需继续使用，必须重新调用 sdkInit(context, config)，并按需调用 verifyAuth(mode, callback)；SDK 不会根据业务场景自动选择鉴权模式。

---

可取消请求句柄

Cancelable

updateSpeaker(...) 返回 Cancelable：

interface Cancelable {
    val isCanceled: Boolean
    fun cancel()
}

取消只影响尚未执行或尚未回调的任务，已生效的服务端动作或音色设置不会回滚。REQUEST_CANCELLED 属于主动取消类错误，业务侧不应弹 fatal 错误框。

---

PCM 工具与音频要求

SDK 接收业务侧推送的 PCM：

• 格式：16-bit little-endian PCM

• 推荐采样率：16000

• 收听模式：单声道

• 一对一模式：双声道交织数据

• 推荐帧长：约 20ms

业务侧需要保证录音器输出与 TmkTransChannelConfig 中的 sampleRate、channelNum 一致。

---

诊断能力

Android 诊断日志由 TmkTransGlobalConfig 控制。诊断能力默认开启，默认等级为 ESSENTIAL；如果业务不希望采集任何诊断文件，需要显式关闭。

配置	说明
setDiagnosisConfig(config)	设置分级诊断日志配置，包括启用状态、采集等级、自定义根目录和音频采集开关。
setDiagnosisConsoleEnabled(enabled)	是否同步输出诊断日志到控制台

示例：

val config = TmkDiagnosisConfig(
    enabled = true,
    level = TmkDiagnosisLevel.DIAGNOSTIC,
    rootDirectory = null,
    audioCaptureEnabled = false
)

诊断等级

等级	采集内容	保留策略
ESSENTIAL	SDK 初始化/销毁、在线和离线鉴权结果、License 与离线包状态、创建/加入/关闭房间、切换语言、切换音色、翻译引擎切换、房间能力接口、错误、超时、创建房间前网络环境、严重网络异常。默认不采集普通 RTC/RTM/Audio/TTS 高频日志，不采集 ASR/MT partial，不创建 Agora 目录，不采集音频文件。	每个文件最大 10 MiB，超限后清理最旧完整日志行，目标清理约 20%；最多保留 10 次会话日志。
DIAGNOSTIC	包含 ESSENTIAL，并增加 Agora 普通日志、常规网络状态、ASR/MT completed 或 final 结果、TTS 关键阶段日志。	仅保留 2 天内数据；单文件最大 10 MiB；滚动文件命名为 workflow.log、workflow1.log 等。
TRACE	包含 DIAGNOSTIC，并增加 ASR/MT partial、RTC/RTM/Audio/TTS 追踪日志等高频数据；只有 audioCaptureEnabled=true 时才采集 PCM/Agora 音频文件。	仅保留 4 天内数据；单文件最大 10 MiB；滚动文件命名为 workflow.log、workflow1.log 等。

诊断目录与导出

目录	说明
filesDir/sdk_diagnosis	SDK 诊断根目录，位于应用私有目录。
filesDir/sdk_diagnosis/sdk.log	SDK 初始化、鉴权、License、离线包、销毁等全局诊断日志。
filesDir/sdk_diagnosis/network_status.log	网络环境、Agora 连接状态、丢包和严重网络异常日志。
filesDir/sdk_diagnosis/<conversation>/workflow.log	单次对话工作流日志，包括建房、入会、关房、语言/音色/引擎/能力接口、ASR/MT/TTS 关键事件和错误。
filesDir/sdk_diagnosis/<conversation>/Agora	Agora RTC/RTM 普通日志目录，仅 DIAGNOSTIC 和 TRACE 按需创建。
filesDir/sdk_diagnosis/<conversation>/pcm	音频诊断文件目录，仅 TRACE 且 audioCaptureEnabled=true 时按需创建。

• 关闭诊断时，SDK 不采集诊断日志，也不采集 Agora RTC/RTM 日志。

• 切换诊断等级不会主动清理历史日志；清理只由保留策略、文件超限或磁盘紧张触发。

• SDK 诊断日志先进入有界内存队列，再由后台批量落盘；文件 I/O 不应阻塞 SDK 业务线程。应用退出、进入后台、释放通道或导出诊断目录时会尽量触发落盘。

• 磁盘紧张时，SDK 会优先清理 PCM/音频诊断文件和较旧的对话日志。

• Android 的诊断目录属于应用私有目录，不能依赖文件管理器直接访问。

• 如需导出，业务应使用 SDK 返回的诊断目录自行打包并分享。

隐私与脱敏

诊断日志可用于排查鉴权、建房、建通道、离线模型、在线 RTC/RTM 和离线 pipeline 问题。SDK 会对 token、connect token、Agora app id、用户标识、license 等敏感字段做脱敏；上传诊断日志前仍需要完成用户授权、业务侧脱敏复核和访问控制，不应记录或上传原始 License、clientSecret、设备私钥或完整用户隐私数据。

---