AI 语音（TSAISpeechInterface）

AI 语音模块提供文本转语音（TTS）以及 PCM、音频文件、设备麦克风三种语音识别（ASR）入口，并支持设备离线识别模式配置。

获取接口

TSAIContext *context = [TSAIKit sharedInstance].activeContext;
id<TSAISpeechInterface> speech = context.speech;

根据实际入口查询 TSAIFeatureSpeechSynthesis、TSAIFeaturePCMRecognition、TSAIFeatureFileRecognition、TSAIFeatureDeviceMicRecognition 或 TSAIFeatureOfflineRecognition。

数据模型

模型	主要属性	说明
`TSAITTSConfig`	`speakerId`	TTS 发音人配置
`TSAITTSResult`	`taskId`、`audioData`、`audioFormat`、`sampleRate`、`duration`	完整 TTS 结果
`TSAITTSStreamChunk`	`taskId`、`sequenceIndex`、`audioData`、`audioFormat`、`sampleRate`、`channelCount`、`bitsPerChannel`	设备主动问答使用的只读流式 TTS 分片
`TSAIASRPCMConfig`	`language`	固定格式 PCM 识别配置
`TSAIASRFileConfig`	`language`、`audioFormat`	本地文件识别配置
`TSAIASRDeviceMicConfig`	`language`、`outputAudioFormat`、`offlineFallbackEnabled`、`scene`	设备麦克风识别配置
`TSAIASRPartialResult`	`taskId`、`sentenceNo`、`fragmentNo`、`text`、`isSentenceFinal`	流式中间结果
`TSAIASRResult`	`taskId`、`text`、`duration`	PCM 或文件识别最终结果
`TSAIASRDeviceMicResult`	`taskId`、`text`、`duration`、`sessionStartTime`、`sessionEndTime`、`scene`	设备麦克风最终结果
`TSAIASRDeviceMicResult`	`isOfflineRecognition`、`isStoppedByInterruption`、`recordedAudioFileURL`、`recordedAudioFormat`	离线、打断和录音文件信息

回调类型

回调	说明
`TSAITTSCompletionBlock`	返回完整 TTS 音频或错误
`TSAIASRPartialBlock`	返回累积语音识别中间结果
`TSAIASRCompletionBlock`	PCM/文件识别终态回调
`TSAIASRDeviceMicCompletionBlock`	设备麦克风识别终态回调
`TSAIDeviceMicRecognitionStateBlock`	设备麦克风识别状态变化
`TSAISpeechBoolResultBlock`	返回布尔查询结果和错误

文本转语音

- (NSString *)synthesizeSpeechWithText:(NSString *)text
                                config:(TSAITTSConfig *)config
                            completion:(nullable TSAITTSCompletionBlock)completion;

- (void)cancelSynthesisWithTaskId:(NSString *)taskId;

TSAITTSConfig *config = [TSAITTSConfig configWithSpeakerId:@"default"];
NSString *taskId = [speech synthesizeSpeechWithText:@"欢迎使用 TopStepAIKit"
    config:config
    completion:^(TSAITTSResult *result, NSError *error) {
        if (error) {
            TSLog(@"语音合成失败: %@", error.localizedDescription);
            return;
        }
        TSLog(@"生成音频 %lu 字节", (unsigned long)result.audioData.length);
    }];

PCM 语音识别

输入必须是非空的 16 kHz、单声道、有符号 Int16 小端 PCM 数据。

- (NSString *)recognizeSpeechWithPCMData:(NSData *)pcmData
                                  config:(TSAIASRPCMConfig *)config
                         onPartialResult:(nullable TSAIASRPartialBlock)onPartialResult
                              completion:(nullable TSAIASRCompletionBlock)completion;

TSAIASRPCMConfig *config =
    [TSAIASRPCMConfig configWithLanguage:TSAILanguageChineseSimplified];

NSString *taskId = [speech recognizeSpeechWithPCMData:pcmData
    config:config
    onPartialResult:^(TSAIASRPartialResult *partial) {
        TSLog(@"识别中: %@", partial.text);
    }
    completion:^(TSAIASRResult *result, NSError *error) {
        TSLog(@"识别结果: %@", result.text);
    }];

音频文件识别

- (NSString *)recognizeSpeechWithFileURL:(NSURL *)audioFileURL
                                  config:(TSAIASRFileConfig *)config
                         onPartialResult:(nullable TSAIASRPartialBlock)onPartialResult
                              completion:(nullable TSAIASRCompletionBlock)completion;

TSAIASRFileConfig *config =
    [TSAIASRFileConfig configWithLanguage:TSAILanguageEnglishUS];
config.audioFormat = TSAIAudioFormatWav;

NSString *taskId = [speech recognizeSpeechWithFileURL:fileURL
    config:config
    onPartialResult:nil
    completion:^(TSAIASRResult *result, NSError *error) {
        if (error) {
            TSLog(@"文件识别失败: %@", error.localizedDescription);
            return;
        }
        TSLog(@"文件识别结果: %@", result.text);
    }];

