Version: Next

离线模型管理

离线翻译并不是“零前置条件即可直接使用”。在正式使用离线翻译前，至少需要满足以下条件：

至少成功调用过一次 verifyAuth(_:)。
当前账号已开通离线翻译能力，即 isOfflineTranslationSupported() 返回 true。
所需离线模型曾下载成功，且本地文件仍然完整可用。

默认离线模型目录

public func defaultOfflineModelRootDirectory() -> String
public func defaultOfflineModelRootDirectoryURL() -> URL

说明：

返回 SDK 默认离线模型目录（Documents/tmkOfflineModel）。
业务方不传 modelRootDirectory 时，相关离线接口会使用该目录。

`downloadOfflineModels(...)`

public func downloadOfflineModels(
    srcLang: String,
    dstLang: String,
    modelRootDirectory: String? = nil,
    scenario: Scenario = .oneToOne,
    needMt: Bool = true,
    needTts: Bool = true,
    listener: TmkOfflineModelDownloadListener?
)

参数说明：

srcLang
- 源语言代码，例如 zh。
dstLang
- 目标语言代码，例如 en。
modelRootDirectory
- 模型根目录。
- nil 时使用默认目录。
scenario
- .listen 或 .oneToOne。
needMt
- 是否下载 MT 模型。
needTts
- 是否下载 TTS 模型。
listener
- 下载监听器。

`cancelOfflineModelDownload()`

public func cancelOfflineModelDownload()

说明：

取消当前正在进行的离线模型下载。

`getOfflineModelPackageInfos(...)`

public func getOfflineModelPackageInfos(
    srcLang: String,
    dstLang: String,
    modelRootDirectory: String? = nil,
    scenario: Scenario = .oneToOne,
    needMt: Bool = true,
    needTts: Bool = true
) -> [TmkOfflineModelPackageInfo]

说明：

获取指定语言对在当前场景下的离线模型包清单与状态。
可用于下载前展示包列表，或用于模型状态诊断。

模型就绪检查接口

public func isOfflineModelReady(
    srcLang: String,
    dstLang: String,
    modelRootDirectory: String? = nil,
    scenario: Scenario = .oneToOne,
    needMt: Bool = true,
    needTts: Bool = true
) -> Bool

public func isAsrModelReady(langCode: String, modelRootDirectory: String? = nil) -> Bool
public func isMtModelReady(srcLang: String, dstLang: String, modelRootDirectory: String? = nil) -> Bool
public func isTtsModelReady(langCode: String, modelRootDirectory: String? = nil) -> Bool
public func isTtsDataReady(modelRootDirectory: String? = nil) -> Bool

public func checkOfflineModelReadyAsync(
    srcLang: String,
    dstLang: String,
    modelRootDirectory: String? = nil,
    scenario: Scenario = .oneToOne,
    needMt: Bool = true,
    needTts: Bool = true,
    callbackQueue: DispatchQueue = .main,
    completion: @escaping OfflineModelReadyCallback
)

说明：

isOfflineModelReady(...)
- 校验当前语言对在指定场景下所需资源是否都已就绪。
checkOfflineModelReadyAsync(...)
- 异步执行离线模型就绪检查。
- 推荐在页面初始化或 UI 交互链路中优先使用，避免同步目录扫描导致主线程卡顿。
其余接口用于单项模型检查。

离线场景所需模型说明

收听模式 `Scenario.listen`

以 zh → en 为例，通常需要：

asr/zh
mt/zh2en
tts/en
tts/tmk-tts-data

一对一模式 `Scenario.oneToOne`

以 zh ↔ en 为例，通常需要：

asr/zh
asr/en
mt/zh2en
mt/en2zh
tts/zh
tts/en
tts/tmk-tts-data

离线通道创建示例（统一接口）

离线收听

let config = TmkTranslationChannelConfig.Builder()
    .setMode(.offline)
    .setScenario(.listen)
    .setSourceLang("zh")
    .setTargetLang("en")
    .setPCMSampleRate(16_000)
    .setPCMChannels(1)
    .setModelRootDirectory(modelRootDirectory)
    .build()

TmkTranslationSDK.shared.createTranslationChannel(config, listener: self) { result in
    switch result {
    case .success(let channel):
        self.channel = channel
    case .failure(let error):
        print(error.message)
    }
}

离线一对一

let config = TmkTranslationChannelConfig.Builder()
    .setMode(.offline)
    .setScenario(.oneToOne)
    .setSourceLang("zh")
    .setTargetLang("en")
    .setSpeakers([
        TmkSpeaker(channel: .left, gender: .female),
        TmkSpeaker(channel: .right, gender: .male)
    ])
    .setOfflineAudioChannelMode(.stereo)
    .setPCMSampleRate(16_000)
    .setPCMChannels(2)
    .setModelRootDirectory(modelRootDirectory)
    .build()

