tts-skill

name	tts-skill
description	Generate cloned narration for the content workspace. Use local IndexTTS2 with the canonical lossless Pluviobyte reference for every local video, voice audition, digital-human narration, and subtitle-ready audio render. Preserve MiniMax only for public-facing articles or tutorials that teach users to connect through the relay service; never use MiniMax for local video production.

TTS Skill

Route every request into exactly one lane.

Hard Routing Rules

1. For local video production, use local IndexTTS2 only. Do not call MiniMax, even when MiniMax credentials exist in .env.
2. Use voice id pluvio-indextts2-calm-v1 and the canonical lossless WAV in automation/config/tts-routing.json. Never use an MP3 as the speaker reference and never replace the canonical reference with the latest output; that would accumulate cloning drift.
3. Generate the locked narration as lossless WAV. MP3 may be emitted only as a portable audition copy, never as the source for another clone or for final subtitle timing.
4. Apply the default_delivery.playback_speed declared in automation/config/tts-routing.json to every audition and final WAV. The production default is 1.12x, implemented with FFmpeg atempo so pitch is preserved. Record the effective multiplier in voice_manifest.json.
5. Do not silently fall back to macOS say, browser speech, MiniMax, or another generic/cloud voice. If IndexTTS2, its model weights, Apple MPS/CPU, or the canonical reference is unavailable, repair the local lane or stop.
6. Every final narration render must leave voice_manifest.json with provider, voice id, model, canonical reference path and SHA-256, segment contract, output path, and used_fallback=false.
7. TTS segment durations are planning metadata only. Run ra-audio-to-subtitles against the exact concatenated lossless narration and use its word timestamps for final captions.
8. For digital-human production, treat the full narration as an audition until the user explicitly approves that exact audio version. Do not describe an unapproved audition as locked or forward it to HeyGen.
9. Before every local audition or final render, enforce references/pronunciation-lexicon.json. A user-approved pronunciation in that file overrides generic phonetic heuristics. Keep the display spelling separate from TTS text when needed, and stop rather than render a forbidden spelling.

Local Video Lane: IndexTTS2

Read the machine-readable route from:

automation/config/tts-routing.json

Generate a narration from a JSONL segment contract with:

python3 .claude/skills/tts-skill/scripts/generate_indextts2_narration.py \
  --batch-file <segments.jsonl> \
  --output <final-narration.wav> \
  --manifest <voice_manifest.json>

Each non-empty JSONL line must follow the official IndexTTS2 batch contract and contain text; it may also contain emotion_vector, emotion_weight, and silence_after_ms. Default to a calm delivery. Add stronger emotion only when the user explicitly asks for it.

Run --dry-run before a new contract or after changing the local model setup. The helper verifies that the canonical speaker reference is a lossless PCM WAV, invokes the official local IndexTTS2 CLI, normalizes the result, and writes the manifest. Keep the raw WAV beside the normalized WAV for auditability.

For mixed Chinese/English scripts, inspect model names, brands, abbreviations, and numbers before the full render. Load references/pronunciation-lexicon.json first. Entries there are approved production contracts: use their tts value exactly and reject every forbidden_tts form. In particular, keep Codex as the raw English token; never transliterate it as “扣代克斯”, “扣戴克斯”, or “扣德克斯”. For a term that is not yet in the lexicon, audition alternatives while keeping canonical spelling in the display script and final captions. After the user chooses, record that decision in the lexicon before the full render.

Public Article Lane: MiniMax Relay

MiniMax is retained only as the public solution used in articles, tutorials, course examples, and relay-station onboarding. It is not a local production provider. When this lane is requested, read references/minimax-relay-article.md and use assets/minimax_tts.py only for the article/demo example.

QC

Before using narration in a final video:

• confirm provider is IndexTTS2/indextts2-local
• confirm voice_id is pluvio-indextts2-calm-v1
• confirm the reference SHA-256 matches the routing config
• confirm the recommended output is PCM WAV and decodes successfully
• confirm playback_speed is 1.12 unless the production contract explicitly overrides the workspace default
• confirm used_fallback=false and no segment provider is MiniMax
• confirm the pronunciation contract is present in voice_manifest.json and the approved mixed-language terms were used
• generate captions from that exact WAV and require caption-qc.json PASS
• for a digital human, require explicit user approval of the exact audition WAV before any paid avatar generation; changing the audio invalidates approval