voice-mode 0.1.24__tar.gz

voice_mode-0.1.24/.gitignore

@@ -0,0 +1,85 @@
+# Environment configuration
+.env.local
+.env
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.so
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.tox/
+*.cover
+*.py,cover
+
+# Virtual environments
+venv/
+env/
+.venv/
+test-env/
+test-pkg-env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Logs
+*.log
+logs/
+*.err
+
+# Temporary files
+tmp/
+temp/
+.tmp/
+*.tmp
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+.eggs/
+*.whl
+
+# Test artifacts
+test_output/
+*.mp3
+*.wav
+*.pcm
+.aider*
+
+# Voice MCP specific
+voice-mcp_recordings/
+debug_recordings/
+
+# Documentation build
+docs/_build/
+docs/promote/
+
+# Local configuration
+.claude/settings.local.json
+
+# Node modules (for livekit frontend)
+node_modules/
+.npm/
+
+# Misc
+.cache/
+*.bak
+*.orig

voice_mode-0.1.24/CHANGELOG.md

@@ -0,0 +1,165 @@
+# Changelog
+
+All notable changes to voice-mcp will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.24] - 2025-06-17
+
+## [0.1.23] - 2025-06-17
+
+### Added
+- Provider registry system MVP for managing TTS/STT providers
+  - Dynamic provider discovery and registration
+  - Automatic availability checking
+  - Feature-based provider filtering
+- Dual package name support (voice-mcp and voice-mode)
+  - Both commands now available in voice-mode package
+  - Maintains backward compatibility
+- Service management tools for Kokoro TTS:
+  - `start_kokoro` - Start the Kokoro TTS service using uvx
+  - `stop_kokoro` - Stop the running Kokoro service
+  - `kokoro_status` - Check service status with CPU/memory usage
+- Automatic cleanup of services on server shutdown
+- psutil dependency for process monitoring
+- `list_tts_voices` tool to list all available TTS voices by provider
+  - Shows OpenAI standard and enhanced voices with characteristics
+  - Lists Kokoro voices with descriptions
+  - Includes usage examples and emotional speech guidance
+  - Checks API/service availability for each provider
+- Voice-chat slash command improvements for better argument handling
+
+### Changed
+- Default TTS voices updated: alloy for OpenAI, af_sky for Kokoro
+
+## [0.1.22] - 2025-06-16
+
+### Added
+- Local STT/TTS configuration support in .mcp.json
+- Split TTS metrics into generation and playback components for better performance insights
+  - Tracks TTS generation time (API call) separately from playback time
+  - Displays metrics as tts_gen, tts_play, and tts_total
+
+### Changed
+- Modified text_to_speech() to return (success, metrics) tuple
+- Updated all tests to handle new TTS return format
+
+## [0.1.21] - 2025-06-16
+
+### Added
+- VOICE_MCP_SAVE_AUDIO environment variable to save all TTS/STT audio files
+- Audio files saved to ~/voice-mcp_audio/ with timestamps
+- Documentation about gpt-4o-mini-tts being best for emotional speech
+- Warning to never use coral voice and default to af_sky for Kokoro
+
+### Changed
+- Voice parameter changed from Literal to str for flexibility in voice selection
+
+## [0.1.20] - 2025-06-15
+
+### Changed
+- Voice parameter changed from Literal to str type for more flexibility
+
+## [0.1.19] - 2025-06-15
+
+### Added
+- TTS provider selection parameter to converse function ("openai" or "kokoro")
+- Auto-detection of TTS provider based on voice selection
+- Support for multiple TTS endpoints with provider-specific clients
+
+## [0.1.18] - 2025-06-15
+
+### Changed
+- Removed mcp-neovim-server from .mcp.json configuration
+
+## [0.1.17] - 2025-06-15
+
+### Changed
+- Minor version bump (no functional changes)
+
+## [0.1.16] - 2025-06-15
+
+## [0.1.16] - 2025-06-15
+
+### Added
+- Voice parameter to converse function for dynamic TTS voice selection
+- Support for Kokoro voices: af_sky, af_sarah, am_adam, af_nicole, am_michael
+- Python 3.13 support with conditional audioop-lts dependency
+
+### Fixed
+- BrokenResourceError when concurrent voice operations interfere with MCP stdio communication
+- Enhanced sounddevice stderr redirection workaround to prevent stdio corruption
+- Added concurrency lock to serialize audio operations and prevent race conditions
+- Protected stdio file descriptors during audio recording and playback operations
+- Added anyio.BrokenResourceError to exception handling for MCP disconnections
+- Configure pytest to exclude manual test scripts from CI builds
+
+## [0.1.15] - 2025-06-14
+
+### Fixed
+- Removed load_dotenv call that was causing import error
+
+## [0.1.14] - 2025-06-14
+
+### Fixed
+- Updated GitHub workflows for new project structure
+
+## [0.1.13] - 2025-06-14
+
+### Added
+- Performance timing in voice responses showing TTS, recording, and STT durations
+- Local STT/TTS documentation for Whisper.cpp and Kokoro
+- CONTRIBUTING.md with development setup instructions
+- CHANGELOG.md for tracking changes
+
+### Changed
+- Refactored from python-package subdirectory to top-level Python package
+- Moved MCP server symlinks from mcp-servers/ to bin/ directory
+- Updated wrapper script to properly resolve symlinks for venv detection
+- Improved signal handlers to prevent premature exit
+- Configure build to only include essential files in package
+
+### Fixed
+- Audio playback dimension mismatch when adding silence buffer
+- MCP server connection persistence (was disconnecting after each request)
+- Event loop cleanup errors on shutdown
+- Wrapper script path resolution for symlinked execution
+- Critical syntax errors in voice-mcp script
+
+### Removed
+- Unused python-dotenv dependency
+- Temporary test files (test_audio.py, test_minimal_mcp.py)
+- Redundant test dependencies in pyproject.toml
+- All container/Docker support
+
+## [0.1.12] - 2025-06-14
+
+### Added
+- Kokoro TTS support with configuration examples
+- Export examples in .env.example for various setups
+- Centralized version management and automatic PyPI publishing
+
+### Changed
+- Simplified project structure with top-level package
+
+## [0.1.11] - 2025-06-13
+
+### Added
+- Initial voice-mcp implementation
+- OpenAI-compatible STT/TTS support
+- LiveKit integration for room-based voice communication
+- MCP tool interface with converse, listen_for_speech, check_room_status, and check_audio_devices
+- Debug mode with audio recording capabilities
+- Support for multiple transport methods (local microphone and LiveKit)
+
+## [0.1.0 - 0.1.10] - 2025-06-13
+
+### Added
+- Initial development and iteration of voice-mcp
+- Basic MCP server structure
+- OpenAI API integration for STT/TTS
+- Audio recording and playback functionality
+- Configuration via environment variables

