实时音视频 iOS & Mac SDK

一、功能简介

TXRealtimeASR 是实时流式语音转写引擎：

·实时流式识别：边说边出字，逐句返回识别结果。

·中间结果与稳态结果：通过 isCompleted 区分进行中（中间结果）与已说完（稳态结果）。

·自动 / 指定识别语言：支持 "zh"（中文）、"en"（英文）等，留空即为自动识别。

·说话人区分：结果携带 speakerId，-1 表示未知。

·时间戳定位：结果携带 startTime / endTime，标识该消息在整个音频流中的起止位置（毫秒），-1 表示未知。

·实时音量回调：通过 onRealtimeASRVolume 获取当前音量等级 [0, 100]，可用于绘制音量波动效果。

·自定义音频采集：可通过 enableCustomCapture 开启，自行采集 PCM 后调用 feedPcmData 送入引擎。

·多监听器：通过 addListener: / removeListener: 注册多个回调监听器。

二、相比直接 WebSocket 接入的优势

相比业务方自行通过 WebSocket 对接 ASR 后端，SDK 在端侧完成音频前处理，提供以下开箱即用的能力：

·端侧远场人声降噪：SDK 内置远场人声增强与降噪算法，识别过程中可消除远场人声、环境噪声的干扰，显著提升会议室、客厅、车载等远场场景的识别准确率，业务方无需自行搭建音频前处理链路。可通过实验性 API callExperimentalAPI: 的 setExtraParams 配置 clientDenoiseStrategy 选择降噪策略，详细参见 实验性 API 中的 setExtraParams。

·声纹降噪（只识别指定人的声音）：支持指定目标说话人，识别过程中只转写目标说话人的声音，自动忽略其他人的说话内容，适用于多人会议、车载多乘员等只听某一个人的场景。

三、API Sample

我们提供了一份完整可运行的 iOS Sample，演示如何使用 ASR SDK 实现语音输入与 AI 会话能力。Sample 在 VoiceAIKit 模块中封装了开箱即用的语音输入组件 VoiceInputBar，只需几行代码即可将语音输入功能引入自己的应用。

·下载地址：Tencent-RTC/VoiceAI iOS Sample（快速跑通说明见 快速跑通 iOS Sample）。

Sample 主要包含以下功能：

·语音输入：封装 VoiceInputBar 组件，开箱即用，支持「键盘 / 语音」切换、按住说话、实时识别与确认发送，可将说话内容实时转写为文字并送入业务（如聊天输入框）。

·AI 会话：语音提问 → 大模型（LLM）回复 → 语音播报（TTS），构成完整的语音对话闭环。

五、开通服务

登录 实时音视频控制台，单击创建应用 。如果你已经完成创建，可以跳过该操作。

在创建应用成功后，你可以在应用管理中获取到你的 SDKAppID 和 SDK 密钥。

·SDKAppID： 控制台创建的实时音视频应用的唯一标识。

·SDK 密钥：生成鉴权信息（UserSig）时使用的密钥串。

六、环境要求

七、引入 SDK

将 VoiceAI ASR SDK 引入项目工程，支持以下两种方式：

八、方式一：CocoaPods 引入（推荐）

在 Podfile 中声明依赖，然后执行 pod install：

platform :ios, '11.0' # iOS# platform :osx, '10.13' # macOStarget 'YourApp' do # iOS pod 'TXLiteAVSDK_VoiceAI_iOS', '13.6.0.237' # macOS # pod 'TXLiteAVSDK_VoiceAI_Mac', '13.6.0.237'end

九、方式二：手动引入

1. 下载 SDK 压缩包：

·iOS：iOS SDK 下载

·macOS： Mac SDK 下载

2. 解压后将 TXLiteAVSDK_VoiceAI_iOS.xcframework（macOS 为 TXLiteAVSDK_VoiceAI_Mac.xcframework）拖入工程。

3. 在 Target > General > Frameworks, Libraries, and Embedded Content 中将 framework 设为 Embed & Sign。

十、导入头文件

两种方式均需导入头文件：

#import "TXRealtimeASR.h"

十一、鉴权信息

启动转写前需要准备以下 TRTC 鉴权信息：

注意：关于 UserSig 的安全说明：

注意：UserSig 是用户身份的加密凭证。请勿在客户端硬编码密钥（SECRETKEY）计算 UserSig，密钥一旦泄露会导致云资源被盗用；生产环境应在业务服务端计算 UserSig，App 通过接口动态获取。

注意：UserSig 计算方式参考：

十二、权限声明

实时转写为在线服务，需要网络访问；同时必须在 Info.plist 中声明麦克风权限：

