pyttslib 0.1.0

A powerful and easy-to-use Python Text-to-Speech library with multiple engine support

🎯 PyTTSLib

🔊 A powerful and easy-to-use Python Text-to-Speech library that supports multiple TTS engines.

✨ Features

• 🎙️ Multiple TTS engine support:
  • 🖥️ pyttsx3 (offline, default) - Works without internet
  • 🌐 Google TTS - High-quality online TTS
• 🎛️ Voice customization:
  • 🏃‍♂️ Adjustable speech rate
  • 📊 Volume control
  • 👥 Multiple voice options
• 💾 Save audio to multiple formats (MP3, WAV)
• 🔄 Smart file management with auto-cleanup
• 🖥️ Cross-platform compatibility (Windows, Linux, macOS)
• 🛡️ Robust error handling
• 📝 Well-documented API

🚀 Installation

pip install pyttslib

📖 Quick Start

from pyttslib import TextToSpeech

# Create a TTS instance (default: pyttsx3 engine)
tts = TextToSpeech()

# Basic text-to-speech
tts.speak("Hello, world!")

# Use Google TTS instead
gtts = TextToSpeech(engine="google")
gtts.speak("Hello from Google Text-to-Speech!")

# Save speech to a file
tts.save_to_file("This will be saved as audio.", "output.mp3")

🎮 Advanced Usage

🎛️ Voice Configuration

# Configure pyttsx3 engine
tts = TextToSpeech(engine="pyttsx3", engine_config={
    "rate": 150,    # Words per minute
    "volume": 0.8,  # Volume level (0.0 to 1.0)
})

# Configure Google TTS
tts = TextToSpeech(engine="google", engine_config={
    "lang": "en",    # Language code
    "tld": "com",    # Top-level domain
    "slow": False    # Normal speed
})

🎭 Voice Selection

# List available voices
voices = tts.list_voices()
for voice in voices:
    print(f"Voice: {voice['name']} (ID: {voice['id']})")

# Set a specific voice
tts.set_voice("en_female_1")  # Voice ID from list_voices()

⚙️ Speech Properties

# Adjust speech rate (pyttsx3 only)
tts.set_rate(150)  # Words per minute

# Adjust volume (pyttsx3 only)
tts.set_volume(0.8)  # 80% volume

🌟 Examples

The package includes example scripts in the examples/ directory:

• 📝 basic_usage.py: Demonstrates fundamental features
• 🔧 advanced_usage.py: Shows advanced functionality

Run the examples:

python examples/basic_usage.py
python examples/advanced_usage.py

🔍 Supported Audio Formats

• 🎵 MP3 (Google TTS)
• 🔊 WAV (pyttsx3)
• 🎼 OGG (platform-dependent)
• 🎹 AIFF (platform-dependent)

🛠️ Technical Details

File Management

• 📁 Temporary files are stored in a dedicated folder
• 🧹 Automatic cleanup after playback
• 💫 Robust retry mechanism for file operations
• 🔒 Safe file handling with proper resource cleanup

Error Handling

• ⚠️ Custom exception classes for better error management
• 🔄 Automatic retries for transient failures
• 📢 Clear error messages and logging
• 🛡️ Graceful fallbacks for playback methods

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. 🍴 Fork the repository
2. 🌿 Create your feature branch (git checkout -b feature/amazing-feature)
3. 💾 Commit your changes (git commit -m 'Add amazing feature')
4. 📤 Push to the branch (git push origin feature/amazing-feature)
5. 🎯 Open a Pull Request

📄 License

MIT License - feel free to use this in your projects!

🙏 Acknowledgments

• 🎤 pyttsx3 for offline TTS
• 🌐 gTTS for Google TTS support
• 🔊 playsound for cross-platform audio playback

📞 Support

• 📧 Report issues on GitHub
• 💭 Submit feature requests
• 🤝 Pull requests are welcome

---

Made with ❤️ for the Python community