房间与通道

在线翻译：房间与通道

房间类型 TmkTranslationRoom

data class TmkTranslationRoom(
    var roomId: String
)

公开方法：

方法	说明
updateRoomLocale(sourceLocales, targetLocales, callback)	运行中更新在线房间语言；要求当前 room 已有关联的 active channel；返回 Cancelable 可在回调前取消
updateTranslateEngine(engine, callback)	运行中切换在线翻译引擎策略；返回 Cancelable，可在回调前取消
updateScenario(scenario, callback)	运行中切换在线房间能力

updateRoomLocale(...) 成功后会返回 Result<Unit>，extraData 中包含更新后的 source_locales 与 target_locale。如果当前房间没有活动在线通道，会返回 INVALID_STATE。语言切换只影响切换后新建的气泡：正在进行的旧气泡会保留其创建时锁定的源/目标语言（旧气泡译文文本仍是旧语言，标签也应保持旧语言）。在线一对一的公开参数语义为 sourceLocales=右路/对方语言、targetLocales=左路/本机语言；SDK 按服务端左右路协议完成映射，业务侧无需手动交换参数或为旧气泡纠正语言标签。

updateTranslateEngine(...) 成功后会返回 Result<Unit>，extraData["translate_engine"] 为当前切换的引擎值；该能力仅影响在线房间，通常对后续服务端处理生效。返回的 Cancelable 只能取消尚未完成的网络请求和回调，已经生效的服务端动作不会回滚。

updateScenario(...) 成功后会返回 Result<Unit>，extraData["scenario"] 为当前房间能力值。业务侧应按新能力调整 UI、播放和结果展示。

createTmkTranslationRoom(config, callback)

创建翻译房间。推荐使用 TmkTranslationRoomConfig 配置对象创建在线房间：

fun createTmkTranslationRoom(
    config: TmkTranslationRoomConfig,
    callback: CreateRoomCallback,
): Cancelable

TmkTranslationRoomConfig 为建房专用配置（与通道配置 TmkTransChannelConfig 区分，仅包含建房所需参数）：

class TmkTranslationRoomConfig private constructor() {
    var mode: TranslationMode                 // 建房模式；默认 ONLINE，OFFLINE 仅创建本地 Room
    var scenario: Scenario?                     // 必填，通道场景：LISTEN / ONE_TO_ONE
    var sourceLang: String                      // 源语言；在线 ONE_TO_ONE 为右路/对方语言，默认 "en"
    var targetLang: String                      // 目标语言；在线 ONE_TO_ONE 为左路/本机语言，默认 "zh"
    var speakers: List<TmkSpeaker>              // 在线建房初始 TTS 音色，可空
    var onlineTranslateEngine: TmkOnlineTranslateEngine // 在线引擎初始策略，默认 AUTOMATIC
    var onlineRecognizeEngine: TmkOnlineRecognizeEngine // 在线识别引擎策略，默认 DEFAULT
    var translateMode: TmkTranslateDeliveryMode   // 翻译下发模式，默认 DEFAULT
    var roomScenario: TmkRoomScenario           // 在线房间初始能力，默认 TRANSLATE_SPEECH_TO_SPEECH
    var dialogConversationAudioMode: TmkDialogConversationAudioMode // 一对一对话音频模式，默认 STANDARD
    var enableSensitiveWordRedaction: TmkSensitiveWordRedactionOption? // 客户端可见文本敏感词脱敏；默认 ENABLED

    class Builder {
        fun setMode(mode: TranslationMode): Builder
        fun setScenario(scenario: Scenario): Builder
        fun setSourceLang(langCode: String): Builder
        fun setTargetLang(langCode: String): Builder
        fun setSpeakers(speakers: List<TmkSpeaker>): Builder
        fun setOnlineTranslateEngine(engine: TmkOnlineTranslateEngine): Builder
        fun setOnlineRecognizeEngine(engine: TmkOnlineRecognizeEngine): Builder
        fun setTranslateMode(mode: TmkTranslateDeliveryMode): Builder
        fun setRoomScenario(roomScenario: TmkRoomScenario): Builder
        fun setDialogConversationAudioMode(mode: TmkDialogConversationAudioMode): Builder
        fun setEnableSensitiveWordRedaction(option: TmkSensitiveWordRedactionOption?): Builder
        fun build(): TmkTranslationRoomConfig   // scenario 未设置会抛 IllegalArgumentException
    }
}

回调说明：