当 audioFormat 为 TSAIAudioFormatNone 时，SDK 尝试根据文件头识别格式；裸 PCM 必须明确指定格式。

取消识别

- (void)cancelRecognitionWithTaskId:(NSString *)taskId;

PCM、文件和设备麦克风识别共用此取消入口。取消会丢弃当前结果，并通过原 completion 返回取消错误。

设备麦克风语音识别

- (NSString *)recognizeSpeechWithDeviceMicConfig:(TSAIASRDeviceMicConfig *)config
                                 onPartialResult:(nullable TSAIASRPartialBlock)onPartialResult
                                      completion:(nullable TSAIASRDeviceMicCompletionBlock)completion;

- (void)stopDeviceMicRecognitionWithTaskId:(NSString *)taskId;
- (void)registerDeviceMicRecognitionStateDidChanged:(nullable TSAIDeviceMicRecognitionStateBlock)stateBlock;
- (void)rejectDeviceMicRecognitionWithCompletion:(nullable TSAICompletionBlock)completion;

TSAIASRDeviceMicConfig *config =
    [TSAIASRDeviceMicConfig configWithLanguage:TSAILanguageChineseSimplified];
config.offlineFallbackEnabled = YES;
config.scene = TSAIASRSceneOnSite;

[speech registerDeviceMicRecognitionStateDidChanged:^(TSAIDeviceMicRecognitionState state) {
    TSLog(@"设备麦克风识别状态: %ld", (long)state);
}];

NSString *taskId = [speech recognizeSpeechWithDeviceMicConfig:config
    onPartialResult:^(TSAIASRPartialResult *partial) {
        TSLog(@"设备识别中: %@", partial.text);
    }
    completion:^(TSAIASRDeviceMicResult *result, NSError *error) {
        if (error) {
            TSLog(@"设备识别失败: %@", error.localizedDescription);
            return;
        }
        TSLog(@"设备识别完成: %@", result.text);
    }];

// 正常结束并冲刷已缓冲音频
// [speech stopDeviceMicRecognitionWithTaskId:taskId];

设备麦克风输入没有自然结束点：

stopDeviceMicRecognitionWithTaskId:：关闭麦克风流、处理缓冲音频并返回最终结果。
cancelRecognitionWithTaskId:：关闭麦克风流并丢弃当前结果。
rejectDeviceMicRecognitionWithCompletion:：设备已请求录音，但 App 因权限或业务冲突无法接受时使用。

离线识别配置

- (void)queryOfflineSpeechSupportedWithCompletion:(nullable TSAISpeechBoolResultBlock)completion;

- (void)setSpeechRecognitionMode:(TSAISpeechRecognitionMode)mode
                      completion:(nullable TSAICompletionBlock)completion;

- (void)setOfflineSpeechMode:(TSAISpeechRecognitionMode)mode
                  completion:(nullable TSAICompletionBlock)completion;

[speech queryOfflineSpeechSupportedWithCompletion:^(BOOL success, BOOL supported, NSError *error) {
    if (!success || !supported) {
        return;
    }

    [speech setOfflineSpeechMode:TSAISpeechRecognitionModeOn
                      completion:^(BOOL success, NSError *error) {
        TSLog(@"切换离线识别: %@", success ? @"成功" : error.localizedDescription);
    }];
}];

关键枚举

TSAIAudioFormat

枚举值	说明
`TSAIAudioFormatUnknown`	未知格式
`TSAIAudioFormatNone`	无音频，或配置中表示自动嗅探
`TSAIAudioFormatPcm`	PCM
`TSAIAudioFormatOpus`	Opus
`TSAIAudioFormatMp3`	MP3
`TSAIAudioFormatWav`	WAV

TSAIASRScene

枚举值	说明
`TSAIASRSceneUnknown`	未指定
`TSAIASRSceneOnSite`	会议、采访、面对面等现场录音
`TSAIASRSceneCall`	电话或 VoIP 通话录音

设备麦克风状态与识别模式

枚举	枚举值与数值
`TSAIDeviceMicRecognitionState`	`DeviceStopped = 0`、`Started = 1`、`Ended = 2`、`Failure = 255`
`TSAISpeechRecognitionMode`	`Off = 0`、`On = 1`

表格中的值应加上对应枚举名前缀，例如 TSAIDeviceMicRecognitionStateStarted。

注意事项

ASR 的 language 不允许使用 TSAILanguageAuto。
所有 taskId 均由客户端同步生成，可用于日志关联和取消。
completion 是终态权威信号；中间结果可能调用零次或多次。
设备麦克风和录音文件涉及隐私，调用前应完成权限说明和用户授权。
页面或业务退出时注销状态监听，并结束仍在运行的设备麦克风任务。

获取接口​

数据模型​

回调类型​

文本转语音​

PCM 语音识别​

音频文件识别​

取消识别​

设备麦克风语音识别​

离线识别配置​

关键枚举​

TSAIAudioFormat​

TSAIASRScene​

设备麦克风状态与识别模式​

注意事项​