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

1. Beat map. Label every line with its role and a target energy from 1 to 5. 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.

2. Rewrite for the ear. For Persian use references/persian-delivery.md; for English, references/english-delivery.md. 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.

   Show the text to the person before generating anything. Generating audio costs them credits, and the wording is theirs to approve.

3. Tag pass. Tag only the beats the text alone cannot carry, within the Tag budget. For tag names and what each one is for, see references/audio-tags.md.

4. Lint (free):

   python scripts/tag_lint.py SCRIPT --model eleven_v4 --tempo 1.15
   

   It prints a beat map with estimated times. It flags:

   • over-tagging;
   • laughs that are too many or too close together;
   • a repeated tag;
   • «!» on every line, and too many ellipses;
   • long sentences;
   • written laughter («هاها», "haha");
   • an opening greeting;
   • SSML on v3/v4, and tags on models that read them aloud.

   Fix every ERROR. Keep a WARN only when you can say why.

5. A/B the risky lines. These are the hook, every laugh, any whisper or sarcasm, and the CTA. Check the cost first; --dry-run sends nothing:

   python scripts/ab.py "VARIANT A" "VARIANT B" --voice VOICE_ID --stability 0.35 --stability 0.5 --prev "line before" --next "line after" --out probe/ab --dry-run
   

   Remove --dry-run to generate. Every clip uses the same --seed, so the differences come from the text and the settings, not from chance. Each clip is transcribed:

   • LEAK means a tag was read aloud as a word. Drop or rephrase that tag.
   • An event such as [laughter] or [خنده] means the sound was performed.

   Speech-to-text cannot judge excitement, so let a human ear pick the winner.

6. Generate the full script with the chosen variants and settings. Then:

   • Set the pacing with ffmpeg -af atempo=1.1 (1.10–1.20 keeps pitch), not with a speed setting. If you have word timings, divide them by the same factor.
   • To fix one line, regenerate only that chunk with previous_text/next_text and splice it in.

Tag budget

Never over-tag. Every tag must help retention or make the voice more human. A tag that repeats what the text already says is noise.

• Density: about 1 tag per 3–4 sentences, which is 4–8 tags in a 60–90 s reel. The linter errors above 0.5 tags per sentence and warns above 0.34.

• Baseline energy is not a tag. The voice, a stability of 0.3–0.4 and punchy text set the overall energy. Do not put [excited] on every line. Save it for 2–3 peaks: the hook, the big reveal and the CTA push.

• Laughs: 0 to 2 per reel, and never forced. Laugh only where a person would:

  • after a real joke or irony;
  • on a self-aware aside;
  • for relief after a tense point.

  Never laugh on numbers, dates, prices, the offer itself or the CTA keyword. Keep laughs 20 s or more apart. Pick the tag by size: [chuckles] is the safe, light one; [laughs] is a clear laugh; use [laughs harder] for one big moment at most.

• Contrast beats intensity. Attention comes from change. Use one change of delivery every 8–12 s; this is the pattern interrupt. For example:

  • a whisper after an energetic line;
  • a pause before a reveal;
  • a sigh before a pain point;
  • a gasp before an unbelievable fact.

• One or two tags at a spot, never three. Put the tag right before the words it colours. Its effect runs to about the end of that sentence.

• Bring the energy back after [whispers] or [sighs]. Do it on the next line with the text (a «!», a short punch) or with a delivery tag. Check it by ear.

• Keep clarity lines clean. Numbers, dates, prices, product names and the CTA keyword are said plainly. A warm tag may come before the CTA sentence, never inside the keyword.

• Never tag staging or music ([music], [standing]), and never tag sensitive topics such as grief, illness or tragedy.

Viral arc

For a 60–90 s vertical video:

For long-form narration (an audiobook, an explainer), halve the tag budget and drop the pattern-interrupt rule. Let the text carry it.

Settings (ElevenLabs)

• eleven_v4 is ElevenLabs' recommended model. It reads only stability and similarity_boost; its help page says Style and Speed are not available. A test on 2026-11-03 confirmed this: speed 0.8 and 1.2 gave clips of 6.32 s and 6.40 s. Set the pace with short sentences and fewer commas, then atempo.
• Stability: lower means more expressive delivery and closer tag-following, but takes vary more from one to the next.
  • 0.3–0.4: hype reels.
  • 0.5: neutral narration.
  • Above 0.7: tags are followed weakly.
  • Below about 0.25: takes can wobble, so A/B first.
