Ai Voice

Hybrid Voice Architecture: Platform + OpenAI TTS

Enable AI agents to express themselves with natural voice synthesis through intelligent engine selection. Supports both zero-config platform voices and premium OpenAI TTS with automatic fallback.

✨ Features

🌩️ Hybrid Architecture

• Platform TTS: Zero-config system voices (macOS, Windows, Linux)
• OpenAI TTS: Premium cloud-based synthesis when API key provided
• Intelligent Selection: Automatic engine selection with graceful fallback
• Asynchronous Processing: Non-blocking voice synthesis

🎭 Voice Options

• Platform Voices: 34+ languages with quality optimization
• OpenAI Voices: 6 premium voices (alloy, echo, fable, onyx, nova, shimmer)
• Quality Modes: Standard (tts-1) and HD (tts-1-hd)
• Speed Control: 0.25x to 4.0x playback speed

🔄 Smart Fallback

• OpenAI → Platform fallback on errors
• Graceful degradation without workflow interruption
• Comprehensive error handling and logging
• Background playback: Audio plays directly without opening windows or applications

🚀 Quick Start

Installation

npm install -g @sylweriusz/mcp-ai-voice

Environment Configuration (.env)

For easier configuration, copy the example environment file:

cp .env.example .env

Edit .env with your settings:

# Required for OpenAI TTS
OPENAI_API_KEY=sk-your-actual-api-key-here

# Optional customizations
DEFAULT_TTS_VOICE=nova          # Your preferred OpenAI voice
DEFAULT_TTS_MODEL=tts-1-hd      # Higher quality model
DEFAULT_TTS_SPEED=1.2           # Slightly faster speech

Claude Desktop Configuration

Basic Setup (Platform TTS only)

{
  "mcpServers": {
    "ai-voice": {
      "command": "npx",
      "args": ["@sylweriusz/mcp-ai-voice"]
    }
  }
}

Hybrid Setup (Platform + OpenAI TTS)

Option 1: Environment Variables

{
  "mcpServers": {
    "ai-voice": {
      "command": "npx",
      "args": ["@sylweriusz/mcp-ai-voice"],
      "env": {
        "OPENAI_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}

Option 2: Using .env file (Recommended)

{
  "mcpServers": {
    "ai-voice": {
      "command": "npx",
      "args": ["@sylweriusz/mcp-ai-voice"]
    }
  }
}

Note: Ensure your .env file is in the project directory with OPENAI_API_KEY configured.

🎮 Usage Examples

Basic Voice Expression

// Simple usage - auto-selects best engine
say("Hello! I'm excited to help you today!")

// Platform-specific language
say("Witam! Jak się masz?", { language: "pl" })

// macOS Easter Egg - exact voice names
say("Welcome to the future!", { language: "Fred" })

OpenAI TTS Usage

// Use OpenAI with default settings
say("This uses premium OpenAI synthesis!", { useOpenAI: true })

// Specific OpenAI voice and model
say("Deep, authoritative voice", {
  useOpenAI: true,
  openaiVoice: "onyx",
  openaiModel: "tts-1-hd"
})

// Speed control
say("Speaking at double speed!", {
  useOpenAI: true,
  openaiSpeed: 2.0
})

// Warm female voice with HD quality
say("Natural, engaging conversation", {
  useOpenAI: true,
  openaiVoice: "nova",
  openaiModel: "tts-1-hd"
})

Engine Selection Strategy

// Force platform engine (even if OpenAI available)
say("Using system voice", { useOpenAI: false })

// Auto-selection (prefers OpenAI if available)
say("Best available quality")

// Fallback demonstration
say("This will use OpenAI, but fall back to platform on error", {
  useOpenAI: true
})

🎭 Voice Characteristics

OpenAI Voices

• alloy: Balanced, versatile voice
• echo: Clear, direct masculine voice ⭐ (Default)
• fable: Expressive, storytelling voice
• onyx: Deep, authoritative masculine voice
• nova: Warm, engaging feminine voice
• shimmer: Bright, energetic feminine voice

Platform Voices

• macOS: Premium system voices with heritage options
• Windows: SAPI voices with quality detection
• Linux: espeak voices with language optimization

⚙️ Configuration

Environment Variables

# Required for OpenAI TTS
OPENAI_API_KEY=sk-your-api-key-here

# Optional: Default voice preference (OpenAI)
DEFAULT_TTS_VOICE=echo

# Optional: Audio player command override
AUDIO_PLAYER_COMMAND=vlc

Tool Parameters

{
  text: "Required text to synthesize",
  
  // Platform engine options
  language: "pl",           // Language code or macOS voice name
  
  // OpenAI engine options
  useOpenAI: true,          // Force OpenAI engine
  openaiVoice: "nova",      // OpenAI voice selection
  openaiModel: "tts-1-hd",  // Quality: tts-1 or tts-1-hd
  openaiSpeed: 1.5          // Speed: 0.25 to 4.0
}

🏗️ Architecture

Hybrid Engine Selection

1. API Key Check: OpenAI available if OPENAI_API_KEY provided
2. User Preference: useOpenAI parameter overrides auto-selection
3. Auto-Selection: Prefers OpenAI when available
4. Fallback: OpenAI errors trigger platform engine fallback
5. Platform Backup: Always available as reliability baseline

Performance Optimization

• Asynchronous Processing: Non-blocking synthesis
• Background Audio: Direct audio playback without opening windows or applications
• Cleanup Management: Automatic temporary file cleanup
• Error Resilience: Graceful degradation on API issues

🛠️ Development

Build from Source

git clone https://github.com/sylweriusz/mcp-ai-voice.git
cd mcp-ai-voice
npm install
npm run build
npm start

Testing Hybrid Setup

# Test platform engine only
node dist/index.js

# Test with OpenAI (requires API key)
OPENAI_API_KEY=sk-... node dist/index.js

📊 Monitoring

The system provides comprehensive logging:

🎵 AI Voice v1.2.0 - Hybrid Voice Architecture
🔍 Initializing voice ecosystem...
📊 Engine Status:
   🎯 Platform TTS: Available
   🌩️ OpenAI TTS: Available
   ⭐ Preferred: OPENAI
📡 Hybrid voice synthesis ready
🎯 Platform: darwin

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature-name
3. Test hybrid functionality with both engines
4. Submit pull request with test cases

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• Repository: https://github.com/sylweriusz/mcp-ai-voice
• NPM Package: https://www.npmjs.com/package/@sylweriusz/mcp-ai-voice
• Issues: https://github.com/sylweriusz/mcp-ai-voice/issues
• OpenAI TTS Documentation: https://platform.openai.com/docs/api-reference/audio/createSpeech

---

🎵 Express yourself vocally - the hybrid way!