yemot-speech 0.1.5

Speech-to-Text and Text-to-Speech library for Yemot HaMashiach systems

Yemot Speech

ספריית Python להמרת שמע לטקסט (STT) וטקסט לשמע (TTS) עבור מערכות ימות המשיח. Python library for Speech-to-Text (STT) and Text-to-Speech (TTS) for Yemot HaMashiach systems.

✨ תכונות עיקריות / Features

• 🎯 ממשק אחיד - API פשוט ואחיד לכל ספקי ה-STT וה-TTS
• 🌐 תמיכה בספקים מרובים - OpenAI, Google Cloud, Amazon, Azure, מודלים מקומיים
• 🎤 Speech-to-Text - המרת שמע לטקסט עם ספקים שונים
• 🔊 Text-to-Speech - המרת טקסט לשמע עם קולות איכותיים
• 🇮🇱 אופטימיזציה לעברית - הגדרות מותאמות לעברית ומערכות ימות המשיח
• 📞 תמיכה בשיחות טלפון - הגדרות מותאמות לקבצי שמע מטלפוניה
• 🔧 גמישות מלאה - תמיכה בקבצים, bytes, וזרמי נתונים
• 🏃‍♂️ קל לשימוש - התחל עם שורה אחת של קוד

🚀 התקנה / Installation

התקנה בסיסית / Basic Installation

pip install yemot-speech
# or
uv add yemot-speech

התקנה עם ספקים ספציפיים / Installation with Specific Providers

# התקנה עם OpenAI Whisper
pip install yemot-speech[openai]
uv add yemot-speech[openai]

# התקנה עם Google Cloud Speech
pip install yemot-speech[google]
uv add yemot-speech[google]

# התקנה עם Amazon Transcribe
pip install yemot-speech[amazon]
uv add yemot-speech[amazon]

# עבור מודלים מקומיים
pip install yemot-speech[local]
uv add yemot-speech[local]

# עבור Text-to-Speech (המרת טקסט לשמע)
pip install yemot-speech[tts]
uv add yemot-speech[tts]

# עבור TTS ספציפי
pip install yemot-speech[tts-openai]    # OpenAI TTS
pip install yemot-speech[tts-amazon]    # Amazon Polly
pip install yemot-speech[tts-azure]     # Azure Cognitive Services

# התקנה עם כל הספקים
pip install yemot-speech[all]
uv add yemot-speech[all]

# התקנה עם מספר ספקים ספציפיים
pip install yemot-speech[openai,google]
uv add yemot-speech[openai,google]

התקנת תלויות בנפרד / Manual Dependencies Installation

# עבור OpenAI Whisper
pip install openai>=1.0.0

# עבור Google Cloud Speech
pip install google-cloud-speech>=2.0.0

# עבור Amazon Transcribe
pip install boto3>=1.26.0

# עבור מודלים מקומיים
pip install openai-whisper>=20230314 SpeechRecognition>=3.10.0

📖 שימוש בסיסי / Basic Usage

🎯 שימוש מהיר / Quick Usage

STT - המרת שמע לטקסט / Speech-to-Text

from yemot_speech import transcribe

# המרה מהירה עם OpenAI
text = transcribe(
    'audio.wav',
    provider='openai',
    api_key='your-api-key',
    language='he'
)
print(text)

TTS - המרת טקסט לשמע / Text-to-Speech

from yemot_speech import synthesize, speak

# יצירת קובץ שמע
audio_file = synthesize(
    'שלום עליכם! ברוכים הבאים למערכת ימות המשיח',
    provider='gtts',
    output_file='greeting.mp3'
)

# השמעה ישירה
speak('שלום וברכה לכולם', provider='gtts')

🔧 שימוש מתקדם / Advanced Usage

from yemot_speech import STT

# יצירת אובייקט STT
stt = STT(
    provider='openai',
    api_key='your-openai-api-key'
)

# המרת קובץ שמע
text = stt.transcribe('path/to/audio.wav', language='he')
print(f"Transcribed: {text}")

# המרת bytes
with open('audio.wav', 'rb') as f:
    audio_bytes = f.read()
text = stt.transcribe_bytes(audio_bytes, language='he')

🛠️ ספקי STT זמינים / Available STT Providers

1. OpenAI Whisper (מומלץ / Recommended)

stt = STT(
    provider='openai',
    api_key='your-api-key',
    model='whisper-1'
)

