updated api so runtime params can be adjusted before audio is running

Author: lucianpar

TODO.md

@@ -12,11 +12,12 @@
 
   - test speaker layout config on windows, validate code
 
+- clean up transcode tab?
+
 ## Other Tasks for final packaging:
 
-- clean up transcoder tab?
-- add render tab - update render code to match non linear channel handeling, give it render params ?
-- debug overall windows build \*\*\*
+OS AND COMPATIBILITY TESTING
+PACKAGING
 
 # Future Work - move to future work md
 

internalDocs/5_10_api_update.md

@@ -230,16 +230,30 @@ Implementation: `SpatialRootPaths::appSettingsRoot()` / `DefaultLayoutManager`.
 
 ## Runtime Control Plane
 
+**`RuntimeParams` is the canonical parameter struct.** Defaults come from `RuntimeParams::defaults()` — a single source of truth used by API, CLI, and GUI. Default values: `masterGainDb=0`, `dbapFocus=1.5`, `speakerMixDb=0`, `subMixDb=0`.
+
+**Staging before Run:** `configureRuntime(params)` can be called before `start()` to set initial playback values. The engine starts from these staged values — it does not briefly use hardcoded defaults. GUI sliders are editable before Run as staged values.
+
+**Live update after Run:** `configureRuntime()`, individual setters, and OSC callbacks all write to the same `RealtimeConfig` atomics and are safe to call while audio is running.
+
+**Querying current state:** `getRuntimeParams()` returns the current values in dB, reflecting the latest `configureRuntime()`, setter, or OSC change. Use this to sync GUI controls after a `resetRuntimeParams()` call.
+
+**Reset:** `resetRuntimeParams()` is equivalent to `configureRuntime(RuntimeParams::defaults())`. Safe before and after `start()`. Does not reload scene/layout, restart playback, or affect transport.
+
 **Primary (in-process):** ImGui GUI calls direct C++ setters on `EngineSession`:
 
-- `setMasterGainDb(float)`, `setDbapFocus(float)`, `setSpeakerMixDb(float)`, `setSubMixDb(float)`, `setElevationMode(ElevationMode)`
+- `setMasterGainDb(float)`, `setDbapFocus(float)`, `setSpeakerMixDb(float)`, `setSubMixDb(float)`, `setElevationMode(ElevationMode)`, `configureRuntime(RuntimeParams)`, `getRuntimeParams()`, `resetRuntimeParams()`
 
 **Secondary (optional OSC):** Remains available for external tooling/remote control.
 
 - Default port: `9009`; disable with `oscPort=0` in `EngineOptions`
