房间与通道

在线翻译：房间与通道

房间相关类型

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：精准模式。

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 固定对应右声道，左右两侧气泡的源/目标语言方向各自正确。业务侧无需为旧气泡手动纠正语言标签。

• 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 translateModel: TmkTranslateDeliveryMode
    public var dialogConversationAudioMode: TmkDialogConversationAudioMode
}

public func createTmkTranslationRoom(
    config: TmkTranslationRoomConfig,
    _ callback: @escaping CreateRoomCallback
)

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

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

兼容旧参数重载（已标记废弃 @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,
    translateModel: TmkTranslateDeliveryMode = .default,
    _ callback: @escaping CreateRoomCallback
)

参数说明：

• sourceLang

  • 源语言代码，例如 zh-CN。

• targetLang

  • 目标语言代码，例如 en-US。

• scenario

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

• roomId

  • 可选业务房间号。

  • 传 nil 时由服务端生成。

• channelScenario

  • 通道场景。

  • 常用值：.listen、.oneToOne。

• messageTunnel

  • 文本消息通道。

• speakers

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

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

• translateEngine

  • 在线翻译引擎策略。

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

• callback

  • 建房结果回调。

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

  • 失败：.failure(TmkTranslationError)。

返回值：

• 无。

勿用立即返回值判断成败

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

说明：

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

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

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

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

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

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

• 回调在主线程触发。

示例（推荐使用 TmkTranslationRoomConfig）：

let roomConfig = TmkTranslationRoomConfig(
    sourceLang: "zh-CN",
    targetLang: "en-US",
    scenario: .toSpeech,
    channelScenario: .listen
)

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

---