TTS

Convert text to natural-sounding speech — quick single-voice narration or smart multi-speaker dialogue from a script.

Convert text or URL content into natural-sounding speech audio. The skill picks one of two paths based on what you give it: a single voice reading straight through, or multiple speakers voicing a script you mark up line by line.

Trigger

Invoke this skill with /tts, or use any of these phrases:

Phrase	Language
`read aloud` / `read this aloud`	English
`TTS` / `text to speech`	English
`voice narration`	English
`朗读这段`	Chinese
`配音` / `语音合成`	Chinese

Requires ListenHub Skills to be installed — see Getting Started.

Quick Example

Read this article aloud: https://en.wikipedia.org/wiki/Podcast

The skill fetches the content, picks a voice, and generates natural speech audio.

Quick vs Script Mode

The skill decides between two modes before it asks you anything. Both produce an MP3 you can stream or download; they differ in how many voices they use and how much control you have over each line.

	Quick mode	Script mode
CLI flag	`--mode direct`	`--mode smart`
Voices	One	One per character
Speed	Fast, low-latency (~1–2 min)	Moderate (~2–3 min)
Best for	Reading an article, casual TTS, a single narrator	Dialogue, audiobooks, scripted multi-character content
Control	Reads the text as one block	Each segment is voiced by the speaker you assign

Quick mode takes a block of text (or a URL) and reads it straight through with one voice. It runs synchronously and returns an audio link quickly.

Script mode takes a script where each line is tagged with a speaker, assigns a distinct voice per character, and stitches the segments into one track. Longer scripts run in the background — the skill submits the job and polls until it completes.

The CLI's tts create command defaults to --mode smart. The skill chooses the flag for you from the mode detection below, so you rarely set it by hand.

How the Mode Is Detected

The skill reads your request and routes to a mode automatically, before asking any questions:

Signal in your input	Mode
"多角色", "脚本", "对话", "script", "dialogue", "multi-speaker"	Script
Multiple characters named or described by role	Script
Structured segments like `A: ...` / `B: ...`	Script
A single paragraph of text, no character markers	Quick
"read this", "TTS", "朗读" with plain text	Quick
Ambiguous	Quick (default)

If the routing looks wrong, say so — for example, "do this as a multi-speaker script" — and the skill switches modes.

Writing a Script (Script mode)

In Script mode you provide the lines with a speaker on each one. The simplest format is one line per turn, Speaker: text:

Alex: Hello everyone, welcome to the show.
Sam: Thanks for having me!
Alex: Let's get into today's topic.

The skill parses each Speaker: marker into a segment, collects the unique characters (Alex, Sam), and assigns a voice to each. Markers carry through to the underlying /v1/flow-speech/episodes/tts request, which also accepts an explicit scripts array if you call the API directly:

{
  "scripts": [
    { "content": "Hello everyone, welcome to the show.", "speakerId": "cozy-man-english" },
    { "content": "Thanks for having me!", "speakerId": "travel-girl-english" }
  ]
}

Each segment is spoken by its assigned speaker, in order.

Script tips

Break at natural speech boundaries — one sentence or short paragraph per line.
Alternate speakers for a dialogue feel.
Keep all speakers in the same language.
If you call the API directly, each speakerId must be a valid ID from the speakers endpoint.

Voice Selection and Saved Preferences

You do not have to choose a voice. The skill follows this order:

Saved preference. If you have a default voice saved for the detected language, the skill uses it silently.

Built-in default. Otherwise it falls back to a built-in default voice for that language — for English, a neutral narrator; for Chinese, a primary and secondary voice for multi-character scripts.

Explicit change. Only if you ask to change the voice does the skill show you the speaker list and let you pick.

When you pick a new voice (not when a default is used), the skill offers to remember it:

Quick mode — "Save this as your default voice for {language}?"
Script mode — "Save these voice assignments for future sessions?"

Saved preferences live in .listenhub/tts/config.json in the working directory, under defaultSpeakers keyed by language. Quick mode stores a single voice; Script mode stores the full set of voices assigned that session. Choosing "No" uses the voice for the current run only and leaves the config untouched.

Preferences are per working directory. Run the skill in a different project and you start from the built-in defaults again.

Parameters

Parameter	Options	Default
Input	Text or URL	—
Mode	`direct` (Quick), `smart` (Script)	Auto-detected
Language	`en`, `zh`, `ja`	Auto-detected from the text
Speaker	Speaker name or `speakerId`	Saved preference, else built-in default

When to Use TTS vs Podcast

Both skills can produce multi-speaker audio, but they serve different purposes:

Use case	Skill
Topic-based discussion with natural conversation flow	Podcast
Precise control over every line and speaker	TTS (Script mode)
Reading an article or text aloud	TTS (Quick mode)

Limits

FlowTTS text input: max 10,000 characters.
For longer content, pass a URL instead — the API fetches and processes it automatically.
Plain text sources must be at least 10 characters.

Credits

Generation consumes credits. Costs depend on length, mode, and voice, so check the relevant estimate-credits endpoint before a large job rather than assuming a fixed price. See the FlowSpeech API reference for the estimation endpoints.

Output

After generation:

Listen link — stream the audio on ListenHub.
Subtitles — Script mode also returns a subtitles URL when available.
Download — say "download audio" to save the MP3 to the current directory with a topic-based filename.

TTS