房间与通道

在线翻译：房间与通道

房间相关类型

TmkTranslationMessageTunnel（仅在线翻译使用）

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

含义：

• rtm：通过 Agora RTM 接收识别/翻译文本。

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

一般建议使用 rtm。

说明：

• 该配置仅在线翻译使用。

• 离线翻译不使用 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"	端到端链路，语音直接完成识别和翻译。translateEngine 不参与该链路。
threeStage	"m_001"	三段式链路：识别、翻译到 TTS。需结合 translateEngine 决定翻译方式。

组合关系：

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

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

note

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

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?
public func updateRoomLocale(sourceLocales: [String],
                             targetLocales: [String],
                             completion: @escaping (Result<Void, TmkTranslationError>) -> Void) -> TmkSDKCancellable?
public func updateTranslateEngine(_ translateEngine: TmkOnlineTranslateEngine = .automatic,
                                  completion: @escaping (Result<Void, TmkTranslationError>) -> Void) -> TmkSDKCancellable?
public func updateScenario(_ scenario: TmkRoomScenario,
                           completion: @escaping (Result<Void, TmkTranslationError>) -> Void) -> TmkSDKCancellable?

说明：

• 关闭当前房间。

• 只在在线翻译中使用。

• updateRoomLocale(...) 用于运行中更新在线房间语言，在不重建房间的前提下生效。语言切换只影响切换后新建的气泡：正在进行的旧气泡会保留其创建时锁定的源/目标语言（旧气泡译文文本仍是旧语言，标签也应保持旧语言）；一对一场景下，sourceLocales 直接对应服务端左路、targetLocales 直接对应服务端右路。该接口不使用 TmkTranslationRoomConfig 的业务字段映射，业务侧无需为旧气泡手动纠正语言标签。

• updateTranslateEngine(...) 用于运行中切换在线翻译引擎策略，回调在主线程触发；切换成功后通常对后续服务端处理生效。

• updateScenario(...) 用于运行中切换在线房间能力，可在 .recognize、.toText、.toSpeech 之间切换；业务侧应按新能力调整 UI、播放和结果展示。

createTmkTranslationRoom(...)

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

public struct TmkTranslationRoomConfig {
    public var sourceLang: String
    public var targetLang: String
    public var scenario: TmkRoomScenario
    public var roomId: String?
    public var channelScenario: Scenario
    public var messageTunnel: TmkTranslationMessageTunnel
    public var speakers: [TmkSpeaker]?
    public var translateEngine: TmkOnlineTranslateEngine
    public var recognizeEngine: 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。

兼容旧参数重载（已标记废弃 @available(*, deprecated)，新接入请改用上面的 config: 重载）：

public func createTmkTranslationRoom(
    sourceLang: String = "en-US",
    targetLang: String = "zh-CN",
    scenario: TmkRoomScenario = .toSpeech,
    roomId: String? = nil,
    channelScenario: Scenario = .listen,
    messageTunnel: TmkTranslationMessageTunnel = .rtm,
    speakers: [TmkSpeaker]? = nil,
    translateEngine: TmkOnlineTranslateEngine = .automatic,
    recognizeEngine: TmkOnlineRecognizeEngine = .default,
    _ callback: @escaping CreateRoomCallback
)

参数说明：

• sourceLang

  • 源语言代码，例如 zh-CN。在 .oneToOne 场景中表示右路/对方语言。

• targetLang

  • 目标语言代码，例如 en-US。在 .oneToOne 场景中表示左路/本机语言。

• scenario

  • 房间业务场景，通常使用 .toSpeech。

• roomId

  • 可选业务房间号。

  • 传 nil 时由服务端生成。

• channelScenario

  • 通道场景。

  • 常用值：.listen、.oneToOne。

• messageTunnel

  • 文本消息通道。

• speakers

  • 在线建房时初始 TTS 音色。

  • 传 nil 时使用服务端默认音色策略。

• translateEngine

  • 在线翻译引擎策略。

  • .automatic 表示由服务端自动选择。

• recognizeEngine

  • 在线识别引擎策略。

  • .default 表示由服务端决定识别链路。

• callback

  • 建房结果回调。

  • 成功：.success(TmkTranslationRoom)，此时 Room 已包含创建通道所需的 dialog 数据。

  • 失败：.failure(TmkTranslationError)。

返回值：

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

勿用立即返回值判断成败

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

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

说明：

• 在线翻译必须先建房，再创建通道。

• 建房时 scenario 决定初始在线房间能力：.recognize 为单 ASR，.toText 为 ASR+MT 文本输出，.toSpeech 为 ASR+MT+TTS 语音输出。

• 建房时 recognizeEngine 决定初始在线识别链路，translateEngine 决定初始在线翻译引擎策略；仅 translateEngine 可通过 room.updateTranslateEngine(...) 在运行中切换。

• 在线一对一的通道音频模式来自 TmkTranslationRoomConfig.dialogConversationAudioMode；离线一对一的通道音频模式来自 TmkTranslationChannelConfig.Builder.setChannelAudioMode(...)。

• enableSensitiveWordRedaction 控制客户端可见文本是否进行敏感词脱敏；默认值为 .enabled，显式设置为 nil 时保持服务端默认行为，适用于 room/dialog 和 room/mono-dialog。

• SDK 不再返回半成品 Room，避免业务侧在 dialog 数据未准备好时误用。

• 建房请求完成前 SDK 内部会临时持有 Room，调用方无需为了等待回调额外强引用 Room。

• 回调在主线程触发。

示例（推荐使用 TmkTranslationRoomConfig）：

let roomConfig = TmkTranslationRoomConfig(
    sourceLang: "zh-CN",
    targetLang: "en-US",
    scenario: .toSpeech,
    channelScenario: .listen,
    recognizeEngine: .threeStage,
    translateEngine: .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)
    }
}

---