Contributing

​

Ways to Contribute

• Report bugs - Open an issue describing the bug
• Request features - Open an issue describing the feature
• Submit code - Fork, make changes, and submit a pull request
• Improve documentation - Help make the docs clearer
• Help others - Answer questions in discussions

​

Development Setup

​

Prerequisites

• Rust (stable, 1.70+)
• Linux with Wayland or X11
• Build dependencies:

sudo pacman -S base-devel clang alsa-lib

sudo apt install build-essential libclang-dev libasound2-dev

sudo dnf install @development-tools clang-devel alsa-lib-devel

​

Building from Source

# Clone the repository
git clone https://github.com/peteonrails/voxtype
cd voxtype

# Build debug version (faster compilation)
cargo build

# Build release version
cargo build --release

# Run tests
cargo test

# Run with verbose output
cargo run -- -vv

​

GPU Acceleration (Optional)

# Install Vulkan runtime
# Arch:
sudo pacman -S vulkan-icd-loader
# Ubuntu:
sudo apt install libvulkan1
# Fedora:
sudo dnf install vulkan-loader

# Build with Vulkan support
cargo build --release --features gpu-vulkan

# Install CUDA toolkit first, then:
cargo build --release --features gpu-cuda

# Install ROCm, then:
cargo build --release --features gpu-hipblas

​

Code Structure

​

Core Traits

• HotkeyListener - Hotkey detection (evdev, compositor bindings)
• AudioCapture - Audio input (cpal, PipeWire, PulseAudio)
• Transcriber - Speech-to-text (Whisper, ONNX engines, remote API)
• TextOutput - Text delivery (wtype, dotool, ydotool, clipboard)

​

Key Components

​

Development Workflow

​

Running Tests

# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run with output visible
cargo test -- --nocapture

# Test a specific module
cargo test text::

​

Manual Testing

# Run with verbose logging
cargo run -- -vv

# Test transcription on audio file
cargo run -- transcribe test.wav

# Watch state changes
cargo run -- status --follow

# Test model download
cargo run -- setup --download

​

Code Quality

# Format code
cargo fmt

# Run linter
cargo clippy

# Fix clippy warnings
cargo clippy --fix

​

Submitting Changes

​

For Bug Fixes

1. Create an issue describing the bug
2. Fork the repository
3. Create a branch: git checkout -b fix/description
4. Make your fix
5. Test thoroughly
6. Submit a pull request referencing the issue

​

For Features

1. Open an issue to discuss the feature first
2. Wait for feedback before investing significant time
3. Fork and create a branch: git checkout -b feature/description
4. Implement the feature
5. Add tests and documentation
6. Submit a pull request

​

Commit Messages

type: short description

Longer description if needed. Explain what and why,
not how (the code shows how).

Fixes #123

​

Pull Request Guidelines

• Keep PRs focused - One feature or fix per PR
• Write tests - Add tests for new functionality
• Update docs - Update relevant documentation
• Follow code style - Run cargo fmt and cargo clippy
• Test on your system - Verify it works before submitting
• Provide context - Explain why the change is needed

​

Documentation

• User Manual (docs/USER_MANUAL.md) - How to use the feature
• Configuration Guide (docs/CONFIGURATION.md) - Config file options
• Troubleshooting (docs/TROUBLESHOOTING.md) - Common issues and solutions
• CLI help - Update src/cli.rs with clear --help text
• Website docs - Update corresponding pages in website/

​

Code Style

​

Rust Conventions

• Use snake_case for functions and variables
• Use PascalCase for types and structs
• Use SCREAMING_SNAKE_CASE for constants
• Keep lines under 100 characters
• Use descriptive variable names

​

Error Handling

#[error("Cannot open input device '{0}'. Is the user in the 'input' group?\n  Run: sudo usermod -aG input $USER")]
DeviceAccess(String),

• What went wrong
• Why it happened
• How to fix it

​

Logging

use tracing::{info, debug, warn, error};

info!("Starting daemon");
debug!(device = %device_name, "Opening audio device");
warn!("Model not found, downloading...");
error!(?err, "Transcription failed");

​

Adding New Features

​

Adding a Transcription Backend

1. Create src/transcribe/your_backend.rs
2. Implement the Transcriber trait:
   #[async_trait]
   pub trait Transcriber: Send + Sync {
       async fn prepare(&mut self) -> Result<()>;
       async fn transcribe(&mut self, audio: &[i16]) -> Result<String>;
   }
   
3. Add to factory in src/transcribe/mod.rs
4. Add config fields to src/config.rs with defaults
5. Add CLI flags in src/cli.rs
6. Document in docs/CONFIGURATION.md
7. Add tests

​

Adding an Output Method

1. Create src/output/your_method.rs
2. Implement the TextOutput trait:
   #[async_trait]
   pub trait TextOutput: Send + Sync {
       async fn output(&mut self, text: &str) -> Result<()>;
       fn is_available(&self) -> bool;
   }
   
3. Add to fallback chain in src/output/mod.rs
4. Consider whether it should be automatic fallback or explicit selection

​

Modifying Configuration

• Add new fields with sensible defaults
• Removed fields should be silently ignored, not cause errors
• Test upgrades by running new version with old config file
• Document changes in release notes

​

Testing Guidelines

​

Unit Tests

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_something() {
        // Test implementation
    }
}

​

Integration Tests

use voxtype::*;

#[tokio::test]
async fn test_end_to_end() {
    // Test implementation
}

​

Best Practices

• Prefer self-documenting code over comments
• Avoid allocations in hot paths (hotkey detection, audio streaming)
• Use spawn_blocking for CPU-intensive work (transcription)
• Prefer streaming over buffering where possible
• Only validate at system boundaries (user input, external APIs)
• Don’t over-engineer - wait for multiple use cases before abstracting

​

Performance Considerations

• Desktop: Prioritize fast transcription
• Laptop: Balance speed with battery efficiency
• Memory: Use on-demand loading for large models
• GPU: Provide isolation option for memory management

​

Getting Help

• Questions? Open a discussion
• Found a bug? Open an issue
• Read the code: The Developer Guide has architectural details

​

Maintainer Response Time

​

Recognition

1. Credited in commit messages with Co-authored-by
2. Added to the Contributors section in README
3. Listed on the website

​

Code of Conduct

​

License

​

Additional Resources

• Architecture Overview - System design details
• Troubleshooting Guide - Common issues
• User Manual - Feature documentation
• Configuration Guide - Config reference
• Developer Guide - Code-level details