GUI - tell the user when the sound moves to a different output device

Author: samaaron

app/api/include/api/sonicpi_api.h

@@ -508,6 +508,9 @@ struct IAPIClient
     // AudioSwitchOutcome. Default no-op so non-GUI consumers don't
     // need to react.
     virtual void AudioSwitchDone(const AudioSwitchOutcome& /*outcome*/) {}
+    // The engine's state and why it changed (/clockwork/statechange: "boot",
+    // "rate-change", "snapshot", "swap-failed-rollback"). Default no-op.
+    virtual void AudioStateChanged(const std::string& /*state*/, const std::string& /*reason*/) {}
     // Immediate accept/reject for /clockwork/devices/reopen (the engine
     // debounces: in-flight or <3s cooldown → rejected). Default no-op.
     virtual void AudioDeviceReopenReply(bool /*accepted*/, const std::string& /*reason*/) {}

app/api/src/osc/osc_handler.cpp

@@ -462,6 +462,7 @@ void OscHandler::oscMessage(std::vector<char> buffer)
             std::string state, reason;
             msg->arg().popStr(state).popStr(reason);
             LOG(INFO, "/clockwork/statechange: " << state << " (" << reason << ")");
+            m_pClient->AudioStateChanged(state, reason);
             if (state == "restarting") {
                 // Show "switching" status in GUI while device change is in progress
                 ScsynthInfo info;

app/gui-tests/audiodevicepolicy.test.cpp

@@ -451,3 +451,64 @@ TEST_CASE("input pick: an unknown driver on either side is left to the engine",
     noInputDriver.engineDriver = "DirectSound";
     REQUIRE(audioInputPickPlan(noInputDriver).send);
 }
+
+// ── 4. Telling the user ────────────────────────────────────────────────────
+//
+// On 2026-10-06 the MOTU was absent at boot: the restore asked for it, the
+// engine refused, the pref was cleared to "follow system" (rightly, so a dead
+// device is not replayed every boot) — and nothing on screen said so. The next
+// boot followed the system default to a streamer in another room, again
+// silently. The decision now says what the user must hear.
+
+TEST_CASE("notice: a failed request names the output that isn't available", "[audio][notice]")
+{
+    SonicPi::AudioSwitchRequest request;
+    request.output = "motu-xaero";
+    SonicPi::AudioSwitchOutcome outcome;
+    outcome.success = false;
+    outcome.error = "No such device: motu-xaero";
+    const auto d = SonicPi::audioPrefsDecision(request, outcome);
+    CHECK(d.notice == SonicPi::AudioNotice::OutputUnavailable);
+    CHECK(d.noticeDevice == "motu-xaero");
+}
+
+TEST_CASE("notice: following the system default names the device it resolved to", "[audio][notice]")
+{
+    SonicPi::AudioSwitchRequest request;
+    request.output = SonicPi::kAudioSystemOutput;
+    SonicPi::AudioSwitchOutcome outcome;
+    outcome.success = true;
+    outcome.actualOutput = "DMP-A6(Kitchen)";
+    const auto d = SonicPi::audioPrefsDecision(request, outcome);
+    CHECK(d.notice == SonicPi::AudioNotice::FollowingSystemDefault);
+    CHECK(d.noticeDevice == "DMP-A6(Kitchen)");
+
+    SonicPi::AudioSwitchRequest byRow;
+    byRow.output = "Some Default Row";
+    byRow.outputFollowsDefault = true;
+    const auto r = SonicPi::audioPrefsDecision(byRow, outcome);
+    CHECK(r.notice == SonicPi::AudioNotice::FollowingSystemDefault);
+}
+
+TEST_CASE("notice: a device the user named and got raises none, nor does an engine-initiated swap", "[audio][notice]")
+{
+    SonicPi::AudioSwitchRequest request;
+    request.output = "motu-xaero";
+    SonicPi::AudioSwitchOutcome outcome;
+    outcome.success = true;
+    outcome.actualOutput = "motu-xaero";
+    CHECK(SonicPi::audioPrefsDecision(request, outcome).notice == SonicPi::AudioNotice::None);
+    SonicPi::AudioSwitchRequest engineInitiated;   // nothing asked: the engine's own reopen
+    CHECK(SonicPi::audioPrefsDecision(engineInitiated, outcome).notice == SonicPi::AudioNotice::None);
+}
+
+TEST_CASE("notice: the engine falling back on its own, mid-session, is a lost device", "[audio][notice]")
+{
+    // The engine's own swap rolled back (a device unplugged, a reopen refused):
+    // the next device-list push names where the sound went, and the user hears it.
+    CHECK(SonicPi::audioStateLostDevice("running", "swap-failed-rollback"));
+    CHECK_FALSE(SonicPi::audioStateLostDevice("running", "rate-change"));   // a swap the user asked for
+    CHECK_FALSE(SonicPi::audioStateLostDevice("running", "boot"));
+    CHECK_FALSE(SonicPi::audioStateLostDevice("running", "snapshot"));
+    CHECK_FALSE(SonicPi::audioStateLostDevice("restarting", "swap-failed-rollback"));   // not until it is running again
+}

app/gui/mainwindow.cpp

@@ -847,6 +847,8 @@ void MainWindow::setupWindowStructure()
             this, &MainWindow::onMixerSettings);
     connect(m_spClient.get(), &SonicPi::QtAPIClient::AudioSwitchDoneReceived,
             this, &MainWindow::onAudioSwitchDone);
