voice-to-notes/CONTRIBUTING.md

Contributing to Voice to Notes

Thank you for your interest in contributing! This guide covers how to set up the project for development and submit changes.

Development Setup

Prerequisites

• Node.js 20+ and npm
• Rust (stable toolchain)
• Python 3.11+ with uv (recommended) or pip
• System libraries (Linux only):

  sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf xdg-utils
  

Clone and Install

git clone https://repo.anhonesthost.net/MacroPad/voice-to-notes.git
cd voice-to-notes

# Frontend
npm install

# Python sidecar
cd python && pip install -e ".[dev]" && cd ..

Running in Dev Mode

npm run tauri:dev

This runs the Svelte dev server + Tauri with hot-reload. The Python sidecar runs from your system Python (no PyInstaller needed in dev mode).

Building

# Build the Python sidecar (frozen binary)
cd python && python build_sidecar.py --cpu-only && cd ..

# Build the full app
npm run tauri build

Project Structure

src/                        # Svelte 5 frontend
  lib/components/           # Reusable UI components
  lib/stores/               # Svelte stores (app state)
  routes/                   # SvelteKit pages
src-tauri/                  # Rust backend (Tauri v2)
  src/sidecar/              # Python sidecar lifecycle (download, extract, IPC)
  src/commands/             # Tauri command handlers
  src/db/                   # SQLite database layer
python/                     # Python ML sidecar
  voice_to_notes/           # Main package
    services/               # Transcription, diarization, AI, export
    ipc/                    # JSON-line IPC protocol
    hardware/               # GPU/CPU detection
.gitea/workflows/           # CI/CD pipelines
docs/                       # Documentation

How It Works

The app has three layers:

1. Frontend (Svelte) — UI, audio playback (wavesurfer.js), transcript editing (TipTap)
2. Backend (Rust/Tauri) — Desktop integration, file access, SQLite, sidecar process management
3. Sidecar (Python) — ML inference (faster-whisper, pyannote.audio), AI chat, export

Rust and Python communicate via JSON-line IPC over stdin/stdout pipes. Each request has an id, type, and payload. The Python sidecar runs as a child process managed by SidecarManager in Rust.

Conventions

Rust

• Follow standard Rust conventions
• Run cargo fmt and cargo clippy before committing
• Tauri commands go in src-tauri/src/commands/

Python

• Python 3.11+, type hints everywhere
• Use ruff for linting: ruff check python/
• Tests with pytest: cd python && pytest
• IPC messages: JSON-line format with id, type, payload fields

TypeScript / Svelte

• Svelte 5 runes ($state, $derived, $effect)
• Strict TypeScript
• Components in src/lib/components/
• State in src/lib/stores/

General

• All timestamps in milliseconds (integer)
• UUIDs as primary keys in the database
• Don't bundle API keys or secrets — those are user-configured

Submitting Changes

1. Fork the repository
2. Create a feature branch: git checkout -b my-feature
3. Make your changes
4. Test locally with npm run tauri:dev
5. Run linters: cargo fmt && cargo clippy, ruff check python/
6. Commit with a clear message describing the change
7. Open a Pull Request against main

CI/CD

Pushes to main automatically:

• Bump the app version and create a release (release.yml)
• Build app installers for all platforms

Changes to python/ also trigger sidecar builds (build-sidecar.yml).

Areas for Contribution

• UI/UX improvements
• New export formats
• Additional AI provider integrations
• Performance optimizations
• Accessibility improvements
• Documentation and translations
• Bug reports and testing on different platforms

Reporting Issues

Open an issue on the repository with:

• Steps to reproduce
• Expected vs actual behavior
• Platform and version info
• Sidecar logs (%LOCALAPPDATA%\com.voicetonotes.app\sidecar.log on Windows)

License

By contributing, you agree that your contributions will be licensed under the MIT License.