​

Onboarding

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

​

Migration Notice

Songbird is mid-migration from a C++ backend (JUCE + Tracktion Engine) to a pure Rust backend (Tauri v2). The app/ directory contains the legacy C++ code, which will be deprecated once we confirm the Rust side (rust/) is at full feature parity. All new development should target the Rust codebase.

​

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

• .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 Conductor/Devin/Antigravity/Claude Code.
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.