+    connect(m_spClient.get(), &SonicPi::QtAPIClient::AudioStateChangedReceived,
+            this, &MainWindow::onAudioStateChanged, Qt::QueuedConnection);
     connect(m_spClient.get(), &SonicPi::QtAPIClient::AudioDeviceReopenReplyReceived,
             this, &MainWindow::onAudioDeviceReopenReply);
 
@@ -9349,9 +9351,23 @@ void MainWindow::updateAudioDevices(const SonicPi::AudioDevicesInfo& devicesInfo
     m_lastAudioDevices = devicesInfo;
     m_audioDevicesSeen = true;
     settingsWidget->updateAudioDevices(devicesInfo);
+    // The engine lost its device and fell back on its own: this push names
+    // where the sound went (audiodevicepolicy.h, audioStateLostDevice).
+    if (m_announceDeviceAfterRollback)
+    {
+        m_announceDeviceAfterRollback = false;
+        showStatusAndAnnounce(tr("Audio device lost — output is now %1")
+                                  .arg(QString::fromStdString(devicesInfo.currentDevice)), 8000);
+    }
     maybeRestoreAudioIntent();
 }
 
+void MainWindow::onAudioStateChanged(const QString& state, const QString& reason)
+{
+    if (SonicPi::audioStateLostDevice(state.toStdString(), reason.toStdString()))
+        m_announceDeviceAfterRollback = true;
+}
+
 void MainWindow::updateAudioInputDevices(const SonicPi::AudioInputDevicesInfo& devicesInfo)
 {
     m_lastAudioInputDevices = devicesInfo;
@@ -9659,6 +9675,22 @@ void MainWindow::onAudioSwitchDone(const SonicPi::AudioSwitchOutcome& outcome)
         gui_settings->setValue("prefs/audio-buffer-size", decision.bufferSizeValue);
     }
 
+    // Where the sound now goes, when it is not where the user pointed: on
+    // the status bar and to a screen reader, whether or not the preferences
+    // are open (audiodevicepolicy.h, AudioNotice).
+    switch (decision.notice) {
+    case SonicPi::AudioNotice::OutputUnavailable:
+        showStatusAndAnnounce(tr("Audio output '%1' isn't available — following the system default")
+                                  .arg(QString::fromStdString(decision.noticeDevice)), 8000);
+        break;
+    case SonicPi::AudioNotice::FollowingSystemDefault:
+        showStatusAndAnnounce(tr("Audio output: %1 (the system default)")
+                                  .arg(QString::fromStdString(decision.noticeDevice)), 6000);
+        break;
+    case SonicPi::AudioNotice::None:
+        break;
+    }
+
     // Two failure shapes from the engine. Surface both as a modal
     // carrying the verbatim engine/JUCE error — no diagnosis, no
     // enrichment. Revert the affected dropdown.

app/gui/mainwindow.h

@@ -632,6 +632,8 @@ private slots:
 #if defined(Q_OS_MAC) || defined(Q_OS_WIN)
     // A+V session-recorder branch of toggleRecording. Write to a temp
     // file; rename or delete it once the user picks a save location.
+    void onAudioStateChanged(const QString& state, const QString& reason);   // the engine's own fallback: say where the sound went
+    bool m_announceDeviceAfterRollback = false;
     void startSessionRecordingFlow();
     void stopSessionRecordingFlow();
     void recordingFailed(const QString& reason);   // the recorder could not start or died: Record goes back

app/gui/qt_api_client.cpp

