tts-director

English · فارسی

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

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

مشکل چیه؟

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

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

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

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

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

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

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

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

• خطی که برچسب نقش و انرژی ( # HOOK 5) نداره، و قوس انرژی‌ای که هوک قوی، افت‌وخیز یا تغییر لحن نداره؛
• زیاده‌روی در تگ‌گذاری، و خنده‌های زیادی یا خیلی نزدیک به هم؛
• نثر نوشتاری («را»، «است»، «می‌شود»)، کمبود یا تکرار صوت‌ها، «هاها»ی نوشتاری و شروع ویدیو با «سلام»؛
• کلمه‌هایی که املاشون با تلفظشون نمی‌خونه («بالاخره»، «حتی»، «فوق‌العاده»)، و هر املای حدسی‌ای که یه «ا» اضافه یا کم می‌کنه؛
• خطاهای مخصوص هر مدل، مثل SSML روی v4 یا تگ روی مدل‌هایی که تگ رو بلند می‌خونن.

آخرش هم یه برنامه‌ی A/B می‌ده: کدوم خط‌ها اول تست بشن و هر کدوم چند کاراکتر خرج داره (--ab-budget نشون می‌ده چی تو بودجه جا می‌شه).

۵. بدون تأیید، صدا ساخته نمی‌شه. بعد از اینکه متن و نقشه‌ی بیت‌ها رو تأیید کردی، --approve یه مهر با هش همون متن می‌سازه. --check-approved تا وقتی مهر با متن نخونه شکست می‌خوره، پس هر پایپ‌لاین TTS می‌تونه ساخت صدا رو به اون وصل کنه.

۶. قبل از ساخت کل ویس، جمله‌های حساس رو 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, arc, ear-rewrite and reading checks, A/B plan
python scripts/tag_lint.py examples/reel-fa.txt --model eleven_v4 --tempo 1.15 --ab-budget 160

# After the text is approved: stamp it, and gate every TTS call on the stamp
python scripts/tag_lint.py script.txt --approve
python scripts/tag_lint.py script.txt --check-approved   # exit 0 approved, 3 not

# 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>گفتار<TAB>یادداشت برای درست کردن تلفظ اسم‌ها و کلمه‌های خارجی، مثل اپ ← اَپْ. یادداشتی که با «✓» شروع بشه یعنی یه نفر با گوش تأییدش کرده؛ برای بقیه LISTEN FOR چاپ می‌شه. همین گزینه رو tag_lint.py هم می‌گیره.
• --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» علامت تجاری صاحبش است.