Utils (`utils/`)

Build, validation, and developer tooling for the Songbird Rust workspace. The directory is being migrated to a flatter convention: top-level entries are extension-less single-purpose drivers (build-rs, validate, export), and scripts grouped by concern live in subdirectories (utils/build/, utils/validation/, …). During the migration some entries exist in both locations — the top-level versions are the canonical ones to invoke; subdirectory scripts are the implementation pieces called by them.

Top-level drivers

Entry	What it does
`build-rs`	Boots the Vite dev server + Tauri shell with HMR. Default dev loop.
`release-rs`	Release-mode build of the desktop app (codesign, optional notarization).
`validate`	Pre-commit / pre-merge checks. Dispatches to `validation/validate_*.sh`. Steps: `rust ts lint vitest`.
`export`	Interactive master render — wraps `songbird-cli render`. Stems & lane variations are UI-only.
`sync-types`	Regenerate TypeScript bindings from Rust enums (ts-rs). Run after editing any sync `defs.rs`.
`sync-docs`	Sync `README.md` files into `docs/` as Mintlify-flavoured `.mdx`.
`worktree`	Populate `libraries/` submodules in this worktree by rsync from the core checkout.
`submodules`	Wrapper around `git submodule update --init --recursive` (slower than `worktree` — prefer the latter).
`install-hooks`	Install the project’s git pre-commit hooks.

Subdirectories

Path	Contents
`build/`	Platform-specific build scripts: `build-android.sh`, `build-ios.sh`, `build-wasm.sh`, `build-web`, `release-wasm.sh`, `agent-headless.sh` (headless DAW for browser testing).
`validation/`	Per-language validators called by the top-level `validate` dispatcher: `validate_rust.sh`, `validate_ts.sh`, `validate_lint.sh`, `validate_vitest.sh`, `validate_cpp.sh` (vestigial — no C++ on this branch; safe to delete once confirmed unused).
`server/`	Collaboration server: `collab-server.sh` (WebSocket server launcher), `songbird-processor.js` (legacy AudioWorklet code), `songbird.service` (systemd unit).
`helpers/`	One-off Python helpers: `convert_tracktion_state.py` (Tracktion XML → bird), `migrate_roopa.py` (Roopa-format migration), `midi-ping.py` (MIDI device probe).

Common workflows

# First-time setup in a new worktree
./utils/workflow/worktree            # populate libraries/ from core
./utils/hooks/install-hooks       # set up git hooks

# Day-to-day dev
./utils/build-rs            # Vite + Tauri with HMR
./utils/validate            # all: rust + ts + lint + vitest
./utils/validate rust       # cargo test + clippy across the workspace
./utils/validate ts         # tsc --noEmit
./utils/sync-types          # after touching any sync engine defs.rs

# Headless harness for browser-driven E2E
./utils/build/agent-headless.sh

# Offline render
./utils/export                              # interactive: pick project + format
./utils/export song.bird --quick            # render with defaults
./utils/export song.bird --sample-rate 96000 --bit-depth 24 --normalize

Notes on `export`

The script wraps cargo run -p songbird-cli -- render and produces a master-mix WAV. It does not support stem export or take-lane variations from the command line — those run through the live audio graph and are exposed only via the desktop app’s Export menu (right toolbar → Export → Stems / Master + Take Lane Variations). If you need batch CLI stems in CI, the underlying limitation is that the offline render path (graph.process in a tight loop) doesn’t drive the clip scheduler. See rust/crates/engine/songbird-export/README.md for the full picture.

Migration status (`utils/export` vs `utils/export.sh`)

utils/export.sh is the historical name; utils/export is the new extension-less form matching build-rs, release-rs, etc. Both files currently hold the same script. Pick one to keep once the rename has propagated through any external callers (CI, docs, muscle memory).

Testing & Validation

Workflows

Specs

Work in Progress

Utils (`utils/`)

Utils (`utils/`)

Top-level drivers

Subdirectories

Common workflows

Notes on `export`

Migration status (`utils/export` vs `utils/export.sh`)

​Utils (utils/)

​Top-level drivers

​Subdirectories

​Common workflows

​Notes on export

​Migration status (utils/export vs utils/export.sh)

Utils (`utils/`)

Top-level drivers

Subdirectories

Common workflows

Notes on `export`

Migration status (`utils/export` vs `utils/export.sh`)