@@ -534,6 +534,11 @@ void QtAPIClient::AudioSwitchDone(const SonicPi::AudioSwitchOutcome& outcome)
   emit AudioSwitchDoneReceived(outcome);
 }
 
+void QtAPIClient::AudioStateChanged(const std::string& state, const std::string& reason)
+{
+  emit AudioStateChangedReceived(QString::fromStdString(state), QString::fromStdString(reason));
+}
+
 void QtAPIClient::AudioDeviceReopenReply(bool accepted, const std::string& reason)
 {
   emit AudioDeviceReopenReplyReceived(accepted, QString::fromStdString(reason));

app/gui/qt_api_client.h

@@ -76,6 +76,7 @@ class QtAPIClient : public QObject, public SonicPi::IAPIClient
     virtual void SupersonicSetup(int sampleRate, int bufferSize) override;
     virtual void SpiderReady() override;
     virtual void AudioSwitchDone(const SonicPi::AudioSwitchOutcome& outcome) override;
+    virtual void AudioStateChanged(const std::string& state, const std::string& reason) override;
     virtual void AudioDeviceReopenReply(bool accepted, const std::string& reason) override;
     virtual void RunStarted(int jobId, const std::string& workspace) override;
     virtual void RunEnded(int jobId) override;
@@ -95,6 +96,7 @@ class QtAPIClient : public QObject, public SonicPi::IAPIClient
     void SupersonicSetupReceived(int sampleRate, int bufferSize);
     void SpiderReadyReceived();
     void AudioSwitchDoneReceived(const SonicPi::AudioSwitchOutcome& outcome);
+    void AudioStateChangedReceived(const QString& state, const QString& reason);
     void AudioDeviceReopenReplyReceived(bool accepted, const QString& reason);
     void RunStartedReceived(int jobId, const QString& workspace);
     void RunEndedReceived(int jobId);

app/gui/utils/audiodevicepolicy.h

@@ -117,7 +117,16 @@ struct AudioSwitchRequest {
 
 enum class PrefAction { Leave, Save, Clear };
 
+// What the user must hear about the swap, on the status bar and to a screen
+// reader — not only inside the preferences pane, which may not be open:
+// the output they asked for could not be opened (its pref is dropped, so
+// the next boot follows the system default), or the system default was
+// followed and resolved to a particular device, which may be in another room.
+enum class AudioNotice { None, OutputUnavailable, FollowingSystemDefault };
+
 struct AudioPrefsDecision {
+    AudioNotice notice = AudioNotice::None;
+    std::string noticeDevice;   // the output asked for, or the one now followed
     PrefAction  output = PrefAction::Leave;
     std::string outputValue;
     PrefAction  input = PrefAction::Leave;
@@ -150,8 +159,12 @@ inline AudioPrefsDecision audioPrefsDecision(const AudioSwitchRequest& request,
 
     if (!outcome.success) {
         // Drop the saved value for whatever was asked for, so a device that no
-        // longer exists isn't replayed on every boot.
-        if (!request.output.empty()) d.output = PrefAction::Clear;
+        // longer exists isn't replayed on every boot — and say so.
+        if (!request.output.empty()) {
+            d.output = PrefAction::Clear;
+            d.notice = AudioNotice::OutputUnavailable;
+            d.noticeDevice = request.output;
+        }
         if (!request.input.empty())  d.input  = PrefAction::Clear;
         return d;
     }
@@ -163,6 +176,8 @@ inline AudioPrefsDecision audioPrefsDecision(const AudioSwitchRequest& request,
     if (request.output == kAudioSystemOutput || request.outputFollowsDefault) {
         d.output = PrefAction::Save;
         d.outputValue = kAudioSystemOutput;
+        d.notice = AudioNotice::FollowingSystemDefault;
+        d.noticeDevice = outcome.actualOutput;
     } else if (!outcome.actualOutput.empty()) {
         d.output = PrefAction::Save;
         d.outputValue = outcome.actualOutput;
@@ -196,6 +211,14 @@ inline AudioPrefsDecision audioPrefsDecision(const AudioSwitchRequest& request,
     return d;
 }
 
+// The engine's own state change that means it lost the device it was on and
+// fell back by itself (no request from the GUI, so audioPrefsDecision never
+// sees it): the device-list push that follows names where the sound went.
+inline bool audioStateLostDevice(const std::string& state, const std::string& reason)
+{
+    return state == "running" && reason == "swap-failed-rollback";
+}
+
 // ── 3. Booting with saved prefs ──────────────────────────────────────────────
 
 // Saved audio prefs are handed to the engine's first open. A pref that names