Scenarios

Scenarios are plugins (layer L6) that orchestrate a show through the media server — sequencing cues, playback, parameters and audio. They run inside the server, but only through a checked facade (ScenarioCtx); they never reach engines, the database or the file system directly.

Plugin API 1.0 (freedome-scenario-api)

• ScenarioManifest: id, semver version, api = (1, 0), localised title / description, params_schema (JSON Schema — Manager renders the form from it), capabilities: Playback, Parameters, AudioDigital, AudioHybrid, Cues, Timers, Events, Storage, Assets, Http { allow }.
• Scenario::start(ctx, params) → SessionHandle; the handle receives on_event (timers, bus events), pause, resume, stop(reason) (must finish within 5 s) and reports status().
• Every ctx accessor checks the declared capability; the session runs with the role of the principal that started it (a capability that needs a scope the principal lacks is refused at start with 403).
• The host accepts API major N and N-1. Loading is static (compiled-in, cargo feature scenarios, on in the deb); out-of-process scenarios over gRPC are planned.

Isolation: one task per session; a panic marks the session failed and the server keeps running; a session that does not stop within 5 s is aborted. Each scenario has its own key-value storage.

Built-in scenarios (freedome_scenarios)

Id	What
ceremony	preparation → main → cool-down phases from an installation profile (mini / standard / pro / master); runs the programme of each preset on the hybrid audio devices of the venue, digital gain by intensity; emergency stop; run history
quantum_resonance	content generator: renders a resonance signal (Schumann / solfeggio / chakra / combined presets) into a WAV asset and optionally plays it

Presets are JSON data validated by schemas (crates/freedome_scenarios/presets, schemas), not compiled constants. Audio parts need the audio engines (anAntaSound / anAntaDigital, phase 3); without them the scenarios run degraded and say so in the session log.

API

REST GET /api/v1/scenarios, PATCH /api/v1/scenarios/{id} (enable / disable, admin), POST /api/v1/venues/{v}/scenario-sessions (start), session get / pause / resume / stop; events on venues/{v}/scenarios/{session}; .dome cue action {do: "scenario", target: "<id>", args: {...}}.