Skip to main content

​
Utils (utils/)

Build scripts, shell utilities, and development tooling.

​
Files

FilePurpose
launch.shMain launch script — builds the C++ app (CMake + Ninja), builds the React UI (npm run build), and launches SongbirdPlayer.app. Use --skip-build to relaunch without rebuilding.
build.shRelease-mode build script — builds with max optimization (-O3), bundles React UI, and codesigns the .app. Supports --debug, --skip-build, and --notarize flags.
release.shFull release pipeline — release build + codesign + optional notarization for distribution. Produces Songbird Player.app in build-release/.
validate.shPre-commit validation suite — runs C++ tests, TypeScript type-check, ESLint, and Vitest in sequence. Use validate.sh [step] to run a single step.
validate_cpp.shBuilds and runs the SongbirdIntegrationTests C++ test binary.
validate_ts.shRuns tsc --noEmit on the React UI for TypeScript type checking.
validate_lint.shRuns ESLint on the React UI source.
validate_vitest.shRuns the Vitest test suite for React UI stores and utilities.
export.shInteractive stem/master export CLI — parses .bird project files, offers dry/wet/master export modes with take lane variations and audio format options. Use --build to rebuild C++ before exporting. Supports non-interactive flags (--dry, --wet, --master, --tracks, etc.).
collab-server.shLaunches the collaboration WebSocket server from server/. Supports --port flag (default 8765).
sync_docs.shSyncs README content into the Mintlify docs folder.
install-linux-deps.shInstalls system dependencies for building on Ubuntu/Debian (CMake, Ninja, GTK, ALSA, etc.). Run with sudo.
local.shLocal development helper — shortcut for building and running locally.
build_bindings.jsonVSCode keyboard shortcut bindings for build tasks (Cmd+R = build, Cmd+B = debug).
include_path.jsonC++ include paths for IDE IntelliSense.

​
Legacy (FeatherS2 Hardware)

FilePurpose
setup.shInstalls Arduino CLI, board cores, and libraries.
flash.shFlashes files to FeatherS2 board via USB.
files.shFile management utility for the FeatherS2 FATFS partition.
mkfatfsBinary tool for creating FAT filesystem images.
partition/ESP32-S2 partition table definitions.
Note: The legacy scripts target the original FeatherS2 hardware prototype. The current Songbird is a desktop-only macOS app.

​
Build Workflow

The primary build workflow for the desktop app: 
# Full build (C++ + React UI) and launch
./utils/launch.sh

# Or manually:
cmake -B build -G Ninja
cmake --build build
cd react_ui && npm run build
open build/SongbirdPlayer_artefacts/Debug/SongbirdPlayer.app

​
Validation

Run the full validation suite before committing: 
# All steps (C++ tests → TypeScript → ESLint → Vitest)
./utils/validate.sh

# Individual steps
./utils/validate.sh cpp
./utils/validate.sh ts
./utils/validate.sh lint
./utils/validate.sh vitest