# עם הגדרות מתקדמות
text = stt.transcribe(
    'audio.wav',
    language='he',
    temperature=0.2,
    prompt='שיחה טלפונית בעברית'
)

2. Google Cloud Speech

stt = STT(
    provider='google',
    credentials_path='path/to/credentials.json',
    language_code='he-IL'
)

# עבור שיחות טלפון
text = stt.transcribe(
    'call.wav',
    encoding='MULAW',
    sample_rate=8000,
    model='phone_call'
)

3. Amazon Transcribe

stt = STT(
    provider='amazon',
    aws_access_key_id='your-key-id',
    aws_secret_access_key='your-secret-key',
    region_name='us-east-1',
    bucket_name='your-s3-bucket'
)

text = stt.transcribe(
    'audio.wav',
    language_code='he-IL',
    enable_speaker_identification=True
)

4. מודל מקומי / Local Models

# שימוש ב-Whisper מקומי
stt = STT(
    provider='local',
    engine='whisper',
    model_name='medium'
)

text = stt.transcribe('audio.wav', language='hebrew')

📞 שימוש עם מערכות ימות המשיח / Yemot HaMashiach Integration

המרת שיחות טלפון / Phone Call Transcription

from yemot_speech import STT

# הגדרה אופטימלית לשיחות ימות המשיח
stt = STT(
    provider='google',
    credentials_path='credentials.json',
    language_code='he-IL'
)

# המרת קובץ שיחה (בדרך כלל WAV או μ-law)
def transcribe_yemot_call(audio_file_path):
    text = stt.transcribe(
        audio_file_path,
        encoding='MULAW',  # או 'LINEAR16' לפי סוג הקובץ
        sample_rate=8000,   # תדירות נפוצה בטלפוניה
        language_code='he-IL',
        enable_automatic_punctuation=True,
        model='phone_call'
    )
    return text

# דוגמה
result = transcribe_yemot_call('yemot_recording.wav')
print(f"תוכן השיחה: {result}")

עיבוד מקובלי קבצים / Batch Processing

import os
from yemot_speech import STT

def process_yemot_recordings(directory_path):
    stt = STT(provider='openai', api_key='your-key')
    
    results = {}
    for filename in os.listdir(directory_path):
        if filename.endswith(('.wav', '.mp3', '.m4a')):
            file_path = os.path.join(directory_path, filename)
            try:
                text = stt.transcribe(file_path, language='he')
                results[filename] = text
                print(f"✅ {filename}: {text[:50]}...")
            except Exception as e:
                print(f"❌ {filename}: Error - {e}")
    
    return results

# עיבוד כל הקבצים בתיקייה
recordings = process_yemot_recordings('/path/to/yemot/recordings')

🔍 מידע על ספקים / Provider Information

from yemot_speech import STT

# בדיקת ספקים זמינים
available_providers = STT.get_available_providers()
print(f"Available providers: {available_providers}")

# מידע על ספק נוכחי
stt = STT(provider='openai', api_key='test')
info = stt.get_provider_info()
print(f"Provider info: {info}")

⚙️ הגדרות מתקדמות / Advanced Configuration

הגדרה מותאמת לעברית / Hebrew-Optimized Settings

# עבור OpenAI - הגדרות אופטימליות לעברית
stt_openai = STT(
    provider='openai',
    api_key='your-key'
)

hebrew_text = stt_openai.transcribe(
    'hebrew_audio.wav',
    language='he',
    temperature=0.1,  # יציבות גבוהה יותר
    prompt='תוכן בעברית, כולל מושגים דתיים ותורניים'
)

# עבור Google Cloud - הגדרות משופרות
stt_google = STT(
    provider='google',
    credentials_path='credentials.json'
)

hebrew_text = stt_google.transcribe(
    'hebrew_audio.wav',
    language_code='he-IL',
    enable_automatic_punctuation=True,
    model='latest_long',  # מודל משופר
    use_enhanced=True     # דיוק גבוה יותר
)

טיפול בשגיאות / Error Handling

from yemot_speech import STT

def safe_transcribe(audio_file, providers=['openai', 'google', 'local']):
    """ניסיון עם מספר ספקים עד להצלחה"""
    
    for provider in providers:
        try:
            if provider == 'openai':
                stt = STT(provider='openai', api_key='your-key')
            elif provider == 'google':
                stt = STT(provider='google', credentials_path='creds.json')
            elif provider == 'local':
                stt = STT(provider='local', engine='whisper', model_name='base')
            
            return stt.transcribe(audio_file, language='he')
            
        except Exception as e:
            print(f"Provider {provider} failed: {e}")
            continue
    
    raise Exception("All providers failed")

