v0 of flluidsynth auto detection and guide to install

MANIFEST.in

@@ -0,0 +1 @@
+recursive-include ressources *.md

Theremini/dashboard.py

@@ -30,6 +30,13 @@ _status: Dict[str, Any] = {
     "updated_at": time.time(),
 }
 
+_health_lock = threading.Lock()
+_health: Dict[str, Any] = {
+    "fluidsynth_ok": True,
+    "fluidsynth_error": None,
+    "fluidsynth_guide_html": "",
+}
+
 
 def set_status(payload: Dict[str, Any]) -> None:
     payload = dict(payload)
@@ -43,6 +50,16 @@ def get_status() -> Dict[str, Any]:
         return dict(_status)
 
 
+def set_health(payload: Dict[str, Any]) -> None:
+    with _health_lock:
+        _health.update(dict(payload))
+
+
+def get_health() -> Dict[str, Any]:
+    with _health_lock:
+        return dict(_health)
+
+
 class DashboardHandler(http.server.SimpleHTTPRequestHandler):
     directory = str(Path(__file__).resolve().parent / "webui")
 
@@ -73,7 +90,7 @@ class DashboardHandler(http.server.SimpleHTTPRequestHandler):
 
     def do_GET(self):
         if self.path == "/api/status":
-            self._send_json({"ok": True, "status": get_status()})
+            self._send_json({"ok": True, "status": get_status(), "health": get_health()})
             return
         if self.path == "/api/config":
             self._send_json(
@@ -175,4 +192,4 @@ class DashboardServer:
         self._ready.set()
 
 
-__all__ = ["DashboardServer", "DASHBOARD_PORT", "set_status", "get_status"]
+__all__ = ["DashboardServer", "DASHBOARD_PORT", "set_status", "get_status", "set_health", "get_health"]

Theremini/fluidsynth_check.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import functools
+import html
+from dataclasses import dataclass
+from pathlib import Path
+
+try:
+    from markdown import markdown as _markdown
+except Exception:  # pragma: no cover - optional dependency guard
+    _markdown = None
+
+GUIDE_PATH = Path(__file__).resolve().parent.parent / "ressources" / "fluidsynth_guide.md"
+
+
+@dataclass(frozen=True)
+class FluidSynthProbeResult:
+    ok: bool
+    error: str | None = None
+
+
+def _render_markdown_fallback(text: str) -> str:
+    escaped = html.escape(text)
+    return f"<pre>{escaped}</pre>"
+
+
+@functools.lru_cache(maxsize=1)
+def get_fluidsynth_guide_html() -> str:
+    try:
+        markdown_text = GUIDE_PATH.read_text(encoding="utf-8")
+    except OSError as exc:  # pragma: no cover - IO failure fallback
+        return _render_markdown_fallback(f"Unable to load guide: {exc}")
+
+    if _markdown is None:
+        return _render_markdown_fallback(markdown_text)
+
+    return _markdown(markdown_text, extensions=["fenced_code", "tables"])
+
+
+def probe_fluidsynth() -> FluidSynthProbeResult:
+    """Try to exercise pyFluidSynth so we catch missing system libs early."""
+    try:
+        import fluidsynth  # type: ignore
+    except Exception as exc:
+        return FluidSynthProbeResult(False, f"pyFluidSynth import failed: {exc}")
+
+    try:
+        synth = fluidsynth.Synth()
+    except Exception as exc:
+        return FluidSynthProbeResult(False, f"Unable to initialise FluidSynth: {exc}")
+
+    try:
+        # Trigger a couple of commands so we actually call into the shared library.
+        synth.noteon(0, 60, 30)
+        synth.noteoff(0, 60)
+    except Exception as exc:
+        synth.delete()
+        return FluidSynthProbeResult(False, f"FluidSynth test note failed: {exc}")
+
+    try:
+        synth.delete()
+    except Exception:
+        pass
+    return FluidSynthProbeResult(True, None)
+
+
+__all__ = ["probe_fluidsynth", "get_fluidsynth_guide_html", "FluidSynthProbeResult"]

Theremini/main.py

@@ -6,15 +6,22 @@ import io
 import math
 import threading
 import time
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from reachy_mini import ReachyMini, ReachyMiniApp
 from reachy_mini.utils import create_head_pose
-from scamp import Session
 from scipy.spatial.transform import Rotation as R
 
 from Theremini.config import get_active_instruments
-from Theremini.dashboard import DASHBOARD_PORT, DashboardServer, set_status
+from Theremini.dashboard import DASHBOARD_PORT, DashboardServer, set_health, set_status
+from Theremini.fluidsynth_check import (
+    FluidSynthProbeResult,
+    get_fluidsynth_guide_html,
+    probe_fluidsynth,
+)
+
+if TYPE_CHECKING:
+    from scamp import Session
 
 # ────────────────── mapping constants ───────────────────────────────
 ROLL_DEG_RANGE = (-60, 60)  # head roll span
@@ -54,10 +61,10 @@ class Theremini(ReachyMiniApp):
 
     def __init__(self, debug_mode: bool = False) -> None:
         super().__init__()
-        self._session = Session(max_threads=1024)
+        self._session: Session | None = None
         self._parts_cache: dict[str, Any] = {}
         self._active_parts = get_active_instruments()
-        self._theremin = self._get_part_for_prog(0)
+        self._theremin: Any | None = None
         self._note_handle: Any | None = None
         self._current_pitch: int | None = None
         self._current_prog: int | None = None
@@ -68,7 +75,37 @@ class Theremini(ReachyMiniApp):
         self._debug_last_motion_command: float | None = None
         self._debug_last_motion_log: float | None = None
 
+        self._fluidsynth_probe = probe_fluidsynth()
+        if self._fluidsynth_probe.ok:
+            try:
+                from scamp import Session as ScampSession
+            except Exception as exc:
+                self._fluidsynth_probe = FluidSynthProbeResult(False, f"SCAMP import failed: {exc}")
+            else:
+                self._session = ScampSession(max_threads=1024)
+                if self._active_parts:
+                    self._theremin = self._get_part_for_prog(0)
+
+        if self._fluidsynth_probe.ok:
+            set_health(
+                {
+                    "fluidsynth_ok": True,
+                    "fluidsynth_error": None,
+                    "fluidsynth_guide_html": "",
+                }
+            )
+        else:
+            set_health(
+                {
+                    "fluidsynth_ok": False,
+                    "fluidsynth_error": self._fluidsynth_probe.error,
+                    "fluidsynth_guide_html": get_fluidsynth_guide_html(),
+                }
+            )
+
     def _get_part_for_prog(self, prog: int):
+        if self._session is None:
+            raise RuntimeError("FluidSynth is unavailable.")
         name = self._active_parts[prog]
         if name not in self._parts_cache:
             buf = io.StringIO()
@@ -95,6 +132,12 @@ class Theremini(ReachyMiniApp):
             )
         set_status(self._build_status_payload(0.0, 0.0, 0.0, 0.0, None, None, False))
 