+- OSC params are initialized from the current runtime state when `start()` is called
+- `configureRuntime()` and `resetRuntimeParams()` sync OSC param values if the server is running; individual setters do not
 - DBAP focus minimum is `0.1`; normalized DBAP preserves `sum(v_k^2) = 1`
 - See [REALTIME_ENGINE.md § OSC Parameter Reference](REALTIME_ENGINE.md#osc-parameter-reference) for full address/range table
 
+**Output routing** is layout-derived and initialized in `applyLayout()` → `configureOutputRouting()`. `configureRuntime()` no longer touches routing setup. CSV remap override is retained as deprecated internal scaffolding only.
+
 ---
 
 ## Common Issues & Solutions

internalDocs/AGENTS.md

@@ -57,12 +57,16 @@ struct LayoutInput {
 ```cpp
 struct RuntimeParams {
     float masterGainDb = 0.0f;      // Master gain in dB. Range: -60–+12 dB. 0 dB = unity.
-    float dbapFocus = 1.5f;         // DBAP rolloff exponent, minimum 0.1
-    float speakerMixDb = 0.0f;      // post-DBAP main trim in dB, range -60–+12 dB
-    float subMixDb = 0.0f;          // post-DBAP sub trim in dB, range -60–+12 dB
+    float dbapFocus    = 1.5f;      // DBAP rolloff exponent. Range: 0.1–5.0.
+    float speakerMixDb = 0.0f;      // Post-DBAP main trim in dB. Range: -60–+12 dB.
+    float subMixDb     = 0.0f;      // Post-DBAP sub trim in dB. Range: -60–+12 dB.
+
+    static RuntimeParams defaults(); // Canonical defaults — single source of truth.
 };
 ```
-All three dB fields are converted to linear at store time: `std::pow(10.0f, dB / 20.0f)`.
+All dB fields are converted to linear at store time via `clampDb` → `dbToLinear`.
+`getRuntimeParams()` performs the inverse conversion (`linearToDb`) and re-clamps; a zero or
+negative linear value returns `-60.0f` (never `-inf` or `NaN`).
 
 ---
 
@@ -72,31 +76,40 @@ The engine enforces a strict, linear initialization sequence:
 
 1. `configureEngine(const EngineOptions&)` — stores sampleRate, bufferSize, outputDeviceName, oscPort, elevationMode into `mConfig`. Always returns `true`.
 2. `loadScene(const SceneInput&)` — parses LUSID scene via `JSONLoader`, initializes `Streaming`. Returns `false` if scene file missing or no sources loaded.
-3. `applyLayout(const LayoutInput&)` — requires `loadScene` to have succeeded (`mSceneData` guard). Loads speaker layout, initializes `Pose` and `Spatializer`.
-4. `configureRuntime(const RuntimeParams&)` — writes gain/focus/mix atomics to `mConfig`. Loads remap CSV if path non-empty. **OSC ParameterServer is NOT started here — it starts in `start()`.**
-5. `start()` — creates and starts `al::ParameterServer` (if `oscPort > 0`), registers OSC callbacks, starts `RealtimeBackend` + loader thread. Prints `"ParameterServer listening"` to stdout when OSC is active.
+3. `applyLayout(const LayoutInput&)` — requires `loadScene` to have succeeded (`mSceneData` guard). Loads speaker layout, initializes `Pose` and `Spatializer`. Calls `configureOutputRouting()` internally.
+4. `configureRuntime(const RuntimeParams&)` — clamps and writes gain/focus/mix atomics to `mConfig`. **Does not perform output routing setup** (moved to `applyLayout()`). Safe before and after `start()`. Syncs OSC param values if the OSC server is already running. **OSC ParameterServer is NOT started here — it starts in `start()`.**
+5. `start()` — creates and starts `al::ParameterServer` (if `oscPort > 0`), initializes OSC params from current runtime state via `getRuntimeParams()`, registers OSC callbacks, starts `RealtimeBackend` + loader thread.
+
+**Runtime control (before or after `start()`):**
 
-**Runtime Control (after `start()`):**
+`configureRuntime()` is safe to call at any point after `configureEngine()`:
+- **Before `start()`:** stages the initial playback values; the engine will start from these.
+- **After `start()`:** applies values live through the same atomic path as the individual setters.
 
-| Method | Writes to | Notes |
+| Method | Writes | Notes |
 |---|---|---|
+| `configureRuntime(const RuntimeParams&)` | all 4 gain/focus params | Clamps + converts dB→linear. Syncs OSC if running. |
+| `getRuntimeParams() -> RuntimeParams` | — (read only) | Returns current state in dB; reflects setters, OSC changes, and `configureRuntime`. |
+| `resetRuntimeParams()` | all 4 gain/focus params | Equivalent to `configureRuntime(RuntimeParams::defaults())`. Does not restart playback, reload scene/layout, or clear files. |
 | `setPaused(bool)` | `mConfig.paused` | Only supported transport control. Stop/seek unsupported. |
-| `update()` | — | Should be called from the main thread / host loop. Currently retained for API stability; no deferred focus-compensation work remains. |
+| `update()` | — | Should be called from the main thread / host loop. Currently retained for API stability. |
 | `queryStatus() -> EngineStatus` | — | Lock-free snapshot. No state mutation. |
 | `consumeDiagnostics() -> DiagnosticEvents` | — | Atomically exchanges event flags. Clears them on read. |
 | `shutdown()` | — | Terminal. Destroy and recreate `EngineSession` to restart. |
 
-**Phase 6 runtime setters (direct C++ control, no OSC required):**
+**Runtime setters (direct C++ control — no OSC required; no OSC sync on individual setters):**
 
-| Method | Writes | Notes |
+| Method | Writes | Range |
 |---|---|---|
-| `setMasterGainDb(float)` | `mConfig.masterGain` | dB → linear conversion at store time; range -60–+12 dB |
-| `setDbapFocus(float)` | `mConfig.dbapFocus` | Clamped to a minimum of `0.1f` |
-| `setSpeakerMixDb(float)` | `mConfig.loudspeakerMix` | dB → linear conversion at store time |
-| `setSubMixDb(float)` | `mConfig.subMix` | dB → linear conversion at store time |
-| `setElevationMode(ElevationMode)` | `mConfig.elevationMode` | Cast to int at store time |
-
-All writes use `std::memory_order_relaxed`. Safe to call after `start()` and before `shutdown()`.
+| `setMasterGainDb(float)` | `mConfig.masterGain` | -60–+12 dB |
+| `setDbapFocus(float)` | `mConfig.dbapFocus` | min 0.1 |
+| `setSpeakerMixDb(float)` | `mConfig.loudspeakerMix` | -60–+12 dB |
+| `setSubMixDb(float)` | `mConfig.subMix` | -60–+12 dB |
+| `setElevationMode(ElevationMode)` | `mConfig.elevationMode` | cast to int |
+
+All writes use `std::memory_order_relaxed`. Safe to call before and after `start()`.
+Individual setters do **not** sync OSC visible parameter values. Use `configureRuntime()` or
+`resetRuntimeParams()` when OSC sync is required.
 
 ### Error Model
 

internalDocs/API_internal.md

@@ -278,11 +278,16 @@ Threading model: audio thread (RT, AlloLib), loader thread (background disk I/O)
 - **Resume step calculation:** Fade-in step is now `(1.0f - mPauseFade) / fadeFrames` rather than always `1/fadeFrames`. Ramp continues from current gain instead of resetting to zero (Bug 11.3).
 - **`stop()` fade-before-hard-stop:** Arms pause fade and unconditionally sleeps 50ms before calling `mAudioIO.stop()`. Resets `mConfig.paused = false` afterward (Bugs 11.2, 11.4).
 
-**Gain system (May 7, 2026):** All three gain controls now accept dB at every public surface. Conversion to linear (`std::pow(10.0f, dB / 20.0f)`) happens at the API boundary in `configureRuntime()`, `setMasterGainDb()`, `setSpeakerMixDb()`, `setSubMixDb()`, and OSC callbacks. Internal `RealtimeConfig` atomics remain linear.
+**Gain system (May 7, 2026; updated May 10, 2026):** All gain controls accept dB at every public surface. Conversion to linear (`clampDb` → `dbToLinear = std::pow(10.0f, dB / 20.0f)`) happens at the API boundary via `applyRuntimeParamsToConfig()`, called by `configureRuntime()`, individual setters, and OSC callbacks. `getRuntimeParams()` performs the inverse via `linearToDb`; zero/negative linear → `-60.0f` (never -inf). Internal `RealtimeConfig` atomics remain linear.
+
+`configureRuntime()` no longer performs output routing setup. Output routing is now initialized in `applyLayout()` → `configureOutputRouting()`. `configureRuntime()` is safe to call before or after `start()`.
+
+`RuntimeParams::defaults()` is the single canonical source of default values for API, CLI, and GUI. `resetRuntimeParams()` is equivalent to `configureRuntime(RuntimeParams::defaults())`.
 
 | Control | Public API | Range | Default | OSC address |
 |---|---|---|---|---|
 | Master gain | `RuntimeParams::masterGainDb`, `setMasterGainDb(float)` | -60–+12 dB | 0.0 dB | `/realtime/gain_db` |
+| DBAP focus | `RuntimeParams::dbapFocus`, `setDbapFocus(float)` | 0.1–5.0 | 1.5 | `/realtime/focus` |
 | Speaker mix | `RuntimeParams::speakerMixDb`, `setSpeakerMixDb(float)` | -60–+12 dB | 0.0 dB | `/realtime/speaker_mix_db` |
 | Sub mix | `RuntimeParams::subMixDb`, `setSubMixDb(float)` | -60–+12 dB | 0.0 dB | `/realtime/sub_mix_db` |
 

internalDocs/REALTIME_ENGINE.md

@@ -5,6 +5,40 @@
 
 ---
 
+## Runtime Parameter Staging, Reset, and Single-Source Defaults (May 10, 2026)
+
+**Status:** Complete. Covers `EngineSession` API, CLI, GUI, and docs.
+
+**Motivation:** Runtime controls (gain, focus, mix) were disabled in the GUI before playback started and reset to hardcoded defaults on every Start click. Default values were duplicated across `RuntimeParams`, CLI argument parsing, and `resetRuntimeToDefaults()` in App.cpp. `configureRuntime()` mixed parameter setup with output routing setup, making it unsafe to call before `applyLayout()`.
+
+**What changed:**
+
+- `EngineSession.hpp` / `EngineSession.cpp`:
+  - Added `RuntimeParams::defaults()` — single canonical source of default values.
+  - Added file-local helpers: `clampDb`, `clampFocus`, `dbToLinear`, `linearToDb` (defensive: zero/negative linear → -60 dB, not -inf).
+  - Added private `sanitizeRuntimeParams()`, `applyRuntimeParamsToConfig()`, `configureOutputRouting()`.
+  - Added public `getRuntimeParams()` — reads atomics, converts linear→dB, re-clamps; reflects setters, OSC, and `configureRuntime` changes.
+  - Added public `resetRuntimeParams()` — equivalent to `configureRuntime(RuntimeParams::defaults())`.
+  - Refactored `configureRuntime()`: now only writes gain/focus/mix atomics + syncs OSC if running. No longer touches `mSpatializer` or `OutputRemap`.
+  - Moved output routing setup (remap CSV scaffolding + layout-derived routing) to `configureOutputRouting()`, called at the end of `applyLayout()`. `configureRuntime()` is now safe to call before `applyLayout()`.
+  - Updated `start()`: initializes OSC param values from `getRuntimeParams()` instead of reading atomics directly.
+  - Updated individual setters to use `clampDb`/`clampFocus`/`dbToLinear` helpers consistently.
+
+- `main.cpp`: CLI now initializes `RuntimeParams` from `RuntimeParams::defaults()` and overrides from flags, eliminating duplicated literal defaults.
+
+- `App.cpp`:
+  - Removed `BeginDisabled` guard around runtime controls — sliders/inputs are always editable as staged values before Run.
+  - Input callbacks always clamp; setters called only when running.
+  - Added "Reset Parameters" SmallButton inline with the RUNTIME CONTROLS header. Before Run: resets GUI staged values via `resetRuntimeToDefaults()`. After Run: calls `mSession->resetRuntimeParams()` and syncs GUI from `mSession->getRuntimeParams()`.
+  - Removed `resetRuntimeToDefaults()` call from `onStart()` — staged values are now preserved when playback starts.
+  - Updated `resetRuntimeToDefaults()` to use `RuntimeParams::defaults()` instead of hardcoded literals.
+
+- `internalDocs/API_internal.md`, `REALTIME_ENGINE.md`, `AGENTS.md`: updated to reflect new API methods, routing refactor, defaults source, and OSC sync semantics.
+
+**OSC sync note:** `configureRuntime()` and `resetRuntimeParams()` sync OSC-visible parameter values when the OSC server is running. Individual setters (`setMasterGainDb` etc.) do not sync OSC values — they write atomics only. `getRuntimeParams()` reflects OSC changes because both OSC callbacks and setters write the same atomics.
+
+---
+
 ## Offline ADM Rendering — Phase 3B/3C: CULT Orchestration + Source Validation (May 10, 2026)
 
 **Status:** Complete. `--adm` without `--positions` now mirrors the realtime ADM architecture end-to-end.