Text to Speech

Synthesize text through the selected AI provider and receive a local audio file that your app can play or otherwise process.

Prerequisites

• AIBudsAISDK is initialized and a registered provider is selected.
• The provider supports TTSServiceAPI.
• Provider authentication and network access are available when required.
• Invoke synthesis from a background thread, as required by the public SDK contract.

Implement with AI Assistance

Build with AI

Implement this workflow with AI

Use the official Implement AIBuds Text to Speech skill to adapt this workflow to your app.

Read and follow https://docs-aibuds.github.io/skills/implement-aibuds-text-to-speech. Use it to implement Implement AIBuds Text to Speech in this iOS project and verify the result.

View official skill↗

API Reference

Framework

AIBudsAI.xcframework

Import

Swift

Swift

import AIBudsAI
import AIBudsAIFoundation

Objective-C

Objective-C

#import <AIBudsAI/AIBudsAI-Swift.h>

Declaration

Swift

Swift

/// Synthesizes text into speech.
/// - Parameters:
///   - text: The text to synthesize.
///   - config: The synthesis configuration.
///   - completion: Called with the task identifier, success state, optional
///     result, and optional error when synthesis completes.
/// - Important: Call this method from a background thread to avoid blocking
///   the main thread.
public static func synthesizeText(_ text: String,
                                  config: TTSConfig = .default,
                              completion: ((
                                  _ taskId: String?,
                                  _ success: Bool,
                                  _ response: TTSResultModel?,
                                  _ error: NSError?
                              ) -> Void)? = nil) -> Void

Objective-C

Objective-C

/// Synthesizes text into speech.
/// - Parameters:
///   - text: The text to synthesize.
///   - config: The synthesis configuration.
///   - completion: Called with the task identifier, success state, optional
///     result, and optional error when synthesis completes.
/// - Important: Call this method from a background thread to avoid blocking
///   the main thread.
+ (void)synthesizeText:(NSString * _Nonnull)text
                config:(AIBudsTTSConfig * _Nonnull)config
            completion:(void (^ _Nullable)(NSString * _Nullable, BOOL, AIBudsTTSResultModel * _Nullable, NSError * _Nullable))completion;

See synthesizeText.

Configuration and Result

TTSConfig exposes an optional speakerId. When it is nil, the provider selects its default speaker.

On success, TTSResultModel provides:

Property	Description
audioFile	Audio file path relative to the app's documents directory.
audioFilePath	Full path to the synthesized audio file.
audioFormat	Format of the synthesized audio file.

Usage Examples

Swift

Swift

let config = TTSConfig.default
config.speakerId = nil

DispatchQueue.global(qos: .userInitiated).async {
    AIBudsAISDK.synthesizeText(
        "Hello, how can I help you?",
        config: config
    ) { taskId, success, response, error in
        guard success, let response else {
            print(error?.localizedDescription ?? "Synthesis failed")
            return
        }

        print("Task: \(taskId ?? "Unavailable")")
        print("Audio: \(response.audioFilePath)")

        DispatchQueue.main.async {
            playAudio(atPath: response.audioFilePath)
        }
    }
}

Objective-C

Objective-C

AIBudsTTSConfig *config = [AIBudsTTSConfig defaultConfig];
config.speakerId = nil;

dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
    [AIBudsAISDK
        synthesizeText:@"Hello, how can I help you?"
                config:config
            completion:^(
                NSString *taskId, BOOL success, AIBudsTTSResultModel *response, NSError *error) {
                if (!success || response == nil) {
                    NSLog(@"%@", error.localizedDescription ?: @"Synthesis failed");
                    return;
                }

                NSLog(@"Task: %@", taskId ?: @"Unavailable");
                NSLog(@"Audio: %@", response.audioFilePath);

                dispatch_async(dispatch_get_main_queue(), ^{
                    [self playAudioAtPath:response.audioFilePath];
                });
            }];
});

Notes

• This API synthesizes a file; it does not start device playback and does not expose stopSpeaking() or isSpeaking().
• Treat success, response, and error together. A successful operation requires success == true and a non-nil response.
• Speaker identifiers are provider-specific. Only set an identifier documented by the selected provider.
• Move UI and audio-player updates back to the main thread.