VoiceBridge Project Assistant

Expert assistant for working with the VoiceBridge project—a comprehensive bidirectional voice-text CLI tool that bridges speech and text seamlessly using OpenAI's Whisper (STT) and VibeVoice (TTS).

What This Skill Does

This skill provides specialized guidance for developing and maintaining the VoiceBridge project, including:

Instructions

1. Environment Setup

**CRITICAL**: This project uses `uv` for fast Python package management and a virtual environment at `.venv/`. Always use Makefile commands or `uv run` for operations.

When setting up or working with the project:

1. **Initialize environment**: Use `make prepare` to set up `.venv` and install dependencies

2. **CUDA support**: Use `make prepare-cuda` for GPU acceleration

3. **System tray support**: Use `make prepare-tray` if needed

4. **Manual uv commands**: Always prefix with `uv run` (e.g., `uv run pytest`)

2. Architecture Awareness

Follow the hexagonal architecture pattern:

```

voicebridge/

├── domain/ # Core business logic and models

├── ports/ # Interfaces/abstract base classes

├── adapters/ # External integrations (audio, system, transcription, TTS)

├── services/ # Application services

├── cli/ # Command line interface

└── tests/ # Test suite

```

When adding features:

3. Development Workflow

Before making changes:

1. **Understand the codebase**: Review relevant files in the hexagonal structure

2. **Check existing tests**: Look at `tests/` for patterns

3. **Lint frequently**: Run `make lint` during development

4. **Test comprehensively**: Run `make test` before committing

When implementing new features:

1. **STT features**: Extend `transcription_service.py` and `adapters/transcription.py`

2. **TTS features**: Extend `tts_service.py` and `adapters/vibevoice_tts.py`

3. **Audio processing**: Modify `adapters/audio/` modules

4. **CLI commands**: Add to `cli/commands.py` with Typer

5. **Performance**: Integrate with `performance_service.py` for metrics

4. Key Commands Reference

Development commands:

Manual operations (with uv):

5. Testing Standards

When adding or modifying code:

1. **Write comprehensive tests**: Cover both STT and TTS functionality

2. **Test both success and failure paths**: Include edge cases

3. **Mock external dependencies**: Use pytest fixtures for Whisper/VibeVoice

4. **Verify GPU code paths**: Test CUDA/Metal detection and fallback

5. **Check memory limits**: Test chunking and streaming behavior

Run tests with: `make test` (full coverage) or `make test-fast` (quick validation)

6. Code Standards

Follow these requirements:

7. System Integration

Be aware of system requirements:

When modifying GPU code:

8. Configuration Management

Configuration locations:

When adding configuration options:

9. TTS Voice Setup

VibeVoice voice sample requirements:

For TTS setup assistance: Reference `setup_tts.py` for guided configuration

10. Common Development Tasks

**Adding a new CLI command**:

1. Define command function in `cli/commands.py`

2. Use Typer decorators for arguments/options

3. Call appropriate service methods

4. Add tests in `tests/cli/`

5. Update help documentation

**Implementing a new export format**:

1. Add format to `services/export_service.py`

2. Update `ExportFormat` enum in `domain/models.py`

3. Implement conversion logic

4. Add CLI option in export commands

5. Test with various transcription results

**Adding audio processing feature**:

1. Implement in `adapters/audio/processor.py`

2. Expose via `services/transcription_service.py` or new service

3. Add CLI command if user-facing

4. Test with various audio formats

5. Document parameters and behavior

Example Usage

When a user asks to:

**"Add support for a new audio format"**:

1. Check `adapters/audio/formats.py` for supported formats

2. Verify FFmpeg support for the format

3. Update format detection in `adapters/audio/processor.py`

4. Add format to documentation

5. Test conversion and processing

6. Run `make lint` and `make test`

**"Improve GPU memory handling"**:

1. Review `adapters/system.py` for GPU detection

2. Check `services/transcription_service.py` for chunking logic

3. Implement memory monitoring improvements

4. Test with various file sizes and GPU configurations

5. Verify CPU fallback behavior

6. Update performance metrics collection

**"Add a new TTS voice management feature"**:

1. Review `adapters/vibevoice_tts.py` for voice handling

2. Implement feature in `services/tts_service.py`

3. Add CLI command in `cli/commands.py`

4. Update voice sample detection if needed

5. Test with various voice samples

6. Document usage and voice requirements

Important Notes