SkillFoxx

tts-director skill

A skill that prepares a script for speech: it maps beats, rewrites for the ear and places ElevenLabs v3 and v4 tags on a budget.

  • 85 ★ on the repository
  • Last commit
  • MIT
Skill

Extended access

Why this level

  • The `ab.py` script sends text to ElevenLabs with your key and spends credits.
All reasons and checks

aligh98/tts-directorAuthor:aligh98

Install

In your terminal, with SkillFoxx CLI

npx skillfoxx add skills/tts-director

Detects the agents on your machine, shows the access level and pins the version.

Other ways to install

Access and checks

How we review

Extended accessThe tool runs code or makes network calls and only reads external data.

  • The `ab.py` script sends text to ElevenLabs with your key and spends credits.

This is third-party code. Review the repository files before installing.

What it does

tts-director is a skill that directs a script before text-to-speech so the voice sounds like an engaged human rather than a narrator. It is built Persian first and supports English. It targets ElevenLabs v3 and v4 audio tags and has notes for other TTS engines. The skill maps the beats of a video (hook, setup, list items, tip, joke, call to action), rewrites the script for the ear keeping every fact and places tags on a strict budget: about one tag per three or four sentences, up to two laughs per reel, a change of delivery every 8–12 seconds. A free linter catches over-tagging, written register and mistakes for the chosen model. `--approve` stamps the approved text, and `--check-approved` blocks generation until the text matches.

Who it is for. Creators of short videos and voiceovers who make reels and clips on ElevenLabs and want lively delivery without over-tagging.

Good fit when

  • A reel script goes into ElevenLabs v4 and the text must be rewritten for the ear.
  • Voiceover sounds like an ad because `[excited]` sits on every line.
  • Doubtful lines are tested on your own voice through A/B before spending credits.
  • The approved text must be stamped before generation so edits cannot skip the check.

Not a fit when

  • You need ready speech synthesis: the skill prepares text, and ElevenLabs voices it.
  • A different TTS platform without audio tags: the skill fits it poorly.
  • You cannot use an ElevenLabs key: A/B testing spends credits.

Example request

Rewrite this reel script for ElevenLabs v4 voiceover: map the beats, place tags on budget, run the linter and show the A/B plan.

Limitations

The scripts are plain Python 3.9 or newer with no dependencies, and `ffmpeg` is optional. The `tag_lint.py` linter is free, while `ab.py` sends text to ElevenLabs and spends credits, with the key set in `ELEVENLABS_API_KEY`. The `eleven_v4` model ignores `speed` and `style`, and `multilingual_v2`, flash and turbo read tags aloud. Speech recognition can prove a laugh was performed but not that a line sounds excited, so a human ear decides. The project is not affiliated with ElevenLabs.

How to disable. Delete the `~/.claude/skills/tts-director` folder or the skill folder in your project. Remove `ELEVENLABS_API_KEY` from the environment and `.env` files.

FAQ

How do I install the skill?

Run `git clone https://github.com/aligh98/tts-director ~/.claude/skills/tts-director`. You can also clone it into a project `.claude/skills/`.

What tag budget does the skill use?

About one tag per three or four sentences, zero to two laughs per reel and a change of delivery every 8–12 seconds.

What does the linter check?

Lines without a beat label, over-tagging, written register, repeated interjections, mistakes for the model and openings with a greeting.

How do I avoid wasting credits?

Run `ab.py` with `--dry-run`: it prints the cost and sends nothing. Then test doubtful lines on your own voice.

Do I need an ElevenLabs key?

Not for the linter. A key is needed only by the `ab.py` script, which sends text to ElevenLabs and spends credits.

Discussion

No questions or reviews yet.

Skills

video-production-skill takes an agent from script to video: slides, speech-verified narration, subtitles and a cover.

SkillExtended access106

A skill that turns a topic into a narrated 4K video: research, script, local TTS, Remotion composition and an FFmpeg mix

SkillExtended access1.7K

Skill turns finished SRT subtitles into a pack of image and video prompts: 21 styles, timecode storyboard, no media generation

SkillMinimal access125

The video-explainer skill turns a script into a vertical 9:16 explainer: narration, captions, Remotion and a pre-render review

SkillExtended access124

A skill that turns a Chinese voice-over script into animated HTML for screen recording, in manual mode or SRT autoplay mode

SkillMinimal access247
Official

Ten skills from ElevenLabs: text to speech, transcription, voice agents, sound effects, music, dubbing and voice cleanup through the API

SkillExtended access559

README in short

The description covers two typical voiceover problems, lists the six steps of the skill, shows installation and script commands, then collects findings about the ElevenLabs models.

README badge

Original SKILL.md

---
name: tts-director
description: Direct a script for text-to-speech so it sounds like a real, engaged human, not a narrator reading. Persian (Farsi) first, English supported. It rewrites the text for the ear, maps the beats of a short-form video (reel, TikTok, Short), and adds ElevenLabs v3/v4 audio tags only where they earn their place ([excited], [whispers], [laughs], [chuckles], [gasps], [sighs], [sarcastic]...). It checks for over-tagging with a free linter and A/B-tests risky lines on the real voice before a full run. It also covers model rules (eleven_v4 ignores speed and style; multilingual_v2, flash and turbo read tags aloud) and converts the result for other TTS engines (OpenAI, Azure, Google). Use for ANY script headed to ElevenLabs or another TTS, and whenever someone wants a voice that is more exciting, emotional, expressive, human or viral, or asks about tone, emotion, laughter, pauses or pacing in TTS: «لحن»، «احساس»، «هیجان»، «خنده»، «تگ»، «انسانی‌تر»، «گوینده»، «صداگذاری».
---

# TTS director: write for the ear, tag the beats, test by ear

A great voiceover is about 80% text and 20% tags. The text sets the rhythm, the register and where the energy goes. Tags only push a delivery the text has already set up. A script with a tag on every line sounds like an over-acted ad and loses the viewer. A script with none often sounds read.

This skill does not replace your TTS pipeline. It prepares the text that goes into it. Scripts are stdlib Python 3.9+; ffmpeg/ffprobe are optional and give durations.

## Workflow

Do the steps in order. The tools check them, so none can be skipped silently:
- `tag_lint.py` gives an ERROR when a line has no beat label;
- `tag_lint.py --check-approved` fails until the person has approved the exact text. Gate your TTS call on it.

Before step 1, read the delivery reference for the script's language (`references/persian-delivery.md` or `references/english-delivery.md`) and `references/audio-tags.md`. The linter checks only part of them.

1. **Beat map, inside the script.** End every spoken line with « # ROLE ENERGY» (energy 1–5):
   ```
   [excited] Wait, this ends Friday... and it's not coming back!   # HOOK 5
   [whispers] Here's the trick...                                  # TIP 2
   ```
   The roles are:
   - HOOK
   - SETUP
   - REVEAL
   - ITEM (a list point)
   - TIP (insider advice)
   - JOKE or IRONY
   - WARNING
   - CTA

   Plan the arc before touching words. See [Viral arc](#viral-arc). Strip the labels before the text goes to the TTS: `tag_lint.strip_beats(text)` does it, or remove everything from « #» to the end of each line. For a script that is not a short-form video, pass `--no-beats`.
2. **Rewrite for the ear.** Keep the meaning and every fact. Rewriting means:
   - shorter sentences;
   - the punch word moved to the end;
   - the interjections a native speaker would actually use;
   - punctuation that marks breaths.

Report a problem