TTS (Text-to-Speech)¶

On-device neural speech. Two model families — NeuTTS and Qwen3-TTS — behind one API, producing 24 kHz mono float PCM you can play, save, or stream. Voices swap at runtime without reloading the model, and your own speaker can ship as a small voice pack.

Use it two ways: synthesise a string and get audio back, or open a stream and hear the first words while the rest is still being made.

Main features

Two families, one API: NeuTTSMultilingualPipeline and Qwen3TTSPipeline share infer / open_stream / set_voice.
Streaming: push text in — whole sentences or LLM tokens — and drain audio as it is synthesised. First audio in tens of milliseconds.
Voice hot-swap: set_voice(voice_id:) changes speaker or language on a live pipeline, no engine reload.
Your own voice: encode a 3-second reference clip into a voice pack and ship it with the app.
Nine languages, one speaker (NeuTTS): english, french, german, spanish, portuguese, japanese, korean, chinese, urdu.
Any output rate: 24 kHz native, resampled once to 16 / 48 kHz if your audio session needs it.
A player is included: AudioStreamPlayer / TSAudioPlayer accept exactly this PCM.

In this page ¶

Here we will cover the following topics:

Supported models: the two families, their voices and languages, and how to pick.
Quick start: speak a string, or stream it — Swift and Flutter side by side.
Synthesise speech: the batch call, output format, and the sampling knobs.
Stream speech: push text, drain audio, and the chunking knobs.
Voices and languages: bundle voices, language override, your own voice pack.
Result object: TTSResult and stream chunk fields.
Usage Guides: read notifications aloud, speak an LLM reply, a multilingual tutor, a brand voice, wrong playback speed, slow first audio.
Troubleshooting: symptom → cause → fix.
Load Progress / Prefetch / Cleanup: first-run download, warming the cache, releasing models.

Supported models ¶

Two families. Both produce 24 kHz mono float and accept the same calls; they differ in size, languages and voice character.

Model	HF repo	Family	Device	Fleet pin
NeuTTS nano multilingual	`TheStageAI/neutts-nano-multilingual`	NeuTTS	NPU	v1.1
Qwen3-TTS 12 Hz 0.6B	`TheStageAI/Qwen3-TTS-12Hz-0.6B-Base`	Qwen3	NPU	v1.1

Feature	NeuTTS nano	Qwen3-TTS
Bundle voices	`paul`, `dave`, `jo`	`b_ref`
Languages	english, french, german, spanish, portuguese, japanese, korean, chinese, urdu — one speaker across all	follows the voice pack
Own voice from a clip	yes (3–10 s reference)	yes (2–4 s reference)
Streaming	yes	yes
Voice Agent TTS	yes	yes

Which one?

You need…	Pick	Why
Lowest latency and footprint	NeuTTS nano	Smallest model; fastest first audio.
The same speaker in several languages	NeuTTS nano	`set_voice(language:)` keeps the speaker and switches phonemes.
Most natural prosody for long narration	Qwen3-TTS	Larger talker model; better on long sentences.
A voice cloned from a very short clip	Qwen3-TTS	Clones from ~3 s of reference audio.

Quick start ¶

Two ways to get audio. Batch when you already have the whole string and a second of latency is fine; stream when the user is waiting to hear it.

You want	Latency	Use
Audio for a string you already have	the whole clip at once	`infer(text:)`
Audio that starts before the text is finished	first chunk in milliseconds	`open_stream` / `TTSStream.open`

Speak a string ¶

Swift

import TheStageSDK

try await TheStageAI.shared.initialize(api_token: "your-api-token")

let tts = try await NeuTTSMultilingualPipeline(
    engines_path: "TheStageAI/neutts-nano-multilingual",
    voice_id: "dave",
    language: "english"
)

let result = tts.infer(text: "Hello from TheStage.")
// result.samples: [Float] mono in [-1, 1], result.sample_rate == 24000

let player = AudioStreamPlayer(
    config: AudioStreamConfig(sample_rate: Double(result.sample_rate))
)
player.start()
player.enqueue(result.samples)
await player.drain()
player.stop()

Flutter

import 'package:thestage_apple_sdk/thestage_apple_sdk.dart';

await TheStageFlutterSDK.initialize(api_token: 'your-api-token');
await TheStageFlutterSDK.start_model(
  model_name: 'tts',
  engines_path: 'TheStageAI/neutts-nano-multilingual',
  config: {'voice_id': 'dave', 'language': 'english'},
);

final rows = await TheStageFlutterSDK.infer(
  model_name: 'tts',
  input_json: {'text': 'Hello from TheStage.'},
);
final audio = rows[0]['audio'] as Float32List;
// 24000
final rate  = rows[0]['sample_rate'] as int;

final player = TSAudioPlayer(sampleRate: rate);
await player.start();
player.enqueue(audio);
await player.drain();
await player.stop();

