override default output device for windows build, cult allolib changes and spatial root changes in realtime engine and app

Author: lucianpar

PUBLIC_DOCS/API.md

@@ -90,7 +90,8 @@ While running, call `update()`, `queryStatus()`, and `consumeDiagnostics()` regu
 | --- | --- | --- | --- |
 | `sampleRate` | `int` | `48000` | Audio sample rate in Hz |
 | `bufferSize` | `int` | `512` | Frames per audio callback |
-| `outputDeviceName` | `std::string` | `""` | Exact device name; empty selects the system default |
+| `outputDeviceId` | `int` | `-1` | Stable backend output-device id; `-1` selects the system default |
+| `outputDeviceName` | `std::string` | `""` | Display name / CLI fallback; used only when no device id is provided |
 | `oscPort` | `int` | `9009` | OSC control port; set to `0` to disable OSC |
 | `elevationMode` | `ElevationMode` | `RescaleAtmosUp` | Vertical remapping mode |
 
@@ -195,6 +196,7 @@ If `containsAudio.json` is present, it is the preferred source-to-file mapping c
 - `audioBackendLabel`
 - `requestedSampleRate`
 - `effectiveStreamSampleRate`
+- `outputDeviceId`
 - `outputDeviceName`
 - `outputDevicePreferredSampleRate`
 

internal/cult-allolib

@@ -19,7 +19,7 @@
 
 | Struct | Purpose |
 |---|---|
-| `EngineOptions` | Core system settings (sample rate, buffer size, device name, OSC port, elevation mode) |
+| `EngineOptions` | Core system settings (sample rate, buffer size, device id/name, OSC port, elevation mode) |
 | `SceneInput` | Audio scene definition (LUSID scene path, sources folder, ADM file) |
 | `LayoutInput` | Speaker layout path and optional remap CSV path |
 | `RuntimeParams` | Initial gain/focus/mix values passed at configure time |
