Use when preparing Persian / Farsi text for any TTS engine. Returns the same text with normalisation, half-spaces, punctuation, Ezafe marks, exception fixes, and optional spoken-style rewrite.
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
Der Befehl bleibt in einer Zeile. Scrollen Sie horizontal, um ihn vor dem Kopieren vollständig zu prüfen.
Sie bevorzugen eine lokale Kopie? Laden Sie die Dateien herunter, die SkillsMP derzeit vorliegen.
Datei-Explorer
9 Dateien
SKILL.md wird angezeigt
SKILL.md
Quellanweisungen · Schreibgeschützte Vorschau
name
Persian TTS Preprocessor
description
Use when preparing Persian / Farsi text for any TTS engine. Returns the same text with normalisation, half-spaces, punctuation, Ezafe marks, exception fixes, and optional spoken-style rewrite.
Persian TTS engines (Azure, Google, MMS, XTTS, ElevenLabs) usually fail not because the model is bad, but because the input text is ambiguous. Persian doesn't write short vowels, often omits the ezafe (ـِ), uses elision in spoken form, and is sensitive to punctuation and syntax for prosody. Hand a raw paragraph to any engine and you'll get a stiff, book-like read with mispronunciations.
This skill takes a Persian text in, applies the minimum set of changes that make it read correctly, and returns the same text — same content, same paragraph structure, same line breaks — just TTS-ready.
When to use this skill
The user has Persian text and wants to feed it to a TTS engine (Azure, Google Gemini-TTS, MMS-TTS, XTTS, ElevenLabs, Coqui).
The user is producing voiceovers, audiobooks, podcasts, IVR, or accessibility output in Persian.
The user's previous TTS output was stiff, mispronounced, run-on, or read numbers as digits.
The user has text that came from ASR / OCR / LLM and needs punctuation restored before TTS.
Do not use when:
The user wants to translate Persian to another language — that's a translation skill.
The user wants to write new Persian text (a poem, a song, marketing copy) — that's a writing skill.
The text is non-Persian — apply a language-specific preprocessor.
Tag legend
[Rule] — always apply; safe in every register.
[Conditional] — apply only when the input contains the trigger pattern.
[Register-dependent] — apply only when the user asks for the Fluent-formal or Spoken register.
[Engine-specific] — apply only when the target engine is known to need it.
Instructions
Step 0 — Pick the register
Ask the user once, then hold it for the whole text:
Register
When to use
What changes
Preserve(default)
The user wants minimal interference — formal writing, news, audiobooks of literary work, legal/academic text
Only safe, mechanical fixes
Fluent-formal
The user wants formal but smooth reading — explainer videos, professional voiceover, e-learning narration
سایتِ اگزمپل دات کام (or skip the URL entirely if it's not meant to be read)
2.5kg
دو و نیم کیلوگرم
№3 / #3
شمارهٔ سه
1st, 2nd, 3rd
اولین, دومین, سومین
&
و
@username
اَت یوزرنیم (or omit if not meant to be read)
*, _, ~, ` (Markdown)
(remove — they're formatting, not content)
Keep ordinals, fractions, and large numbers in spelled-out Persian, not digits.
For currency: name the currency. For units: name the unit (don't use abbreviations like kg).
Step 5 — Ezafe marking — selective, not global [Conditional][Register-dependent]
The ezafe (ـِ) is the unstressed -e that links noun phrases: کتابِ من (my book). In normal Persian, ezafe is rarely written; the reader infers it. TTS engines guess wrong on ambiguous noun groups.
Selective rule (Preserve register):
Mark ezafe only on noun-noun or noun-adjective groups where the engine is likely to drop it.
Mark on the first ezafe of a chain, then let context handle the rest.
Do NOT mark ezafe globally — over-marked text reads like a textbook.
Pattern
Mark
noun + space + adjective (clearly attributive)
nounِ adjective — e.g.کتاب خوب → کتابِ خوب
noun + space + noun (clearly possessive)
nounِ noun — e.g.صدای تو (already explicit via ـی) → leave
Noun ending in ه + space + word
nounی + word — e.g.خانه بزرگ → خانهی بزرگ
Noun ending in long vowel ا/و/ی + space + word
noun + ی + word — e.g.پای من ← already explicit
Names (proper nouns) + space + descriptor
نامِ کامل — only mark when ambiguous
Fluent-formal register: mark ezafe more aggressively, including in compound technical phrases.
Spoken register: mark ezafe in the spoken-form rewrite (خونهی بزرگ, اسمِ تو).
See resources/ezafe.md for the full decision tree and edge cases.
This is the step that catches "obviously wrong" TTS readings. Do not treat this as optional. Scan every word in the text against the four classes below and apply the fix every time the pattern matches.
The previous version of this skill was too conservative here — it deferred to "engine usually handles it" and let through known-bad cases like کفش → kefesh and چتر → chetre. The correct posture is: if a word is in the lexicon, always diacritize, even in Preserve register.
Single-syllable Persian words with a final consonant cluster. The engine inserts a phantom vowel mid-cluster because Persian doesn't write short vowels. Always add the explicit short vowel.
Bare
Diacritized
Reading
کفش
کَفش
kafsh
چتر
چَتر
chatr
قبر
قَبر
qabr
قفل
قُفل
qofl
شکل
شِکل
shekl
مشت
مُشت
mosht
دست
دَست
dast
تخت
تَخت
takht
سخت
سَخت
sakht
نفس
نَفَس
nafas
فکر
فِکر
fekr
ذکر
ذِکر
zekr
صبر
صَبر
sabr
لطف
لُطف
lotf
عشق
عِشق
eshq
قلب
قَلب
qalb
قدر
قَدر
qadr
پست
پُست
post
نطق
نُطق
notq
شخص
شَخص
shakhs
نبض
نَبض
nabz
خشک
خُشک
khoshk
پخش
پَخش
pakhsh
See resources/exception-lexicon.md §1A for the full list (~50+ entries). When in doubt, mark it. Over-diacritising a single-syllable word is harmless; under-marking is the failure mode.
6.2 — Ambiguous short-vowel monosyllables
Words where the short vowel determines the meaning. Always diacritize based on context.
Word
When meaning …
Mark as
شن
sand
شِن
لنگ
leg / pair
لِنگ
لنگ
lame
لَنگ
سر
head
سَر
سر
secret
سِرّ
مرد
man
مَرد
مرد
died
مُرد
کرم
worm
کِرم
کرم
cream
کِرِم
کرم
generosity
کَرَم
شکر
sugar
شِکَر
شکر
thanks
شُکر
پر
feather
پَر
پر
full
پُر
ده
ten
دَه
ده
village
دِه
سم
poison
سَم
سم
hoof
سُم
See resources/exception-lexicon.md §1B for the extended list. Always diacritize words from this class — engine guesses are roughly 50/50 and frequently wrong.
When a consonant-final cluster noun takes ها + a possessive clitic (ت, ش, م), some engines insert a phantom ه.
Real failure:قدمهات read as qadame-hât (extra e).
Fix: diacritize the host noun before the clitic chain.
Bare
Diacritized fix
قدمهات
قَدَمهات
دستهاش
دَستهاش
چشمهام
چِشمهام
حرفهات
حَرفهات
Multi-syllable nouns rarely fail (کتابهاش is usually correct). The single-syllable cluster nouns are the high-risk class.
6.4 — واو معدوله and other historical exceptions
Words written with خوا where the و is silent — handle by lexicon (the spelling can't be fixed in plain text, so flag for the user or use phonetic notation if the engine supports it):
Pattern
Examples
Reading
خوا- family
خواهر, خواب, خواندن, خواستن, خواهان, خواهش
khâ- (silent و)
Religious phrases
الله, الرحمن, الرحیم
preserve as-is
Foreign loans
کامپیوتر, تلویزیون, اینترنت
usually safe — leave alone
Proper names with phantom-ezafe risk
نازلی, سارا, لیلا, ندا, رضا
wrap in « » or use possessive form
See resources/exception-lexicon.md §1, §2, §3, §4 for the full lists.
6.5 — Context-dependent homographs [Rule]
Words spelled normally but meaning different things depending on the short vowel. The engine picks the most-frequent reading; the user's intended reading is often the less-frequent one.
Bare
When meaning
Mark as
دور
far
leave as دور (dur)
دور
around / surrounding
دَوْرِ (dor) — e.g. دَوْرِ چراغ "around the lamp"
دوره
era / period / course
leave as دوره (dowre)
دوره
"it is far" (contracted)
rewrite as دور است or write دورْه
نت
music note
نُت (not)
درام
drum (music context)
دِرام (derâm)
درام
drama (theatre)
leave as درام (derâm standard)
بهونه
excuse (colloquial of بهانه)
بَهونه (bahune) — always
رو
object marker after a vowel
رُ (ro) — e.g. من رُ
رو
face
leave as رو (ru)
حرفت
your speech (spoken)
حرفِت (harfet)
حرفت
your speech (formal)
حرفَت (harfat)
پر
full
پُر (por)
پر
feather
پَر (par)
شکر
thanks
شُکر (shokr)
شکر
sugar
شِکَر (shekar)
See resources/exception-lexicon.md §1E for the full list. For every word in the input, ask: is this a homograph? If yes, what's the meaning here? Then mark.
6.6 — Foreign loans with internal consonant clusters [Rule]
Foreign loanwords (music, tech, modern vocabulary) with 2+ consonants between vowels get a phantom vowel from the engine. Same failure as §1A but in loanwords.
Bare
Diacritized
Reading
ساکسیفون
ساکْسیفُون
sâksifun
پیانو
پِیانو
pyâno
ساندویچ
ساندْویچ
sandvich
اسپرت
اِسْپُورْت
esport
الکترونیک
اِلِکْتْرونیک
elektronik
Often-safe (usually correct without marking): کامپیوتر, تلویزیون, اینترنت, موبایل, رادیو, سینما, اتوبوس, موسیقی, بانک, پلیس. The dividing line: 3+ syllables usually OK; 2-syllable with internal cluster usually fails.
See resources/exception-lexicon.md §1F.
6.7 — Scan procedure (do this for every word in every text)
Walk every word through this 7-step check:
Single-syllable cluster word? (§1A) → diacritize.
Ambiguous short-vowel monosyllable? (§1B) → diacritize per context.
Clitic chain on cluster noun? (§1C) → diacritize the host.
Cluster word taking ezafe? (§1D) → diacritize the cluster, then mark ezafe.
Context-dependent homograph? (§1E) → diacritize per meaning.
Foreign loan with internal cluster? (§1F) → diacritize the cluster.
خوا- family / religious / proper-name phantom-ezafe? (§1, §2, §3, §4) → handle per section.
The v0.2 leak was that the LLM scanned §1A–§1D but not §1E–§1F. v0.3 adds those classes and the visible audit (Step 8) that forces the scan to happen on every word.
6.8 — Consistency rule [Rule]
Same word, same diacritisation, every time it appears in the text. No exceptions.
If you marked ساکسیفون as ساکْسیفُون in verse 1, every occurrence in verses 2, 3, the chorus, and the bridge must also be ساکْسیفُون. Inconsistent marking is worse than no marking — the engine produces correct reading on one line and wrong on the next, which sounds random and unprofessional.
To enforce: after diacritizing, search for each diacritized word's bare form in the text and confirm zero matches remain. If a bare form survives anywhere, mark it.
Do not rewrite proper names, technical terms, religious phrases, fixed expressions, or quoted material.
Do not mix registers — once a word is rewritten to spoken, all instances of that word in the text should match.
See resources/spoken-rewrite.md for the extended table and "don't rewrite" list.
Step 8 — Preserve the structure on output
Return the text with the same paragraph structure, line breaks, and overall layout as the input. Only the content of each line changes.
Preserve
Reason
Paragraph breaks
TTS engines reset prosody at paragraph boundaries
Line breaks within stanzas (poetry, lyrics)
Sometimes structurally meaningful
Headings and section markers
User may chunk by section
List bullets / numbering
User's formatting choice
Quoted passages
Keep quote marks as-is
Markdown bold/italic
Remove if asked, but flag — TTS doesn't render markdown
After the preprocessed text, append a mandatory Word Audit showing the lexicon-scan decisions. This is what forces the scan to actually happen — without the visible audit, the LLM tends to mark a few obvious words and skip the rest.
Word Audit (required) [Rule]
For every word in the text that was a candidate for the lexicon (§6.1 through §6.7), produce one row:
Word audit
─────────────────────────────────────────────────────────────────
Word (bare) | Lexicon class | Decision | Marked form | Count
─────────────────────────────────────────────────────────────────
کفش | §1A cluster | mark | کَفش | 2
چتر | §1A cluster | mark | چَتر | 1
شن | §1B short-vowel | mark per context | شِن (sand) | 1
لنگهم | §1B short-vowel | mark per context | لِنگهم (pair) | 1
قدمهات | §1C clitic-chain | mark host | قَدَمهات | 1
دور | §1E homograph | mark per context | دَوْرِ (around) | 1
درام | §1E homograph | mark per context (music) | دِرام | 3
دوره | §1E homograph | rewrite (means "is far") | دور است | 1
نت | §1E homograph | mark per context (music note) | نُت | 1
بهونه | §1E always | mark | بَهونه | 1
حرفت | §1E homograph | mark per register (spoken) | حرفِت | 2
ساکسیفون | §1F foreign-loan cluster | mark | ساکْسیفُون | 6
پیانو | §1F foreign-loan cluster | mark | پِیانو | 1
─────────────────────────────────────────────────────────────────
Consistency check: ✓ every bare form replaced everywhere it appears
This is non-negotiable. The audit must include:
Every word that matched a lexicon class
The class (§1A through §1F)
The decision (mark / mark-per-context / rewrite / leave)
The marked form
The count (how many times it appears in the text)
An explicit consistency-check line at the bottom
The audit is what the user reads to verify nothing was left to chance. If the audit is missing or incomplete, the work is not done.
If the user names the target engine, also add the engine-specific layer at the end:
Engine
Add
Azure Speech (fa-IR)
Add SSML <break> tags at paragraph breaks (<break time="500ms"/>). Note: Azure does NOT support phoneme / custom lexicon for fa-IR voices, so all pronunciation fixes must be in the text.
Google Gemini-TTS (fa-IR)
Add SSML <break> similarly. Currently Preview — expect some variance.
MMS-TTS Persian
Strip all punctuation before sending. MMS removes it anyway. Instead, split into short sentences and synthesise separately with controlled silence between (~ 400ms).
XTTS-v2 / ElevenLabs
XTTS-v2 doesn't officially support fa — use only fine-tuned community checkpoints. ElevenLabs handles Persian; punctuation works as expected.
Unknown engine
Skip this step. Deliver the text without engine-specific markup.
See resources/engine-adapters.md for the full per-engine notes.
Examples
Example 1 — minimal (Preserve register)
Input:
این کتاب خوب رو که دیروز خریدم همون کتابیه که بهت گفته بودم
Output (Preserve):
این کتابِ خوب رو که دیروز خریدم، همون کتابیه که بهت گفته بودم.
Changes:
Added ezafe on کتابِ خوب (was missing).
Added ، before همون (clause boundary).
Added . at sentence end.
(No character normalisation needed — input was clean.)
Example 2 — full pipeline (Fluent-formal register)
Input:
سال 1405/02/01 ساعت 10:30 جلسه با مدير شركت داريم نميتونم بيام
Output (Fluent-formal):
سالِ یکم اردیبهشتِ هزار و چهارصد و پنج، ساعتِ ده و نیم، جلسه با مدیرِ شرکت داریم. نمیتونم بیام.
Changes:
Arabic ي/ك → Persian ی/ک (4 replacements).
Date 1405/02/01 → یکم اردیبهشتِ هزار و چهارصد و پنج.
Time 10:30 → ساعتِ ده و نیم.
Ezafe on سالِ, ساعتِ, مدیرِ شرکت.
Half-space restored on نمیتونم.
Added ، between clauses.
Added . to split the run-on into two sentences.
Example 3 — Spoken rewrite
Input:
من میخواهم این کتاب را به تو بدهم چون آن را دوست داری
Output (Spoken):
من میخوام این کتابو بهت بدم، چون اونو دوست داری.
Changes:
میخواهم → میخوام (spoken).
این کتاب را → این کتابو (spoken; را → -و).
به تو بدهم → بهت بدم (spoken contractions).
آن را → اونو (spoken).
Added ، before چون and . at end.
Example 4 — engine-specific (MMS-TTS adapter)
Input + register chosen + engine = MMS-TTS:
اگر دیر رسیدی، شروع کن. ولی عجله نکن.
Output for MMS:
[Chunk 1, send to MMS, insert 400ms silence after]
اگر دیر رسیدی شروع کن
[Chunk 2, send to MMS, insert 400ms silence after]
ولی عجله نکن
MMS strips punctuation, so the text is delivered as two separate synthesis calls with explicit silence between.
Example 5 — diacritising single-syllable cluster words (the v0.2 fix)
These are the exact failures reported on v0.1 of the skill. Each was a "ordinary-looking" word that the engine mispronounced because the short vowel was implicit. v0.2 catches them via the lexicon scan in Step 6.
Input
What v0.1 produced (bad)
What v0.2 should produce (good)
What the engine then reads
لنگهکفش
لنگهکفش (no fix) — engine read lange-kefesh
لنگهکَفش
lange-kafsh ✓
چتر خریدی
چتر خریدی (no fix) — engine read chetre kharidi
چَتر خریدی
chatr kharidi ✓
شن نشست
شن نشست (no fix) — engine read shan neshast
شِن نشست
shen neshast ✓
لنگهم
لنگهم (no fix) — engine read lang-am
لِنگهم
leng-am ✓
قدمهات
قدمهات (no fix) — engine read qadame-hât
قَدَمهات
qadam-hât ✓
The v0.2 instruction: scan every word against resources/exception-lexicon.md §1A, §1B, §1C, §1D before delivery. If a word matches a pattern, diacritize it. Don't second-guess; over-marking is harmless.
Worked example — Input:
من حافظِ قدمهات هستم. لنگهکفش رو پیدا کردم. چتر خریدی؟ شن نشست رو پاکم.
Output (Preserve + Step 6 applied):
من حافظِ قَدَمهات هستم. لنگهکَفش رو پیدا کردم. چَتر خریدی؟ شِن نشست رو پاکم.
Changes per word:
قدمهات → قَدَمهات (cluster noun + clitic — §1C)
لنگهکفش → لنگهکَفش (cluster word inside a compound — §1D)
چتر → چَتر (CVCC cluster — §1A)
شن → شِن (ambiguous short vowel — §1B; meaning "sand" from context)
Nothing else in the text changes. The structure, the formal register, the other words — all preserved.
Example 6 — full song lyric (the v0.3 fix — homographs + foreign loans + visible Word Audit)
The exact failure case the user reported on v0.2: a song lyric that passed v0.2's cluster-monosyllable check but still mispronounced homographs (دور, درام, دوره, نت), foreign loans (ساکسیفون, پیانو), and inconsistent words (some occurrences fixed, others left bare).
Input (excerpt, Spoken-leaning register):
[Intro | smoky jazz club | brushed drums | upright bass]
دود میپیچه دورِ چراغ
شب نشسته روی شونههام
میزِ چوبی، لیوانِ سرد
اسمِ تو مونده روی لبهام
[Verse 1]
درام آرومه...
مثلِ بارون روی شیشه
کافه خوابه، شهر دوره
دل هنوز از تو مینویسه
سایهات رد میشه از ذهنم
مثلِ فیلمی بیصدا
من به هر نت خیره میمونم
تو به هر خاطره، جدا
[Pre-Chorus]
هیچکس اینجا
جایِ تو حرف نمیزنه
جز ساکسیفونی که انگار
اسمِ من رو پس میزنه
[Chorus]
بمون امشب
بمون یه کم
بذار ساکسیفون
حرفت رو بزنه
Output (preprocessed):
[Intro | smoky jazz club | brushed drums | upright bass]
دود میپیچه دَوْرِ چراغ
شب نشسته روی شونههام
میزِ چوبی، لیوانِ سرد
اسمِ تو مونده روی لبهام
[Verse 1]
دِرام آرومه...
مثلِ بارون روی شیشه
کافه خوابه، شهرْ دور است
دل هنوز از تو مینویسه
سایهات رد میشه از ذهنم
مثلِ فیلمی بیصدا
من به هر نُت خیره میمونم
تو به هر خاطره، جدا
[Pre-Chorus]
هیچکس اینجا
جایِ تو حرف نمیزنه
جز ساکْسیفُونی که انگار
اسمِ من رُ پس میزنه
[Chorus]
بمون امشب
بمون یه کم
بذار ساکْسیفُون
حرفِت رو بزنه
Word Audit:
Word audit
────────────────────────────────────────────────────────────────────────
Word (bare) | Class | Decision | Marked form | Count
────────────────────────────────────────────────────────────────────────
دورِ | §1E homograph | mark per context (around) | دَوْرِ | 1
درام | §1E homograph | mark per context (drum/music) | دِرام | 3 (verse 1, chorus, outro)
دوره | §1E homograph | rewrite ("is far") | دور است | 1
نت | §1E homograph | mark per context (music) | نُت | 1
ساکسیفون | §1F foreign-loan cluster | mark | ساکْسیفُون | 6
ساکسیفونی | §1F foreign-loan cluster + suffix | mark | ساکْسیفُونی | 1
رو (object after vowel) | §1E homograph | mark | رُ | 1 (in `من رُ`)
حرفت | §1E homograph | mark per register (spoken) | حرفِت | 2
بهونه | §1E always | mark | بَهونه | 1 (in outro/bridge)
پیانو | §1F foreign-loan cluster | mark | پِیانو | 1 (in verse 2)
کفش (in لنگهکفش) | §1A cluster | mark inside compound | لنگهکَفش | (only if appears)
چتر | §1A cluster | mark | چَتر | (only if appears)
شن | §1B short-vowel | mark per context (sand) | شِن | (only if appears)
قدمهات | §1C clitic-chain | mark host | قَدَمهات | (if appears)
────────────────────────────────────────────────────────────────────────
Consistency check: ✓ every occurrence of ساکسیفون marked as ساکْسیفُون;
✓ every occurrence of درام marked as دِرام;
✓ every occurrence of حرفت marked as حرفِت
resources/test-cases.md — the 12-slice test suite (Ezafe, post-ه Ezafe, homograph, واو معدوله, half-space verbs, suffixes, yes/no questions, clause boundaries, numbers/dates, mild colloquial, clitics, long text). Use to verify the preprocessor's output on each engine.
Notes & limitations
Persian TTS is front-end-limited, not model-limited. The preprocessor matters more than the engine choice. Even a great model produces stiff output on raw text; a moderate model produces natural output on preprocessed text.
Preserve mode is the default. Don't aggressively rewrite to Spoken unless the user explicitly asks. Rewriting formal text into colloquial form can break tone (academic, legal, literary, religious).
Ezafe marking is selective, not global. Marking every possible ezafe makes the output read like a school textbook. Only mark where the engine is likely to drop it.
But short-vowel diacritization on cluster monosyllables is NOT selective — always mark. Single-syllable Persian words with closed consonant clusters (کفش, چتر, قفل, شکل, …) and ambiguous-short-vowel monosyllables (شن, لنگ, سر, …) must be diacritized every time. Skipping these is the #1 source of "obvious" TTS mispronunciation. See Step 6.1–6.3 and resources/exception-lexicon.md §1A–§1D.
"Selective" applies to Ezafe, not to the exception lexicon. v0.1 of this skill conflated the two — the LLM read "selective diacritization" as a global posture and let through known-bad cluster words. v0.2 corrects the framing: Ezafe is selective; lexicon entries are always applied.
The visible Word Audit is non-negotiable. v0.2 made the lexicon [Rule] but the LLM still scanned incompletely — fixing some occurrences of a word and leaving others bare. v0.3 fixes this by requiring a visible per-word audit table in the output (Step 8). If the audit is missing or incomplete, the work is not done. The forcing function is the same idea the Persian Suno Lyrics skill uses with its Content Brief: making the LLM show its scan prevents the "I marked the easy ones and skipped the rest" failure mode.
Consistency is mandatory. Same word, same diacritisation, every occurrence. The Word Audit ends with an explicit consistency-check line confirming zero bare forms of marked words remain anywhere in the text.
Context-dependent homographs are the most subtle failure class. Words like دور, درام, دوره, نت, حرفت are spelled normally — the failure isn't a missing diacritic on a weird word, it's the engine picking the wrong reading of a normal word. These need contextual diacritisation: read the sentence, pick the meaning, mark accordingly. See §6.5 and resources/exception-lexicon.md §1E.
Foreign loanwords with internal clusters need the same treatment as native cluster monosyllables.ساکسیفون, پیانو, ساندویچ — all have the same phantom-vowel-insertion failure as کفش or چتر. Mark them. See §6.6 and resources/exception-lexicon.md §1F.
Engine support for Persian varies wildly. Azure has two voices but no custom lexicon. MMS strips punctuation. XTTS-v2 doesn't officially support Persian. ElevenLabs and Google Gemini-TTS are currently the safer English-speaker-friendly defaults for high-quality Persian; specialised Persian-trained models (ManaTTS, ParsVoice fine-tunes) are stronger for native quality but require infrastructure. See resources/engine-adapters.md.
Some Persian sounds remain AI-hard even with clean text.ع, ح, ق, ء are inconsistently rendered. Proper names ending in -li, -ra, -ma (نازلی, سارا, نیما) often get a phantom ezafe inserted (nâz-LI → nâz-EH-li). The skill flags these but the engine may still mispronounce. Re-roll 2–3 times and pick.
Regional dialects (Khorasani, Lori, Kurdish, Bandari) are out of scope. Default register is Tehran-standard Persian (fa-IR معیار). If the user wants regional flavour, write the معیار form and use post-processing in the audio.
Don't try to mark every Ezafe perfectly. Mark the high-risk ones, let context handle the rest. The goal is "good enough that TTS reads naturally", not "every linguistic relationship encoded".
The skill output should be reversible. A user should be able to compare input vs output and understand every change. If a change isn't explainable in one line, it's probably wrong.
Changelog
0.3.0 — second round of fixes after v0.2 live testing. v0.2 added the lexicon classes but the LLM was still scanning incompletely — some occurrences of a word got diacritized, others didn't (the "leaving it to chance" problem the user flagged). v0.3 adds two new lexicon classes that v0.2 missed entirely (§1E context-dependent homographs covering دور/دوره/نت/درام/بهونه/رو/حرفت/شکر/پر/سر/مرد/etc., and §1F foreign loans with internal consonant clusters covering ساکسیفون/پیانو/ساندویچ/اسپرت/الکترونیک/etc.). More importantly, v0.3 adds a mandatory visible Word Audit to the output (Step 8) — a table listing every lexicon-class word, its decision, marked form, and count, with an explicit consistency-check line. This is the forcing mechanism: the LLM has to show the per-word scan, which makes "I'll fix some of them" impossible. Added §6.8 explicit consistency rule. Added Example 6 walking through the user's actual song lyric end-to-end with the full Word Audit. Renumbered the previous Example 6 to Example 7.
0.2.0 — major fix to Step 6 (exception lexicon) after live testing revealed the v0.1 was too conservative and let through known-bad cases like کفش → kefesh, چتر → chetre, شن → shan, لنگ → lang, and clitic chains like قدمهات → qadame-hât. The root cause: v0.1's exception lexicon was scoped to the خوا- family + proper names, and the LLM interpreted "selective diacritization" in Step 5 as "minimise diacritics". v0.2 expands the lexicon into four new sub-sections (§1A closed consonant-cluster monosyllables, §1B ambiguous short-vowel monosyllables, §1C clitic chains on cluster nouns, §1D Ezafe on cluster words) covering ~80+ high-frequency words, and rewrites Step 6 as a mandatory scan-and-diacritize procedure ([Rule], not heuristic) that applies in every register including Preserve. Added a new Example 5 walking through the exact failures the user reported. Step 6 now has an explicit 6-priority scan procedure; over-marking is harmless, under-marking is the failure mode.
0.1.0 — initial version. Distilled from a comprehensive research brief on Persian TTS preprocessing covering phonetic basics, normalisation, half-space restoration, punctuation repair, Ezafe marking, exception lexicon, spoken-style rewrite, engine-specific adapters, and a 12-slice evaluation framework.