voice_mode-0.1.24/PKG-INFO

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: voice-mode
+Version: 0.1.24
+Summary: Voice interaction capabilities for Model Context Protocol (MCP) servers (also available as voice-mcp)
+Project-URL: Homepage, https://github.com/mbailey/voice-mcp
+Project-URL: Repository, https://github.com/mbailey/voice-mcp
+Project-URL: Issues, https://github.com/mbailey/voice-mcp/issues
+Author-email: mbailey <mbailey@example.com>
+License: MIT
+Keywords: ai,livekit,llm,mcp,speech,stt,tts,voice
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: audioop-lts; python_version >= '3.13'
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx
+Requires-Dist: numpy
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pydub
+Requires-Dist: scipy
+Requires-Dist: simpleaudio
+Requires-Dist: sounddevice
+Requires-Dist: uv>=0.4.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: twine>=4.0.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# voice-mcp - Voice Mode for Claude Code
+
+A Model Context Protocol (MCP) server that enables voice interactions with Claude and other LLMs. Requires only an OpenAI API key and microphone/speakers.
+
+## 🖥️ Compatibility
+
+**Runs on:** Linux • macOS • Windows (WSL) | **Python:** 3.10+ | **Tested:** Ubuntu 24.04 LTS, Fedora 42
+
+## ✨ Features
+
+- **🎙️ Voice conversations** with Claude - ask questions and hear responses
+- **🔄 Multiple transports** - local microphone or LiveKit room-based communication  
+- **🗣️ OpenAI-compatible** - works with any STT/TTS service (local or cloud)
+- **⚡ Real-time** - low-latency voice interactions with automatic transport selection
+- **🔧 MCP Integration** - seamless with Claude Desktop and other MCP clients
+
+## 🎯 Simple Requirements
+
+**All you need to get started:**
+
+1. **🔑 OpenAI API Key** (or compatible service) - for speech-to-text and text-to-speech
+2. **🎤 Computer with microphone and speakers** OR **☁️ LiveKit server** ([LiveKit Cloud](https://docs.livekit.io/home/cloud/) or [self-hosted](https://github.com/livekit/livekit))
+
+## Quick Start
+
+Setup for Claude Code:
+
+```bash
+export OPENAI_API_KEY=your-openai-key
+claude mcp add voice-mcp uvx voice-mcp
+claude
+```
+
+Try: *"Let's have a voice conversation"*
+
+## 🎬 Demo
+
+Watch voice-mcp in action:
+
+[![voice-mcp Demo](https://img.youtube.com/vi/aXRNWvpnwVs/maxresdefault.jpg)](https://www.youtube.com/watch?v=aXRNWvpnwVs)
+
+## Example Usage
+
+Once configured, try these prompts with Claude:
+
+- `"Let's have a voice conversation"`
+- `"Ask me about my day using voice"`
+- `"Tell me a joke"` (Claude will speak and wait for your response)
+- `"Say goodbye"` (Claude will speak without waiting)
+
+The new `converse` function makes voice interactions more natural - it automatically waits for your response by default.
+
+## Claude Desktop Setup
+
+Add to your Claude Desktop configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+<details>
+<summary>Using uvx (recommended)</summary>
+
+```json
+{
+  "mcpServers": {
+    "voice-mcp": {
+      "command": "uvx",
+      "args": ["voice-mcp"],
+      "env": {
+        "OPENAI_API_KEY": "your-openai-key"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>Using pip install</summary>
+
+```json
+{
+  "mcpServers": {
+    "voice-mcp": {
+      "command": "voice-mcp",
+      "env": {
+        "OPENAI_API_KEY": "your-openai-key"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+## Tools
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `converse` | Have a voice conversation - speak and optionally listen | `message`, `wait_for_response` (default: true), `listen_duration` (default: 10s), `transport` (auto/local/livekit) |
+| `listen_for_speech` | Listen for speech and convert to text | `duration` (default: 5s) |
+| `check_room_status` | Check LiveKit room status and participants | None |
+| `check_audio_devices` | List available audio input/output devices | None |
+| `start_kokoro` | Start the Kokoro TTS service | `models_dir` (optional, defaults to ~/Models/kokoro) |
+| `stop_kokoro` | Stop the Kokoro TTS service | None |
+| `kokoro_status` | Check the status of Kokoro TTS service | None |
+
+**Note:** The `converse` tool is the primary interface for voice interactions, combining speaking and listening in a natural flow.
+
+## Configuration
+
+**📖 See [docs/configuration.md](docs/configuration.md) for complete setup instructions for all MCP hosts**
+
+**📁 Ready-to-use config files in [config-examples/](config-examples/)**
+
+### Quick Setup
+
+The only required configuration is your OpenAI API key:
+
+```bash
+export OPENAI_API_KEY="your-key"
+```
+
+### Optional Settings
+
+```bash
+# Custom STT/TTS services (OpenAI-compatible)
+export STT_BASE_URL="http://localhost:2022/v1"  # Local Whisper
+export TTS_BASE_URL="http://localhost:8880/v1"  # Local TTS
+export TTS_VOICE="alloy"                        # Voice selection
+
+# LiveKit (for room-based communication)
+# See docs/livekit/ for setup guide
+export LIVEKIT_URL="wss://your-app.livekit.cloud"
+export LIVEKIT_API_KEY="your-api-key"
+export LIVEKIT_API_SECRET="your-api-secret"
+
+# Debug mode
+export VOICE_MCP_DEBUG="true"
+
+# Save all audio (TTS output and STT input)
+export VOICE_MCP_SAVE_AUDIO="true"
+```
+
+## Local STT/TTS Services
+
+For privacy-focused or offline usage, voice-mcp supports local speech services:
+
+- **[Whisper.cpp](docs/whisper.cpp.md)** - Local speech-to-text with OpenAI-compatible API
+- **[Kokoro](docs/kokoro.md)** - Local text-to-speech with multiple voice options
+
+These services provide the same API interface as OpenAI, allowing seamless switching between cloud and local processing.
+
+### OpenAI API Compatibility Benefits
+
+By strictly adhering to OpenAI's API standard, voice-mcp enables powerful deployment flexibility:
+
+- **🔀 Transparent Routing**: Users can implement their own API proxies or gateways outside of voice-mcp to route requests to different providers based on custom logic (cost, latency, availability, etc.)
+- **🎯 Model Selection**: Deploy routing layers that select optimal models per request without modifying voice-mcp configuration
+- **💰 Cost Optimization**: Build intelligent routers that balance between expensive cloud APIs and free local models
+- **🔧 No Lock-in**: Switch providers by simply changing the `BASE_URL` - no code changes required
+
+Example: Simply set `OPENAI_BASE_URL` to point to your custom router:
+```bash
+export OPENAI_BASE_URL="https://router.example.com/v1"
+export OPENAI_API_KEY="your-key"
+# voice-mcp now uses your router for all OpenAI API calls
+```
+
+The OpenAI SDK handles this automatically - no voice-mcp configuration needed!
+
+## Architecture
+
+```
+┌─────────────────────┐     ┌──────────────────┐     ┌─────────────────────┐
+│   Claude/LLM        │     │  LiveKit Server  │     │  Voice Frontend     │
+│   (MCP Client)      │◄────►│  (Optional)      │◄────►│  (Optional)         │
+└─────────────────────┘     └──────────────────┘     └─────────────────────┘
+         │                            │
+         │                            │
+         ▼                            ▼
+┌─────────────────────┐     ┌──────────────────┐
+│  Voice MCP Server   │     │   Audio Services │
+│  • converse         │     │  • OpenAI APIs   │
+│  • listen_for_speech│◄────►│  • Local Whisper │
+│  • check_room_status│     │  • Local TTS     │
+│  • check_audio_devices    └──────────────────┘
+└─────────────────────┘
+```
+
+## Troubleshooting
+
+### Common Issues
+
+- **No microphone access**: Check system permissions for terminal/application
+- **UV not found**: Install with `curl -LsSf https://astral.sh/uv/install.sh | sh`
+- **OpenAI API error**: Verify your `OPENAI_API_KEY` is set correctly
+- **No audio output**: Check system audio settings and available devices
+
+### Debug Mode
+
+Enable detailed logging and audio file saving:
+
+```bash
+export VOICE_MCP_DEBUG=true
+```
+
+Debug audio files are saved to: `~/voice-mcp_recordings/`
+
+### Audio Saving
+
+To save all audio files (both TTS output and STT input):
+
+```bash
+export VOICE_MCP_SAVE_AUDIO=true
+```
+
+Audio files are saved to: `~/voice-mcp_audio/` with timestamps in the filename.
+
+## License
+
+MIT