VoiceMode Converse Code Path Guide

VoiceMode Converse Code Path Guide

Overview

This guide traces the code path from running voicemode converse through all the relevant files.

Code Path

1. Entry Point: Package Configuration

File: pyproject.toml Lines: 100-102

[project.scripts]
voice-mode = "voice_mode.cli:voice_mode"
voicemode = "voice_mode.cli:voice_mode"

Both commands map to the voice_mode() function in the CLI module.

2. CLI Entry Function

File: voice_mode/cli.py Function: voice_mode() Lines: 74-76

def voice_mode() -> None:
    """Entry point for voicemode command - starts the MCP server or runs subcommands."""
    voice_mode_main_cli()

This calls the main CLI group.

3. Main CLI Group

File: voice_mode/cli.py Function: voice_mode_main_cli() Lines: 40-72 This is a Click command group that handles all subcommands. Without a subcommand, it starts the MCP server. With subcommands, it routes to the appropriate handler.

4. Converse Subcommand

File: voice_mode/cli.py Decorator: @voice_mode_main_cli.command() Function: converse() Lines: 1650-1815

Key parameters:

• --message, -m: Initial message to speak
• --wait/--no-wait: Whether to wait for response
• --duration, -d: Listen duration
• --voice: TTS voice to use
• --tts-provider: OpenAI or Kokoro
• --continuous, -c: Continuous conversation mode

The function creates an async wrapper (line 1690) that calls the actual tool implementation.

5. Converse Tool Implementation

File: voice_mode/tools/converse.py Decorator: @mcp.tool() Function: converse() Lines: 1194-1195 (and beyond)

This is the main MCP tool that handles:

• Voice synthesis (TTS)
• Voice recognition (STT)
• Provider selection
• Audio playback and recording
• Conversation logging

Key imports:

• Line 61-70: Core functions from voice_mode.core
• Line 60: Provider registry from voice_mode.provider_discovery
• Line 28: Conversation logger

6. Core Audio Functions

File: voice_mode/core.py

Key functions:

• get_openai_clients() - Line 131: Initialize API clients
• text_to_speech() - Line 163: Convert text to audio
• play_chime_start() - Line 612: Play start chime
• play_chime_end() - Line 644: Play end chime
• generate_chime() - Line 528: Generate chime audio
• cleanup() - Line 676: Cleanup resources

7. Provider Discovery

File: voice_mode/provider_discovery.py

Discovers and manages TTS/STT providers:

• OpenAI API (cloud)
• Whisper.cpp (local STT)
• Kokoro (local TTS)
• LiveKit (real-time communication)

The provider registry is imported at line 60 of converse.py and used to select the best available provider.

8. Configuration

File: voice_mode/config.py

Loaded by converse.py (lines 29-58), provides:

• Audio settings (sample rate, channels)
• Service endpoints
• Debug flags
• Audio feedback settings
• Silence detection parameters

Demonstration Script

Setup

# Terminal control pattern: Use show tool with neovim panes
# After each step, use look tool to confirm the pane is showing correctly

Step 1: Show Entry Point

# Show pyproject.toml focusing on scripts section
show pyproject.toml
look  # Confirm it's visible
# Highlight lines 100-102 in neovim

Step 2: Show CLI Entry Functions

# Show the voice_mode() entry point
show voice_mode/cli.py:74-76
look  # Confirm visible

# Show the main CLI group
show voice_mode/cli.py:40-72
look  # Confirm visible

Step 3: Show Converse Command

# Show the converse subcommand definition
show voice_mode/cli.py:1650-1700
look  # Confirm visible

# Search for the async wrapper
# Navigate to line 1690 to show how it calls the tool

Step 4: Show Tool Implementation

# Open the converse tool file
show voice_mode/tools/converse.py:1194
look  # Confirm visible

# Show the key imports
show voice_mode/tools/converse.py:1-100
look  # Confirm visible

Step 5: Show Core Functions

# Show the core module with TTS/STT functions
show voice_mode/core.py
look  # Confirm visible

# Highlight text_to_speech function
# Search for: /^async def text_to_speech

Step 6: Show Provider Discovery

# Show provider discovery system
show voice_mode/provider_discovery.py
look  # Confirm visible

Voice Demonstration Script

While showing each file, use voice to narrate:

converse("Let's trace the voicemode converse command. First, the entry point is in pyproject.toml.", wait_for_response=False)
# Then show pyproject.toml

converse("When you run voicemode converse, it calls voice_mode function in cli.py", wait_for_response=False)
# Then show cli.py entry

converse("This routes to the converse subcommand, which is a Click command", wait_for_response=False)
# Then show converse function

converse("The CLI wraps the actual MCP tool, which is in tools/converse.py", wait_for_response=False)
# Then show tools/converse.py

converse("The tool uses core functions for text-to-speech and speech-to-text", wait_for_response=False)
# Then show core.py

converse("Provider discovery finds available TTS and STT services", wait_for_response=False)
# Then show provider_discovery.py

Summary Flow

User runs: voicemode converse
    ↓
pyproject.toml (scripts) → voice_mode.cli:voice_mode
    ↓
cli.py:voice_mode() → voice_mode_main_cli()
    ↓
cli.py:converse() command (Click subcommand)
    ↓
tools/converse.py:converse() (MCP tool)
    ↓
Parallel operations:
- core.py:text_to_speech() → Speak the message
- Recording → Listen for response
- core.py:play_chime_start/end() → Audio feedback
- provider_discovery.py → Select TTS/STT providers
    ↓
Return transcribed response to user

Key Concepts

1. Click CLI Framework: Handles command parsing and routing
2. FastMCP Tools: MCP tool decorator makes functions available to AI
3. Provider Registry: Dynamic discovery of local/cloud services
4. Async/Await: All voice operations are asynchronous
5. Configuration: Environment-based with sensible defaults