iOS SDK 概览

本次更新

当前版本更新内容：

• 新增网络请求统一超时配置 setNetworkTimeout(_:)，作用于鉴权、建房、建通道、语言列表等所有网络请求；未设置时默认 15 秒，超时处理与网络请求超时保持一致。

• 在线/离线一对一统一使用 sourceLang=右路/对方、targetLang=左路/本机的业务字段语义；在线低延迟 TTS 应以 audio_route 选择本机播放路，speaker_channel 仅用于关联原始说话侧。

• SDK 可同时保留一个在线和一个离线运行时；releaseChannel() 会一次释放两者。

• 新增通道配置 setTranslateMode(_:)，用于离线通道设置翻译下发模式（partial 中间态下发 / stable 断句后下发），在线引擎忽略此配置。

• 新增通道配置 setCapabilityTier(_:)，用于离线通道设置能力档位（.recognize 仅 ASR / .toText ASR + MT / .toSpeech 完整链路），控制离线引擎按需加载模型。

• 新增 channel.updateLanguages(sourceLang:targetLang:completion:) 带回调重载：在线为可超时、可取消的真实句柄，离线为流式切换，不打断音频流、不销毁并重建 pipeline，且不可取消。

• 新增 channel.updateTranslateMode(_:completion:)，运行时切换翻译下发模式；仅离线支持，在线返回 .engineNotSupported。

• 新增 channel.updateScenario(_:completion:)，运行时切换能力档位（在线/离线统一入口）；在线走服务端热切，离线升档前校验模型就绪后按需加载或卸载 MT/TTS。

• createTmkTranslationRoom、createTranslationChannel 以及运行中异步能力接口返回 TmkSDKCancellable?；业务方可忽略返回值，需要取消尚未完成的请求时调用 cancel()。已完成的服务端动作不会回滚，离线不支持中途取消的接口返回 nil。

• iOS 设备密钥 Security.framework 错误按 OSStatus 细分为 2001201-2001206/2001299，同时提供稳定的中英文说明和 actualErrorCode/actualErrorDomain/actualErrorMessage 诊断字段；详见错误码速查。

• onRecognized 回调的 result.extraData 新增 offset（Int64，纳秒）和 duration（Int64，纳秒），表示本段 ASR 语音在音频流中的起始偏移与时长；服务端未下发时不存在，MT 翻译回调不携带这些字段。

• 新增离线气泡结束事件 offline_bubble_end，语义与在线 online_bubble_end 对齐；SDK 通过 onEvent 回调，args 为 TmkResult<String>，可从 result.bubbleId 读取气泡 ID。

• 离线 TTS 公共数据目录从 tts/espeak-ng-data 改名为 tts/tmk-tts-data，下载相关路径同步更新。

简介

TmkTranslationSDK 用于将业务侧采集的 PCM 音频接入翻译能力，并向业务侧返回：

• 识别文本

• 翻译文本

• 翻译后的 PCM 音频

• 通道状态与错误信息

• 诊断日志与离线模型状态

当前 SDK 同时支持：

• 在线翻译

• 离线翻译

• 收听模式（单声道）

• 一对一模式（双声道）

本文面向外部接入方，重点说明：

• SDK 初始化与鉴权

• 在线/离线接入流程

• 所有公开接口与数据模型

• 常见使用方式与注意事项

---

接入前准备

环境要求

项目	说明
最低系统版本	iOS 15.0+
Swift 版本	Swift 5.x
真机架构	arm64
模拟器	以发布产物包含的 simulator slice 为准
发布产物	TmkTranslationSDK.xcframework

权限要求

宿主 App 需要声明麦克风权限：

<key>NSMicrophoneUsageDescription</key>
<string>需要访问麦克风以采集实时语音</string>

如果联调环境使用 HTTP，还需要按实际情况配置 ATS 例外。生产环境建议只使用 HTTPS

<key>NSAppTransportSecurity</key>
        <dict>
          <key>NSAllowsArbitraryLoads</key>
        <true/>
</dict>

安装示例

推荐使用 CocoaPods

pod 'TmkTranslationSDK', '1.3.1'

使用 pod install --repo-update 安装 SDK，并且需要在 Build Setting 中设置 User Script sandboxing 为 NO；

如具体发布版本与本文不一致，请以发布说明为准。

---

核心流程总览

在线翻译

在线模式典型流程：

1. sdkInit

2. getOnlineSupportedLanguages(version:_:)

3. verifyAuth

4. createTmkTranslationRoom

5. createTranslationChannel

6. pushStreamAudioData

7. releaseChannel

8. destroy

离线翻译

离线模式典型流程：

1. sdkInit

2. getOfflineSupportedLanguages(version:_:)

3. verifyAuth

4. isOfflineTranslationSupported

5. isOfflineModelReady 或 downloadOfflineModels

6. createTranslationChannel（config.mode = .offline）

7. pushStreamAudioData

8. releaseChannel

9. destroy

回调线程说明

SDK 对外的大多数异步回调都会切回主线程后再回调业务方，包括：

• verifyAuth

• createTmkTranslationRoom

• createTranslationChannel

• closeRoom

监听器 TmkTranslationListener 的回调会切回主线程后再回调业务方，可直接用于更新 UI。

离线模型下载监听器 TmkOfflineModelDownloadListener 的回调同样会切回主线程。

在线与离线的主要区别

项目	在线翻译	离线翻译
是否依赖 verifyAuth	是	建议先鉴权，用于确认离线能力
是否需要房间	需要	不需要
是否需要离线模型	不需要	需要
通道创建接口	createTranslationChannel	createTranslationChannel

---