Render the window where there is no screen to show it on

takt4 is worked on from sessions that have a window station but no display, and
§5.9's window could not be looked at from one. Measured, both ways: a screen DC
does not exist at all — CreateDC("DISPLAY", …) returns null and BitBlt from
GetDC(NULL) fails — and PrintWindow with PW_RENDERFULLCONTENT hands back the
frame with a white client area, on the Skia/OpenGL renderer and under
SLINT_BACKEND=winit-skia-software alike. So the window built, launched, sized
itself correctly and closed cleanly, and nobody could say whether it looked
right.

takt4-shot does not need a screen. A slint::platform::Platform of our own hands
the runtime a window adapter whose SoftwareRenderer draws into a buffer we own,
and that goes out as a BMP. It is the real component — real layout, real fonts,
real colours — not a mock-up of it. The readouts are filled by running the
tracker over tests/data/features/synthetic.wav, so the picture holds numbers the
engine actually produced and can be checked against what `takt4-cli track` prints
for the same file: 127.66 BPM, locked, 4/4. The pickers are filled from whatever
audio hardware is present.

Looking at the first render found four things immediately, all fixed here:

  * A y binding on a child of a layout is silently ignored — the layout owns its
    children's positions. "BPM" floated above the number instead of sitting on
    its baseline; vertical-alignment is what that wanted. The bar dots carried
    the same dead binding.

  * A VerticalLayout's default alignment spreads leftover height *between*
    children that cannot stretch, so the tempo readouts were pushed forty pixels
    apart with the meter left stranded halfway down the window.

  * "folded from N BPM" tested the difference between the raw and published
    tempo, so it fired on the beat-spacing refinement — 126.8 against 127.66 —
    and called it an octave fold. A fold is a halving or a doubling, so the test
    is the ratio.

  * The activation trace was pinned at 88 px while the readouts took every spare
    pixel. That is backwards: the trace is the one thing here worth more when it
    is bigger, and §5.9 says it is what carries this UI.

ui/window_state.cpp comes out of app.cpp so there is one place that knows how an
engine value becomes a window property, and both the live window and takt4-shot
use it. That is what lets the shot tool fill the window with no tracker, no timer
and no audio device behind it.

158 tests, unchanged: this adds no engine code. Builds clean with the UI on and
with it off.

Author: Fohdeesha

src/CMakeLists.txt

@@ -22,11 +22,19 @@ if(TAKT4_BUILD_UI)
   target_link_libraries(takt4 PRIVATE takt4::ui takt4::core takt4::warnings)
   takt4_enable_rt_guard(takt4 DEBUG_ONLY)
 
+  # takt4-shot: renders the window to an image with no display involved (src/ui/shot.cpp).
+  # A bench tool like takt4-cli, never packaged.
+  add_executable(takt4-shot shot_main.cpp)
+  target_link_libraries(takt4-shot PRIVATE takt4::ui takt4::core takt4::warnings)
+
   # The same weight set and state space the console reads, from the same place in the
   # source tree, for the same reason: there is no installer yet. Phase 7 replaces this
   # with paths resolved next to the executable — see HANDOFF §8 Phase 7.
+  # TAKT4_TEST_DATA_DIR is takt4-shot's: it fills the readouts by running the tracker over
+  # the committed synthetic excerpt, so the picture holds numbers the engine really made.
   target_compile_definitions(takt4_ui PRIVATE
     "TAKT4_WEIGHTS_DIR=\"${PROJECT_SOURCE_DIR}/assets/weights\""
     "TAKT4_STATESPACE_DIR=\"${PROJECT_SOURCE_DIR}/assets/statespace\""
+    "TAKT4_TEST_DATA_DIR=\"${PROJECT_SOURCE_DIR}/tests/data\""
   )
 endif()

src/shot_main.cpp

