agentleFS
godot-fungodot-fun/godot-agent/.agents/skills/ai-text-to-speech/SKILL.md

ai-text-to-speech

Skill210 starsChanged 2 days agoMITView on GitHub

Zero-shot text-to-speech with voice cloning via IndexTTS2 (index-tts). Synthesizes speech from text using a user-provided reference audio for timbre. Use when the user wants TTS, text-to-speech, voice cloning, voice clone, IndexTTS, IndexTTS2, or generating narration/voice lines from a reference WAV.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 0 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    When this skill applies, read and follow dependency-manager — run scripts as documented, install missing tools into .dependency/.

    line 16
  2. Very specific:

    Run tts.py at .ai/ai-text-to-speech/tts.py through the index-tts manifest entry (.dependency/index-tts/.venv/).

    line 18
  3. Very specific:

    Do not hand-write IndexTTS Python snippets or uv run webui.py for synthesis — use the bundled script.

    line 19
  4. Very specific:

    Ensure python-3.11 and uv are populated under .dependency/ (see dependency-manager).

    line 30
  5. Very specific:

    Use python / uv (no .exe) on Unix.

    line 43
  6. Very specific:

    If HuggingFace is slow: HF_ENDPOINT=https://hf-mirror.com (Unix) / $env:HF_ENDPOINT="https://hf-mirror.com" (PowerShell).

    line 85
  7. Very specific:

    Use .dependency/index-tts/.venv/bin/python on Unix.

    line 96
  8. Very specific:

    Do not combine --emotion-audio, --emotion-vector, and --emotion-text / --emotion-from-text in conflicting ways — pick one emotion source.

    line 170

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

AI Text-to-Speech (IndexTTS2)

Clone a speaker from a reference audio, then synthesize speech from text with IndexTTS2.

Rules

When this skill applies, read and follow dependency-manager — run scripts as documented, install missing tools into .dependency/.

  • Run tts.py at .ai/ai-text-to-speech/tts.py through the index-tts manifest entry (.dependency/index-tts/.venv/). Never use host python, py, python3, or any interpreter outside .dependency/.
  • Do not hand-write IndexTTS Python snippets or uv run webui.py for synthesis — use the bundled script.
  • IndexTTS requires uv for install (pip/conda are unsupported upstream). Python must be >=3.10,<3.12 (use python-3.11).
  • populated: false for index-tts (or missing models) is not a reason to skip. Install / download first, set populated: true, retry the same command.
  • Never overwrite sources. Pass the user's real voice path and text; write only to -o / --output.

Setup (first run)

From project root.

1. Python 3.11 + uv

Ensure python-3.11 and uv are populated under .dependency/ (see dependency-manager). Register:

"python-3.11": {
  "populated": true,
  "bin": ".dependency/python-3.11/python.exe"
},
"uv": {
  "populated": true,
  "bin": ".dependency/uv/uv.exe"
}

Use python / uv (no .exe) on Unix.

2. Clone IndexTTS

git clone https://github.com/index-tts/index-tts.git .dependency/index-tts
cd .dependency/index-tts
git lfs install
git lfs pull

3. Install deps with uv (required)

# from .dependency/index-tts
# Windows: skip deepspeed extras if install fails
.dependency/uv/uv.exe sync --extra webui

Slow PyPI (China mirrors):

.dependency/uv/uv.exe sync --extra webui --default-index "https://mirrors.aliyun.com/pypi/simple"

CUDA Toolkit 12.8+ is needed for GPU. CPU works but is slow.

4. Download IndexTTS-2 checkpoints

cd .dependency/index-tts
.dependency/uv/uv.exe tool install "huggingface-hub[cli,hf_xet]"
hf download IndexTeam/IndexTTS-2 --local-dir=checkpoints

Or ModelScope:

.dependency/uv/uv.exe tool install "modelscope"
modelscope download --model IndexTeam/IndexTTS-2 --local_dir checkpoints

If HuggingFace is slow: HF_ENDPOINT=https://hf-mirror.com (Unix) / $env:HF_ENDPOINT="https://hf-mirror.com" (PowerShell).

5. Register manifest

"index-tts": {
  "populated": true,
  "bin": ".dependency/index-tts/.venv/Scripts/python.exe"
}

Use .dependency/index-tts/.venv/bin/python on Unix. Confirm checkpoints/config.yaml exists before synthesizing.

Quick Start

Voice reference + text → WAV (default output: <voice-dir>/ai-text-to-speech/<voice-stem>.wav):

.dependency/index-tts/.venv/Scripts/python.exe .ai/ai-text-to-speech/tts.py \
  --voice audio/voice/ref.wav \
  --text "Hello, welcome to this world."
