Plantasia Sound Engine

Two users again. The app author needs a safe, small API that cannot be called in the wrong order and that reports what the sound is doing. The player needs a handful of controls that feel like forces, not parameters: turn up growth and the world gets busier, turn up mold and it decays, whichever species is playing.

The v1 engine was preset centric. v2 reorganized everything around species: a plugin with its own synthesis graph that interprets the five shared ecological controls its own way. The preset system stayed, but every preset now resolves to a species plus an ecology. The tradeoff: two audio paths coexist during the transition (a Tone.js chain for v1 and per species graphs for v2), and the demo's analyser only listens to one of them, which is the first fix on the engine's list.

The architecture landed under a premature v2.0.0 tag before the host contract was real. Rather than build on it, I deprecated the tag, listed the integration blockers (lifecycle contract, playable only registry, unified facade, event bus, scheduler, MIDI, migration guide, browser sonic test, CPU budget test, adapter and integration doc), shipped all of them as 1.0.0 beta 1, and told hosts to pin that. The demo went through a validation pass that removed every control not wired to a real engine call. 1.0.0 followed once the surface was measured, not just built.

Before calling the public API stable I wrote a Playwright harness that plays the built engine in Chromium and WebKit and measures what a player feels: the time from noteOn to the first audible sample, located to the sample on a tap of the master bus, and dropouts over a minute of generative playback while a fake visual loop burns eight milliseconds of every frame. The first run measured 102 ms of latency: Tone.js schedules a tenth of a second ahead by default. Setting the lookahead to ten milliseconds brought it to 12 ms with zero dropouts in both browsers. The harness also showed that on a single held note the five ecological controls move the spectrum less than the voice moves itself; they act on the population, which is the design, and now it is written down rather than assumed. In 1.2 the harness moved into CI and grew rows for control extremes, a morph across a species switch, and per control audibility; a lab page built for tuning by ear found, on its first A/B, that Flowers threw a range error above ninety percent bloom, a bug no gate had reached because no gate had pushed a control to its edge.

Layers

• Public tier: createPlantasiaEngine and twenty three methods on it, createPlantasonicAdapter, the shipped presets. Root export carries the v1 preset path and internals; nothing removed.
• Lifecycle state machine: idle, loaded, running, disposed; wrong order throws.
• Species manager and registry; ecology controls normalized and clamped at the engine layer.
• Generative engine (phrases, harmony, rhythm, probability, memory) shared by all species.
• Performance engine: velocity engine, expression router, twelve macros.
• Scheduler and transport; Web MIDI input scaffold.
• Semantic event bus for hosts, every payload stamped with audio clock time.
• Master bus: every output path, v1 chain, signature graphs, and all species, terminates in one node with the analyser, FFT, and meter behind getAudioFeatures.
• Modulation engine (1.1): global, beside the species manager; descriptor sources, additive routes, a 30 Hz frame handed to the species through an optional hook, change gated so eight routes cost a fifth of a millisecond per tick.
• Snapshots (1.2): one versioned JSON object for species, controls, tempo, routes, preferences, and polyphony cap; applySnapshot validates before it changes anything, replaces routes, switches species, and morphs controls and tempo at 30 Hz over a chosen time.

Validation gates on every build

• Presets, species API, ecology controls, generative engine, performance engine, species registry, lifecycle, facade, events, analysis, modulation, preferences, snapshot, scheduler, MIDI, species audio readiness, performance budget, v2 release check.

Browser performance harness

• Playwright in Chromium and WebKit, locally and in GitHub Actions: noteOn to audible located to the sample on a master bus tap, dropouts over sixty seconds of generative Seed with and without eight modulation routes under a mock visual loop burning eight milliseconds a frame, control extremes on every species, a five second morph across a species switch, control audibility per species, bundle size against a budget. Dropouts, extremes, the morph and the size budget block; the rest is recorded per release.

Shared controls with species specific mappings is the idea that made the engine feel like one instrument instead of four. The honest beta was the right call; the premature major tag cost more trust than the extra week would have. The master analyser that every path feeds should have come first; when it landed, the stage lit up for the whole engine, and the harness built on it found that the default scheduling lookahead put a hundred milliseconds between noteOn and sound. Ten lines fixed it; the point is that it was measured before the surface was called stable. Eight placeholder species were cut rather than kept as promises. Modulation followed in 1.1, designed the same way: a grill first, a decisions table, then the code, then the harness rows before the tag. 1.2 held to it and added a rule: build the measuring tool before the work it measures. The lab page came first so the sound pass could start whenever ears were free, and it paid for itself the day it was built. The grill after that asked what the engine is in one sentence, and the answer, an instrument that plays itself and answers you, reordered the docs and the demo without touching a line of engine code: simpler is what you read first, not what exists.