@@ -0,0 +1,83 @@
+// takt4-shot — render the main window to an image without a display. See src/ui/shot.cpp
+// for why this exists. A bench tool, like takt4-cli; never packaged.
+
+#include "core/build_info.hpp"
+#include "ui/app.hpp"
+
+#include <exception>
+#include <filesystem>
+#include <iostream>
+#include <string>
+#include <string_view>
+
+namespace {
+
+void printUsage(std::ostream& out) {
+    out << "takt4-shot " << takt4::buildInfo().version
+        << " — render the main window to a BMP\n"
+           "\n"
+           "  takt4-shot OUT.bmp [--size WxH]\n"
+           "\n"
+           "  --size WxH      the window size to render, default 900x520\n"
+           "\n"
+           "Draws the real component with Slint's software renderer, so it needs no\n"
+           "display: the readouts are filled by running the tracker over\n"
+           "tests/data/features/synthetic.wav, which `takt4-cli track` prints as\n"
+           "\"499 frames, 21 beats (5 downbeats), ending at 127.7 BPM in 4/4, locked\".\n";
+}
+
+} // namespace
+
+int main(int argc, char** argv) {
+    std::filesystem::path out;
+    int width = 900;
+    int height = 520;
+
+    for (int i = 1; i < argc; ++i) {
+        const std::string_view arg = argv[i];
+        if (arg == "--help" || arg == "-h") {
+            printUsage(std::cout);
+            return 0;
+        }
+        if (arg == "--size") {
+            if (i + 1 >= argc) {
+                std::cerr << "takt4-shot: --size needs WxH\n";
+                return 2;
+            }
+            const std::string value = argv[++i];
+            const std::size_t cross = value.find('x');
+            if (cross == std::string::npos) {
+                std::cerr << "takt4-shot: --size expects WxH, got " << value << '\n';
+                return 2;
+            }
+            try {
+                width = std::stoi(value.substr(0, cross));
+                height = std::stoi(value.substr(cross + 1));
+            } catch (const std::exception&) {
+                std::cerr << "takt4-shot: --size expects two numbers, got " << value << '\n';
+                return 2;
+            }
+        } else if (arg.starts_with("-")) {
+            std::cerr << "takt4-shot: unknown option '" << arg << "'\n";
+            printUsage(std::cerr);
+            return 2;
+        } else if (out.empty()) {
+            out = std::filesystem::path(arg);
+        } else {
+            std::cerr << "takt4-shot: one output file, not two\n";
+            return 2;
+        }
+    }
+
+    if (out.empty()) {
+        printUsage(std::cerr);
+        return 2;
+    }
+
+    try {
+        return takt4::ui::renderShot(out, width, height);
+    } catch (const std::exception& e) {
+        std::cerr << "takt4-shot: " << e.what() << '\n';
+        return 1;
+    }
+}

src/ui/CMakeLists.txt

@@ -26,6 +26,9 @@ target_link_libraries(takt4_ui_slint PUBLIC Slint::Slint)
 add_library(takt4_ui STATIC
   app.cpp
   app.hpp
+  shot.cpp
+  window_state.cpp
+  window_state.hpp
 )
 add_library(takt4::ui ALIAS takt4_ui)
 

src/ui/app.cpp

@@ -10,6 +10,7 @@
 #include "core/engine/beat_engine.hpp"
 #include "core/engine/live_tracker.hpp"
 #include "core/tracking/tempo_tracker.hpp"
+#include "ui/window_state.hpp"
 
 #include "main_window.h" // generated from main_window.slint
 
@@ -18,10 +19,8 @@
 #include <cstddef>
 #include <exception>
 #include <filesystem>
-#include <iomanip>
 #include <iostream>
 #include <memory>
-#include <sstream>
 #include <string>
 #include <tuple>
 #include <vector>
