> ## Documentation Index > Fetch the complete documentation index at: https://docs.baryon.live/docs/llms.txt > Use this file to discover all available pages before exploring further. # Engine architecture > How the open Baryon engine turns live audio into a volumetric cymatic field, and the contracts that keep it stable. This is a conceptual map of the open Baryon engine: the pipeline, the one seam that matters most, and the contracts that stay stable across versions. For the governing equations and the modal physics, read the engine whitepaper; for the implementation, read the [source on GitHub](https://github.com/BaryonOfficial/Baryon). ## The pipeline The engine turns live audio into a volumetric cymatic field through one mostly linear path: ```text theme={null} audio source -> Web Audio analyzers / live-input analysis -> feature building -> AudioFeatureFrame -> visualization runtime -> render / output -> presentation ``` The defining property is that Baryon is **not** a generic audio-reactive renderer. The audio side interprets musical and resonant structure first, and the render side consumes that interpreted structure. Most "the visuals look wrong" questions are really questions about which stage owns the behavior. ## The packages The engine ships as two shared packages, consumed by the web app: * **`packages/engine`** — the engine and its domain semantics: audio analysis, `AudioFeatureFrame` construction, the control schema, render-profile policy, and the raymarch runtime. * **`packages/app-shell`** — the shared React orchestration around the engine: control-state lifecycle, the render loop, runtime diagnostics, and scene mounting. * **`apps/web`** — the browser product shell. Host integrations that embed the engine wrap these shared packages rather than forking their semantics. ## The main seam The highest-value boundary in the engine is: ```text theme={null} audio analysis -> AudioFeatureFrame -> visualization runtime ``` It exists so that audio interpretation stays renderer-agnostic, render bugs can be debugged without rewriting analysis semantics, and a new runtime can consume the same authoritative structure. When a render symptom appears, the first job is to locate which stage owns it: capture and live-input classification, feature construction, or render consumption. ## The contracts that stay stable These boundaries should be treated as stable unless a change explicitly intends to move them. The goal is not "never refactor" — it is to avoid accidental breakage where Baryon has persisted settings and a shared engine that more than one host can consume. ### `AudioFeatureFrame` The authoritative boundary between audio interpretation and visualization. The audio side interprets signal structure; the render side consumes it; render code must not silently rebuild analysis from raw audio. The mental model is one chain: `audio drive -> rectangular water-cavity modes -> modal pressure field -> spherical render hull`. Pressure and radiation values are normalized visualization quantities — not calibrated acoustic measurements. Adding fields that consumers can ignore, or restructuring internal stages, is safe; changing the meaning of an existing field without a coordinated migration is not. ### Control schema The source of truth for control keys, defaults, applicability, and whether a control is live or debug-only. Changing a label is cheap. Changing a key that is persisted or synced is a compatibility change, because that key is effectively part of a stored format. ### Persistence Only controls marked **live** are saved into presets and auto-save; debug-only controls are excluded. Loading starts from schema defaults, drops unknown keys, falls back to defaults for missing ones, and normalizes a few legacy fields forward. Adding a new live control with a correct default is usually safe; renaming or removing a persisted key needs explicit migration. ### Visualization method `raymarch` is the only supported method. Legacy values (`fullscreen-volume`, `cymatics-2d`) collapse to `raymarch` at ingress. The field is kept as a constant for forward compatibility; there is no user-facing visualizer selector. ### Performance profile Three values: `auto` (adaptive step-budget behavior on), `custom` (adapts toward an explicit frame budget), and `max-quality` (step-budget adaptation off). Persisted control/config ingress still migrates the legacy `none` alias to `max-quality`; live render profiles stay canonical. The user-facing wording is "Performance Profile," but some compatibility fields still use `qualityPreset` or `renderQualityPreset` — treat those as naming vocabulary that still matters, not as free renames. ### Input semantics Line-feed / system input and acoustic-microphone input are intentionally distinct analysis paths; collapsing them into a single live-input mode is high-risk. Within acoustic-mic input, the **Voice** and **Ambient** profiles are small policy deltas over one shared engine, not separate analyzers. Source confidence is input evidence only — it does not grant render authority. ### Spectral Light color Audio interpretation produces additive first- and second-order circular pitch moments per modal term and carries them through spectral-moment slots. The persistent observer caches one resolved unit phase direction directly in appearance XY. On the same observer step it evaluates the constant-luminance two-harmonic mapping once and stores a derived RGB chromatic companion in organization RGB. The material fetches that companion from one nearest observer voxel, so RGB interpolation cannot cross grey. This adds no render target or palette lookup. The renderer never reconstructs pitch evidence from raw FFT bins. The plasma allocates its scalar radiance budget before applying that unit-luminance chromaticity, so pitch can change hue but not geometry, extinction, or brightness. A spectral moment must not promote a mode on its own. An explicit Spectral Chroma control may move that chromaticity toward equal-luminance neutral without blending in static colors or changing acoustic radiance. The detailed Spectral Light architecture lives in the engine whitepaper. ## Changing the engine safely Before moving a boundary, ask whether the change is **semantic** or an **implementation detail**, whether the value crosses persistence or host boundaries, and whether tests already assert its shape. Prefer normalization layers and dual-read compatibility over broad renames at genuine persistence or host boundaries. Inside the semantic core, use one canonical name and translate legacy values only at the boundary that still requires them.