cartesia-hebrew-tts

Cartesia Hebrew TTS

The voice itself sounds natural out of the box. Nearly all failures are pronunciation: unvoweled Hebrew leaves the model guessing vowels, gender and how to read digits. So the work is in preparing the text and checking the result.

Scripts are in scripts/ next to this file. Run them with node (20 or newer), from the folder where the output should go. Personal data lives in ~/.cartesia-tts: the keys (.env), the default voice and settings (config.json) and the pronunciation list (lexicon.json). Updating the skill never touches that folder.

First run

Talk to the user in their language, in plain words, and wait for them after each step.

1. Run node scripts/doctor.mjs. It is free. It prints READY, or what to fix.

2. Keys: if one is missing, run node scripts/doctor.mjs --keys. It opens the key file in a text editor, where the user pastes:

   • CARTESIA_API_KEY, from play.cartesia.ai (API keys). A free account works.
   • GEMINI_API_KEY, from aistudio.google.com (the same key from Day 1 of the course).

   Never ask the user to paste a key into the chat, and never print a key.

3. Voice: ask whether they want to clone their own voice (see "Clone a voice") or use a stock voice for now (node scripts/voices.mjs --language he, then --set-default <id>).

4. Run doctor.mjs again until it says READY, then make one short test line through "Make a voiceover" so they can hear it.

Make a voiceover

1. Save the original as <name>.original.txt, untouched.

2. Prepare the script. Read references/hebrew-rules.md, then save <name>.txt with:

   • numbers, times and prices as spoken words with the right gender
   • full nikud on ambiguous words, including prefix letters, and everything else plain
   • English names in English letters, and clean punctuation

   Change how words are written, not what they say. If a rewording would really help, such as replacing a formal time, say so in your summary.

3. Generate and check:

   node scripts/speak.mjs <name>.txt <name>.wav --check
   

   Add --emotion none, --speed 1.0 or --voice <id> if asked. Use a .mp3 output name for MP3. It also writes <name>.wav.sent.txt (the exact text sent) and <name>.wav.check.json (the report). Exit code 2 means the check found errors.

4. Fix only what failed. The check can flag a word that was said correctly, so first compare heard_as with the reading you intended, and ignore the report for that word if they match. For each real error, correct it in <name>.txt and regenerate. In order of preference: add or correct full nikud, then respell it, then swap in a synonym. Stop after 3 rounds and report what remains, because more retries rarely help and each one uses credits.

5. Remember real fixes. If a word needed a fix and always means the same thing, add it to ~/.cartesia-tts/lexicon.json (create the file if needed), which is applied automatically on every run:

   [{ "text": "גוללים", "say": "גּוֹלְלִים" }]
   

   Matching is on the exact whole word, so add prefixed forms as their own entries. Leave out homographs like ספר, since the right reading depends on the sentence and a fixed replacement would break other uses.

6. Report back: the audio path, the check result, any words you changed, and a reminder to listen.

The check catches wrong words better than subtle delivery. In testing it gave three different reel takes identical perfect scores. A PASS means no mistakes were detected, and the user's ear makes the final call. When asked to compare takes on feel, give them the takes rather than picking from the scores.

Generate one take at a time, because Cartesia limits concurrent requests by plan.

Check an existing take

node scripts/check.mjs <audio> <script.txt> --json report.json

Clone a voice

node scripts/clone.mjs <clip> --name "Voice name" --language he --set-default

Clone only the user's own voice, or a voice whose owner gave clear permission. If it is someone else's voice and permission isn't clear, stop and ask. Leave off --set-default to try a clone first, then pass it to speak.mjs with --voice <id>. Advise on the clip before uploading, since the clone copies it closely:

• 30 to 60 seconds (Sonic 3.6 learns from up to 60), one speaker, a quiet room, under 16 MB
• speak naturally rather than like an announcer
• record in the mood wanted for the voice, because a cheerful clip gives a cheerful voice in everything it says

Pro Voice Clones need 30+ minutes of audio and a higher plan. They improve likeness, not pronunciation, so they won't fix misread words. Details: https://docs.cartesia.ai/build-with-cartesia/capability-guides/clone-voices-pro

What it costs

Sonic uses 1 credit per character, about 750 to 800 credits per minute of audio. Cartesia's free plan includes 20,000 credits a month and instant voice cloning, for evaluation and personal use. Commercial use needs a paid plan, from $5 a month. Current details: https://www.cartesia.ai/pricing. The Gemini check runs on the user's Gemini key.