# → audio/voice/ai-text-to-speech/ref.wav

Explicit output path:

.dependency/index-tts/.venv/Scripts/python.exe .ai/ai-text-to-speech/tts.py \
  --voice audio/voice/ref.wav \
  --text "Hello, this is a test." \
  --output audio/voice/ai-text-to-speech/hello.wav

Directory (writes <voice-stem>.wav inside, e.g. audio/voice/ai-text-to-speech/ref.wav):

.dependency/index-tts/.venv/Scripts/python.exe .ai/ai-text-to-speech/tts.py --voice audio/voice/ref.wav --text "Hello, this is a test." --output audio/voice/ai-text-to-speech

Long script from a UTF-8 text file:

.dependency/index-tts/.venv/Scripts/python.exe .ai/ai-text-to-speech/tts.py \
  --voice audio/voice/ref.wav \
  --text-file script/lines/intro.txt \
  --output audio/voice/ai-text-to-speech/intro.wav

FP16 (faster, less VRAM):

.dependency/index-tts/.venv/Scripts/python.exe .ai/ai-text-to-speech/tts.py \
  --voice audio/voice/ref.wav \
  --text "Testing half-precision inference." \
  --fp16

Emotion control (optional)

ModeFlagsNotes
Emotion reference audio--emotion-audio path.wavSeparate clip for emotion; timbre still from --voice
Emotion weight--emotion-weight 0.6Maps to emo_alpha (0.0–1.0, default 1.0)
Emotion from text--emotion-from-textInfer emotion from synthesis text; prefer --emotion-weight ≈ 0.6
Emotion description--emotion-text "..."Natural-language emotion; implies text emotion mode
Emotion vector--emotion-vector 0,0,0.8,0,0,0,0,08 floats: happy, angry, sad, afraid, disgusted, melancholic, surprised, calm
# Emotion reference audio
.dependency/index-tts/.venv/Scripts/python.exe .ai/ai-text-to-speech/tts.py \
  --voice audio/voice/ref.wav \
  --emotion-audio audio/voice/emo_sad.wav \
  --emotion-weight 0.9 \
  --text "The inn has gone rotten and started auctioning off rooms." \
  --output audio/voice/ai-text-to-speech/sad_line.wav

# Emotion description text
.dependency/index-tts/.venv/Scripts/python.exe .ai/ai-text-to-speech/tts.py \
  --voice audio/voice/ref.wav \
  --emotion-text "afraid, tense" \
  --emotion-weight 0.6 \
  --text "Hide quickly! He is coming!" \
  --output audio/voice/ai-text-to-speech/afraid_line.wav

Do not combine --emotion-audio, --emotion-vector, and --emotion-text / --emotion-from-text in conflicting ways — pick one emotion source.

Defaults

OptionDefaultNotes
Output<voice-dir>/ai-text-to-speech/<voice-stem>.wav--output file uses that name; --output directory uses the voice file's stem
Model.dependency/index-tts/checkpointsIndexTTS-2
--fp16offEnable on GPU when VRAM is tight
--emotion-weight1.0Lower (~0.6) for text emotion modes
OverwriteoffPass --force to replace an existing output

Agent workflow

  1. Confirm inputs — need a clear reference voice WAV/MP3 and the text (or --text-file). Ask if either is missing.
  2. Use the user's real paths — do not copy voice files into the repo unless asked.
  3. Trial first — synthesize one short line, play/inspect before long scripts.
  4. Reference audio tips — clean, single-speaker, little noise; a few seconds of clear speech works best.
  5. Missing install — follow Setup; register index-tts in manifest.json; retry the same command.
  6. GPU — prefer CUDA + --fp16 for speed; CPU is acceptable for short tests only.
  7. Revert — delete files under ai-text-to-speech/; sources are never modified.

Troubleshooting

IssueFix
index-tts not populatedClone + uv sync + download checkpoints; update manifest
checkpoints/config.yaml missingRe-run hf download IndexTeam/IndexTTS-2 --local-dir=checkpoints
CUDA / torch errorsInstall CUDA 12.8+; or run on CPU (slow)
OOM / VRAMPass --fp16; shorten text; close other GPU apps
Slow HuggingFaceSet HF_ENDPOINT=https://hf-mirror.com; or use ModelScope
uv sync / DeepSpeed fail on WindowsUse uv sync --extra webui without deepspeed
Unnatural emotionLower --emotion-weight to ~0.6; try a clearer --emotion-audio

CLI

Copy-paste commands: cli/ai-text-to-speech.md

Related

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.