AI Speech (TSAISpeechInterface)

AI Speech provides text-to-speech (TTS), PCM/file/device-microphone speech recognition (ASR), and offline-recognition mode configuration.

Obtain the interface

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

Query the matching feature: SpeechSynthesis, PCMRecognition, FileRecognition, DeviceMicRecognition, or OfflineRecognition.

Data models

Model	Main properties	Description
TSAITTSConfig	speakerId	TTS voice configuration
TSAITTSResult	taskId, audioData, audioFormat, sampleRate, duration	Complete TTS result
TSAITTSStreamChunk	taskId, sequenceIndex, audioData, audioFormat, sampleRate, channelCount, bitsPerChannel	Read-only streaming TTS chunk used by device-initiated Q&A
TSAIASRPCMConfig	language	Fixed-format PCM recognition configuration
TSAIASRFileConfig	language, audioFormat	Local-file recognition configuration
TSAIASRDeviceMicConfig	language, outputAudioFormat, offlineFallbackEnabled, scene	Device-microphone configuration
TSAIASRPartialResult	taskId, sentenceNo, fragmentNo, text, isSentenceFinal	Streaming partial result
TSAIASRResult	taskId, text, duration	PCM or file final result
TSAIASRDeviceMicResult	taskId, text, duration, sessionStartTime, sessionEndTime, scene	Device-microphone final result
TSAIASRDeviceMicResult	isOfflineRecognition, isStoppedByInterruption, recordedAudioFileURL, recordedAudioFormat	Device session metadata

Callback types

Callback	Description
TSAITTSCompletionBlock	Complete TTS audio or error
TSAIASRPartialBlock	Cumulative ASR updates
TSAIASRCompletionBlock	PCM/file terminal result
TSAIASRDeviceMicCompletionBlock	Device-microphone terminal result
TSAIDeviceMicRecognitionStateBlock	Device-microphone state changes
TSAISpeechBoolResultBlock	Boolean query result and error

Text to speech

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

TSAITTSConfig *config = [TSAITTSConfig configWithSpeakerId:@"default"];
NSString *taskId = [speech synthesizeSpeechWithText:@"Welcome to TopStepAIKit"
    config:config
    completion:^(TSAITTSResult *result, NSError *error) {
        if (error) {
            TSLog(@"TTS failed: %@", error.localizedDescription);
            return;
        }
        TSLog(@"Audio bytes: %lu", (unsigned long)result.audioData.length);
    }];

PCM recognition

Input must be non-empty 16 kHz, mono, signed Int16 little-endian PCM.

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

TSAIASRPCMConfig *config =
    [TSAIASRPCMConfig configWithLanguage:TSAILanguageEnglishUS];

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

Audio-file recognition

- (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(@"File ASR failed: %@", error.localizedDescription);
            return;
        }
        TSLog(@"File ASR: %@", result.text);
    }];

TSAIAudioFormatNone asks the SDK to inspect a file header. Raw PCM must specify its format explicitly.

Cancel recognition

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

PCM, file, and device-microphone tasks share this cancellation API. Cancellation discards the current result and completes the original task with an error.

Device-microphone recognition

- (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:TSAILanguageEnglishUS];
config.offlineFallbackEnabled = YES;
config.scene = TSAIASRSceneOnSite;

[speech registerDeviceMicRecognitionStateDidChanged:^(TSAIDeviceMicRecognitionState state) {
    TSLog(@"Device-mic state: %ld", (long)state);
}];

NSString *taskId = [speech recognizeSpeechWithDeviceMicConfig:config
    onPartialResult:^(TSAIASRPartialResult *partial) {
        TSLog(@"Device ASR: %@", partial.text);
    }
    completion:^(TSAIASRDeviceMicResult *result, NSError *error) {
        if (error) {
            TSLog(@"Device ASR failed: %@", error.localizedDescription);
            return;
        }
        TSLog(@"Device ASR complete: %@", result.text);
    }];

// Gracefully flush buffered audio.
// [speech stopDeviceMicRecognitionWithTaskId:taskId];

• stopDeviceMicRecognitionWithTaskId: closes the stream, flushes audio, and returns a final result.
• cancelRecognitionWithTaskId: closes the stream and discards the result.
• rejectDeviceMicRecognitionWithCompletion: rejects a device request when permission or local state prevents recording.

Offline-recognition configuration

- (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(@"Offline mode: %@", success ? @"enabled" : error.localizedDescription);
    }];
}];

Key enums

TSAIAudioFormat value	Description
Unknown	Unknown format
None	No audio in a result, or automatic format inspection in a config
Pcm	PCM
Opus	Opus
Mp3	MP3
Wav	WAV

TSAIASRScene value	Description
Unknown	Unspecified
OnSite	Meetings, interviews, and other on-site recordings
Call	Telephone or VoIP recordings

Device-microphone states and recognition modes

Enum	Values and raw values
TSAIDeviceMicRecognitionState	DeviceStopped = 0, Started = 1, Ended = 2, Failure = 255
TSAISpeechRecognitionMode	Off = 0, On = 1

Add the corresponding enum prefix to shortened values, for example TSAIDeviceMicRecognitionStateStarted.

Important notes

1. ASR language fields do not accept TSAILanguageAuto.
2. Client task IDs are returned synchronously for tracing and cancellation.
3. Completion is authoritative; partial callbacks may run zero or more times.
4. Obtain explicit user permission before processing microphone or recorded audio.
5. Unregister listeners and end device-microphone tasks when leaving the owning feature.