Let the outputs be changed without restarting anything

Phase 5's exit criterion is "launch to synced output without documentation, a text
editor, or a restart", so the window will have to switch Link on, point OSC
somewhere and pick a MIDI port while the app is open — and the transports were
built once from a config and never touched again. This makes them settable, and
gives the output thread the same way in that the tracker already has.

**Link is now always built, whether or not it is switched on**, and that is the
load-bearing decision here. `BeatEngine::setHostTimeSource` is handed the session
and the audio thread reads it every hop (§4.3); building it on demand would mean
destroying one under a running audio thread the first time an operator switched
Link off, and no ordering makes that safe. Built once, switched on and off, never
replaced — so `OutputRunner::hostTimeClock()` is stable for the runner's life and
that hazard cannot occur. It costs nothing idle: Link's own header says
construction "does not touch the network; nothing is visible to peers until the
session is enabled", and a publisher with no targets sends to nobody. MIDI is the
exception and stays on demand, because it is a named device rather than a switch.

Switching Link on while stopped says what to do rather than doing it: the session
joins at startOutputs, so ticking a box before Start does not put takt4 in front of
peers before it is tracking anything. Switching it off and on again resends the
tempo on the next beat, because a rejoined session knows nothing and the
"unchanged, do not resend" rule would otherwise leave peers waiting for a change.

`OutputCommand` and `OutputRunner::post` are `engine::Command` and
`BeatEngine::post` again, for the same reason: the transports belong to the output
thread, and a caller must not reach into something another thread is using. Posting
while stopped applies immediately instead — an operator ticking Link with nothing
running should not have to press Start to find out whether it took. The runner owns
the `Transports` now rather than borrowing them, which turns "one thread touches
these" from a comment into something the type system enforces: `transports()` hands
back a const reference, and the mutating members are not on it.

A MIDI port that will not open is the failure that actually happens. `Transports`
builds the new port before tearing the old one down, so a bad name leaves a working
clock exactly where it was; `OutputRunner` catches it and keeps the message in
`lastError()`, because the transports carrying on is precisely what makes the
failure invisible otherwise. A port opened mid-set starts its clock from now rather
than from when the outputs started — `advance` would otherwise try to emit every
tick of the intervening set at once.

`OscPublisher::clearTargets` forgets the published state along with the targets.
Only changed values are sent between beats, so a target typed in mid-set would
otherwise wait for the tempo to move before learning what it is.

Eight more tests: that the Link session is the same object across a switch, that
switching on before start does not join, that replacing OSC targets resends the
state, that a bad MIDI port leaves the transports usable and is reported rather
than swallowed, and that a change posted while running actually travels.

174 tests with the UI off, 190 with it on. `track` over the excerpt still ends
"499 frames, 21 beats (5 downbeats), ending at 127.7 BPM in 4/4, locked", and a
live run with --link and --osc still sends and shuts down clean.

Author: Fohdeesha

src/cli/main.cpp