• eleven_v3: the same tags work. The ElevenLabs UI names three stability presets: Creative (low), Natural (0.5) and Robust (high, follows tags weakly). If the API rejects a value, use 0.0, 0.5 or 1.0.
• No SSML on v3/v4. <break> is not supported. Use «...» or «—» for pauses, «،»/«,» for a breath, and [short pause] when punctuation is not enough.
• multilingual_v2, flash, turbo: these read [tags] aloud, so strip every tag. Steer with style (0–1), speed (0.7–1.2) and <break time="0.5s"/> (3 s at most, and only a few).
• Chunks: when you generate part of a script, send previous_text/next_text so the energy and intonation join up. That context is not spoken.
• Seed: seed makes sampling close to repeatable, though not guaranteed. Fix it for A/B tests.

Other TTS engines

Convert the directed script into whatever the engine accepts:

• OpenAI gpt-4o-mini-tts: no inline tags, so remove them. Put the delivery into the instructions field, for example: "energetic young narrator, fast, smiling, one short laugh after the joke".
• Azure or Google SSML: use <break>, <prosody rate pitch> and <emphasis>. Use Azure's <mstts:express-as style> only on voices that list that style; check the voice's style list first.
• Prompt-driven engines (e.g. Gemini TTS): a natural-language style prompt plus the clean text.

Whatever the engine, the step 2 rewrite does most of the work.

Calibrate for a new voice

Tag behaviour and speaking rate depend on the voice. Once per voice:

• Run tag_lint.py SCRIPT --calibrate AUDIO.mp3. It measures the voice's real characters per second from one finished take, for free. Pass that number as --cps from then on.
• A/B the tags you plan to use with ab.py. Record what works in the tested-voices table in references/audio-tags.md.

Files

tts-director

English · فارسی

یه اسکیل برای ایجنت‌های هوش مصنوعی که متن رو قبل از تبدیل به صدا کارگردانی می‌کنه. نتیجه‌اش صدای یه آدم واقعی و پرانرژیه، نه کسی که از رو کاغذ می‌خونه.

اول برای فارسی ساخته شده و انگلیسی رو هم پشتیبانی می‌کنه. روی تگ‌های صوتی ElevenLabs v3/v4 تمرکز داره و برای سرویس‌های دیگه‌ی TTS هم راهنما داره.

مشکل چیه؟

بیشتر متن‌هایی که به TTS داده می‌شن به یکی از این دو دلیل خراب می‌شن:

• برای چشم نوشته شدن، نه برای گوش. جمله‌ها رسمی و طولانی‌ان، پس خروجی شبیه خوندن اخبار می‌شه.
• تگ‌گذاری زیادی دارن. وقتی سر هر خط [excited] باشه، صدا شبیه یه تبلیغ اغراق‌آمیز می‌شه و بیننده رد می‌کنه.

این اسکیل چی کار می‌کنه؟

۱. نقشه‌ی ضرب‌آهنگ ویدیو رو می‌کشه. نقش هر خط رو مشخص می‌کنه: هوک، مقدمه، آیتم‌های لیست، نکته‌ی طلایی، شوخی، دعوت به اقدام.

۲. متن رو برای گوش بازنویسی می‌کنه. متن محاوره‌ای می‌شه، جمله‌ها کوتاه می‌شن، کلمه‌ی اصلی میره آخر جمله، و صوت‌های واقعی مثل «وای»، «ببین» و «دیگه» اضافه می‌شن. هیچ واقعیتی از متن عوض نمی‌شه.

۳. تگ‌ها رو با بودجه‌ی سفت‌وسخت می‌ذاره:

• حدود یه تگ برای هر ۳ تا ۴ جمله؛
• تو هر ریلز صفر تا دو خنده، فقط جایی که یه آدم واقعی می‌خنده؛
• هر ۸ تا ۱۲ ثانیه یه تغییر لحن، مثلاً پچ‌پچ، آه یا مکث، تا بیننده رد نکنه.

۴. یه لینتر رایگان داره که بدون مصرف اعتبار این‌ها رو پیدا می‌کنه:

• زیاده‌روی در تگ‌گذاری؛
• خنده‌های زیادی یا خیلی نزدیک به هم؛
• «هاها»ی نوشتاری؛
• شروع ویدیو با «سلام»؛
• خطاهای مخصوص هر مدل، مثل SSML روی v4 یا تگ روی مدل‌هایی که تگ رو بلند می‌خونن.