+        if not self._fluidsynth_probe.ok:
+            self._wait_for_fluidsynth_install(stop_event)
+            dashboard_server.stop()
+            print("\nTheremin stopped.")
+            return
+
         reachy_mini.enable_motors()
         try:
             self._perform_intro_demo(reachy_mini, stop_event)
@@ -111,6 +154,16 @@ class Theremini(ReachyMiniApp):
             dashboard_server.stop()
             print("\nTheremin stopped.")
 
+    def _wait_for_fluidsynth_install(self, stop_event: threading.Event) -> None:
+        message = self._fluidsynth_probe.error or "FluidSynth runtime check failed."
+        print(
+            "\nFluidSynth is required but could not be initialised.\n"
+            f"Details: {message}\n"
+            "Open the Theremini dashboard for installation instructions."
+        )
+        while not stop_event.is_set():
+            time.sleep(0.5)
+
     def _build_status_payload(
         self,
         roll_deg: float,
@@ -173,6 +226,8 @@ class Theremini(ReachyMiniApp):
                 self._theremin = self._get_part_for_prog(0)
 
     def _handle_sound_state(self, target_pitch: int, amp: float, prog: int) -> None:
+        if self._theremin is None:
+            return
         if prog != self._current_prog:
             self._stop_note()
             self._theremin = self._get_part_for_prog(prog)
@@ -400,6 +455,12 @@ class Theremini(ReachyMiniApp):
             )
         set_status(self._build_status_payload(0.0, 0.0, 0.0, 0.0, None, None, False))
 