@@ -31,20 +30,13 @@ namespace {
 
 using namespace std::chrono_literals;
 
-/// Frames of activation the trace holds: four seconds at the 50 Hz frame rate, which is
-/// two bars at 120 BPM — long enough to see the pattern the network is responding to.
-constexpr std::size_t kTraceLength = 200;
-
 /// How often the window drains the engine's rings and redraws. HANDOFF §7.5: "Push
 /// audio-side results through a lock-free ring and drain on a UI timer — do not queue one
 /// closure per audio callback." 30 Hz is slower than the 50 Hz the frames arrive at, so
 /// every tick finds one or two waiting and none is ever missed; the ring holds ten
 /// seconds of them, so even a stalled event loop loses nothing.
 constexpr auto kRedrawInterval = 33ms;
 
-/// The bottom of the input meter. Quieter than this is not a level anyone is setting.
-constexpr float kMeterFloorDb = -60.0f;
-
 /// How far the peak indicator falls back each tick — slow enough that a moment of
 /// clipping is still on screen when the operator looks up.
 constexpr float kPeakDecay = 0.88f;
@@ -57,39 +49,10 @@ std::filesystem::path stateSpacePath() {
     return std::filesystem::path(TAKT4_STATESPACE_DIR) / "default.bin";
 }
 
-std::string fixed(double value, int places) {
-    std::ostringstream out;
-    out << std::fixed << std::setprecision(places) << value;
-    return out.str();
-}
-
 slint::SharedString shared(const std::string& text) {
     return slint::SharedString(text);
 }
 
-/// What the device picker shows. The host API leads, because on Windows one interface
-/// appears under both ASIO and WASAPI and the two are not interchangeable (§5.1): only
-/// the ASIO entry picks channels natively, and only the WASAPI one offers loopback.
-std::string describeDevice(const audio::InputDevice& device) {
-    std::string text = device.hostApiName + " / " + device.name + "  (" +
-                       std::to_string(device.maxInputChannels) + " in";
-    if (device.isLoopback) {
-        text += ", loopback";
-    }
-    return text + ")";
-}
-
-/// What the channel picker shows, numbered from 1 as it is printed on the interface.
-/// ASIO and CoreAudio hand over the driver's own names for them; nothing else does.
-std::string describeChannel(const audio::InputDevice& device, int channel) {
-    const std::string number = std::to_string(channel + 1);
-    const auto index = static_cast<std::size_t>(channel);
-    if (index < device.channelNames.size() && !device.channelNames[index].empty()) {
-        return "In " + number + " — " + device.channelNames[index];
-    }
-    return "In " + number;
-}
-
 /// Everything the window needs that is not the window: the tracker behind it, the model
 /// behind its trace, and the one timer that drains the engine's rings.
 ///
@@ -206,22 +169,9 @@ class WindowController {
         publishOpenStream();
     }
 
-    /// Everything the readouts say while nothing is running, so a stopped window does not
-    /// leave the last set's tempo sitting there looking live.
     void publishStopped() {
         window_->set_running(false);
-        window_->set_bpm(0.0f);
-        window_->set_raw_bpm(0.0f);
-        window_->set_locked(false);
-        window_->set_holding(false);
-        window_->set_refined(false);
-        window_->set_confidence(0.0f);
-        window_->set_beats_per_bar(0);
-        window_->set_beat_in_bar(0);
-        window_->set_bars(0);
-        window_->set_input_level(0.0f);
-        window_->set_input_peak(0.0f);
-        window_->set_input_reading(shared(""));
+        publishIdleReadouts(*window_);
         publishOptions();
         if (!devices_.empty() && !statusIsError_) {
             setStatus("takt4 " + buildInfo().version + " — pick an input and press Start.", false);
@@ -251,12 +201,7 @@ class WindowController {
     /// §5.5's settings as the tracker actually holds them. Read from the engine every
     /// time and never from a copy: a tap moves the fold window underneath anyone keeping
     /// one (§7 deviation 8), and this window exists to show that window honestly.
-    void publishOptions() {
-        const tracking::TempoTracker::Options options = tracker_.engine().tempoOptions();
-        window_->set_fold_on(options.octaveFold);
-        window_->set_fold_min(static_cast<float>(options.minBpm));
-        window_->set_fold_max(static_cast<float>(options.maxBpm));
-    }
+    void publishOptions() { publishTempoOptions(*window_, tracker_.engine().tempoOptions()); }
 
     void setStatus(const std::string& text, bool error) {
         statusIsError_ = error;
@@ -273,12 +218,8 @@ class WindowController {
         bool moved = false;
         engine::EngineFrame frame;
         while (tracker_.engine().popFrame(frame)) {
-            TracePoint point;
-            point.beat = frame.activation.beat;
-            point.downbeat = frame.activation.downbeat;
-            point.called = frame.beat;
             std::rotate(trace_.begin(), trace_.begin() + 1, trace_.end());
-            trace_.back() = point;
+            trace_.back() = tracePoint(frame);
             moved = true;
         }
         if (moved) {
@@ -305,16 +246,7 @@ class WindowController {
     }
 
     void publishState() {
-        const tracking::TempoState state = tracker_.engine().state();
-        window_->set_bpm(static_cast<float>(state.bpm));
-        window_->set_raw_bpm(static_cast<float>(state.rawBpm));
-        window_->set_locked(state.locked);
-        window_->set_holding(state.holding);
-        window_->set_refined(state.refined);
-        window_->set_confidence(static_cast<float>(state.confidence));
-        window_->set_beats_per_bar(static_cast<int>(state.beatsPerBar));
-        window_->set_beat_in_bar(static_cast<int>(state.beatInBar));
-        window_->set_bars(static_cast<int>(state.bars));
+        publishTempoState(*window_, tracker_.engine().state());
         publishOptions();
     }
 
@@ -327,14 +259,13 @@ class WindowController {
             peak = std::max(peak, level.peak);
         }
         peak_ = std::max(peak, peak_ * kPeakDecay);
-        window_->set_input_peak(peak_);
         if (loudest < 0.0f) {
-            return; // leave the reading where it was rather than flashing to silence
+            // Nothing arrived this tick: let the peak fall, leave the reading where it
+            // was rather than flashing to silence.
+            window_->set_input_peak(peak_);
+            return;
         }
-        const float db = audio::toDbfs(loudest);
-        window_->set_input_level(std::clamp((db - kMeterFloorDb) / -kMeterFloorDb, 0.0f, 1.0f));
-        window_->set_input_reading(
-            shared(db <= kMeterFloorDb ? "-inf dB" : fixed(static_cast<double>(db), 1) + " dB"));
+        publishInput(*window_, loudest, peak_);
     }
 
     engine::LiveTracker& tracker_;

src/ui/app.hpp

@@ -1,9 +1,17 @@
 #pragma once
 
+#include <filesystem>
+
 namespace takt4::ui {
 
 /// Shows the main window and runs the event loop on the calling thread.
 /// Returns when the window is closed.
 int run();
 
+/// Renders the main window to a 24-bit BMP at `out`, with no window system involved.
+///
+/// HANDOFF §5.9's window is worked on from sessions that have no display, where every
+/// screen-capture route fails; this one does not need one. See `shot.cpp`.
+int renderShot(const std::filesystem::path& out, int width, int height);
+
 } // namespace takt4::ui

src/ui/main_window.slint

@@ -185,15 +185,20 @@ export component MainWindow inherits Window {
     }
 
     // --- the readouts ------------------------------------------------------------
+    // The readouts take the height they need; the trace below gets the rest, because
+    // it is the one thing here that is worth more when it is bigger.
     HorizontalLayout {
       padding: 24px;
       spacing: 24px;
-      vertical-stretch: 1;
+      vertical-stretch: 0;
 
-      // tempo, and the bar
+      // tempo, and the bar. Centred rather than stretched: a VerticalLayout's
+      // default alignment spreads the leftover height *between* children that
+      // cannot stretch, which pushed these forty pixels apart.
       VerticalLayout {
         spacing: 4px;
         horizontal-stretch: 1;
+        alignment: center;
 
         HorizontalLayout {
           spacing: 8px;
@@ -211,10 +216,13 @@ export component MainWindow inherits Window {
           }
 
           Text {
+            // Sat on the baseline of the number beside it. A layout owns its
+            // children's y, so this is vertical-alignment and not a y binding —
+            // that one was silently ignored and left the label up in the air.
             text: "BPM";
             color: Theme.dim;
             font-size: 14px;
-            y: parent.height - self.height - 14px;
+            vertical-alignment: bottom;
           }
         }
 
@@ -243,7 +251,6 @@ export component MainWindow inherits Window {
           for beat in root.beats-per-bar : Rectangle {
             width: 16px;
             height: 16px;
-            y: 2px;
             border-radius: 8px;
             border-width: 2px;
             border-color: beat == 0 ? Theme.text : Theme.dim;
@@ -275,7 +282,7 @@ export component MainWindow inherits Window {
       VerticalLayout {
         spacing: 10px;
         horizontal-stretch: 1;
-        alignment: start;
+        alignment: center;
 
         HorizontalLayout {
           spacing: 8px;
@@ -331,9 +338,16 @@ export component MainWindow inherits Window {
         }
 
         Text {
-          // Only worth saying when folding actually moved the number, which is
-          // exactly when an operator would otherwise mistrust the readout.
-          text: (root.fold-on && root.raw-bpm > 0 && abs(root.raw-bpm - root.bpm) > 0.5)
+          // Only when folding actually moved the number, which is exactly when an
+          // operator would otherwise mistrust the readout.
+          //
+          // The test is the *ratio*, not the difference. A fold is a halving or a
+          // doubling, so it leaves the two numbers a factor of two apart; a plain
+          // difference also catches the tenth-of-a-BPM gap between the cloud's
+          // tempo interval and the refined tempo (§6: 5.4 BPM apart at 130), which
+          // is not a fold and must not be announced as one.
+          text: (root.fold-on && root.raw-bpm > 0 && root.bpm > 0
+                 && (root.raw-bpm > root.bpm * 1.5 || root.raw-bpm < root.bpm * 0.67))
             ? "folded from " + round(root.raw-bpm * 10) / 10 + " BPM"
             : "";
           color: Theme.holding;
@@ -350,11 +364,11 @@ export component MainWindow inherits Window {
       padding-right: 24px;
       padding-bottom: 8px;
       spacing: 8px;
-      vertical-stretch: 0;
+      vertical-stretch: 1;
 
       HorizontalLayout {
         spacing: 10px;
-        vertical-stretch: 0;
+        vertical-stretch: 1;
 
         Text {
           text: "activation";
@@ -367,7 +381,7 @@ export component MainWindow inherits Window {
         Rectangle {
           background: Theme.panel;
           border-radius: 3px;
-          height: 88px;
+          min-height: 88px;
           clip: true;
 
           // One column per 50 Hz frame, oldest at the left. One repeater, not two,