# Changelog

All notable changes to VoiceMode (formerly 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]

## [4.7.1] - 2025-09-23

### Fixed
- **CLI Commands**
  - Fix broken whisper model install command import path after services refactoring

### Changed
- **Testing**
  - Move comprehensive help test from manual to automated testing for CI coverage

## [4.7.0] - 2025-09-22

### Fixed
- **Voice Interaction**
  - Distinguish STT connection errors from genuine "no speech detected" scenarios (#62)
  - Display detailed error messages showing attempted endpoints and specific failures
  - Fix misleading "[no speech detected]" messages when services are unavailable
  - Simplify STT function architecture from 3 layers to 2
  - Clean up "Unclosed client session" asyncio warning on startup

### Added
- **Testing**
  - Add comprehensive test coverage for STT error scenarios
  - Test connection failures, authentication errors, and fallback behavior

### Documentation
- Add troubleshooting guide index with diagnostic flowchart

## [4.6.0] - 2025-09-21

### Added
- **Streamlined Installation Experience**
  - Add OpenAI API key setup with browser integration for quick start
  - Add microphone detection before voice test
  - Improve confirmation prompts with smart defaults ([Y/n] for essential, [y/N] for optional)
  - Position OpenAI as recommended quick-start path (~3 minute setup)
  - Consolidate system dependency prompts into single confirmation

- **Documentation**
  - Add comprehensive tool loading architecture documentation
  - Improve README clarity and simplify getting started
  - Add reference documentation for internal systems

### Changed
- **Installation Flow**
  - Remove local services prompt from initial setup (moved to post-install docs)
  - Focus installation on getting users to Claude Code quickly
  - Update Claude Code configuration to use `uvx --refresh` for latest version
  - Use long flags in install script for better clarity

- **Code Organization**
  - Refactor services directory structure - flatten tools directory hierarchy
  - Move service tools up one level (services/whisper/install.py → whisper_install.py)
  - Simplify tool loading logic for uniform subdirectory handling
  - Move version utilities from tools to utils module

### Fixed
- **macOS Compatibility**
  - Fix bash completion "nosort: invalid option name" error on bash 3.2
  - Remove timeout command usage (not available on macOS by default)
  - Correct microphone device counting (filter input devices only)
  - Ensure voice test works with API keys from config files
  - Simplify voice test command for better compatibility

- **Tool Loading**
  - Handle sound_fonts subdirectory with underscore in name correctly
  - Fix installer tests after services directory restructuring

## [4.5.0] - 2025-09-18

### Added
- **Enhanced STT Logging**
  - Add comprehensive logging for speech-to-text operations
  - Log provider selection and fallback attempts
  - Include transcription details and provider info in logs

- **Configuration Management**
  - Add `voicemode config edit` command for easy configuration file editing
  - Support custom editor selection via --editor flag
  - Automatically open configuration file in default editor

- **Tool Environment Variables**
  - Replace VOICEMODE_TOOLS with VOICEMODE_TOOLS_ENABLED and VOICEMODE_TOOLS_DISABLED
  - Allow fine-grained control over tool availability
  - Support comma-separated lists for enabling/disabling specific tools

### Changed
- **Provider Selection Architecture**
  - Consolidate dual provider selection systems into single simple failover approach
  - Remove SIMPLE_FAILOVER configuration - simple failover is now the only mode
  - Simplify get_tts_config and get_stt_config to use direct configuration
  - Eliminate ~400 lines of unused provider registry selection logic
  - Provider registry now only stores endpoint info without complex selection

### Fixed
- Disable OpenAI client retries for local endpoints to avoid delays
- Fix logger name consistency (voicemode vs voice-mode) for STT logging
- Prevent test_installers from killing running voice services during tests
- Update tests to work with refactored provider system
- Resolve test failures related to new environment variables

## [4.4.0] - 2025-09-10

### Added
- **MCP Registry Support**
  - Add server.json configuration for MCP registry publication
  - Add mcp-name field to README for PyPI package validation
  - Integrate MCP registry publishing into CI/CD workflow
  - Support DNS-based namespace authentication (com.failmode/voicemode)
  - Update Makefile to sync server.json version during releases
  
- **Cloudflare Worker for voicemode.sh**
  - Serve install script via custom domain
  - Smart user-agent detection for CLI vs browser
  - Cached script delivery with fallback
  
- **Selective Tool Loading**
  - Reduce token usage by loading tools on demand
  - Implement smart tool filtering based on context
  - Add tool loading configuration options

- **Documentation Improvements**
  - Complete documentation reorganization
  - Add tutorials, guides, and reference sections
  - Improve getting-started guide with clear paths
  - Add universal installer as primary quick start
  - Archive outdated documentation

- **Three Bears Agent Support**
  - Add baby-bear, mama-bear, and papa-bear agent configurations
  - Integrate with sound fonts for agent-specific audio feedback

### Changed
- Consolidate PyPI and MCP Registry publishing workflows
- Update branch references from 'main' to 'master'
- Improve Cloudflare Worker error handling and caching
- Rename hook to hooks, stdin-receiver to receiver

### Fixed
- Fix broken documentation links after refactor
- Restore minimal claude command group for hook support
- Fix Claude settings.json path configuration

## [4.3.2] - 2025-09-03

### Fixed
- Add missing pyyaml dependency to pyproject.toml
- Remove macOS-only restriction from package
- Add Claude hooks configuration to repository settings

## [4.3.1] - 2025-09-03

### Fixed
- Minor bug fixes and improvements

## [4.3.0] - 2025-09-03

### Added
- Sound fonts with MP3 support and Three Bears sounds integration

## [4.2.0] - 2025-09-03

### Added
- **🧠 Think Out Loud Mode - AI Reasoning Made Audible**
  - Revolutionary feature that transforms AI's internal thinking into spoken performances
  - Extracts and voices Claude's reasoning blocks using multiple personas
  - Herman's Head / Inside Out style multi-voice performances for different reasoning types
  - Theditor agent that orchestrates thinking performances with distinct voices
  - Makes AI decision-making transparent and engaging through voice

- **🔊 Sound Fonts Integration - Audio Feedback for Every Action**
  - Play custom sounds for tool operations, errors, and completions
  - Filesystem-based sound font system with automatic discovery
  - Claude Code integration via receiver for hook-based audio
  - CLI command `play-sound` with theme, action, and sound selection
  - Enhances user experience with auditory feedback during operations
  - MP3 support added for 90% file size reduction over WAV
  - Recursive directory copying for complete sound font structure
  - Three Bears sound fonts for baby-bear, mama-bear, and papa-bear agents
  - Sound fonts disabled by default (VOICEMODE_SOUNDFONTS_ENABLED=false)

- **🎭 Claude Code Deep Integration**
  - Extract and analyze Claude's conversation logs in real-time
  - Access Claude's internal thinking blocks for transparency
  - CLI commands for message extraction with multiple output formats
  - Automatic context detection for Claude Code sessions
  - Foundation for advanced AI introspection features

### Changed
- **Enhanced Message Extraction**
  - Generic and flexible extraction supporting full conversations
  - Multiple output formats: full messages, text only, or thinking only
  - Better filtering by message type (user/assistant)
  - Improved integration with voice mode tools

### Removed
- **Redundant get_claude_thinking MCP tool**
  - Consolidated into more powerful get_claude_messages tool

### Documentation
- **Comprehensive Think Out Loud Documentation**
  - Agent specifications for theditor
  - Claude orchestration instructions
  - Voice persona mapping guide
  - Integration patterns and examples

## [4.1.0] - 2025-09-01

### Added
- **Pronunciation middleware for TTS/STT text processing**
  - Configurable pronunciation rules system that processes text before TTS and after STT
  - Regex-based text substitution rules with YAML configuration
  - Separate TTS and STT rule sets for bidirectional corrections
  - Privacy support - rules can be marked private to hide from LLM tool listings
  - Default rules for common patterns (3M, PoE, GbE, etc.)
  - Full CLI interface for managing pronunciation rules
  - MCP tool for LLM-based rule management with `pronounce` tool
  - Integrated into converse tool for automatic text processing
  - New configuration file: `voice_mode/data/default_pronunciation.yaml`

## [4.0.1] - 2025-09-01

### Removed
- Removed `whisperx` optional dependency to fix PyPI upload compatibility
  - The dependency was specified as a Git URL which is not allowed for PyPI packages
  - WhisperX functionality was recently added and not essential for core features

## [4.0.0] - 2025-08-31

### BREAKING CHANGES
- **Unified voice configuration system**
  - **BREAKING**: Replaced `.voices.txt` files with unified `.voicemode.env` configuration
  - Changed environment variable from `VOICEMODE_TTS_VOICES` to `VOICEMODE_VOICES` for simplicity
  - Implemented cascading configuration: env vars > project configs > global config  
  - Added directory tree walking for project-specific configuration discovery
  - Supports runtime configuration reloading via MCP tools
  - **Migration Required**: Users must migrate from `.voices.txt` to `.voicemode.env` with `VOICEMODE_VOICES=voice1,voice2` format

### Added

- **Comprehensive test coverage reporting system**
  - Integration with pytest-cov for coverage measurement
  - HTML coverage reports generated in htmlcov/ directory  
  - Coverage badges and metrics for monitoring code quality
  - Automated coverage reporting in CI/CD pipeline
  
- **Word-level timestamps for transcription**
  - Enhanced transcription output with word-level timing information
  - Support for SubRip (SRT) format output with precise word timestamps
  - New transcription CLI command for processing audio files
  - Comprehensive transcription backend supporting multiple formats
  - Word timing data available for improved accessibility and analysis

- **Enhanced voice selection guide**
  - Comprehensive documentation for voice selection across different providers
  - Clear migration instructions from old `.voices.txt` system
  
### Removed  
- **Legacy voice preference system**
  - Removed 578 lines of old `voice_preferences.py` system
  - Eliminated unreliable `.voices.txt` file parsing
  - Removed associated test files for deprecated voice preference system

## [3.34.3] - 2025-08-26

### Changed
- **Service management code cleanup**
  - Removed references to non-existent `start.sh` script in Kokoro service discovery
  - Improved Kokoro start script detection by checking for GPU/CPU specific scripts only
  - Cleaned up code paths for better maintainability

## [2.34.2] - 2025-08-26

## [2.34.1] - 2025-08-26

### Fixed
- **Whisper service enable command**
  - Fixed `voicemode whisper enable` using incorrect template variable names
  - Changed from WHISPER_BIN/MODEL_FILE to START_SCRIPT_PATH/INSTALL_DIR to match plist template
  - Correctly locates start-whisper-server.sh script in whisper install directory
  - Fixes KeyError 'START_SCRIPT_PATH' when enabling whisper service after installation

### Changed
- **Installer reliability**
  - Added `--force` flag to `uv tool install --upgrade` command
  - Ensures voicemode is fully reinstalled even if already present
  - Prevents stale installations when package structure changes
  - Improves update reliability when running install.sh multiple times

## [2.34.0] - 2025-08-26

### Changed
- **Installer improvements**
  - Refactored installer to use permanent `uv tool install --upgrade` instead of `uvx --refresh`
  - Added `uv tool update-shell` for automatic PATH configuration
  - Improved shell completion detection with smart fallbacks
  - Added Homebrew zsh completion directory support on macOS
  - Implemented XDG-compliant paths for bash completions
  - Removed fish shell support to simplify maintenance (bash/zsh only)
  - Zsh completions now correctly use underscore prefix (_voicemode)
  - MCP configuration now uses plain `voice-mode` command for better performance

### Fixed
- **Service file updates on reinstall**
  - Fixed whisper and kokoro installers to always update service files (plist/systemd) even when service is already installed
  - Ensures paths are properly expanded (no `~` symbols) in service files
  - Fixes issue where broken service files with unexpanded paths would remain broken after running install.sh
  - Service files now updated to latest templates on every install, ensuring users always get working configurations

## [2.33.4] - 2025-08-26

### Fixed
- **CoreML support restoration**
  - Re-enabled CoreML acceleration after fixing plist template path issues
  - Improved CoreML compilation flags handling in whisper installer

## [2.33.3] - 2025-08-26

### Changed
- Version bump for testing installer fixes

## [2.33.2] - 2025-08-26

### Fixed
- **Whisper service installation**
  - Corrected plist template path in whisper installer
  - Fixed CoreML support compilation flags (disabled then re-enabled after testing)
  - Removed duplicate inline plist fallback to prevent template divergence

## [2.33.1] - 2025-08-26

### Fixed
- **Whisper service LaunchAgent fixes**
  - Fixed LaunchAgent plist to call start-whisper-server.sh script instead of binary directly
  - Script provides dynamic model selection via VOICEMODE_WHISPER_MODEL environment variable
  - Added proper command-line arguments (--inference-path, --threads) missing from direct binary call
  - Resolved Signal 15 (SIGTERM) restart loop caused by missing parameters

### Changed
- **Service configuration templates**
  - Refactored Whisper installer to use plist template file instead of inline generation
  - Template approach improves maintainability and makes configuration easier to find
  - Removed duplicate inline plist fallback to prevent template/code divergence
  - Templates are packaged with distribution ensuring availability

## [2.33.0] - 2025-08-26

### Fixed
- **CoreML acceleration improvements**
  - Re-enabled CoreML acceleration in installer after fixing template loading issues
  - Fixed CoreML conversion with dedicated Python environment to avoid dependency conflicts
  - Improved CoreML setup to handle PyTorch dependency management properly
  - Disabled misleading CoreML prompt temporarily while fixing PyTorch installation

- **Whisper service improvements**
  - Implemented unified Whisper startup script for Mac and Linux
  - Fixed Whisper service to respect VOICEMODE_WHISPER_MODEL setting properly
  - Changed default Whisper model from large-v2 to base for faster initial setup

- **Installer script stability**
  - Fixed script exit after Whisper installation when CoreML setup CLI check fails
  - Properly handle check_voice_mode_cli failures in setup_coreml_acceleration
  - Installer now continues with Kokoro and LiveKit even if CoreML setup encounters issues
  - Fixed installer exit issue after Whisper when checking for voicemode CLI

- **Documentation corrections**
  - Removed mention of response_duration from converse prompt to avoid confusion

### Changed
- **Web documentation improvements**
  - Updated Quick Start to use `curl -O && bash install.sh` for proper interactive prompts
  - Clarified OpenAI API key is optional and serves as backup when local services unavailable
  - Added comprehensive list of what the installer automatically configures
  - Changed example to use `claude converse` instead of interactive prompt
  - Updated README to use `/voicemode:converse` for consistent voice usage

- **Configuration updates**
  - Added voicemode MCP to Claude Code configuration for easier integration

## [2.32.0] - 2025-08-25

### Added
- **Safe shell completions in installer**
  - Re-enabled shell completion setup with runtime command availability checks
  - Completions only activate if `voicemode` command is found in PATH
  - Prevents shell startup errors when command is not available
  - Supports bash, zsh, and fish shells with safe fallback behavior

- **Interactive PyTorch installation prompt for Whisper**
  - Added `--install-torch` flag to CLI for explicit PyTorch installation
  - Interactive prompt when Core ML acceleration requires PyTorch (~2.5GB)
  - Clear user choice between Core ML acceleration and standard Metal performance

### Changed
- **CLI consistency improvements**
  - Replaced all user-facing "voice-mode" references with "voicemode"
  - Updated shell completion environment variables from `_VOICE_MODE_COMPLETE` to `_VOICEMODE_COMPLETE`
  - Removed redundant `completion` command, keeping only the superior `completions` command
  - Simplified command help text and examples for consistency
  - Logger name remains "voice-mode" for backward compatibility

### Fixed
- **Installer script reliability**
  - Fixed false positive failure detection when Whisper shows "Make clean" warning
  - Improved service installation success detection
  - Fixed incorrect `whisper model-install` command (should be `whisper model install`)
  - Removed non-existent `--auto-confirm` flag from CoreML installation

- **Clean CLI output**
  - Replaced deprecated `proc.connections()` with `proc.net_connections()` to eliminate warnings
  - Suppressed httpx INFO logging in CLI commands for cleaner output
  - All warnings and debug info still available with `--debug` flag

## [2.30.0] - 2025-08-25

### Added
- **Intelligent update command**
  - Automatic detection of installation method (UV tool, UV pip, or standard pip)
  - Uses appropriate update strategy based on installation type
  - Seamless updates regardless of how Voice Mode was installed

## [2.29.0] - 2025-08-25

### Added
- **CoreML acceleration support for Whisper on Apple Silicon**
  - Added optional dependency group 'coreml' with PyTorch and CoreMLTools
  - Enhanced whisper_model_install tool with install_torch and auto_confirm parameters
  - Automatic detection of Apple Silicon Macs with CoreML acceleration offer
  - User-friendly confirmation prompts for large (~2.5GB) PyTorch download
  - Graceful fallback to Metal acceleration if CoreML requirements not met
  - Clear instructions for enabling CoreML later if initially skipped

- **Beautiful installer experience**
  - Added Voice Mode ASCII art in Claude Code orange color
  - Enhanced preamble with clear value proposition and privacy messaging
  - Early system detection with special recognition for Apple Silicon
  - Professional presentation with centered text and visual hierarchy

### Fixed
- **Improved converse tool documentation**
  - Simplified listen_duration parameter documentation
  - Removed confusing duration recommendations that led to unnecessary overrides
  - Clarified that silence detection handles timing well with sensible defaults
  - Reduces cognitive load and prevents token waste from explicit duration settings

## [2.28.3] - 2025-08-24

### Fixed
- **Parameter type handling for MCP tools**
  - Fixed vad_aggressiveness parameter to accept string values from LLMs
  - Fixed port parameters in kokoro_install and livekit_install
  - Fixed lines parameter in service management tool
  - All numeric parameters now properly convert strings to integers
  - Addresses systemic issue where Claude Code MCP client passes strings

- **Installer script uvx command corrections**
  - Fixed MCP configuration to use correct command `uvx voice-mode` (without --refresh)
  - Installer now always refreshes to latest version at start
  - Removed unnecessary --refresh flags from runtime commands
  - Updated user-facing command examples to show correct usage

## [2.28.2] - 2025-08-24

### Added
- **Configurable audio feedback pip delays**
  - Added VOICEMODE_PIP_LEADING_SILENCE and VOICEMODE_PIP_TRAILING_SILENCE environment variables
  - Allows customization of silence before and after audio feedback chimes
  - Configurable via converse tool parameters pip_leading_silence and pip_trailing_silence
  - Helps prevent audio cutoff on Bluetooth devices and other audio systems with delay

### Fixed
- **Audio feedback for Bluetooth devices**
  - Added silence buffer before chimes to prevent Bluetooth audio cutoff
  - Improved compatibility with devices that have audio activation delay
  - Better audio feedback experience across different output devices

## [2.28.1] - 2025-08-24

### Added
- **Standardized project naming as VoiceMode MCP**
  - Consistent branding across all documentation and code
  - Updated project descriptions and metadata
  - Renamed internal references from "voice-mode" to "VoiceMode MCP"
  - Maintains backward compatibility with existing installations

### Fixed
- **CoreML fallback for whisper.cpp on Apple Silicon**
  - Added proper error handling when CoreML models fail to load
  - Automatically falls back to CPU processing if CoreML initialization fails
  - Prevents whisper-server crashes on systems with CoreML issues
  - Improves reliability on various macOS configurations

## [2.28.0] - 2025-08-23

### Added
- **Comprehensive CLI help support**
  - Added `-h` and `--help` options to all CLI commands and subcommands
  - Consistent help functionality across all command groups (kokoro, whisper, livekit, config, etc.)
  - Help options available for both groups and individual commands
  - Improved user experience with quick access to command documentation

- **Core ML support for whisper.cpp installation**
  - Whisper install now uses CMake instead of Make for better control
  - Automatically enables Core ML support on Apple Silicon Macs
  - Provides ~3x faster encoding performance with Core ML acceleration
  - Core ML models automatically converted during installation
  - Falls back gracefully if Core ML conversion fails
  
- **Enhanced whisper status command**
  - Shows whisper.cpp version information
  - Displays Core ML support status (enabled/disabled)
  - Shows if Core ML model is active for current model
  - Reports GPU acceleration type (Metal/CUDA)
  - Helper utility in `whisper_version.py` for capability detection
  
- **Audio conversion optimization for local whisper**
  - Automatically detects truly local whisper (not SSH-forwarded)
  - Skips WAV to MP3 conversion for local whisper, sending WAV directly
  - Adds timing measurements for audio format conversion
  - Logs conversion time at INFO level for performance monitoring
  - Significantly reduces STT processing time for local deployments
  
- **Whisper model benchmark command**
  - New `whisper model benchmark` CLI command
  - Compares performance across multiple models
  - Shows load time, encode time, and total processing time
  - Calculates real-time factor for each model
  - Fixed timing output by removing --no-prints flag
  - Helps users choose optimal model for speed/accuracy tradeoffs
  - Provides personalized recommendations based on results

### Fixed
- **MCP server configuration**
  - Fixed .mcp.json to use `uv run voicemode` for local development
  - Removed hardcoded paths for better portability
  - Works correctly with project-local development version
  
- **Whisper model management**
  - Fixed model active command to properly update configuration
  - Fixed naming conflict in model install CLI command
  - Benchmark now correctly shows timing information
  - Core ML conversion errors are now properly reported and handled

## [2.27.0] - 2025-08-20

### Added
- **CLI version and update commands**
  - New `voice-mode version` command to display current version
  - New `voice-mode update` command to upgrade to latest version
  - Comprehensive bats tests for version and update functionality
  - Automatic version detection from package metadata
  
- **Shell completion support for CLI**
  - New `voice-mode completion` command group with bash, zsh, and fish subcommands
  - Automatic tab completion for all commands, options, and arguments
  - Install.sh automatically configures shell completions during setup
  - Native Click completion mechanism for dynamic suggestions
  
- **Parallel operations documentation**
  - Documented `wait_for_response=False` pattern in converse tool
  - Enables speaking while performing other operations simultaneously
  - Creates more natural conversations by eliminating dead air
  - Marked as RECOMMENDED pattern with clear usage examples
  
- **Comprehensive Whisper model management system**
  - New `whisper models` CLI command to list all available models with status
  - `whisper model active` command to get/set the active model  
  - `whisper model install` and `whisper model remove` commands
  - Model registry with complete size/hash metadata for all Whisper models
  - Color-coded output showing installed/available models (green=installed, yellow=selected)
  - Support for English-only models and all multilingual variants
  - Automatic Core ML conversion on Apple Silicon for improved performance
  - Shell completion support for all model management commands
  
- **MCP tools for model management**
  - `list_models` tool to list all available Whisper models with status
  - Enhanced `download_model` tool with registry validation
  - Force download option to re-download corrupted models
  - Skip Core ML option for testing
  - Parity between CLI and MCP interfaces
  
- **Infrastructure improvements**
  - Centralized model registry in `whisper/models.py` with all model metadata
  - Model categorization: tiny, base, small, medium, large, turbo
  - Size information for all models (39MB to 3.1GB)
  - SHA256 hashes for integrity verification
  - Shared download logic extracted to helpers module
  - Dynamic Click-based shell completions replacing static files
  - Comprehensive test suite for model management

### Changed
- **Configuration file naming**
  - Renamed `.voicemode.env` to `voicemode.env` (removed leading dot)
  - Added backwards compatibility to check for old filename
  - Shows deprecation warning when old filename is used
  - Updated all documentation to reference new filename
  - Updated systemd service templates
  
- Replaced static shell completions with Click-generated dynamic completions
- Shell completion files now generated from CLI structure
- Whisper model downloads now use centralized registry for validation
- Model status checks now verify both file existence and selection

### Fixed
- **macOS installation improvements**
  - Added coreutils dependency for timeout command support
  - Fixed duplicate launchctl load in service installers
  - Improved zsh PATH configuration by sourcing profile after UV/npm additions
  - Skip sudo prompts on macOS to prevent installation issues
  
- **Test suite fixes**
  - Fixed deprecation warning appearing in help output
  - Renamed deprecated `.voicemode.env` to `voicemode.env` to fix test failures
  
- Whisper model management now properly uses voicemode.env configuration file
- Test suite updated for all API changes and return value structures
- Resolved all CI test failures related to service status and diagnostics

### Removed
- Old static shell completion files  
- SERVICE_COMMANDS.md (replaced by integrated CLI commands)
- Shell aliases file (functionality moved to Click commands)

## [2.26.0] - 2025-08-18

### Added
- **CLI converse command** - Direct voice conversations from the command line
  - New `voice-mode converse` command for testing voice interactions
  - Supports all MCP tool options (voice, speed, audio format, etc.)
  - Continuous conversation mode with `--continuous` flag
  - Useful for testing TTS/STT services without MCP client
  - Full control over voice parameters and silence detection
  
### Changed
- **Gitignore update** - Added `*.prof` files to gitignore for profiling output

## [2.25.1] - 2025-08-18

### Fixed
- **WSL2 detection display** - Fixed incorrect WSL2 label on non-WSL systems
  - Parameter expansion bug was showing "(WSL2)" on all Linux systems
  - Now properly checks if IS_WSL equals "true" before adding WSL2 label
  - Fixes false positive on Fedora and other Linux distributions
  - Complements previous detection fix from 2025-08-17

## [git push origin -v2.25.0] - 2025-08-18

## [2.25.0] - 2025-08-18

### Fixed
- **uvx command refresh flag** - Add --refresh flag to all uvx commands in installer
  - Ensures latest version is always fetched when running voice-mode commands
  - Fixes issues with cached old versions being used
  - Applies to service installation, uninstallation, and status commands
- **Performance optimization** - Significantly improved help command performance
  - Lazy load heavy imports (numpy, scipy, webrtcvad) only when needed
  - Help command now runs 10x faster (from ~1.5s to ~0.15s)
  - Faster MCP server startup time for better user experience
- **Config path expansion** - Fixed tilde expansion for user home directories
  - Configuration paths now properly expand `~` to user home directory
  - Fixes issues with paths like `~/Models/kokoro` not being found
  - Added comprehensive tests for path expansion functionality
- **Frontend imports** - Corrected import statements to use single module
  - Fixed import errors in livekit frontend commands
  - All frontend commands now properly import from frontend module

## [2.24.0] - 2025-08-16

### Added
- **Enhanced Voice Activity Detection** - Improved silence detection behavior
  - VAD now waits indefinitely for speech before starting silence detection
  - No more timeouts when user hasn't started speaking yet
  - Silent recordings are not sent to STT, reducing API costs and preventing hallucinations
  - Returns "No speech detected" message instead of processing silence
  - Significantly improves user experience for voice interactions
- **VAD debugging mode** - Comprehensive debugging for Voice Activity Detection
  - New `VOICEMODE_VAD_DEBUG` environment variable enables detailed VAD logging
  - Shows real-time speech detection decisions, state transitions, and timing
  - Helps diagnose issues where recording stops before speech or cuts off early
  - Added test script `scripts/test-vad-enhancement.py` for VAD testing
  - Documented in `docs/vad-debugging.md` with common issues and solutions

## [2.23.0] - 2025-08-16

### Added
- **`skip_tts` parameter** - Dynamic control over text-to-speech in converse tool
  - Add optional `skip_tts` parameter to override global `VOICEMODE_SKIP_TTS` setting
  - When `True`: Skip TTS for faster text-only responses
  - When `False`: Always use TTS regardless of environment setting
  - When `None` (default): Follow `VOICEMODE_SKIP_TTS` environment variable
  - Enables LLM to intelligently choose between voice and text-only responses
- **`VOICEMODE_SKIP_TTS` environment variable** - Global TTS skip configuration
  - Set to `true` for permanent text-only mode (faster responses)
  - Can be overridden per-call with `skip_tts` parameter
  - Useful for rapid development iterations or when voice isn't needed

### Fixed
- **Service status detection** - Correctly identify SSH-forwarded vs locally running services
  - SSH processes listening on service ports are now recognized as port forwards
  - Status command now shows 🔄 for forwarded services vs ✅ for local services
  - Prevents confusion about where services are actually running

## [2.22.3] - 2025-08-16

### Fixed
- **Service auto-enable error** - Fix 'FunctionTool' object is not callable
  - Changed whisper and kokoro installers to use `enable_service` function instead of MCP tool
  - Services can now be properly auto-enabled after installation
- **Whisper build errors** - Remove obsolete make server command
  - whisper-server is now built as part of the main build target
  - Removed unnecessary build step that was causing errors
- **Build output verbosity** - Suppress cmake/make output unless debugging
  - Build output is now captured and only shown on errors
  - Use VOICEMODE_DEBUG=true to see full build output
  - Significantly cleaner installation experience

## [2.22.2] - 2025-08-16

### Fixed
- **CLI deprecation warnings** - Suppress known warnings for cleaner output
  - Hide audioop, pkg_resources, and psutil deprecation warnings by default
  - Warnings can be shown with `VOICEMODE_DEBUG=true` or `--debug` flag
  - Improves user experience when running CLI commands and MCP server
  - Applies to both direct CLI usage and MCP server invocations

## [2.22.1] - 2025-08-16

### Fixed
- **Package size reduction** - Exclude unnecessary files from wheel distribution
  - Exclude `__pycache__`, `node_modules`, `.next/cache` directories
  - Exclude test files, logs, and build artifacts
  - Remove overly broad shared-data section that included entire frontend
  - Significantly reduces installed package size
- **Install.sh service detection** - Fix service command availability check
  - Handle Python deprecation warnings that were causing false negatives
  - Check for actual help output content instead of just exit code
  - Services now install correctly when warnings are present
  - Add `--help` and `--debug` flags for better troubleshooting
  - Support `DEBUG=true` environment variable

## [2.22.0] - 2025-08-16

### Added
- **LiveKit service integration** - Complete support for LiveKit as a managed service
  - Install/uninstall LiveKit server with `voice-mode livekit install/uninstall`
  - Service management commands: `start/stop/status/restart/enable/disable/logs`
  - Frontend management for LiveKit Voice Assistant UI
  - Configurable host/port settings for frontend
  - SSL configuration examples and documentation
  - Production-ready frontend build support
  - Bash completions for all new commands
- **Service installation in install.sh** - Automated service setup during installation
  - Offers to install Whisper, Kokoro, and LiveKit services
  - Quick mode (Y) installs all services automatically
  - Selective mode (s) allows choosing individual services
  - Uses `uvx voice-mode` for robust operation on fresh systems
  - Cross-platform support for Linux and macOS
- **Install.sh automated testing** - Comprehensive test suite (temporarily skipped)
  - Unit tests for individual bash functions
  - Functional tests with environment mocking
  - Integration tests for complete installation flows
  - Foundation for future testing improvements
- **Documentation improvements**
  - YubiKey touch detector setup guide
  - LiveKit SSL configuration examples
  - Install.sh robustness analysis
  - Service installation feature documentation

### Fixed
- **LiveKit local development** - Added dummy API key support for local services
- **Frontend dependency handling** - Improved error messages and dependency resolution
- **Service enable command** - Resolved frontend service enable command issues
- **LiveKit WebSocket URL** - Hardcoded to wss://x1:8443 for reliable connections

### Changed
- **Whisper default port** - Updated from 2000 to 2022 in shell aliases
- **Install.sh robustness** - Always use `uvx voice-mode` for consistency
- **Test infrastructure** - Skip failing tests temporarily to maintain green CI

## [2.21.1] - 2025-08-13

- Late update to changelog for release 2.21.0

## [2.21.0] - 2025-08-13

### Added
- **CLI service commands** - New subcommands for managing Whisper and Kokoro services
  - `voice-mode service whisper start/stop/status/restart/enable/disable/logs`
  - `voice-mode service kokoro start/stop/status/restart/enable/disable/logs`
  - `voice-mode service whisper update-service-files` - Update systemd/launchd service files
  - `voice-mode service kokoro update-service-files` - Update systemd/launchd service files
  - Unified interface for controlling both STT and TTS services
  - Direct access to service management without needing MCP client
  - Consistent behavior across Linux (systemd) and macOS (launchd)

## [2.20.1] - 2025-08-11

### Fixed
- **Speed parameter validation error** - Fixed MCP validation error when passing speed parameter as string
  - Added type conversion from string to float for speed parameter
  - Now properly handles speed values passed by MCP clients (e.g., via uvx)
  - Added comprehensive validation and error messages for invalid speed values

## [2.20.0] - 2025-08-10

### Added
- **VAD aggressiveness control**
  - New `vad_aggressiveness` parameter in converse tool for controlling Voice Activity Detection sensitivity (0-3)
  - 0 = least aggressive filtering (more permissive), 3 = most aggressive (strict)
  - Allows adapting to different environments: quiet rooms (0-1) vs noisy environments (2-3)
  - Also configurable via VOICEMODE_VAD_AGGRESSIVENESS environment variable

### Changed
- **Improved VAD documentation**
  - Clarified that aggressiveness controls how strictly VAD filters out non-speech
  - Updated examples to better demonstrate appropriate use cases
  - Fixed configuration documentation that had backwards descriptions

## [2.19.0] - 2025-08-10

### Added
- **MCP prompt command: /release-notes**
  - New command to display recent changelog entries directly in Claude Code
  - Shows 5 most recent versions by default (configurable with parameter)
  - Parses and formats CHANGELOG.md for easy reading
  - Inspired by Claude Code's own /release-notes feature
  - Includes comprehensive test coverage

### Fixed
- Release notes prompt now handles empty string parameters correctly
- Command works properly with both source and installed packages
- Changelog is now accessible as an MCP resource when package is installed

### Changed
- Release notes output format now matches Claude Code's clean, minimal style
- Removed decorative headers and footers for cleaner terminal output
- Release notes displayed in chronological order (oldest first)

## [2.18.0] - 2025-08-10

### Added
- **TTS speed control**
  - New `speed` parameter in converse tool for controlling speech rate (0.25 to 4.0)
  - Currently supported by Kokoro TTS and any OpenAI-compatible services that support speed
  - Examples: 0.5 = half speed, 2.0 = double speed
  - Based on user request in issue #15

## [2.17.3] - 2025-08-07

### Fixed
- **STT audio saving with simple failover**
  - Fixed critical bug where STT audio files were not being saved when VOICEMODE_SIMPLE_FAILOVER=true
  - Simple failover now properly saves audio recordings before processing
  - Ensures consistent audio archival behavior across all failover modes

### Changed
- **Post-release improvements from 2.17.2**
  - Improved installer output formatting when Voice Mode is already configured
  - Fixed installer test that was failing due to complex mock setup
  - GitHub release notes now feature universal installer as primary installation method
  - Manual installation methods (pip, claude mcp) moved to subsection

## [2.17.2] - 2025-07-29

### Added
- **Universal installer script** for automatic setup
  - Single command installation: `curl -O https://getvoicemode.com/install.sh && bash install.sh`
  - Cross-platform support: Linux (Ubuntu/Fedora), macOS, and Windows WSL
  - Automatic dependency installation (Node.js, audio libraries, etc.)
  - Claude Code installation and Voice Mode MCP configuration
  - WSL2-specific audio setup and troubleshooting guidance
  - Symlink in project root for easy access: `./install.sh`
- **Centralized GPU detection utility**
  - Unified GPU detection across platforms (Metal, CUDA, ROCm)
  - Automatic selection of GPU vs CPU scripts for services
  - Intelligent fallback when specific scripts are missing
- **Service robustness improvements**
  - Systemd services now use `Restart=on-failure` instead of `Restart=always`
  - Added `RestartPreventExitStatus=127` to prevent restart loops when executables are missing
  - Services fail cleanly when installation directory is moved or deleted

### Changed
- **Installation improvements**
  - Installer now detects `ffmpeg` by command presence on Fedora (handles RPM Fusion installs)
  - Fixed installer exiting early due to `dnf check-update` exit codes
  - Automatic fallback for older Claude Code versions without `--scope` flag support
  - Better handling of existing Voice Mode configurations
- **Documentation updates**
  - README now emphasizes Claude Code and AI code editors as primary audience
  - Quick Start section leads with automatic installer
  - Clarified that OpenAI API key is optional (local services available)
  - Added clear explanation of free, open-source alternatives

### Fixed
- **Configuration directory creation**
  - Removed redundant `config/` directory creation (config stored in `voicemode.env`)
  - Fixed issue where services created unexpected directory structures
- **Claude Code compatibility**
  - Fixed `claude mcp list` and `claude mcp add` for versions without `--scope` support
  - Installer now works with all Claude Code versions

### Developer
- Added comprehensive tests for GPU detection and missing script scenarios
- Updated service file versions to 1.1.1 with improved systemd configuration

## [2.17.1] - 2025-07-29

## [2.17.0] - 2025-07-29

### 🎯 Major Voice Activity Detection Improvement
- **Dramatically improved silence detection accuracy** by fixing audio resampling bug
  - VAD was receiving corrupted audio due to improper downsampling from 24kHz to 16kHz
  - Now uses proper signal resampling instead of simple truncation
  - Results in significantly better speech/silence detection and fewer false positives
  - Background noise (fans, traffic) is now properly filtered out

### Added
- **Automatic configuration file loading**
  - Voice Mode now creates `~/.voicemode/voicemode.env` on first run
  - Template file includes all available settings with documentation
  - Environment variables always take precedence over file settings
  - Secure file permissions (0600) automatically set
- **Enhanced conversation logs with provider tracking (Schema v3)**
  - Added `provider_url` and `provider_type` fields to track which endpoint handled requests
  - Added detailed timing metrics: TTFA, generation time, playback time, transcription time
  - Moved conversation logs to `logs/conversations/` subdirectory for better organization
- **Year/month directory structure for audio files**
  - Audio files now saved in `audio/YYYY/MM/` structure to prevent flat directory issues
  - Automatic date extraction from filenames
  - Backward compatible with existing flat structure
- Development version detection with git info for better debugging
- Service file update capability for systemd/launchd services
- Complete service health check implementation
  - Services can report readiness status
  - Better failover decisions based on actual service health
- Enhanced service management with unified `service` tool
- Auto-installation of cmake dependency for whisper.cpp on macOS
- Simple failover mode for provider selection
  - New `VOICEMODE_SIMPLE_FAILOVER` environment variable (default: true)
  - Try each endpoint in order without health checks
  - Immediate failover on connection refused errors
  - No performance penalty as connection failures are instant

### Changed
- **Major project structure reorganization**
  - Moved external dependencies to `vendor/` directory (industry standard naming)
    - `bin/livekit-admin-mcp` → `vendor/livekit-admin-mcp/`
    - `livekit/` → `vendor/livekit-voice-assistant/`
  - Moved development docs to `docs/development/`
    - `DUAL_PACKAGE_NAMES.md`, `TESTING-CHECKLIST.md`
    - `insights/` → `docs/development/insights/`
  - Moved test files from root to `tests/` directory
  - Merged `config-examples/` into `docs/integrations/`
  - Removed directories moved to shadow repository: `assets/`, `notebooks/`, `npm-voicemode/`
  - Cleaned up root directory following Python best practices
  - Moved `testing/` to `docs/testing/` for manual testing procedures
  - Removed backup files (`.mcp.json-20250728`) and temporary files (`COMMIT-MESSAGE.txt`)
  - Removed outdated `.env.example` from root (superseded by auto-generated config)
- Renamed `conversation.py` to `converse.py` for consistency
- Reorganized service directory structure for better maintainability
- Consolidated service management prompts and documentation
- Separated MCP templates and data from resources
- **Improved configuration documentation**
  - Added comprehensive configuration reference guide
  - Documented auto-generation of `~/.voicemode/voicemode.env`
  - Clarified that environment variables take precedence over file settings
- **Configuration management now uses user-level config only**
  - Removed project-level `voicemode.env` support for security
  - All configuration stored in `~/.voicemode/voicemode.env`

### Fixed
- Fixed `wait_for_response=false` being ignored in converse tool
  - Added proper string-to-boolean conversion for MCP parameters
- Fixed critical TTS failover issue when Kokoro is stopped
  - Simple failover now maps Kokoro voices to OpenAI-compatible voices
  - af_sky → nova, af_alloy → alloy, etc.
  - Prevents "Failed to speak message" errors when primary TTS is unavailable
- Fixed provider failover issues when local services are stopped
  - Previously, stopping a service (like Kokoro) would cause "All TTS providers failed" errors
  - Now correctly fails over to next available endpoint (e.g., OpenAI)
- Removed unnecessary soundfile dependency from simple failover
- Fixed various import issues with TTS_VOICES and TTS_MODELS
- **Fixed whisper model download tool**
  - Now correctly checks `~/.voicemode/services/whisper/` installation path
  - Support for both new and legacy whisper installation locations
  - Fixed model type validation

## [2.16.0] - 2025-07-28 [YANKED]

### Added
- Version management for whisper.cpp and kokoro-fastapi services
  - Track installed versions and support upgrades
  - Install only tagged releases by default (not latest commits)
  - `version` parameter added to install tools
  - Version info displayed in service status
- Uninstall tools for whisper and kokoro services
  - Clean removal of services and optionally models/data
  - Automatic service stop before uninstall
- Migration helpers for old service naming conventions
  - Automatically migrate from old naming (e.g., whisper-server) to new (whisper)
  - Built into installers, no separate tool needed

### Changed
- Reorganized helper functions from tools/ to utils/
  - `voice_mode/tools/services/common.py` → `voice_mode/utils/services/common.py`
  - `voice_mode/tools/services/*/helpers.py` → `voice_mode/utils/services/*_helpers.py`
  - `voice_mode/tools/services/version_helpers.py` → `voice_mode/utils/version_helpers.py`
  - Helper functions are no longer exposed as MCP tools

### Fixed
- Fixed test failures caused by version management implementation
  - Fixed version parsing bug with mixed int/string comparisons
  - Updated test mocks to use correct import paths
  - Made subprocess mocks command-specific to avoid breaking git commands
- Fixed unified service test failures
  - Added missing subprocess.run and Path.exists mocks
  - Fixed incomplete Popen mock setup

## [2.15.0] - 2025-07-23

## [2.14.0] - 2025-07-20

### Added
- New `VOICEMODE_DEFAULT_LISTEN_DURATION` environment variable to customize default listening time (defaults to 120s)

### Changed
- Changed default listen_duration parameter from 45s to 120s for more natural conversations
- Updated recommended listen durations in converse tool documentation
  - Normal conversational responses: 20s → 30s
  - Open-ended questions: 30s → 60s
  - Detailed explanations: 100s → 120s (now the default)
  - Stories or long explanations: 300s (unchanged)
  - Provides more generous time for users giving longer responses
- **BREAKING**: Voice preference files renamed from `voices.txt` to `.voices.txt`
  - Now uses hidden files to avoid cluttering project directories
  - Affects both standalone files and those in `.voicemode` directories

### Fixed
- Improved error messages when OpenAI API key is missing to provide helpful guidance
  - Now explicitly mentions need to set OPENAI_API_KEY or use local services
  - Differentiates between missing API key and other connection failures

## [2.13.0] - 2025-07-14

### Added
- Unified CLI system with shared exchanges library
  - New `voicemode` command with multiple subcommands (`show`, `tell`, `diagnose`, etc.)
  - Centralized exchange processing library for consistent behavior across scripts
  - Modular command architecture for easy extension
- Enhanced exchange logging capabilities:
  - STT entries logged even when no speech is detected for better debugging
  - Real-time logging of both TTS and STT exchanges
  - Split timing metrics between STT and TTS for accurate performance attribution
  - Additional metadata in exchange logs for better analysis

### Changed
- Migrated all standalone scripts to use the unified CLI system
  - Scripts now accessible as subcommands of the main `voicemode` command
  - Consistent argument parsing and help documentation across all commands
  - Improved code reuse through shared libraries

### Fixed
- Fixed undefined `audio_path` variable in STT logging
- Fixed incorrect hardcoded audio format in STT logs (now uses actual format)

## [2.12.0] - 2025-07-06

### Fixed
- Fixed TypeError in `refresh_provider_registry` tool that prevented TTS service detection (#6)
  - Changed incorrect `url=` parameter to `base_url=` when creating EndpointInfo objects
  - Added unit tests to prevent regression

## [2.11.0] - 2025-07-06

### Added
- Password protection for LiveKit voice assistant frontend
  - Prevents unauthorized access to voice conversation interface
  - Configurable via `LIVEKIT_ACCESS_PASSWORD` environment variable
  - Includes `.env.local.example` template with secure defaults
  - Password validation on API endpoint before token generation
- Prominent language support guidance in conversation tool
  - Clear language-specific voice recommendations for 8 languages
  - Mandatory voice selection for non-English text
  - Warning about American accent when using default voices
  - Examples for Spanish, French, Italian, Portuguese, Chinese, Japanese, and Hindi

### Changed
- Updated convention paths from `.conventions/` to `docs/conventions/` in CLAUDE.md
- Enhanced language voice selection documentation with explicit requirements

### Documentation
- Added Spanish voice conversation example demonstrating language-specific voice selection
- Added blind community outreach contacts and resources for accessibility collaboration
- Updated LiveKit frontend README with password protection instructions

## [2.10.0] - 2025-07-06

### Added
- All 67 Kokoro TTS voices now available for local text-to-speech
  - Complete set of high-quality voices across multiple accents and languages
  - Voices include various English accents (American, British, Australian, Indian, Nigerian, Scottish)
  - Multiple voices per accent for variety (e.g., 9 American female, 13 American male voices)
  - Support for international English speakers
  - Automatically available when Kokoro TTS service is running
- Voice preference files support for project and user-level voice settings
  - Supports both standalone `voices.txt` and `.voicemode/voices.txt` files
  - Automatic discovery by walking up directory tree from current working directory
  - User-level fallback to `~/voices.txt` or `~/.voicemode/voices.txt`
  - Standalone files take precedence over .voicemode directory files
  - Simple text format with one voice name per line
  - Comments and empty lines supported
  - Preferences take priority over environment variables
- New `check_audio_dependencies` MCP tool for diagnosing audio system setup
  - Checks for required system packages on Linux/WSL
  - Verifies PulseAudio status
  - Provides platform-specific installation commands
  - Helpful for troubleshooting audio initialization errors
- Enhanced audio error handling with helpful diagnostics
  - Detects missing system packages and suggests installation commands
  - WSL-specific guidance for audio setup
  - Better error messages when audio recording fails

### Fixed
- Mock voice preferences in provider selection tests to prevent test pollution
- Skip conversation browser playback test when Flask is not installed

### Documentation
- Updated Roo Code integration guide with comprehensive MCP interface instructions
- Added visual guide to MCP settings and troubleshooting section
- Added comprehensive Voice Preferences section to configuration documentation
- Updated README with voice preference file examples
- Updated Ubuntu/Debian installation instructions to include all required audio packages (pulseaudio, libasound2-plugins)
- Added WSL2-specific note in README pointing to detailed troubleshooting guide

## [2.9.0] - 2025-07-03

### Added
- Version logging on server startup for better debugging and support

### Fixed
- Cleaned up debug output by removing duplicate print statements
- Suppressed known upstream deprecation warnings from dependencies:
  - pydub SyntaxWarnings for invalid escape sequences
  - audioop deprecation (already handled with audioop-lts for Python 3.13+)
  - pkg_resources deprecation in webrtcvad
- Converted debug print statements to proper logger calls

## [2.8.0] - 2025-07-03

### Changed
- Changed default `min_listen_duration` from 1.0 to 2.0 seconds to provide more time for users to think before responding

## [2.7.1] - 2025-07-03

### Changed
- Changed default `min_listen_duration` from 0.0 to 1.0 seconds to prevent premature cutoffs

## [2.7.1] - 2025-07-03

### Fixed
- Fixed failing test for stdio restoration on recording error
- Added Flask to project dependencies for conversation browser script

## [2.7.0] - 2025-07-03

### Added
- Minimum listen duration control for voice responses
  - New `min_listen_duration` parameter in `converse()` tool (default: 0.0)
  - Prevents silence detection from stopping recording before minimum duration
  - Useful for preventing premature cutoffs when users need thinking time
  - Works alongside existing `listen_duration` (max) parameter
  - Validates that min_listen_duration <= listen_duration
  - Examples:
    - Complex questions: 2-3 seconds minimum
    - Open-ended prompts: 3-5 seconds minimum
    - Quick responses: 0.5-1 second minimum

## [2.6.0] - 2025-06-30

### Changed
- Updated Discord link to new community server
- Increased default listen duration to 45 seconds for better user experience
- Fixed config import issue in conversation tool
- Improved FFmpeg detection for MCP mode

### Added
- Screencast preparation materials including title cards
- Initial screencast planning documentation

## [2.5.1] - 2025-06-28

## [2.5.0] - 2025-06-28

### Added
- Automatic silence detection for voice recording
  - Uses WebRTC VAD (Voice Activity Detection) to detect when user stops speaking
  - Automatically stops recording after configurable silence threshold (default: 1000ms)
  - Significantly reduces latency for short responses (e.g., "yes" now takes ~1s instead of 20s)
  - Configurable via environment variables:
    - `VOICEMODE_ENABLE_SILENCE_DETECTION` - Enable/disable feature (default: true)
    - `VOICEMODE_VAD_AGGRESSIVENESS` - VAD sensitivity 0-3 (default: 2)
    - `VOICEMODE_SILENCE_THRESHOLD_MS` - Silence duration before stopping (default: 1000)
    - `VOICEMODE_MIN_RECORDING_DURATION` - Minimum recording time (default: 0.5s)
  - Added `disable_vad` parameter to converse() for per-interaction control
  - Automatic fallback to fixed-duration recording if VAD unavailable or errors occur
  - Comprehensive test suite and manual testing tools
  - Full documentation in docs/silence-detection.md
- Voice-first provider selection algorithm
  - TTS providers are now selected based on voice availability rather than base URL order
  - Ensures Kokoro is automatically selected when af_sky voice is preferred
  - Added provider_type field to EndpointInfo for clearer provider identification
  - Improved model selection to respect provider capabilities
  - Comprehensive test coverage for voice-first selection logic
- Configurable initial silence grace period
  - New `VOICEMODE_INITIAL_SILENCE_GRACE_PERIOD` environment variable (default: 4.0s)
  - Prevents premature cutoff when users need time to think before speaking
  - Gives users more time to start speaking before VAD stops recording
- Trace-level debug logging
  - Enabled with `VOICEMODE_DEBUG=trace` environment variable
  - Includes httpx and openai library debug output
  - Writes to `~/.voicemode/logs/debug/voicemode_debug_YYYY-MM-DD.log`
  - Helps diagnose provider connection issues

### Fixed
- Fixed WebRTC VAD sample rate compatibility issue
  - VAD requires 8kHz, 16kHz, or 32kHz but voice_mode uses 24kHz
  - Implemented proper sample extraction for VAD processing
  - Silence detection now works correctly with 24kHz audio
- Added automatic STT (Speech-to-Text) failover mechanism
  - STT now automatically tries all configured endpoints when one fails
  - Matches the existing TTS failover behavior for consistency
  - Prevents complete STT failure when primary endpoint has connection issues
- Implemented optimistic endpoint initialization
  - All endpoints now assumed healthy at startup instead of pre-checked
  - Endpoints only marked unhealthy when they actually fail during use
  - Prevents false negatives from overly strict health checks
  - Added optimistic mode to refresh_provider_registry tool (default: True)
- Fixed EndpointInfo attribute naming bug
  - Renamed 'url' to 'base_url' for consistency across codebase
  - Fixed AttributeError that was preventing STT failover from working
- Fixed Kokoro TTS not being selected despite being available
  - Provider registry now initializes with known Kokoro voices
  - Enables automatic Kokoro selection when af_sky is preferred
- Prevented microphone indicator flickering on macOS
  - Changed from start/stop recording for each interaction to continuous stream
  - Microphone stays active during voice session preventing UI flicker
  - More responsive recording start times

### Changed
- Replaced all localhost URLs with 127.0.0.1 for better IPv6 compatibility
  - Prevents issues with SSH port forwarding on dual-stack systems
  - Affects TTS, STT, and LiveKit default URLs throughout codebase

### Removed
- Cleaned up temporary and development files
  - Removed unused debug scripts and test files
  - Removed obsolete documentation and analysis files

### Planned
- In-memory buffer for conversation timing metrics
  - Track full conversation lifecycle including Claude response times
  - Maintain recent interaction history without persistent storage
  - Enable better performance analysis and debugging
- Sentence-based TTS streaming
  - Send first sentence to TTS immediately while rest is being generated
  - Significant reduction in time to first audio (TTFA)
  - More responsive conversation experience

## [2.4.1] - 2025-06-25

## [2.4.0] - 2025-06-25

### Added
- Unified event logging system for tracking voice interaction events
  - JSONL format for easy parsing and analysis
  - Automatic daily log rotation
  - Thread-safe async file writing
  - Session-based event grouping
  - Configurable via `VOICEMODE_EVENT_LOG_ENABLED` and `VOICEMODE_EVENT_LOG_DIR`
- Event types tracked:
  - TTS events: request, start, first audio, playback start/end, errors
  - Recording events: start, end, saved
  - STT events: request, start, complete, no speech, errors
  - System events: session start/end, transport switches, provider switches
- Automatic timing metric calculation from event timestamps
- Integration with conversation flow for accurate performance tracking
- Provider management tools for voice-mode
  - `refresh_provider_registry` tool to manually update health checks
  - `get_provider_details` tool to inspect specific endpoints
  - Support for filtering by service type (tts/stt) or specific URL
- Automatic TTS failover support in conversation tools
  - Systematic failover through all configured endpoints
  - Failed endpoints marked as unhealthy for automatic exclusion
  - Better error tracking and debugging information

### Changed
- TTS provider selection algorithm now uses URL-priority based selection
  - Iterates through TTS_BASE_URLS in preference order
  - Supports both voice and model preference matching
  - More predictable provider selection behavior
- Default TTS configuration updated for local-first experience
  - Kokoro (127.0.0.1:8880) prioritized over OpenAI
  - Default voices: af_sky, alloy (available on both providers)
  - Model preference order: gpt-4o-mini-tts, tts-1-hd, tts-1
- Voice parameter selection guidelines added to CLAUDE.md
  - Encourages auto-selection over manual specification
  - Clear examples of when to specify parameters

### Fixed
- Negative response time calculation in conversation metrics
  - Response time now correctly measured from end of recording
  - Event-based timing provides more accurate measurements

### Removed
- VOICE_ALLOW_EMOTIONS environment variable (emotional TTS now automatic with gpt-4o-mini-tts)

## [2.3.0] - 2025-06-23

### Added
- Comprehensive uv/uvx documentation (`docs/uv.md`)
  - Installation and version management guide
  - Development setup instructions
  - Integration with Claude Desktop
- Documentation section in README with organized links to all guides
- WSL2 microphone troubleshooting guide and diagnostic script
- Test script for direct STT verification

### Fixed
- STT audio format now defaults to MP3 when base format is PCM, fixing OpenAI Whisper compatibility
  - OpenAI Whisper API doesn't support PCM format for uploads
  - Automatic fallback ensures STT continues to work with default configuration

### Changed
- Simplified audio feedback configuration to boolean AUDIO_FEEDBACK_ENABLED
- Removed voice feedback functionality, keeping only chime feedback
- Updated provider base URL specification to use comma-separated lists
- PCM remains the default format for TTS streaming (best performance)
- Standardized audio sample rate to 24kHz across codebase (was 44.1kHz)
  - Updated SAMPLE_RATE configuration constant
  - Replaced all hardcoded sample rate values with config constant
  - Aligned test mocks with new standard rate
  - Ensures consistency between OpenAI and Kokoro TTS providers

## [2.2.0] - 2025-06-22

### Added
- Configurable audio format support with PCM as the default for TTS streaming
- Environment variables for audio format configuration:
  - `VOICEMODE_AUDIO_FORMAT` - Primary format (default: pcm)
  - `VOICEMODE_TTS_AUDIO_FORMAT` - TTS-specific override (default: pcm)
  - `VOICEMODE_STT_AUDIO_FORMAT` - STT-specific override
- Support for multiple audio formats: pcm, mp3, wav, flac, aac, opus
- Format-specific quality settings:
  - `VOICEMODE_OPUS_BITRATE` (default: 32000)
  - `VOICEMODE_MP3_BITRATE` (default: 64k)
  - `VOICEMODE_AAC_BITRATE` (default: 64k)
- Automatic format validation based on provider capabilities
- Provider-aware format fallback logic
- Test suite for audio format configuration
- Streaming audio playback infrastructure:
  - `VOICEMODE_STREAMING_ENABLED` (default: true)
  - `VOICEMODE_STREAM_CHUNK_SIZE` (default: 4096)
  - `VOICEMODE_STREAM_BUFFER_MS` (default: 150)
  - `VOICEMODE_STREAM_MAX_BUFFER` (default: 2.0)
- TTFA (Time To First Audio) metric in timing output
- Per-request audio format override via `audio_format` parameter in conversation tools
- **Live Statistics Dashboard**: Comprehensive conversation performance tracking
  - Real-time performance metrics (TTFA, TTS generation, STT processing, total turnaround)
  - Session statistics (interaction counts, success rates, provider usage)
  - MCP tools: `voice_statistics`, `voice_statistics_summary`, `voice_statistics_recent`, `voice_statistics_reset`, `voice_statistics_export`
  - MCP resources: `voice://statistics/{type}`, `voice://statistics/summary/{format}`, `voice://statistics/export/{timestamp}`
  - Automatic integration with conversation tools - no manual tracking required
  - Thread-safe statistics collection across concurrent operations
  - Memory-efficient storage (maintains last 1000 interactions)

### Changed
- **BREAKING**: All `VOICE_MODE_` environment variables renamed to `VOICEMODE_`
  - `VOICE_MODE_DEBUG` → `VOICEMODE_DEBUG`
  - `VOICE_MODE_SAVE_AUDIO` → `VOICEMODE_SAVE_AUDIO`
  - `VOICE_MODE_AUDIO_FEEDBACK` → `VOICEMODE_AUDIO_FEEDBACK`
  - `VOICE_MODE_FEEDBACK_VOICE` → `VOICEMODE_FEEDBACK_VOICE`
  - `VOICE_MODE_FEEDBACK_MODEL` → `VOICEMODE_FEEDBACK_MODEL`
  - `VOICE_MODE_FEEDBACK_STYLE` → `VOICEMODE_FEEDBACK_STYLE`
  - `VOICE_MODE_PREFER_LOCAL` → `VOICEMODE_PREFER_LOCAL`
  - `VOICE_MODE_AUTO_START_KOKORO` → `VOICEMODE_AUTO_START_KOKORO`
- Also renamed non-prefixed variables to use `VOICEMODE_` prefix:
  - `VOICE_ALLOW_EMOTIONS` → `VOICEMODE_ALLOW_EMOTIONS`
  - `VOICE_EMOTION_AUTO_UPGRADE` → `VOICEMODE_EMOTION_AUTO_UPGRADE`
- Default audio format changed from MP3 to PCM for zero-latency TTS streaming
- Audio format is now validated against provider capabilities before use
- Dynamic audio loading based on format instead of hardcoded MP3
- Centralized all configuration in `voice_mcp/config.py` to eliminate duplication
- Logger names updated from "voice-mcp" to "voicemode"
- Debug directory paths updated:
  - `~/voice-mcp_recordings/` → `~/voicemode_recordings/`
  - `~/voice-mcp_audio/` → `~/voicemode_audio/`

### Benefits
- Zero-latency TTS streaming with PCM format
- Best real-time performance for voice conversations
- Universal compatibility with all audio systems
- Maintains backward compatibility with compressed formats
- Cleaner, consistent environment variable naming

### Known Issues
- OpenAI TTS with Opus format produces poor audio quality - NOT recommended for streaming
  - Use PCM (default) or MP3 for TTS instead
  - Opus still works well for STT uploads and file storage

## [2.1.3] - 2025-06-20

## [2.1.2] - 2025-06-20

## [2.1.1] - 2025-06-20

### Fixed
- Fixed `voice_status` tool error where `get_provider_display_status` was called with incorrect arguments
- Updated `.mcp.json` to use local package installation with `--refresh` flag

### Added
- Audio feedback chimes for recording start/stop (inspired by PR #1 from @jtuffin)
- New `VOICE_MODE_AUDIO_FEEDBACK` configuration with options: `chime` (default), `voice`, `both`, `none`
- Backward compatibility for boolean audio feedback values

### Changed
- Replaced all references from `voice-mcp` to `voice-mode` throughout documentation
- Updated MCP configuration examples to use `uvx` instead of outdated `./mcp-servers/` directory
- Removed hardcoded version from `server_new.py`
- Changed default listen duration to 15 seconds (from 10s/20s) in all voice conversation functions for better balance
- Audio feedback now defaults to chimes instead of voice for faster, less intrusive feedback

## [2.1.0] - 2025-06-20

## [2.0.3] - 2025-06-20

## [2.0.2] - 2025-06-20

## [2.0.1] - 2025-06-20

### Changed
- Consolidated package structure from three to two pyproject.toml files
- Removed unpublishable `voicemode` package configuration
- Made `voice-mode` the primary package (in pyproject.toml)
- Moved `voice-mcp` to secondary configuration (pyproject-voice-mcp.toml)

### Added
- Documentation for local development with uvx (`docs/local-development-uvx.md`)

## [2.0.0] - 2025-06-20

### 🎉 Major Project Rebrand: VoiceMCP → VoiceMode

We're excited to announce that **voice-mcp** has been rebranded to **VoiceMode**! 

This change reflects our vision for the project's future. While MCP (Model Context Protocol) describes the underlying technology, VoiceMode better captures what this tool actually delivers - a seamless voice interaction mode for AI assistants.

#### Why the Change?
- **Clarity**: VoiceMode immediately communicates the tool's purpose
- **Timelessness**: The name isn't tied to a specific protocol that may evolve
- **Simplicity**: Easier to remember and more intuitive for users

#### What's Changed?
- Primary command renamed from `voice-mcp` to `voicemode`
- GitHub repository moved to `mbailey/voicemode`
- Primary PyPI package is now `voice-mode` (hyphenated due to naming restrictions)
- Legacy `voice-mcp` package maintained for backward compatibility
- Documentation and branding updated throughout
- Simplified package structure to dual-package configuration

#### Backward Compatibility
- The `voice-mcp` command remains available for existing users
- Both `voice-mode` and `voice-mcp` packages available on PyPI
- All packages provide the `voicemode` command

### Changed
- Consolidated package configuration to two pyproject.toml files
- Made `voice-mode` the primary package with VoiceMode branding
- Updated package descriptions to reflect the rebrand

### Added
- Local development documentation for uvx usage

## [0.1.30] - 2025-06-19

### Added
- Audio feedback with whispered responses by default
- Configurable audio feedback style (whisper or shout) via VOICE_MODE_FEEDBACK_STYLE environment variable
- Support for overriding audio feedback settings per conversation

## [0.1.29] - 2025-06-17

### Changed
- Refactored MCP prompt names to use kebab-case convention (kokoro-start, kokoro-stop, kokoro-status, voice-status)
- Renamed Kokoro tool functions to follow consistent naming pattern (start_kokoro → kokoro_start, stop_kokoro → kokoro_stop)

## [0.1.28] - 2025-06-17

### Added
- MCP prompts for Kokoro TTS management:
  - `kokoro-start` - Start the local Kokoro TTS service
  - `kokoro-stop` - Stop the local Kokoro TTS service
  - `kokoro-status` - Check the status of Kokoro service
  - `voice-status` - Check comprehensive status of all voice services
- Instructions in CLAUDE.md for AI assistants on when to use Kokoro tools

## [0.1.27] - 2025-06-17

### Added
- Voice chat prompt/command (`/voice-mcp:converse`) for interactive voice conversations
- Automatic local provider preference with VOICE_MODE_PREFER_LOCAL environment variable
- Documentation improvements with better organization and cross-linking

### Changed
- Renamed voice_chat prompt to converse for clarity
- Simplified voice_chat prompt to take no arguments


## [0.1.26] - 2025-06-17

### Fixed
- Added missing voice_mode() function to cli.py for voice-mode command

## [0.1.25] - 2025-06-17

### Added
- Build tooling improvements for dual package maintenance

### Fixed
- Missing psutil dependency in voice-mode package

## [0.1.24] - 2025-06-17

### Fixed
- Improved signal handling for proper Ctrl-C shutdown
  - First Ctrl-C attempts graceful shutdown
  - Second Ctrl-C forces immediate exit

## [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

### 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_MODE_SAVE_AUDIO environment variable to save all TTS/STT audio files
- Audio files saved to ~/voice-mcp_audio/ with timestamps
- Improved voice selection documentation and guidance

### Changed
- Voice parameter changed from Literal to str for flexibility in voice selection


## [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