interface CreateRoomCallback {
    fun onSuccess(room: TmkTranslationRoom)
    fun onError(errorId: Int, e: Exception)
}

行为说明：

• 必须先调用 sdkInit(context, config)。

• SDK 在建房时即向服务端完成在线对话链路准备，onSuccess 返回的 TmkTranslationRoom 已包含创建通道所需的 dialog 数据（roomNo、订阅信息等）；业务侧无需再等到通道启动。

• 返回 Cancelable，可在回调前取消建房请求。

• 建房成功若检测到已有房间/通道，SDK 会先释放旧会话再切换到新房间。

• scenario 决定通道场景（LISTEN / ONE_TO_ONE），roomScenario 决定初始在线房间能力，onlineRecognizeEngine 决定初始识别链路，onlineTranslateEngine 决定初始翻译引擎策略；运行中可分别通过 room.updateScenario(...)、room.updateTranslateEngine(...) 切换。SDK 当前未提供运行中切换 onlineRecognizeEngine 的公开接口。

• 创建房间时通过 setOnlineRecognizeEngine(TmkOnlineRecognizeEngine.END_TO_END) 选择端到端链路，或通过 setOnlineRecognizeEngine(TmkOnlineRecognizeEngine.THREE_STAGE) 选择三段式链路。端到端链路忽略 onlineTranslateEngine；三段式链路再结合 FAST / ACCURATE 选择翻译策略。

• dialogConversationAudioMode 设置在线一对一对话音频模式（STANDARD / LOW_LATENCY）；仅 ONE_TO_ONE 场景下 LOW_LATENCY 生效，其他场景自动降级为 STANDARD；默认 STANDARD。STANDARD 使用单 UID 混合双声道，LOW_LATENCY 使用双 UID 左右独立单声道。

• enableSensitiveWordRedaction 控制客户端可见文本是否进行敏感词脱敏，实际语种和词库由 Vocat 配置决定；默认 ENABLED 下发 true，DISABLED 下发 false，显式设置为 null 时保持服务端默认行为。该字段同时用于 room/dialog 和 room/mono-dialog。

• 回调在主线程触发。

示例：

val roomConfig = TmkTranslationRoomConfig.Builder()
    .setScenario(Scenario.LISTEN)
    .setSourceLang("zh-CN")
    .setTargetLang("en-US")
    .setOnlineRecognizeEngine(TmkOnlineRecognizeEngine.THREE_STAGE)
    .setOnlineTranslateEngine(TmkOnlineTranslateEngine.FAST)
    .setRoomScenario(TmkRoomScenario.TRANSLATE_SPEECH_TO_SPEECH)
    .build()

val cancelable = TmkTranslationSDK.createTmkTranslationRoom(roomConfig, object : CreateRoomCallback {
    override fun onSuccess(room: TmkTranslationRoom) {
        // room 已含 dialog 数据，可直接用于构建 TmkTransChannelConfig
    }
    override fun onError(errorId: Int, e: Exception) { }
})

note

兼容的无参重载 createTmkTranslationRoom(callback) 仅生成本地 roomId、不预备在线链路，已不再作为推荐接入方式，新接入请使用上面的 config 重载。

离线本地 Room（Demo 使用方式）

当 TmkTranslationRoomConfig.mode 设置为 TranslationMode.OFFLINE 时，createTmkTranslationRoom(...) 只创建本地 Room，不会请求在线建房接口，也不会建立 RTC/RTM 链路。Android Demo 使用该方式统一管理在线和离线会话的生命周期，再通过 TmkTransChannelConfig.Builder.setRoom(room) 关联本地 Room 与离线通道。

离线通道创建本身不依赖 Room：TmkTransChannelConfig.room 可以为空，SDK 仅在在线模式读取 Room 的 dialog 数据。最小离线接入可以直接创建离线通道；如需与 Demo 保持相同的本地 Room 生命周期，可使用以下流程：

val roomConfig = TmkTranslationRoomConfig.Builder()
    .setMode(TranslationMode.OFFLINE)
    .setScenario(Scenario.LISTEN)
    .setSourceLang("zh-CN")
    .setTargetLang("en-US")
    .build()

TmkTranslationSDK.createTmkTranslationRoom(roomConfig, object : CreateRoomCallback {
    override fun onSuccess(room: TmkTranslationRoom) {
        // 将 room 传给离线 TmkTransChannelConfig.Builder.setRoom(room) 是可选的。
    }

    override fun onError(errorId: Int, e: Exception) { }
})

---