Version: v1.3.2

房间与通道

在线翻译：房间与通道

房间相关类型

`TmkTranslationMessageTunnel`（iOS 专有，仅在线翻译使用）

public enum TmkTranslationMessageTunnel: String, Equatable {
    case rtm
    case rtc
}

含义：

rtm：通过 Agora RTM 接收识别/翻译文本。
rtc：通过 Agora RTC stream message 接收识别/翻译文本。

一般建议使用 rtm。

说明：

该配置仅在线翻译使用。
Android 暂未提供对应接口。
离线翻译不使用 TmkTranslationMessageTunnel。

`TmkRoomScenario`

public enum TmkRoomScenario {
    case recognize
    case toText
    case toSpeech
}

含义：

recognize：单 ASR，只输出识别文本。
toText：ASR+MT，输出文本翻译，不要求 TTS 语音合成。
toSpeech：ASR+MT+TTS，输出识别文本、翻译文本和翻译音频。

实时翻译常用 toSpeech。

`TmkOnlineTranslateEngine`

public enum TmkOnlineTranslateEngine: String {
    case automatic = ""
    case fast = "g_001"
    case accurate = "o_001"
}

`TmkTranslateDeliveryMode`

/// 翻译结果下发模式。
/// - Note: 控制服务端翻译文本的下发时机；标准对话与现场收听共用同一套语义。
public enum TmkTranslateDeliveryMode: String, Equatable, Sendable, CaseIterable {
    /// 默认下发策略：传空字符串，由服务端按当前默认策略处理。
    case `default` = ""
    /// 中间态下发：翻译过程中持续下发中间结果，时延更低。
    case partial
    /// 稳定态下发：仅在翻译稳定后下发，结果更完整。
    case stable
}

含义：

automatic：由服务端自动选择在线翻译引擎。
fast：快速模式。
accurate：精准模式。

`TmkOnlineRecognizeEngine`

public enum TmkOnlineRecognizeEngine: String, Equatable, Sendable, CaseIterable {
    case `default` = ""
    case endToEnd = "d_004"
    case threeStage = "m_001"
}

在线识别引擎策略决定识别链路：

枚举	协议值	说明
`default`	`""`	不指定识别引擎，由服务端决定，默认值。
`endToEnd`	`"d_004"`	端到端链路，语音直接完成识别和翻译。`onlineTranslateEngine` 不参与该链路。
`threeStage`	`"m_001"`	三段式链路：识别、翻译到 TTS。需结合 `onlineTranslateEngine` 决定翻译方式。

组合关系：

识别链路	`onlineRecognizeEngine`	`onlineTranslateEngine`
端到端	`.endToEnd`	忽略。
三段式普通 MT	`.threeStage`	`.fast`。
三段式 LLM	`.threeStage`	`.accurate`。

三种链路的处理流程、结果特点和选择建议见在线翻译链路。

note

选择 .endToEnd 后，updateTranslateEngine(_:) 不生效。SDK 当前未提供运行中切换 onlineRecognizeEngine 的公开接口；如需切换识别链路，请使用新配置重新创建房间。

`TmkTranslationRoomDialogResponse`

public struct TmkTranslationRoomDialogResponse: Equatable, Sendable {
    public struct TranslationItem: Equatable, Sendable {
        public let locale: String
        public let subscribeUid: String
    }

    public struct SpeakerItem: Equatable, Sendable {
        public let channel: String
        public let locale: String
        public let connectUid: String
        public let subscribeUid: String
        public let speakerIdentityNo: String
    }

    public let connectUid: String
    public let roomNo: String
    public let speakerIdentityNo: String
    public let translationList: [TranslationItem]
    public let speakers: [SpeakerItem]
}

字段说明：

connectUid
- 当前用户连接 UID。
roomNo
- 服务端房间号。
speakerIdentityNo
- 说话人身份号。
translationList
- 目标语言订阅列表。
- 每项的 subscribeUid 表示对应语言音频流的订阅 UID。
speakers
- 低延迟一对一对话的左右路 speaker 列表；标准对话场景下可能为空。
- 每项包含左右路标识 channel、该路语言 locale、入会 UID connectUid、翻译音频订阅 UID subscribeUid 与说话人身份标识 speakerIdentityNo。

`TmkTranslationRoom`

TmkTranslationRoom 是在线翻译的房间容器。

公开属性：

channelDialogResponse: TmkTranslationRoomDialogResponse?
- 最近一次成功建房后的 dialog 快照。
roomScenario: TmkRoomScenario
- 当前房间业务场景。
messageTunnel: TmkTranslationMessageTunnel
- 当前文本消息通道。

公开方法：

public func closeRoom(completion: @escaping (Result<Void, TmkTranslationError>) -> Void) -> TmkSDKCancellable?

说明：

关闭当前房间。
只在在线翻译中使用。

`createTmkTranslationRoom(...)`

推荐使用配置对象创建在线房间：

