hbuddenberg/TTS-Notify

TTS Notify v2.0.0

🎯 Modular Text-to-Speech notification system for macOS with CLI, MCP, and REST API interfaces

TTS Notify v2.0.0 is a complete rewrite featuring a modular architecture that maintains full compatibility with v1.5.0 while adding powerful new capabilities. It provides three different interfaces (CLI, MCP, REST API) that all use the same core TTS engine.

✨ What's New in v2.0.0

🏗️ Complete Modular Architecture

• Core System: 6 modular components with clean separation of concerns
• Multiple Interfaces: CLI, MCP Server, REST API - all using the same core
• Plugin Foundation: Extensible architecture for future enhancements
• 40% Code Reduction: Eliminated duplication through smart design

🎛️ Intelligent Configuration System

• 30+ Environment Variables: Complete control over all aspects
• 10+ Predefined Profiles: Ready-to-use configurations for different scenarios
• YAML Configuration Files: Human-readable configuration management
• Runtime Validation: Automatic configuration validation with helpful error messages

🚀 Enhanced Performance

• Async Support: Non-blocking operations throughout the system
• Voice Caching: Intelligent caching with configurable TTL
• Concurrent Processing: Support for multiple simultaneous requests
• Resource Optimization: Efficient memory and CPU usage

🛠️ Developer Experience

• Type Safety: Full Pydantic model validation
• Comprehensive Logging: Structured logging with JSON support
• Modern Tooling: Black, isort, mypy, pytest integration
• Cross-Platform Installers: UV-based installation for all platforms

🚀 Quick Start

Installation

🎯 Complete Installation (Recommended)

git clone https://github.com/yourusername/tts-notify.git
cd tts-notify
./installers/install.sh all

🔧 Development Mode

git clone https://github.com/yourusername/tts-notify.git
cd tts-notify
./installers/install.sh development
source venv/bin/activate

Basic Usage

CLI Interface

# Basic text-to-speech
tts-notify "Hello world"

# With specific voice and rate
tts-notify "Hola mundo" --voice monica --rate 200

# List available voices
tts-notify --list

# Save audio file
tts-notify "Test message" --save output --format wav

# System information
tts-notify --info

MCP Server (Claude Desktop)

# Start MCP server
tts-notify --mode mcp

# Automatic Claude Desktop configuration
# Voice search with natural language in Claude:
"Lee en voz alta: Hola mundo"
"Lista todas las voces en español"
"Guarda este texto como archivo: prueba de audio"

REST API

# Start API server
tts-notify --mode api

# API available at http://localhost:8000
# Interactive docs at http://localhost:8000/docs

🏗️ Architecture

TTS_Notify/
├── src/                     # Source code
│   ├── main.py              # Main orchestrator
│   ├── core/                # Core functionality (6 modules)
│   │   ├── config_manager.py    # Intelligent configuration
│   │   ├── voice_system.py      # Voice detection & management
│   │   ├── tts_engine.py        # Abstract TTS engine
│   │   ├── models.py            # Data models with validation
│   │   └── exceptions.py        # Custom exception hierarchy
│   ├── ui/                  # User interfaces
│   │   ├── cli/            # Command-line interface
│   │   ├── mcp/            # MCP server for Claude Desktop
│   │   └── api/            # REST API with FastAPI
│   ├── utils/               # Utility modules
│   ├── installer/          # Installer module
│   └── plugins/            # Plugin system foundation
├── installers/             # Installation scripts
├── tests/                  # Test suite
├── config/                 # Configuration files
└── docs/                   # Documentation

Interface Overview

⚙️ Configuration

Environment Variables

# Voice Settings (Core)
TTS_NOTIFY_VOICE=monica                    # Default voice
TTS_NOTIFY_RATE=175                        # Speech rate (WPM)
TTS_NOTIFY_LANGUAGE=es                     # Language
TTS_NOTIFY_QUALITY=enhanced                # Voice quality

# Voice Settings (Advanced)
TTS_NOTIFY_PITCH=1.0                       # Voice pitch (0.5-2.0)
TTS_NOTIFY_VOLUME=1.0                      # Voice volume (0.0-1.0)