Stream it ¶

Swift

let tts = try await NeuTTSMultilingualPipeline(
    engines_path: "TheStageAI/neutts-nano-multilingual",
    voice_id: "dave",
    language: "english"
)

let player = AudioStreamPlayer(config: AudioStreamConfig(sample_rate: 24_000))
player.start()

let speech = tts.open_stream()
// drain BEFORE you send
let consumer = Task {
    for await chunk in speech.output {
        if let pcm = chunk.audio { player.enqueue(pcm) }
    }
}

speech.send("Hello from TheStage. ")
speech.send("This plays while the rest is still being made.")
// no more text
speech.close()
await consumer.value
await player.drain()
player.stop()

Flutter

await TheStageFlutterSDK.start_model(
  model_name: 'tts',
  engines_path: 'TheStageAI/neutts-nano-multilingual',
  config: {'voice_id': 'dave', 'language': 'english'},
);

final player = TSAudioPlayer(sampleRate: 24000);
await player.start();

final speech = await TTSStream.open(model_name: 'tts');
// listen BEFORE you send
final consumer = speech.output.listen((chunk) {
  final audio = chunk['audio'] as Float32List?;
  if (audio != null) player.enqueue(audio);
});

await speech.send('Hello from TheStage. ');
await speech.send('This plays while the rest is still being made.');
// no more text
await speech.close();
await consumer.asFuture();
await player.drain();
await player.stop();

Important API ¶

Purpose	Swift	Flutter
Load a model	`try await NeuTTSMultilingualPipeline(engines_path:voice_id:language:device:)` / `Qwen3TTSPipeline(engines_path:voice_id:device:)`	`start_model(model_name: 'tts', engines_path:, config: {voice_id, language})`
Speak a string	`tts.infer(text:config:)` → `TTSResult`	`infer(model_name: 'tts', input_json: {'text'})` → `rows[0]`
Stream	`tts.open_stream()` → `TTSStream`: `send` / `flush` / `close` / `cancel`, `output`	`TTSStream.open(model_name:)`: same methods, `output`
Change voice	`try tts.set_voice(voice_id:language:voice_dir:)`	`stop_model` + `start_model` with a new `config`
Play audio	`AudioStreamPlayer`: `start` / `enqueue` / `drain` / `stop`	`TSAudioPlayer`: same
Release	drop the pipeline	`stop_model(model_name: 'tts')`

Synthesise speech ¶

One string in, one clip out. Use it for notifications, short prompts, and anything you will play more than once — the result is plain PCM you can cache or write to a file.

Swift

let tts = try await NeuTTSMultilingualPipeline(
    engines_path: "TheStageAI/neutts-nano-multilingual",
    voice_id: "dave",
    language: "english"
)

var config = TTSGenerationConfig()
// match your audio session (optional)
config.sample_rate_out = 48_000
// calmer; omit for the pack default
config.temperature = 0.8

let result = tts.infer(text: "Your order has shipped.", config: config)

// Play, or keep it
try AudioIO.write_wav(
    samples: result.samples,
    sample_rate: result.sample_rate,
    path: cacheURL.appendingPathComponent("shipped.wav").path
)
print(result.duration, "s of audio in", result.rtf, "× real time")

Flutter

await TheStageFlutterSDK.start_model(
  model_name: 'tts',
  engines_path: 'TheStageAI/neutts-nano-multilingual',
  config: {'voice_id': 'dave', 'language': 'english'},
);

final rows = await TheStageFlutterSDK.infer(
  model_name: 'tts',
  input_json: {
    'text': 'Your order has shipped.',
    // match your audio session (optional)
    'sample_rate_out': 48000,
    // calmer; omit for the pack default
    'temperature': 0.8,
  },
);
final audio = rows[0]['audio'] as Float32List;
// 48000
final rate  = rows[0]['sample_rate'] as int;
// Play with TSAudioPlayer(sampleRate: rate), or persist the samples.

Output contract — mono float PCM in [-1, 1]. The codec is native 24 kHz; sample_rate_out resamples once on the way out. Whatever result.sample_rate says is the rate your player must run at.

Sampling options — TTSGenerationConfig. Omit everything for the pack’s tuned voice; reach for these with a specific goal.

Field	Default	Change it when
`temperature`	pack (≈ 0.9)	Lower to `0.7` for long narration with fewer artefacts; raise to `1.1` for an expressive character voice.
`top_k`	pack (≈ 50)	Lower to `25` with a low temperature for maximum stability.
`sample_rate_out`	24 000	Your `AVAudioSession` runs at 48 kHz, or the audio feeds ASR at 16 kHz. Saves a resample in your code.
`seed`	random	Golden-file tests. Same seed + same device + same pack → same PCM.
`return_debug_info`	false	Diagnosing an empty result.

Stream speech ¶

