Skip to main content

​
Onboarding

Welcome to Songbird! This guide will help you get up and running as a new contributor.

​
Architecture

Songbird is pure Rust + React/TypeScript on Tauri v2 — there is no C++ or JUCE; that migration is complete. The Rust backend lives in rust/ (a Cargo workspace) and the React frontend in react_ui/.

​
Setup

Follow the instructions in install.md at the repo root. It covers prerequisites, submodule init, patching, building, and verification — and works with LLM coding agents out of the box.

​
Project Structure Overview

​
Rust Crate Map

The rust/crates/ directory contains:

​
Key Concepts to Learn

  • Linear Automation — How work flows through the Linear board: moving a card between columns drives an automated agent action (planning, review, execution, merge). Read this before picking up your first ticket.
  • .bird notation — The text-based music format at the heart of Songbird. Understand this first.
  • Sync Engine — How React, Rust, and Git stay in sync.
  • Collaboration — Git-based collaboration with real-time multiplayer cursors (WIP).
  • Tauri IPC — The React UI communicates with the Rust backend via Tauri’s typed IPC commands. Each command returns IpcResult<T>.
  • Real-time audio — The engine uses a lock-free, zero-allocation audio callback with pre-allocated buffers and SpscRingBuffer for UI communication.

​
Branches

All new work should branch off rust.

​
The Tree of Code

Not all code carries the same risk. Think of the codebase as a tree — the closer to the roots, the more caution is required. Roots — Core foundation. Breaking these breaks everything.
  • Examples: App shell, install scripts, base of the audio engine, sync engine.
  • Discuss changes in advance, overcommunicate, heavy test coverage, code review, QA thoroughly.
Trunk — Code everyone else relies on. Core features.
  • Examples: Tracks, plugin hosting, playback, frequently used components, UI theme.
  • Overcommunicate, heavy test coverage, code review, QA thoroughly.
Branches — Ancillary features, prototypes, or features that don’t impact most users.
  • Examples: Export options, CLI tool, niche plugin UIs.
  • Test coverage, use best judgement about code review, QA.
Leaves — Small, self-contained things that won’t break other parts of the app.
  • Examples: Tooltips, cosmetic tweaks, docs, one-off scripts.
  • Let the LLMs go wild and have fun :)

​
Development Workflow

  1. Branch off rust in Devin/Antigravity/Claude Code (or any other tool).
  2. Write tests first — define success conditions before implementation.
  3. Implement against those tests.
  4. QA features and core functionality (e.g., don’t break playback while moving fast).
  5. Commit and submit a PR targeting rust.
  6. Request human review (reviewers may use agents).

​
Useful Commands

​
Next Steps

  • Read the Introduction for an architecture overview.
  • Explore the React UI docs for frontend details.
  • Check the Roadmap to see what’s in progress.
  • Look at the Keyboard Shortcuts to navigate the app efficiently.
  • Read rust/ARCHITECTURE.md for a detailed reference of the Rust engine internals.