Building Voice Mode¶

This guide covers building Voice Mode for local development and testing.

Prerequisites¶

Python >= 3.10
uv installed

Note: Development builds temporarily modify the version file, but make build-dev automatically restores it.

Building a Development Version¶

Automatic Dev Versioning (Recommended)¶

Use the make build-dev command for automatic versioning:

# Automatically appends .dev + timestamp to current version
make build-dev

This creates a unique development version like 2.4.2.dev20240627123456.

The command safely handles version updates with automatic rollback on errors.

Manual Version Update¶

If you prefer to set a specific dev version:

# Edit voice_mode/__version__.py
__version__ = "2.4.2.dev0"  # Example dev version

# Then build
uv build

This creates wheel and source distributions in the dist/ directory: - dist/voice_mode-2.4.2.dev0-py3-none-any.whl - dist/voice_mode-2.4.2.dev0.tar.gz

Installing Your Build¶

In Another Project¶

# Install the wheel directly
pip install /path/to/voicemode/dist/voice_mode-2.4.2.dev0-py3-none-any.whl

# Or with uv
uv pip install /path/to/voicemode/dist/voice_mode-2.4.2.dev0-py3-none-any.whl

In MCP Configuration¶

For testing with Claude Code or other MCP clients:

{
  "mcpServers": {
    "voice-mode-dev": {
      "command": "python",
      "args": ["-m", "voice_mode"],
      "env": {
        "PYTHONPATH": "/path/to/voicemode",
        "OPENAI_API_KEY": "your-key"
      }
    }
  }
}

Version Management¶

Development Versions¶

Use .devN suffix: 2.4.2.dev0, 2.4.2.dev1, etc.
These won't be published to PyPI by CI/CD
Increment the dev number for each test build

Release Versions¶

Use semantic versioning: 2.4.2, 2.5.0, etc.
Only create release versions when ready to publish
Use make release for official releases

Testing Your Build¶

Create a test environment:

uv venv test-env
source test-env/bin/activate  # On Windows: test-env\Scripts\activate

Install your build:
```
uv pip install dist/voice_mode-*.whl
```
Test the installation:
```
python -m voice_mode --help
```

Troubleshooting¶

Build Errors¶

Ensure you're in the project root directory
Check that pyproject.toml is valid
Run uv sync to ensure dependencies are installed

Import Errors¶

Verify the wheel installed correctly: pip show voice-mode
Check Python path: python -c "import voice_mode; print(voice_mode.__file__)"

Version Conflicts¶

Uninstall existing versions: pip uninstall voice-mode
Use virtual environments to isolate installations