Streaming speech synthesis, span by span

A stream takes text in any size — whole paragraphs or one LLM token at a time — splits it into sentences internally, and emits audio chunks as each span is synthesised. The user hears the first words while the model is still working on the rest.

Swift

let llm = try await TSLLM(engines_path: "TheStageAI/Qwen3-0.6B")
let tts = try await NeuTTSMultilingualPipeline(
    engines_path: "TheStageAI/neutts-nano-multilingual",
    voice_id: "dave",
    language: "english"
)
let player = AudioStreamPlayer(config: AudioStreamConfig(sample_rate: 24_000))
player.start()
var llmConfig = llm.generation_defaults
llmConfig.enable_thinking = false

let speech = tts.open_stream(
    TTSGenerationConfig(),
    // faster first audio
    config: TTSStreamConfig(first_frames_per_chunk: 12)
)
let consumer = Task {
    for await chunk in speech.output {
        if let pcm = chunk.audio { player.enqueue(pcm) }
        if chunk.is_final { break }
    }
}

for await token in llm.infer_stream(prompt: question, config: llmConfig) {
    // tokens, not sentences
    if !token.is_final { speech.send(token.text) }
}
speech.close()
await consumer.value

Flutter

await TheStageFlutterSDK.start_model(
  model_name: 'llm',
  engines_path: 'TheStageAI/Qwen3-0.6B',
);
await TheStageFlutterSDK.start_model(
  model_name: 'tts',
  engines_path: 'TheStageAI/neutts-nano-multilingual',
  config: {'voice_id': 'dave', 'language': 'english'},
);
final player = TSAudioPlayer(sampleRate: 24000);
await player.start();

final speech = await TTSStream.open(
  model_name: 'tts',
  stream_config: const TTSStreamConfig(first_frames_per_chunk: 12),
);
final consumer = speech.output.listen((chunk) {
  final audio = chunk['audio'] as Float32List?;
  if (audio != null) player.enqueue(audio);
});

await for (final token in TheStageFlutterSDK.infer_stream(
  model_name: 'llm', input_json: {'prompt': question})) {
  if (token['is_final'] == true) break;
  // tokens, not sentences
  await speech.send(token['delta'] as String? ?? '');
}
await speech.close();
await consumer.asFuture();

Attention

Start draining output before the first send. If you send all the text first and read afterwards, the buffer fills and nothing plays.

Stream calls — TTSStream (Swift and Flutter):

Call	Use it to
`send(_:)`	Push text. Any size; sentence splitting is internal.
`flush()`	Speak what is buffered now, even a fragment without a full stop.
`close()`	No more text. `output` ends after the last chunk drains.
`cancel()`	Stop immediately — the user interrupted.

Chunking options — TTSStreamConfig. The defaults suit a voice assistant; touch these only for latency or seam quality.

Field	Default	Change it when
`first_frames_per_chunk`	25	Lower to `6`–`12` for faster first audio; the first chunk is shorter, later ones are normal.
`frames_per_chunk`	25	Raise if individual chunks sound thin.
`overlap_frames`	1	Raise to `2`–`3` if you hear clicks at chunk seams.
`lookforward` / `lookback`	5 / 50	Leave alone.

Voices and languages ¶

Three knobs compose, and they have the same names on the constructor and on set_voice: ``voice_id`` picks a speaker that ships in the pack; ``voice_dir`` points at an external voice pack (yours, or a downloaded one) and wins over voice_id; ``language`` switches phonemisation on NeuTTS while keeping the speaker.

Swift

// At load
let tts = try await NeuTTSMultilingualPipeline(
    engines_path: "TheStageAI/neutts-nano-multilingual",
    voice_id: "paul",
    language: "english"
)
// ["dave", "jo", "paul"]
print(tts.available_voices)

// At runtime — no engine reload
try tts.set_voice(voice_id: "dave")
try tts.set_voice(voice_id: "dave", language: "french")
// your own voice pack
try tts.set_voice(voice_dir: packURL.path)
// back to the bundle voice
try tts.set_voice(voice_dir: "")

Flutter

// Voice is fixed at load. To change it, stop and start again.
await TheStageFlutterSDK.stop_model(model_name: 'tts');
await TheStageFlutterSDK.start_model(
  model_name: 'tts',
  engines_path: 'TheStageAI/neutts-nano-multilingual',
  config: {
    'voice_id': 'dave',
    'language': 'french',
    // 'voice_dir': '/path/to/your/voice_pack',   // wins over voice_id
  },
);

Your own voice. A voice pack is a folder with one voice.json, produced from a short reference clip and its transcript with the public tools in the AppleSDK repo — see Ship a brand voice below.

Note

Inside the Voice Agent the same knobs are tts_voice, tts_voice_dir and tts_language on TSAgentConfig, and agent.set_voice(...) on Flutter — see Voice Agent.

