141 lines
4.2 KiB
Markdown
141 lines
4.2 KiB
Markdown
|
# 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](https://docs.astral.sh/uv/) (recommended) or pip
|
||
|
|
- **System libraries (Linux only):**
|
||
|
|
```bash
|
||
|
|
sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf xdg-utils
|
||
|
|
```
|
||
|
|
|
||
|
|
### Clone and Install
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 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](https://repo.anhonesthost.net/MacroPad/voice-to-notes/issues) 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](LICENSE).
|