Skip to main content

​
songbird-scenarios

JSON-defined workflows that drive Songbird into a starting state by issuing sync engine commands sequentially.

​
What it owns

  • The scenario file format (scenarios/**/*.json).
  • The resolver that flattens include: chains into a single step list.
  • The ${name.field} reference substitution.
  • The runner that walks the step list and calls songbird_sync::dispatch::dispatch() on each step.

​
Public API

  • find_scenario(name, root) — locate a scenario JSON file by bare name (recursive search) or path-qualified name.
  • resolve(name, root) -> ResolvedScenario — parse, recursively flatten include:s (dedup + cycle detection), return an ordered Vec<Step>.
  • run(&ResolvedScenario, &RunOptions) -> RunReport — execute the steps, substituting refs and dispatching each one. Requires songbird_sync::dispatch::init to have already been called.

​
How it fits

The Tauri app (songbird-app) calls into this crate from its setup() flow when the SONGBIRD_SCENARIO env var is set, after the sync engine context is initialized. ./utils/build-rs -s <name> is the dev-loop entry point that sets the env var. This crate does not know about Tauri, the audio engine, or files beyond JSON parsing — it only knows about songbird-sync::dispatch.

​
Tests

cargo test -p songbird-scenarios
Tests cover parsing, finding, resolving (including cycle detection), and ref substitution. The runner is integration-tested via the Tauri app because it depends on the global dispatch context.