# Functionality
TTS_NOTIFY_ENABLED=true                    # Enable TTS
TTS_NOTIFY_CACHE_ENABLED=true              # Enable voice caching
TTS_NOTIFY_LOG_LEVEL=INFO                  # Logging level

# Performance & Limits
TTS_NOTIFY_MAX_TEXT_LENGTH=5000            # Maximum text length
TTS_NOTIFY_OUTPUT_FORMAT=aiff              # Audio format

# API Server
TTS_NOTIFY_API_PORT=8000                   # API server port
TTS_NOTIFY_API_HOST=localhost              # API server host

🚀 Auto-Configured Variables: The new MCP installers automatically configure all 11 environment variables with optimal defaults for Claude Code integration.

Configuration Profiles

# Use predefined profiles
tts-notify --profile claude-desktop  # Optimized for Claude Desktop
tts-notify --profile development      # Development with debugging
tts-notify --profile production       # Production ready

🎵 Voice System

84+ Voice Support

• Automatic Detection: Discovers all system voices at startup
• Smart Categorization: Español, Enhanced, Premium, Siri, Others
• Flexible Search: Exact, partial, case-insensitive, accent-insensitive matching
• Performance: 75% faster voice detection with caching

Voice Search Examples

# Exact match
tts-notify "Test" --voice Monica

# Case-insensitive
tts-notify "Test" --voice monica

# Partial match
tts-notify "Test" --voice angel  # Finds Angélica

# Quality variants
tts-notify "Test" --voice "monica enhanced"

🧪 Development

Setup

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Code formatting
black src tests
isort src tests

# Type checking
mypy src

Testing

# All tests
pytest

# Specific modules
pytest tests/test_core.py
pytest tests/test_api.py

# With coverage
pytest --cov=src

📖 Documentation

• - Complete documentation
• - Version history and changes
• - Migration from v1.5.0
• - Development guide for Claude Code
• - Global MCP configuration guide

🔧 Installation Scripts

Cross-Platform Installers

# Main installer (Linux/macOS)
./installers/install.sh [development|production|mcp|all|uninstall]

# Windows installers
installers/install.bat [mode]
installers/install.ps1 -Mode [mode]

# Specific installers
./installers/install-cli.sh           # CLI only
./installers/install-mcp.sh            # MCP dual-mode (Claude Code + Desktop)
./installers/install-mcp-claude-code.sh # Claude Code specialized installer

🚀 NEW: Claude Code Global Installation

The installer now supports automatic global configuration for Claude Code:

# Automatic detection and configuration
./installers/install-mcp.sh

# Specialized Claude Code installer (recommended)
./installers/install-mcp-claude-code.sh

# Interactive mode with voice selection
./installers/install-mcp-claude-code.sh --interactive

# Non-interactive mode
./installers/install-mcp-claude-code.sh --non-interactive --voice "Siri Female (Spanish Spain)" --rate 175

Features:

• ✅ Global Configuration: Available in ALL Claude Code projects automatically
• ✅ 11 Environment Variables: Complete configuration with all recommended settings
• ✅ Smart Detection: Automatically detects Claude Code and optimal paths
• ✅ Fallback Support: Maintains Claude Desktop compatibility
• ✅ Interactive Setup: Choose voice, rate, and options during installation

📊 Performance

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Install development dependencies: ./installers/install.sh development
4. Make changes with tests
5. Run tests: pytest
6. Format code: black src tests && isort src tests
7. Commit changes: git commit -m "Add amazing feature"
8. Push branch: git push origin feature/amazing-feature
9. Open Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🔗 Links

• Homepage: https://github.com/yourusername/tts-notify
• Documentation: https://github.com/yourusername/tts-notify#readme
• Issues: https://github.com/yourusername/tts-notify/issues
• Changelog: https://github.com/yourusername/tts-notify/blob/main/CHANGELOG.md

TTS Notify v2.0.0 - 🎯 Modular, Powerful, and Ready for Production!