TmkTranslationSDK.shared.createTranslationChannel(config, listener: self) { result in
    switch result {
    case .success(let channel):
        self.channel = channel
    case .failure(let error):
        print(error.message)
    }
}

说明：

.setSpeakers(...) 只覆盖传入声道的音色；不传时使用 SDK 默认音色。
.setOfflineAudioChannelMode(.stereo) 是离线一对一默认行为，适合直接播放立体声 TTS。
如业务侧希望自行合成播放声道，可设置 .setOfflineAudioChannelMode(.mono) 后按 Result.extraData["channel"] 管理音频来源。

离线模型下载监听器

`TmkOfflineModelPackageState`

public enum TmkOfflineModelPackageState: String {
    case ready
    case needsDownload
    case needsUpdate
    case resumable
    case downloading
    case unzipping
    case failed
    case cancelled
}

取值说明：

值	含义
`ready`	已准备完成
`needsDownload`	尚未下载，需要下载
`needsUpdate`	本地版本过旧，需要更新
`resumable`	可继续下载
`downloading`	下载中
`unzipping`	解压中
`failed`	处理失败
`cancelled`	已取消

`TmkOfflineModelPackageInfo`

public struct TmkOfflineModelPackageInfo {
    public let packageKey: String
    public let type: String
    public let name: String
    public let state: TmkOfflineModelPackageState
    public let index: Int
    public let total: Int
    public let downloadedBytes: Int64
    public let totalBytes: Int64
    public let unzipProgress: Double
    public let localDirectory: String
}

字段说明：

packageKey
- 资源包键，例如 asr/zh。
type
- 包类型，例如 asr、mt、tts。
name
- 包名称，例如 zh、zh2en。
state
- 当前资源包状态。
index / total
- 当前批次中的序号和总数。
downloadedBytes / totalBytes
- 下载进度。
unzipProgress
- 解压进度，范围 0.0 ~ 1.0。
localDirectory
- 本地目录。

`TmkOfflineModelDownloadListener`

public protocol TmkOfflineModelDownloadListener: AnyObject {
    func onOfflineModelEvent(name: String, args: Any?)
    func onOfflineModelDownloadProgress(fileName: String, index: Int, total: Int, downloaded: Int64, fileTotal: Int64)
    func onOfflineModelUnzipProgress(fileName: String, progress: Double)
    func onOfflineModelReady()
    func onOfflineModelPackageInfosChanged(_ packages: [TmkOfflineModelPackageInfo])
    func onOfflineModelError(_ error: TmkTranslationError)
}

回调线程：

TmkOfflineModelDownloadListener 的所有回调都会在主线程回调。

各回调说明：

onOfflineModelEvent(name:args:)
- 下载过程中的通用事件回调。
- name 为事件名。
- args 可能为 nil，也可能为简单说明对象。业务方不应强依赖其具体结构。
onOfflineModelDownloadProgress(fileName:index:total:downloaded:fileTotal:)
- 下载进度回调。
- fileName：当前资源包名称。
- index：当前资源包在本次下载批次中的序号，通常从 1 开始。
- total：当前批次总包数。
- downloaded：当前包已下载字节数。
- fileTotal：当前包总字节数；当总大小未知时，可能为 -1。
onOfflineModelUnzipProgress(fileName:progress:)
- 解压进度回调。
- progress 范围为 0.0 ~ 1.0。
onOfflineModelReady()
- 当前批次所需模型均已准备完成。
onOfflineModelPackageInfosChanged(_:)
- 整批资源包状态变化回调。
- packages 中每个 TmkOfflineModelPackageInfo.state 可能取值：
  - ready：已就绪
  - needsDownload：需要下载
  - needsUpdate：需要更新
  - resumable：可继续下载
  - downloading：下载中
  - unzipping：解压中
  - failed：失败
  - cancelled：已取消
onOfflineModelError(_:)
- 下载或解压过程中的统一错误回调。

离线模型管理​

默认离线模型目录​

downloadOfflineModels(...)​

cancelOfflineModelDownload()​

getOfflineModelPackageInfos(...)​

模型就绪检查接口​

离线场景所需模型说明​

收听模式 Scenario.listen​

一对一模式 Scenario.oneToOne​

离线通道创建示例（统一接口）​

离线收听​

离线一对一​

离线模型下载监听器​

TmkOfflineModelPackageState​

TmkOfflineModelPackageInfo​

TmkOfflineModelDownloadListener​

离线模型管理

默认离线模型目录

`downloadOfflineModels(...)`

`cancelOfflineModelDownload()`

`getOfflineModelPackageInfos(...)`

模型就绪检查接口

离线场景所需模型说明

收听模式 `Scenario.listen`

一对一模式 `Scenario.oneToOne`

离线通道创建示例（统一接口）

离线收听

离线一对一

离线模型下载监听器

`TmkOfflineModelPackageState`

`TmkOfflineModelPackageInfo`

`TmkOfflineModelDownloadListener`