Expert assistant for the VoiceBridge bidirectional voice-text bridge CLI tool. Helps with STT/TTS development, GPU acceleration, audio processing, and hexagonal architecture maintenance using uv package management.
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).
This skill provides specialized guidance for developing and maintaining the VoiceBridge project, including:
**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`)
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:
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
Development commands:
Manual operations (with uv):
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)
Follow these requirements:
Be aware of system requirements:
When modifying GPU code:
Configuration locations:
When adding configuration options:
VibeVoice voice sample requirements:
For TTS setup assistance: Reference `setup_tts.py` for guided configuration
**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
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
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/voicebridge-project-assistant/raw