Voices

Two things determine how synthesis sounds: which TTS model is loaded, and the voice field on RATTSOptions. Neural voices are models you register and download. System voices come from AVSpeechSynthesizer and need no download.

Voice sources

Source	Framework	Delivery	Raw PCM available
Sherpa-ONNX Piper	`.sherpa`	tar.gz archive, downloaded	Yes
MLX audio models	`.mlx`	multi-file, downloaded	Yes
Apple system TTS	`.systemTts`	built in, nothing to download	No, playback only

Apple’s AVSpeechSynthesizer synthesizes straight to the speaker and gives no way to capture samples for arbitrary text. Use speak() with system voices; use a Piper or MLX model when you need synthesize() to hand back audio.

Loading a neural voice

Voices are models, so they go through the same register, download, load sequence as anything else.

let voice = try await RunAnywhere.registerModel(
    archive: "https://github.com/RunanywhereAI/sherpa-onnx/releases/download/runanywhere-models-v1/vits-piper-en_US-lessac-medium.tar.gz",
    structure: .nestedDirectory,
    id: "vits-piper-en_US-lessac-medium",
    name: "Piper TTS (US English, Medium)",
    framework: .sherpa,
    modality: .speechSynthesis,
    archiveType: .tarGz,
    memoryRequirement: 65_000_000
)

_ = try await RunAnywhere.downloadModel(voice) { progress in
    print("Downloading: \(Int(progress.overallProgress * 100))%")
}

var load = RAModelLoadRequest()
load.modelID = voice.id
load.category = .speechSynthesis

let result = await RunAnywhere.loadModel(load)
guard result.success else {
    print("Load failed: \(result.errorMessage)")
    return
}

The vits-piper-* archives published under the RunAnywhere sherpa-onnx release tag are the set the iOS example app ships with. Any Piper VITS archive with the same layout works the same way.

Selecting a system voice

Nothing to load. Set voice to an AVSpeechSynthesisVoice identifier or a language code, then call speak.

var options = RATTSOptions.defaults()
options.voice = "com.apple.ttsbundle.Samantha-compact"
options.languageCode = "en-US"

_ = try await RunAnywhere.speak("Hello from the system voice.", options: options)

Resolution order for voice on the system path: an exact voice identifier, then a language code, then languageCode as a fallback. Leaving voice empty, or setting it to "system" or "system-tts", picks the default voice for languageCode. Enumerate what the device offers with AVSpeechSynthesisVoice.speechVoices().

Enumerating engine voices

The loaded engine can report the voices it exposes. This lives on the bridge layer rather than the RunAnywhere facade.

let list = try CppBridge.TTS.shared.listVoices()
for voice in list.voices {
    print("\(voice.id): \(voice.displayName) [\(voice.languageCode)]")
}

RATTSVoiceInfo fields: id, displayName, languageCode, gender, description_p, isNeural, isSystem, sampleRate, supportedStyles.

Checking and unloading

var query = RACurrentModelRequest()
query.category = .speechSynthesis
let current = RunAnywhere.currentModel(query)

if current.found {
    print("Current voice model: \(current.modelID)")
}

var unload = RAModelUnloadRequest()
unload.category = .speechSynthesis
_ = await RunAnywhere.unloadModel(unload)

Voice picker

struct VoicePickerView: View {
    @State private var voices: [RAModelInfo] = []
    @State private var selectedID: String?
    @State private var isLoading = false

    var body: some View {
        VStack(spacing: 20) {
            Picker("Voice", selection: $selectedID) {
                ForEach(voices, id: \.id) { voice in
                    Text(voice.name).tag(Optional(voice.id))
                }
            }
            .pickerStyle(.wheel)

            Button {
                Task { await apply() }
            } label: {
                HStack {
                    if isLoading { ProgressView().scaleEffect(0.8) }
                    Text(isLoading ? "Loading" : "Apply")
                }
            }
            .disabled(isLoading || selectedID == nil)

            Button("Preview") {
                Task { _ = try? await RunAnywhere.speak("This is a preview of the selected voice.") }
            }
            .disabled(isLoading)
        }
        .padding()
        .task {
            var query = RAModelQuery()
            query.category = .speechSynthesis
            let listed = await RunAnywhere.queryModels(query)
            voices = listed.models.models
        }
    }

    func apply() async {
        guard let selectedID else { return }
        isLoading = true
        defer { isLoading = false }

        var load = RAModelLoadRequest()
        load.modelID = selectedID
        load.category = .speechSynthesis

        let result = await RunAnywhere.loadModel(load)
        if !result.success {
            print("Failed to load voice: \(result.errorMessage)")
        }
    }
}

Per-voice settings

Rate, pitch, and volume live on RATTSOptions, so they apply per call rather than per voice. Keep your own table if you want each voice to sound consistent.

struct VoiceSettings {
    var speakingRate: Float = 1.0
    var pitch: Float = 1.0
    var volume: Float = 1.0
}

@MainActor
final class VoiceManager {
    private let settings: [String: VoiceSettings] = [
        "vits-piper-en_US-lessac-medium": VoiceSettings(speakingRate: 0.95),
        "vits-piper-en_GB-alba-medium": VoiceSettings(speakingRate: 1.0, pitch: 0.95),
    ]

    func speak(_ text: String) async throws {
        var query = RACurrentModelRequest()
        query.category = .speechSynthesis
        let current = RunAnywhere.currentModel(query)

        let voiceSettings = settings[current.modelID] ?? VoiceSettings()

        var options = RATTSOptions.defaults()
        options.speakingRate = voiceSettings.speakingRate
        options.pitch = voiceSettings.pitch
        options.volume = voiceSettings.volume

        _ = try await RunAnywhere.speak(text, options: options)
    }
}

Switching voices mid-session

Loading a different model under .speechSynthesis replaces the active one.

@MainActor
final class MultiVoiceNarrator {
    let assignments = [
        "narrator": "vits-piper-en_US-lessac-medium",
        "character": "vits-piper-en_GB-alba-medium",
    ]

    func speak(as role: String, text: String) async throws {
        guard let modelID = assignments[role] else { return }

        var query = RACurrentModelRequest()
        query.category = .speechSynthesis

        if RunAnywhere.currentModel(query).modelID != modelID {
            var load = RAModelLoadRequest()
            load.modelID = modelID
            load.category = .speechSynthesis
            guard await RunAnywhere.loadModel(load).success else { return }
        }

        _ = try await RunAnywhere.speak(text)
    }
}

Swapping models costs a load. For back-and-forth dialogue, batch the lines per speaker.

Best practices

Preload voices

Download and load during onboarding so the first speak() is not waiting on a model read.

Persist the selection

Save the chosen model ID and reload it at launch.

Fall back to system voices

System voices need no download and are always present. Fall back to speak() with a system voice identifier when a neural voice fails to load.

synthesize()

Basic synthesis

Streaming TTS

Stream long text

Getting Started

Swift SDK

Kotlin SDK

React Native SDK

Flutter SDK

Web SDK

Vibe Coding

Voice sources

Loading a neural voice

Selecting a system voice

Enumerating engine voices

Checking and unloading

Voice picker

Per-voice settings

Switching voices mid-session

Best practices

synthesize()

Streaming TTS

​Voice sources

​Loading a neural voice

​Selecting a system voice

​Enumerating engine voices

​Checking and unloading

​Voice picker

​Per-voice settings

​Switching voices mid-session

​Best practices

synthesize()

Streaming TTS

Voice sources

Loading a neural voice

Selecting a system voice

Enumerating engine voices

Checking and unloading

Voice picker

Per-voice settings

Switching voices mid-session

Best practices