🎙️ Gemini Hebrew TTS Notebook

מערכת מתקדמת בקוד פתוח להמרת טקסט לדיבור (Text-to-Speech) בשפה העברית, המבוססת על המודלים החדישים של Google Gemini (ספציפית gemini-2.5-flash-preview-tts). המערכת בנויה בתצורת "מחברת" (Notebook) המאפשרת עבודה נוחה עם בלוקים של טקסט, ומכילה צינור עיבוד (Pipeline) עשיר לשיפור דרמטי של איכות ההגייה בעברית.

---

✨ תכונות מרכזיות

• מחברת עבודה (Notebook Mode): כל הפסקה או משפט הופכים לבלוק עצמאי שאפשר לערוך, להאזין לו שוב, ולהוריד למחשב. הבלוקים נשמרים על המסך כך שאפשר לחזור אחורה בכל שלב.
• ניקוד אוטומטי (Dicta Nakdan API): חיבור מובנה למנוע הניקוד של דיקטה, שפותר כמעט את כל בעיות ההגייה (כמו ההבדל בין "מְנַהֵל" ל-"מִנְהָל").
• סוכן עיבוד דינמי (Gemini LLM): סוכן חכם שקורא את הטקסט לפני ההקראה, פותח ראשי תיבות (דו"ח -> דוח) ומזהה מילים באנגלית כדי שהקריין יהגה אותן במבטא לועזי תקין (WhatsApp במקום "ווטסאפ").
• מילון חריגים (Static Lexicon): מאפשר הגדרה של "מצא והחלף" קבוע מראש למילים ספציפיות שרוצים לתקן את ההגייה שלהן.
• המרה אוטומטית של מספרים: הופך ספרות למילים בעברית (למשל: "3" -> "שלוש") בעזרת ספריית num2words.
• ניהול Rate Limits חכם: המערכת מזהה הגבלות של ה-API החינמי של גוגל (כגון 3 בקשות בדקה או 10 ביום) ומציגה שעון ספירה לאחור חכם במקום לקרוס.
• ממשק עברי מלא (RTL): כל הממשק, כיווני ההקלדה, והיישור (כולל תיבות הסימון והכפתורים) מותאמים במאה אחוז לשפה העברית.

---

🛠️ התקנה והרצה (הוראות למפתחים)

1. דרישות מוקדמות

• פייתון: Python 3.10 ומעלה מותקן על המחשב.
• מפתח API של גוגל: חשבון חינמי ב-Google AI Studio לקבלת API_KEY.

2. התקנת הפרויקט

שכפלו את הפרויקט למחשב שלכם, וצרו סביבה וירטואלית (venv) כדי לשמור על סדר:

git clone <repository_url>
cd gemini-tts-hebrew
python3 -m venv venv

# הפעלת הסביבה הווירטואלית (בלינוקס / מאק):
source venv/bin/activate  
# הפעלת הסביבה הווירטואלית (בווינדוס):
# venv\Scripts\activate

התקינו את כל הספריות הנדרשות לפרויקט:

pip install -r requirements.txt

3. קונפיגורציה (הגדרת משתני סביבה)

צרו קובץ חדש בשם .env בתיקייה הראשית של הפרויקט (איפה ש-app.py נמצא). הדביקו לתוכו את מפתח ה-API שלכם ואת מודל ה-TTS הרצוי:

GEMINI_API_KEY=AIzaSy...הכנס_כאן_את_המפתח_שלך...
GEMINI_MODEL=gemini-2.5-flash-preview-tts

4. הפעלת המערכת

הפעילו את שרת ה-Streamlit בעזרת הפקודה הבאה:

streamlit run app.py

המערכת תיפתח אוטומטית בדפדפן שלכם בכתובת http://localhost:8501.

---

⚙️ הגדרות וקונפיגורציה (בממשק המשתמש)

בצד ימין (או שמאל, תלוי בהגדרות המערכת שלכם) תמצאו את תפריט ההגדרות (Sidebar). כל בחירה שתעשו כאן תישמר אוטומטית (בקובץ מקומי בשם user_prefs.json) ותחכה לכם בדיוק באותו המצב בפעם הבאה שתפעילו את האפליקציה!

🗣️ הגדרות קול

• בחר קול (Voice Option): המודל של גוגל מציע מספר קולות מובנים. Puck ו-Charon נוטים להיות גבריים/עמוקים יותר, בעוד ש-Kore ו-Aoede נוטים להיות נשיים ורכים יותר. ניתן להחליף קול בכל שלב ולייצר בלוק חדש כדי לשמוע את ההבדל.

🧠 הגדרות עיבוד טקסט (The Pipeline)

שלב זה הוא ה"מוח" של המערכת. הוא מורכב מ-4 שכבות עיבוד שמכינות את הטקסט העברי לפני שהוא נשלח להקראה. ניתן להדליק ולכבות כל שלב בנפרד:

1. הפעל מילון חריגים סטטי (Static Lexicon):

   • מה זה עושה? מבצע "מצא והחלף" מהיר ובטוח של מילים ידועות מראש (למשל הפיכת "דו"ח" ל-"דוח").
   • איך מקנפגים? פתחו את הקובץ utils/lexicon.json והוסיפו אליו כל מילה שגוגל מקריאה באופן שגוי ואת התחליף הפונטי שלה.

2. ✨ הפעל עיבוד דינמי (Gemini LLM):

   • מה זה עושה? שולח את הפסקה המקורית לסוכן בינה מלאכותית (LLM מודל gemini-2.5-flash) שמנתח אותה, פותח ראשי תיבות מורכבים לפי ההקשר, ובעיקר: מוצא מילים לועזיות טכנולוגיות שנכתבו בעברית (כמו "ווטסאפ" או "אינטרנט") וכותב אותן באנגלית ("WhatsApp") כדי שהקריין של ה-TTS יעבור אוטומטית למבטא לועזי מושלם כשהוא מגיע אליהן.
   • למה לשים לב? פעולה זו מוסיפה כ-2-3 שניות לזמן העיבוד.

3. הפעל ניקוד אוטומטי (Nakdan API):

   • מה זה עושה? שולח את הטקסט למנוע הניקוד המתקדם והמדויק של Dicta.
   • למה צריך את זה? מנועי TTS מתקשים להבין הקשר בעברית ללא ניקוד (למשל: בֹּקֶר לעומת בָּקָר). הניקוד "נועל" את ההגייה של גוגל ומבטיח שהיא תקרא בדיוק את המילה שהתכוונתם אליה. מומלץ להשאיר דולק תמיד.

4. המר מספרים למילים (num2words):

   • מה זה עושה? סורק את הטקסט, מחפש ספרות (למשל 3) והופך אותן למילים מפורשות (שלוש). מונע מצב שבו מנוע ה-TTS מנסה לקרוא מספרים באנגלית או צורה שבורה.

---

🔄 איך משתמשים במערכת (זרימת העבודה / Workflow)

המערכת בנויה בצורה של "בלוקים" (Cells), כדי שתוכלו לקרוא ולעבד טקסטים ארוכים פסקה אחר פסקה, מבלי לדרוס מידע קודם:

1. הזנת קלט: בתוך הבלוק הרלוונטי (למשל "בלוק 1"), כותבים או מדביקים את הטקסט המקורי בתוך התיבה העליונה ("טקסט מקורי"). (טיפ: אם תשימו # לפני שורה, המערכת תזהה שזו כותרת ותכריח את הקריין לעשות פאוזה ארוכה ומשמעותית אחריה).
2. עיבוד: לוחצים על הכפתור "עבד טקסט". המערכת תפעיל את כל הפילטרים והניקוד שבחרתם בסרגל ההגדרות.
3. עריכה סופית (Manual Override): הטקסט המוכן והמנוקד יופיע בתיבה התחתונה. כאן הכוח בידיים שלכם! תוכלו לעבור על הטקסט, לתקן שגיאות ניקוד ספציפיות, לשנות מילה פה ושם, או להוסיף פסיק שישנה את קצב הקריאה.
4. יצירת אודיו: לחצו על "🎙️ הפוך לדיבור (שלח ל-Gemini)".
5. תוצאה והמשך עבודה: לאחר מספר שניות, נגן האודיו יופיע ויתחיל להתנגן. תחתיו יופיע כפתור להורדת קובץ ה-.wav למחשב. במקביל, יפתח אוטומטית בלוק חדש וריק (בלוק 2) למטה, כדי שתוכלו להמשיך להקליד את הפסקה הבאה שלכם ברצף!

תהנו! 🎉