房间与通道

在线翻译：房间与通道

房间类型 TmkTranslationRoom

data class TmkTranslationRoom(
    var roomId: String
)

公开方法：

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

updateRoomLocale(...) 成功后会返回 Result<Unit>，extraData 中包含更新后的 source_locales 与 target_locale。如果当前房间没有活动在线通道，会返回 INVALID_STATE。语言切换只影响切换后新建的气泡：正在进行的旧气泡会保留其创建时锁定的源/目标语言（旧气泡译文文本仍是旧语言，标签也应保持旧语言）；一对一场景下，sourceLocales 对应左声道、targetLocales 对应右声道，左右两侧气泡的源/目标语言方向各自正确。业务侧无需为旧气泡手动纠正语言标签。

updateTranslateEngine(...) 成功后会返回 Result<Unit>，extraData["translate_engine"] 为当前切换的引擎值；该能力仅影响在线房间，通常对后续服务端处理生效。

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

createTmkTranslationRoom(config, callback)

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

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

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

class TmkTranslationRoomConfig private constructor() {
    var scenario: Scenario?                     // 必填，通道场景：LISTEN / ONE_TO_ONE
    var sourceLang: String                      // 源语言，默认 "en"
    var targetLang: String                      // 目标语言，默认 "zh"
    var speakers: List<TmkSpeaker>              // 在线建房初始 TTS 音色，可空
    var onlineTranslateEngine: TmkOnlineTranslateEngine // 在线引擎初始策略，默认 AUTOMATIC
    var translateMode: TmkTranslateDeliveryMode   // 翻译下发模式，默认 DEFAULT
    var roomScenario: TmkRoomScenario           // 在线房间初始能力，默认 TRANSLATE_SPEECH_TO_SPEECH
    var dialogConversationAudioMode: TmkDialogConversationAudioMode // 一对一对话音频模式，默认 STANDARD

    class 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 setTranslateMode(mode: TmkTranslateDeliveryMode): Builder
        fun setRoomScenario(roomScenario: TmkRoomScenario): Builder
        fun setDialogConversationAudioMode(mode: TmkDialogConversationAudioMode): 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 决定初始在线房间能力，onlineTranslateEngine 决定初始在线引擎策略；运行中可分别通过 room.updateScenario(...)、room.updateTranslateEngine(...) 切换。

• dialogConversationAudioMode 设置在线一对一对话音频模式（STANDARD / LOW_LATENCY）；仅 ONE_TO_ONE 场景下 LOW_LATENCY 生效，其他场景自动降级为 STANDARD；默认 STANDARD。

• 回调在主线程触发。

示例：

val roomConfig = TmkTranslationRoomConfig.Builder()
    .setScenario(Scenario.LISTEN)
    .setSourceLang("zh-CN")
    .setTargetLang("en-US")
    .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 重载。

---