@@ -1015,7 +1015,7 @@ int runTrackFile(const std::filesystem::path& in, const takt4::model::ModelWeigh
     offline.midiClockPort.reset();
 
     auto engine = std::make_unique<takt4::engine::BeatEngine>(weights, model, engineOptions(args));
-    takt4::output::Transports transports(transportConfig(offline));
+    takt4::output::Transports transports{transportConfig(offline)};
     BeatPrinter printer;
     if (args.beatsOut) {
         printer.writeTo(*args.beatsOut);
@@ -1068,7 +1068,10 @@ int runTrackDevice(const TrackArgs& args, const takt4::model::ModelWeights& weig
     options.sampleRate = args.beats.stream.rate;
     options.forceSoftwareSlice = args.beats.stream.software;
     takt4::audio::InputStream stream(session, device, selection, *engine, options);
-    takt4::output::Transports transports(transportConfig(args));
+    // The runner owns the transports (§4.2): one thread touches them, and that is
+    // structural rather than a comment now.
+    takt4::output::OutputRunner runner(*engine, transportConfig(args));
+    const takt4::output::Transports& transports = runner.transports();
     BeatPrinter printer;
     if (args.beatsOut) {
         printer.writeTo(*args.beatsOut);
@@ -1077,9 +1080,7 @@ int runTrackDevice(const TrackArgs& args, const takt4::model::ModelWeights& weig
     // beat carries the host time of the audio it was found in rather than of the moment
     // this loop happened to notice it. Before the stream is started, because the stamp is
     // taken on the audio thread and there has to be a clock in place before there is one.
-    if (transports.link() != nullptr) {
-        engine->setHostTimeSource(transports.link());
-    }
+    engine->setHostTimeSource(&runner.hostTimeClock());
 
     std::cout << "device:    " << device.hostApiName << " / " << device.name << '\n'
               << "channel:   " << selection.channels[0] + 1;
@@ -1101,13 +1102,11 @@ int runTrackDevice(const TrackArgs& args, const takt4::model::ModelWeights& weig
     if (!args.anyOutput()) {
         std::cout << "none (--link, --osc HOST:PORT, --midi-clock PORT)";
     }
-    if (transports.link() != nullptr) {
+    if (transports.linkEnabled()) {
         std::cout << "Link ";
     }
-    if (transports.osc() != nullptr) {
-        for (std::size_t i = 0; i < transports.osc()->targetCount(); ++i) {
-            std::cout << "OSC " << transports.osc()->target(i).resolved() << " ";
-        }
+    for (std::size_t i = 0; i < transports.osc().targetCount(); ++i) {
+        std::cout << "OSC " << transports.osc().target(i).resolved() << " ";
     }
     if (transports.midiPort() != nullptr) {
         std::cout << "MIDI clock to \"" << transports.midiPort()->portName() << "\"";
@@ -1165,7 +1164,7 @@ int runTrackDevice(const TrackArgs& args, const takt4::model::ModelWeights& weig
             takt4::tracking::TempoTracker::Options live = engine->tempoOptions();
             live.latencyOffsetSeconds += key == '[' ? -0.005 : 0.005;
             (void)engine->post(Command::setTempoOptions(live));
-            transports.setLatencySeconds(live.latencyOffsetSeconds);
+            runner.setLatencySeconds(live.latencyOffsetSeconds);
             std::cout << "  latency offset " << fixed1(live.latencyOffsetSeconds * 1000.0)
                       << " ms\n";
             break;
@@ -1201,11 +1200,10 @@ int runTrackDevice(const TrackArgs& args, const takt4::model::ModelWeights& weig
     std::mutex publishedMutex;
     std::vector<takt4::engine::EngineBeat> published;
 
-    // §4.2's output thread. It is the single consumer of the engine's beat ring from here
-    // on, so this loop must not drain it: it polls keys, prints, and drains the *frame*
-    // ring, which nothing else wants. The tracking waits on neither — the inference thread
-    // runs at the audio's pace — and now neither does a MIDI tick.
-    takt4::output::OutputRunner runner(*engine, transports);
+    // §4.2's output thread. It is the single consumer of the engine's beat ring, so this
+    // loop must not drain it: it polls keys, prints, and drains the *frame* ring, which
+    // nothing else wants. The tracking waits on neither — the inference thread runs at the
+    // audio's pace — and now neither does a MIDI tick.
     runner.setBeatObserver([&](const takt4::engine::EngineBeat& beat) {
         const std::lock_guard<std::mutex> lock(publishedMutex);
         published.push_back(beat);
@@ -1272,18 +1270,18 @@ int runTrackDevice(const TrackArgs& args, const takt4::model::ModelWeights& weig
                       ? ", " + std::to_string(engine->framesDropped()) + " frames not drained"
                       : "")
               << '\n';
-    if (transports.osc() != nullptr) {
-        std::cout << "OSC: " << transports.osc()->messagesSent() << " messages sent, "
-                  << transports.osc()->messagesFailed() << " failed\n";
+    if (transports.osc().targetCount() != 0) {
+        std::cout << "OSC: " << transports.osc().messagesSent() << " messages sent, "
+                  << transports.osc().messagesFailed() << " failed\n";
     }
     if (transports.midiClock() != nullptr) {
         std::cout << "MIDI clock: " << transports.midiClock()->ticksSent() << " ticks, "
                   << transports.midiClock()->ticksSkipped() << " skipped\n";
     }
-    if (transports.link() != nullptr) {
-        std::cout << "Link: " << transports.link()->tempoUpdates() << " tempo updates, "
-                  << transports.link()->beatRequests() << " beat requests, "
-                  << transports.link()->numPeers() << " peers at the end\n";
+    if (transports.linkEnabled()) {
+        std::cout << "Link: " << transports.link().tempoUpdates() << " tempo updates, "
+                  << transports.link().beatRequests() << " beat requests, "
+                  << transports.link().numPeers() << " peers at the end\n";
     }
     return 0;
 }

src/core/output/osc_publisher.cpp

@@ -46,6 +46,16 @@ void OscPublisher::addTarget(std::string_view host, std::uint16_t port) {
     targets_.push_back(std::make_unique<OscSender>(host, port));
 }
 
+void OscPublisher::clearTargets() noexcept {
+    targets_.clear();
+    // Back to exactly what a freshly built publisher holds, so a target added after this
+    // is told the same things a target present from the start would have been.
+    lastBpm_ = -1.0;
+    lastConfidence_ = -1.0;
+    lastLocked_ = -1;
+    lastMeter_ = 0;
+}
+
 void OscPublisher::sendInt(std::string_view address, std::int32_t value) {
     OscMessage message(address);
     message.addInt(value);

src/core/output/osc_publisher.hpp

@@ -45,6 +45,14 @@ class OscPublisher {
     /// Adds a target. Throws std::runtime_error if the host cannot be resolved.
     void addTarget(std::string_view host, std::uint16_t port);
 
+    /// Removes every target, and forgets what was last published with them.
+    ///
+    /// The forgetting is the point: only changed values are sent between beats, so a
+    /// target added after this has never been told the tempo and would otherwise wait for
+    /// it to move before learning it. An operator who types an address mid-set expects
+    /// the next message, not the next tempo change.
+    void clearTargets() noexcept;
+
     std::size_t targetCount() const noexcept { return targets_.size(); }
     const OscSender& target(std::size_t index) const noexcept { return *targets_[index]; }
 

src/core/output/output_runner.cpp

@@ -1,5 +1,8 @@
 #include "core/output/output_runner.hpp"
 
+#include <exception>
+#include <utility>
+
 #if defined(_WIN32)
 #include <windows.h>
 // timeapi.h must follow windows.h.
@@ -34,8 +37,8 @@ void restoreTimerResolution(bool raised) noexcept {
 
 } // namespace
 
-OutputRunner::OutputRunner(engine::BeatEngine& engine, Transports& transports)
-    : engine_(engine), transports_(transports) {}
+OutputRunner::OutputRunner(engine::BeatEngine& engine, const Transports::Config& config)
+    : engine_(engine), transports_(config) {}
 
 OutputRunner::~OutputRunner() {
     stop();
@@ -69,6 +72,10 @@ void OutputRunner::stop() noexcept {
     running_.store(false, std::memory_order_release);
     worker_.join();
 
+    // Anything posted in the moments before the stop still meant something, and the
+    // transports are this thread's now.
+    applyCommands();
+
     // The last beats of a set are still beats: the engine may have called one between the
     // final round and the join. Safe on this thread now — the only other consumer of that
     // ring has been joined.
@@ -84,8 +91,63 @@ void OutputRunner::stop() noexcept {
     raisedTimer_ = false;
 }
 
+void OutputRunner::post(OutputCommand command) {
+    if (!running()) {
+        // Nothing else is touching the transports, so there is no reason to make an
+        // operator press Start before a setting takes: this is how an app is configured
+        // before it is running at all.
+        apply(command);
+        return;
+    }
+    const std::lock_guard<std::mutex> lock(commandMutex_);
+    pending_.push_back(std::move(command));
+}
+
+std::string OutputRunner::lastError() const {
+    const std::lock_guard<std::mutex> lock(errorMutex_);
+    return lastError_;
+}
+
+void OutputRunner::apply(const OutputCommand& command) {
+    try {
+        switch (command.kind) {
+        case OutputCommand::Kind::LinkEnabled:
+            transports_.setLinkEnabled(command.enabled);
+            break;
+        case OutputCommand::Kind::OscTargets:
+            transports_.setOscTargets(command.targets);
+            break;
+        case OutputCommand::Kind::MidiClockPort:
+            transports_.setMidiClockPort(command.port);
+            break;
+        }
+        const std::lock_guard<std::mutex> lock(errorMutex_);
+        lastError_.clear();
+    } catch (const std::exception& e) {
+        // A MIDI port that is not there. Transports leaves what was working alone, so the
+        // failure is only that the change did not happen — which somebody has to be told.
+        const std::lock_guard<std::mutex> lock(errorMutex_);
+        lastError_ = e.what();
+    }
+}
+
+void OutputRunner::applyCommands() noexcept {
+    {
+        const std::lock_guard<std::mutex> lock(commandMutex_);
+        if (pending_.empty()) {
+            return;
+        }
+        applying_.swap(pending_);
+    }
+    for (const OutputCommand& command : applying_) {
+        apply(command);
+    }
+    applying_.clear();
+}
+
 void OutputRunner::run() noexcept {
     while (running_.load(std::memory_order_acquire)) {
+        applyCommands();
         try {
             drainOnce(elapsed());
         } catch (...) {

src/core/output/output_runner.hpp

@@ -1,16 +1,55 @@
 #pragma once
 
+#include "core/audio/host_time.hpp"
 #include "core/engine/beat_engine.hpp"
 #include "core/output/transports.hpp"
 
 #include <atomic>
 #include <chrono>
 #include <cstdint>
 #include <functional>
+#include <mutex>
+#include <optional>
+#include <string>
 #include <thread>
+#include <vector>
 
 namespace takt4::output {
 
+/// A change to what the transports are sending.
+///
+/// Posted by whoever owns the controls — a window, §5.7's inbound OSC later — and applied
+/// by the output thread between rounds, because the transports belong to it. Exactly the
+/// shape `engine::Command` has for the tracker, and for the same reason: many producers,
+/// one consumer, and no caller reaching into something another thread is using.
+struct OutputCommand {
+    enum class Kind : std::uint8_t { LinkEnabled, OscTargets, MidiClockPort };
+
+    static OutputCommand linkEnabled(bool on) {
+        OutputCommand command;
+        command.kind = Kind::LinkEnabled;
+        command.enabled = on;
+        return command;
+    }
+    static OutputCommand oscTargets(std::vector<Transports::OscTarget> targets) {
+        OutputCommand command;
+        command.kind = Kind::OscTargets;
+        command.targets = std::move(targets);
+        return command;
+    }
+    static OutputCommand midiClockPort(std::optional<std::string> port) {
+        OutputCommand command;
+        command.kind = Kind::MidiClockPort;
+        command.port = std::move(port);
+        return command;
+    }
+
+    Kind kind = Kind::LinkEnabled;
+    bool enabled = false;
+    std::vector<Transports::OscTarget> targets;
+    std::optional<std::string> port;
+};
+
 /// HANDOFF §4.2's output thread.
 ///
 /// §4.2 wants the transports off the audio thread *and* off the caller's loop, so that
@@ -30,9 +69,9 @@ namespace takt4::output {
 ///
 /// The caller still owns two things that have to happen around it:
 ///
-///   * `engine.setHostTimeSource(transports.link())` **before the engine is started**,
-///     because §4.3's stamp is taken on the audio thread and there has to be a clock in
-///     place before there is one.
+///   * `engine.setHostTimeSource(&runner.hostTimeClock())` **before the audio stream is
+///     opened**, because §4.3's stamp is taken on the audio thread and there has to be a
+///     clock in place before there is one.
 ///   * Draining `popFrame`, if anything wants the frames. Nobody has to, but a ring that
 ///     nobody drains fills and the engine starts counting frames lost.
 class OutputRunner {
@@ -46,8 +85,13 @@ class OutputRunner {
     /// loop has to come round well inside that or the ticks inherit its period as jitter.
     static constexpr std::chrono::milliseconds kPeriod{1};
 
-    /// Both must outlive this. Nothing is sent until `start()`.
-    OutputRunner(engine::BeatEngine& engine, Transports& transports);
+    /// The engine must outlive this. The transports are built here and owned here, which
+    /// is what makes "one thread touches them" structural rather than a comment: nothing
+    /// else can reach a mutating member of them. Changes go through `post`.
+    ///
+    /// Throws whatever `Transports` throws — a MIDI port that is not on the machine.
+    /// Nothing is sent until `start()`.
+    OutputRunner(engine::BeatEngine& engine, const Transports::Config& config);
     ~OutputRunner();
 
     OutputRunner(const OutputRunner&) = delete;
@@ -78,15 +122,53 @@ class OutputRunner {
     /// Seconds since `start()`, on the steady clock the transports are driven from.
     double elapsed() const noexcept;
 
+    /// The transports, for reading. Their counters are atomic and Link's own state is
+    /// safe to query, so a UI may call this while the thread is sending; the members that
+    /// change what is sent are not reachable through it, and that is deliberate.
+    const Transports& transports() const noexcept { return transports_; }
+
+    /// Link's clock, for `engine::BeatEngine::setHostTimeSource`.
+    ///
+    /// §4.3's stamp is taken on the audio thread, so this has to be installed before the
+    /// stream is opened. It is stable for this runner's life — the session is built once
+    /// and switched on and off, never replaced — which is exactly why switching Link off
+    /// mid-set cannot leave the audio thread holding a destroyed clock.
+    audio::HostTimeSource& hostTimeClock() noexcept { return transports_.link(); }
+
+    /// §5.5's latency offset. Any thread: it writes one atomic.
+    void setLatencySeconds(double seconds) noexcept { transports_.setLatencySeconds(seconds); }
+
+    /// Asks for a change to what is being sent. Any thread; applied by the output thread
+    /// before its next round, so it has happened within a millisecond. Applied
+    /// immediately on the calling thread when the runner is not running, which is what
+    /// lets an app be configured before it is started.
+    void post(OutputCommand command);
+
+    /// What went wrong applying the last posted change, or empty. A MIDI port that is not
+    /// on the machine is the one that happens; an operator has to be told rather than
+    /// left wondering why nothing ticks.
+    std::string lastError() const;
+
 private:
     void run() noexcept;
     /// One round: every beat waiting, then the clock. On the output thread, or on the
     /// caller's in `stop()` once the thread has been joined — never on both at once.
     void drainOnce(double now);
+    /// Everything posted since the last round, in order. On whichever thread owns the
+    /// transports at the time.
+    void applyCommands() noexcept;
+    void apply(const OutputCommand& command);
 
     engine::BeatEngine& engine_;
-    Transports& transports_;
+    Transports transports_;
     BeatObserver observer_;
+
+    mutable std::mutex commandMutex_;
+    std::vector<OutputCommand> pending_;
+    /// Drained into, and reused, so applying commands allocates nothing after the first.
+    std::vector<OutputCommand> applying_;
+    mutable std::mutex errorMutex_;
+    std::string lastError_;
     std::thread worker_;
     std::atomic<bool> running_{false};
     std::atomic<std::uint64_t> rounds_{0};