<key>NSMicrophoneUsageDescription</key><string>需要使用麦克风进行语音转写</string>

注意：说明：

注意：首次采集时系统会自动弹出授权弹窗；若用户拒绝授权，需引导其前往「设置」中开启。

注意：macOS 额外要求：若开启了 Hardened Runtime，请在 Target > Signing & Capabilities 中勾选 Audio Input，否则无法访问麦克风。

十三、快速开始

#import "TXRealtimeASR.h"@interface ASRDemo ()<TXRealtimeASRListener>@property (nonatomic, strong) TXRealtimeASR *asr;@end@implementation ASRDemo- (void)startASR { // 1. 创建实例 self.asr = [[TXRealtimeASR alloc] init]; // 2. 设置监听器 [self.asr addListener:self]; // 3. 配置参数并启动 TXRealtimeASRParams *params = [[TXRealtimeASRParams alloc] init]; params.sdkAppId = @"1400000000"; // TRTC 应用 ID params.userSig = @"your_user_sig"; // 服务端下发的用户签名 params.voiceId = @"uuid-xxxx-xxxx-xxxx"; // 识别会话 ID，建议每次调用重新生成 UUID params.sourceLanguage = @"zh"; // 识别语言，"zh"/"en"，留空为自动识别 params.enableCustomCapture = NO; // 是否启用自定义音频采集 [self.asr startRealtimeASR:params]; // 4.（可选）自定义采集模式：开启后自行采集并送入 PCM 音频 // NSData *pcm = …; // 16k、单声道、16bit 采样 // [self.asr feedPcmData:pcm sampleRate:16000 channels:1];}- (void)release { [self.asr stopRealtimeASR]; [self.asr removeListener:self]; self.asr = nil; // ARC 释放}#pragma mark – TXRealtimeASRListener- (void)onRealtimeASRStarted:(NSString *)voiceId { // 转录会话已开启}- (void)onReceiveRealtimeASRMessage:(TXRealtimeASRMessage *)message { if (message.isCompleted) { // 稳态结果：某句话已说完 } else { // 中间结果：正在识别中 } // 可获取该消息在音频流中的时间区间（毫秒），-1 表示未知 int start = message.startTime; int end = message.endTime;}- (void)onRealtimeASRStopped { // 转录正常停止}- (void)onRealtimeASRError:(int)errorCode errorMsg:(NSString *)errorMsg { // 转录出错，errorCode 非 0 表示异常}- (void)onRealtimeASRVolume:(int)volume { // 实时音量，volume 取值 [0, 100]}@end

十六、创建

十七、监听器管理

十八、核心方法

十九、监听器协议 TXRealtimeASRListener

注意：说明：

注意：所有方法均为 @optional，按需实现。所有回调均已切换到主线程，调用方无需关心线程安全。

21、TXRealtimeASRParams（启动参数）

22、TXRealtimeASRMessage（转录消息）

23、实验性 API

callExperimentalAPI: 用于调用实验性 / 扩展能力。入参为 JSON 字符串，返回字符串。格式：

{ "api": "<接口名>", "params": { … } }

24、setExtraParams

引擎参数配置，用于追加自定义的 ASR 引擎参数与降噪策略。

输入参数（params 字段）：

extraRequestParams 可用键名：

参数优先级规则：

1. SDK 内部生成的参数（timestamp、expired、signature、nonce 等）不可被覆盖。

2. 启动参数中的显性字段（sdkAppId、userSig、voiceId、sourceLanguage）不可被覆盖。

3. extraRequestParams 中的其余键——自由扩展，整体追加到 URL 末尾。

注意：说明：

示例：

NSString *json = @"{\\"api\\":\\"setExtraParams\\",\\"params\\":{" @"\\"extraRequestParams\\":\\"engine_model_type=bigmodel\\"," @"\\"clientDenoiseStrategy\\":1}}";[self.asr callExperimentalAPI:json];

25、最佳实践与注意事项

1. 鉴权信息：userSig 应由服务端生成后下发，切勿将生成密钥硬编码到客户端。

2. voiceId 唯一性：每次调用 startRealtimeASR: 建议重新生成新的 UUID 作为 voiceId。

3. 自定义采集：enableCustomCapture = YES 时须主动调用 feedPcmData:sampleRate:channels: 送入 16bit PCM 数据，并保证 sampleRate、channels 与数据一致。

4. 中间结果与稳态结果：isCompleted = NO 的文本会持续更新，仅在 isCompleted = YES 时该段识别才最终确定。

5. 监听器生命周期：监听器被 removeListener: 移除前请保持其引用有效。

6. 生命周期：使用完毕先 stopRealtimeASR，再 removeListener: 并释放对象（ARC）。