+        if not self._fluidsynth_probe.ok:
+            self._wait_for_fluidsynth_install(stop_event)
+            dashboard_server.stop()
+            print("\nDebug Theremin loop stopped.")
+            return
+
         reachy_mini.enable_motors()
         try:
             while not stop_event.is_set():

Theremini/webui/app.js

@@ -11,6 +11,9 @@ const rollValueEl = document.getElementById("rollValue");
 const heightValueEl = document.getElementById("heightValue");
 const antennaValueEl = document.getElementById("antennaValue");
 const playingIndicator = document.getElementById("playingIndicator");
+const guidePanel = document.getElementById("guidePanel");
+const guideContentEl = document.getElementById("guideContent");
+const guideErrorEl = document.getElementById("guideError");
 const availableListEl = document.getElementById("availableList");
 const activeListEl = document.getElementById("activeList");
 const searchInput = document.getElementById("instrumentSearch");
@@ -18,6 +21,7 @@ const configStatusEl = document.getElementById("configStatus");
 const dialSegmentsGroup = document.getElementById("dialSegments");
 const dialPointer = document.getElementById("dialPointer");
 const dialAngleEl = document.getElementById("dialAngle");
+const bodyEl = document.body;
 
 const RIGHT_ANT_RANGE = { min: -Math.PI / 3, max: Math.PI / 3 };
 const DIAL_CENTER = 120;
@@ -103,6 +107,24 @@ function updateStatus(status) {
     updateDial(antenna, programIndex);
 }
 