@@ -35,6 +35,7 @@
 struct EngineOptions {
     int sampleRate = 48000;
     int bufferSize = 512;
+    int outputDeviceId = -1;        // stable backend id; -1 = system default
     std::string outputDeviceName;   // empty = system default
     int oscPort = 9009;             // 0 = disable OSC entirely
     ElevationMode elevationMode = ElevationMode::RescaleAtmosUp;
@@ -83,6 +84,7 @@ std::string audioBackendLabel;              // best-effort runtime backend/API l
 int requestedSampleRate = 48000;           // requested engine rate
 double effectiveStreamSampleRate = 0.0;    // actual running stream rate, if known
 bool effectiveStreamSampleRateKnown = false;
+int outputDeviceId = -1;                   // resolved backend output device id, if known
 std::string outputDeviceName;              // selected output device, if known
 double outputDevicePreferredSampleRate = 0.0; // device preferred/default rate, if known
 bool outputDevicePreferredSampleRateKnown = false;
@@ -102,7 +104,7 @@ Semantics:
 
 The engine enforces a strict, linear initialization sequence:
 
-1. `configureEngine(const EngineOptions&)` — stores sampleRate, bufferSize, outputDeviceName, oscPort, elevationMode into `mConfig`. Always returns `true`.
+1. `configureEngine(const EngineOptions&)` — stores sampleRate, bufferSize, outputDeviceId, 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`. 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()`.**

internalDocs/API_internal.md

@@ -281,6 +281,7 @@ App::App(std::string projectRoot, bool keepTempSessions, std::string tempRootOve
     tryLoadDefaultLayoutOnStartup();
 
     appendEngineLog("[GUI] Select a source and layout, then click START.");
+    scanDevices();
 
     int lw = 0, lh = 0, lch = 0;
     unsigned char* logoData = stbi_load_from_memory(
@@ -584,6 +585,12 @@ void App::renderEngineTab() {
         (mDeviceIdx >= 0 && mDeviceIdx < static_cast<int>(mDeviceOutputChannels.size()))
             ? mDeviceOutputChannels[mDeviceIdx]
             : 0;
+    const int selectedDeviceBackendId =
+        (mDeviceIdx >= 0 && mDeviceIdx < static_cast<int>(mDeviceBackendIds.size()))
+            ? mDeviceBackendIds[mDeviceIdx]
+            : -1;
+    const int activeDeviceBackendId =
+        (mStatus.outputDeviceId >= 0) ? mStatus.outputDeviceId : selectedDeviceBackendId;
     const double scannedDeviceSampleRate =
         (mDeviceIdx >= 0 && mDeviceIdx < static_cast<int>(mDeviceSampleRates.size()))
             ? mDeviceSampleRates[mDeviceIdx]
@@ -726,6 +733,9 @@ void App::renderEngineTab() {
                    << (audioReady ? "Ready" : (audioNotReady ? "Not Ready" : "Unknown")) << "\n"
                    << "Backend: " << backendLabel << "\n"
                    << "Device: " << activeDeviceName << "\n"
+                   << "Device ID: "
+                   << (activeDeviceBackendId >= 0 ? std::to_string(activeDeviceBackendId)
+                                                    : std::string("system default")) << "\n"
                    << "Output Channels: "
                    << (selectedOutputChannels > 0 ? std::to_string(selectedOutputChannels) : "unknown") << "\n"
                    << "Required sample rate: " << requiredSampleRate << " Hz\n"
@@ -755,6 +765,10 @@ void App::renderEngineTab() {
                 ImGui::SetNextItemWidth(ImGui::GetContentRegionAvail().x);
                 if (ImGui::Combo("##device", &mDeviceIdx, items.data(), (int)items.size())) {
                     mDeviceName = (mDeviceIdx == 0) ? "" : mDeviceList[mDeviceIdx];
+                    mDeviceBackendId =
+                        (mDeviceIdx >= 0 && mDeviceIdx < static_cast<int>(mDeviceBackendIds.size()))
+                            ? mDeviceBackendIds[mDeviceIdx]
+                            : -1;
                 }
             }
             if (selectedOutputChannels > 0) {
@@ -1621,6 +1635,7 @@ void App::doLaunchEngine(const std::string& scenePath,
     EngineOptions opts;
     opts.sampleRate = 48000;
     opts.bufferSize = kBufferSizes[mBufferSizeIdx];
+    opts.outputDeviceId = mDeviceBackendId;
     opts.outputDeviceName = mDeviceName;
     opts.oscPort = 9009;
     opts.elevationMode = static_cast<ElevationMode>(mElevationMode);
@@ -1823,23 +1838,38 @@ void App::resetRuntimeToDefaults() {
 }
 
 void App::scanDevices() {
+    const int previousDeviceId = mDeviceBackendId;
+    const std::string previousDeviceName = mDeviceName;
     mDeviceList.clear();
+    mDeviceBackendIds.clear();
     mDeviceOutputChannels.clear();
     mDeviceSampleRates.clear();
     mDeviceList.push_back("(system default)");
+    mDeviceBackendIds.push_back(-1);
     mDeviceOutputChannels.push_back(0);
     mDeviceSampleRates.push_back(0.0);
     const int n = al::AudioDevice::numDevices();
     for (int i = 0; i < n; ++i) {
         al::AudioDevice dev(i);
         if (dev.valid() && dev.hasOutput()) {
             mDeviceList.push_back(std::string(dev.name()));
+            mDeviceBackendIds.push_back(dev.id());
             mDeviceOutputChannels.push_back(dev.channelsOutMax());
             mDeviceSampleRates.push_back(dev.defaultSampleRate());
         }
     }
     mDeviceIdx = 0;
+    mDeviceBackendId = -1;
     mDeviceName = "";
+    for (int i = 1; i < static_cast<int>(mDeviceBackendIds.size()); ++i) {
+        if ((previousDeviceId >= 0 && mDeviceBackendIds[i] == previousDeviceId) ||
+            (!previousDeviceName.empty() && mDeviceList[i] == previousDeviceName)) {
+            mDeviceIdx = i;
+            mDeviceBackendId = mDeviceBackendIds[i];
+            mDeviceName = mDeviceList[i];
+            break;
+        }
+    }
 }
 
 void App::detectSource() {

source/gui/imgui/src/App.cpp

@@ -92,8 +92,10 @@ class App {
     std::string mLayoutPath;   // speaker layout JSON
     std::string              mDeviceName;   // "" = system default
     std::vector<std::string> mDeviceList;  // populated by scanDevices(); [0] = system default
+    std::vector<int>         mDeviceBackendIds; // mirrors mDeviceList; -1 = system default
     std::vector<int>         mDeviceOutputChannels; // mirrors mDeviceList; 0 = unknown/system default
     std::vector<double>      mDeviceSampleRates;    // mirrors mDeviceList; 0.0 = unknown/system default
+    int                      mDeviceBackendId = -1;
     int                      mDeviceIdx = 0;
     int         mBufferSizeIdx = 3;   // index into kBufferSizes[]
     int         mLayoutPreset  = 0;   // index into kLayoutNames[]

source/gui/imgui/src/App.hpp

@@ -182,6 +182,7 @@ bool EngineSession::configureEngine(const EngineOptions& opts)
 {
     mConfig.sampleRate = opts.sampleRate;
     mConfig.bufferSize = opts.bufferSize;
+    mConfig.outputDeviceId = opts.outputDeviceId;
     mConfig.outputDeviceName = opts.outputDeviceName;
     mOscPort = opts.oscPort;
     mConfig.elevationMode.store(static_cast<int>(opts.elevationMode), std::memory_order_relaxed);
@@ -552,9 +553,11 @@ EngineStatus EngineSession::queryStatus() const
     st.paused = mConfig.paused.load(std::memory_order_relaxed);
     st.isExitRequested = (mBackend && !mBackend->isRunning()); 
     st.requestedSampleRate = mConfig.sampleRate;
+    st.outputDeviceId = mConfig.outputDeviceId;
     st.outputDeviceName = mConfig.outputDeviceName.empty() ? "(system default)" : mConfig.outputDeviceName;
     if (mBackend) {
         st.audioBackendLabel = mBackend->backendDisplayLabel();
+        st.outputDeviceId = mBackend->selectedDeviceId();
         st.outputDeviceName = mBackend->selectedDeviceName().empty()
                                 ? st.outputDeviceName
                                 : mBackend->selectedDeviceName();

source/spatial_engine/realtimeEngine/src/EngineSession.cpp

@@ -32,6 +32,7 @@ struct EngineStatus {
     int requestedSampleRate = 48000;
     double effectiveStreamSampleRate = 0.0;
     bool effectiveStreamSampleRateKnown = false;
+    int outputDeviceId = -1;
     std::string outputDeviceName;
     double outputDevicePreferredSampleRate = 0.0;
     bool outputDevicePreferredSampleRateKnown = false;
@@ -67,6 +68,7 @@ struct DiagnosticEvents {
 struct EngineOptions {
     int sampleRate = 48000;
     int bufferSize = 512;
+    int outputDeviceId = -1;
     std::string outputDeviceName;
     int oscPort = 9009;
     ElevationMode elevationMode = ElevationMode::RescaleAtmosUp;