back
loading skill details...
Use this skill whenever the user wants to convert text into speech, generate audio from text, or produce voiceovers. Triggers include: any mention of 'TTS',…
tts
Convert any text into speech audio. Supports two backends (Kokoro local, Noiz cloud), two modes (simple or timeline-accurate), and per-segment voice control.
Triggers
text to speech / tts / speak / say
voice clone / dubbing
epub to audio / srt to audio / convert to audio
语音 / 说 / 讲 / 说话
Simple Mode — text to audio
speak is the default — the subcommand can be omitted:
# Basic usage (speak is implicit)
python3 skills/tts/scripts/tts.py -t "Hello world" # add -o path to save
python3 skills/tts/scripts/tts.py -f article.txt -o out.mp3
# Voice cloning — local file path or URL
python3 skills/tts/scripts/tts.py -t "Hello" --ref-audio ./ref.wav
python3 skills/tts/scripts/tts.py -t "Hello" --ref-audio https://example.com/my_voice.wav -o clone.wav
# Voice message format
python3 skills/tts/scripts/tts.py -t "Hello" --format opus -o voice.opus
python3 skills/tts/scripts/tts.py -t "Hello" --format ogg -o voice.ogg
Third-party integration (Feishu/Telegram/Discord) is documented in ref_3rd_party.md.
Timeline Mode — SRT to time-aligned audio
For precise per-segment timing (dubbing, subtitles, video narration).
Step 1: Get or create an SRT
If the user doesn't have one, generate from text:
python3 skills/tts/scripts/tts.py to-srt -i article.txt -o article.srt
python3 skills/tts/scripts/tts.py to-srt -i article.txt -o article.srt --cps 15 --gap 500
--cps = characters per second (default 4, good for Chinese; ~15 for English). The agent can also write SRT manually.
Step 2: Create a voice map
JSON file controlling default + per-segment voice settings. segments keys support single index "3" or range "5-8".
Kokoro voice map:
{
"default": { "voice": "zf_xiaoni", "lang": "cmn" },
"segments": {
"1": { "voice": "zm_yunxi" },
"5-8": { "voice": "af_sarah", "lang": "en-us", "speed": 0.9 }
}
}
Noiz voice map (adds emo, reference_audio support). reference_audio can be a local path or a URL (user’s own audio; Noiz only):
{
"default": { "voice_id": "voice_123", "target_lang": "zh" },
"segments": {
"1": { "voice_id": "voice_host", "emo": { "Joy": 0.6 } },
"2-4": { "reference_audio": "./refs/guest.wav" }
}
}
Dynamic Reference Audio Slicing:
If you are translating or dubbing a video and want each sentence to automatically use the audio from the original video at the exact same timestamp as its reference audio, use the --ref-audio-track argument instead of setting reference_audio in the map:
python3 skills/tts/scripts/tts.py render --srt input.srt --voice-map vm.json --ref-audio-track original_video.mp4 -o output.wav
See examples/ for full samples.
Step 3: Render
python3 skills/tts/scripts/tts.py render --srt input.srt --voice-map vm.json -o output.wav
python3 skills/tts/scripts/tts.py render --srt input.srt --voice-map vm.json --backend noiz --auto-emotion -o output.wav
When to Choose Which
Need
Recommended
Just read text aloud, no fuss
Kokoro (default)
EPUB/PDF audiobook with chapters
Kokoro (native support)
Voice blending ("v1:60,v2:40")
Kokoro
Voice cloning from reference audio
Noiz
Emotion control (emo param)
Noiz
Exact server-side duration per segment
Noiz
When the user needs emotion control + voice cloning + precise duration together, Noiz is the only backend that supports all three.
Guest Mode (no API key)
When no API key is configured, tts.py automatically falls back to guest mode — a limited Noiz endpoint that requires no authentication. Guest mode only supports --voice-id, --speed, and --format; voice cloning, emotion, duration, and timeline rendering are not available.
# Guest mode (auto-detected when no API key is set)
python3 skills/tts/scripts/tts.py -t "Hello" --voice-id 883b6b7c -o hello.wav
# Explicit backend override to use kokoro instead
python3 skills/tts/scripts/tts.py -t "Hello" --backend kokoro
Available guest voices (15 built-in):
voice_id
name
lang
gender
tone
063a4491
販売員(なおみ)
ja
F
喜び
4252b9c8
落ち着いた女性
ja
F
穏やか
578b4be2
熱血漢(たける)
ja
M
怒り
a9249ce7
安らぎ(みなと)
ja
M
穏やか
f00e45a1
旅人(かいと)
ja
M
穏やか
b4775100
悦悦|社交分享
zh
F
Joyful
77e15f2c
婉青|情绪抚慰
zh
F
Calm
ac09aeb4
阿豪|磁性主持
zh
M
Calm
87cb2405
建国|知识科普
zh
M
Calm
3b9f1e27
小明|科技达人
zh
M
Joyful
95814add
Science Narration
en
M
Calm
883b6b7c
The Mentor (Alex)
en
M
Joyful
a845c7de
The Naturalist (Silas)
en
M
Calm
5a68d66b
The Healer (Serena)
en
F
Calm
0e4ab6ec
The Mentor (Maya)
en
F
Calm
Security & data disclosure
This skill performs the following file and network operations at runtime:
Credential storage: When you run config --set-api-key, the key is saved to ~/.config/noiz/api_key (permissions 0600). The NOIZ_API_KEY environment variable is also supported as an alternative.
Legacy key migration: If ~/.noiz_api_key exists and ~/.config/noiz/api_key does not, the key is copied (not deleted) to the new location. A message is printed; the old file is left untouched for you to remove manually.
Network calls (Noiz backend): Text and optional reference audio are uploaded to https://noiz.ai/v1/ for synthesis. No data is sent unless you invoke a Noiz command.
Reference audio download: When --ref-audio is a URL, the file is downloaded to a temp file, used for the API call, then deleted. If no voice-id or ref-audio is provided, a default reference audio is downloaded from storage.googleapis.com or noiz.ai.
Temp files: Temporary audio/text files may be created during synthesis and are cleaned up after use.
ffmpeg: Invoked only in timeline render mode to assemble the final audio.
No files outside the output path and ~/.config/noiz/ are modified. The Kokoro backend runs entirely offline with no network access.
Requirements
ffmpeg in PATH (timeline mode only)
requests package: uv pip install requests (required for Noiz backend)
Get your API key at Noiz Developer, then run python3 skills/tts/scripts/tts.py config --set-api-key YOUR_KEY (guest mode works without a key but has limited features)
Kokoro: if already installed, pass --backend kokoro to use the local backend
Noiz API authentication
Use only the base64-encoded API key as Authorization—no prefix (e.g. no APIKEY or Bearer ). Any prefix causes 401.
For backend details and full argument reference, see reference.md.don't have the plugin yet? install it then click "run inline in claude" again.