# שימוש
try:
    result = safe_transcribe('audio.wav')
    print(f"Success: {result}")
except Exception as e:
    print(f"All transcription attempts failed: {e}")

📁 מבנה הפרוייקט / Project Structure

yemot-speech/
├── src/yemot_speech/
│   ├── __init__.py          # API ראשי
│   ├── stt.py              # מחלקה מרכזת STT
│   ├── tts.py              # מחלקה מרכזת TTS
│   ├── base.py             # מחלקות בסיס
│   └── providors/          # ספקי STT ו-TTS
│       ├── openai.py       # OpenAI Whisper (STT)
│       ├── openai_tts.py   # OpenAI TTS
│       ├── google.py       # Google Cloud Speech (STT)
│       ├── gtts.py         # Google TTS
│       ├── amazon.py       # Amazon Transcribe (STT)
│       ├── amazon_tts.py   # Amazon Polly (TTS)
│       ├── azure_tts.py    # Azure Cognitive Services (TTS)
│       └── local.py        # מודלים מקומיים
├── demo_full.py           # דמו מלא עם STT ו-TTS
├── examples.py            # דוגמאות מפורטות
├── check_install.py       # בדיקת התקנה
├── test_basic.py          # טסטים בסיסיים
├── pyproject.toml        # הגדרות פרוייקט
└── README.md             # תיעוד זה

🎯 סיכום מהיר / Quick Summary

STT - Speech to Text

from yemot_speech import STT
stt = STT(provider='openai', api_key='key')
text = stt.transcribe('audio.wav', language='he')

TTS - Text to Speech

from yemot_speech import TTS
tts = TTS(provider='gtts', language='he')
audio = tts.synthesize('שלום עליכם!')
tts.save_audio('שלום עליכם!', 'greeting.mp3')

פונקציות מהירות / Quick Functions

from yemot_speech import transcribe, synthesize, speak

# STT
text = transcribe('audio.wav', provider='openai', api_key='key')

# TTS
audio = synthesize('שלום וברכה', provider='gtts', output_file='greeting.mp3')
speak('שלום לכולם', provider='gtts')  # השמעה ישירה

🤝 תרומה לפרוייקט / Contributing

התקנה לפיתוח / Development Installation

# Clone the repository
git clone https://github.com/your-username/yemot-speech
cd yemot-speech

# Install for development
pip install -e .[dev,all]
# or with uv
uv add -e .[dev,all]

# Run tests
python test_basic.py

# Check installation
python check_install.py

בנייה ופרסום / Building and Publishing

# Make the build script executable
chmod +x build_and_publish.sh

# Build the package
./build_and_publish.sh