Result object ¶

TTSResult is what infer returns; stream chunks carry the audio fields only.

Swift

let tts = try await NeuTTSMultilingualPipeline(
    engines_path: "TheStageAI/neutts-nano-multilingual",
    voice_id: "dave",
    language: "english"
)
let speech = tts.open_stream()
var config = TTSGenerationConfig()

let result = tts.infer(text: text, config: config)
// [Float], mono, [-1, 1]
result.samples
// 24000, or sample_rate_out
result.sample_rate
// seconds of audio
result.duration
// audio seconds per wall second
result.rtf

for await chunk in speech.output {
    // [Float]? — nil on the final marker
    chunk.audio
    // Int?
    chunk.sample_rate
    chunk.is_final
}

Flutter

await TheStageFlutterSDK.start_model(
  model_name: 'tts',
  engines_path: 'TheStageAI/neutts-nano-multilingual',
  config: {'voice_id': 'dave', 'language': 'english'},
);
final speech = await TTSStream.open(model_name: 'tts');

final r = rows[0];
// Float32List
r['audio'];
// 24000, or sample_rate_out
r['sample_rate'];
r['duration'];
r['rtf'];

speech.output.listen((chunk) {
  // Float32List? — null on the final marker
  chunk['audio'];
  chunk['sample_rate'];
  chunk['is_final'];
});

Swift	Flutter JSON	Meaning
`samples`	`audio`	The PCM.
`sample_rate`	`sample_rate`	Hz. Run the player at exactly this.
`duration`	`duration`	Seconds of audio produced.
`rtf`	`rtf`	Audio seconds per wall second. `2.5` means a 5 s clip took 2 s.
`prefill_seconds` / `decode_seconds` / `codec_seconds`	same	Where the time went.

Troubleshooting ¶

Symptom	Cause	Fix
Empty `samples`	Empty or whitespace text; unknown `voice_id`; called before load finished.	Check the text; `available_voices`; await the constructor.
Nothing plays while streaming	Consumer attached after `send`.	Drain `output` first.
Too fast / too slow	Player rate ≠ `sample_rate`.	Read the rate off the result.
Clicks between sentences	Chunk seams.	`overlap_frames: 2`–`3`.
Wrong pronunciation	`language` does not match the text (NeuTTS).	`set_voice(language:)`.
Slow first audio	Batch call, or large first chunk, or cold pipeline.	Stream; `first_frames_per_chunk: 8`; warm at launch.
Voice sounds like the default, not the pack	`voice_dir` path wrong or empty.	Pass an absolute folder path containing `voice.json`.
Flutter: voice did not change	Voice is fixed at `start_model`.	`stop_model` then `start_model` with the new config.

Load Progress / Prefetch / Cleanup ¶

First run downloads and prepares the pack; later runs hit the cache. Show progress the first time, warm the cache on a splash screen, and release models you are done with.

Swift

let ai = TheStageAI.shared

// Progress
let tts = try await NeuTTSMultilingualPipeline(
    engines_path: "TheStageAI/neutts-nano-multilingual",
    voice_id: "dave",
    on_load_progress: { p in
        print("[\(p.model)] \(p.phase) \(Int(p.fraction * 100))%")
    }
)

// Prefetch on a splash screen, construct later
let engines_dir = try await ai.prefetch_engines(
    repo_id: "TheStageAI/neutts-nano-multilingual")
let tts = try await NeuTTSMultilingualPipeline(
    engines_path: engines_dir, voice_id: "dave")

// Cleanup: drop the reference, or
_ = try ai.stop_model(model_name: "tts")

Flutter

// Progress
TheStageFlutterSDK.on_progress.listen((event) {
  if (event['model_name'] != 'tts') return;
  print('[tts] ${event['phase']} ${((event['progress'] ?? 0) * 100).round()}%');
});

await TheStageFlutterSDK.start_model(
  model_name: 'tts',
  engines_path: 'TheStageAI/neutts-nano-multilingual',
  config: {'voice_id': 'dave', 'language': 'english'},
);

// Cleanup
await TheStageFlutterSDK.stop_model(model_name: 'tts');

Phases: downloading → extracting → loading → ready. Cache hits skip the first two. Full contract: TheStage Apple SDK (Load Progress).

TTS (Text-to-Speech)¶

In this page ¶

Supported models ¶

Quick start ¶

Speak a string ¶

Stream it ¶

Important API ¶

Synthesise speech ¶

Stream speech ¶

Voices and languages ¶

Result object ¶

Usage Guides ¶

Read notifications aloud ¶

Speak an LLM reply as it is generated ¶

One tutor voice, several languages ¶

Ship a brand voice with the app ¶

Audio plays too fast, too slow, or clicks ¶

First audio takes too long ¶

Troubleshooting ¶

Load Progress / Prefetch / Cleanup ¶