public struct TmkTranslationRoomConfig {
    public var mode: TranslationMode
    public var sourceLang: String
    public var targetLang: String
    public var roomScenario: TmkRoomScenario
    public var roomId: String?
    public var channelScenario: Scenario
    public var messageTunnel: TmkTranslationMessageTunnel
    public var speakers: [TmkSpeaker]?
    public var onlineTranslateEngine: TmkOnlineTranslateEngine
    public var onlineRecognizeEngine: TmkOnlineRecognizeEngine
    public var translateMode: TmkTranslateDeliveryMode
    public var dialogConversationAudioMode: TmkDialogConversationAudioMode
    public var enableSensitiveWordRedaction: TmkSensitiveWordRedactionOption?
}

public func createTmkTranslationRoom(
    config: TmkTranslationRoomConfig,
    _ callback: @escaping CreateRoomCallback
) -> TmkSDKCancellable?

当 channelScenario 为 .oneToOne 时，配置中的 sourceLang 表示右路/对方语言，targetLang 表示左路/本机语言；SDK 建房时映射为 left = targetLang、right = sourceLang。双声道 PCM 的左路应对应 targetLang，右路应对应 sourceLang，业务侧无需手动交换字段。

TmkDialogConversationAudioMode 用于在线一对一对话音频模式：

枚举	说明
`standard`	标准一对一对话音频模式
`lowLatency`	低延迟一对一对话音频模式，适合双方长时间连续说话、翻译和播报

TmkSensitiveWordRedactionOption 用于控制客户端可见文本的敏感词脱敏，实际语种和词库由 Vocat 配置决定：

枚举	请求值
`enabled`	`true`
`disabled`	`false`

默认值为 .enabled 并下发 true；显式设置为 nil 时不下发字段，保持服务端默认行为。该字段同时用于 room/dialog 和 room/mono-dialog。

参数说明：

sourceLang
- 源语言代码，例如 zh-CN。在 .oneToOne 场景中表示右路/对方语言。
targetLang
- 目标语言代码，例如 en-US。在 .oneToOne 场景中表示左路/本机语言。
roomScenario
- 房间业务场景，通常使用 .toSpeech。
roomId
- 可选业务房间号。
- 传 nil 时由服务端生成。
channelScenario
- 通道场景。
- 常用值：.listen、.oneToOne。
messageTunnel
- iOS 专有的文本消息通道；Android 暂未提供对应接口。
speakers
- 在线建房时初始 TTS 音色。
- 传 nil 时使用服务端默认音色策略。
onlineTranslateEngine
- 在线翻译引擎策略。
- .automatic 表示由服务端自动选择。
onlineRecognizeEngine
- 在线识别引擎策略。
- .default 表示由服务端决定识别链路。
callback
- 建房结果回调。
- 成功：.success(TmkTranslationRoom)，此时 Room 已包含创建通道所需的 dialog 数据。
- 失败：.failure(TmkTranslationError)。

返回值：

返回 TmkSDKCancellable?。业务方可以忽略返回值；需要取消尚未完成的建房时调用 cancel()。

勿用立即返回值判断成败

不要从立即返回值获取 Room；必须在 callback 成功分支中拿到 Room 后再创建通道。

取消只会阻止尚未完成的建房后续动作和结果回调；已经完成的服务端动作不会回滚。需要切换当前翻译会话时，仍应按生命周期要求显式调用 releaseChannel()。

说明：

在线翻译必须先建房，再创建通道。
建房时 roomScenario 决定初始在线房间能力：.recognize 为单 ASR，.toText 为 ASR+MT 文本输出，.toSpeech 为 ASR+MT+TTS 语音输出。
建房时 onlineRecognizeEngine 决定初始在线识别链路，onlineTranslateEngine 决定初始在线翻译引擎策略；运行中可通过通道对象上的对应接口切换支持的能力。
在线一对一的通道音频模式来自 TmkTranslationRoomConfig.dialogConversationAudioMode；离线一对一的通道音频模式来自 TmkTranslationChannelConfig.Builder.setChannelAudioMode(...)。
enableSensitiveWordRedaction 控制客户端可见文本是否进行敏感词脱敏；默认值为 .enabled，显式设置为 nil 时保持服务端默认行为，适用于 room/dialog 和 room/mono-dialog。
SDK 不再返回半成品 Room，避免业务侧在 dialog 数据未准备好时误用。
建房请求完成前 SDK 内部会临时持有 Room，调用方无需为了等待回调额外强引用 Room。
回调在主线程触发。

示例（推荐使用 TmkTranslationRoomConfig）：

let roomConfig = TmkTranslationRoomConfig(
    mode: .online,
    sourceLang: "zh-CN",
    targetLang: "en-US",
    roomScenario: .toSpeech,
    channelScenario: .listen,
    onlineRecognizeEngine: .threeStage,
    onlineTranslateEngine: .fast
)

TmkTranslationSDK.shared.createTmkTranslationRoom(config: roomConfig) { result in
    switch result {
    case .success(let room):
        print(room.channelDialogResponse?.roomNo ?? "-")
    case .failure(let error):
        print(error.message)
    }
}

在线翻译：房间与通道​

房间相关类型​

TmkTranslationMessageTunnel（iOS 专有，仅在线翻译使用）​

TmkRoomScenario​

TmkOnlineTranslateEngine​

TmkTranslateDeliveryMode​

TmkOnlineRecognizeEngine​

TmkTranslationRoomDialogResponse​

TmkTranslationRoom​

createTmkTranslationRoom(...)​