# Or manually:
python -m build
python -m twine upload dist/*

דוגמאות נוספות / More Examples

# Run the demo
python demo.py

# Check what providers are available
python -c "from yemot_speech import STT; print(STT.get_available_providers())"

נשמח לתרומות! אנא פתח Issue או Pull Request.

📄 רישיון / License

MIT License

🆘 תמיכה / Support

לשאלות ותמיכה:

• פתח Issue ב-GitHub
• שלח מייל למפתחים

---

💡 טיפים להתקנה / Installation Tips

עבור משתמשי uv (מהיר יותר) / For uv users (faster)

# התקנה מהירה עם uv
uv add yemot-speech[openai]
uv add yemot-speech[google,local]  # מספר ספקים
uv add yemot-speech[all]           # כל הספקים

עבור פרוייקטים קיימים / For existing projects

# הוסף לפרוייקט קיים
pip install yemot-speech[openai] --upgrade
uv add yemot-speech[openai]

# בדוק שהתקנה עבדה
python -c "from yemot_speech import STT; print('✅ Installation successful!')"

בעיות התקנה נפוצות / Common Installation Issues

# אם יש בעיות עם Google Cloud
pip install google-cloud-speech --upgrade

# אם יש בעיות עם Whisper מקומי
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
pip install openai-whisper

# עבור Apple Silicon (M1/M2)
pip install yemot-speech[local] --no-deps
pip install openai-whisper torch

📦 התקנה מהירה ושימוש / Quick Start

1. התקן עם הספק המועדף / Install with your preferred provider

# לשימוש עם OpenAI (מומלץ)
pip install yemot-speech[openai]

# לשימוש עם Google Cloud
pip install yemot-speech[google] 

# לשימוש עם מודל מקומי (ללא API keys)
pip install yemot-speech[local]

2. השתמש בקוד / Use in your code

from yemot_speech import STT

# עם OpenAI
stt = STT(provider='openai', api_key='your-api-key')
text = stt.transcribe('audio.wav', language='he')

# עם Google Cloud  
stt = STT(provider='google', credentials_path='creds.json')
text = stt.transcribe('audio.wav', language_code='he-IL')

# עבור מודל מקומי (ללא API)
stt = STT(provider='local', engine='whisper', model_name='base')
text = stt.transcribe('audio.wav', language='hebrew')

🔊 ספקי TTS זמינים / Available TTS Providers

1. Google TTS (gTTS) - מומלץ / Recommended

from yemot_speech import TTS

tts = TTS(provider='gtts', language='he')

# יצירת שמע
audio_bytes = tts.synthesize('שלום עליכם!')

# שמירה לקובץ
tts.save_audio('שלום עליכם!', 'greeting.mp3')

# השמעה ישירה (דורש pygame)
tts.play_audio('שלום עליכם!')

2. OpenAI TTS

tts = TTS(
    provider='openai',
    api_key='your-api-key',
    voice='nova'  # עובד טוב עם עברית
)

# יצירת שמע באיכות גבוהה
audio_bytes = tts.synthesize(
    'שלום וברכה לכולם',
    voice='nova',
    speed=1.0
)

3. Azure Cognitive Services TTS

tts = TTS(
    provider='azure',
    subscription_key='your-azure-key',
    region='eastus'
)

# עם קול עברי
audio_bytes = tts.synthesize(
    'ברוכים הבאים',
    voice_name='he-IL-AvigailNeural'
)

# עם SSML למרכות מתקדמות
tts.synthesize_ssml('''
<speak version="1.0" xml:lang="he-IL">
    <voice name="he-IL-AvigailNeural">
        <prosody rate="slow">שלום וברכה</prosody>
    </voice>
</speak>
''', 'greeting.wav')

4. Amazon Polly TTS

tts = TTS(
    provider='amazon',
    aws_access_key_id='your-key-id',
    aws_secret_access_key='your-secret-key'
)

# עם קול עברי (אם זמין)
audio_bytes = tts.synthesize(
    'שלום עליכם',
    voice_id='Ayelet',  # קול עברי
    language_code='he-IL'
)

3. עבור פיתוח וקוד בדיקה / For development and testing

# התקן עם כל הספקים
pip install yemot-speech[all]

📚 דוגמאות שימוש / Usage Examples

הפרויקט כולל דוגמאות מפורטות ומאורגנות בתיקיית examples/:

🎯 דוגמאות בסיסיות:

• stt_basic.py - דוגמאות STT בסיסיות עם ספקים שונים
• tts_basic.py - דוגמאות TTS בסיסיות עם ספקים שונים
• demo.py - דמו מהיר לספריה
• demo_full.py - דמו מלא עם כל התכונות

🏛️ מיוחד לימות המשיח:

• yemot_voice_system.py - מערכות קוליות מלאות (תפריטים, הודעות, שגיאות)
• stt_advanced.py - עיבוד שיחות טלפון ותפריטים אינטראקטיביים

🔄 זרימות עבודה:

• combined_workflows.py - שילוב STT+TTS בזרימות מלאות

🔗 שילוב עם Yemot:

• yemot_integration.py - שילוב מלא עם הפרויקט Yemot
• yemot_use_cases.py - מקרי שימוש נפוצים עם מערכת ימות המשיח
• YEMOT_INTEGRATION.md - מדריך מפורט לשילוב עם Yemot

הרצת הדוגמאות:

# דוגמאות בסיסיות
python examples/stt_basic.py
python examples/tts_basic.py

# מערכות ימות המשיח
python examples/yemot_voice_system.py

# שילוב עם Yemot (דורש: pip install yemot)
python examples/yemot_integration.py
python examples/yemot_use_cases.py

# דמואים מלאים
python examples/demo_full.py

הערה: הדוגמאות עובדות גם ללא API keys (במצב דמו) להדגמה.

---

Made with ❤️ for the Yemot HaMashiach community