+function updateHealth(health = {}) {
+    const healthy =
+        health && Object.prototype.hasOwnProperty.call(health, "fluidsynth_ok")
+            ? Boolean(health.fluidsynth_ok)
+            : true;
+    bodyEl.dataset.guide = healthy ? "hidden" : "visible";
+    if (!healthy && guidePanel && guideContentEl && guideErrorEl) {
+        guideErrorEl.textContent = health.fluidsynth_error || "FluidSynth runtime not detected.";
+        const guideHtml = typeof health.fluidsynth_guide_html === "string" ? health.fluidsynth_guide_html.trim() : "";
+        if (guideHtml) {
+            guideContentEl.innerHTML = guideHtml;
+        } else {
+            guideContentEl.innerHTML =
+                "<p class=\"meta\">Unable to load the installation guide. Please check the app logs.</p>";
+        }
+    }
+}
+
 async function pollStatus() {
     try {
         const response = await fetch("/api/status", { cache: "no-store" });
@@ -112,6 +134,7 @@ async function pollStatus() {
         const payload = await response.json();
         if (payload && payload.ok) {
             updateStatus(payload.status ?? {});
+            updateHealth(payload.health ?? {});
         }
     } catch (error) {
         console.error("Theremini dashboard", error);

Theremini/webui/index.html

@@ -8,7 +8,7 @@
     <link rel="stylesheet" href="style.css" />
 </head>
 
-<body>
+<body data-guide="hidden">
     <main class="page">
         <header class="hero">
             <div>
@@ -22,113 +22,126 @@
             </div>
         </header>
 
-        <section class="grid stats">
-            <article class="card">
-                <p class="label">Instrument</p>
-                <h2 id="instrumentName">--</h2>
-                <p class="meta">Program <span id="instrumentIndex">--</span></p>
-            </article>
-            <article class="card">
-                <p class="label">Note</p>
-                <h2 id="noteName">--</h2>
-                <p class="meta">MIDI <span id="noteNumber">--</span></p>
-            </article>
-            <article class="card">
-                <p class="label">Amplitude</p>
-                <h2 id="ampPercent">0%</h2>
-                <div class="meter">
-                    <div class="meter-fill" id="ampMeter"></div>
-                </div>
-            </article>
+        <section class="card guide-card" id="guidePanel">
+            <div class="guide-head">
+                <p class="label">Setup required</p>
+                <h2>Install FluidSynth to unlock Theremini</h2>
+                <p class="meta" id="guideError">FluidSynth runtime not detected.</p>
+            </div>
+            <div class="guide-content" id="guideContent">
+                <p class="meta">Loading troubleshooting guide…</p>
+            </div>
         </section>
 
-        <section class="grid meters">
-            <article class="card span-2">
-                <div class="row">
-                    <div>
-                        <p class="label">Head roll</p>
-                        <h3 id="rollValue">0°</h3>
-                        <p class="meta">maps to MIDI {48 .. 84}</p>
+        <div id="dashboardContent">
+            <section class="grid stats">
+                <article class="card">
+                    <p class="label">Instrument</p>
+                    <h2 id="instrumentName">--</h2>
+                    <p class="meta">Program <span id="instrumentIndex">--</span></p>
+                </article>
+                <article class="card">
+                    <p class="label">Note</p>
+                    <h2 id="noteName">--</h2>
+                    <p class="meta">MIDI <span id="noteNumber">--</span></p>
+                </article>
+                <article class="card">
+                    <p class="label">Amplitude</p>
+                    <h2 id="ampPercent">0%</h2>
+                    <div class="meter">
+                        <div class="meter-fill" id="ampMeter"></div>
                     </div>
-                    <p class="range">-60° ⇢ +60°</p>
-                </div>
-                <div class="meter" data-min="-60" data-max="60" data-unit="°">
-                    <div class="meter-fill" id="rollMeter"></div>
-                </div>
-            </article>
+                </article>
+            </section>
 
-            <article class="card span-2">
-                <div class="row">
-                    <div>
-                        <p class="label">Head Z height</p>
-                        <h3 id="heightValue">0 mm</h3>
-                        <p class="meta">controls amplitude envelope</p>
+            <section class="grid meters">
+                <article class="card span-2">
+                    <div class="row">
+                        <div>
+                            <p class="label">Head roll</p>
+                            <h3 id="rollValue">0°</h3>
+                            <p class="meta">maps to MIDI {48 .. 84}</p>
+                        </div>
+                        <p class="range">-60° ⇢ +60°</p>
                     </div>
-                    <p class="range">-30 mm ⇢ +5 mm</p>
-                </div>
-                <div class="meter" data-min="-30" data-max="5" data-unit=" mm">
-                    <div class="meter-fill" id="heightMeter"></div>
-                </div>
-            </article>
+                    <div class="meter" data-min="-60" data-max="60" data-unit="°">
+                        <div class="meter-fill" id="rollMeter"></div>
+                    </div>
+                </article>
 
-            <article class="card span-2">
-                <div class="row">
-                    <div>
-                        <p class="label">Right antenna</p>
-                        <h3 id="antennaValue">0°</h3>
-                        <p class="meta">selects instrument slot</p>
+                <article class="card span-2">
+                    <div class="row">
+                        <div>
+                            <p class="label">Head Z height</p>
+                            <h3 id="heightValue">0 mm</h3>
+                            <p class="meta">controls amplitude envelope</p>
+                        </div>
+                        <p class="range">-30 mm ⇢ +5 mm</p>
                     </div>
-                    <p class="range">-60° ⇢ +60°</p>
-                </div>
-                <div class="meter" data-min="-1.047" data-max="1.047" data-unit="°">
-                    <div class="meter-fill" id="antennaMeter"></div>
-                </div>
-            </article>
-        </section>
+                    <div class="meter" data-min="-30" data-max="5" data-unit=" mm">
+                        <div class="meter-fill" id="heightMeter"></div>
+                    </div>
+                </article>
 
-        <section class="card program-card">
-            <div class="dial-wrapper">
-                <div class="dial-headings">
-                    <p class="label">Program slots</p>
-                    <h2>FluidSynth voices</h2>
-                    <p class="meta">Move the right antenna to cycle through your curated list.</p>
-                </div>
-                <div class="dial-visual">
-                    <div class="dial-canvas">
-                        <svg id="dialSvg" viewBox="0 0 240 240" role="presentation">
-                            <g id="dialSegments"></g>
-                            <line id="dialPointer" x1="120" y1="120" x2="120" y2="32" />
-                            <circle id="dialCenter" cx="120" cy="120" r="20" />
-                        </svg>
+                <article class="card span-2">
+                    <div class="row">
+                        <div>
+                            <p class="label">Right antenna</p>
+                            <h3 id="antennaValue">0°</h3>
+                            <p class="meta">selects instrument slot</p>
+                        </div>
+                        <p class="range">-60° ⇢ +60°</p>
                     </div>
-                    <p class="meta">Antenna angle: <span id="dialAngle">0°</span></p>
-                </div>
-            </div>
-        </section>
+                    <div class="meter" data-min="-1.047" data-max="1.047" data-unit="°">
+                        <div class="meter-fill" id="antennaMeter"></div>
+                    </div>
+                </article>
+            </section>
 
-        <section class="card config-card">
-            <div class="config-head">
-                <div>
-                    <p class="label">Live instrument set</p>
-                    <h2>Pick the presets Reachy cycles through</h2>
-                    <p class="meta">Choose up to eight voices from the full GM bank. Order matters.</p>
-                </div>
-                <div class="config-actions">
-                    <input id="instrumentSearch" type="text" placeholder="Filter presets..." />
+            <section class="card program-card">
+                <div class="dial-wrapper">
+                    <div class="dial-headings">
+                        <p class="label">Program slots</p>
+                        <h2>FluidSynth voices</h2>
+                        <p class="meta">Move the right antenna to cycle through your curated list.</p>
+                    </div>
+                    <div class="dial-visual">
+                        <div class="dial-canvas">
+                            <svg id="dialSvg" viewBox="0 0 240 240" role="presentation">
+                                <g id="dialSegments"></g>
+                                <line id="dialPointer" x1="120" y1="120" x2="120" y2="32" />
+                                <circle id="dialCenter" cx="120" cy="120" r="20" />
+                            </svg>
+                        </div>
+                        <p class="meta">Antenna angle: <span id="dialAngle">0°</span></p>
+                    </div>
                 </div>
-            </div>
-            <div class="list-grid">
-                <div class="list-panel">
-                    <p class="panel-title">Available voices</p>
-                    <div class="list-box" id="availableList"></div>
+            </section>
+
+            <section class="card config-card">
+                <div class="config-head">
+                    <div>
+                        <p class="label">Live instrument set</p>
+                        <h2>Pick the presets Reachy cycles through</h2>
+                        <p class="meta">Choose up to eight voices from the full GM bank. Order matters.</p>
+                    </div>
+                    <div class="config-actions">
+                        <input id="instrumentSearch" type="text" placeholder="Filter presets..." />
+                    </div>
                 </div>
-                <div class="list-panel">
-                    <p class="panel-title">Active rotation</p>
-                    <div class="list-box active" id="activeList"></div>
+                <div class="list-grid">
+                    <div class="list-panel">
+                        <p class="panel-title">Available voices</p>
+                        <div class="list-box" id="availableList"></div>
+                    </div>
+                    <div class="list-panel">
+                        <p class="panel-title">Active rotation</p>
+                        <div class="list-box active" id="activeList"></div>
+                    </div>
                 </div>
-            </div>
-            <p class="meta" id="configStatus">&nbsp;</p>
-        </section>
+                <p class="meta" id="configStatus">&nbsp;</p>
+            </section>
+        </div>
     </main>
 
     <script src="app.js" type="module"></script>

Theremini/webui/style.css

@@ -24,6 +24,14 @@ body {
     color: var(--text);
 }
 
+body[data-guide="visible"] #dashboardContent {
+    display: none;
+}
+
+body[data-guide="hidden"] #guidePanel {
+    display: none;
+}
+
 .page {
     max-width: 1000px;
     margin: 0 auto;
@@ -114,6 +122,63 @@ body {
     box-shadow: 0 25px 50px rgba(2, 6, 23, 0.6);
 }
 
+.guide-card {
+    display: flex;
+    flex-direction: column;
+    gap: 1rem;
+    border: 1px solid rgba(251, 113, 133, 0.45);
+    background: rgba(127, 29, 29, 0.25);
+}
+
+.guide-head h2 {
+    margin: 0.2rem 0 0;
+}
+
+.guide-head .meta {
+    color: rgba(248, 113, 113, 0.95);
+}
+
+.guide-content {
+    display: flex;
+    flex-direction: column;
+    gap: 0.75rem;
+    line-height: 1.5;
+}
+
+.guide-content h2,
+.guide-content h3 {
+    margin: 1rem 0 0.2rem;
+}
+
+.guide-content hr {
+    border: none;
+    height: 1px;
+    background: rgba(248, 250, 252, 0.25);
+    margin: 1rem 0;
+}
+
+.guide-content pre {
+    padding: 0.75rem 1rem;
+    border-radius: 12px;
+    background: rgba(15, 23, 42, 0.85);
+    border: 1px solid rgba(148, 163, 184, 0.35);
+    overflow-x: auto;
+}
+
+.guide-content a {
+    color: #38bdf8;
+}
+
+.guide-content ul,
+.guide-content ol {
+    padding-left: 1.5rem;
+    margin: 0.2rem 0 0.6rem;
+}
+
+.guide-content li + li {
+    margin-top: 0.2rem;
+}
+
 .card h2,
 .card h3 {
     margin: 0.25rem 0;

pyproject.toml

@@ -12,7 +12,8 @@ requires-python = ">=3.10"
 dependencies = [
     "reachy-mini",
     "scamp",
-    "scipy"
+    "scipy",
+    "markdown"
 ]
 keywords = ["reachy-mini-app"]
 

ressources/fluidsynth_guide.md

@@ -0,0 +1,122 @@
+
+---
+
+If you see this message, it means that **FluidSynth** is not installed.
+
+This app needs **FluidSynth**, a system audio component, to be installed on your computer.
+
+The dashboard doesn't have the permissions to install the library so you have to do it manually.
+
+**Important:**
+After installing FluidSynth, you must **uninstall and reinstall the app**.
+This is the fastest and safest way to make sure everything is detected correctly.
+
+---
+
+## macOS
+
+### Step 1 – Install FluidSynth
+
+1. Open **Terminal**
+
+   * Press `⌘ + Space`
+   * Type **Terminal**
+   * Press Enter
+
+2. Copy and paste this command, then press Enter:
+
+   ```
+   brew install fluid-synth
+   ```
+
+If you see an error saying `brew: command not found`, do this first:
+
+```
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+Wait for it to finish, then run again:
+
+```
+brew install fluid-synth
+```
+
+---
+
+### Step 2 – Reinstall the app (from the dashboard)
+
+1. Uninstall the app
+2. Install it again
+3. Launch the app
+
+---
+
+## Windows
+
+### Step 1 – Install FluidSynth
+
+1. Open this page in your browser:
+   [https://github.com/FluidSynth/fluidsynth/releases](https://github.com/FluidSynth/fluidsynth/releases)
+
+2. Download the latest **Windows installer (.exe)**
+
+3. Run the installer
+
+   * Keep all default options
+   * Finish the installation
+
+---
+
+### Step 2 – Reinstall the app (from the dashboard)
+
+1. Uninstall the app
+2. Install it again
+3. Launch the app
+
+The app will detect FluidSynth and complete setup automatically.
+
+Windows audio setups vary, but this works for most users.
+
+---
+
+## Linux (Ubuntu / Debian)
+
+### Step 1 – Install FluidSynth
+
+1. Open a terminal
+2. Run:
+
+   ```
+   sudo apt update
+   sudo apt install fluidsynth
+   ```
+
+---
+
+### Step 2 – Reinstall the app (from the dashboard)
+
+1. Uninstall the app
+2. Install it again
+3. Launch the app
+
+---
+
+## How to check if FluidSynth is installed (optional)
+
+If you are curious, you can run:
+
+```
+fluidsynth --version
+```
+
+If you see a version number, FluidSynth is installed correctly.
+
+---
+
+## If it still does not work
+
+If the problem persists, copy the error messages you can find and create an issue with the info.
+
+---
+
+