۵. قبل از ساخت کل ویس، جمله‌های حساس رو A/B تست می‌کنه و با صدای خودت چند نسخه می‌سازه:

• همه‌ی نسخه‌ها با یه seed ثابت ساخته می‌شن تا مقایسه منصفانه باشه؛
• --dry-run هزینه رو قبل از ارسال نشون می‌ده؛
• هر کلیپ به متن تبدیل می‌شه و معلوم می‌شه کدوم تگ بلند خونده شده و کدوم خنده واقعاً اجرا شده.

با Claude Code و هر ایجنتی که اسکیل‌های SKILL.md رو بخونه کار می‌کنه. اسکریپت‌ها با Python 3.9+ نوشته شدن و هیچ وابستگی‌ای ندارن؛ ffmpeg اختیاریه.

نصب

برای Claude Code به‌عنوان اسکیل شخصی:

git clone https://github.com/aligh98/tts-director ~/.claude/skills/tts-director

یا داخل .claude/skills/ یه پروژه کلونش کن. هر وقت متنی قراره به TTS بره، یا ازش بخوای صدا انسانی‌تر و پرهیجان‌تر بشه، خودش فعال می‌شه.

استفاده‌ی مستقیم از اسکریپت‌ها

# Free: beat map, length estimate, over-tagging and model errors
python scripts/tag_lint.py examples/reel-fa.txt --model eleven_v4 --tempo 1.15

# Free: measure your voice's real speaking rate from one finished take
python scripts/tag_lint.py script.txt --calibrate voice.mp3

# Check the cost first (sends nothing)
python scripts/ab.py "[excited] وای! فقط تا جمعه وقت داری!" "وای... فقط تا جمعه وقت داری!" --stability 0.35 --stability 0.5 --out probe --dry-run

# Generate and transcribe each variant (uses ElevenLabs credits)
export ELEVENLABS_API_KEY=...
python scripts/ab.py "[excited] وای! فقط تا جمعه وقت داری!" --voice YOUR_VOICE_ID --lang fa --en-check --out probe

گزینه‌های ab.py:

• --prev و --next: خط قبل و بعد رو به‌عنوان زمینه به مدل می‌دن تا لحن جمله‌ها به هم بچسبه.
• --lexicon words.tsv: یه فایل نوشتار<TAB>گفتار برای درست کردن تلفظ اسم‌ها و کلمه‌های خارجی، مثل کلش ← کِلَشْ.
• --en-check: کلیپ رو به‌صورت انگلیسی هم به متن تبدیل می‌کنه تا اگه یه تگ انگلیسی بلند خونده شده باشه، معلوم بشه.

تست‌های آفلاین: python -m unittest discover tests

چیزهایی که با آزمون و خطا فهمیدیم

• eleven_v4 تنظیم سرعت و style رو نادیده می‌گیره. یه جمله رو با سرعت ۰.۸ و ۱.۲ ساختیم و طولش تقریباً یکی شد (۶.۳۲ و ۶.۴۰ ثانیه). روی v4 فقط stability اثر داره. سرعت رو بعد از ساخت با ffmpeg -af atempo=1.1 تنظیم کن؛ زیر و بمی صدا عوض نمی‌شه.
• multilingual_v2، flash و turbo تگ‌ها رو بلند می‌خونن. v3 و v4 هم <break> رو نمی‌شناسن؛ به جاش از «...» استفاده کن.
• تگ‌ها رو حتی تو متن فارسی انگلیسی بنویس. مدل با تگ‌های انگلیسی آموزش دیده.
• خنده‌ی نوشتاری («هاها») حرف‌به‌حرف خونده می‌شه. به جاش [laughs] یا [chuckles] بذار.
• تبدیل صدا به متن فقط ثابت می‌کنه که خنده اجرا شده. اینکه صدا واقعاً هیجان‌زده‌ست یا نه رو فقط گوش آدم می‌فهمه.

مشارکت

مفیدترین کمک، اضافه کردن یه ردیف به جدول صداهای تست‌شده توی references/audio-tags.md است: صدا، مدل و زبان؛ کدوم تگ‌ها اجرا شدن و کدوم نه؛ و سرعت حرف زدن اون صدا. راهنمای زبان‌های دیگه هم با نام references/<زبان>-delivery.md خوش‌اومده.

مجوز

MIT. این پروژه هیچ ارتباطی با ElevenLabs نداره و «ElevenLabs» علامت تجاری صاحبش است.