Refactor marionette into modules, fix audio sync, improve tests

Split 2349-line main.py into 7 focused modules (app, state, recording,
datasets, routes, audio, models). Fix audio-motion sync by compensating
320ms push_audio_sample pipeline latency (AUDIO_LEAD_MS). Fix countdown
beep sample rate (was 48kHz, should be 16kHz). Fix dataset re-download.
Add comprehensive sync test suite and 142+ unit tests.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.gitignore

@@ -9,3 +9,9 @@ emotion_dataset_example/
 .report.json
 pytest-of-*/
 temp_uploads/
+
+# Test artifacts (plots, recordings, results)
+tests/*.png
+tests/*.wav
+tests/*.json
+!tests/conftest.py

ARCHITECTURE.md

@@ -0,0 +1,176 @@
+# Marionette Architecture
+
+This document explains the design of the Marionette app for developers who want to understand, modify, or debug it.
+
+## What Marionette Does
+
+Marionette records and plays back head movements (+ optional audio) for the Reachy Mini robot. A user moves the robot's head by hand while the app records the pose at 100 Hz, then replays it as an animated movement. Audio can be recorded from the mic, uploaded as a file, downloaded from YouTube, or picked from the robot's filesystem.
+
+## System Overview
+
+```
+┌─────────────────┐         HTTP (polling)        ┌──────────────────┐
+│   Browser (UI)  │ ◄──────────────────────────── │  FastAPI Server  │
+│   main.js       │ ──────────────────────────── ►│  (Uvicorn)       │
+│   index.html    │     POST /api/record          │                  │
+│   style.css     │     POST /api/play            │  marionette/     │
+└─────────────────┘     GET  /api/state           │  ├── app.py      │
+                                                  │  ├── routes.py   │
+                                                  │  ├── recording.py│
+                                                  │  ├── datasets.py │
+                                                  │  ├── audio.py    │
+                                                  │  ├── state.py    │
+                                                  │  └── models.py   │
+                                                  └────────┬─────────┘
+                                                           │
+                                                  ┌────────▼─────────┐
+                                                  │   Reachy Mini    │
+                                                  │   (Robot SDK)    │
+                                                  └──────────────────┘
+```
+
+### Two-Machine vs Single-Machine
+
+- **Reachy Mini**: Backend runs on the robot (Linux ARM), browser runs on a laptop. Connected via WiFi.
+- **Reachy Mini Light**: Backend and browser run on the same laptop. The robot connects via USB.
+
+## Module Map
+
+| Module | Purpose | Key classes/functions |
+|--------|---------|---------------------|
+| `models.py` | Data types, constants, Pydantic models | `RecordingMetadata`, `RecordingRequest`, `DatasetEntry`, all `*Payload` classes |
+| `audio.py` | Stateless audio functions | `play_wav_chunked()`, `preload_wav()`, `play_preloaded_wav()` |
+| `state.py` | Thread-safe state read/write | `StateMixin._serialize_state()`, `_set_state()`, `_set_idle_state()` |
+| `recording.py` | Motion capture + playback | `RecordingMixin._capture_motion()`, `_perform_recording()`, `_perform_playback()` |
+| `datasets.py` | Dataset filesystem + HF sync | `DatasetMixin._load_dataset_registry()`, `_sync_dataset()`, `_check_hf_login()` |
+| `routes.py` | HTTP endpoint definitions | `register_routes()` — all FastAPI route closures |
+| `app.py` | Main class, run loop, robot helpers | `Marionette`, `create_app()` |
+| `main.py` | Re-export hub | Imports and re-exports everything for backward compatibility |
+| `motion_models.py` | Lead compensation model | `MotionModelRegistry`, shifts commands forward to counter mechanical lag |
+
+## Threading Model
+
+The app has three types of threads:
+
+1. **Uvicorn thread** — Runs the FastAPI HTTP server. Handles all API requests. This is the thread that calls route handlers in `routes.py`.
+2. **Main robot thread** — Runs `Marionette.run()`. Polls for pending jobs (recording or playback) in a 50ms loop. Executes recording/playback synchronously.
+3. **Audio threads** — Spawned as daemon threads during playback. Push audio chunks to the robot's GStreamer pipeline.
+
+### Thread Safety
+
+All shared state is protected by `_state_lock` (a `threading.Lock`):
+
+- The HTTP thread writes: `_pending_recording`, `_pending_playback`, `_mode`
+- The robot thread reads and clears: `_pending_recording`, `_pending_playback`
+- Both threads read: `_mode`, `_recordings`, `_datasets`
+
+The lock is held briefly — never during I/O or network calls.
+
+### Cancel Events
+
+- `_recording_cancel_event` — Set by the HTTP thread (POST /api/record/stop), checked by the robot thread's capture loop.
+- `_playback_cancel_event` — Set by the HTTP thread (POST /api/play/stop), checked by the robot thread's playback loop.
+
+## State Machine
+
+```
+          POST /api/record
+  idle ──────────────────── queued
+   ▲                          │
+   │                     (robot thread picks up)
+   │                          ▼
+   │                      countdown (3s)
+   │                          │
+   │                          ▼
+   └──────────────────── recording
+                              │
+                         (duration elapsed or stop)
+                              ▼
+                            idle
+
+          POST /api/play
+  idle ──────────────────── queued
+   ▲                          │
+   │                     (robot thread picks up)
+   │                          ▼
+   └──────────────────── playing
+                              │
+                         (move ends or stop)
+                              ▼
+                            idle
+```
+
+Additional states: `starting_up` (during boot animation), `error` (transient, returns to idle).
+
+## Frontend Architecture
+
+The frontend is vanilla JavaScript (no framework). Key patterns:
+
+### Polling Loop
+
+The browser polls `GET /api/state` at regular intervals:
+- **1500ms** when idle (nothing happening)
+- **200ms** when active (recording, playing, countdown)
+
+Each poll returns the full app state. The frontend updates the UI accordingly.
+
+### Dirty Flag Pattern (Flickering Fix)
+
+The moves list and dataset dropdown are expensive to rebuild (full DOM replacement). Without optimization, they flicker on every poll. The fix:
+
+- `movesListDirty` and `datasetsDirty` flags start as `true`
+- `renderMoves()` / `updateDatasetUI()` only run when the flag is `true`
+- Flags are set `true` after user actions (record, delete, switch dataset, etc.)
+- During idle polling, only lightweight updates happen (mode badge, play/stop buttons)
+
+### NTP-Style Clock Sync
+
+The backend sends `server_time` with each state response. The frontend computes `clockOffset = serverTime - localTime` and uses it to accurately display countdown timers and recording progress bars, even when the browser and robot are on different machines with unsynchronized clocks.
+
+### Phase Overlay
+
+During countdown and recording, a full-screen overlay shows progress. This uses `requestAnimationFrame` for smooth 60fps animation, independent of the polling interval.
+
+## Dataset Layout
+
+```
+~/reachy_mini_datasets/           # dataset root (configurable)
+├── local_dataset/                # default dataset
+│   └── data/                     # all recordings live here
+│       ├── happy-dance.json      # motion trajectory
+│       └── happy-dance.wav       # optional audio
+├── my-custom-set/
+│   └── data/
+│       └── ...
+└── user-community-set/           # downloaded from HF
+    └── data/
+        └── ...
+```
+
+The `dataset_registry.json` file (next to the app) tracks which datasets exist, which is active, and per-dataset metadata (uploaded move IDs, origin, etc.).
+
+## Audio Playback Pipeline
+
+Audio is played through the Reachy Mini's GStreamer pipeline using chunk-based pushing:
+
+1. **Preload**: Read WAV file, resample to output rate if needed
+2. **Prime pipeline**: Call `start_playing()` to initialize GStreamer
+3. **Wait for sync**: Audio thread waits for `start_signal` (set when first motion command is sent)
+4. **Push chunks**: Feed 20ms audio chunks at ~1.25x real-time
+5. **Drain buffer**: Wait for remaining audio to play out
+6. **Cleanup**: Call `stop_playing()` with timeout (GStreamer can hang)
+
+This push-based approach allows stopping audio at any time, unlike `play_sound()` which creates an uninterruptible pipeline.
+
+## Lead Compensation
+
+Mechanical lag means the robot's actual motion trails the commanded trajectory. The lead compensation model (in `motion_models.py`) shifts commands forward in time so the actual motion matches the original recording. Parameters (head lead, antenna lead) are tunable in the settings UI.
+
+## Testing
+
+Tests live in `tests/test_api.py` and use FastAPI's `TestClient` for synchronous HTTP testing without a real robot. The `conftest.py` creates a Marionette instance with a temporary dataset directory.
+
+Key test patterns:
+- HF functions are monkeypatched on `marionette.datasets` (the canonical location)
+- Audio functions are monkeypatched on `marionette.recording` (where they're imported)
+- Recording/playback tests use fake `ReachyMini` objects with stub methods

marionette/app.py

@@ -0,0 +1,330 @@
+"""Core Marionette application class.
+
+This module defines the Marionette class that inherits from ReachyMiniApp
+and composes all functionality via mixins (StateMixin, RecordingMixin,
+DatasetMixin).  It handles initialisation, the main run loop, robot
+motion helpers, and the startup animation.
+"""
+from __future__ import annotations
+
+import time as _time_mod
+_BOOT_T0 = _time_mod.perf_counter()
+
+import logging
+import platform
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from reachy_mini import ReachyMini, ReachyMiniApp
+from reachy_mini.reachy_mini import INIT_HEAD_POSE, SLEEP_HEAD_POSE
+from reachy_mini.utils.interpolation import distance_between_poses
+
+from marionette.audio import play_wav_chunked
+from marionette.datasets import DatasetMixin
+from marionette.models import (
+    DATASET_REGISTRY_FILENAME,
+    DEFAULT_DURATION,
+    RecordingMetadata,
+    RecordingRequest,
+    SEMI_AWAKEN_POSE,
+)
+from marionette.motion_models import MotionModelRegistry
+from marionette.recording import RecordingMixin
+from marionette.routes import register_routes
+from marionette.state import StateMixin
+
+try:
+    import soundfile as sf
+except Exception:  # pragma: no cover
+    sf = None
+
+try:
+    from importlib.metadata import version as _pkg_version
+    __version__ = _pkg_version("marionette")
+except Exception:
+    __version__ = "unknown"
+
+logger = logging.getLogger(__name__)
+
+
+class Marionette(DatasetMixin, RecordingMixin, StateMixin, ReachyMiniApp):
+    """Manual Marionette recorder for Reachy Mini."""
+
+    custom_app_url: str | None = "http://0.0.0.0:8042"
+
+    def __init__(
+        self,
+        registry_path: Path | None = None,
+        dataset_root: Path | None = None,
+    ) -> None:
+        super().__init__()
+        self._registry_path = registry_path or (
+            Path(__file__).resolve().parent.parent / DATASET_REGISTRY_FILENAME
+        )
+        self._dataset_root_override = dataset_root
+        self._datasets: dict[str, Any] = {}
+        self._active_dataset_id: str | None = None
+        self._dataset_root: Path
+        self._dataset_dir: Path
+        self._motion_model_registry = MotionModelRegistry()
+        self._preferred_duration: float = DEFAULT_DURATION
+        self._welcome_messages: int = 2  # 0=none, 1=intro only, 2=intro+second
+        self._load_dataset_registry()  # may overwrite _preferred_duration and _welcome_messages
+
+        self._recordings: dict[str, RecordingMetadata] = {}
+        self._pending_recording: RecordingRequest | None = None
+        self._pending_playback: str | None = None
+        self._uploaded_audio: dict[str, Path] = {}  # upload_id -> temp file path
+        self._playback_cancel_event = threading.Event()
+        self._recording_cancel_event = threading.Event()
+        self._mode: str = "idle"
+        self._message: str = "Ready to capture moves"
+        self._countdown_ends_at: float | None = None
+        self._active_record_started_at: float | None = None
+        self._active_record_duration: float | None = None
+        self._active_move: str | None = None
+        self._state_lock = threading.Lock()
+        self._audio_available = sf is not None
+        self._recording_stats: dict[str, Any] | None = None
+        self._hf_username: str | None = None
+        self._hf_checked = False
+
+        self._refresh_recordings()
+        print(f"[BOOT] __init__ done at +{time.perf_counter() - _BOOT_T0:.2f}s after module import", flush=True)
+        logger.info("Marionette v%s starting on %s (%s)", __version__, platform.node(), platform.system())
+        if self.settings_app is not None:
+            register_routes(self, version=__version__)
+
+    # ──────── Startup animation ───────────────────────────────────────
+
+    def _run_startup_animation(
+        self, reachy_mini: ReachyMini, stop_event: threading.Event
+    ) -> None:
+        """Startup greeting with configurable welcome messages.
+
+        Behaviour depends on self._welcome_messages (0, 1, or 2):
+          0 messages — head up, head down, release torque (silent)
+          1 message  — head up, play intro, head down, release torque
+          2 messages — head up, play intro, head down, pause, head semi-up,
+                       play second message, release torque (full greeting)
+
+        Uses stop_event.wait() instead of time.sleep() so the startup
+        can be interrupted cleanly if the app is shutting down.
+        """
+        self._set_state(mode="starting_up", message="Starting up…", active_move=None)
+        assets = Path(__file__).parent / "assets"
+        n_messages = self._welcome_messages
+
+        # Step 1: Head up (all modes)
+        self._safe_enable_motors(reachy_mini)
+        print(f"[BOOT] anim: enable_motors done at +{time.perf_counter() - _BOOT_T0:.2f}s", flush=True)
+        self._goto_pose_scaled(
+            reachy_mini,
+            INIT_HEAD_POSE,
+            antennas=[0.0, 0.0],
+            min_duration=0.2,
+        )
+        print(f"[BOOT] anim: head-up done at +{time.perf_counter() - _BOOT_T0:.2f}s", flush=True)
+
+        if stop_event.is_set():
+            return
+
+        # Step 2: Play intro sound (1 or 2 messages)
+        if n_messages >= 1:
+            intro_path = assets / "intro_marionette.wav"
+            if intro_path.exists() and not stop_event.is_set():
+                try:
+                    play_wav_chunked(reachy_mini, intro_path, stop_event)
+                except Exception as exc:
+                    logger.warning("Failed to play intro sound: %s", exc)
+            print(f"[BOOT] anim: intro sound done at +{time.perf_counter() - _BOOT_T0:.2f}s", flush=True)
+
+        if stop_event.is_set():
+            return
+
+        # Step 3: Head down + release torque (all modes)
+        self._goto_sleep_and_release(reachy_mini)
+
+        if stop_event.is_set():
+            return
+
+        # Step 4: Second message with semi-awaken pose (2 messages only)
+        # Motion first (fast, ~0.3s), then audio sequentially — same
+        # pattern as Step 2 for simplicity.
+        if n_messages >= 2:
+            second_path = assets / "please.wav"
+            if second_path.exists() and not stop_event.is_set():
+                self._safe_enable_motors(reachy_mini)
+                antenna_angle = np.deg2rad(15)
+                reachy_mini.goto_target(
+                    SEMI_AWAKEN_POSE,
+                    antennas=[-antenna_angle, antenna_angle],
+                    duration=0.3,
+                )
+                try:
+                    play_wav_chunked(reachy_mini, second_path, stop_event)
+                except Exception as exc:
+                    logger.warning("Failed to play second sound: %s", exc)
+                self._goto_sleep_and_release(reachy_mini)
+
+    # ──────── Main loop ───────────────────────────────────────────────
+
+    def run(self, reachy_mini: ReachyMini, stop_event: threading.Event) -> None:
+        try:
+            _run_t0 = time.perf_counter()
+            print(f"[BOOT] run() entered at +{_run_t0 - _BOOT_T0:.2f}s after module import", flush=True)
+            self._run_startup_animation(reachy_mini, stop_event)
+            print(f"[BOOT] startup animation done at +{time.perf_counter() - _BOOT_T0:.2f}s", flush=True)
+            self._set_idle_state()
+
+            # Main job-polling loop: check for pending recording or playback
+            # every 20ms. The HTTP thread queues jobs by setting _pending_recording
+            # or _pending_playback under the lock; we pick them up and execute
+            # synchronously on this thread (the robot thread).
+            while not stop_event.is_set():
+                job_type: str | None = None
+                payload: RecordingRequest | str | None = None
+
+                with self._state_lock:
+                    if self._pending_recording is not None:
+                        job_type = "record"
+                        payload = self._pending_recording
+                        self._pending_recording = None
+                    elif self._pending_playback is not None:
+                        job_type = "play"
+                        payload = self._pending_playback
+                        self._pending_playback = None
+
+                if job_type == "record" and isinstance(payload, RecordingRequest):
+                    self._perform_recording(reachy_mini, stop_event, payload)
+                    self._set_idle_state()
+                elif job_type == "play" and isinstance(payload, str):
+                    self._perform_playback(reachy_mini, payload)
+                    self._set_idle_state()
+                    self._align_head_and_release(reachy_mini)
+                else:
+                    stop_event.wait(0.02)
+        finally:
+            self._park_robot(reachy_mini)
+
+    # ──────── Robot motion helpers ────────────────────────────────────
+
+    def _scaled_duration(
+        self, reachy_mini: ReachyMini, target_head_pose: np.ndarray, *, min_duration: float = 0.05
+    ) -> float:
+        """Compute a motion duration proportional to the distance to travel.
+
+        Uses the SDK's distance_between_poses (combining rotation and
+        translation into a single scalar) and scales it to a comfortable
+        speed. This ensures slow moves for small adjustments and faster
+        moves for large transitions, instead of a fixed duration.
+        """
+        _, _, magic_distance = distance_between_poses(
+            reachy_mini.get_current_head_pose(),
+            target_head_pose,
+        )
+        duration = magic_distance * 20 / 1000
+        return max(min_duration, duration)
+
+    def _goto_pose_scaled(
+        self,
+        reachy_mini: ReachyMini,
+        head_pose: np.ndarray,
+        *,
+        antennas: list[float] | np.ndarray | None = None,
+        min_duration: float = 0.05,
+    ) -> None:
+        """Go to pose with duration scaled by distance. goto_target is blocking."""
+        duration = self._scaled_duration(reachy_mini, head_pose, min_duration=min_duration)
+        antennas_payload = list(antennas) if antennas is not None else None
+        reachy_mini.goto_target(
+            head=head_pose,
+            antennas=antennas_payload,
+            duration=duration,
+        )
+
+    def _goto_current_pose(self, reachy_mini: ReachyMini, duration: float = 0.05) -> None:
+        head_pose = reachy_mini.get_current_head_pose()
+        _, antennas = reachy_mini.get_current_joint_positions()
+        reachy_mini.goto_target(
+            head=head_pose,
+            antennas=list(antennas) if antennas is not None else None,
+            duration=max(0.02, duration),
+        )
+
+    def _safe_enable_motors(self, reachy_mini: ReachyMini) -> None:
+        """Enable motors without a physical jerk.
+
+        If we just call enable_motors(), the robot snaps to whatever target
+        pose was last commanded. By first setting the target to the current
+        actual pose, the transition is smooth even if the head was moved
+        by hand while motors were off.
+        """
+        self._goto_current_pose(reachy_mini, duration=0.05)
+        reachy_mini.enable_motors()
+        time.sleep(0.1)
+
+    def _park_robot(self, reachy_mini: ReachyMini) -> None:
+        self._safe_enable_motors(reachy_mini)
+        self._goto_pose_scaled(
+            reachy_mini,
+            INIT_HEAD_POSE,
+            antennas=[0.0, 0.0],
+            min_duration=0.2,
+        )
+
+    def _align_head_and_release(self, reachy_mini: ReachyMini) -> None:
+        """After playback, return to neutral pose then release motors.
+
+        Called after _perform_playback so the robot ends in a predictable
+        position ready for the user to grab and record the next move.
+        """
+        self._safe_enable_motors(reachy_mini)
+        self._goto_pose_scaled(
+            reachy_mini,
+            INIT_HEAD_POSE,
+            antennas=[0.0, 0.0],
+            min_duration=0.2,
+        )
+        self._goto_sleep_and_release(reachy_mini)
+
+    def _goto_sleep_and_release(self, reachy_mini: ReachyMini) -> None:
+        """Move head to sleep pose then disable motors (graceful torque-off)."""
+        # Use 15 degrees for antennas for style points
+        antenna_angle = np.deg2rad(15)
+        reachy_mini.goto_target(
+            SLEEP_HEAD_POSE,
+            antennas=[-antenna_angle, antenna_angle],
+            duration=1.0,
+        )
+        reachy_mini.disable_motors()
+
+
+def create_app(
+    registry_path: Path | None = None,
+    dataset_root: Path | None = None,
+) -> tuple["Any", "Marionette"]:
+    """Create a Marionette instance and its FastAPI app.
+
+    Useful for testing with FastAPI's TestClient:
+        app, marionette = create_app(registry_path=tmp / "reg.json", dataset_root=tmp / "ds")
+        client = TestClient(app)
+    """
+    marionette = Marionette(
+        registry_path=registry_path,
+        dataset_root=dataset_root,
+    )
+    assert marionette.settings_app is not None
+    return marionette.settings_app, marionette
+
+
+if __name__ == "__main__":
+    app = Marionette()
+    try:
+        app.wrapped_run()
+    except KeyboardInterrupt:
+        app.stop()

marionette/audio.py

@@ -0,0 +1,201 @@
+"""Audio playback and recording helper functions.
+
+All functions in this module are stateless (no class dependency) and can be
+called from any context.  They handle WAV file I/O, resampling, and chunked
+push-based playback through the Reachy Mini media pipeline.
+"""
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from pathlib import Path
+
+import numpy as np
+
+try:
+    import soundfile as sf
+except Exception:  # pragma: no cover - optional dependency
+    sf = None
+
+logger = logging.getLogger(__name__)
+
+
+def generate_beep(
+    freq: float = 440,
+    duration: float = 0.1,
+    sr: int = 48000,
+    fade_ms: float = 10,
+) -> np.ndarray:
+    """Generate a short sine-wave beep with fade-in/out to avoid clicks."""
+    n = int(sr * duration)
+    t = np.arange(n, dtype=np.float32) / sr
+    samples = 0.3 * np.sin(2 * np.pi * freq * t).astype(np.float32)
+    # Apply fade-in/out
+    fade_samples = int(sr * fade_ms / 1000)
+    if fade_samples > 0 and 2 * fade_samples < n:
+        fade_in = np.linspace(0, 1, fade_samples, dtype=np.float32)
+        fade_out = np.linspace(1, 0, fade_samples, dtype=np.float32)
+        samples[:fade_samples] *= fade_in
+        samples[-fade_samples:] *= fade_out
+    return samples
+
+
+def get_audio_duration(path: Path, fallback: float | None = 3.0) -> float | None:
+    """Return the duration of a WAV file in seconds, or *fallback* on error."""
+    if sf is not None:
+        try:
+            info = sf.info(str(path))
+            return float(info.duration)
+        except Exception:
+            pass
+    return fallback
+
+
+def play_wav_chunked(
+    reachy_mini: object,
+    wav_path: Path,
+    stop_event: threading.Event,
+    chunk_duration: float = 0.02,
+) -> None:
+    """Play a WAV file via push_audio_sample() so it can be stopped at any time.
+
+    Unlike play_sound() which creates an orphan GStreamer pipeline that
+    cannot be interrupted, this loads the WAV, resamples to the output
+    rate, and pushes small chunks through the stoppable playback pipeline.
+    """
+    if sf is None:
+        return
+    try:
+        data, sr = sf.read(str(wav_path), dtype="float32")
+    except Exception as exc:
+        logger.warning("Failed to read %s: %s", wav_path, exc)
+        return
+
+    if data.ndim == 2:
+        data = data.mean(axis=1)
+
+    # Resample if the file's rate doesn't match the output device.
+    try:
+        sr_out = int(reachy_mini.media.get_output_audio_samplerate() or 16000)
+    except Exception:
+        sr_out = 16000
+    if sr != sr_out:
+        try:
+            from scipy.signal import resample
+
+            num_samples = int(len(data) * sr_out / sr)
+            data = resample(data, num_samples).astype(np.float32)
+            sr = sr_out
+        except Exception as exc:
+            logger.warning("Resample failed: %s — playing at original rate", exc)
+
+    reachy_mini.media.start_playing()
+
+    samples_per_chunk = max(1, int(sr * chunk_duration))
+    play_start = time.perf_counter()
+    try:
+        for offset in range(0, len(data), samples_per_chunk):
+            if stop_event.is_set():
+                break
+            chunk = data[offset : offset + samples_per_chunk]
+            reachy_mini.media.push_audio_sample(chunk)
+            # Sleep slightly less than chunk duration to keep buffer fed
+            stop_event.wait(chunk_duration * 0.8)
+        else:
+            # All chunks pushed — wait for the audio buffer to drain.
+            # We pushed ~20% faster than real-time, so the playback
+            # pipeline still has buffered audio to play out.
+            audio_duration = len(data) / sr
+            elapsed = time.perf_counter() - play_start
+            remaining = audio_duration - elapsed
+            if remaining > 0:
+                stop_event.wait(remaining)
+    finally:
+        call_with_timeout(reachy_mini.media.stop_playing)
+
+
+def preload_wav(wav_path: Path, target_sr: int | None = None) -> tuple[np.ndarray, int] | None:
+    """Read a WAV file, returning (data, sample_rate) or None.
+
+    If target_sr is given and differs from the file's rate, resample.
+    """
+    if sf is None:
+        return None
+    try:
+        data, sr = sf.read(str(wav_path), dtype="float32")
+    except Exception as exc:
+        logger.warning("Failed to read %s: %s", wav_path, exc)
+        return None
+    if data.ndim == 2:
+        data = data.mean(axis=1)
+    if target_sr and sr != target_sr:
+        try:
+            from scipy.signal import resample
+
+            num_samples = int(len(data) * target_sr / sr)
+            data = resample(data, num_samples).astype(np.float32)
+            sr = target_sr
+        except Exception as exc:
+            logger.warning("Resample failed: %s — using original rate", exc)
+    return data, sr
+
+
+def play_preloaded_wav(
+    reachy_mini: object,
+    wav_data: tuple[np.ndarray, int],
+    stop_event: threading.Event,
+    chunk_duration: float = 0.02,
+    pipeline_ready: bool = False,
+    start_signal: threading.Event | None = None,
+) -> None:
+    """Push preloaded WAV data through the playback pipeline."""
+    data, sr = wav_data
+    if not pipeline_ready:
+        reachy_mini.media.start_playing()
+    # If a start_signal is provided, wait until the caller says go
+    # (e.g. after the first motion command is sent).
+    if start_signal is not None:
+        start_signal.wait(timeout=5.0)
+    samples_per_chunk = max(1, int(sr * chunk_duration))
+    play_start = time.perf_counter()
+    try:
+        for offset in range(0, len(data), samples_per_chunk):
+            if stop_event.is_set():
+                break
+            chunk = data[offset : offset + samples_per_chunk]
+            reachy_mini.media.push_audio_sample(chunk)
+            stop_event.wait(chunk_duration * 0.8)
+        else:
+            audio_duration = len(data) / sr
+            elapsed = time.perf_counter() - play_start
+            remaining = audio_duration - elapsed
+            if remaining > 0:
+                stop_event.wait(remaining)
+    finally:
+        call_with_timeout(reachy_mini.media.stop_playing)
+
+
+def call_with_timeout(fn: object, timeout: float = 2.0, retries: int = 2) -> bool:
+    """Call fn() in a daemon thread with timeout and retries.
+
+    GStreamer's set_state() can hang when the audio device is slow or the
+    GLib MainLoop is starved.  We run the call in a disposable daemon thread
+    and retry up to `retries` times — often the second attempt succeeds
+    because the MainLoop has had time to process pending bus messages.
+
+    Returns True if the call completed within the timeout, False if all
+    attempts timed out (the last thread is abandoned as a daemon).
+    """
+    for attempt in range(1, retries + 1):
+        t = threading.Thread(target=fn, daemon=True)
+        t.start()
+        t.join(timeout)
+        if not t.is_alive():
+            return True
+        logger.warning(
+            "%s attempt %d/%d did not complete within %.1fs",
+            fn, attempt, retries, timeout,
+        )
+    logger.error("%s hung after %d attempts — abandoning", fn, retries)
+    return False

marionette/datasets.py

@@ -0,0 +1,706 @@
+"""Dataset management mixin for the Marionette app.
+
+Handles dataset registry CRUD, Hugging Face sync/download, community
+dataset listing, and filesystem layout management.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import platform
+import shutil
+import time
+from datetime import datetime
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from textwrap import dedent
+from typing import Any
+
+from fastapi import HTTPException
+
+from marionette.models import (
+    COMMUNITY_DATASET_TAG,
+    DATASET_DATA_SUBDIR,
+    DATASET_DIRNAME,
+    DEFAULT_DATASET_LABEL,
+    DEFAULT_DURATION,
+    HF_DATASETS_API_URL,
+    MAX_COMMUNITY_DATASETS,
+    DatasetEntry,
+    DownloadDatasetPayload,
+    RecordingMetadata,
+    _slugify,
+)
+
+# ──────── Optional Hugging Face imports ───────────────────────────────
+
+try:
+    from huggingface_hub import HfApi, snapshot_download, whoami as hf_whoami
+    from huggingface_hub import login as hf_login, logout as hf_logout
+    from huggingface_hub import get_token as hf_get_token
+except Exception:  # pragma: no cover - optional dependency
+    HfApi = None
+    snapshot_download = None
+    hf_whoami = None
+    hf_login = None
+    hf_logout = None
+    hf_get_token = None
+
+try:
+    from huggingface_hub import DatasetFilter
+except Exception:  # pragma: no cover - optional helper
+    DatasetFilter = None
+
+logger = logging.getLogger(__name__)
+
+
+class DatasetMixin:
+    """Mixin providing dataset management methods.
+
+    Expects the host class to have: _registry_path, _dataset_root_override,
+    _datasets, _active_dataset_id, _dataset_root, _dataset_dir,
+    _motion_model_registry, _preferred_duration, _welcome_messages,
+    _recordings, _state_lock, _save_dataset_registry(), _refresh_recordings(),
+    _ensure_dataset_data_dir().
+    """
+
+    def _load_dataset_registry(self) -> None:
+        """Load the dataset registry JSON and discover dataset folders on disk.
+
+        The registry stores user preferences (motion model params, preferred
+        duration, welcome messages) alongside per-dataset metadata. On startup:
+          1. Read the registry file (if it exists)
+          2. Determine the dataset root: CLI override > registry > fallback > platform default
+          3. Scan the root for dataset folders, merging stored metadata
+          4. Ensure at least one dataset exists (creates "local_dataset" if empty)
+        """
+        if self._registry_path.exists():
+            try:
+                raw = json.loads(self._registry_path.read_text(encoding="utf-8"))
+            except Exception:
+                raw = {}
+        else:
+            raw = {}
+
+        raw_params = raw.get("motion_model_params", {})
+        if isinstance(raw_params, dict):
+            for model_name, params in raw_params.items():
+                if isinstance(params, dict):
+                    try:
+                        self._motion_model_registry.set_model_params(model_name, params)
+                    except KeyError:
+                        continue
+        self._preferred_duration = float(raw.get("preferred_duration", DEFAULT_DURATION))
+        self._welcome_messages = int(raw.get("welcome_messages", 2))
+
+        dataset_entries = raw.get("datasets", [])
+        metadata_by_folder: dict[str, dict[str, Any]] = {}
+        fallback_root: Path | None = None
+        for entry in dataset_entries:
+            folder = entry.get("folder")
+            path_str = entry.get("path")
+            if folder:
+                metadata_by_folder[folder] = entry
+                if not fallback_root and path_str:
+                    resolved = self._resolve_dataset_path(path_str)
+                    fallback_root = resolved.parent
+            elif path_str and not fallback_root:
+                resolved = self._resolve_dataset_path(path_str)
+                fallback_root = resolved.parent
+
+        raw_root = raw.get("root_path")
+        if self._dataset_root_override is not None:
+            root_path = self._dataset_root_override
+        elif raw_root:
+            root_path = self._resolve_dataset_path(raw_root)
+        elif fallback_root:
+            root_path = fallback_root
+        else:
+            root_path = self._default_dataset_root()
+        self._dataset_root = root_path
+        self._dataset_root.mkdir(parents=True, exist_ok=True)
+        logger.info("Using dataset root at %s", self._dataset_root)
+
+        datasets: dict[str, DatasetEntry] = {}
+        used_ids: set[str] = set()
+        for folder_path in sorted(self._dataset_root.iterdir()):
+            if not folder_path.is_dir():
+                continue
+            folder = folder_path.name
+            meta = metadata_by_folder.get(folder, {})
+            dataset_id = meta.get("id")
+            if not dataset_id or dataset_id in used_ids:
+                dataset_id = self._next_dataset_id(folder, used_ids)
+            else:
+                used_ids.add(dataset_id)
+            label = meta.get("label") or folder
+            uploaded_ids = set(meta.get("uploaded_move_ids") or [])
+            origin = meta.get("origin", "local")
+            entry = self._entry_from_folder(folder, label, dataset_id, uploaded_ids, origin=origin)
+            datasets[dataset_id] = entry
+
+        if not datasets:
+            default_id = "default" if "default" not in used_ids else self._next_dataset_id(DATASET_DIRNAME, used_ids)
+            entry = self._entry_from_folder(DATASET_DIRNAME, DEFAULT_DATASET_LABEL, default_id)
+            datasets[entry.dataset_id] = entry
+
+        self._datasets = datasets
+        active_id = raw.get("active")
+        if active_id not in self._datasets:
+            active_id = next(iter(self._datasets))
+        self._active_dataset_id = active_id
+        self._dataset_dir = self._ensure_dataset_data_dir(self._datasets[active_id])
+        self._save_dataset_registry()
+
+    def _save_dataset_registry(self) -> None:
+        data = {
+            "active": self._active_dataset_id,
+            "root_path": str(self._dataset_root),
+            "motion_model_params": {
+                "lead_compensation": self._motion_model_registry.get_model_params("lead_compensation"),
+            },
+            "preferred_duration": self._preferred_duration,
+            "welcome_messages": self._welcome_messages,
+            "datasets": [
+                {
+                    "id": entry.dataset_id,
+                    "label": entry.label,
+                    "folder": entry.folder,
+                    "path": str(entry.path),
+                    "uploaded_move_ids": list(entry.uploaded_move_ids or []),
+                    "origin": entry.origin,
+                }
+                for entry in self._datasets.values()
+            ],
+        }
+        self._registry_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+    def _resolve_dataset_path(self, raw_path: str | Path) -> Path:
+        path = Path(raw_path).expanduser()
+        try:
+            path = path.resolve(strict=False)
+        except Exception:
+            path = path.expanduser().absolute()
+        return path
+
+    def _next_dataset_id(self, label: str, used: set[str]) -> str:
+        base = _slugify(label or "dataset")
+        candidate = base or "dataset"
+        suffix = 1
+        while candidate in used:
+            candidate = f"{base}-{suffix}"
+            suffix += 1
+        used.add(candidate)
+        return candidate
+
+    def _entry_from_folder(
+        self,
+        folder: str,
+        label: str,
+        dataset_id: str,
+        uploaded_move_ids: set[str] | None = None,
+        origin: str = "local",
+    ) -> DatasetEntry:
+        path = self._dataset_root / folder
+        entry = DatasetEntry(
+            dataset_id=dataset_id,
+            label=label,
+            folder=folder,
+            path=path,
+            uploaded_move_ids=uploaded_move_ids or set(),
+            origin=origin,
+        )
+        self._ensure_dataset_data_dir(entry)
+        return entry
+
+    def _default_dataset_root(self) -> Path:
+        system = platform.system().lower()
+        home = Path.home()
+        if "windows" in system:
+            base = home / "Documents" / "ReachyMini" / "datasets"
+        elif "darwin" in system:
+            base = home / "Library" / "Application Support" / "ReachyMini" / "datasets"
+        else:
+            base = home / "reachy_mini_datasets"
+        return base
+
+    def _ensure_dataset_data_dir(self, entry: DatasetEntry) -> Path:
+        """Ensure the dataset layout (root/folder/data/) exists and migrate legacy files.
+
+        Early versions stored .json/.wav directly in the dataset folder.
+        This migrates them into the data/ subdirectory for consistency with
+        the HF dataset layout.
+        """
+        entry.path.mkdir(parents=True, exist_ok=True)
+        data_dir = entry.path / DATASET_DATA_SUBDIR
+        data_dir.mkdir(parents=True, exist_ok=True)
+        legacy_moves = list(entry.path.glob("*.json"))
+        for json_path in legacy_moves:
+            target = data_dir / json_path.name
+            if not target.exists():
+                shutil.move(str(json_path), str(target))
+            for suffix in (".wav",):
+                source = json_path.with_suffix(suffix)
+                if source.exists():
+                    shutil.move(str(source), str(data_dir / source.name))
+        return data_dir
+
+    def _create_dataset_internal(
+        self,
+        folder: str,
+        label: str,
+        *,
+        dataset_id: str | None = None,
+        save: bool = True,
+        origin: str = "local",
+    ) -> DatasetEntry:
+        folder_slug = _slugify(folder or label or "dataset")
+        if any(entry.folder == folder_slug for entry in self._datasets.values()):
+            if dataset_id is None:
+                raise HTTPException(status_code=409, detail=f"Dataset folder '{folder_slug}' already exists.")
+        path = self._dataset_root / folder_slug
+        path.mkdir(parents=True, exist_ok=True)
+
+        if dataset_id is None:
+            base = _slugify(label or folder_slug or "dataset")
+            dataset_id = base or "dataset"
+            suffix = 1
+            while dataset_id in self._datasets:
+                dataset_id = f"{base}-{suffix}"
+                suffix += 1
+
+        entry = DatasetEntry(
+            dataset_id=dataset_id, label=label or dataset_id, folder=folder_slug, path=path, origin=origin
+        )
+        self._datasets[entry.dataset_id] = entry
+        self._ensure_dataset_data_dir(entry)
+        if save:
+            self._save_dataset_registry()
+        return entry
+
+    def _create_dataset(self, name: str, label: str | None) -> DatasetEntry:
+        if not name:
+            raise HTTPException(status_code=400, detail="Dataset name is required.")
+        folder = _slugify(name)
+        if not folder:
+            raise HTTPException(status_code=400, detail="Dataset name is invalid.")
+        if any(entry.folder == folder for entry in self._datasets.values()):
+            raise HTTPException(status_code=409, detail="Dataset name already used.")
+        label_to_use = label or name or DEFAULT_DATASET_LABEL
+        entry = self._create_dataset_internal(folder, label_to_use)
+        return entry
+
+    def _select_dataset(self, dataset_id: str) -> None:
+        entry = self._datasets.get(dataset_id)
+        if entry is None:
+            raise HTTPException(status_code=404, detail=f"Dataset {dataset_id} not found.")
+        self._active_dataset_id = dataset_id
+        self._dataset_dir = self._ensure_dataset_data_dir(entry)
+        self._save_dataset_registry()
+
+    def _datasets_payload(self) -> dict[str, Any]:
+        entries = sorted(
+            [entry.to_payload() for entry in self._datasets.values()],
+            key=lambda e: (e.get("label") or e["id"]).lower(),
+        )
+        return {
+            "active_id": self._active_dataset_id,
+            "root_path": str(self._dataset_root),
+            "entries": entries,
+        }
+
+    def _set_dataset_root(self, raw_path: str) -> None:
+        new_root = self._resolve_dataset_path(raw_path)
+        new_root.mkdir(parents=True, exist_ok=True)
+        self._dataset_root = new_root
+        logger.info("Dataset root updated to %s", self._dataset_root)
+        for entry in self._datasets.values():
+            entry.path = self._dataset_root / entry.folder
+            self._ensure_dataset_data_dir(entry)
+        if self._active_dataset_id not in self._datasets and self._datasets:
+            self._active_dataset_id = next(iter(self._datasets))
+        if self._active_dataset_id:
+            self._dataset_dir = self._ensure_dataset_data_dir(self._datasets[self._active_dataset_id])
+        else:
+            default = self._create_dataset_internal(DATASET_DIRNAME, DEFAULT_DATASET_LABEL)
+            self._active_dataset_id = default.dataset_id
+            self._dataset_dir = self._ensure_dataset_data_dir(default)
+        self._save_dataset_registry()
+
+    def _check_hf_login(self) -> str | None:
+        """Return the logged-in Hugging Face username, or None.
+
+        Uses a two-tier check:
+        1. Local: hf_get_token() reads ~/.cache/huggingface/token (no network).
+           If no token exists, we're definitely not logged in.
+        2. Network: hf_whoami() fetches the username from the HF API.
+           If this fails (timeout, rate limit, network down), we still report
+           as logged in (token exists) — just without a username.
+
+        Results are cached so we don't hit the API on every poll.
+        """
+        if self._hf_checked:
+            return self._hf_username
+        self._hf_checked = True
+        # Tier 1: local token check (no network)
+        if hf_get_token is None or not hf_get_token():
+            self._hf_username = None
+            return None
+        # Tier 2: try to get the username (network call)
+        if hf_whoami is not None:
+            try:
+                info = hf_whoami()
+                self._hf_username = info.get("name") if isinstance(info, dict) else None
+            except Exception:
+                # Network failed but token exists — report as logged in
+                self._hf_username = "(token saved)"
+        else:
+            self._hf_username = "(token saved)"
+        return self._hf_username
+
+    def _ensure_hf_backend(self, purpose: str) -> None:
+        global HfApi, DatasetFilter, snapshot_download
+        if HfApi is not None and snapshot_download is not None:
+            return
+        try:
+            from huggingface_hub import HfApi as _HfApi, snapshot_download as _snapshot_download
+            try:
+                from huggingface_hub import DatasetFilter as _DatasetFilter
+            except Exception:
+                _DatasetFilter = DatasetFilter  # keep existing (possibly None)
+        except Exception as exc:  # pragma: no cover - optional dependency
+            logger.warning("huggingface_hub unavailable for %s: %s", purpose, exc)
+            raise HTTPException(
+                status_code=500,
+                detail=f"huggingface_hub is not installed. Install it to {purpose}",
+            ) from exc
+        DatasetFilter = _DatasetFilter
+        HfApi = _HfApi
+        snapshot_download = _snapshot_download
+
+    def _sync_dataset(self, hf_username: str, move_ids: list[str], dataset_slug: str | None) -> dict[str, Any]:
+        self._ensure_hf_backend("publish datasets.")
+        if not move_ids:
+            raise HTTPException(status_code=400, detail="No moves selected for synchronization.")
+
+        self._refresh_recordings()
+        missing = [move_id for move_id in move_ids if move_id not in self._recordings]
+        if missing:
+            raise HTTPException(
+                status_code=404,
+                detail=f"Moves not found in active dataset: {', '.join(missing)}",
+            )
+
+        entry = self._datasets.get(self._active_dataset_id or "")
+        if entry is None:
+            raise HTTPException(status_code=404, detail="No active dataset.")
+
+        repo_basename = dataset_slug or _slugify(entry.label or entry.dataset_id)
+        repo_id = f"{hf_username}/{repo_basename}"
+        exported_bytes = 0
+        selected_meta = [self._recordings[move_id] for move_id in move_ids]
+
+        with TemporaryDirectory(prefix="marionette-sync-") as tmpdir:
+            export_root = Path(tmpdir)
+            data_dir = export_root / "data"
+            data_dir.mkdir(parents=True, exist_ok=True)
+            for meta in selected_meta:
+                src_json = meta.json_path
+                dest_json = data_dir / src_json.name
+                shutil.copy2(src_json, dest_json)
+                exported_bytes += dest_json.stat().st_size
+                wav_path = src_json.with_suffix(".wav")
+                if meta.has_audio and wav_path.exists():
+                    dest_wav = data_dir / wav_path.name
+                    shutil.copy2(wav_path, dest_wav)
+                    exported_bytes += dest_wav.stat().st_size
+
+            readme_path = export_root / "README.md"
+            readme_path.write_text(
+                self._build_hf_readme(entry, selected_meta, repo_id, exported_bytes),
+                encoding="utf-8",
+            )
+
+            api = HfApi()
+            try:
+                api.create_repo(
+                    repo_id=repo_id,
+                    repo_type="dataset",
+                    exist_ok=True,
+                    private=False,
+                )
+                api.upload_folder(
+                    folder_path=str(export_root),
+                    repo_id=repo_id,
+                    repo_type="dataset",
+                )
+            except Exception as exc:  # pragma: no cover - network failure
+                raise HTTPException(status_code=502, detail=f"Failed to upload dataset: {exc}") from exc
+
+        # Mark moves as uploaded
+        if entry.uploaded_move_ids is None:
+            entry.uploaded_move_ids = set()
+        for meta in selected_meta:
+            entry.uploaded_move_ids.add(meta.move_id)
+        self._save_dataset_registry()
+        self._refresh_recordings()
+
+        url = f"https://huggingface.co/datasets/{repo_id}"
+        return {
+            "status": "synced",
+            "repo_id": repo_id,
+            "uploaded_moves": len(selected_meta),
+            "url": url,
+        }
+
+    def _download_community_dataset(self, payload: DownloadDatasetPayload) -> DatasetEntry:
+        self._ensure_hf_backend("download datasets.")
+        repo_id = payload.repo_id.strip()
+        logger.info("Downloading community dataset %s", repo_id)
+        if "/" not in repo_id:
+            raise HTTPException(status_code=400, detail="repo_id must include the username (e.g. user/name).")
+        owner, repo_name = repo_id.split("/", 1)
+        folder_base = payload.name or f"{owner}-{repo_name}"
+        folder = _slugify(folder_base)
+        if not folder:
+            folder = _slugify(repo_id.replace("/", "-"))
+        existing = next((e for e in self._datasets.values() if e.folder == folder), None)
+        if existing is not None:
+            # Remove the old registry entry so we can re-download with updated content.
+            logger.info("Re-downloading dataset '%s' — removing old entry", folder)
+            del self._datasets[existing.dataset_id]
+            self._save_dataset_registry()
+        target_path = self._dataset_root / folder
+        if target_path.exists():
+            shutil.rmtree(target_path)
+        target_path.mkdir(parents=True, exist_ok=True)
+
+        try:
+            snapshot_download(
+                repo_id=repo_id,
+                repo_type="dataset",
+                local_dir=str(target_path),
+            )
+        except Exception as exc:  # pragma: no cover - network failure
+            logger.exception("Failed to download dataset %s", repo_id)
+            raise HTTPException(status_code=502, detail=f"Failed to download dataset: {exc}") from exc
+
+        label = payload.label or repo_id
+        entry = self._create_dataset_internal(folder=folder, label=label, origin="downloaded")
+        self._select_dataset(entry.dataset_id)
+        logger.info("Dataset %s downloaded into %s", repo_id, entry.path)
+        return entry
+
+    def _list_community_datasets(self) -> list[dict[str, Any]]:
+        datasets: list[Any] = self._fetch_community_datasets_http()
+        if not datasets and HfApi is not None:
+            dataset_filter = None
+            if DatasetFilter is not None:
+                try:
+                    dataset_filter = DatasetFilter(tags=[COMMUNITY_DATASET_TAG])
+                except Exception:  # pragma: no cover - incompatible hub version
+                    logger.debug("DatasetFilter unavailable, falling back to text search.")
+                    dataset_filter = None
+            search_query = None if dataset_filter else COMMUNITY_DATASET_TAG
+            logger.info("Listing community datasets via HfApi for tag %s", COMMUNITY_DATASET_TAG)
+            try:
+                api = HfApi()
+                datasets = api.list_datasets(
+                    filter=dataset_filter,
+                    search=search_query,
+                    limit=MAX_COMMUNITY_DATASETS,
+                    full=True,
+                )
+            except Exception as exc:  # pragma: no cover - network failure
+                logger.warning("HfApi dataset listing failed: %s", exc)
+                datasets = []
+        if not datasets:
+            raise HTTPException(status_code=502, detail="Unable to list community datasets from Hugging Face.")
+
+        filtered_items: list[Any] = []
+        for item in datasets:
+            tags = getattr(item, "tags", None) or item.get("tags") if isinstance(item, dict) else []
+            if tags and COMMUNITY_DATASET_TAG in tags:
+                filtered_items.append(item)
+        if not filtered_items:
+            filtered_items = datasets
+
+        results = []
+        for item in filtered_items:
+            repo_id = (
+                getattr(item, "id", None)
+                or getattr(item, "repo_id", None)
+                or (item.get("id") if isinstance(item, dict) else None)
+                or (item.get("repo_id") if isinstance(item, dict) else None)
+            )
+            if not repo_id:
+                continue
+            card = (
+                getattr(item, "cardData", None)
+                or getattr(item, "card_data", None)
+                or (item.get("cardData") if isinstance(item, dict) else None)
+                or {}
+            )
+            pretty = card.get("pretty_name") or repo_id
+            description = card.get("short_description") or card.get("description") or item.get("description", "")
+            updated = getattr(item, "lastModified", None) or item.get("lastModified")
+            if isinstance(updated, datetime):
+                updated_str = updated.isoformat()
+            else:
+                updated_str = str(updated) if updated else None
+
+            results.append(
+                {
+                    "repo_id": repo_id,
+                    "pretty_name": pretty,
+                    "description": description,
+                    "author": getattr(item, "author", None) or item.get("author"),
+                    "likes": getattr(item, "likes", None) or item.get("likes"),
+                    "downloads": getattr(item, "downloads", None) or item.get("downloads"),
+                    "last_modified": updated_str,
+                    "tags": getattr(item, "tags", None) or item.get("tags"),
+                }
+            )
+        return results
+
+    def _fetch_community_datasets_http(self) -> list[dict[str, Any]]:
+        """Try multiple HF API search strategies to find community datasets.
+
+        The HF API has changed its search syntax several times. We try three
+        approaches in order (tag:, keyword, legacy filter) and return the
+        first one that yields results. This makes us resilient to API changes.
+        """
+        base_params = {
+            "limit": MAX_COMMUNITY_DATASETS,
+            "full": "true",
+            "sort": "downloads",
+            "direction": "-1",
+        }
+        attempts = [
+            ("tag_search", {"search": f"tag:{COMMUNITY_DATASET_TAG}"}),
+            ("keyword_search", {"search": COMMUNITY_DATASET_TAG}),
+            ("legacy_filter", {"filter": COMMUNITY_DATASET_TAG}),
+        ]
+        for label, extra_params in attempts:
+            params = base_params.copy()
+            params.update(extra_params)
+            try:
+                import requests  # lazy import — only needed for community datasets
+                logger.debug("HTTP dataset listing (%s) with params %s", label, params)
+                resp = requests.get(
+                    HF_DATASETS_API_URL,
+                    params=params,
+                    timeout=30,
+                )
+                resp.raise_for_status()
+                data = resp.json()
+                if isinstance(data, list) and data:
+                    logger.info("Fetched %d community datasets via HTTP (%s)", len(data), label)
+                    return data
+                if isinstance(data, list):
+                    logger.debug("HTTP dataset listing (%s) returned zero results.", label)
+            except Exception as exc:
+                logger.warning("HTTP dataset listing (%s) failed: %s", label, exc)
+        return []
+
+    def _build_hf_readme(
+        self,
+        dataset_entry: DatasetEntry,
+        selected_meta: list[RecordingMetadata],
+        repo_id: str,
+        exported_bytes: int,
+    ) -> str:
+        pretty_name = f"{dataset_entry.label} • Reachy Mini Moves"
+        num_examples = len(selected_meta)
+        total_duration = sum(meta.duration for meta in selected_meta)
+        audio_count = sum(1 for meta in selected_meta if meta.has_audio)
+        latest_timestamp = max((meta.created_at for meta in selected_meta), default=time.time())
+        created_iso = datetime.utcfromtimestamp(latest_timestamp).strftime("%Y-%m-%dT%H:%M:%SZ")
+        move_rows = []
+        for meta in selected_meta:
+            recorded_at = datetime.utcfromtimestamp(meta.created_at).strftime("%Y-%m-%d %H:%M")
+            audio_label = "Yes" if meta.has_audio else "No"
+            move_rows.append(
+                f"| `{meta.move_id}` | {meta.duration:.1f}s | {audio_label} | {recorded_at} |"
+            )
+        moves_table = "\n".join(move_rows) if move_rows else "| – | – | – | – |"
+        front_matter = dedent(
+            f"""\
+            ---
+            dataset_info:
+              features:
+                - name: move_id
+                  dtype: string
+                - name: description
+                  dtype: string
+                - name: duration_seconds
+                  dtype: float64
+                - name: has_audio
+                  dtype: bool
+              splits:
+                - name: train
+                  num_examples: {num_examples}
+                  num_bytes: {exported_bytes}
+              download_size: {exported_bytes}
+              dataset_size: {exported_bytes}
+            configs:
+              - config_name: default
+                data_files:
+                  - split: train
+                    path: data/*.json
+            task_categories:
+              - robotics
+            language:
+              - en
+            tags:
+              - reachy_mini_community_moves
+            pretty_name: {pretty_name}
+            license: apache-2.0
+            ---
+            """
+        ).strip()
+
+        body = dedent(
+            f"""
+            # {pretty_name}
+
+            Community-contributed Marionette recordings captured on Reachy Mini.
+
+            - **Moves uploaded:** {num_examples}
+            - **Total motion time:** {total_duration:.1f} seconds
+            - **Audio tracks:** {audio_count}
+            - **Last updated:** {created_iso}
+
+            Files live under `data/` — each move ships as a JSON trajectory (Reachy Mini emotions schema) plus an optional WAV recorded directly from the robot.
+
+            ## How this dataset was produced
+
+            These takes were recorded with the Marionette Reachy Mini app. Pick the moves to share, set your Hugging Face username, run `huggingface-cli login` once locally, then hit **Synchronize to Hugging Face dataset** inside Marionette. The app packages the selected files, generates this README, and uploads them to `{repo_id}`.
+
+            ## Selected moves
+
+            | Move | Duration | Audio | Recorded at (UTC) |
+            | --- | --- | --- | --- |
+            {moves_table}
+
+            ## Reuse
+
+            - Cite this dataset as `{repo_id}`.
+            - Keep the `reachy_mini_community_moves` tag when sharing derivatives so the community can discover related sets.
+            """
+        ).strip()
+        return f"{front_matter}\n\n{body}\n"
+
+    def _delete_move_files(self, move_id: str) -> None:
+        json_path = self._dataset_dir / f"{move_id}.json"
+        if not json_path.exists():
+            raise HTTPException(status_code=404, detail=f"Move {move_id} not found.")
+        try:
+            json_path.unlink()
+            # Delete associated audio files (including legacy denoised/noise files)
+            for suffix in (".wav", ".noise.wav", ".denoised.wav"):
+                path = self._dataset_dir / f"{move_id}{suffix}"
+                if path.exists():
+                    path.unlink()
+        except OSError as exc:
+            raise HTTPException(status_code=500, detail=f"Failed to delete {move_id}: {exc}") from exc

marionette/main.py

@@ -1,2225 +1,67 @@
-from __future__ import annotations
-
-import time as _time_mod
-_BOOT_T0 = _time_mod.perf_counter()
-
-import json
-import logging
-import platform
-import re
-import shutil
-import threading
-import time
-import uuid
-from dataclasses import dataclass
-from datetime import datetime
-from pathlib import Path
-from tempfile import TemporaryDirectory
-from textwrap import dedent
-from typing import Any, Callable
-
-_t = _time_mod.perf_counter(); import numpy as np; _BOOT_NUMPY = _time_mod.perf_counter() - _t  # noqa: E702
-_BOOT_REQUESTS = 0.0  # requests is now lazy-imported (only needed for HF API calls)
-_t = _time_mod.perf_counter(); from fastapi import HTTPException, UploadFile, File; _BOOT_FASTAPI = _time_mod.perf_counter() - _t  # noqa: E702
-_t = _time_mod.perf_counter(); from pydantic import BaseModel, Field; _BOOT_PYDANTIC = _time_mod.perf_counter() - _t  # noqa: E702
+"""Marionette — re-export hub for backward compatibility.
 
-_t = _time_mod.perf_counter()
-from reachy_mini import ReachyMini, ReachyMiniApp
-from reachy_mini.motion.recorded_move import RecordedMove
-from reachy_mini.reachy_mini import INIT_HEAD_POSE, SLEEP_HEAD_POSE, SLEEP_ANTENNAS_JOINT_POSITIONS
-from reachy_mini.utils.interpolation import distance_between_poses
-_BOOT_REACHY = _time_mod.perf_counter() - _t
-
-_t = _time_mod.perf_counter(); from marionette.motion_models import MotionModelRegistry; _BOOT_MOTION = _time_mod.perf_counter() - _t  # noqa: E702
-
-try:
-    from importlib.metadata import version as _pkg_version
-    __version__ = _pkg_version("marionette")
-except Exception:
-    __version__ = "unknown"
+All public names are available via ``from marionette.main import ...`` so
+existing tests and entry points continue to work unchanged after the
+backend was split into focused submodules.
+"""
+from __future__ import annotations
 
-# Semi-awaken pose: identity rotation, same XY as sleep, Z raised 1.5cm
-SEMI_AWAKEN_POSE = np.array(
-    [
-        [1.0, 0.0, 0.0, -0.021],
-        [0.0, 1.0, 0.0, 0.001],
-        [0.0, 0.0, 1.0, -0.029],
-        [0.0, 0.0, 0.0, 1.0],
-    ]
+# Re-export all public types, constants, and utilities from submodules.
+from marionette.models import (  # noqa: F401
+    AUDIO_SAMPLE_RATE,
+    COMMUNITY_DATASET_TAG,
+    COUNTDOWN_SECONDS,
+    DATASET_DATA_SUBDIR,
+    DATASET_DIRNAME,
+    DATASET_REGISTRY_FILENAME,
+    DEFAULT_DATASET_LABEL,
+    DEFAULT_DURATION,
+    HF_DATASETS_API_URL,
+    MAX_COMMUNITY_DATASETS,
+    MOTION_SAMPLE_RATE,
+    SEMI_AWAKEN_POSE,
+    CreateDatasetPayload,
+    DatasetEntry,
+    DownloadDatasetPayload,
+    HfTokenPayload,
+    PlayMovePayload,
+    RecordingMetadata,
+    RecordingRequest,
+    RobotAudioSelectPayload,
+    SelectDatasetPayload,
+    StartRecordingPayload,
+    SyncDatasetPayload,
+    UpdateDatasetRootPayload,
+    UpdateExperimentsPayload,
+    UpdateLeadCompensationPayload,
+    _slugify,
 )
 
-_t = _time_mod.perf_counter()
-try:
-    import soundfile as sf
-except Exception:  # pragma: no cover - optional dependency
-    sf = None
-_BOOT_SOUNDFILE = _time_mod.perf_counter() - _t
-
-_BOOT_SCIPY = 0.0  # scipy is now lazy-imported (only needed for user-uploaded audio)
-
-_t = _time_mod.perf_counter()
-try:
-    from huggingface_hub import HfApi, snapshot_download, whoami as hf_whoami
-    from huggingface_hub import login as hf_login, logout as hf_logout
-    from huggingface_hub import get_token as hf_get_token
-except Exception:  # pragma: no cover - optional dependency
-    HfApi = None
-    snapshot_download = None
-    hf_whoami = None
-    hf_login = None
-    hf_logout = None
-    hf_get_token = None
-_BOOT_HF = _time_mod.perf_counter() - _t
-
-try:
-    from huggingface_hub import DatasetFilter
-except Exception:  # pragma: no cover - optional helper
-    DatasetFilter = None
-
-_BOOT_IMPORTS_TOTAL = _time_mod.perf_counter() - _BOOT_T0
-
-# Log import times at module level (before logger is configured, use print)
-print(
-    f"[BOOT] imports: total={_BOOT_IMPORTS_TOTAL:.2f}s | "
-    f"numpy={_BOOT_NUMPY:.2f}s requests={_BOOT_REQUESTS:.2f}s "
-    f"fastapi={_BOOT_FASTAPI:.2f}s pydantic={_BOOT_PYDANTIC:.2f}s "
-    f"reachy_mini={_BOOT_REACHY:.2f}s motion_models={_BOOT_MOTION:.2f}s "
-    f"soundfile={_BOOT_SOUNDFILE:.2f}s scipy={_BOOT_SCIPY:.2f}s "
-    f"huggingface_hub={_BOOT_HF:.2f}s",
-    flush=True,
+from marionette.audio import (  # noqa: F401
+    call_with_timeout,
+    get_audio_duration,
+    play_preloaded_wav,
+    play_wav_chunked,
+    preload_wav,
 )
 
-AUDIO_SAMPLE_RATE = 44_100
-MOTION_SAMPLE_RATE = 100.0
-COUNTDOWN_SECONDS = 3
-DEFAULT_DURATION = 5.0
-DATASET_DIRNAME = "local_dataset"
-DATASET_REGISTRY_FILENAME = "dataset_registry.json"
-DEFAULT_DATASET_LABEL = "Local dataset"
-COMMUNITY_DATASET_TAG = "reachy_mini_community_moves"
-MAX_COMMUNITY_DATASETS = 50
-HF_DATASETS_API_URL = "https://huggingface.co/api/datasets"
-DATASET_DATA_SUBDIR = "data"
-NOISE_SUFFIX = ".noise.wav"
-DENOISED_SUFFIX = ".denoised.wav"
-
-logger = logging.getLogger(__name__)
-
-
-def _slugify(value: str) -> str:
-    slug = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
-    return slug or "take"
-
-
-@dataclass
-class RecordingMetadata:
-    move_id: str
-    label: str
-    description: str
-    duration: float
-    created_at: float
-    json_path: Path
-    has_audio: bool
-    has_noise_profile: bool
-    has_denoised_audio: bool
-    is_uploaded: bool = False
-    audio_only: bool = False
-
-    def to_payload(self) -> dict[str, Any]:
-        return {
-            "id": self.move_id,
-            "label": self.label,
-            "duration": self.duration,
-            "created_at": self.created_at,
-            "has_audio": self.has_audio,
-            "description": self.description,
-            "has_noise_profile": self.has_noise_profile,
-            "has_denoised_audio": self.has_denoised_audio,
-            "is_uploaded": self.is_uploaded,
-            "audio_only": self.audio_only,
-        }
-
-
-@dataclass
-class RecordingRequest:
-    move_id: str
-    label: str
-    description: str
-    duration: float
-    record_audio: bool
-    record_motion: bool = True
-    uploaded_audio_path: Path | None = None
-
-
-@dataclass
-class DatasetEntry:
-    dataset_id: str
-    label: str
-    folder: str
-    path: Path
-    uploaded_move_ids: set[str] | None = None
-    origin: str = "local"  # "local" or "downloaded"
-
-    def __post_init__(self) -> None:
-        if self.uploaded_move_ids is None:
-            self.uploaded_move_ids = set()
-
-    def to_payload(self) -> dict[str, Any]:
-        return {
-            "id": self.dataset_id,
-            "label": self.label,
-            "path": str(self.path),
-            "folder": self.folder,
-            "origin": self.origin,
-        }
-
-
-class StartRecordingPayload(BaseModel):
-    duration: float = Field(DEFAULT_DURATION, gt=0.5, le=300.0)
-    record_audio: bool = Field(default=True)
-    record_motion: bool = Field(default=True, description="When False, record audio only (no motion capture)")
-    label: str | None = Field(default=None, max_length=80)
-    description: str | None = Field(default=None, max_length=500)
-    uploaded_audio_id: str | None = Field(default=None, description="ID of previously uploaded audio file")
-
-
-class PlayMovePayload(BaseModel):
-    move_id: str = Field(..., description="Move identifier (filename stem)")
-
-
-class CreateDatasetPayload(BaseModel):
-    name: str = Field(..., description="Folder name for the dataset", min_length=1, max_length=80)
-    label: str | None = Field(default=None, max_length=80)
-
-
-class SelectDatasetPayload(BaseModel):
-    dataset_id: str
-
-
-class SyncDatasetPayload(BaseModel):
-    move_ids: list[str] = Field(..., min_items=1, description="Subset of moves to publish")
-    hf_username: str | None = Field(default=None, min_length=2, max_length=80)
-    dataset_slug: str | None = Field(
-        default=None, description="Optional override for the Hugging Face dataset slug"
-    )
-
-
-class UpdateDatasetRootPayload(BaseModel):
-    path: str = Field(..., description="Filesystem directory containing all datasets")
-
-
-class DownloadDatasetPayload(BaseModel):
-    repo_id: str = Field(..., description="Hugging Face dataset repository, e.g. user/name")
-    label: str | None = Field(default=None, max_length=80)
-    name: str | None = Field(
-        default=None,
-        description="Optional folder name; defaults to the dataset slug",
-        max_length=80,
-    )
-
-
-class UpdateLeadCompensationPayload(BaseModel):
-    lead_frames_head: int | None = Field(
-        default=None, ge=0, le=2000, description="Look-ahead for head/body in 100Hz frames"
-    )
-    lead_frames_antennas: int | None = Field(
-        default=None, ge=0, le=2000, description="Look-ahead for antennas in 100Hz frames"
-    )
-
-
-class UpdateExperimentsPayload(BaseModel):
-    duration_seconds: float | None = Field(default=None, gt=0.5, le=300.0)
-    welcome_messages: int | None = Field(default=None, ge=0, le=2, description="Number of welcome messages at startup (0, 1, or 2)")
-
-
-class HfTokenPayload(BaseModel):
-    token: str = Field(..., min_length=5, description="Hugging Face access token (starts with hf_)")
-
-
-class Marionette(ReachyMiniApp):
-    """Manual Marionette recorder for Reachy Mini."""
-
-    custom_app_url: str | None = "http://0.0.0.0:8042"
-
-    def __init__(
-        self,
-        registry_path: Path | None = None,
-        dataset_root: Path | None = None,
-    ) -> None:
-        super().__init__()
-        self._registry_path = registry_path or (
-            Path(__file__).resolve().parent.parent / DATASET_REGISTRY_FILENAME
-        )
-        self._dataset_root_override = dataset_root
-        self._datasets: dict[str, DatasetEntry] = {}
-        self._active_dataset_id: str | None = None
-        self._dataset_root: Path
-        self._dataset_dir: Path
-        self._motion_model_registry = MotionModelRegistry()
-        self._preferred_duration: float = DEFAULT_DURATION
-        self._welcome_messages: int = 2  # 0=none, 1=intro only, 2=intro+second
-        self._load_dataset_registry()  # may overwrite _preferred_duration and _welcome_messages
-
-        self._recordings: dict[str, RecordingMetadata] = {}
-        self._pending_recording: RecordingRequest | None = None
-        self._pending_playback: str | None = None
-        self._uploaded_audio: dict[str, Path] = {}  # upload_id -> temp file path
-        self._playback_cancel_event = threading.Event()
-        self._recording_cancel_event = threading.Event()
-        self._mode: str = "idle"
-        self._message: str = "Ready to capture moves"
-        self._countdown_ends_at: float | None = None
-        self._active_record_started_at: float | None = None
-        self._active_record_duration: float | None = None
-        self._active_move: str | None = None
-        self._state_lock = threading.Lock()
-        self._audio_available = sf is not None
-        self._recording_stats: dict[str, Any] | None = None
-        self._hf_username: str | None = None
-        self._hf_checked = False
-
-        self._refresh_recordings()
-        print(f"[BOOT] __init__ done at +{time.perf_counter() - _BOOT_T0:.2f}s after module import", flush=True)
-        logger.info("Marionette v%s starting on %s (%s)", __version__, platform.node(), platform.system())
-        if self.settings_app is not None:
-            self._register_routes()
-
-    # ──────── FastAPI routes ────────────────────────────────────────────
-    def _register_routes(self) -> None:
-        assert self.settings_app is not None
-
-        @self.settings_app.get("/api/state")
-        def get_state() -> dict[str, Any]:
-            return self._serialize_state()
-
-        @self.settings_app.get("/api/version")
-        def get_version() -> dict[str, str]:
-            return {"version": __version__, "platform": platform.system(), "hostname": platform.node()}
-
-        # Dummy endpoint to silence 404 spam from external tools
-        @self.settings_app.get("/sensor_data")
-        def sensor_data() -> dict[str, Any]:
-            return {}
-
-        @self.settings_app.post("/api/upload-audio")
-        async def upload_audio(file: UploadFile = File(...)) -> dict[str, Any]:
-            if not file.filename:
-                raise HTTPException(status_code=400, detail="No file provided.")
-            ext = Path(file.filename).suffix.lower()
-            if ext not in {".wav", ".mp3"}:
-                raise HTTPException(
-                    status_code=400,
-                    detail=f"Unsupported audio format '{ext}'. Use .wav or .mp3.",
-                )
-            upload_id = str(uuid.uuid4())
-            temp_dir = Path(__file__).resolve().parent.parent / "temp_uploads"
-            temp_dir.mkdir(parents=True, exist_ok=True)
-            temp_path = temp_dir / f"{upload_id}{ext}"
-            try:
-                content = await file.read()
-                temp_path.write_bytes(content)
-            except Exception as exc:
-                raise HTTPException(status_code=500, detail=f"Failed to save upload: {exc}") from exc
-
-            # Convert MP3 to WAV for better playback quality
-            duration: float | None = None
-            if ext == ".mp3" and sf is not None:
-                try:
-                    data, samplerate = sf.read(str(temp_path))
-                    wav_path = temp_dir / f"{upload_id}.wav"
-                    # Resample to 48kHz for better quality (common output rate)
-                    target_rate = 48000
-                    if samplerate != target_rate:
-                        try:
-                            from scipy import signal
-                            original_rate = samplerate
-                            num_samples = int(len(data) * target_rate / samplerate)
-                            if data.ndim == 1:
-                                data = signal.resample(data, num_samples)
-                            else:
-                                data = signal.resample(data, num_samples, axis=0)
-                            samplerate = target_rate
-                            logger.info("Resampled audio from %d to %d Hz", original_rate, target_rate)
-                        except ImportError:
-                            logger.warning("scipy not available, skipping resample")
-                    # Write as 16-bit PCM WAV for maximum compatibility
-                    sf.write(str(wav_path), data, samplerate, subtype='PCM_16')
-                    duration = len(data) / samplerate
-                    # Remove original MP3 and use WAV
-                    temp_path.unlink()
-                    temp_path = wav_path
-                    logger.info("Converted MP3 to WAV: %s", wav_path.name)
-                except Exception as exc:
-                    logger.warning("MP3 to WAV conversion failed, using original: %s", exc)
-
-            # Get audio duration if not already determined
-            if duration is None and sf is not None:
-                try:
-                    info = sf.info(str(temp_path))
-                    duration = float(info.duration)
-                except Exception as exc:
-                    logger.warning("Could not determine audio duration: %s", exc)
-
-            self._uploaded_audio[upload_id] = temp_path
-            return {"upload_id": upload_id, "filename": file.filename, "duration": duration}
-
-        @self.settings_app.post("/api/record")
-        def start_recording(payload: StartRecordingPayload) -> dict[str, Any]:
-            uploaded_audio_path: Path | None = None
-            if payload.uploaded_audio_id:
-                uploaded_audio_path = self._uploaded_audio.get(payload.uploaded_audio_id)
-                if not uploaded_audio_path or not uploaded_audio_path.exists():
-                    raise HTTPException(
-                        status_code=400,
-                        detail="Uploaded audio file not found. Please re-upload.",
-                    )
-            elif payload.record_audio and not self._audio_available:
-                raise HTTPException(
-                    status_code=400,
-                    detail="Audio capture backend unavailable.",
-                )
-
-            active_entry = self._datasets.get(self._active_dataset_id or "")
-            if active_entry and active_entry.origin == "downloaded":
-                raise HTTPException(
-                    status_code=409,
-                    detail="Cannot record into a downloaded dataset. Switch to a local dataset or create a new one.",
-                )
-
-            request = self._build_recording_request(payload, uploaded_audio_path)
-
-            with self._state_lock:
-                if (
-                    self._mode not in {"idle", "queued"}
-                    or self._pending_recording
-                    or self._pending_playback
-                ):
-                    raise HTTPException(status_code=409, detail="Robot is busy.")
-                self._preferred_duration = float(request.duration)
-                self._pending_recording = request
-                self._mode = "queued"
-                self._message = "Recording scheduled"
-                self._countdown_ends_at = None
-                self._active_record_started_at = None
-                self._active_record_duration = None
-                self._save_dataset_registry()
-
-            return {
-                "accepted": True,
-                "move_id": request.move_id,
-                "label": request.label,
-            }
-
-        @self.settings_app.post("/api/play")
-        def play_move(payload: PlayMovePayload) -> dict[str, Any]:
-            if payload.move_id not in self._recordings:
-                raise HTTPException(status_code=404, detail="Move not found.")
-
-            with self._state_lock:
-                if (
-                    self._mode != "idle"
-                    or self._pending_recording
-                    or self._pending_playback
-                ):
-                    raise HTTPException(status_code=409, detail="Robot is busy.")
-                self._pending_playback = payload.move_id
-                self._mode = "queued"
-                self._message = f"Playback queued for {payload.move_id}"
-
-            return {"accepted": True, "move_id": payload.move_id}
-
-        @self.settings_app.post("/api/play/stop")
-        def stop_playback() -> dict[str, Any]:
-            with self._state_lock:
-                if self._mode != "playing":
-                    return {"stopped": False, "reason": "not_playing"}
-                self._playback_cancel_event.set()
-            return {"stopped": True}
-
-        @self.settings_app.post("/api/record/stop")
-        def stop_recording() -> dict[str, Any]:
-            with self._state_lock:
-                if self._mode not in {"recording", "countdown", "queued"}:
-                    return {"stopped": False, "reason": "not_recording"}
-                if self._mode == "queued":
-                    self._pending_recording = None
-                    self._mode = "idle"
-                    self._message = "Recording cancelled"
-                    return {"stopped": True}
-                self._recording_cancel_event.set()
-            return {"stopped": True}
-
-        @self.settings_app.delete("/api/moves/{move_id}")
-        def delete_move(move_id: str) -> dict[str, Any]:
-            self._delete_move_files(move_id)
-            self._refresh_recordings()
-            return {"status": "deleted", "move_id": move_id}
-
-        @self.settings_app.get("/api/datasets")
-        def list_datasets() -> dict[str, Any]:
-            return self._datasets_payload()
-
-        @self.settings_app.post("/api/datasets")
-        def create_dataset(payload: CreateDatasetPayload) -> dict[str, Any]:
-            with self._state_lock:
-                if (
-                    self._mode not in {"idle", "queued"}
-                    or self._pending_recording
-                    or self._pending_playback
-                ):
-                    raise HTTPException(status_code=409, detail="Robot is busy.")
-                entry = self._create_dataset(payload.name, payload.label)
-                self._select_dataset(entry.dataset_id)
-            self._refresh_recordings()
-            return {"status": "created", "dataset": entry.to_payload()}
-
-        @self.settings_app.post("/api/datasets/select")
-        def select_dataset(payload: SelectDatasetPayload) -> dict[str, Any]:
-            with self._state_lock:
-                if (
-                    self._mode not in {"idle", "queued"}
-                    or self._pending_recording
-                    or self._pending_playback
-                ):
-                    raise HTTPException(status_code=409, detail="Robot is busy.")
-                self._select_dataset(payload.dataset_id)
-            self._refresh_recordings()
-            return {"status": "selected", "active_id": payload.dataset_id}
-
-        @self.settings_app.post("/api/datasets/sync")
-        def sync_dataset(payload: SyncDatasetPayload) -> dict[str, Any]:
-            with self._state_lock:
-                if (
-                    self._mode not in {"idle", "queued"}
-                    or self._pending_recording
-                    or self._pending_playback
-                ):
-                    raise HTTPException(status_code=409, detail="Robot is busy.")
-            username = payload.hf_username or self._check_hf_login()
-            if not username:
-                raise HTTPException(
-                    status_code=400,
-                    detail="No Hugging Face username provided and not logged in via CLI.",
-                )
-            result = self._sync_dataset(username, payload.move_ids, payload.dataset_slug)
-            return result
-
-        @self.settings_app.post("/api/datasets/root")
-        def update_dataset_root(payload: UpdateDatasetRootPayload) -> dict[str, Any]:
-            with self._state_lock:
-                if (
-                    self._mode not in {"idle", "queued"}
-                    or self._pending_recording
-                    or self._pending_playback
-                ):
-                    raise HTTPException(status_code=409, detail="Robot is busy.")
-                self._set_dataset_root(payload.path)
-            self._refresh_recordings()
-            return {"status": "updated", "root_path": str(self._dataset_root)}
-
-        @self.settings_app.get("/api/datasets/community")
-        def community_datasets() -> dict[str, Any]:
-            datasets = self._list_community_datasets()
-            return {"datasets": datasets}
-
-        @self.settings_app.post("/api/datasets/download")
-        def download_dataset(payload: DownloadDatasetPayload) -> dict[str, Any]:
-            with self._state_lock:
-                if self._mode not in {"idle", "queued"} or self._pending_recording or self._pending_playback:
-                    raise HTTPException(status_code=409, detail="Robot is busy.")
-            entry = self._download_community_dataset(payload)
-            self._refresh_recordings()
-            return {"status": "downloaded", "dataset": entry.to_payload()}
-
-        @self.settings_app.post("/api/experiments")
-        def update_experiments(payload: UpdateExperimentsPayload) -> dict[str, Any]:
-            updates = payload.dict(exclude_none=True)
-            if not updates:
-                return {"status": "unchanged"}
-            with self._state_lock:
-                for key, value in updates.items():
-                    if key == "duration_seconds":
-                        self._preferred_duration = float(value)
-                    elif key == "welcome_messages":
-                        self._welcome_messages = max(0, min(2, int(value)))
-                self._save_dataset_registry()
-            return {
-                "status": "updated",
-                "preferred_duration": self._preferred_duration,
-                "motion_models": self._motion_model_registry.to_payload(),
-            }
-
-        @self.settings_app.post("/api/motion-model/lead")
-        def update_motion_model_lead(payload: UpdateLeadCompensationPayload) -> dict[str, Any]:
-            params = payload.dict(exclude_none=True)
-            if not params:
-                return {
-                    "status": "unchanged",
-                    "active": self._motion_model_registry.active,
-                    "params": self._motion_model_registry.get_model_params("lead_compensation"),
-                }
-            try:
-                self._motion_model_registry.set_model_params("lead_compensation", params)
-            except KeyError as exc:
-                raise HTTPException(status_code=404, detail="Lead compensation model unavailable.") from exc
-            self._save_dataset_registry()
-            return {
-                "status": "updated",
-                "active": self._motion_model_registry.active,
-                "params": self._motion_model_registry.get_model_params("lead_compensation"),
-            }
-
-        @self.settings_app.post("/api/hf-auth/save-token")
-        def save_hf_token(payload: HfTokenPayload) -> dict[str, Any]:
-            if hf_login is None:
-                raise HTTPException(status_code=500, detail="huggingface_hub is not installed.")
-            token = payload.token.strip()
-            if not token.startswith("hf_"):
-                raise HTTPException(status_code=422, detail="Token must start with 'hf_'.")
-            try:
-                hf_login(token=token, add_to_git_credential=False)
-            except Exception as exc:
-                raise HTTPException(status_code=401, detail=f"Invalid token: {exc}") from exc
-            # Verify the token works
-            self._hf_checked = False
-            username = self._check_hf_login()
-            if not username:
-                raise HTTPException(status_code=401, detail="Token saved but could not verify identity.")
-            return {"status": "logged_in", "username": username}
-
-        @self.settings_app.delete("/api/hf-auth/token")
-        def delete_hf_token() -> dict[str, Any]:
-            if hf_logout is None:
-                raise HTTPException(status_code=500, detail="huggingface_hub is not installed.")
-            try:
-                hf_logout()
-            except Exception as exc:
-                logger.warning("HF logout error: %s", exc)
-            self._hf_username = None
-            self._hf_checked = False
-            return {"status": "logged_out"}
-
-    # ──────── Main loop ────────────────────────────────────────────────
-    @staticmethod
-    def _get_audio_duration(path: Path, fallback: float = 3.0) -> float:
-        if sf is not None:
-            try:
-                info = sf.info(str(path))
-                return float(info.duration)
-            except Exception:
-                pass
-        return fallback
-
-    @staticmethod
-    def _play_wav_chunked(
-        reachy_mini: ReachyMini,
-        wav_path: Path,
-        stop_event: threading.Event,
-        chunk_duration: float = 0.02,
-    ) -> None:
-        """Play a WAV file via push_audio_sample() so it can be stopped at any time.
-
-        Unlike play_sound() which creates an orphan GStreamer pipeline that
-        cannot be interrupted, this loads the WAV, resamples to the output
-        rate, and pushes small chunks through the stoppable playback pipeline.
-        """
-        if sf is None:
-            return
-        try:
-            data, sr = sf.read(str(wav_path), dtype="float32")
-        except Exception as exc:
-            logger.warning("Failed to read %s: %s", wav_path, exc)
-            return
-
-        if data.ndim == 2:
-            data = data.mean(axis=1)
-
-        # Resample if the file's rate doesn't match the output device.
-        try:
-            sr_out = int(reachy_mini.media.get_output_audio_samplerate() or 16000)
-        except Exception:
-            sr_out = 16000
-        if sr != sr_out:
-            try:
-                from scipy.signal import resample
-
-                num_samples = int(len(data) * sr_out / sr)
-                data = resample(data, num_samples).astype(np.float32)
-                sr = sr_out
-            except Exception as exc:
-                logger.warning("Resample failed: %s — playing at original rate", exc)
-
-        reachy_mini.media.start_playing()
-
-        samples_per_chunk = max(1, int(sr * chunk_duration))
-        play_start = time.perf_counter()
-        try:
-            for offset in range(0, len(data), samples_per_chunk):
-                if stop_event.is_set():
-                    break
-                chunk = data[offset : offset + samples_per_chunk]
-                reachy_mini.media.push_audio_sample(chunk)
-                # Sleep slightly less than chunk duration to keep buffer fed
-                stop_event.wait(chunk_duration * 0.8)
-            else:
-                # All chunks pushed — wait for the audio buffer to drain.
-                # We pushed ~20% faster than real-time, so the playback
-                # pipeline still has buffered audio to play out.
-                audio_duration = len(data) / sr
-                elapsed = time.perf_counter() - play_start
-                remaining = audio_duration - elapsed
-                if remaining > 0:
-                    stop_event.wait(remaining)
-        finally:
-            # stop_playing() can hang on some audio backends (GStreamer's
-            # set_state(NULL) blocks when the device is slow or the MainLoop
-            # is starved).  Run it in a daemon thread with a timeout so we
-            # never block the caller indefinitely.
-            try:
-                t = threading.Thread(
-                    target=reachy_mini.media.stop_playing, daemon=True
-                )
-                t.start()
-                t.join(2.0)
-                if t.is_alive():
-                    logger.warning(
-                        "stop_playing() did not complete within 2s — abandoning"
-                    )
-            except Exception:
-                pass
-
-    @staticmethod
-    def _preload_wav(wav_path: Path, target_sr: int | None = None) -> tuple[np.ndarray, int] | None:
-        """Read a WAV file, returning (data, sample_rate) or None.
-
-        If target_sr is given and differs from the file's rate, resample.
-        """
-        if sf is None:
-            return None
-        try:
-            data, sr = sf.read(str(wav_path), dtype="float32")
-        except Exception as exc:
-            logger.warning("Failed to read %s: %s", wav_path, exc)
-            return None
-        if data.ndim == 2:
-            data = data.mean(axis=1)
-        if target_sr and sr != target_sr:
-            try:
-                from scipy.signal import resample
-
-                num_samples = int(len(data) * target_sr / sr)
-                data = resample(data, num_samples).astype(np.float32)
-                sr = target_sr
-            except Exception as exc:
-                logger.warning("Resample failed: %s — using original rate", exc)
-        return data, sr
-
-    @staticmethod
-    def _play_preloaded_wav(
-        reachy_mini: ReachyMini,
-        wav_data: tuple[np.ndarray, int],
-        stop_event: threading.Event,
-        chunk_duration: float = 0.02,
-        pipeline_ready: bool = False,
-        start_signal: threading.Event | None = None,
-    ) -> None:
-        """Push preloaded WAV data through the playback pipeline."""
-        data, sr = wav_data
-        if not pipeline_ready:
-            reachy_mini.media.start_playing()
-        # If a start_signal is provided, wait until the caller says go
-        # (e.g. after the first motion command is sent).
-        if start_signal is not None:
-            start_signal.wait(timeout=5.0)
-        samples_per_chunk = max(1, int(sr * chunk_duration))
-        play_start = time.perf_counter()
-        try:
-            for offset in range(0, len(data), samples_per_chunk):
-                if stop_event.is_set():
-                    break
-                chunk = data[offset : offset + samples_per_chunk]
-                reachy_mini.media.push_audio_sample(chunk)
-                stop_event.wait(chunk_duration * 0.8)
-            else:
-                audio_duration = len(data) / sr
-                elapsed = time.perf_counter() - play_start
-                remaining = audio_duration - elapsed
-                if remaining > 0:
-                    stop_event.wait(remaining)
-        finally:
-            try:
-                t = threading.Thread(
-                    target=reachy_mini.media.stop_playing, daemon=True
-                )
-                t.start()
-                t.join(2.0)
-                if t.is_alive():
-                    logger.warning(
-                        "stop_playing() did not complete within 2s — abandoning"
-                    )
-            except Exception:
-                pass
-
-    def _run_startup_animation(
-        self, reachy_mini: ReachyMini, stop_event: threading.Event
-    ) -> None:
-        """Startup greeting with configurable welcome messages.
-
-        Behaviour depends on self._welcome_messages (0, 1, or 2):
-          0 messages — head up, head down, release torque (silent)
-          1 message  — head up, play intro, head down, release torque
-          2 messages — head up, play intro, head down, pause, head semi-up,
-                       play second message, release torque (full greeting)
-
-        Uses stop_event.wait() instead of time.sleep() so the startup
-        can be interrupted cleanly if the app is shutting down.
-        """
-        self._set_state(mode="starting_up", message="Starting up…", active_move=None)
-        assets = Path(__file__).parent / "assets"
-        n_messages = self._welcome_messages
-        _anim_t0 = time.perf_counter()
-
-        # Step 1: Head up (all modes)
-        self._safe_enable_motors(reachy_mini)
-        print(f"[BOOT] anim: enable_motors done at +{time.perf_counter() - _BOOT_T0:.2f}s", flush=True)
-        self._goto_pose_scaled(
-            reachy_mini,
-            INIT_HEAD_POSE,
-            antennas=[0.0, 0.0],
-            min_duration=0.2,
-        )
-        print(f"[BOOT] anim: head-up done at +{time.perf_counter() - _BOOT_T0:.2f}s", flush=True)
-
-        if stop_event.is_set():
-            return
-
-        # Step 2: Play intro sound (1 or 2 messages)
-        if n_messages >= 1:
-            intro_path = assets / "intro_marionette.wav"
-            if intro_path.exists() and not stop_event.is_set():
-                try:
-                    self._play_wav_chunked(reachy_mini, intro_path, stop_event)
-                except Exception as exc:
-                    logger.warning("Failed to play intro sound: %s", exc)
-            print(f"[BOOT] anim: intro sound done at +{time.perf_counter() - _BOOT_T0:.2f}s", flush=True)
-
-        if stop_event.is_set():
-            return
-
-        # Step 3: Head down + release torque (all modes)
-        self._goto_sleep_and_release(reachy_mini)
-
-        if stop_event.is_set():
-            return
-
-        # Step 4: Second message with semi-awaken pose (2 messages only)
-        if n_messages >= 2:
-            second_path = assets / "please.wav"
-            if second_path.exists() and not stop_event.is_set():
-                # Preload wav during the pause so playback starts immediately.
-                wav_data = self._preload_wav(second_path)
-                #stop_event.wait(0.5)
-                if stop_event.is_set():
-                    return
-                self._safe_enable_motors(reachy_mini)
-                antenna_angle = np.deg2rad(15)
-                # Start audio and head rise simultaneously.
-                audio_stop = threading.Event()
-                audio_thread: threading.Thread | None = None
-                if wav_data is not None:
-                    audio_thread = threading.Thread(
-                        target=self._play_preloaded_wav,
-                        args=(reachy_mini, wav_data, audio_stop),
-                        daemon=True,
-                    )
-                    audio_thread.start()
-                reachy_mini.goto_target(
-                    SEMI_AWAKEN_POSE,
-                    antennas=[-antenna_angle, antenna_angle],
-                    duration=0.3,
-                )
-                if audio_thread is not None:
-                    audio_thread.join(timeout=10.0)
-                    audio_stop.set()
-                self._goto_sleep_and_release(reachy_mini)
-
-    def _disable_mic_agc(self) -> None:
-        """Disable the mic's automatic gain control for cleaner recordings.
-
-        The XMOS XVF3800 AGC scales sensitivity to avoid saturation, but
-        this causes the mic to "mute" when motors are loud.  We disable
-        AGC on startup and restore the original value on shutdown.
-        """
-        try:
-            from reachy_mini.media.audio_control_utils import init_respeaker_usb
-        except ImportError:
-            logger.debug("audio_control_utils not available, skipping AGC config")
-            return
-
-        try:
-            respeaker = init_respeaker_usb()
-            if respeaker is None:
-                logger.debug("No ReSpeaker USB device found, skipping AGC config")
-                return
-            self._original_agc = respeaker.read("PP_AGCONOFF")
-            respeaker.write("PP_AGCONOFF", [0])
-            respeaker.close()
-            logger.info("Mic AGC disabled (was %s)", self._original_agc)
-        except Exception as exc:
-            logger.warning("Failed to disable mic AGC: %s", exc)
-
-    def _restore_mic_agc(self) -> None:
-        """Restore the mic AGC to its original value."""
-        if not hasattr(self, "_original_agc") or self._original_agc is None:
-            return
-        try:
-            from reachy_mini.media.audio_control_utils import init_respeaker_usb
-
-            respeaker = init_respeaker_usb()
-            if respeaker is None:
-                return
-            respeaker.write("PP_AGCONOFF", self._original_agc)
-            respeaker.close()
-            logger.info("Mic AGC restored to %s", self._original_agc)
-        except Exception as exc:
-            logger.warning("Failed to restore mic AGC: %s", exc)
-
-    def run(self, reachy_mini: ReachyMini, stop_event: threading.Event) -> None:
-        try:
-            _run_t0 = time.perf_counter()
-            print(f"[BOOT] run() entered at +{_run_t0 - _BOOT_T0:.2f}s after module import", flush=True)
-            self._disable_mic_agc()
-            print(f"[BOOT] _disable_mic_agc done at +{time.perf_counter() - _BOOT_T0:.2f}s", flush=True)
-            self._run_startup_animation(reachy_mini, stop_event)
-            print(f"[BOOT] startup animation done at +{time.perf_counter() - _BOOT_T0:.2f}s", flush=True)
-            self._set_idle_state()
-
-            while not stop_event.is_set():
-                job_type: str | None = None
-                payload: RecordingRequest | str | None = None
-
-                with self._state_lock:
-                    if self._pending_recording is not None:
-                        job_type = "record"
-                        payload = self._pending_recording
-                        self._pending_recording = None
-                    elif self._pending_playback is not None:
-                        job_type = "play"
-                        payload = self._pending_playback
-                        self._pending_playback = None
-
-                if job_type == "record" and isinstance(payload, RecordingRequest):
-                    self._perform_recording(reachy_mini, stop_event, payload)
-                    self._set_idle_state()
-                elif job_type == "play" and isinstance(payload, str):
-                    self._perform_playback(reachy_mini, payload)
-                    self._set_idle_state()
-                    self._align_head_and_release(reachy_mini)
-                else:
-                    stop_event.wait(0.05)
-        finally:
-            self._restore_mic_agc()
-            self._park_robot(reachy_mini)
-
-    # ──────── Robot actions ────────────────────���────────────────────────
-    def _perform_recording(
-        self,
-        reachy_mini: ReachyMini,
-        stop_event: threading.Event,
-        request: RecordingRequest,
-    ) -> None:
-        self._recording_cancel_event.clear()
-        countdown_end = time.time() + COUNTDOWN_SECONDS
-        self._set_state(
-            mode="countdown",
-            message=f"Recording {request.label} in {COUNTDOWN_SECONDS}s",
-            active_move=request.label,
-            countdown_ends_at=countdown_end,
-        )
-
-        while time.time() < countdown_end:
-            if stop_event.wait(0.1) or self._recording_cancel_event.is_set():
-                self._recording_cancel_event.clear()
-                self._set_state(mode="idle", message="Recording cancelled", active_move=None)
-                return
-
-        with self._state_lock:
-            self._recording_stats = None
-
-        self._set_state(
-            mode="recording",
-            message=f"Recording {request.label}",
-            active_move=request.move_id,
-            recording_started_at=time.time(),
-            recording_duration=request.duration,
-        )
-
-        try:
-            self._run_capture_and_save(reachy_mini, stop_event, request)
-        except Exception as exc:
-            logger.error("Recording failed: %s", exc, exc_info=True)
-            self._set_state(
-                mode="error",
-                message=f"Recording error: {exc}",
-                active_move=None,
-            )
-
-    def _run_capture_and_save(
-        self,
-        reachy_mini: ReachyMini,
-        stop_event: threading.Event,
-        request: RecordingRequest,
-    ) -> None:
-        """Inner recording logic, wrapped by _perform_recording's safety net."""
-        # For uploaded-audio sessions, preload and prime the playback pipeline,
-        # then gate audio start on the exact capture start instant.
-        audio_stop = threading.Event()
-        audio_start = threading.Event()
-        audio_thread: threading.Thread | None = None
-        if request.uploaded_audio_path and request.uploaded_audio_path.exists():
-            try:
-                sr_out = int(reachy_mini.media.get_output_audio_samplerate() or 16000)
-            except Exception:
-                sr_out = 16000
-            wav_data = self._preload_wav(request.uploaded_audio_path, target_sr=sr_out)
-            if wav_data is not None:
-                reachy_mini.media.start_playing()
-                audio_thread = threading.Thread(
-                    target=self._play_preloaded_wav,
-                    args=(reachy_mini, wav_data, audio_stop),
-                    kwargs={"pipeline_ready": True, "start_signal": audio_start},
-                    daemon=True,
-                )
-                audio_thread.start()
-
-        # When using uploaded audio, don't record from mic (audio comes from the file)
-        should_record_mic = request.record_audio and not request.uploaded_audio_path
-        try:
-            timestamps, frames, audio_frames, audio_samplerate = self._capture_motion(
-                reachy_mini, stop_event, request.duration, should_record_mic,
-                record_motion=request.record_motion,
-                on_capture_start=(audio_start.set if audio_thread is not None else None),
-            )
-        finally:
-            # Signal the audio thread to stop and wait briefly
-            audio_stop.set()
-            if audio_thread is not None:
-                audio_thread.join(timeout=3.0)
-
-        # Check if recording was cancelled
-        was_cancelled = self._recording_cancel_event.is_set()
-        self._recording_cancel_event.clear()
-
-        if not timestamps:
-            self._set_state(
-                mode="idle",
-                message="Recording cancelled" if was_cancelled else "No motion data captured.",
-                active_move=None,
-            )
-            return
-
-        # Save the recording (even if partial due to early stop)
-        self._save_recording(request, timestamps, frames, audio_frames, audio_samplerate)
-        self._refresh_recordings()
-        pose_count = len(frames)
-        duration_elapsed = timestamps[-1] if timestamps else request.duration
-        duration_elapsed = max(duration_elapsed, 1e-6)
-        poses_per_sec = pose_count / duration_elapsed
-        with self._state_lock:
-            self._recording_stats = {
-                "poses": pose_count,
-                "duration": duration_elapsed,
-                "poses_per_second": poses_per_sec,
-            }
-        if not request.record_motion:
-            status_msg = f"Recorded audio: {request.label} ({duration_elapsed:.1f}s)"
-            if was_cancelled:
-                status_msg = f"Saved audio: {request.label} (stopped early, {duration_elapsed:.1f}s)"
-        else:
-            status_msg = f"Recorded {request.label} • {pose_count} poses ({poses_per_sec:.1f}/s)"
-            if was_cancelled:
-                status_msg = f"Saved {request.label} (stopped early) • {pose_count} poses"
-        self._set_state(
-            mode="idle",
-            message=status_msg,
-            active_move=None,
-        )
-        if not was_cancelled:
-            self._preferred_duration = request.duration
-
-    def _perform_playback(self, reachy_mini: ReachyMini, move_id: str) -> None:
-        meta = self._recordings.get(move_id)
-        if not meta:
-            self._set_state(mode="error", message=f"Move {move_id} missing.", active_move=None)
-            return
-
-        try:
-            move = self._load_move(meta.json_path)
-        except Exception as exc:  # pragma: no cover - filesystem failure
-            self._set_state(
-                mode="error",
-                message=f"Failed to load {move_id}: {exc}",
-                active_move=None,
-            )
-            return
-
-        # Audio-only moves: just play the audio, no motion replay
-        if meta.audio_only:
-            self._playback_cancel_event.clear()
-            self._set_state(
-                mode="playing",
-                message=f"Playing audio: {meta.label}",
-                active_move=meta.move_id,
-            )
-            if move.sound_path is not None:
-                try:
-                    self._play_wav_chunked(
-                        reachy_mini, move.sound_path, self._playback_cancel_event,
-                    )
-                except Exception:
-                    pass
-            cancelled = self._playback_cancel_event.is_set()
-            self._playback_cancel_event.clear()
-            msg = f"Playback stopped for {meta.label}" if cancelled else f"Finished playing {meta.label}"
-            self._set_state(mode="idle", message=msg, active_move=None)
-            return
-
-        move_to_play = self._apply_motion_model(move)
-
-        self._playback_cancel_event.clear()
-        self._set_state(
-            mode="playing",
-            message=f"Playing {meta.label}",
-            active_move=meta.move_id,
-        )
-
-        self._safe_enable_motors(reachy_mini)
-        cancelled = False
-
-        # Preload audio (including resample) while we go to the start pose,
-        # so playback can begin instantly when motion starts.
-        try:
-            sr_out = int(reachy_mini.media.get_output_audio_samplerate() or 16000)
-        except Exception:
-            sr_out = 16000
-        wav_data: tuple[np.ndarray, int] | None = None
-        if move_to_play.sound_path is not None:
-            wav_data = self._preload_wav(move_to_play.sound_path, target_sr=sr_out)
-
-        # Move to the start pose BEFORE starting audio so they begin in sync.
-        try:
-            start_head_pose, start_antennas, start_body_yaw = move_to_play.evaluate(0.0)
-        except Exception:
-            self._set_state(mode="error", message="Failed to evaluate move start pose", active_move=None)
-            return
-        self._goto_pose_scaled(
-            reachy_mini,
-            start_head_pose,
-            antennas=list(start_antennas) if start_antennas is not None else None,
-            min_duration=0.2,
-        )
-        if start_body_yaw is not None:
-            reachy_mini.set_target_body_yaw(float(start_body_yaw))
-
-        # Warm the audio pipeline, then let the audio thread wait for the
-        # motion loop to send its first command before pushing audio.
-        audio_stop = threading.Event()
-        audio_start = threading.Event()
-        audio_thread: threading.Thread | None = None
-        if wav_data is not None:
-            reachy_mini.media.start_playing()
-            audio_thread = threading.Thread(
-                target=self._play_preloaded_wav,
-                args=(reachy_mini, wav_data, audio_stop),
-                kwargs={"pipeline_ready": True, "start_signal": audio_start},
-                daemon=True,
-            )
-            audio_thread.start()
-        try:
-            cancelled = not self._stream_playback(
-                reachy_mini, move_to_play, start_signal=audio_start,
-            )
-        finally:
-            self._playback_cancel_event.clear()
-            audio_stop.set()
-            if audio_thread is not None:
-                audio_thread.join(timeout=3.0)
-
-        if cancelled:
-            self._set_state(
-                mode="idle",
-                message=f"Playback stopped for {meta.label}",
-                active_move=None,
-            )
-        else:
-            self._set_state(
-                mode="idle",
-                message=f"Finished playing {meta.label}",
-                active_move=None,
-            )
-
-    @staticmethod
-    def _call_with_timeout(fn: Callable, timeout: float = 2.0, retries: int = 2) -> bool:
-        """Call fn() in a daemon thread with timeout and retries.
-
-        GStreamer's set_state() can hang when the audio device is slow or the
-        GLib MainLoop is starved.  We run the call in a disposable daemon thread
-        and retry up to `retries` times — often the second attempt succeeds
-        because the MainLoop has had time to process pending bus messages.
-
-        Returns True if the call completed within the timeout, False if all
-        attempts timed out (the last thread is abandoned as a daemon).
-        """
-        for attempt in range(1, retries + 1):
-            t = threading.Thread(target=fn, daemon=True)
-            t.start()
-            t.join(timeout)
-            if not t.is_alive():
-                return True
-            logger.warning(
-                "%s attempt %d/%d did not complete within %.1fs",
-                fn, attempt, retries, timeout,
-            )
-        logger.error("%s hung after %d attempts — abandoning", fn, retries)
-        return False
-
-    # ──────── Capture helpers ───────────────────────────────────────────
-    def _capture_motion(
-        self,
-        reachy_mini: ReachyMini,
-        stop_event: threading.Event,
-        duration: float,
-        record_audio: bool,
-        record_motion: bool = True,
-        on_capture_start: Callable[[], None] | None = None,
-    ) -> tuple[list[float], list[dict[str, Any]], list[np.ndarray], int | None]:
-        timestamps: list[float] = []
-        frames: list[dict[str, Any]] = []
-        audio_frames: list[np.ndarray] = []
-        audio_samplerate: int | None = None
-        audio_active = False
-
-        def _pull_audio_frames(max_seconds: float = 1.0) -> None:
-            if not audio_active:
-                return
-            deadline = time.perf_counter() + max_seconds
-            while time.perf_counter() < deadline:
-                sample = reachy_mini.media.get_audio_sample()
-                if sample is None:
-                    break
-                audio_frames.append(sample)
-
-        if record_audio and self._audio_available:
-            try:
-                reachy_mini.media.start_recording()
-                audio_active = True
-                reported_rate = reachy_mini.media.get_input_audio_samplerate()
-                audio_samplerate = int(reported_rate) if reported_rate else AUDIO_SAMPLE_RATE
-            except Exception as exc:  # pragma: no cover - runtime audio failure
-                self._set_state(
-                    mode="error",
-                    message=f"Audio init failed: {exc}",
-                    active_move=None,
-                )
-                record_audio = False
-                audio_active = False
-
-        start = time.perf_counter()
-        # Update recording_started_at to the actual capture start (after audio init).
-        # Without this, the frontend progress bar is ahead by the audio init delay (~0.5s).
-        self._set_state(recording_started_at=time.time())
-        if on_capture_start is not None:
-            try:
-                on_capture_start()
-            except Exception as exc:
-                logger.warning("Capture start hook failed: %s", exc)
-
-        # Hard time guard: if an SDK call hangs mid-iteration, bail out
-        # after duration + generous margin rather than blocking forever.
-        hard_deadline = start + duration + 10.0
-
-        sample_period = 1.0 / MOTION_SAMPLE_RATE
-        try:
-            while not stop_event.is_set() and not self._recording_cancel_event.is_set():
-                elapsed = time.perf_counter() - start
-                if elapsed >= duration:
-                    break
-                if time.perf_counter() > hard_deadline:
-                    logger.error("Capture loop exceeded hard deadline — aborting")
-                    break
-                if record_motion:
-                    try:
-                        head_pose = reachy_mini.get_current_head_pose()
-                        head_joints, antennas = reachy_mini.get_current_joint_positions()
-                    except Exception as exc:
-                        logger.warning("SDK call failed during capture: %s", exc)
-                        break
-                    timestamps.append(elapsed)
-                    frames.append(
-                        {
-                            "head": np.asarray(head_pose, dtype=float).tolist(),
-                            "antennas": np.asarray(antennas, dtype=float).tolist(),
-                            "body_yaw": float(head_joints[0]) if head_joints else 0.0,
-                            "check_collision": False,
-                        }
-                    )
-                else:
-                    timestamps.append(elapsed)
-                stop_event.wait(sample_period)
-                _pull_audio_frames()
-        finally:
-            if audio_active:
-                stopped_ok = False
-                try:
-                    stopped_ok = self._call_with_timeout(
-                        reachy_mini.media.stop_recording, timeout=3.0
-                    )
-                except Exception as exc:
-                    logger.warning("stop_recording() failed: %s", exc)
-                if stopped_ok:
-                    _pull_audio_frames()
-                else:
-                    logger.warning(
-                        "Skipping audio drain — stop_recording did not complete"
-                    )
-        return timestamps, frames, audio_frames, audio_samplerate
-
-    def _stream_playback(
-        self,
-        reachy_mini: ReachyMini,
-        move: RecordedMove,
-        sample_hook: Callable[[], None] | None = None,
-        start_signal: threading.Event | None = None,
-    ) -> bool:
-        playback_freq = 100.0
-        sleep_period = 1.0 / playback_freq
-        t0 = time.perf_counter()
-        signalled = False
-        while True:
-            if self._playback_cancel_event.is_set():
-                return False
-            elapsed = time.perf_counter() - t0
-            if elapsed >= move.duration:
-                break
-            t = min(max(elapsed, 0.0), max(move.duration - 1e-3, 0.0))
-            head, antennas, body_yaw = move.evaluate(t)
-            reachy_mini.set_target_head_pose(head)
-            if body_yaw is not None:
-                reachy_mini.set_target_body_yaw(float(body_yaw))
-            if antennas is not None:
-                reachy_mini.set_target_antenna_joint_positions(list(antennas))
-            if not signalled and start_signal is not None:
-                start_signal.set()
-                signalled = True
-            if sample_hook is not None:
-                sample_hook()
-
-            remaining = move.duration - elapsed
-            wait_time = max(0.001, min(sleep_period, remaining))
-            if self._playback_cancel_event.wait(wait_time):
-                return False
-
-        return True
-
-    def _apply_motion_model(self, move: RecordedMove) -> RecordedMove:
-        try:
-            return self._motion_model_registry.apply(move)
-        except Exception as exc:
-            logger.warning("Motion model %s failed: %s", self._motion_model_registry.active, exc)
-            return move
-
-    def _save_recording(
-        self,
-        request: RecordingRequest,
-        timestamps: list[float],
-        frames: list[dict[str, Any]],
-        audio_frames: list[np.ndarray],
-        audio_samplerate: int | None,
-    ) -> None:
-        json_path = self._dataset_dir / f"{request.move_id}.json"
-        wav_path = json_path.with_suffix(".wav")
-
-        data: dict[str, Any] = {
-            "description": request.description,
-            "time": timestamps,
-            "set_target_data": frames,
-        }
-        if not request.record_motion:
-            data["audio_only"] = True
-
-        json_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
-
-        # Handle audio: either copy uploaded file or save mic recording
-        if request.uploaded_audio_path and request.uploaded_audio_path.exists():
-            # Copy uploaded audio to move's wav path.
-            # Keep the temp file so the user can record again with the same upload.
-            shutil.copy2(str(request.uploaded_audio_path), str(wav_path))
-        elif request.record_audio and audio_frames and self._audio_available and audio_samplerate:
-            audio_data = np.concatenate(audio_frames, axis=0)
-            sf.write(str(wav_path), audio_data, audio_samplerate)  # type: ignore[arg-type]
-
-    def _load_move(self, json_path: Path, *, prefer_denoised: bool = True) -> RecordedMove:
-        move = json.loads(json_path.read_text(encoding="utf-8"))
-        sound_path = json_path.with_suffix(".wav")
-        if prefer_denoised:
-            denoised = json_path.with_suffix(DENOISED_SUFFIX)
-            if denoised.exists():
-                sound_path = denoised
-        return RecordedMove(move, sound_path if sound_path.exists() else None)
-
-    def _build_recording_request(
-        self, payload: StartRecordingPayload, uploaded_audio_path: Path | None = None
-    ) -> RecordingRequest:
-        stamp = datetime.utcnow().strftime("%Y%m%d-%H%M%S")
-        base_name = payload.label or f"take-{stamp}"
-        label = payload.label or f"Take {stamp}"
-        slug = _slugify(base_name)
-        move_id = slug
-        index = 1
-        while (self._dataset_dir / f"{move_id}.json").exists():
-            move_id = f"{slug}-{index}"
-            index += 1
-
-        description = payload.description or f"Recorded with Marionette on {stamp}"
-
-        return RecordingRequest(
-            move_id=move_id,
-            label=label,
-            description=description,
-            duration=float(payload.duration),
-            record_audio=bool(payload.record_audio),
-            record_motion=bool(payload.record_motion),
-            uploaded_audio_path=uploaded_audio_path,
-        )
-
-    def _refresh_recordings(self) -> None:
-        recordings: dict[str, RecordingMetadata] = {}
-        # Get uploaded move IDs for the active dataset
-        active_entry = self._datasets.get(self._active_dataset_id or "")
-        uploaded_ids = active_entry.uploaded_move_ids if active_entry else set()
-
-        for json_path in sorted(self._dataset_dir.glob("*.json")):
-            try:
-                move = json.loads(json_path.read_text(encoding="utf-8"))
-                timestamps = move.get("time", [])
-                duration = (
-                    float(timestamps[-1]) - float(timestamps[0])
-                    if len(timestamps) >= 2
-                    else float(timestamps[0]) if timestamps else 0.0
-                )
-                description = move.get("description", "")
-                original_audio = json_path.with_suffix(".wav")
-                denoised_audio = json_path.with_suffix(DENOISED_SUFFIX)
-                noise_profile = json_path.with_suffix(NOISE_SUFFIX)
-                has_denoised = denoised_audio.exists()
-                has_audio = has_denoised or original_audio.exists()
-                move_id = json_path.stem
-                recordings[move_id] = RecordingMetadata(
-                    move_id=move_id,
-                    label=move_id,
-                    description=description,
-                    duration=duration,
-                    created_at=json_path.stat().st_mtime,
-                    json_path=json_path,
-                    has_audio=has_audio,
-                    has_noise_profile=noise_profile.exists(),
-                    has_denoised_audio=has_denoised,
-                    is_uploaded=move_id in uploaded_ids,
-                    audio_only=bool(move.get("audio_only", False)),
-                )
-            except Exception:
-                continue
-
-        with self._state_lock:
-            self._recordings = recordings
-
-    # ──────── Dataset management ───────────────────────────────────────
-    def _load_dataset_registry(self) -> None:
-        if self._registry_path.exists():
-            try:
-                raw = json.loads(self._registry_path.read_text(encoding="utf-8"))
-            except Exception:
-                raw = {}
-        else:
-            raw = {}
-
-        raw_params = raw.get("motion_model_params", {})
-        if isinstance(raw_params, dict):
-            for model_name, params in raw_params.items():
-                if isinstance(params, dict):
-                    try:
-                        self._motion_model_registry.set_model_params(model_name, params)
-                    except KeyError:
-                        continue
-        self._preferred_duration = float(raw.get("preferred_duration", DEFAULT_DURATION))
-        self._welcome_messages = int(raw.get("welcome_messages", 2))
-
-        dataset_entries = raw.get("datasets", [])
-        metadata_by_folder: dict[str, dict[str, Any]] = {}
-        fallback_root: Path | None = None
-        for entry in dataset_entries:
-            folder = entry.get("folder")
-            path_str = entry.get("path")
-            if folder:
-                metadata_by_folder[folder] = entry
-                if not fallback_root and path_str:
-                    resolved = self._resolve_dataset_path(path_str)
-                    fallback_root = resolved.parent
-            elif path_str and not fallback_root:
-                resolved = self._resolve_dataset_path(path_str)
-                fallback_root = resolved.parent
-
-        raw_root = raw.get("root_path")
-        if self._dataset_root_override is not None:
-            root_path = self._dataset_root_override
-        elif raw_root:
-            root_path = self._resolve_dataset_path(raw_root)
-        elif fallback_root:
-            root_path = fallback_root
-        else:
-            root_path = self._default_dataset_root()
-        self._dataset_root = root_path
-        self._dataset_root.mkdir(parents=True, exist_ok=True)
-        logger.info("Using dataset root at %s", self._dataset_root)
-
-        datasets: dict[str, DatasetEntry] = {}
-        used_ids: set[str] = set()
-        for folder_path in sorted(self._dataset_root.iterdir()):
-            if not folder_path.is_dir():
-                continue
-            folder = folder_path.name
-            meta = metadata_by_folder.get(folder, {})
-            dataset_id = meta.get("id")
-            if not dataset_id or dataset_id in used_ids:
-                dataset_id = self._next_dataset_id(folder, used_ids)
-            else:
-                used_ids.add(dataset_id)
-            label = meta.get("label") or folder
-            uploaded_ids = set(meta.get("uploaded_move_ids") or [])
-            origin = meta.get("origin", "local")
-            entry = self._entry_from_folder(folder, label, dataset_id, uploaded_ids, origin=origin)
-            datasets[dataset_id] = entry
-
-        if not datasets:
-            default_id = "default" if "default" not in used_ids else self._next_dataset_id(DATASET_DIRNAME, used_ids)
-            entry = self._entry_from_folder(DATASET_DIRNAME, DEFAULT_DATASET_LABEL, default_id)
-            datasets[entry.dataset_id] = entry
-
-        self._datasets = datasets
-        active_id = raw.get("active")
-        if active_id not in self._datasets:
-            active_id = next(iter(self._datasets))
-        self._active_dataset_id = active_id
-        self._dataset_dir = self._ensure_dataset_data_dir(self._datasets[active_id])
-        self._save_dataset_registry()
-
-    def _save_dataset_registry(self) -> None:
-        data = {
-            "active": self._active_dataset_id,
-            "root_path": str(self._dataset_root),
-            "motion_model_params": {
-                "lead_compensation": self._motion_model_registry.get_model_params("lead_compensation"),
-            },
-            "preferred_duration": self._preferred_duration,
-            "welcome_messages": self._welcome_messages,
-            "datasets": [
-                {
-                    "id": entry.dataset_id,
-                    "label": entry.label,
-                    "folder": entry.folder,
-                    "path": str(entry.path),
-                    "uploaded_move_ids": list(entry.uploaded_move_ids or []),
-                    "origin": entry.origin,
-                }
-                for entry in self._datasets.values()
-            ],
-        }
-        self._registry_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
-
-    def _resolve_dataset_path(self, raw_path: str | Path) -> Path:
-        path = Path(raw_path).expanduser()
-        try:
-            path = path.resolve(strict=False)
-        except Exception:
-            path = path.expanduser().absolute()
-        return path
-
-    def _next_dataset_id(self, label: str, used: set[str]) -> str:
-        base = _slugify(label or "dataset")
-        candidate = base or "dataset"
-        suffix = 1
-        while candidate in used:
-            candidate = f"{base}-{suffix}"
-            suffix += 1
-        used.add(candidate)
-        return candidate
-
-    def _entry_from_folder(
-        self,
-        folder: str,
-        label: str,
-        dataset_id: str,
-        uploaded_move_ids: set[str] | None = None,
-        origin: str = "local",
-    ) -> DatasetEntry:
-        path = self._dataset_root / folder
-        entry = DatasetEntry(
-            dataset_id=dataset_id,
-            label=label,
-            folder=folder,
-            path=path,
-            uploaded_move_ids=uploaded_move_ids or set(),
-            origin=origin,
-        )
-        self._ensure_dataset_data_dir(entry)
-        return entry
-
-    def _default_dataset_root(self) -> Path:
-        system = platform.system().lower()
-        home = Path.home()
-        if "windows" in system:
-            base = home / "Documents" / "ReachyMini" / "datasets"
-        elif "darwin" in system:
-            base = home / "Library" / "Application Support" / "ReachyMini" / "datasets"
-        else:
-            base = home / "reachy_mini_datasets"
-        return base
-
-    def _ensure_dataset_data_dir(self, entry: DatasetEntry) -> Path:
-        """Ensure the dataset layout (root + data subdir) exists and migrate legacy files."""
-        entry.path.mkdir(parents=True, exist_ok=True)
-        data_dir = entry.path / DATASET_DATA_SUBDIR
-        data_dir.mkdir(parents=True, exist_ok=True)
-        legacy_moves = list(entry.path.glob("*.json"))
-        for json_path in legacy_moves:
-            target = data_dir / json_path.name
-            if not target.exists():
-                shutil.move(str(json_path), str(target))
-            for suffix in (".wav", NOISE_SUFFIX, DENOISED_SUFFIX):
-                source = json_path.with_suffix(suffix)
-                if source.exists():
-                    shutil.move(str(source), str(data_dir / source.name))
-        return data_dir
-
-    def _create_dataset_internal(
-        self,
-        folder: str,
-        label: str,
-        *,
-        dataset_id: str | None = None,
-        save: bool = True,
-        origin: str = "local",
-    ) -> DatasetEntry:
-        folder_slug = _slugify(folder or label or "dataset")
-        if any(entry.folder == folder_slug for entry in self._datasets.values()):
-            if dataset_id is None:
-                raise HTTPException(status_code=409, detail=f"Dataset folder '{folder_slug}' already exists.")
-        path = self._dataset_root / folder_slug
-        path.mkdir(parents=True, exist_ok=True)
-
-        if dataset_id is None:
-            base = _slugify(label or folder_slug or "dataset")
-            dataset_id = base or "dataset"
-            suffix = 1
-            while dataset_id in self._datasets:
-                dataset_id = f"{base}-{suffix}"
-                suffix += 1
-
-        entry = DatasetEntry(
-            dataset_id=dataset_id, label=label or dataset_id, folder=folder_slug, path=path, origin=origin
-        )
-        self._datasets[entry.dataset_id] = entry
-        self._ensure_dataset_data_dir(entry)
-        if save:
-            self._save_dataset_registry()
-        return entry
-
-    def _create_dataset(self, name: str, label: str | None) -> DatasetEntry:
-        if not name:
-            raise HTTPException(status_code=400, detail="Dataset name is required.")
-        folder = _slugify(name)
-        if not folder:
-            raise HTTPException(status_code=400, detail="Dataset name is invalid.")
-        if any(entry.folder == folder for entry in self._datasets.values()):
-            raise HTTPException(status_code=409, detail="Dataset name already used.")
-        label_to_use = label or name or DEFAULT_DATASET_LABEL
-        entry = self._create_dataset_internal(folder, label_to_use)
-        return entry
-
-    def _select_dataset(self, dataset_id: str) -> None:
-        entry = self._datasets.get(dataset_id)
-        if entry is None:
-            raise HTTPException(status_code=404, detail=f"Dataset {dataset_id} not found.")
-        self._active_dataset_id = dataset_id
-        self._dataset_dir = self._ensure_dataset_data_dir(entry)
-        self._save_dataset_registry()
-
-    def _datasets_payload(self) -> dict[str, Any]:
-        entries = [entry.to_payload() for entry in self._datasets.values()]
-        return {
-            "active_id": self._active_dataset_id,
-            "root_path": str(self._dataset_root),
-            "entries": entries,
-        }
-
-    def _set_dataset_root(self, raw_path: str) -> None:
-        new_root = self._resolve_dataset_path(raw_path)
-        new_root.mkdir(parents=True, exist_ok=True)
-        self._dataset_root = new_root
-        logger.info("Dataset root updated to %s", self._dataset_root)
-        for entry in self._datasets.values():
-            entry.path = self._dataset_root / entry.folder
-            self._ensure_dataset_data_dir(entry)
-        if self._active_dataset_id not in self._datasets and self._datasets:
-            self._active_dataset_id = next(iter(self._datasets))
-        if self._active_dataset_id:
-            self._dataset_dir = self._ensure_dataset_data_dir(self._datasets[self._active_dataset_id])
-        else:
-            default = self._create_dataset_internal(DATASET_DIRNAME, DEFAULT_DATASET_LABEL)
-            self._active_dataset_id = default.dataset_id
-            self._dataset_dir = self._ensure_dataset_data_dir(default)
-        self._save_dataset_registry()
-
-    def _check_hf_login(self) -> str | None:
-        """Return the logged-in Hugging Face username, or None.
-
-        Uses a two-tier check:
-        1. Local: hf_get_token() reads ~/.cache/huggingface/token (no network).
-           If no token exists, we're definitely not logged in.
-        2. Network: hf_whoami() fetches the username from the HF API.
-           If this fails (timeout, rate limit, network down), we still report
-           as logged in (token exists) — just without a username.
-
-        Results are cached so we don't hit the API on every poll.
-        """
-        if self._hf_checked:
-            return self._hf_username
-        self._hf_checked = True
-        # Tier 1: local token check (no network)
-        if hf_get_token is None or not hf_get_token():
-            self._hf_username = None
-            return None
-        # Tier 2: try to get the username (network call)
-        if hf_whoami is not None:
-            try:
-                info = hf_whoami()
-                self._hf_username = info.get("name") if isinstance(info, dict) else None
-            except Exception:
-                # Network failed but token exists — report as logged in
-                self._hf_username = "(token saved)"
-        else:
-            self._hf_username = "(token saved)"
-        return self._hf_username
-
-    def _ensure_hf_backend(self, purpose: str) -> None:
-        global HfApi, DatasetFilter, snapshot_download
-        if HfApi is not None and snapshot_download is not None:
-            return
-        try:
-            from huggingface_hub import HfApi as _HfApi, snapshot_download as _snapshot_download
-            try:
-                from huggingface_hub import DatasetFilter as _DatasetFilter
-            except Exception:
-                _DatasetFilter = DatasetFilter  # keep existing (possibly None)
-        except Exception as exc:  # pragma: no cover - optional dependency
-            logger.warning("huggingface_hub unavailable for %s: %s", purpose, exc)
-            raise HTTPException(
-                status_code=500,
-                detail=f"huggingface_hub is not installed. Install it to {purpose}",
-            ) from exc
-        DatasetFilter = _DatasetFilter
-        HfApi = _HfApi
-        snapshot_download = _snapshot_download
-
-    def _sync_dataset(self, hf_username: str, move_ids: list[str], dataset_slug: str | None) -> dict[str, Any]:
-        self._ensure_hf_backend("publish datasets.")
-        if not move_ids:
-            raise HTTPException(status_code=400, detail="No moves selected for synchronization.")
-
-        self._refresh_recordings()
-        missing = [move_id for move_id in move_ids if move_id not in self._recordings]
-        if missing:
-            raise HTTPException(
-                status_code=404,
-                detail=f"Moves not found in active dataset: {', '.join(missing)}",
-            )
-
-        entry = self._datasets.get(self._active_dataset_id or "")
-        if entry is None:
-            raise HTTPException(status_code=404, detail="No active dataset.")
-
-        repo_basename = dataset_slug or _slugify(entry.label or entry.dataset_id)
-        repo_id = f"{hf_username}/{repo_basename}"
-        exported_bytes = 0
-        selected_meta = [self._recordings[move_id] for move_id in move_ids]
-
-        with TemporaryDirectory(prefix="marionette-sync-") as tmpdir:
-            export_root = Path(tmpdir)
-            data_dir = export_root / "data"
-            data_dir.mkdir(parents=True, exist_ok=True)
-            for meta in selected_meta:
-                src_json = meta.json_path
-                dest_json = data_dir / src_json.name
-                shutil.copy2(src_json, dest_json)
-                exported_bytes += dest_json.stat().st_size
-                wav_path = src_json.with_suffix(".wav")
-                if meta.has_audio and wav_path.exists():
-                    dest_wav = data_dir / wav_path.name
-                    shutil.copy2(wav_path, dest_wav)
-                    exported_bytes += dest_wav.stat().st_size
-
-            readme_path = export_root / "README.md"
-            readme_path.write_text(
-                self._build_hf_readme(entry, selected_meta, repo_id, exported_bytes),
-                encoding="utf-8",
-            )
-
-            api = HfApi()
-            try:
-                api.create_repo(
-                    repo_id=repo_id,
-                    repo_type="dataset",
-                    exist_ok=True,
-                    private=False,
-                )
-                api.upload_folder(
-                    folder_path=str(export_root),
-                    repo_id=repo_id,
-                    repo_type="dataset",
-                )
-            except Exception as exc:  # pragma: no cover - network failure
-                raise HTTPException(status_code=502, detail=f"Failed to upload dataset: {exc}") from exc
-
-        # Mark moves as uploaded
-        if entry.uploaded_move_ids is None:
-            entry.uploaded_move_ids = set()
-        for meta in selected_meta:
-            entry.uploaded_move_ids.add(meta.move_id)
-        self._save_dataset_registry()
-        self._refresh_recordings()
-
-        url = f"https://huggingface.co/datasets/{repo_id}"
-        return {
-            "status": "synced",
-            "repo_id": repo_id,
-            "uploaded_moves": len(selected_meta),
-            "url": url,
-        }
-
-    def _download_community_dataset(self, payload: DownloadDatasetPayload) -> DatasetEntry:
-        self._ensure_hf_backend("download datasets.")
-        repo_id = payload.repo_id.strip()
-        logger.info("Downloading community dataset %s", repo_id)
-        if "/" not in repo_id:
-            raise HTTPException(status_code=400, detail="repo_id must include the username (e.g. user/name).")
-        owner, repo_name = repo_id.split("/", 1)
-        folder_base = payload.name or f"{owner}-{repo_name}"
-        folder = _slugify(folder_base)
-        if not folder:
-            folder = _slugify(repo_id.replace("/", "-"))
-        if any(entry.folder == folder for entry in self._datasets.values()):
-            raise HTTPException(status_code=409, detail=f"Dataset '{folder}' already exists locally. Delete it first to re-download.")
-        target_path = self._dataset_root / folder
-        target_path.mkdir(parents=True, exist_ok=True)
-
-        try:
-            snapshot_download(
-                repo_id=repo_id,
-                repo_type="dataset",
-                local_dir=str(target_path),
-            )
-        except Exception as exc:  # pragma: no cover - network failure
-            logger.exception("Failed to download dataset %s", repo_id)
-            raise HTTPException(status_code=502, detail=f"Failed to download dataset: {exc}") from exc
-
-        label = payload.label or repo_id
-        entry = self._create_dataset_internal(folder=folder, label=label, origin="downloaded")
-        self._select_dataset(entry.dataset_id)
-        logger.info("Dataset %s downloaded into %s", repo_id, entry.path)
-        return entry
-
-    def _list_community_datasets(self) -> list[dict[str, Any]]:
-        datasets: list[Any] = self._fetch_community_datasets_http()
-        if not datasets and HfApi is not None:
-            dataset_filter = None
-            if DatasetFilter is not None:
-                try:
-                    dataset_filter = DatasetFilter(tags=[COMMUNITY_DATASET_TAG])
-                except Exception:  # pragma: no cover - incompatible hub version
-                    logger.debug("DatasetFilter unavailable, falling back to text search.")
-                    dataset_filter = None
-            search_query = None if dataset_filter else COMMUNITY_DATASET_TAG
-            logger.info("Listing community datasets via HfApi for tag %s", COMMUNITY_DATASET_TAG)
-            try:
-                api = HfApi()
-                datasets = api.list_datasets(
-                    filter=dataset_filter,
-                    search=search_query,
-                    limit=MAX_COMMUNITY_DATASETS,
-                    full=True,
-                )
-            except Exception as exc:  # pragma: no cover - network failure
-                logger.warning("HfApi dataset listing failed: %s", exc)
-                datasets = []
-        if not datasets:
-            raise HTTPException(status_code=502, detail="Unable to list community datasets from Hugging Face.")
-
-        filtered_items: list[Any] = []
-        for item in datasets:
-            tags = getattr(item, "tags", None) or item.get("tags") if isinstance(item, dict) else []
-            if tags and COMMUNITY_DATASET_TAG in tags:
-                filtered_items.append(item)
-        if not filtered_items:
-            filtered_items = datasets
-
-        results = []
-        for item in filtered_items:
-            repo_id = (
-                getattr(item, "id", None)
-                or getattr(item, "repo_id", None)
-                or (item.get("id") if isinstance(item, dict) else None)
-                or (item.get("repo_id") if isinstance(item, dict) else None)
-            )
-            if not repo_id:
-                continue
-            card = (
-                getattr(item, "cardData", None)
-                or getattr(item, "card_data", None)
-                or (item.get("cardData") if isinstance(item, dict) else None)
-                or {}
-            )
-            pretty = card.get("pretty_name") or repo_id
-            description = card.get("short_description") or card.get("description") or item.get("description", "")
-            updated = getattr(item, "lastModified", None) or item.get("lastModified")
-            if isinstance(updated, datetime):
-                updated_str = updated.isoformat()
-            else:
-                updated_str = str(updated) if updated else None
-
-            results.append(
-                {
-                    "repo_id": repo_id,
-                    "pretty_name": pretty,
-                    "description": description,
-                    "author": getattr(item, "author", None) or item.get("author"),
-                    "likes": getattr(item, "likes", None) or item.get("likes"),
-                    "downloads": getattr(item, "downloads", None) or item.get("downloads"),
-                    "last_modified": updated_str,
-                    "tags": getattr(item, "tags", None) or item.get("tags"),
-                }
-            )
-        return results
-
-    def _fetch_community_datasets_http(self) -> list[dict[str, Any]]:
-        base_params = {
-            "limit": MAX_COMMUNITY_DATASETS,
-            "full": "true",
-            "sort": "downloads",
-            "direction": "-1",
-        }
-        attempts = [
-            ("tag_search", {"search": f"tag:{COMMUNITY_DATASET_TAG}"}),
-            ("keyword_search", {"search": COMMUNITY_DATASET_TAG}),
-            ("legacy_filter", {"filter": COMMUNITY_DATASET_TAG}),
-        ]
-        for label, extra_params in attempts:
-            params = base_params.copy()
-            params.update(extra_params)
-            try:
-                import requests  # lazy import — only needed for community datasets
-                logger.debug("HTTP dataset listing (%s) with params %s", label, params)
-                resp = requests.get(
-                    HF_DATASETS_API_URL,
-                    params=params,
-                    timeout=30,
-                )
-                resp.raise_for_status()
-                data = resp.json()
-                if isinstance(data, list) and data:
-                    logger.info("Fetched %d community datasets via HTTP (%s)", len(data), label)
-                    return data
-                if isinstance(data, list):
-                    logger.debug("HTTP dataset listing (%s) returned zero results.", label)
-            except Exception as exc:
-                logger.warning("HTTP dataset listing (%s) failed: %s", label, exc)
-        return []
-
-    def _build_hf_readme(
-        self,
-        dataset_entry: DatasetEntry,
-        selected_meta: list[RecordingMetadata],
-        repo_id: str,
-        exported_bytes: int,
-    ) -> str:
-        pretty_name = f"{dataset_entry.label} • Reachy Mini Moves"
-        num_examples = len(selected_meta)
-        total_duration = sum(meta.duration for meta in selected_meta)
-        audio_count = sum(1 for meta in selected_meta if meta.has_audio)
-        latest_timestamp = max((meta.created_at for meta in selected_meta), default=time.time())
-        created_iso = datetime.utcfromtimestamp(latest_timestamp).strftime("%Y-%m-%dT%H:%M:%SZ")
-        move_rows = []
-        for meta in selected_meta:
-            recorded_at = datetime.utcfromtimestamp(meta.created_at).strftime("%Y-%m-%d %H:%M")
-            audio_label = "Yes" if meta.has_audio else "No"
-            move_rows.append(
-                f"| `{meta.move_id}` | {meta.duration:.1f}s | {audio_label} | {recorded_at} |"
-            )
-        moves_table = "\n".join(move_rows) if move_rows else "| – | – | – | – |"
-        front_matter = dedent(
-            f"""\
-            ---
-            dataset_info:
-              features:
-                - name: move_id
-                  dtype: string
-                - name: description
-                  dtype: string
-                - name: duration_seconds
-                  dtype: float64
-                - name: has_audio
-                  dtype: bool
-              splits:
-                - name: train
-                  num_examples: {num_examples}
-                  num_bytes: {exported_bytes}
-              download_size: {exported_bytes}
-              dataset_size: {exported_bytes}
-            configs:
-              - config_name: default
-                data_files:
-                  - split: train
-                    path: data/*.json
-            task_categories:
-              - robotics
-            language:
-              - en
-            tags:
-              - reachy_mini_community_moves
-            pretty_name: {pretty_name}
-            license: apache-2.0
-            ---
-            """
-        ).strip()
-
-        body = dedent(
-            f"""
-            # {pretty_name}
-
-            Community-contributed Marionette recordings captured on Reachy Mini.
-
-            - **Moves uploaded:** {num_examples}
-            - **Total motion time:** {total_duration:.1f} seconds
-            - **Audio tracks:** {audio_count}
-            - **Last updated:** {created_iso}
-
-            Files live under `data/` — each move ships as a JSON trajectory (Reachy Mini emotions schema) plus an optional WAV recorded directly from the robot.
-
-            ## How this dataset was produced
-
-            These takes were recorded with the Marionette Reachy Mini app. Pick the moves to share, set your Hugging Face username, run `huggingface-cli login` once locally, then hit **Synchronize to Hugging Face dataset** inside Marionette. The app packages the selected files, generates this README, and uploads them to `{repo_id}`.
-
-            ## Selected moves
-
-            | Move | Duration | Audio | Recorded at (UTC) |
-            | --- | --- | --- | --- |
-            {moves_table}
-
-            ## Reuse
-
-            - Cite this dataset as `{repo_id}`.
-            - Keep the `reachy_mini_community_moves` tag when sharing derivatives so the community can discover related sets.
-            """
-        ).strip()
-        return f"{front_matter}\n\n{body}\n"
-
-    def _scaled_duration(
-        self, reachy_mini: ReachyMini, target_head_pose: np.ndarray, *, min_duration: float = 0.05
-    ) -> float:
-        _, _, magic_distance = distance_between_poses(
-            reachy_mini.get_current_head_pose(),
-            target_head_pose,
-        )
-        duration = magic_distance * 20 / 1000
-        return max(min_duration, duration)
-
-    def _goto_pose_scaled(
-        self,
-        reachy_mini: ReachyMini,
-        head_pose: np.ndarray,
-        *,
-        antennas: list[float] | np.ndarray | None = None,
-        min_duration: float = 0.05,
-    ) -> None:
-        """Go to pose with duration scaled by distance. goto_target is blocking."""
-        duration = self._scaled_duration(reachy_mini, head_pose, min_duration=min_duration)
-        antennas_payload = list(antennas) if antennas is not None else None
-        reachy_mini.goto_target(
-            head=head_pose,
-            antennas=antennas_payload,
-            duration=duration,
-        )
-
-    def _goto_current_pose(self, reachy_mini: ReachyMini, duration: float = 0.05) -> None:
-        head_pose = reachy_mini.get_current_head_pose()
-        _, antennas = reachy_mini.get_current_joint_positions()
-        reachy_mini.goto_target(
-            head=head_pose,
-            antennas=list(antennas) if antennas is not None else None,
-            duration=max(0.02, duration),
-        )
-
-    def _safe_enable_motors(self, reachy_mini: ReachyMini) -> None:
-        self._goto_current_pose(reachy_mini, duration=0.05)
-        reachy_mini.enable_motors()
-        time.sleep(0.1)
-
-    def _park_robot(self, reachy_mini: ReachyMini) -> None:
-        self._safe_enable_motors(reachy_mini)
-        self._goto_pose_scaled(
-            reachy_mini,
-            INIT_HEAD_POSE,
-            antennas=[0.0, 0.0],
-            min_duration=0.2,
-        )
-
-    def _align_head_and_release(self, reachy_mini: ReachyMini) -> None:
-        self._safe_enable_motors(reachy_mini)
-        self._goto_pose_scaled(
-            reachy_mini,
-            INIT_HEAD_POSE,
-            antennas=[0.0, 0.0],
-            min_duration=0.2,
-        )
-        self._goto_sleep_and_release(reachy_mini)
-
-    def _goto_sleep_and_release(self, reachy_mini: ReachyMini) -> None:
-        """Move head to sleep pose then disable motors (graceful torque-off)."""
-        # Use 15 degrees for antennas for style points
-        antenna_angle = np.deg2rad(15)
-        reachy_mini.goto_target(
-            SLEEP_HEAD_POSE,
-            antennas=[-antenna_angle, antenna_angle],
-            duration=1.0,
-        )
-        reachy_mini.disable_motors()
-
-    def _delete_move_files(self, move_id: str) -> None:
-        json_path = self._dataset_dir / f"{move_id}.json"
-        if not json_path.exists():
-            raise HTTPException(status_code=404, detail=f"Move {move_id} not found.")
-        try:
-            json_path.unlink()
-            wav_path = json_path.with_suffix(".wav")
-            if wav_path.exists():
-                wav_path.unlink()
-        except OSError as exc:
-            raise HTTPException(status_code=500, detail=f"Failed to delete {move_id}: {exc}") from exc
-
-    # ──────── State helpers ─────────────────────────────────────────────
-    def _serialize_state(self) -> dict[str, Any]:
-        with self._state_lock:
-            moves = sorted(
-                (meta.to_payload() for meta in self._recordings.values()),
-                key=lambda entry: entry["created_at"],
-                reverse=True,
-            )
-            # Unified timing: phase_start_at / phase_end_at
-            phase_start_at: float | None = None
-            phase_end_at: float | None = None
-            if self._mode == "countdown" and self._countdown_ends_at is not None:
-                phase_start_at = self._countdown_ends_at - COUNTDOWN_SECONDS
-                phase_end_at = self._countdown_ends_at
-            elif self._mode == "recording" and self._active_record_started_at is not None:
-                phase_start_at = self._active_record_started_at
-                if self._active_record_duration is not None:
-                    phase_end_at = self._active_record_started_at + self._active_record_duration
-
-            return {
-                "server_time": time.time(),
-                "mode": self._mode,
-                "message": self._message,
-                "active_move": self._active_move,
-                "phase_start_at": phase_start_at,
-                "phase_end_at": phase_end_at,
-                "countdown_ends_at": self._countdown_ends_at,
-                "recording_started_at": self._active_record_started_at,
-                "recording_duration": self._active_record_duration,
-                "recording_stats": self._recording_stats,
-                "pending_recording": self._pending_recording.label if self._pending_recording else None,
-                "pending_playback": self._pending_playback,
-                "moves": moves,
-                "config": {
-                    "default_duration": DEFAULT_DURATION,
-                    "preferred_duration": self._preferred_duration,
-                    "countdown_seconds": COUNTDOWN_SECONDS,
-                    "motion_sample_rate": MOTION_SAMPLE_RATE,
-                    "audio_available": self._audio_available,
-                    "active_dataset_path": str(self._dataset_dir),
-                    "dataset_root_path": str(self._dataset_root),
-                    "hf_username": self._check_hf_login(),
-                    "motion_models": self._motion_model_registry.to_payload(),
-                    "welcome_messages": self._welcome_messages,
-                },
-                "datasets": self._datasets_payload(),
-            }
-
-    _UNSET = object()
-
-    def _set_state(
-        self,
-        *,
-        mode: str | None = None,
-        message: str | None = None,
-        active_move: object = _UNSET,
-        countdown_ends_at: object = _UNSET,
-        recording_started_at: object = _UNSET,
-        recording_duration: object = _UNSET,
-    ) -> None:
-        with self._state_lock:
-            if mode is not None:
-                self._mode = mode
-            if message is not None:
-                self._message = message
-            if active_move is not self._UNSET:
-                self._active_move = active_move
-            if countdown_ends_at is not self._UNSET:
-                self._countdown_ends_at = countdown_ends_at
-            if recording_started_at is not self._UNSET:
-                self._active_record_started_at = recording_started_at
-            if recording_duration is not self._UNSET:
-                self._active_record_duration = recording_duration
-
-    def _set_idle_state(self) -> None:
-        self._set_state(
-            mode="idle",
-            message="Ready to capture moves",
-            active_move=None,
-            countdown_ends_at=None,
-            recording_started_at=None,
-            recording_duration=None,
-        )
-
-
-def create_app(
-    registry_path: Path | None = None,
-    dataset_root: Path | None = None,
-) -> tuple["FastAPI", "Marionette"]:
-    """Create a Marionette instance and its FastAPI app.
-
-    Useful for testing with FastAPI's TestClient:
-        app, marionette = create_app(registry_path=tmp / "reg.json", dataset_root=tmp / "ds")
-        client = TestClient(app)
-    """
-    from fastapi import FastAPI as _FastAPI
-
-    marionette = Marionette(
-        registry_path=registry_path,
-        dataset_root=dataset_root,
-    )
-    assert marionette.settings_app is not None
-    return marionette.settings_app, marionette
-
+from marionette.state import StateMixin  # noqa: F401
+from marionette.recording import RecordingMixin  # noqa: F401
+from marionette.datasets import (  # noqa: F401
+    DatasetMixin,
+    hf_whoami,
+    hf_login,
+    hf_logout,
+    hf_get_token,
+    HfApi,
+    DatasetFilter,
+    snapshot_download,
+)
+from marionette.routes import register_routes  # noqa: F401
+from marionette.app import Marionette, create_app, __version__  # noqa: F401
 
+# The daemon runs `python -u -m marionette.main` to launch the app.
+# Without this block, the module just imports and exits immediately.
 if __name__ == "__main__":
     app = Marionette()
     try:

marionette/models.py

@@ -0,0 +1,202 @@
+"""Data models, constants, and utility functions for the Marionette app.
+
+This module contains all the shared types (dataclasses, Pydantic models),
+configuration constants, and small utility functions used across the
+application. It has no dependencies on other marionette submodules.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from pydantic import BaseModel, Field
+
+# ──────── Configuration constants ─────────────────────────────────────
+
+AUDIO_SAMPLE_RATE = 44_100          # Default sample rate for mic recording (Hz)
+MOTION_SAMPLE_RATE = 100.0          # How often we sample the robot's pose (Hz)
+COUNTDOWN_SECONDS = 3               # Seconds of countdown before recording starts
+# Compensation for push_audio_sample pipeline latency during playback.
+# Audio is started this many ms before the first motion command so that
+# both arrive at the speaker/motors at the same time.
+# Measured via tests/test_marionette_sync.py: 320ms = 245ms GStreamer
+# pipeline latency + ~75ms thread-scheduling overhead.
+AUDIO_LEAD_MS = 320
+DEFAULT_DURATION = 5.0              # Default recording duration (seconds)
+DATASET_DIRNAME = "local_dataset"   # Folder name for the default dataset
+DATASET_REGISTRY_FILENAME = "dataset_registry.json"  # Persists dataset config
+DEFAULT_DATASET_LABEL = "Local dataset"
+COMMUNITY_DATASET_TAG = "reachy_mini_community_moves"  # HF tag for discovery
+MAX_COMMUNITY_DATASETS = 50         # Cap on HF API results
+HF_DATASETS_API_URL = "https://huggingface.co/api/datasets"
+DATASET_DATA_SUBDIR = "data"        # Subdirectory within each dataset folder
+
+# Semi-awaken pose: identity rotation, same XY as sleep, Z raised 1.5cm
+SEMI_AWAKEN_POSE = np.array(
+    [
+        [1.0, 0.0, 0.0, -0.021],
+        [0.0, 1.0, 0.0, 0.001],
+        [0.0, 0.0, 1.0, -0.029],
+        [0.0, 0.0, 0.0, 1.0],
+    ]
+)
+
+
+# ──────── Utility functions ───────────────────────────────────────────
+
+def _slugify(value: str) -> str:
+    """Convert a human-readable string to a filesystem-safe slug.
+
+    Used for move IDs and dataset folder names. Falls back to "take"
+    if the input contains no alphanumeric characters.
+    """
+    slug = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
+    return slug or "take"
+
+
+# ──────── Dataclasses ─────────────────────────────────────────────────
+
+@dataclass
+class RecordingMetadata:
+    """In-memory representation of a saved recording (one JSON file on disk).
+
+    Populated by _refresh_recordings() which scans the active dataset directory.
+    """
+    move_id: str          # Unique identifier, same as the JSON filename stem
+    label: str            # Human-readable name shown in the UI
+    description: str      # User-provided or auto-generated description
+    duration: float       # Duration in seconds (computed from timestamps)
+    created_at: float     # Unix timestamp of file modification time
+    json_path: Path       # Absolute path to the .json trajectory file
+    has_audio: bool       # Whether a matching .wav file exists
+    is_uploaded: bool = False   # Whether this move was synced to HF
+    audio_only: bool = False    # True for mic-only recordings (no motion)
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "id": self.move_id,
+            "label": self.label,
+            "duration": self.duration,
+            "created_at": self.created_at,
+            "has_audio": self.has_audio,
+            "description": self.description,
+            "is_uploaded": self.is_uploaded,
+            "audio_only": self.audio_only,
+        }
+
+
+@dataclass
+class RecordingRequest:
+    """Parameters for a pending recording, built from StartRecordingPayload.
+
+    Created by _build_recording_request() and consumed by _perform_recording().
+    Passed from the HTTP thread to the robot thread via _pending_recording.
+    """
+    move_id: str                          # Generated unique slug
+    label: str                            # Display name
+    description: str                      # Description text
+    duration: float                       # Requested duration in seconds
+    record_audio: bool                    # Whether to capture from the mic
+    record_motion: bool = True            # False = mic-only (no pose capture)
+    uploaded_audio_path: Path | None = None  # Pre-uploaded audio to play during recording
+
+
+@dataclass
+class DatasetEntry:
+    """Represents one dataset (a folder containing recordings).
+
+    A dataset is a directory under the dataset root. It has a unique ID
+    (for API use), a human label, and tracks which moves have been synced
+    to Hugging Face.
+    """
+    dataset_id: str                          # Unique identifier for API calls
+    label: str                               # Human-readable name
+    folder: str                              # Filesystem folder name under dataset root
+    path: Path                               # Absolute path to the dataset folder
+    uploaded_move_ids: set[str] | None = None # Move IDs that have been synced to HF
+    origin: str = "local"                    # "local" (user-created) or "downloaded" (from HF)
+
+    def __post_init__(self) -> None:
+        if self.uploaded_move_ids is None:
+            self.uploaded_move_ids = set()
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "id": self.dataset_id,
+            "label": self.label,
+            "path": str(self.path),
+            "folder": self.folder,
+            "origin": self.origin,
+        }
+
+
+# ──────── Pydantic request models ────────────────────────────────────
+
+class StartRecordingPayload(BaseModel):
+    duration: float = Field(DEFAULT_DURATION, gt=0.5, le=300.0)
+    record_audio: bool = Field(default=True)
+    record_motion: bool = Field(default=True, description="When False, record audio only (no motion capture)")
+    label: str | None = Field(default=None, max_length=80)
+    description: str | None = Field(default=None, max_length=500)
+    uploaded_audio_id: str | None = Field(default=None, description="ID of previously uploaded audio file")
+
+
+class PlayMovePayload(BaseModel):
+    move_id: str = Field(..., description="Move identifier (filename stem)")
+
+
+class CreateDatasetPayload(BaseModel):
+    name: str = Field(..., description="Folder name for the dataset", min_length=1, max_length=80)
+    label: str | None = Field(default=None, max_length=80)
+
+
+class SelectDatasetPayload(BaseModel):
+    dataset_id: str
+
+
+class SyncDatasetPayload(BaseModel):
+    move_ids: list[str] = Field(..., min_length=1, description="Subset of moves to publish")
+    hf_username: str | None = Field(default=None, min_length=2, max_length=80)
+    dataset_slug: str | None = Field(
+        default=None, description="Optional override for the Hugging Face dataset slug"
+    )
+
+
+class UpdateDatasetRootPayload(BaseModel):
+    path: str = Field(..., description="Filesystem directory containing all datasets")
+
+
+class DownloadDatasetPayload(BaseModel):
+    repo_id: str = Field(..., description="Hugging Face dataset repository, e.g. user/name")
+    label: str | None = Field(default=None, max_length=80)
+    name: str | None = Field(
+        default=None,
+        description="Optional folder name; defaults to the dataset slug",
+        max_length=80,
+    )
+
+
+class UpdateLeadCompensationPayload(BaseModel):
+    lead_frames_head: int | None = Field(
+        default=None, ge=0, le=2000, description="Look-ahead for head/body in 100Hz frames"
+    )
+    lead_frames_antennas: int | None = Field(
+        default=None, ge=0, le=2000, description="Look-ahead for antennas in 100Hz frames"
+    )
+
+
+class UpdateExperimentsPayload(BaseModel):
+    duration_seconds: float | None = Field(default=None, gt=0.5, le=300.0)
+    welcome_messages: int | None = Field(default=None, ge=0, le=2, description="Number of welcome messages at startup (0, 1, or 2)")
+
+
+class HfTokenPayload(BaseModel):
+    token: str = Field(..., min_length=5, description="Hugging Face access token (starts with hf_)")
+
+
+
+class RobotAudioSelectPayload(BaseModel):
+    path: str = Field(..., description="Absolute path to a WAV file on the robot")

marionette/motion_models.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import copy
-from typing import Any, Dict
+from typing import Any
 
 try:
     from reachy_mini.motion.recorded_move import RecordedMove
@@ -11,7 +11,7 @@ except Exception:  # pragma: no cover - reachable at runtime
     RecordedMove = None  # type: ignore
 
 
-def _deepcopy_move(move: Dict[str, Any]) -> Dict[str, Any]:
+def _deepcopy_move(move: dict[str, Any]) -> dict[str, Any]:
     """Copy a move dict without mutating the source."""
     return copy.deepcopy(move)
 
@@ -31,7 +31,7 @@ class LeadCompensationModel:
         self.lead_frames_antennas = max(0, int(lead_frames_antennas))
         self.lead_frames_head = max(0, int(lead_frames_head))
 
-    def transform(self, move: Dict[str, Any]) -> Dict[str, Any]:
+    def transform(self, move: dict[str, Any]) -> dict[str, Any]:
         patched = _deepcopy_move(move)
         data = patched.get("set_target_data", [])
         if not data:
@@ -59,7 +59,7 @@ class MotionModelRegistry:
     def active(self) -> str:
         return self._active
 
-    def set_model_params(self, name: str, params: Dict[str, Any]) -> None:
+    def set_model_params(self, name: str, params: dict[str, Any]) -> None:
         if name != LeadCompensationModel.name:
             raise KeyError(name)
         head = params.get("lead_frames_head")
@@ -69,7 +69,7 @@ class MotionModelRegistry:
         if antennas is not None:
             self._model.lead_frames_antennas = max(0, int(antennas))
 
-    def get_model_params(self, name: str) -> Dict[str, Any]:
+    def get_model_params(self, name: str) -> dict[str, Any]:
         if name != LeadCompensationModel.name:
             raise KeyError(name)
         return {
@@ -77,7 +77,7 @@ class MotionModelRegistry:
             "lead_frames_antennas": int(self._model.lead_frames_antennas),
         }
 
-    def transform_move(self, move_data: Dict[str, Any]) -> Dict[str, Any]:
+    def transform_move(self, move_data: dict[str, Any]) -> dict[str, Any]:
         return self._model.transform(move_data)
 
     def apply(self, recorded_move: RecordedMove) -> RecordedMove:
@@ -86,7 +86,7 @@ class MotionModelRegistry:
         mutated = self.transform_move(recorded_move.move)
         return RecordedMove(mutated, recorded_move.sound_path)
 
-    def to_payload(self) -> Dict[str, Any]:
+    def to_payload(self) -> dict[str, Any]:
         return {
             "active": self._active,
             "models": [

marionette/recording.py

@@ -0,0 +1,678 @@
+"""Recording, capture, and playback mixin for the Marionette app.
+
+Contains all methods related to motion capture, audio recording during
+capture, move playback, and recording file I/O (save/load/refresh).
+"""
+from __future__ import annotations
+
+import json
+import logging
+import shutil
+import threading
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Callable
+
+import numpy as np
+from reachy_mini.motion.recorded_move import RecordedMove
+
+from marionette.audio import (
+    call_with_timeout,
+    generate_beep,
+    play_preloaded_wav,
+    play_wav_chunked,
+    preload_wav,
+)
+from marionette.models import (
+    AUDIO_LEAD_MS,
+    AUDIO_SAMPLE_RATE,
+    COUNTDOWN_SECONDS,
+    MOTION_SAMPLE_RATE,
+    RecordingMetadata,
+    RecordingRequest,
+    StartRecordingPayload,
+    _slugify,
+)
+
+try:
+    import soundfile as sf
+except Exception:  # pragma: no cover
+    sf = None
+
+logger = logging.getLogger(__name__)
+
+
+class RecordingMixin:
+    """Mixin providing recording, capture, and playback methods.
+
+    Expects the host class to have: _state_lock, _recording_cancel_event,
+    _playback_cancel_event, _recordings, _dataset_dir, _audio_available,
+    _preferred_duration, _motion_model_registry, _set_state(),
+    _set_idle_state(), _safe_enable_motors(), _goto_pose_scaled(),
+    _goto_sleep_and_release().
+    """
+
+    def _perform_recording(
+        self,
+        reachy_mini: object,
+        stop_event: threading.Event,
+        request: RecordingRequest,
+    ) -> None:
+        self._recording_cancel_event.clear()
+
+        # ── Pre-countdown: preload audio + warm pipeline ──────────────
+        # All audio prep (resample, GStreamer warm-up) happens BEFORE the
+        # countdown so there's zero lag at the critical sync point.
+        audio_stop = threading.Event()
+        audio_start = threading.Event()
+        audio_thread: threading.Thread | None = None
+        pipeline_warmed = False
+
+        try:
+            sr_out = int(reachy_mini.media.get_output_audio_samplerate() or 16000)
+        except Exception:
+            sr_out = 16000
+
+        if request.uploaded_audio_path and request.uploaded_audio_path.exists():
+            self._set_state(
+                mode="preparing",
+                message=f"Preparing audio for {request.label}",
+                active_move=request.label,
+            )
+            wav_data = preload_wav(request.uploaded_audio_path, target_sr=sr_out)
+            if wav_data is not None:
+                self._warm_audio_pipeline(reachy_mini)
+                pipeline_warmed = True
+                audio_thread = threading.Thread(
+                    target=play_preloaded_wav,
+                    args=(reachy_mini, wav_data, audio_stop),
+                    kwargs={"pipeline_ready": True, "start_signal": audio_start},
+                    daemon=True,
+                )
+                audio_thread.start()
+
+        # Warm pipeline for countdown beeps (even without uploaded audio)
+        if not pipeline_warmed:
+            self._warm_audio_pipeline(reachy_mini)
+            pipeline_warmed = True
+
+        # ── Countdown with beeps ──────────────────────────────────────
+        countdown_end = time.perf_counter() + COUNTDOWN_SECONDS
+        self._set_state(
+            mode="countdown",
+            message=f"Recording {request.label} in {COUNTDOWN_SECONDS}s",
+            active_move=request.label,
+            countdown_ends_at=time.time() + COUNTDOWN_SECONDS,
+        )
+
+        beeped = set()
+        beep_samples = generate_beep(freq=440, duration=0.1, sr=sr_out)
+        go_beep_samples = generate_beep(freq=880, duration=0.1, sr=sr_out)
+        while time.perf_counter() < countdown_end:
+            # Play beeps at each second boundary
+            elapsed = COUNTDOWN_SECONDS - (countdown_end - time.perf_counter())
+            second = int(elapsed)
+            if second not in beeped and 0 <= second < COUNTDOWN_SECONDS:
+                beeped.add(second)
+                try:
+                    reachy_mini.media.push_audio_sample(beep_samples)
+                except Exception:
+                    pass
+            if stop_event.wait(0.02) or self._recording_cancel_event.is_set():
+                self._recording_cancel_event.clear()
+                self._cleanup_audio(audio_thread, audio_start, audio_stop, pipeline_warmed, reachy_mini, has_uploaded_audio=audio_thread is not None)
+                self._set_state(mode="idle", message="Recording cancelled", active_move=None)
+                return
+
+        # 4th beep: GO! (higher pitch, fires at capture start)
+        try:
+            reachy_mini.media.push_audio_sample(go_beep_samples)
+        except Exception:
+            pass
+
+        # Stop pipeline if we only warmed it for beeps (no uploaded audio to play)
+        if pipeline_warmed and audio_thread is None:
+            try:
+                call_with_timeout(reachy_mini.media.stop_playing)
+            except Exception:
+                pass
+
+        with self._state_lock:
+            self._recording_stats = None
+
+        self._set_state(
+            mode="recording",
+            message=f"Recording {request.label}",
+            active_move=request.move_id,
+            recording_started_at=time.time(),
+            recording_duration=request.duration,
+        )
+
+        try:
+            self._run_capture_and_save(
+                reachy_mini, stop_event, request,
+                audio_thread=audio_thread,
+                audio_start=audio_start,
+                audio_stop=audio_stop,
+            )
+        except Exception as exc:
+            logger.error("Recording failed: %s", exc, exc_info=True)
+            self._cleanup_audio(audio_thread, audio_start, audio_stop, False, reachy_mini, has_uploaded_audio=audio_thread is not None)
+            self._set_state(
+                mode="error",
+                message=f"Recording error: {exc}",
+                active_move=None,
+            )
+
+    @staticmethod
+    def _warm_audio_pipeline(reachy_mini: object) -> None:
+        """Start GStreamer and push a silent buffer to avoid cold-start lag."""
+        reachy_mini.media.start_playing()
+        try:
+            reachy_mini.media.push_audio_sample(
+                np.zeros(160, dtype=np.float32)
+            )
+        except Exception:
+            pass
+
+    @staticmethod
+    def _cleanup_audio(
+        audio_thread: threading.Thread | None,
+        audio_start: threading.Event,
+        audio_stop: threading.Event,
+        pipeline_warmed: bool,
+        reachy_mini: object,
+        has_uploaded_audio: bool,
+    ) -> None:
+        """Clean up audio thread and pipeline on cancellation or error."""
+        audio_start.set()
+        audio_stop.set()
+        if audio_thread is not None:
+            audio_thread.join(timeout=3.0)
+        if pipeline_warmed and not has_uploaded_audio:
+            try:
+                call_with_timeout(reachy_mini.media.stop_playing)
+            except Exception:
+                pass
+
+    def _run_capture_and_save(
+        self,
+        reachy_mini: object,
+        stop_event: threading.Event,
+        request: RecordingRequest,
+        audio_thread: threading.Thread | None = None,
+        audio_start: threading.Event | None = None,
+        audio_stop: threading.Event | None = None,
+    ) -> None:
+        """Inner recording logic, wrapped by _perform_recording's safety net.
+
+        Audio preload/resample/pipeline-warm is done in _perform_recording
+        before the countdown. This method receives the pre-built audio thread
+        and events, and only needs to fire audio_start at capture start.
+        """
+        if audio_start is None:
+            audio_start = threading.Event()
+        if audio_stop is None:
+            audio_stop = threading.Event()
+
+        # When using uploaded audio, don't record from mic (audio comes from the file)
+        should_record_mic = request.record_audio and not request.uploaded_audio_path
+        try:
+            timestamps, frames, audio_frames, audio_samplerate = self._capture_motion(
+                reachy_mini, stop_event, request.duration, should_record_mic,
+                record_motion=request.record_motion,
+                on_capture_start=(audio_start.set if audio_thread is not None else None),
+            )
+        finally:
+            # Unblock the audio thread's start_signal.wait() first, then
+            # signal stop. Without this, an early capture failure would
+            # leave the audio thread stranded in wait() for up to 5s.
+            audio_start.set()
+            audio_stop.set()
+            if audio_thread is not None:
+                audio_thread.join(timeout=3.0)
+
+        # Check if recording was cancelled
+        was_cancelled = self._recording_cancel_event.is_set()
+        self._recording_cancel_event.clear()
+
+        if not timestamps:
+            self._set_state(
+                mode="idle",
+                message="Recording cancelled" if was_cancelled else "No motion data captured.",
+                active_move=None,
+            )
+            return
+
+        # Save the recording (even if partial due to early stop)
+        self._save_recording(request, timestamps, frames, audio_frames, audio_samplerate)
+        self._refresh_recordings()
+        pose_count = len(frames)
+        duration_elapsed = timestamps[-1] if timestamps else request.duration
+        duration_elapsed = max(duration_elapsed, 1e-6)
+        poses_per_sec = pose_count / duration_elapsed
+        with self._state_lock:
+            self._recording_stats = {
+                "poses": pose_count,
+                "duration": duration_elapsed,
+                "poses_per_second": poses_per_sec,
+            }
+        if not request.record_motion:
+            status_msg = f"Recorded audio: {request.label} ({duration_elapsed:.1f}s)"
+            if was_cancelled:
+                status_msg = f"Saved audio: {request.label} (stopped early, {duration_elapsed:.1f}s)"
+        else:
+            status_msg = f"Recorded {request.label} • {pose_count} poses ({poses_per_sec:.1f}/s)"
+            if was_cancelled:
+                status_msg = f"Saved {request.label} (stopped early) • {pose_count} poses"
+        self._set_state(
+            mode="idle",
+            message=status_msg,
+            active_move=None,
+        )
+        if not was_cancelled:
+            self._preferred_duration = request.duration
+
+    def _perform_playback(self, reachy_mini: object, move_id: str) -> None:
+        """Replay a recorded move with optional audio.
+
+        Playback flow for motion moves:
+          1. Load JSON trajectory and apply lead compensation
+          2. Preload WAV and resample (overlapped with goto start pose)
+          3. Warm GStreamer pipeline, spawn audio thread waiting on start_signal
+          4. _stream_playback sends first motion command then fires start_signal
+          5. Audio and motion run in sync until done or cancelled
+        """
+        meta = self._recordings.get(move_id)
+        if not meta:
+            self._set_state(mode="error", message=f"Move {move_id} missing.", active_move=None)
+            return
+
+        try:
+            move = self._load_move(meta.json_path)
+        except Exception as exc:  # pragma: no cover - filesystem failure
+            self._set_state(
+                mode="error",
+                message=f"Failed to load {move_id}: {exc}",
+                active_move=None,
+            )
+            return
+
+        # Audio-only moves: just play the audio, no motion replay
+        if meta.audio_only:
+            self._playback_cancel_event.clear()
+            self._set_state(
+                mode="playing",
+                message=f"Playing audio: {meta.label}",
+                active_move=meta.move_id,
+            )
+            if move.sound_path is not None:
+                try:
+                    play_wav_chunked(
+                        reachy_mini, move.sound_path, self._playback_cancel_event,
+                    )
+                except Exception:
+                    pass
+            cancelled = self._playback_cancel_event.is_set()
+            self._playback_cancel_event.clear()
+            msg = f"Playback stopped for {meta.label}" if cancelled else f"Finished playing {meta.label}"
+            self._set_state(mode="idle", message=msg, active_move=None)
+            return
+
+        move_to_play = self._apply_motion_model(move)
+
+        self._playback_cancel_event.clear()
+        self._set_state(
+            mode="playing",
+            message=f"Playing {meta.label}",
+            active_move=meta.move_id,
+        )
+
+        self._safe_enable_motors(reachy_mini)
+        cancelled = False
+
+        # Preload audio (including resample) while we go to the start pose,
+        # so playback can begin instantly when motion starts.
+        try:
+            sr_out = int(reachy_mini.media.get_output_audio_samplerate() or 16000)
+        except Exception:
+            sr_out = 16000
+        wav_data: tuple[np.ndarray, int] | None = None
+        if move_to_play.sound_path is not None:
+            wav_data = preload_wav(move_to_play.sound_path, target_sr=sr_out)
+
+        # Move to the start pose BEFORE starting audio so they begin in sync.
+        try:
+            start_head_pose, start_antennas, start_body_yaw = move_to_play.evaluate(0.0)
+        except Exception:
+            self._set_state(mode="error", message="Failed to evaluate move start pose", active_move=None)
+            return
+        self._goto_pose_scaled(
+            reachy_mini,
+            start_head_pose,
+            antennas=list(start_antennas) if start_antennas is not None else None,
+            min_duration=0.2,
+        )
+        if start_body_yaw is not None:
+            reachy_mini.set_target_body_yaw(float(start_body_yaw))
+
+        # Warm the audio pipeline and start audio early to compensate for
+        # push_audio_sample pipeline latency (see AUDIO_LEAD_MS).
+        audio_stop = threading.Event()
+        audio_start = threading.Event()
+        audio_thread: threading.Thread | None = None
+        if wav_data is not None:
+            reachy_mini.media.start_playing()
+            # Warm the GStreamer pipeline (see recording path for explanation).
+            try:
+                reachy_mini.media.push_audio_sample(
+                    np.zeros(160, dtype=np.float32)
+                )
+            except Exception:
+                pass
+            audio_thread = threading.Thread(
+                target=play_preloaded_wav,
+                args=(reachy_mini, wav_data, audio_stop),
+                kwargs={"pipeline_ready": True, "start_signal": audio_start},
+                daemon=True,
+            )
+            audio_thread.start()
+            # Start audio BEFORE motion so that by the time chunks traverse
+            # the GStreamer pipeline, the first audible output coincides with
+            # the first physical movement.
+            audio_start.set()
+            time.sleep(AUDIO_LEAD_MS / 1000.0)
+        try:
+            cancelled = not self._stream_playback(
+                reachy_mini, move_to_play,
+            )
+        finally:
+            self._playback_cancel_event.clear()
+            if audio_thread is not None:
+                if cancelled:
+                    # Force-stop audio immediately on user cancellation.
+                    audio_stop.set()
+                    audio_thread.join(timeout=3.0)
+                else:
+                    # Normal completion: let the audio thread finish naturally
+                    # (it may still be draining its buffer since chunks are
+                    # pushed ~20% faster than real-time).
+                    audio_thread.join(timeout=max(10.0, move_to_play.duration))
+                    audio_stop.set()  # cleanup: ensure thread exits
+
+        if cancelled:
+            self._set_state(
+                mode="idle",
+                message=f"Playback stopped for {meta.label}",
+                active_move=None,
+            )
+        else:
+            self._set_state(
+                mode="idle",
+                message=f"Finished playing {meta.label}",
+                active_move=None,
+            )
+
+    # ──────── Capture helpers ─────────────────────────────────────────
+
+    def _capture_motion(
+        self,
+        reachy_mini: object,
+        stop_event: threading.Event,
+        duration: float,
+        record_audio: bool,
+        record_motion: bool = True,
+        on_capture_start: Callable[[], None] | None = None,
+    ) -> tuple[list[float], list[dict[str, Any]], list[np.ndarray], int | None]:
+        timestamps: list[float] = []
+        frames: list[dict[str, Any]] = []
+        audio_frames: list[np.ndarray] = []
+        audio_samplerate: int | None = None
+        audio_active = False
+
+        def _pull_audio_frames(max_seconds: float = 1.0) -> None:
+            if not audio_active:
+                return
+            deadline = time.perf_counter() + max_seconds
+            while time.perf_counter() < deadline:
+                sample = reachy_mini.media.get_audio_sample()
+                if sample is None:
+                    break
+                audio_frames.append(sample)
+
+        if record_audio and self._audio_available:
+            try:
+                reachy_mini.media.start_recording()
+                audio_active = True
+                reported_rate = reachy_mini.media.get_input_audio_samplerate()
+                audio_samplerate = int(reported_rate) if reported_rate else AUDIO_SAMPLE_RATE
+            except Exception as exc:  # pragma: no cover - runtime audio failure
+                self._set_state(
+                    mode="error",
+                    message=f"Audio init failed: {exc}",
+                    active_move=None,
+                )
+                record_audio = False
+                audio_active = False
+
+        start = time.perf_counter()
+        # Update recording_started_at to the actual capture start (after audio init).
+        # Without this, the frontend progress bar is ahead by the audio init delay (~0.5s).
+        self._set_state(recording_started_at=time.time())
+        if on_capture_start is not None:
+            try:
+                on_capture_start()
+            except Exception as exc:
+                logger.warning("Capture start hook failed: %s", exc)
+
+        # Hard time guard: if an SDK call hangs mid-iteration, bail out
+        # after duration + generous margin rather than blocking forever.
+        hard_deadline = start + duration + 10.0
+
+        # Capture loop: read pose at MOTION_SAMPLE_RATE (100 Hz).
+        # We use perf_counter for timestamps (monotonic, high-resolution)
+        # while time.time() is used for server_time (wall clock for frontend sync).
+        sample_period = 1.0 / MOTION_SAMPLE_RATE
+        try:
+            while not stop_event.is_set() and not self._recording_cancel_event.is_set():
+                elapsed = time.perf_counter() - start
+                if elapsed >= duration:
+                    break
+                if time.perf_counter() > hard_deadline:
+                    logger.error("Capture loop exceeded hard deadline — aborting")
+                    break
+                if record_motion:
+                    try:
+                        head_pose = reachy_mini.get_current_head_pose()
+                        head_joints, antennas = reachy_mini.get_current_joint_positions()
+                    except Exception as exc:
+                        logger.warning("SDK call failed during capture: %s", exc)
+                        break
+                    timestamps.append(elapsed)
+                    frames.append(
+                        {
+                            "head": np.asarray(head_pose, dtype=float).tolist(),
+                            "antennas": np.asarray(antennas, dtype=float).tolist(),
+                            "body_yaw": float(head_joints[0]) if head_joints else 0.0,
+                            "check_collision": False,
+                        }
+                    )
+                else:
+                    timestamps.append(elapsed)
+                stop_event.wait(sample_period)
+                _pull_audio_frames()
+        finally:
+            if audio_active:
+                stopped_ok = False
+                try:
+                    stopped_ok = call_with_timeout(
+                        reachy_mini.media.stop_recording, timeout=3.0
+                    )
+                except Exception as exc:
+                    logger.warning("stop_recording() failed: %s", exc)
+                if stopped_ok:
+                    _pull_audio_frames()
+                else:
+                    logger.warning(
+                        "Skipping audio drain — stop_recording did not complete"
+                    )
+        return timestamps, frames, audio_frames, audio_samplerate
+
+    def _stream_playback(
+        self,
+        reachy_mini: object,
+        move: RecordedMove,
+        sample_hook: Callable[[], None] | None = None,
+        start_signal: threading.Event | None = None,
+    ) -> bool:
+        """Stream a RecordedMove to the robot at 100 Hz.
+
+        Returns True if playback completed normally, False if cancelled.
+        Fires start_signal after the first motion command so audio can begin
+        in sync with the physical movement.
+        """
+        sleep_period = 1.0 / MOTION_SAMPLE_RATE
+        t0 = time.perf_counter()
+        signalled = False
+        while True:
+            if self._playback_cancel_event.is_set():
+                return False
+            elapsed = time.perf_counter() - t0
+            if elapsed >= move.duration:
+                break
+            t = min(max(elapsed, 0.0), max(move.duration - 1e-3, 0.0))
+            try:
+                head, antennas, body_yaw = move.evaluate(t)
+                reachy_mini.set_target_head_pose(head)
+                if body_yaw is not None:
+                    reachy_mini.set_target_body_yaw(float(body_yaw))
+                if antennas is not None:
+                    reachy_mini.set_target_antenna_joint_positions(list(antennas))
+            except Exception as exc:
+                logger.error("Playback command failed at t=%.2f: %s", t, exc)
+                break
+            if not signalled and start_signal is not None:
+                start_signal.set()
+                signalled = True
+            if sample_hook is not None:
+                sample_hook()
+
+            remaining = move.duration - elapsed
+            wait_time = max(0.001, min(sleep_period, remaining))
+            if self._playback_cancel_event.wait(wait_time):
+                return False
+
+        # Ensure start_signal fires even if the loop exited early, so
+        # the audio thread isn't left waiting on start_signal.wait().
+        if not signalled and start_signal is not None:
+            start_signal.set()
+        return True
+
+    def _apply_motion_model(self, move: RecordedMove) -> RecordedMove:
+        try:
+            return self._motion_model_registry.apply(move)
+        except Exception as exc:
+            logger.warning("Motion model %s failed: %s", self._motion_model_registry.active, exc)
+            return move
+
+    def _save_recording(
+        self,
+        request: RecordingRequest,
+        timestamps: list[float],
+        frames: list[dict[str, Any]],
+        audio_frames: list[np.ndarray],
+        audio_samplerate: int | None,
+    ) -> None:
+        json_path = self._dataset_dir / f"{request.move_id}.json"
+        wav_path = json_path.with_suffix(".wav")
+
+        data: dict[str, Any] = {
+            "description": request.description,
+            "time": timestamps,
+            "set_target_data": frames,
+        }
+        if not request.record_motion:
+            data["audio_only"] = True
+
+        json_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+        # Handle audio: either copy uploaded file or save mic recording
+        if request.uploaded_audio_path and request.uploaded_audio_path.exists():
+            # Copy uploaded audio to move's wav path.
+            # Keep the temp file so the user can record again with the same upload.
+            shutil.copy2(str(request.uploaded_audio_path), str(wav_path))
+        elif request.record_audio and audio_frames and self._audio_available and audio_samplerate:
+            audio_data = np.concatenate(audio_frames, axis=0)
+            sf.write(str(wav_path), audio_data, audio_samplerate)  # type: ignore[arg-type]
+
+    def _load_move(self, json_path: Path) -> RecordedMove:
+        move = json.loads(json_path.read_text(encoding="utf-8"))
+        sound_path = json_path.with_suffix(".wav")
+        return RecordedMove(move, sound_path if sound_path.exists() else None)
+
+    def _build_recording_request(
+        self, payload: StartRecordingPayload, uploaded_audio_path: Path | None = None
+    ) -> RecordingRequest:
+        stamp = datetime.utcnow().strftime("%Y%m%d-%H%M%S")
+        base_name = payload.label or f"take-{stamp}"
+        label = payload.label or f"Take {stamp}"
+        slug = _slugify(base_name)
+        move_id = slug
+        index = 1
+        while (self._dataset_dir / f"{move_id}.json").exists():
+            move_id = f"{slug}-{index}"
+            index += 1
+
+        description = payload.description or f"Recorded with Marionette on {stamp}"
+
+        return RecordingRequest(
+            move_id=move_id,
+            label=label,
+            description=description,
+            duration=float(payload.duration),
+            record_audio=bool(payload.record_audio),
+            record_motion=bool(payload.record_motion),
+            uploaded_audio_path=uploaded_audio_path,
+        )
+
+    def _refresh_recordings(self) -> None:
+        """Scan the active dataset's data/ dir and rebuild the in-memory recordings dict.
+
+        Called after any change that affects the moves list (record, delete,
+        dataset switch). The result is protected by _state_lock so the HTTP
+        thread always sees a consistent snapshot.
+        """
+        recordings: dict[str, RecordingMetadata] = {}
+        # Get uploaded move IDs for the active dataset
+        active_entry = self._datasets.get(self._active_dataset_id or "")
+        uploaded_ids = active_entry.uploaded_move_ids if active_entry else set()
+
+        for json_path in sorted(self._dataset_dir.glob("*.json")):
+            try:
+                move = json.loads(json_path.read_text(encoding="utf-8"))
+                timestamps = move.get("time", [])
+                duration = (
+                    float(timestamps[-1]) - float(timestamps[0])
+                    if len(timestamps) >= 2
+                    else float(timestamps[0]) if timestamps else 0.0
+                )
+                description = move.get("description", "")
+                has_audio = json_path.with_suffix(".wav").exists()
+                move_id = json_path.stem
+                recordings[move_id] = RecordingMetadata(
+                    move_id=move_id,
+                    label=move_id,
+                    description=description,
+                    duration=duration,
+                    created_at=json_path.stat().st_mtime,
+                    json_path=json_path,
+                    has_audio=has_audio,
+                    is_uploaded=move_id in uploaded_ids,
+                    audio_only=bool(move.get("audio_only", False)),
+                )
+            except Exception:
+                continue
+
+        with self._state_lock:
+            self._recordings = recordings

marionette/routes.py

@@ -0,0 +1,430 @@
+"""FastAPI route registration for the Marionette app.
+
+All HTTP endpoints are defined here as closures that capture a reference
+to the Marionette instance.  This keeps routes thin — they validate input,
+delegate to the appropriate method, and return the result.
+"""
+from __future__ import annotations
+
+import logging
+import platform
+import uuid
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from fastapi import HTTPException, UploadFile, File
+
+from marionette.audio import get_audio_duration
+from marionette.models import (
+    DATASET_DATA_SUBDIR,
+    CreateDatasetPayload,
+    DownloadDatasetPayload,
+    HfTokenPayload,
+    PlayMovePayload,
+    RobotAudioSelectPayload,
+    SelectDatasetPayload,
+    StartRecordingPayload,
+    SyncDatasetPayload,
+    UpdateDatasetRootPayload,
+    UpdateExperimentsPayload,
+    UpdateLeadCompensationPayload,
+)
+
+try:
+    import soundfile as sf
+except Exception:  # pragma: no cover
+    sf = None
+
+if TYPE_CHECKING:
+    from marionette.app import Marionette
+
+logger = logging.getLogger(__name__)
+
+# Shared temp directory for uploaded and downloaded audio files.
+_TEMP_UPLOADS_DIR = Path(__file__).resolve().parent.parent / "temp_uploads"
+
+
+def register_routes(app: Marionette, *, version: str) -> None:
+    """Register all FastAPI endpoints on *app*.settings_app."""
+    # Import the datasets MODULE (not individual names) so that references
+    # like _ds.hf_login are resolved at call time.  This is critical for
+    # testing: tests monkeypatch marionette.datasets.hf_login, and if we
+    # had imported `from marionette.datasets import hf_login`, the closure
+    # would capture the original function, not the monkeypatched one.
+    import marionette.datasets as _ds
+
+    assert app.settings_app is not None
+
+    @app.settings_app.get("/api/state")
+    def get_state() -> dict[str, Any]:
+        return app._serialize_state()
+
+    @app.settings_app.get("/api/version")
+    def get_version() -> dict[str, str]:
+        return {"version": version, "platform": platform.system(), "hostname": platform.node()}
+
+    # Dummy endpoint to silence 404 spam from external tools
+    @app.settings_app.get("/sensor_data")
+    def sensor_data() -> dict[str, Any]:
+        return {}
+
+    @app.settings_app.post("/api/upload-audio")
+    async def upload_audio(file: UploadFile = File(...)) -> dict[str, Any]:
+        if not file.filename:
+            raise HTTPException(status_code=400, detail="No file provided.")
+        ext = Path(file.filename).suffix.lower()
+        if ext not in {".wav", ".mp3"}:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Unsupported audio format '{ext}'. Use .wav or .mp3.",
+            )
+        upload_id = str(uuid.uuid4())
+        temp_dir = _TEMP_UPLOADS_DIR
+        temp_dir.mkdir(parents=True, exist_ok=True)
+        temp_path = temp_dir / f"{upload_id}{ext}"
+        try:
+            content = await file.read()
+            temp_path.write_bytes(content)
+        except Exception as exc:
+            raise HTTPException(status_code=500, detail=f"Failed to save upload: {exc}") from exc
+
+        # Convert MP3 to WAV for better playback quality
+        duration: float | None = None
+        if ext == ".mp3" and sf is not None:
+            try:
+                data, samplerate = sf.read(str(temp_path))
+                wav_path = temp_dir / f"{upload_id}.wav"
+                # Resample to 48kHz for better quality (common output rate)
+                target_rate = 48000
+                if samplerate != target_rate:
+                    try:
+                        from scipy import signal
+                        original_rate = samplerate
+                        num_samples = int(len(data) * target_rate / samplerate)
+                        if data.ndim == 1:
+                            data = signal.resample(data, num_samples)
+                        else:
+                            data = signal.resample(data, num_samples, axis=0)
+                        samplerate = target_rate
+                        logger.info("Resampled audio from %d to %d Hz", original_rate, target_rate)
+                    except ImportError:
+                        logger.warning("scipy not available, skipping resample")
+                # Write as 16-bit PCM WAV for maximum compatibility
+                sf.write(str(wav_path), data, samplerate, subtype='PCM_16')
+                duration = len(data) / samplerate
+                # Remove original MP3 and use WAV
+                temp_path.unlink()
+                temp_path = wav_path
+                logger.info("Converted MP3 to WAV: %s", wav_path.name)
+            except Exception as exc:
+                logger.warning("MP3 to WAV conversion failed, using original: %s", exc)
+
+        # Get audio duration if not already determined
+        if duration is None:
+            duration = get_audio_duration(temp_path, fallback=None)
+
+        app._uploaded_audio[upload_id] = temp_path
+        return {"upload_id": upload_id, "filename": file.filename, "duration": duration}
+
+    @app.settings_app.post("/api/record")
+    def start_recording(payload: StartRecordingPayload) -> dict[str, Any]:
+        uploaded_audio_path: Path | None = None
+        if payload.uploaded_audio_id:
+            uploaded_audio_path = app._uploaded_audio.get(payload.uploaded_audio_id)
+            if not uploaded_audio_path or not uploaded_audio_path.exists():
+                raise HTTPException(
+                    status_code=400,
+                    detail="Uploaded audio file not found. Please re-upload.",
+                )
+        elif payload.record_audio and not app._audio_available:
+            raise HTTPException(
+                status_code=400,
+                detail="Audio capture backend unavailable.",
+            )
+
+        active_entry = app._datasets.get(app._active_dataset_id or "")
+        if active_entry and active_entry.origin == "downloaded":
+            raise HTTPException(
+                status_code=409,
+                detail="Cannot record into a downloaded dataset. Switch to a local dataset or create a new one.",
+            )
+
+        request = app._build_recording_request(payload, uploaded_audio_path)
+
+        with app._state_lock:
+            if (
+                app._mode not in {"idle", "queued"}
+                or app._pending_recording
+                or app._pending_playback
+            ):
+                raise HTTPException(status_code=409, detail="Robot is busy.")
+            app._preferred_duration = float(request.duration)
+            app._pending_recording = request
+            app._mode = "queued"
+            app._message = "Recording scheduled"
+            app._countdown_ends_at = None
+            app._active_record_started_at = None
+            app._active_record_duration = None
+        # Persist outside the lock — never do I/O while holding _state_lock
+        app._save_dataset_registry()
+
+        return {
+            "accepted": True,
+            "move_id": request.move_id,
+            "label": request.label,
+        }
+
+    @app.settings_app.post("/api/play")
+    def play_move(payload: PlayMovePayload) -> dict[str, Any]:
+        if payload.move_id not in app._recordings:
+            raise HTTPException(status_code=404, detail="Move not found.")
+
+        with app._state_lock:
+            if (
+                app._mode != "idle"
+                or app._pending_recording
+                or app._pending_playback
+            ):
+                raise HTTPException(status_code=409, detail="Robot is busy.")
+            app._pending_playback = payload.move_id
+            app._mode = "queued"
+            app._message = f"Playback queued for {payload.move_id}"
+
+        return {"accepted": True, "move_id": payload.move_id}
+
+    @app.settings_app.post("/api/play/stop")
+    def stop_playback() -> dict[str, Any]:
+        with app._state_lock:
+            if app._mode == "queued" and app._pending_playback is not None:
+                app._pending_playback = None
+                app._mode = "idle"
+                app._message = "Playback cancelled"
+                return {"stopped": True}
+            if app._mode != "playing":
+                return {"stopped": False, "reason": "not_playing"}
+            app._playback_cancel_event.set()
+        return {"stopped": True}
+
+    @app.settings_app.post("/api/record/stop")
+    def stop_recording() -> dict[str, Any]:
+        with app._state_lock:
+            if app._mode not in {"recording", "countdown", "queued", "preparing"}:
+                return {"stopped": False, "reason": "not_recording"}
+            if app._mode == "queued":
+                app._pending_recording = None
+                app._mode = "idle"
+                app._message = "Recording cancelled"
+                return {"stopped": True}
+            app._recording_cancel_event.set()
+        return {"stopped": True}
+
+    @app.settings_app.delete("/api/moves/{move_id}")
+    def delete_move(move_id: str) -> dict[str, Any]:
+        app._delete_move_files(move_id)
+        app._refresh_recordings()
+        return {"status": "deleted", "move_id": move_id}
+
+    @app.settings_app.get("/api/datasets")
+    def list_datasets() -> dict[str, Any]:
+        return app._datasets_payload()
+
+    @app.settings_app.post("/api/datasets")
+    def create_dataset(payload: CreateDatasetPayload) -> dict[str, Any]:
+        with app._state_lock:
+            if (
+                app._mode not in {"idle", "queued"}
+                or app._pending_recording
+                or app._pending_playback
+            ):
+                raise HTTPException(status_code=409, detail="Robot is busy.")
+            entry = app._create_dataset(payload.name, payload.label)
+            app._select_dataset(entry.dataset_id)
+        app._refresh_recordings()
+        return {"status": "created", "dataset": entry.to_payload()}
+
+    @app.settings_app.post("/api/datasets/select")
+    def select_dataset(payload: SelectDatasetPayload) -> dict[str, Any]:
+        with app._state_lock:
+            if (
+                app._mode not in {"idle", "queued"}
+                or app._pending_recording
+                or app._pending_playback
+            ):
+                raise HTTPException(status_code=409, detail="Robot is busy.")
+            app._select_dataset(payload.dataset_id)
+        app._refresh_recordings()
+        return {"status": "selected", "active_id": payload.dataset_id}
+
+    @app.settings_app.post("/api/datasets/sync")
+    def sync_dataset(payload: SyncDatasetPayload) -> dict[str, Any]:
+        with app._state_lock:
+            if (
+                app._mode not in {"idle", "queued"}
+                or app._pending_recording
+                or app._pending_playback
+            ):
+                raise HTTPException(status_code=409, detail="Robot is busy.")
+        username = payload.hf_username or app._check_hf_login()
+        if not username:
+            raise HTTPException(
+                status_code=400,
+                detail="No Hugging Face username provided and not logged in via CLI.",
+            )
+        result = app._sync_dataset(username, payload.move_ids, payload.dataset_slug)
+        return result
+
+    @app.settings_app.post("/api/datasets/root")
+    def update_dataset_root(payload: UpdateDatasetRootPayload) -> dict[str, Any]:
+        with app._state_lock:
+            if (
+                app._mode not in {"idle", "queued"}
+                or app._pending_recording
+                or app._pending_playback
+            ):
+                raise HTTPException(status_code=409, detail="Robot is busy.")
+            app._set_dataset_root(payload.path)
+        app._refresh_recordings()
+        return {"status": "updated", "root_path": str(app._dataset_root)}
+
+    @app.settings_app.get("/api/datasets/community")
+    def community_datasets() -> dict[str, Any]:
+        datasets = app._list_community_datasets()
+        return {"datasets": datasets}
+
+    @app.settings_app.post("/api/datasets/download")
+    def download_dataset(payload: DownloadDatasetPayload) -> dict[str, Any]:
+        with app._state_lock:
+            if app._mode not in {"idle", "queued"} or app._pending_recording or app._pending_playback:
+                raise HTTPException(status_code=409, detail="Robot is busy.")
+        entry = app._download_community_dataset(payload)
+        app._refresh_recordings()
+        return {"status": "downloaded", "dataset": entry.to_payload()}
+
+    @app.settings_app.post("/api/experiments")
+    def update_experiments(payload: UpdateExperimentsPayload) -> dict[str, Any]:
+        updates = payload.model_dump(exclude_none=True)
+        if not updates:
+            return {"status": "unchanged"}
+        with app._state_lock:
+            for key, value in updates.items():
+                if key == "duration_seconds":
+                    app._preferred_duration = float(value)
+                elif key == "welcome_messages":
+                    app._welcome_messages = max(0, min(2, int(value)))
+        app._save_dataset_registry()
+        return {
+            "status": "updated",
+            "preferred_duration": app._preferred_duration,
+            "motion_models": app._motion_model_registry.to_payload(),
+        }
+
+    @app.settings_app.post("/api/motion-model/lead")
+    def update_motion_model_lead(payload: UpdateLeadCompensationPayload) -> dict[str, Any]:
+        params = payload.model_dump(exclude_none=True)
+        if not params:
+            return {
+                "status": "unchanged",
+                "active": app._motion_model_registry.active,
+                "params": app._motion_model_registry.get_model_params("lead_compensation"),
+            }
+        try:
+            app._motion_model_registry.set_model_params("lead_compensation", params)
+        except KeyError as exc:
+            raise HTTPException(status_code=404, detail="Lead compensation model unavailable.") from exc
+        app._save_dataset_registry()
+        return {
+            "status": "updated",
+            "active": app._motion_model_registry.active,
+            "params": app._motion_model_registry.get_model_params("lead_compensation"),
+        }
+
+    @app.settings_app.post("/api/hf-auth/save-token")
+    def save_hf_token(payload: HfTokenPayload) -> dict[str, Any]:
+        if _ds.hf_login is None:
+            raise HTTPException(status_code=500, detail="huggingface_hub is not installed.")
+        token = payload.token.strip()
+        if not token.startswith("hf_"):
+            raise HTTPException(status_code=422, detail="Token must start with 'hf_'.")
+        try:
+            _ds.hf_login(token=token, add_to_git_credential=False)
+        except Exception as exc:
+            raise HTTPException(status_code=401, detail=f"Invalid token: {exc}") from exc
+        # Verify the token works
+        app._hf_checked = False
+        username = app._check_hf_login()
+        if not username:
+            raise HTTPException(status_code=401, detail="Token saved but could not verify identity.")
+        return {"status": "logged_in", "username": username}
+
+    @app.settings_app.delete("/api/hf-auth/token")
+    def delete_hf_token() -> dict[str, Any]:
+        if _ds.hf_logout is None:
+            raise HTTPException(status_code=500, detail="huggingface_hub is not installed.")
+        try:
+            _ds.hf_logout()
+        except Exception as exc:
+            logger.warning("HF logout error: %s", exc)
+        app._hf_username = None
+        app._hf_checked = False
+        return {"status": "logged_out"}
+
+    # ── Robot audio file listing ──────────────────────────────────
+
+    @app.settings_app.get("/api/robot-audio")
+    def list_robot_audio() -> dict[str, Any]:
+        """List WAV files from audio-only recordings (Record Audio button)."""
+        import json as _json
+
+        files: list[dict[str, Any]] = []
+        seen: set[str] = set()
+
+        for entry in app._datasets.values():
+            data_dir = entry.path / DATASET_DATA_SUBDIR
+            if not data_dir.is_dir():
+                continue
+            for json_path in data_dir.glob("*.json"):
+                try:
+                    meta = _json.loads(json_path.read_text(encoding="utf-8"))
+                except Exception:
+                    continue
+                if not meta.get("audio_only", False):
+                    continue
+                wav_path = json_path.with_suffix(".wav")
+                if not wav_path.exists():
+                    continue
+                real = str(wav_path.resolve())
+                if real not in seen:
+                    seen.add(real)
+                    files.append({
+                        "name": wav_path.stem,
+                        "path": real,
+                        "duration_seconds": get_audio_duration(wav_path, fallback=None),
+                    })
+
+        # Sort newest first so auto-select picks the latest recording
+        files.sort(key=lambda f: Path(f["path"]).stat().st_mtime, reverse=True)
+        return {"files": files}
+
+    @app.settings_app.post("/api/robot-audio/select")
+    def select_robot_audio(payload: RobotAudioSelectPayload) -> dict[str, Any]:
+        """Register a robot-side WAV file for use as recording audio."""
+        path = Path(payload.path).resolve()
+
+        # Security: only allow files within dataset dirs or temp_uploads
+        allowed_roots: list[Path] = [_TEMP_UPLOADS_DIR]
+        for entry in app._datasets.values():
+            allowed_roots.append(entry.path.resolve())
+
+        if not any(path == root or root in path.parents for root in allowed_roots):
+            raise HTTPException(
+                status_code=403,
+                detail="Access denied: file is outside allowed directories.",
+            )
+        if not path.exists() or not path.is_file():
+            raise HTTPException(status_code=404, detail="File not found.")
+        if path.suffix.lower() != ".wav":
+            raise HTTPException(status_code=400, detail="Only WAV files are supported.")
+
+        upload_id = str(uuid.uuid4())
+        app._uploaded_audio[upload_id] = path
+        return {"upload_id": upload_id, "filename": path.name, "duration": get_audio_duration(path, fallback=None)}

marionette/state.py

@@ -0,0 +1,117 @@
+"""State management mixin for the Marionette app.
+
+Provides thread-safe state serialization and mutation methods.
+The _state_lock (a threading.Lock) is defined on the Marionette instance;
+this mixin supplies the methods that read/write the protected fields.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from marionette.models import COUNTDOWN_SECONDS, DEFAULT_DURATION, MOTION_SAMPLE_RATE
+
+
+class StateMixin:
+    """Mixin providing state serialization and mutation helpers.
+
+    Expects the host class to have: _state_lock, _mode, _message,
+    _active_move, _countdown_ends_at, _active_record_started_at,
+    _active_record_duration, _recordings, _recording_stats,
+    _pending_recording, _pending_playback, _preferred_duration,
+    _audio_available, _dataset_dir, _dataset_root, _welcome_messages,
+    _motion_model_registry, _check_hf_login(), _datasets_payload().
+    """
+
+    # Sentinel value to distinguish "not passed" from None in _set_state().
+    # We can't use None as default because None is a valid value for
+    # active_move, countdown_ends_at, etc.
+    _UNSET = object()
+
+    def _serialize_state(self) -> dict[str, Any]:
+        # Resolve HF username BEFORE acquiring the lock — _check_hf_login()
+        # may call hf_whoami() (a network round-trip) on first invocation,
+        # and we must never hold the lock during I/O.
+        hf_username = self._check_hf_login()
+
+        with self._state_lock:
+            moves = sorted(
+                (meta.to_payload() for meta in self._recordings.values()),
+                key=lambda entry: entry["created_at"],
+                reverse=True,
+            )
+            # Unified timing sent to the frontend for overlay animations.
+            # The frontend uses (phase_start_at, phase_end_at) + clock offset
+            # to render a smooth countdown or recording progress bar.
+            phase_start_at: float | None = None
+            phase_end_at: float | None = None
+            if self._mode == "countdown" and self._countdown_ends_at is not None:
+                phase_start_at = self._countdown_ends_at - COUNTDOWN_SECONDS
+                phase_end_at = self._countdown_ends_at
+            elif self._mode == "recording" and self._active_record_started_at is not None:
+                phase_start_at = self._active_record_started_at
+                if self._active_record_duration is not None:
+                    phase_end_at = self._active_record_started_at + self._active_record_duration
+
+            return {
+                "server_time": time.time(),
+                "mode": self._mode,
+                "message": self._message,
+                "active_move": self._active_move,
+                "phase_start_at": phase_start_at,
+                "phase_end_at": phase_end_at,
+                "countdown_ends_at": self._countdown_ends_at,
+                "recording_started_at": self._active_record_started_at,
+                "recording_duration": self._active_record_duration,
+                "recording_stats": self._recording_stats,
+                "pending_recording": self._pending_recording.label if self._pending_recording else None,
+                "pending_playback": self._pending_playback,
+                "moves": moves,
+                "config": {
+                    "default_duration": DEFAULT_DURATION,
+                    "preferred_duration": self._preferred_duration,
+                    "countdown_seconds": COUNTDOWN_SECONDS,
+                    "motion_sample_rate": MOTION_SAMPLE_RATE,
+                    "audio_available": self._audio_available,
+                    "active_dataset_path": str(self._dataset_dir),
+                    "dataset_root_path": str(self._dataset_root),
+                    "hf_username": hf_username,
+                    "motion_models": self._motion_model_registry.to_payload(),
+                    "welcome_messages": self._welcome_messages,
+                },
+                "datasets": self._datasets_payload(),
+            }
+
+    def _set_state(
+        self,
+        *,
+        mode: str | None = None,
+        message: str | None = None,
+        active_move: object = _UNSET,
+        countdown_ends_at: object = _UNSET,
+        recording_started_at: object = _UNSET,
+        recording_duration: object = _UNSET,
+    ) -> None:
+        with self._state_lock:
+            if mode is not None:
+                self._mode = mode
+            if message is not None:
+                self._message = message
+            if active_move is not self._UNSET:
+                self._active_move = active_move
+            if countdown_ends_at is not self._UNSET:
+                self._countdown_ends_at = countdown_ends_at
+            if recording_started_at is not self._UNSET:
+                self._active_record_started_at = recording_started_at
+            if recording_duration is not self._UNSET:
+                self._active_record_duration = recording_duration
+
+    def _set_idle_state(self) -> None:
+        self._set_state(
+            mode="idle",
+            message="Ready to capture moves",
+            active_move=None,
+            countdown_ends_at=None,
+            recording_started_at=None,
+            recording_duration=None,
+        )

marionette/static/index.html

@@ -26,17 +26,70 @@
     </div>
   </header>
 
-  <!-- ════════ RECORD HERO ════════ -->
+  <!-- ════════ RECORD HERO — Two buttons: Record Move + Record Audio ════════ -->
   <section class="record-hero fade-in fade-in-1" id="record-hero">
     <p class="record-hero-tagline">
       Move Reachy Mini's head with your hands to create animated movements with sound
     </p>
-    <div class="record-ring">
-      <button class="record-btn" id="record-btn" title="Start Recording">
-        <span class="rec-icon"></span>
-        <span class="rec-label">Record</span>
-      </button>
+
+    <div class="record-actions">
+      <!-- PRIMARY: Record a motion (with optional audio source) -->
+      <div class="record-action-block">
+        <div class="record-ring">
+          <button class="record-btn" id="record-btn" title="Record Move">
+            <span class="rec-icon"></span>
+            <span class="rec-label">Record Move</span>
+          </button>
+        </div>
+
+        <!-- Audio source: inline below Record Move button -->
+        <div class="audio-source-panel" id="audio-source-panel">
+          <span class="audio-source-label">Audio source</span>
+          <p class="audio-source-hint">Plays during recording so you can sync your movements</p>
+          <div class="audio-source-tabs">
+            <label class="audio-tab">
+              <input type="radio" name="audio-src" value="silent" checked/> Silent
+            </label>
+            <label class="audio-tab">
+              <input type="radio" name="audio-src" value="upload"/> Upload
+            </label>
+            <label class="audio-tab">
+              <input type="radio" name="audio-src" value="robot"/> Robot file
+            </label>
+          </div>
+
+          <!-- Upload zone (visible when 'upload' is selected) -->
+          <div id="audio-upload-section" style="display:none">
+            <div class="audio-upload-zone" id="audio-upload-zone">
+              Drop a WAV or MP3 here, or click to browse
+              <input type="file" id="audio-file-input" accept=".wav,.mp3,audio/wav,audio/mpeg"/>
+            </div>
+            <p class="audio-upload-status" id="audio-upload-status"></p>
+          </div>
+
+          <!-- Robot file (visible when 'robot' is selected) -->
+          <div id="robot-audio-section" style="display:none">
+            <select class="dataset-select" id="robot-audio-select">
+              <option value="">Select audio file...</option>
+            </select>
+          </div>
+        </div>
+      </div>
+
+      <!-- SECONDARY: Record audio only (mic, no motion) -->
+      <div class="record-action-block">
+        <div class="record-ring record-ring-audio">
+          <button class="record-btn record-btn-audio" id="record-audio-btn" title="Record Audio">
+            <span class="rec-icon-audio">&#127908;</span>
+            <span class="rec-label">Record Audio</span>
+          </button>
+        </div>
+        <p class="record-hint-small">Mic only, no motion</p>
+        <p class="record-audio-hint">Audio recordings appear in your moves list and under &ldquo;Robot file&rdquo; for use as a soundtrack during motion recording.</p>
+      </div>
     </div>
+
+    <!-- Shared name + duration fields -->
     <div class="record-fields">
       <div class="record-field">
         <label for="rec-name">Name</label>
@@ -47,6 +100,7 @@
         <input type="number" id="rec-duration" min="0.5" max="300" step="any" placeholder="5.0"/>
       </div>
     </div>
+    <p class="audio-selection-status" id="audio-selection-status">Audio: Silent</p>
     <p class="record-hint">3 seconds to prepare before recording starts</p>
     <p class="downloaded-warning" id="downloaded-warning">
       Switch to a local dataset to record new moves
@@ -55,14 +109,17 @@
 
   <!-- ════════ SECTION TABS ════════ -->
   <nav class="section-tabs fade-in fade-in-2">
-    <button class="section-tab active" data-tab="moves">
-      Moves <span class="tab-count" id="moves-count">0</span>
+    <button class="section-tab active" data-tab="my-moves">
+      My Moves <span class="tab-count" id="my-moves-count">0</span>
+    </button>
+    <button class="section-tab" data-tab="library">
+      Library <span class="tab-count" id="library-count">0</span>
     </button>
     <button class="section-tab" data-tab="community">Community</button>
   </nav>
 
-  <!-- ════════ MOVES TAB ════════ -->
-  <div class="tab-panel active" id="tab-moves">
+  <!-- ════════ MY MOVES TAB ════════ -->
+  <div class="tab-panel active" id="tab-my-moves">
     <div class="moves-toolbar">
       <div class="moves-toolbar-left">
         <div class="dataset-bar">
@@ -89,12 +146,26 @@
     </div>
   </div>
 
+  <!-- ════════ LIBRARY TAB ════════ -->
+  <div class="tab-panel" id="tab-library">
+    <div class="moves-toolbar">
+      <div class="moves-toolbar-left">
+        <div class="dataset-bar">
+          <select class="dataset-select" id="library-dataset-select"></select>
+        </div>
+      </div>
+    </div>
+    <div id="library-moves-list">
+      <div class="moves-empty">
+        <div class="moves-empty-icon">&#11088;</div>
+        Download datasets from the Community tab to see them here
+      </div>
+    </div>
+  </div>
+
   <!-- ════════ COMMUNITY TAB ════════ -->
   <div class="tab-panel" id="tab-community">
     <div class="community-toolbar">
-      <button class="community-fetch-btn" id="fetch-community-btn">
-        Fetch community datasets
-      </button>
       <button class="community-download-btn" id="download-community-btn" disabled>
         Download selected
       </button>
@@ -122,32 +193,6 @@
     <button class="settings-close" id="settings-close">&times;</button>
   </div>
 
-  <!-- Audio source: mic (default), upload file, or silent -->
-  <div class="settings-section">
-    <h3>Audio Source</h3>
-    <div class="settings-radio-group">
-      <label class="settings-radio">
-        <input type="radio" name="audio-src" value="mic" checked/> Mic
-      </label>
-      <label class="settings-radio">
-        <input type="radio" name="audio-src" value="upload"/> Upload
-      </label>
-      <label class="settings-radio">
-        <input type="radio" name="audio-src" value="none"/> Silent
-      </label>
-      <label class="settings-radio">
-        <input type="radio" name="audio-src" value="mic-only"/> Mic only (no motion)
-      </label>
-    </div>
-    <div id="audio-upload-section" style="display:none">
-      <div class="audio-upload-zone" id="audio-upload-zone">
-        Drop a WAV or MP3 here, or click to browse
-        <input type="file" id="audio-file-input" accept=".wav,.mp3,audio/wav,audio/mpeg"/>
-      </div>
-      <p class="audio-upload-status" id="audio-upload-status"></p>
-    </div>
-  </div>
-
   <!-- Hugging Face login -->
   <div class="settings-section">
     <h3>Hugging Face</h3>

marionette/static/main.js

@@ -1,21 +1,26 @@
 /* ═══════════════════════════════════════════════════════════════════════
    MARIONETTE FRONTEND — JavaScript
 
-   Architecture overview:
-   ────────────────────
-   1. STATE POLLING: fetchState() runs every 1500ms (200ms during active phases),
-      calls GET /api/state, and passes the response to updateUI().
-
-   2. UI UPDATE: updateUI() is the single function that synchronizes all
-      DOM elements with the backend state. It's called after every poll
-      and after every user action.
+   Architecture overview
+   ─────────────────────
+   1. STATE POLLING: fetchState() runs every 1500 ms (200 ms during active
+      phases), calls GET /api/state, and passes the response to updateUI().
+
+   2. UI UPDATE: updateUI() synchronises lightweight DOM elements with the
+      backend state: the mode badge, the busy flag, the record-button
+      appearance, and the phase-overlay timing variables.  Heavy DOM work
+      (moves list, dataset dropdown) is ONLY done when a "dirty" flag is
+      set — which happens exclusively after user actions that change data
+      (record, delete, dataset switch …).  This prevents the 1.5 s polling
+      loop from rebuilding DOM and causing visual flickering.
 
    3. PHASE ANIMATION: A requestAnimationFrame loop continuously updates
-      the countdown/recording overlay based on phase_start_at / phase_end_at
-      timestamps from the backend.
+      the countdown / recording overlay based on phase_start_at /
+      phase_end_at timestamps from the backend.
 
-   4. EVENT HANDLERS: All user interactions (record, play, delete, etc.)
-      send the appropriate API call and then trigger a state refresh.
+   4. EVENT HANDLERS: All user interactions (record, play, delete …) send
+      the appropriate API call, set dirty flags, then trigger a state
+      refresh via fetchState().
    ═══════════════════════════════════════════════════════════════════════ */
 
 
@@ -23,119 +28,129 @@
 // SECTION 1: APP STATE & ELEMENT REFERENCES
 // ═══════════════════════════════════════════════════════════════════════
 
-let lastState = null;     // Last received state from backend
-let busy = false;         // True when mode is not idle/queued
-let clockOffset = 0;      // Diff between server clock and local clock (seconds, NTP-style)
-let clockOffsetSamples = 0; // Number of clock offset measurements taken
-let bestRtt = Infinity;   // Lowest RTT seen (best clock sync sample)
-let phaseMode = 'idle';   // Current phase for overlay: 'idle', 'countdown', 'recording'
-let phaseStartAt = null;  // Server timestamp: when current phase started
-let phaseEndAt = null;    // Server timestamp: when current phase ends
-let countdownEndAt = null;  // Server timestamp: when countdown ends (= recording starts)
-let recordingEndAt = null;  // Server timestamp: when recording ends
-let requestedDuration = null; // Duration the user requested (seconds), for predicting recording end
-let selectedMoves = new Set();    // Move IDs selected for HF upload
-let communitySelection = new Set(); // Community dataset repo_ids selected for download
-let uploadedAudioId = null;       // ID of uploaded audio file (from /api/upload-audio)
-let uploadedAudioFilename = null; // Original filename of uploaded audio
-let stopping = false;             // True while a stop request is in flight (debounce)
-let datasetSwitching = false;     // True while a dataset select is in flight (prevents dropdown snap-back)
-let pollingHandle = null;         // setTimeout handle for adaptive state polling
-let stateSeq = 0;         // Monotonic counter to ignore out-of-order responses
-let latestSeq = 0;        // Highest seq we've processed
-let hfUsername = null;     // Auto-detected HF username (from backend)
+let lastState = null;          // Last received state from backend
+let busy = false;              // True when mode is not idle/queued
+let clockOffset = 0;           // Diff between server clock and local clock (seconds)
+let clockOffsetSamples = 0;    // Number of clock-offset measurements taken
+let bestRtt = Infinity;        // Lowest round-trip time seen (best clock sample)
+let phaseMode = 'idle';        // 'idle' | 'countdown' | 'recording' | …
+let phaseStartAt = null;       // Server timestamp: current phase started
+let phaseEndAt = null;         // Server timestamp: current phase ends
+let countdownEndAt = null;     // Server timestamp: countdown ends (= recording starts)
+let recordingEndAt = null;     // Server timestamp: recording ends
+let requestedDuration = null;  // Duration the user requested (for prediction)
+let selectedMoves = new Set(); // Move IDs checked for HF upload
+let communitySelection = new Set(); // Community dataset repo_ids selected
+let uploadedAudioId = null;    // ID from /api/upload-audio or /api/robot-audio/select
+let uploadedAudioFilename = null;
+let stopping = false;          // Debounce: true while a stop request is in flight
+let datasetSwitching = false;  // True while dataset select is in flight
+let pollingHandle = null;      // setTimeout handle for adaptive polling
+let stateSeq = 0;              // Monotonic counter — ignore out-of-order responses
+let latestSeq = 0;             // Highest seq processed
+let hfUsername = null;          // Auto-detected HF username
+
+// ── Dirty flags ──
+// When true, the next updateUI() call will do a full DOM rebuild for that
+// section.  They start as true so the first poll populates everything.
+let movesListDirty = true;
+let datasetsDirty = true;
+let libraryDirty = true;
+let lastLocalDatasetId = null;
 
 const STORAGE_KEYS = {
   moveLabel: 'marionette.last_move_label',
 };
 
-/* DOM element references — gathered once at startup */
-const $modeBadge = document.getElementById('mode-badge');
-const $recordBtn = document.getElementById('record-btn');
-const $recName = document.getElementById('rec-name');
-const $recDuration = document.getElementById('rec-duration');
+/* DOM element references — gathered once at startup.
+   We use the convention $name for DOM elements. */
+const $modeBadge        = document.getElementById('mode-badge');
+const $recordBtn        = document.getElementById('record-btn');
+const $recordAudioBtn   = document.getElementById('record-audio-btn');
+const $recName          = document.getElementById('rec-name');
+const $recDuration      = document.getElementById('rec-duration');
 const $downloadedWarning = document.getElementById('downloaded-warning');
-const $movesList = document.getElementById('moves-list');
-const $movesCount = document.getElementById('moves-count');
-const $uploadBar = document.getElementById('upload-bar');
-const $uploadCount = document.getElementById('upload-count');
-const $uploadBtn = document.getElementById('upload-btn');
-const $datasetSelect = document.getElementById('dataset-select');
-const $newDatasetBtn = document.getElementById('new-dataset-btn');
+const $movesList        = document.getElementById('moves-list');
+const $myMovesCount     = document.getElementById('my-moves-count');
+const $libraryCount     = document.getElementById('library-count');
+const $libraryDatasetSelect = document.getElementById('library-dataset-select');
+const $libraryMovesList = document.getElementById('library-moves-list');
+const $uploadBar        = document.getElementById('upload-bar');
+const $uploadCount      = document.getElementById('upload-count');
+const $uploadBtn        = document.getElementById('upload-btn');
+const $datasetSelect    = document.getElementById('dataset-select');
+const $newDatasetBtn    = document.getElementById('new-dataset-btn');
 const $newDatasetInline = document.getElementById('new-dataset-inline');
-const $newDatasetInput = document.getElementById('new-dataset-input');
+const $newDatasetInput  = document.getElementById('new-dataset-input');
 const $createDatasetBtn = document.getElementById('create-dataset-btn');
 const $cancelDatasetBtn = document.getElementById('cancel-dataset-btn');
-const $settingsBtn = document.getElementById('settings-btn');
+const $settingsBtn      = document.getElementById('settings-btn');
 const $settingsBackdrop = document.getElementById('settings-backdrop');
-const $settingsDrawer = document.getElementById('settings-drawer');
-const $settingsClose = document.getElementById('settings-close');
-const $phaseOverlay = document.getElementById('phase-overlay');
-const $phaseNumber = document.getElementById('phase-number');
-const $phaseSublabel = document.getElementById('phase-sublabel');
-const $phaseFill = document.getElementById('phase-fill');
-const $phaseStopBtn = document.getElementById('phase-stop-btn');
-const $hfStatus = document.getElementById('hf-status');
-const $hfHint = document.getElementById('hf-hint');
-const $hfLoginForm = document.getElementById('hf-login-form');
-const $hfTokenInput = document.getElementById('hf-token-input');
-const $hfLoginBtn = document.getElementById('hf-login-btn');
-const $hfLogoutSection = document.getElementById('hf-logout-section');
-const $hfLogoutBtn = document.getElementById('hf-logout-btn');
+const $settingsDrawer   = document.getElementById('settings-drawer');
+const $settingsClose    = document.getElementById('settings-close');
+const $phaseOverlay     = document.getElementById('phase-overlay');
+const $phaseNumber      = document.getElementById('phase-number');
+const $phaseSublabel    = document.getElementById('phase-sublabel');
+const $phaseFill        = document.getElementById('phase-fill');
+const $phaseStopBtn     = document.getElementById('phase-stop-btn');
+const $hfStatus         = document.getElementById('hf-status');
+const $hfHint           = document.getElementById('hf-hint');
+const $hfLoginForm      = document.getElementById('hf-login-form');
+const $hfTokenInput     = document.getElementById('hf-token-input');
+const $hfLoginBtn       = document.getElementById('hf-login-btn');
+const $hfLogoutSection  = document.getElementById('hf-logout-section');
+const $hfLogoutBtn      = document.getElementById('hf-logout-btn');
 const $datasetRootInput = document.getElementById('dataset-root-input');
-const $datasetRootHint = document.getElementById('dataset-root-hint');
-const $updateRootBtn = document.getElementById('update-root-btn');
-const $leadFramesHead = document.getElementById('lead-frames-head');
+const $datasetRootHint  = document.getElementById('dataset-root-hint');
+const $updateRootBtn    = document.getElementById('update-root-btn');
+const $leadFramesHead   = document.getElementById('lead-frames-head');
 const $leadFramesAntennas = document.getElementById('lead-frames-antennas');
-const $fetchCommunityBtn = document.getElementById('fetch-community-btn');
 const $downloadCommunityBtn = document.getElementById('download-community-btn');
-const $communityStatus = document.getElementById('community-status');
-const $communityList = document.getElementById('community-list');
-const $audioFileInput = document.getElementById('audio-file-input');
-const $audioUploadZone = document.getElementById('audio-upload-zone');
+const $communityStatus  = document.getElementById('community-status');
+const $communityList    = document.getElementById('community-list');
+const $audioFileInput   = document.getElementById('audio-file-input');
+const $audioUploadZone  = document.getElementById('audio-upload-zone');
 const $audioUploadSection = document.getElementById('audio-upload-section');
 const $audioUploadStatus = document.getElementById('audio-upload-status');
+const $robotAudioSection = document.getElementById('robot-audio-section');
+const $robotAudioSelect = document.getElementById('robot-audio-select');
+const $audioSelectionStatus = document.getElementById('audio-selection-status');
 
 
 // ═══════════════════════════════════════════════════════════════════════
-// SECTION 2: STATE POLLING & CLOCK SYNCHRONIZATION
-//
-// CLOCK SYNC: We use an NTP-style algorithm to estimate the offset
-// between the server clock and the local clock. On each poll:
-//   1. Record local time BEFORE the request (t1)
-//   2. Server generates server_time during request handling (ts)
-//   3. Record local time AFTER the response arrives (t2)
-//   4. Estimate one-way latency as (t2 - t1) / 2
-//   5. offset = ts - (t1 + one_way_latency) = ts - (t1 + t2) / 2
+// SECTION 2: STATE POLLING & CLOCK SYNCHRONISATION
 //
-// We keep a running average of the best (lowest-latency) samples
-// for stability. This gives ~5-20ms accuracy on LAN/WiFi.
+// CLOCK SYNC (NTP-style):
+//   On each poll we measure the round-trip time (RTT) and estimate
+//   the offset between the server clock and the local clock.
+//     offset ≈ server_time − midpoint_of_local_times
+//   We weight towards the lowest-RTT sample for accuracy (~5–20 ms on
+//   LAN/WiFi).
 //
-// ADAPTIVE POLLING: During countdown/recording, we poll every 200ms
-// (instead of 1500ms) to get backend timestamps sooner. In idle
-// mode we poll every 1500ms to save resources.
+// ADAPTIVE POLLING:
+//   During countdown / recording / playing we poll every 200 ms so the
+//   phase overlay stays responsive.  In idle mode we poll every 1500 ms.
 // ═══════════════════════════════════════════════════════════════════════
 
-const POLL_IDLE_MS = 1500;    // Polling interval when idle
-const POLL_ACTIVE_MS = 200;   // Polling interval during countdown/recording
+const POLL_IDLE_MS   = 1500;
+const POLL_ACTIVE_MS = 200;
 
 async function fetchState() {
   const id = ++stateSeq;
-  const t1 = Date.now() / 1000; // Local Unix time before request (seconds)
+  const t1 = Date.now() / 1000;
   try {
     const r = await fetch('/api/state', { cache: 'no-store' });
     if (!r.ok) { scheduleNextPoll('idle'); return; }
     const data = await r.json();
-    const t2 = Date.now() / 1000; // Local Unix time after response (seconds)
-    if (id < latestSeq) return; // Ignore stale responses
+    const t2 = Date.now() / 1000;
+    if (id < latestSeq) return;          // stale response
     latestSeq = id;
 
-    // NTP-style clock offset calculation.
+    // NTP-style clock offset
     if (data.server_time) {
       const rtt = t2 - t1;
       const localMidpoint = (t1 + t2) / 2;
       const newOffset = data.server_time - localMidpoint;
-
       if (rtt < 0.5) {
         if (clockOffsetSamples === 0 || rtt < bestRtt) {
           clockOffset = newOffset;
@@ -149,8 +164,6 @@ async function fetchState() {
 
     updateUI(data);
     lastState = data;
-
-    // Adaptive polling: faster during active phases
     scheduleNextPoll(data.mode);
   } catch (e) {
     console.error('State poll failed:', e);
@@ -160,117 +173,143 @@ async function fetchState() {
 
 function scheduleNextPoll(mode) {
   clearTimeout(pollingHandle);
-  const isActive = ['countdown', 'recording', 'playing'].includes(mode);
+  const isActive = ['preparing', 'countdown', 'recording', 'playing'].includes(mode);
   pollingHandle = setTimeout(fetchState, isActive ? POLL_ACTIVE_MS : POLL_IDLE_MS);
 }
 
-function startPolling() {
-  fetchState(); // First poll immediately
-}
+function startPolling() { fetchState(); }
 
 
 // ═══════════════════════════════════════════════════════════════════════
-// SECTION 3: UI UPDATE — Single function that syncs all DOM with state
+// SECTION 3: UI UPDATE
+//
+// updateUI() is called after every poll AND after every user action.
+// It intentionally does ONLY lightweight work on each poll:
+//   - mode badge text
+//   - busy flag
+//   - record-button appearance
+//   - phase overlay timing variables
+//   - config fields (only when not focused by user)
+//
+// The expensive work — rebuilding the moves list and dataset dropdown —
+// is gated behind dirty flags that are set by user actions only.
+// This eliminates the flickering caused by DOM rebuilds every 1.5 s.
 // ═══════════════════════════════════════════════════════════════════════
 
 function updateUI(s) {
-  // ── Mode badge ──
-  $modeBadge.textContent = s.mode.toUpperCase();
-  $modeBadge.dataset.mode = s.mode;
+  // ── Mode badge (one text write, no DOM rebuild) ──
+  if ($modeBadge.textContent !== s.mode.toUpperCase()) {
+    $modeBadge.textContent = s.mode.toUpperCase();
+    $modeBadge.dataset.mode = s.mode;
+  }
 
-  // ── Busy flag — disables interactive controls ──
+  // ── Busy flag ──
   busy = !['idle', 'queued'].includes(s.mode);
 
-  // ── Record button state ──
+  // ── Record buttons state ──
   const activeEntry = s.datasets?.entries?.find(e => e.id === s.datasets?.active_id);
   const isDownloaded = activeEntry?.origin === 'downloaded';
   $recordBtn.disabled = busy || isDownloaded;
-
-  // Show warning when active dataset is downloaded (can't record into it)
+  if ($recordAudioBtn) $recordAudioBtn.disabled = busy;
   $downloadedWarning.classList.toggle('visible', isDownloaded && !busy);
-
-  // Visual state of record button
   $recordBtn.classList.toggle('is-recording', s.mode === 'recording');
   $recordBtn.classList.toggle('is-countdown', s.mode === 'countdown');
 
-  // ── Config (from state.config) ──
-  if (s.config) {
-    // Duration field placeholder from preferred duration
-    const dur = s.config.preferred_duration || s.config.default_duration || 5;
-    $recDuration.placeholder = dur.toFixed(1);
-    if (!$recDuration.value) $recDuration.value = dur.toFixed(1);
-
-    // Hugging Face login status — auto-detected, NOT editable
-    if (s.config.hf_username) {
-      hfUsername = s.config.hf_username;
-      $hfStatus.textContent = `Logged in as ${s.config.hf_username}`;
-      $hfStatus.className = 'hf-status logged-in';
-      $hfHint.textContent = '';
-      $hfLoginForm.style.display = 'none';
-      $hfLogoutSection.style.display = '';
-    } else {
-      hfUsername = null;
-      $hfStatus.textContent = 'Not logged in';
-      $hfStatus.className = 'hf-status logged-out';
-      $hfHint.textContent = '';
-      $hfLoginForm.style.display = '';
-      $hfLogoutSection.style.display = 'none';
-    }
+  // ── Phase timing (variables only — rAF loop reads them) ──
+  updatePhase(s);
 
-    // Dataset root
-    if (s.config.dataset_root_path) {
-      if (!$datasetRootInput.value) $datasetRootInput.value = s.config.dataset_root_path;
-      if ($datasetRootHint) $datasetRootHint.textContent =
-        `Datasets folder: ${s.config.dataset_root_path}`;
-    }
+  // ── Config: lightweight field updates ──
+  if (s.config) updateConfigUI(s.config);
 
-    // Audio availability — disable mic options if not available
-    const micRadio = document.querySelector('input[name="audio-src"][value="mic"]');
-    const micOnlyRadio = document.querySelector('input[name="audio-src"][value="mic-only"]');
-    if (micRadio) {
-      micRadio.disabled = !s.config.audio_available;
-      if (!s.config.audio_available && micRadio.checked) {
-        document.querySelector('input[name="audio-src"][value="none"]').checked = true;
-      }
-    }
-    if (micOnlyRadio) {
-      micOnlyRadio.disabled = !s.config.audio_available;
-      if (!s.config.audio_available && micOnlyRadio.checked) {
-        document.querySelector('input[name="audio-src"][value="none"]').checked = true;
-      }
-    }
+  // ── Datasets: only rebuild when dirty ──
+  if (datasetsDirty && s.datasets) {
+    updateDatasetUI(s.datasets);
+    datasetsDirty = false;
+  }
 
-    // Welcome messages radio sync
-    if (s.config.welcome_messages != null) {
-      const radio = document.querySelector(`input[name="welcome-msgs"][value="${s.config.welcome_messages}"]`);
-      if (radio && !radio.checked) radio.checked = true;
+  // ── Moves list: render into My Moves or Library depending on active dataset ──
+  if (movesListDirty) {
+    const moves = s.moves || [];
+    reconcileMoves(moves);
+    if (isDownloaded && $libraryMovesList) {
+      renderMoves(moves, s.mode, s.active_move, $libraryMovesList, true);
+      $libraryCount.textContent = moves.length;
+    } else {
+      renderMoves(moves, s.mode, s.active_move, $movesList, false);
+      $myMovesCount.textContent = moves.length;
     }
+    updateUploadBar();
+    movesListDirty = false;
+  } else {
+    // Lightweight: update play/stop buttons and is-playing state
+    // without rebuilding the entire list
+    updateMoveCardStates(s.mode, s.active_move);
+  }
+}
 
-    // Lead compensation
-    updateLeadCompUI(s.config);
+/* Update config fields in the UI.  Only writes to DOM elements that are
+   not currently focused by the user (to avoid overwriting mid-edit). */
+function updateConfigUI(config) {
+  const dur = config.preferred_duration || config.default_duration || 5;
+  $recDuration.placeholder = dur.toFixed(1);
+  if (!$recDuration.value) $recDuration.value = dur.toFixed(1);
+
+  // HF login status
+  if (config.hf_username) {
+    hfUsername = config.hf_username;
+    $hfStatus.textContent = `Logged in as ${config.hf_username}`;
+    $hfStatus.className = 'hf-status logged-in';
+    $hfHint.textContent = '';
+    $hfLoginForm.style.display = 'none';
+    $hfLogoutSection.style.display = '';
+  } else {
+    hfUsername = null;
+    $hfStatus.textContent = 'Not logged in';
+    $hfStatus.className = 'hf-status logged-out';
+    $hfHint.textContent = '';
+    $hfLoginForm.style.display = '';
+    $hfLogoutSection.style.display = 'none';
   }
 
-  // ── Datasets ──
-  if (s.datasets) updateDatasetUI(s.datasets);
+  // Dataset root
+  if (config.dataset_root_path) {
+    if (!$datasetRootInput.value) $datasetRootInput.value = config.dataset_root_path;
+    if ($datasetRootHint) $datasetRootHint.textContent =
+      `Datasets folder: ${config.dataset_root_path}`;
+  }
 
-  // ── Phase timing (for overlay animation) ──
-  updatePhase(s);
+  // Welcome messages radio sync
+  if (config.welcome_messages != null) {
+    const radio = document.querySelector(
+      `input[name="welcome-msgs"][value="${config.welcome_messages}"]`
+    );
+    if (radio && !radio.checked) radio.checked = true;
+  }
 
-  // ── Moves list ──
-  const moves = s.moves || [];
-  reconcileMoves(moves);
-  renderMoves(moves, s.mode, s.active_move);
-  $movesCount.textContent = moves.length;
-  updateUploadBar();
+  // Lead compensation
+  updateLeadCompUI(config);
 }
 
 
 // ═══════════════════════════════════════════════════════════════════════
-// SECTION 4: PHASE OVERLAY — Continuous countdown → recording display
+// SECTION 4: PHASE OVERLAY — Countdown → recording animation
+//
+// The phase overlay is a full-screen overlay that shows countdown
+// numbers (3… 2… 1…) then a recording progress bar.  It uses
+// requestAnimationFrame (rAF) for smooth 60 fps animation.
+//
+// How it works:
+//   1. updatePhase(s) — called from updateUI(), stores server timestamps
+//      into JS variables (phaseStartAt, phaseEndAt, etc.)
+//   2. animationLoop() — runs every frame via rAF, calls
+//      updatePhaseDisplay() which reads those timestamps and the
+//      NTP-corrected local time to render the overlay.
 // ═══════════════════════════════════════════════════════════════════════
 
 function updatePhase(s) {
-  if (s.mode === 'countdown' && s.phase_start_at != null && s.phase_end_at != null) {
+  if (s.mode === 'preparing') {
+    phaseMode = 'preparing';
+  } else if (s.mode === 'countdown' && s.phase_start_at != null && s.phase_end_at != null) {
     phaseMode = 'countdown';
     phaseStartAt = s.phase_start_at;
     phaseEndAt = s.phase_end_at;
@@ -292,7 +331,16 @@ function updatePhase(s) {
 }
 
 function updatePhaseDisplay() {
-  // Hide overlay when no active phase
+  // "Preparing…" overlay while audio is being preloaded/resampled
+  if (phaseMode === 'preparing') {
+    $phaseOverlay.className = 'phase-overlay active phase-countdown';
+    $phaseFill.style.width = '100%';
+    $phaseNumber.textContent = 'Preparing\u2026';
+    $phaseSublabel.textContent = '';
+    $phaseStopBtn.textContent = 'Cancel';
+    return;
+  }
+
   if (phaseStartAt == null || phaseEndAt == null) {
     $phaseOverlay.className = 'phase-overlay';
     return;
@@ -300,9 +348,8 @@ function updatePhaseDisplay() {
 
   const now = Date.now() / 1000 + clockOffset;
 
-  // Determine the effective display phase. When phaseMode is still
-  // 'countdown' (poll hasn't caught up yet) but the countdown timer has
-  // expired, we PREDICT the recording phase locally.
+  // When phaseMode is 'countdown' but the timer expired, predict
+  // the recording phase locally (poll may not have caught up yet).
   let displayPhase = phaseMode;
   if (phaseMode === 'countdown' && now >= phaseEndAt) {
     displayPhase = 'recording';
@@ -311,7 +358,6 @@ function updatePhaseDisplay() {
   if (displayPhase === 'countdown') {
     const remaining = phaseEndAt - now;
     const secs = Math.ceil(remaining);
-
     $phaseOverlay.className = 'phase-overlay active phase-countdown';
     $phaseFill.style.width = '100%';
     $phaseNumber.textContent = Math.max(1, secs);
@@ -327,21 +373,18 @@ function updatePhaseDisplay() {
       recStart = countdownEndAt || phaseEndAt;
       recEnd = recStart + (requestedDuration || 5);
     }
-
     const recTotal = recEnd - recStart;
     const recRemaining = Math.max(0, recEnd - now);
     const ratio = recTotal > 0 ? Math.min(1, Math.max(0, recRemaining / recTotal)) : 0;
 
     $phaseOverlay.className = 'phase-overlay active phase-recording';
     $phaseFill.style.width = (ratio * 100) + '%';
-
     $phaseNumber.innerHTML = '<span class="rec-dot"></span>Recording';
     $phaseSublabel.textContent = recRemaining.toFixed(1) + 's remaining';
     $phaseStopBtn.textContent = 'Stop Recording';
   }
 }
 
-/* Animation loop — runs continuously via requestAnimationFrame */
 function animationLoop() {
   updatePhaseDisplay();
   requestAnimationFrame(animationLoop);
@@ -354,14 +397,50 @@ animationLoop();
 // ═══════════════════════════════════════════════════════════════════════
 
 function updateDatasetUI(ds) {
+  const entries = ds.entries || [];
+  const localEntries = entries.filter(e => e.origin !== 'downloaded');
+  const downloadedEntries = entries.filter(e => e.origin === 'downloaded');
+
+  // My Moves dropdown — local datasets only
   $datasetSelect.innerHTML = '';
-  (ds.entries || []).forEach(e => {
+  localEntries.forEach(e => {
     const opt = document.createElement('option');
     opt.value = e.id;
-    opt.textContent = (e.origin === 'downloaded' ? '\u2B07 ' : '') + (e.label || e.id);
+    opt.textContent = e.label || e.id;
     $datasetSelect.appendChild(opt);
   });
-  if (!datasetSwitching) $datasetSelect.value = ds.active_id || '';
+
+  // Library dropdown — downloaded datasets only
+  if ($libraryDatasetSelect) {
+    $libraryDatasetSelect.innerHTML = '';
+    if (!downloadedEntries.length) {
+      const opt = document.createElement('option');
+      opt.value = '';
+      opt.textContent = 'No downloaded datasets';
+      opt.disabled = true;
+      $libraryDatasetSelect.appendChild(opt);
+    }
+    downloadedEntries.forEach(e => {
+      const opt = document.createElement('option');
+      opt.value = e.id;
+      opt.textContent = e.label || e.id;
+      $libraryDatasetSelect.appendChild(opt);
+    });
+  }
+
+  // Track last local dataset for tab switching
+  const activeEntry = entries.find(e => e.id === ds.active_id);
+  if (activeEntry && activeEntry.origin !== 'downloaded') {
+    lastLocalDatasetId = ds.active_id;
+  }
+
+  if (!datasetSwitching) {
+    if (activeEntry?.origin === 'downloaded' && $libraryDatasetSelect) {
+      $libraryDatasetSelect.value = ds.active_id || '';
+    } else {
+      $datasetSelect.value = ds.active_id || '';
+    }
+  }
 }
 
 
@@ -376,30 +455,39 @@ function reconcileMoves(moves) {
   }
 }
 
-function renderMoves(moves, mode, activeMove) {
+function renderMoves(moves, mode, activeMove, container, readOnly) {
+  container = container || $movesList;
   if (!moves.length) {
-    $movesList.innerHTML = `
+    const icon = readOnly ? '&#11088;' : '&#9898;';
+    const msg = readOnly
+      ? 'Download datasets from the Community tab to see them here'
+      : 'Record your first move to see it here';
+    container.innerHTML = `
       <div class="moves-empty">
-        <div class="moves-empty-icon">&#9898;</div>
-        Record your first move to see it here
+        <div class="moves-empty-icon">${icon}</div>
+        ${msg}
       </div>`;
     return;
   }
 
-  $movesList.innerHTML = '';
+  container.innerHTML = '';
   moves.forEach(m => {
     const card = document.createElement('div');
     card.className = 'move-card' +
       (activeMove === m.id && mode === 'playing' ? ' is-playing' : '');
-
-    const cb = document.createElement('input');
-    cb.type = 'checkbox';
-    cb.className = 'move-check';
-    cb.checked = selectedMoves.has(m.id);
-    cb.onchange = () => {
-      cb.checked ? selectedMoves.add(m.id) : selectedMoves.delete(m.id);
-      updateUploadBar();
-    };
+    card.dataset.moveId = m.id;   // used by updateMoveCardStates()
+
+    let cb = null;
+    if (!readOnly) {
+      cb = document.createElement('input');
+      cb.type = 'checkbox';
+      cb.className = 'move-check';
+      cb.checked = selectedMoves.has(m.id);
+      cb.onchange = () => {
+        cb.checked ? selectedMoves.add(m.id) : selectedMoves.delete(m.id);
+        updateUploadBar();
+      };
+    }
 
     const info = document.createElement('div');
     info.className = 'move-info';
@@ -415,7 +503,9 @@ function renderMoves(moves, mode, activeMove) {
     dot.className = 'audio-dot ' + (m.has_audio ? 'has' : 'none');
     meta.appendChild(dot);
     const dur = m.duration != null ? m.duration.toFixed(1) + 's' : '--';
-    const date = new Date(m.created_at * 1000).toLocaleDateString();
+    const date = new Date(m.created_at * 1000).toLocaleString(undefined, {
+      month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit'
+    });
     meta.appendChild(document.createTextNode(dur + ' \u00B7 ' + date));
     info.appendChild(meta);
 
@@ -440,23 +530,43 @@ function renderMoves(moves, mode, activeMove) {
     playBtn.textContent = (mode === 'playing' && activeMove === m.id) ? 'Stop' : 'Play';
     playBtn.disabled = busy && !(mode === 'playing' && activeMove === m.id);
     playBtn.onclick = () => {
-      if (mode === 'playing' && activeMove === m.id) stopPlayback();
+      if (playBtn.closest('.move-card')?.classList.contains('is-playing')) stopPlayback();
       else queuePlayback(m.id);
     };
-
-    const delBtn = document.createElement('button');
-    delBtn.className = 'move-action delete-action';
-    delBtn.textContent = 'Delete';
-    delBtn.disabled = busy;
-    delBtn.onclick = () => deleteMove(m.id);
-
     actions.appendChild(playBtn);
-    actions.appendChild(delBtn);
 
-    card.appendChild(cb);
+    if (!readOnly) {
+      const delBtn = document.createElement('button');
+      delBtn.className = 'move-action delete-action';
+      delBtn.textContent = 'Delete';
+      delBtn.disabled = busy;
+      delBtn.onclick = () => deleteMove(m.id);
+      actions.appendChild(delBtn);
+    }
+
+    if (cb) card.appendChild(cb);
     card.appendChild(info);
     card.appendChild(actions);
-    $movesList.appendChild(card);
+    container.appendChild(card);
+  });
+}
+
+/* Lightweight update of play/stop buttons and is-playing class on
+   existing move cards.  Called by updateUI() on every poll when the
+   moves list is NOT dirty.  This avoids a full DOM rebuild while still
+   keeping play/stop buttons responsive. */
+function updateMoveCardStates(mode, activeMove) {
+  document.querySelectorAll('.move-card').forEach(card => {
+    const id = card.dataset.moveId;
+    const isPlaying = (mode === 'playing' && activeMove === id);
+    card.classList.toggle('is-playing', isPlaying);
+    const playBtn = card.querySelector('.play-action');
+    if (playBtn) {
+      playBtn.textContent = isPlaying ? 'Stop' : 'Play';
+      playBtn.disabled = busy && !isPlaying;
+    }
+    const delBtn = card.querySelector('.delete-action');
+    if (delBtn) delBtn.disabled = busy;
   });
 }
 
@@ -474,24 +584,39 @@ function updateUploadBar() {
 
 // ═══════════════════════════════════════════════════════════════════════
 // SECTION 7: USER ACTIONS — API calls triggered by user interactions
+//
+// Each action follows the same pattern:
+//   1. Guard (busy? valid input?)
+//   2. Call the backend API
+//   3. Set dirty flags for affected UI sections
+//   4. Call fetchState() to get the latest state
 // ═══════════════════════════════════════════════════════════════════════
 
+/* Record Move — motion capture with optional uploaded audio playback.
+   Audio source can be: silent, upload (from laptop), or robot file.
+   Mic recording during motion is NOT supported (motor noise). */
 async function queueRecording() {
   if (busy) return;
   const dur = parseFloat($recDuration.value) || parseFloat($recDuration.placeholder) || 5;
   const label = $recName.value.trim() || null;
-  const audioSrc = document.querySelector('input[name="audio-src"]:checked')?.value || 'mic';
-  const isMicOnly = audioSrc === 'mic-only';
-  const recordAudio = audioSrc !== 'none';
-  const recordMotion = !isMicOnly;
-  const audioId = audioSrc === 'upload' ? uploadedAudioId : null;
+  const audioSrc = document.querySelector('input[name="audio-src"]:checked')?.value || 'silent';
 
-  if (audioSrc === 'upload' && !uploadedAudioId) return;
+  // For upload/robot sources, audio must be prepared first
+  if ((audioSrc === 'upload' || audioSrc === 'robot') && !uploadedAudioId) {
+    alert('Please select or upload an audio file first, or choose Silent.');
+    return;
+  }
 
+  const audioId = uploadedAudioId;  // null for 'silent'
   requestedDuration = dur;
   $recordBtn.disabled = true;
   try {
-    const payload = { duration: dur, record_audio: recordAudio, record_motion: recordMotion, label };
+    const payload = {
+      duration: dur,
+      record_audio: false,    // mic-during-motion removed
+      record_motion: true,
+      label,
+    };
     if (audioId) payload.uploaded_audio_id = audioId;
     const r = await fetch('/api/record', {
       method: 'POST',
@@ -499,11 +624,10 @@ async function queueRecording() {
       body: JSON.stringify(payload),
     });
     if (!r.ok) throw new Error(await r.text());
+    movesListDirty = true;
     await fetchState();
-    // Preserve label for next recording
     const savedLabel = window.localStorage.getItem(STORAGE_KEYS.moveLabel);
     $recName.value = savedLabel || '';
-    // Keep uploadedAudioId so the user can record again with the same file
   } catch (e) {
     console.error('Record error:', e);
   } finally {
@@ -511,6 +635,49 @@ async function queueRecording() {
   }
 }
 
+/* Record Audio — mic-only recording (no motion capture).
+   Simple flow: click → countdown → mic records for duration → save. */
+async function queueAudioRecording() {
+  if (busy) return;
+  const dur = parseFloat($recDuration.value) || parseFloat($recDuration.placeholder) || 5;
+  const label = $recName.value.trim() || null;
+  requestedDuration = dur;
+  if ($recordAudioBtn) $recordAudioBtn.disabled = true;
+  try {
+    const r = await fetch('/api/record', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        duration: dur,
+        record_audio: true,
+        record_motion: false,
+        label,
+      }),
+    });
+    if (!r.ok) throw new Error(await r.text());
+    movesListDirty = true;
+    await fetchState();
+    // Auto-switch to "Robot file" source and select the new recording
+    const robotRadio = document.querySelector('input[name="audio-src"][value="robot"]');
+    if (robotRadio) {
+      robotRadio.checked = true;
+      robotRadio.dispatchEvent(new Event('change', { bubbles: true }));
+      // Wait for file list to load, then auto-select newest (first) entry
+      await new Promise(r => setTimeout(r, 1500));
+      if ($robotAudioSelect && $robotAudioSelect.options.length > 0) {
+        $robotAudioSelect.selectedIndex = 0;
+        await selectRobotAudio();
+        // Match duration to the audio recording
+        if ($recDuration) $recDuration.value = dur;
+      }
+    }
+  } catch (e) {
+    console.error('Record audio error:', e);
+  } finally {
+    if ($recordAudioBtn) $recordAudioBtn.disabled = false;
+  }
+}
+
 async function queuePlayback(id) {
   if (busy) return;
   try {
@@ -529,7 +696,7 @@ async function stopPlayback() {
   stopping = true;
   try {
     const ctrl = new AbortController();
-    const tid = setTimeout(() => ctrl.abort(), 10000);
+    const tid = setTimeout(() => ctrl.abort(), 3000);
     await fetch('/api/play/stop', { method: 'POST', signal: ctrl.signal });
     clearTimeout(tid);
     await fetchState();
@@ -543,9 +710,10 @@ async function stopRecording() {
   $phaseStopBtn.disabled = true;
   try {
     const ctrl = new AbortController();
-    const tid = setTimeout(() => ctrl.abort(), 10000);
+    const tid = setTimeout(() => ctrl.abort(), 3000);
     await fetch('/api/record/stop', { method: 'POST', signal: ctrl.signal });
     clearTimeout(tid);
+    movesListDirty = true;
     await fetchState();
   } catch (e) { console.error(e); }
   finally { stopping = false; $phaseStopBtn.disabled = false; }
@@ -558,6 +726,7 @@ async function deleteMove(id) {
     const r = await fetch('/api/moves/' + encodeURIComponent(id), { method: 'DELETE' });
     if (!r.ok) throw new Error(await r.text());
     selectedMoves.delete(id);
+    movesListDirty = true;
     await fetchState();
   } catch (e) { console.error('Delete error:', e); }
 }
@@ -572,6 +741,8 @@ async function selectDataset(id) {
     });
     if (!r.ok) throw new Error(await r.text());
     selectedMoves.clear();
+    movesListDirty = true;
+    datasetsDirty = true;
     await fetchState();
   } catch (e) { console.error(e); }
   finally { datasetSwitching = false; }
@@ -589,6 +760,8 @@ async function createDataset(name) {
       const d = await r.json().catch(() => ({}));
       throw new Error(d.detail || r.statusText);
     }
+    datasetsDirty = true;
+    movesListDirty = true;
     await fetchState();
     $newDatasetInline.classList.remove('active');
     $newDatasetBtn.style.display = '';
@@ -608,6 +781,7 @@ async function syncToHF() {
     });
     if (!r.ok) throw new Error(await r.text());
     selectedMoves.clear();
+    movesListDirty = true;
     await fetchState();
   } catch (e) {
     console.error(e);
@@ -629,6 +803,8 @@ async function updateDatasetRoot() {
       body: JSON.stringify({ path }),
     });
     if (!r.ok) throw new Error(await r.text());
+    datasetsDirty = true;
+    movesListDirty = true;
     await fetchState();
   } catch (e) { console.error(e); }
 }
@@ -644,15 +820,80 @@ async function uploadAudioFile(file) {
     const data = await r.json();
     uploadedAudioId = data.upload_id;
     uploadedAudioFilename = data.filename;
-    $audioUploadStatus.textContent = `Ready: ${data.filename}` + (data.duration ? ` (${data.duration.toFixed(1)}s)` : '');
-    if (data.duration && $recDuration) $recDuration.value = (Math.round(data.duration * 10) / 10).toFixed(1);
-    // Auto-close settings drawer after successful upload
-    $settingsBackdrop.classList.remove('open');
-    $settingsDrawer.classList.remove('open');
+    $audioUploadStatus.textContent = `Ready: ${data.filename}` +
+      (data.duration ? ` (${data.duration.toFixed(1)}s)` : '');
+    if (data.duration && $recDuration) {
+      $recDuration.value = (Math.round(data.duration * 10) / 10).toFixed(1);
+    }
   } catch (e) {
     $audioUploadStatus.textContent = 'Failed: ' + e.message;
     uploadedAudioId = null;
   }
+  updateAudioSelectionStatus();
+}
+
+/* Update the "Audio: ..." indicator below the move name field. */
+function updateAudioSelectionStatus() {
+  if (!$audioSelectionStatus) return;
+  const src = document.querySelector('input[name="audio-src"]:checked')?.value;
+  if (src === 'silent' || !src) {
+    $audioSelectionStatus.textContent = 'Audio: Silent';
+  } else if (uploadedAudioFilename) {
+    $audioSelectionStatus.textContent = `Audio: ${uploadedAudioFilename}`;
+  } else {
+    $audioSelectionStatus.textContent = 'Audio: None selected';
+  }
+}
+
+/* Load the list of audio files available on the robot. */
+async function loadRobotAudioFiles() {
+  if (!$robotAudioSelect) return;
+  $robotAudioSelect.innerHTML = '<option value="">Loading...</option>';
+  try {
+    const r = await fetch('/api/robot-audio', { cache: 'no-store' });
+    const data = await r.json();
+    $robotAudioSelect.innerHTML = '';
+    const files = data.files || [];
+    if (!files.length) {
+      $robotAudioSelect.innerHTML = '<option value="">No audio files found</option>';
+      return;
+    }
+    files.forEach(f => {
+      const opt = document.createElement('option');
+      opt.value = f.path;
+      opt.textContent = f.name + (f.duration_seconds ? ` (${f.duration_seconds.toFixed(1)}s)` : '');
+      $robotAudioSelect.appendChild(opt);
+    });
+    // Auto-select the first file so uploadedAudioId is set immediately.
+    // Without this, the user would need to manually click "Use" before recording.
+    if (files.length > 0) selectRobotAudio();
+  } catch (e) {
+    $robotAudioSelect.innerHTML = '<option value="">Error loading files</option>';
+    console.error('Robot audio error:', e);
+  }
+}
+
+/* Select an audio file already on the robot for use in recording. */
+async function selectRobotAudio() {
+  const path = $robotAudioSelect?.value;
+  if (!path) { updateAudioSelectionStatus(); return; }
+  try {
+    const r = await fetch('/api/robot-audio/select', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ path }),
+    });
+    if (!r.ok) throw new Error((await r.json().catch(() => ({}))).detail || r.statusText);
+    const data = await r.json();
+    uploadedAudioId = data.upload_id;
+    uploadedAudioFilename = data.filename;
+    if (data.duration && $recDuration) {
+      $recDuration.value = (Math.round(data.duration * 10) / 10).toFixed(1);
+    }
+  } catch (e) {
+    console.error('Robot audio select error:', e);
+  }
+  updateAudioSelectionStatus();
 }
 
 
@@ -727,6 +968,8 @@ async function downloadCommunity() {
     }
     communitySelection.clear();
     $communityStatus.textContent = 'Download complete.';
+    movesListDirty = true;
+    datasetsDirty = true;
     await fetchState();
   } catch (e) {
     $communityStatus.textContent = 'Error: ' + e.message;
@@ -745,14 +988,12 @@ function updateLeadCompUI(config) {
   const modelsPayload = config.motion_models;
   if (!modelsPayload) return;
   const params = modelsPayload.params?.lead_compensation || {};
-  if ($leadFramesHead && document.activeElement !== $leadFramesHead && Number.isFinite(params.lead_frames_head)) {
+  if ($leadFramesHead && document.activeElement !== $leadFramesHead &&
+      Number.isFinite(params.lead_frames_head)) {
     $leadFramesHead.value = String(params.lead_frames_head);
   }
-  if (
-    $leadFramesAntennas
-    && document.activeElement !== $leadFramesAntennas
-    && Number.isFinite(params.lead_frames_antennas)
-  ) {
+  if ($leadFramesAntennas && document.activeElement !== $leadFramesAntennas &&
+      Number.isFinite(params.lead_frames_antennas)) {
     $leadFramesAntennas.value = String(params.lead_frames_antennas);
   }
 }
@@ -762,22 +1003,42 @@ function updateLeadCompUI(config) {
 // SECTION 10: EVENT LISTENERS
 // ═══════════════════════════════════════════════════════════════════════
 
-/* Record button — either starts recording or stops it */
+/* Record Move button — start or stop */
 $recordBtn.addEventListener('click', () => {
-  if (busy && (phaseMode === 'recording' || phaseMode === 'countdown')) {
+  if (busy && ['preparing', 'countdown', 'recording'].includes(phaseMode)) {
     stopRecording();
   } else {
     queueRecording();
   }
 });
 
-/* Phase overlay stop button */
-$phaseStopBtn.addEventListener('click', stopRecording);
+/* Record Audio button — mic-only recording */
+if ($recordAudioBtn) {
+  $recordAudioBtn.addEventListener('click', () => {
+    if (busy && ['preparing', 'countdown', 'recording'].includes(phaseMode)) {
+      stopRecording();
+    } else {
+      queueAudioRecording();
+    }
+  });
+}
+
+/* Phase overlay stop button — dispatch based on current mode */
+$phaseStopBtn.addEventListener('click', () => {
+  if (phaseMode === 'playing') stopPlayback();
+  else stopRecording();
+});
 
-/* Dataset selector */
+/* Dataset selector — My Moves tab */
 $datasetSelect.addEventListener('change', e => {
   if (e.target.value) selectDataset(e.target.value);
 });
+/* Dataset selector — Library tab */
+if ($libraryDatasetSelect) {
+  $libraryDatasetSelect.addEventListener('change', e => {
+    if (e.target.value) selectDataset(e.target.value);
+  });
+}
 
 /* New dataset creation (inline form) */
 $newDatasetBtn.addEventListener('click', () => {
@@ -795,7 +1056,6 @@ $newDatasetInput.addEventListener('keydown', e => {
   if (e.key === 'Enter') { e.preventDefault(); createDataset($newDatasetInput.value.trim()); }
   if (e.key === 'Escape') { $newDatasetInline.classList.remove('active'); $newDatasetBtn.style.display = ''; }
 });
-/* Auto-lowercase and replace spaces with underscores */
 $newDatasetInput.addEventListener('input', e => {
   e.target.value = e.target.value.toLowerCase().replace(/\s+/g, '_');
 });
@@ -820,37 +1080,54 @@ $settingsClose.addEventListener('click', () => {
 /* Dataset root update */
 $updateRootBtn.addEventListener('click', updateDatasetRoot);
 
-/* Audio source radio buttons */
+/* Audio source radio buttons — show/hide the relevant sub-panel */
 document.querySelectorAll('input[name="audio-src"]').forEach(r => {
   r.addEventListener('change', () => {
-    $audioUploadSection.style.display = (r.value === 'upload' && r.checked) ? '' : 'none';
-    if (r.value !== 'upload') {
-      uploadedAudioId = null;
-      uploadedAudioFilename = null;
-      $audioUploadStatus.textContent = '';
-    }
+    if ($audioUploadSection) $audioUploadSection.style.display =
+      (r.value === 'upload' && r.checked) ? '' : 'none';
+    if ($robotAudioSection) $robotAudioSection.style.display =
+      (r.value === 'robot' && r.checked) ? '' : 'none';
+    // Clear audio selection when switching between ANY source type.
+    // This prevents stale uploadedAudioId from a previous source.
+    uploadedAudioId = null;
+    uploadedAudioFilename = null;
+    if ($audioUploadStatus) $audioUploadStatus.textContent = '';
+    // Auto-load robot audio files when selecting "Robot file"
+    if (r.value === 'robot' && r.checked) loadRobotAudioFiles();
+    updateAudioSelectionStatus();
   });
 });
 
 /* Audio upload zone — click and drag-and-drop */
-$audioUploadZone.addEventListener('click', () => $audioFileInput.click());
-$audioFileInput.addEventListener('change', e => {
-  if (e.target.files?.[0]) uploadAudioFile(e.target.files[0]);
-});
-$audioUploadZone.addEventListener('dragover', e => {
-  e.preventDefault();
-  $audioUploadZone.classList.add('drag-over');
-});
-$audioUploadZone.addEventListener('dragleave', e => {
-  e.preventDefault();
-  $audioUploadZone.classList.remove('drag-over');
-});
-$audioUploadZone.addEventListener('drop', e => {
-  e.preventDefault();
-  $audioUploadZone.classList.remove('drag-over');
-  const f = e.dataTransfer?.files?.[0];
-  if (f && /\.(wav|mp3)$/i.test(f.name)) uploadAudioFile(f);
-});
+if ($audioUploadZone) {
+  $audioUploadZone.addEventListener('click', () => $audioFileInput?.click());
+}
+if ($audioFileInput) {
+  $audioFileInput.addEventListener('change', e => {
+    if (e.target.files?.[0]) uploadAudioFile(e.target.files[0]);
+  });
+}
+if ($audioUploadZone) {
+  $audioUploadZone.addEventListener('dragover', e => {
+    e.preventDefault();
+    $audioUploadZone.classList.add('drag-over');
+  });
+  $audioUploadZone.addEventListener('dragleave', e => {
+    e.preventDefault();
+    $audioUploadZone.classList.remove('drag-over');
+  });
+  $audioUploadZone.addEventListener('drop', e => {
+    e.preventDefault();
+    $audioUploadZone.classList.remove('drag-over');
+    const f = e.dataTransfer?.files?.[0];
+    if (f && /\.(wav|mp3)$/i.test(f.name)) uploadAudioFile(f);
+  });
+}
+
+/* Robot audio select — auto-select on dropdown change + manual "Use" button */
+if ($robotAudioSelect) {
+  $robotAudioSelect.addEventListener('change', selectRobotAudio);
+}
 
 /* HF login/logout */
 $hfLoginBtn.addEventListener('click', async () => {
@@ -932,18 +1209,43 @@ $recDuration.addEventListener('change', () => {
   }, 500);
 });
 
-/* Tab switching */
+/* Tab switching — auto-switch datasets and auto-fetch community */
 document.querySelectorAll('.section-tab').forEach(tab => {
   tab.addEventListener('click', () => {
     document.querySelectorAll('.section-tab').forEach(t => t.classList.remove('active'));
     document.querySelectorAll('.tab-panel').forEach(p => p.classList.remove('active'));
     tab.classList.add('active');
     document.getElementById('tab-' + tab.dataset.tab)?.classList.add('active');
+
+    // My Moves tab: restore last local dataset if currently on a downloaded one
+    if (tab.dataset.tab === 'my-moves' && lastLocalDatasetId) {
+      const ae = lastState?.datasets?.entries?.find(
+        e => e.id === lastState?.datasets?.active_id
+      );
+      if (ae?.origin === 'downloaded') {
+        selectDataset(lastLocalDatasetId);
+      }
+    }
+
+    // Library tab: auto-select first downloaded dataset
+    if (tab.dataset.tab === 'library') {
+      const downloaded = (lastState?.datasets?.entries || [])
+        .filter(e => e.origin === 'downloaded');
+      if (downloaded.length) {
+        const cur = lastState?.datasets?.active_id;
+        if (!downloaded.some(d => d.id === cur)) {
+          selectDataset(downloaded[0].id);
+        }
+      }
+    }
+
+    if (tab.dataset.tab === 'community' && $communityList.childElementCount === 0) {
+      fetchCommunity();
+    }
   });
 });
 
 /* Community */
-$fetchCommunityBtn.addEventListener('click', fetchCommunity);
 $downloadCommunityBtn.addEventListener('click', downloadCommunity);
 
 /* Name field — persist to localStorage */
@@ -965,5 +1267,4 @@ if ($recName) {
 // SECTION 11: INIT
 // ═══════════════════════════════════════════════════════════════════════
 
-/* Start polling */
 startPolling();

marionette/static/style.css

@@ -338,6 +338,14 @@ input[type=number]::-webkit-inner-spin-button,
 input[type=number]::-webkit-outer-spin-button { -webkit-appearance: none; }
 input[type=number] { -moz-appearance: textfield; }
 
+/* Audio selection indicator below record fields */
+.audio-selection-status {
+  font-size: .8rem;
+  color: var(--text-muted);
+  text-align: center;
+  margin: .25rem 0 0;
+}
+
 /* Small hint text below the fields */
 .record-hint {
   font-size: .75rem;
@@ -1008,4 +1016,136 @@ input[type=number] { -moz-appearance: textfield; }
 .fade-in-1 { animation-delay: .05s; }
 .fade-in-2 { animation-delay: .1s; }
 .fade-in-3 { animation-delay: .15s; }
-</style>
+
+
+/* ═══════════════════════════════════════════════════════════════════
+   RECORD ACTIONS — Two-button layout: "Record Move" + "Record Audio"
+
+   The two buttons sit side-by-side on wide screens and stack on
+   mobile.  The audio source panel appears inline below Record Move.
+   ═══════════════════════════════════════════════════════════════════ */
+.record-actions {
+  display: flex;
+  gap: 2rem;
+  align-items: flex-start;
+  justify-content: center;
+  flex-wrap: wrap;
+  width: 100%;
+}
+
+.record-action-block {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: .75rem;
+}
+
+/* Audio button: green instead of red to visually differentiate */
+.record-btn-audio {
+  background: linear-gradient(145deg, #16a34a, #15803d);
+  box-shadow: 0 8px 40px var(--green-glow), inset 0 1px 0 rgba(255,255,255,.15);
+}
+.record-btn-audio:hover {
+  box-shadow: 0 12px 60px var(--green-glow), inset 0 1px 0 rgba(255,255,255,.2);
+}
+.record-ring-audio::before {
+  border-color: var(--border);
+}
+.record-ring-audio:hover::before {
+  border-color: var(--green);
+  box-shadow: 0 0 40px var(--green-glow);
+}
+.rec-icon-audio {
+  font-size: 2rem;
+  line-height: 1;
+}
+.record-hint-small {
+  font-size: .7rem;
+  color: var(--text-muted);
+  opacity: .6;
+  text-align: center;
+}
+.record-audio-hint {
+  font-size: .65rem;
+  color: var(--text-muted);
+  opacity: .5;
+  text-align: center;
+  max-width: 14rem;
+  margin: .25rem auto 0;
+  line-height: 1.3;
+}
+
+/* ═══════════════════════════════════════════════════════════════════
+   AUDIO SOURCE PANEL — Inline below the Record Move button.
+
+   Shows pill-shaped radio tabs: Silent | Upload | Robot file.
+   Only one sub-panel is visible at a time (controlled by JS).
+   ═══════════════════════════════════════════════════════════════════ */
+.audio-source-panel {
+  display: flex;
+  flex-direction: column;
+  gap: .65rem;
+  width: 100%;
+  max-width: 360px;
+  text-align: center;
+}
+.audio-source-label {
+  font-size: .7rem;
+  text-transform: uppercase;
+  letter-spacing: .1em;
+  color: var(--text-muted);
+  font-weight: 600;
+}
+.audio-source-hint {
+  font-size: .65rem;
+  color: var(--text-muted);
+  opacity: .55;
+  margin: -.25rem 0 0;
+  line-height: 1.35;
+}
+.audio-source-tabs {
+  display: flex;
+  gap: .4rem;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+.audio-tab {
+  padding: .35rem .75rem;
+  border-radius: 999px;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  font-size: .75rem;
+  cursor: pointer;
+  transition: all .15s;
+  display: flex;
+  align-items: center;
+  gap: .3rem;
+}
+.audio-tab:has(input:checked) {
+  border-color: var(--accent);
+  background: rgba(225,29,72,.06);
+  color: var(--text);
+}
+.audio-tab input {
+  accent-color: var(--accent);
+  width: 12px;
+  height: 12px;
+}
+
+/* Inline row layout for audio source sections (robot file selector, etc.) */
+.audio-source-row {
+  display: flex;
+  gap: .5rem;
+  align-items: center;
+}
+.audio-source-row .settings-input,
+.audio-source-row .dataset-select {
+  flex: 1;
+  padding: .5rem .75rem;
+  font-size: .8rem;
+}
+
+/* Mobile: stack the two record-action blocks */
+@media (max-width: 600px) {
+  .record-actions { gap: 1.5rem; }
+}

marionette/useless_but_emotional/README.md

@@ -0,0 +1,4 @@
+# Useless but emotional
+
+Code that's currently unused but might become useful later.
+Each file explains why it was archived and when it might return.

marionette/useless_but_emotional/mic_agc.py

@@ -0,0 +1,67 @@
+"""Microphone AGC (Automatic Gain Control) management for ReSpeaker USB.
+
+Disables the XMOS XVF3800 AGC on the ReSpeaker mic array to prevent
+motor noise from causing the mic to "mute" during recording. The AGC
+aggressively scales sensitivity to avoid saturation, which backfires
+when motors are loud — the mic goes nearly silent.
+
+WHY ARCHIVED:
+    We no longer record microphone audio during motion capture (the motor
+    noise was too disruptive anyway). Audio is now recorded separately
+    via the "Record Audio" button, or provided as an uploaded file.
+    Without simultaneous mic+motion, the AGC conflict doesn't occur.
+
+WHEN TO RESTORE:
+    If we re-enable simultaneous microphone + motion recording (e.g. with
+    quieter motors or better noise cancellation), bring these functions
+    back into app.py and call them from run().
+
+USAGE (when active):
+    Called in Marionette.run():
+        self._disable_mic_agc()   # at start
+        self._restore_mic_agc()   # in finally block
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def disable_mic_agc():
+    """Disable the mic's automatic gain control for cleaner recordings."""
+    try:
+        from reachy_mini.media.audio_control_utils import init_respeaker_usb
+    except ImportError:
+        logger.debug("audio_control_utils not available, skipping AGC config")
+        return None
+
+    try:
+        respeaker = init_respeaker_usb()
+        if respeaker is None:
+            logger.debug("No ReSpeaker USB device found, skipping AGC config")
+            return None
+        original_agc = respeaker.read("PP_AGCONOFF")
+        respeaker.write("PP_AGCONOFF", [0])
+        respeaker.close()
+        logger.info("Mic AGC disabled (was %s)", original_agc)
+        return original_agc
+    except Exception as exc:
+        logger.warning("Failed to disable mic AGC: %s", exc)
+        return None
+
+
+def restore_mic_agc(original_agc):
+    """Restore the mic AGC to its original value."""
+    if original_agc is None:
+        return
+    try:
+        from reachy_mini.media.audio_control_utils import init_respeaker_usb
+
+        respeaker = init_respeaker_usb()
+        if respeaker is None:
+            return
+        respeaker.write("PP_AGCONOFF", original_agc)
+        respeaker.close()
+        logger.info("Mic AGC restored to %s", original_agc)
+    except Exception as exc:
+        logger.warning("Failed to restore mic AGC: %s", exc)

pyproject.toml

@@ -14,6 +14,7 @@ dependencies = [
     "soundfile",
     "huggingface-hub==0.34.4",
     "python-multipart",
+    "yt-dlp",
 ]
 keywords = ["reachy-mini-app"]
 

tests/SYNC_TEST_REPORT.md

@@ -0,0 +1,201 @@
+# Audio-Motion Synchronization Test Report
+
+## Summary
+
+Comprehensive testing of audio-motion sync across the Reachy Mini Marionette stack.
+Tests measure the time delay between audio (beeps) and physical motion (antenna collisions)
+using a laptop microphone to capture both sounds from the same clock source.
+
+**Final result**: After identifying and compensating a 320ms `push_audio_sample` pipeline
+latency, Marionette playback sync is now **-4ms mean error, 5ms std** — essentially perfect.
+
+## Test Progression
+
+### 1. Audio Roundtrip (`test_audio_roundtrip.py`)
+**Purpose**: Verify beeps can be played on the robot and detected by the laptop mic.
+
+- 5 beeps at non-periodic times [0.5, 1.8, 3.5, 5.8, 8.9]s
+- 2kHz frequency, 200ms duration, 0.9 amplitude
+- Robot plays at 16kHz via `push_audio_sample`
+- **Result**: 5/5 beeps detected, sub-millisecond accuracy
+
+### 2. Antenna Collision Position Test (`test_antenna_collision.py`)
+**Purpose**: Verify commanded collisions can be detected from motor position feedback.
+
+- Right antenna fixed at -0.68 rad, left swings to 0.70 rad
+- Physical contact at ~0.60 rad, with overshoot to ~0.77 rad
+- PID + comms latency: ~120-160ms from command to peak position
+- **Result**: 5/5 collisions detected from position data
+
+### 3. Collision + Mic Test (`test_collision_mic.py`)
+**Purpose**: Verify collisions can be detected from laptop microphone audio.
+
+- Same collision sequence, recorded via laptop mic
+- Mean delay command -> audible collision: +39ms (std 13ms)
+- **Caveat**: Cross-clock measurement (robot clock vs laptop clock). Only relative
+  consistency is trustworthy, not absolute delay.
+- **Result**: 5/5 collisions detected via mic
+
+### 4. Combined Beep + Collision Sync (`test_beep_collision_sync.py`)
+**Purpose**: THE KEY TEST. Measure audio pipeline latency using same-clock measurement.
+
+Both beeps and collisions are commanded in the same 50Hz loop on the robot.
+Both are detected from the same laptop microphone = no cross-clock bias.
+Beeps at [1.0, 2.3, 4.0, 6.3, 9.4], collisions exactly 1.0s after each.
+
+**Critical Finding**: `push_audio_sample` adds ~245ms pipeline latency.
+- Measured interval: 755ms (expected 1000ms)
+- Error: -245ms mean, 6ms std (extremely consistent)
+- This latency is inherent to the chunk-based audio pipeline, not a warm-up issue
+  (all 5 pairs show the same delay, including the first)
+
+### 5. SDK Move Sync (`test_move_sync.py`)
+**Purpose**: Test audio-motion sync using SDK's `play_move()` + `play_sound()`.
+
+Creates a Marionette-format move (JSON + WAV) and plays it via the SDK's built-in
+`play_move()` method, which internally calls `play_sound()` (file-based audio).
+
+| Trial | Mean error | Std  | Notes                |
+|-------|-----------|------|----------------------|
+| 1     | -5ms*     | 19ms | *excl. 1 outlier     |
+| 2     | -22ms     | 5ms  | Excellent, no outliers|
+
+**Critical Finding**: `play_sound()` (file-based) has essentially zero latency (~22ms),
+vs `push_audio_sample()` (chunk-based) at ~245ms.
+
+### 6. Marionette E2E Playback Test (`test_marionette_sync.py --test playback`)
+**Purpose**: Test through Marionette's full playback pipeline.
+
+Injects a synthetic move (beeps + antenna collisions) into Marionette's active dataset,
+triggers playback via `POST /api/play`, records both sounds via laptop mic.
+
+#### Before compensation (AUDIO_LEAD_MS = 0)
+
+| Trial | Mean error | Std  | Notes |
+|-------|-----------|------|-------|
+| 1     | -320ms    | 7ms  | 5/5 pairs |
+| 2     | -321ms    | 11ms | 5/5 pairs |
+
+The extra 75ms beyond raw pipeline latency (245ms) comes from Marionette's
+`start_signal` thread coordination: audio thread wakes up after the first motor
+command, then pushes through the 245ms pipeline.
+
+#### After compensation (AUDIO_LEAD_MS = 320)
+
+| Trial | Mean error | Std  | Notes |
+|-------|-----------|------|-------|
+| 1     | **-4ms**  | 5ms  | 5/5 pairs, essentially perfect |
+
+Audio thread now starts 320ms before the first motion command. By the time chunks
+traverse the GStreamer pipeline, the first audible output coincides with the first
+physical movement.
+
+### 7. Marionette Recording Countdown Test (`test_marionette_sync.py --test recording`)
+**Purpose**: Verify the 3-2-1 countdown timing and go-to-audio delay.
+
+Uploads a test WAV (2kHz marker beep at t=0.2s), triggers recording via
+`POST /api/record`, records countdown beeps via laptop mic.
+
+**Results** (after fixing beep sample rate bug):
+- 3 countdown beeps detected at 440Hz: gaps of 954ms, 960ms (expected 1000ms)
+- Go beep (880Hz) detected correctly after countdown
+- Marker beep (2kHz) detected at 297ms after go beep
+  - 200ms = marker position in audio file
+  - 97ms = remaining pipeline overhead for uploaded audio start
+
+**Note**: Detection is sensitive to ambient noise. 440Hz/880Hz are in a range with
+significant motor noise and room noise. Tests should be run in a quiet environment.
+
+## Bugs Found and Fixed
+
+### 1. `generate_beep` sample rate mismatch
+**File**: `marionette/recording.py`
+
+`generate_beep()` defaults to `sr=48000` but `push_audio_sample` expects 16kHz data.
+Countdown beeps were playing at 1/3 the intended frequency (147Hz instead of 440Hz)
+and 3x the intended duration (300ms instead of 100ms).
+
+**Fix**: Pass `sr=sr_out` (the robot's output sample rate) to `generate_beep()`.
+
+### 2. Dataset re-download blocked
+**File**: `marionette/datasets.py`
+
+Downloading a dataset that already existed locally raised HTTP 409, preventing updates.
+
+**Fix**: Remove existing entry and folder before re-downloading.
+
+## Key Findings
+
+### Audio Pipeline Latency Comparison
+
+| Method                     | API               | Mean error | Std  | Used by Marionette? |
+|----------------------------|-------------------|-----------|------|---------------------|
+| Direct chunk pushing       | push_audio_sample | **-245ms** | 6ms  | **YES** (playback + recording) |
+| SDK file playback          | play_sound        | **-22ms**  | 5ms  | NO (not interruptible) |
+| Marionette E2E (no comp.)  | push_audio_sample | **-320ms** | 9ms  | Before fix |
+| Marionette E2E (with comp.)| push_audio_sample | **-4ms**   | 5ms  | **After fix** |
+
+### Why Marionette Uses push_audio_sample
+
+Marionette deliberately uses `push_audio_sample` instead of `play_sound` because:
+
+1. **Cancellability**: `play_sound()` creates a GStreamer pipeline that cannot be interrupted.
+   `push_audio_sample` loops can be stopped at any time via `stop_event.set()`.
+   (See `marionette/audio.py:61-65` docstring)
+
+2. **play_sound stoppability fix not merged**: A fix exists on branch
+   `892-stop_playing-has-no-effect-on-audio-started-by-play_sound-gstreamer-backend`
+   (authored by RemiFabre, 2026-02-24) but is not yet merged.
+
+3. **cancel_move not merged**: SDK's `cancel_move()` exists on branch
+   `make-dance-cancellable` but was never merged to main.
+
+### Compensation Mechanism (AUDIO_LEAD_MS)
+
+**Constant**: `AUDIO_LEAD_MS = 320` in `marionette/models.py`
+
+The playback flow now starts audio 320ms before the first motion command:
+
+1. Load JSON trajectory, apply lead compensation
+2. Preload WAV + resample to 16kHz
+3. Goto start pose
+4. Warm GStreamer: `start_playing()` + push 160 silence samples
+5. Spawn audio thread: `play_preloaded_wav()` waiting on `start_signal`
+6. **Fire `start_signal` immediately** → audio thread starts pushing chunks
+7. **Sleep 320ms** → audio fills the GStreamer pipeline
+8. `_stream_playback()`: first motion command coincides with first audible output
+9. On cancel: `audio_stop.set()` → audio thread exits
+
+The 320ms = 245ms GStreamer pipeline latency + ~75ms thread-scheduling overhead.
+
+## Files Created/Modified
+
+### Production Code Changes
+- `marionette/recording.py` — Fixed `generate_beep` sample rate, added AUDIO_LEAD_MS compensation
+- `marionette/datasets.py` — Allow re-downloading existing datasets
+- `marionette/models.py` — Added `AUDIO_LEAD_MS = 320` constant
+
+### Test Scripts
+- `tests/test_audio_roundtrip.py` - Standalone beep roundtrip test
+- `tests/test_antenna_collision.py` - Position-based collision test
+- `tests/test_collision_mic.py` - Collision + mic delay test
+- `tests/test_beep_collision_sync.py` - Combined sync test (KEY measurement)
+- `tests/test_move_sync.py` - SDK play_move sync test
+- `tests/test_marionette_sync.py` - Marionette E2E sync test (playback + recording)
+- `tests/audio_analysis.py` - Shared detection utilities
+- `tests/antenna_gui.py` - Developer GUI for collision values
+
+### Output Files (gitignored, on disk)
+- `tests/collision_trajectory.png` - Antenna position plot
+- `tests/collision_mic_plot.png` - Collision mic timing plot
+- `tests/beep_collision_sync_plot.png` - Key sync measurement plot
+- `tests/move_sync_plot.png` - SDK play_move sync plot
+- `tests/marionette_sync_plot.png` - Marionette E2E sync plot
+- Various `.wav` and `.json` result files
+
+## Future Work
+
+1. **Re-run recording countdown test** in quiet environment for cleaner detection
+2. **Tune AUDIO_LEAD_MS** if hardware changes (different robot speaker, GStreamer version)
+3. **Switch to `play_move`/`play_sound`** once SDK cancel support is merged (eliminating
+   the need for compensation entirely — `play_sound` has only ~22ms latency)

tests/antenna_gui.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""GUI to find antenna collision values on Reachy Mini.
+
+Based on reachy_mini/examples/mini_head_position_gui.py.
+Adds an antenna slider so the user can manually find the value
+where the two antennas collide (producing a distinctive click sound).
+
+Usage:
+    python tests/antenna_gui.py
+
+Move the "Antennas" slider until you hear/see the antennas collide.
+The current value is displayed and printed to stdout when you quit.
+"""
+from __future__ import annotations
+
+import tkinter as tk
+
+import numpy as np
+from scipy.spatial.transform import Rotation as R
+
+from reachy_mini import ReachyMini
+from reachy_mini.utils import create_head_pose
+
+
+def main() -> None:
+    """Run GUI with head + antenna control."""
+    with ReachyMini(media_backend="no_media") as mini:
+        root = tk.Tk()
+        root.title("Antenna Collision Finder")
+
+        row = 0
+
+        # --- Head orientation ---
+        roll_var = tk.DoubleVar(value=0.0)
+        pitch_var = tk.DoubleVar(value=0.0)
+        yaw_var = tk.DoubleVar(value=0.0)
+
+        tk.Label(root, text="Roll (deg):").grid(row=row, column=0, sticky="e")
+        tk.Scale(root, variable=roll_var, from_=-45, to=45, orient=tk.HORIZONTAL, length=300).grid(row=row, column=1)
+        row += 1
+        tk.Label(root, text="Pitch (deg):").grid(row=row, column=0, sticky="e")
+        tk.Scale(root, variable=pitch_var, from_=-45, to=45, orient=tk.HORIZONTAL, length=300).grid(row=row, column=1)
+        row += 1
+        tk.Label(root, text="Yaw (deg):").grid(row=row, column=0, sticky="e")
+        tk.Scale(root, variable=yaw_var, from_=-175, to=175, orient=tk.HORIZONTAL, length=300).grid(row=row, column=1)
+        row += 1
+
+        # --- Body yaw ---
+        body_yaw_var = tk.DoubleVar(value=0.0)
+        tk.Label(root, text="Body Yaw (deg):").grid(row=row, column=0, sticky="e")
+        tk.Scale(root, variable=body_yaw_var, from_=-180, to=180, resolution=1.0, orient=tk.HORIZONTAL, length=300).grid(row=row, column=1)
+        row += 1
+
+        # --- Separator ---
+        tk.Frame(root, height=2, bd=1, relief=tk.SUNKEN).grid(row=row, column=0, columnspan=2, sticky="ew", pady=8)
+        row += 1
+
+        # --- Antenna sliders (independent left/right) ---
+        left_var = tk.DoubleVar(value=0.0)
+        right_var = tk.DoubleVar(value=0.0)
+
+        tk.Label(root, text="Left antenna (rad):", font=("Helvetica", 12, "bold")).grid(row=row, column=0, sticky="e")
+        tk.Scale(
+            root,
+            variable=left_var,
+            from_=-1.5,
+            to=1.5,
+            resolution=0.01,
+            orient=tk.HORIZONTAL,
+            length=300,
+        ).grid(row=row, column=1)
+        row += 1
+
+        tk.Label(root, text="Right antenna (rad):", font=("Helvetica", 12, "bold")).grid(row=row, column=0, sticky="e")
+        tk.Scale(
+            root,
+            variable=right_var,
+            from_=-1.5,
+            to=1.5,
+            resolution=0.01,
+            orient=tk.HORIZONTAL,
+            length=300,
+        ).grid(row=row, column=1)
+        row += 1
+
+        # Display current value prominently
+        value_label = tk.Label(root, text="antennas = [0.00, 0.00]", font=("Courier", 14))
+        value_label.grid(row=row, column=0, columnspan=2, pady=5)
+        row += 1
+
+        # Hint
+        tk.Label(
+            root,
+            text="Slide each antenna independently to find collision values.",
+            fg="gray",
+        ).grid(row=row, column=0, columnspan=2)
+        row += 1
+
+        mini.goto_target(create_head_pose(), antennas=[0.0, 0.0], duration=1.0)
+
+        def update_robot() -> None:
+            left = left_var.get()
+            right = right_var.get()
+            value_label.config(text=f"antennas = [{left:+.2f}, {right:+.2f}]")
+
+            head = np.eye(4)
+            roll = np.deg2rad(roll_var.get())
+            pitch = np.deg2rad(pitch_var.get())
+            yaw = np.deg2rad(yaw_var.get())
+            head[:3, :3] = R.from_euler("xyz", [roll, pitch, yaw], degrees=False).as_matrix()
+
+            mini.set_target(
+                head=head,
+                body_yaw=np.deg2rad(body_yaw_var.get()),
+                antennas=np.array([left, right]),
+            )
+
+            root.after(20, update_robot)
+
+        root.after(20, update_robot)
+
+        try:
+            root.mainloop()
+        except KeyboardInterrupt:
+            pass
+        finally:
+            left = left_var.get()
+            right = right_var.get()
+            print(f"\nFinal antenna values:")
+            print(f"  antennas = [{left:+.2f}, {right:+.2f}]")
+            root.destroy()
+
+
+if __name__ == "__main__":
+    main()

tests/audio_analysis.py

@@ -0,0 +1,290 @@
+"""Audio analysis utilities for sync testing.
+
+Generates test audio with beep markers, creates antenna collision
+trajectories, and detects both beep onsets and transient events
+in recorded audio for measuring audio-motion sync accuracy.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+# ──────── Test Signal Generation ──────────────────────────────────
+
+# Non-periodic beep times so large offsets can't accidentally align.
+DEFAULT_BEEP_TIMES = [1.0, 2.5, 4.0, 5.0, 7.0]
+
+
+def generate_sync_test_audio(
+    sr: int = 48000,
+    duration: float = 8.0,
+    beep_times: list[float] | None = None,
+    beep_freq: float = 1000.0,
+    beep_duration: float = 0.1,
+) -> tuple[np.ndarray, list[float]]:
+    """Generate audio with tonal beeps at known timestamps.
+
+    Returns (audio_data, beep_timestamps).
+    Beeps are sine waves with fade-in/out to avoid clicks.
+    """
+    if beep_times is None:
+        beep_times = DEFAULT_BEEP_TIMES
+
+    n_total = int(sr * duration)
+    audio = np.zeros(n_total, dtype=np.float32)
+
+    for t in beep_times:
+        start_sample = int(t * sr)
+        n_beep = int(beep_duration * sr)
+        if start_sample + n_beep > n_total:
+            continue
+        t_arr = np.arange(n_beep, dtype=np.float32) / sr
+        beep = 0.5 * np.sin(2 * np.pi * beep_freq * t_arr).astype(np.float32)
+        # Fade in/out (5ms each)
+        fade = int(0.005 * sr)
+        if fade > 0 and 2 * fade < n_beep:
+            beep[:fade] *= np.linspace(0, 1, fade, dtype=np.float32)
+            beep[-fade:] *= np.linspace(1, 0, fade, dtype=np.float32)
+        audio[start_sample : start_sample + n_beep] += beep
+
+    return audio, list(beep_times)
+
+
+def generate_collision_trajectory(
+    beep_times: list[float],
+    duration: float,
+    motion_sr: int = 100,
+) -> tuple[list[float], list[dict]]:
+    """Generate frames where antennas collide at each beep time.
+
+    Antennas start apart (±0.3 rad ≈ ±17°) and slam together
+    (0.0 rad) at each beep timestamp, then return apart.
+    Each collision takes ~200ms (100ms approach + 100ms return).
+
+    Returns (timestamps, frames).
+    """
+    from scipy.spatial.transform import Rotation as R
+
+    n = int(duration * motion_sr)
+    dt = 1.0 / motion_sr
+    rest_pos = 0.3  # rad, antennas apart
+
+    timestamps = []
+    frames = []
+    identity_pose = np.eye(4)
+
+    for i in range(n):
+        t = i * dt
+        timestamps.append(t)
+
+        # Compute antenna position: slam together at each beep time
+        antenna_val = rest_pos
+        for bt in beep_times:
+            approach_start = bt - 0.1  # 100ms before collision
+            return_end = bt + 0.1      # 100ms after collision
+
+            if approach_start <= t <= bt:
+                # Approaching: ease from rest to 0
+                frac = (t - approach_start) / 0.1
+                antenna_val = rest_pos * (1.0 - frac)
+                break
+            elif bt < t <= return_end:
+                # Returning: ease from 0 to rest
+                frac = (t - bt) / 0.1
+                antenna_val = rest_pos * frac
+                break
+
+        frames.append({
+            "head": identity_pose.tolist(),
+            "antennas": [-antenna_val, antenna_val],
+            "body_yaw": 0.0,
+            "check_collision": False,
+        })
+
+    return timestamps, frames
+
+
+# ──────── Audio Analysis ──────────────────────────────────────────
+
+
+def detect_beep_onsets(
+    audio: np.ndarray,
+    sr: int,
+    freq: float = 1000.0,
+    bandwidth: float = 200.0,
+    threshold_db: float = -20.0,
+    min_separation: float = 0.3,
+) -> list[float]:
+    """Detect onset times of tonal beeps using bandpass + envelope.
+
+    1. Bandpass filter around target frequency
+    2. Compute amplitude envelope via rectification + lowpass
+    3. Rising-edge threshold crossing for onset detection
+    """
+    from scipy.signal import butter, sosfilt
+
+    # Bandpass around beep frequency
+    low = max(20, freq - bandwidth / 2) / (sr / 2)
+    high = min(0.99, (freq + bandwidth / 2) / (sr / 2))
+    sos = butter(4, [low, high], btype="bandpass", output="sos")
+    filtered = sosfilt(sos, audio.astype(np.float64))
+
+    # Amplitude envelope: rectify + lowpass at 50Hz
+    envelope = np.abs(filtered)
+    lp_freq = min(50.0 / (sr / 2), 0.99)
+    sos_lp = butter(2, lp_freq, btype="lowpass", output="sos")
+    envelope = sosfilt(sos_lp, envelope)
+
+    # Normalize and threshold
+    peak_val = np.max(envelope)
+    if peak_val < 1e-10:
+        return []
+    envelope /= peak_val
+    threshold = 10 ** (threshold_db / 20)
+
+    # Rising-edge threshold crossings (onset = first sample above threshold)
+    above = envelope > threshold
+    edges = np.diff(above.astype(np.int8))
+    onset_indices = np.where(edges > 0)[0] + 1
+
+    # Filter by minimum separation
+    min_distance = int(min_separation * sr)
+    if len(onset_indices) > 1:
+        filtered_indices = [onset_indices[0]]
+        for idx in onset_indices[1:]:
+            if idx - filtered_indices[-1] >= min_distance:
+                filtered_indices.append(idx)
+        onset_indices = filtered_indices
+
+    return [idx / sr for idx in onset_indices]
+
+
+def detect_transient_onsets(
+    audio: np.ndarray,
+    sr: int,
+    highpass_freq: float = 2000.0,
+    threshold_db: float = -20.0,
+) -> list[float]:
+    """Detect impulsive sounds (antenna collisions) via spectral flux.
+
+    1. High-pass filter to separate from tonal beeps
+    2. Compute onset strength via spectral flux
+    3. Peak detection for sharp transients
+    """
+    from scipy.signal import butter, sosfilt, find_peaks
+
+    # High-pass to isolate transients from tonal beeps
+    hp_freq = min(highpass_freq / (sr / 2), 0.99)
+    sos = butter(4, hp_freq, btype="highpass", output="sos")
+    filtered = sosfilt(sos, audio.astype(np.float64))
+
+    # Onset strength: short-term energy in 5ms windows
+    win_samples = max(1, int(0.005 * sr))
+    energy = np.array([
+        np.sum(filtered[i : i + win_samples] ** 2)
+        for i in range(0, len(filtered) - win_samples, win_samples)
+    ])
+
+    if len(energy) < 2:
+        return []
+
+    # Spectral flux: positive differences in energy
+    flux = np.diff(energy)
+    flux = np.maximum(flux, 0)
+
+    peak_val = np.max(flux)
+    if peak_val < 1e-10:
+        return []
+    flux /= peak_val
+    threshold = 10 ** (threshold_db / 20)
+
+    # Find peaks with minimum 200ms separation
+    min_distance = max(1, int(0.2 * sr / win_samples))
+    peaks, _ = find_peaks(flux, height=threshold, distance=min_distance)
+
+    # Convert window indices to seconds
+    return [(p * win_samples) / sr for p in peaks]
+
+
+def measure_sync_offsets(
+    beep_onsets: list[float],
+    collision_onsets: list[float],
+    max_match_distance: float = 0.5,
+) -> dict:
+    """Match each beep to its nearest collision and compute offsets.
+
+    Returns dict with pairs, mean/max/std offset in milliseconds.
+    Positive offset means collision came AFTER beep.
+    """
+    pairs = []
+    remaining_collisions = list(collision_onsets)
+
+    for bt in beep_onsets:
+        if not remaining_collisions:
+            break
+        distances = [abs(ct - bt) for ct in remaining_collisions]
+        best_idx = int(np.argmin(distances))
+        if distances[best_idx] <= max_match_distance:
+            ct = remaining_collisions.pop(best_idx)
+            offset_ms = (ct - bt) * 1000.0
+            pairs.append((bt, ct, offset_ms))
+
+    offsets = [p[2] for p in pairs]
+    return {
+        "pairs": pairs,
+        "n_matched": len(pairs),
+        "n_beeps": len(beep_onsets),
+        "n_collisions": len(collision_onsets),
+        "mean_offset_ms": float(np.mean(offsets)) if offsets else float("nan"),
+        "max_offset_ms": float(np.max(np.abs(offsets))) if offsets else float("nan"),
+        "std_offset_ms": float(np.std(offsets)) if offsets else float("nan"),
+    }
+
+
+# ──────── Mic Recording Helper ────────────────────────────────────
+
+
+class MicRecorder:
+    """Record from laptop microphone using sounddevice.
+
+    Usage:
+        recorder = MicRecorder(sr=48000)
+        recorder.start()
+        # ... do stuff ...
+        audio = recorder.stop()  # returns np.ndarray
+    """
+
+    def __init__(self, sr: int = 48000, channels: int = 1):
+        self.sr = sr
+        self.channels = channels
+        self._frames: list[np.ndarray] = []
+        self._stream = None
+
+    def start(self) -> None:
+        import sounddevice as sd
+
+        self._frames = []
+
+        def callback(indata, frames, time_info, status):
+            self._frames.append(indata.copy())
+
+        self._stream = sd.InputStream(
+            samplerate=self.sr,
+            channels=self.channels,
+            dtype="float32",
+            callback=callback,
+        )
+        self._stream.start()
+
+    def stop(self) -> np.ndarray:
+        if self._stream is not None:
+            self._stream.stop()
+            self._stream.close()
+            self._stream = None
+        if not self._frames:
+            return np.zeros(0, dtype=np.float32)
+        audio = np.concatenate(self._frames, axis=0)
+        # Return mono (first channel if multi-channel)
+        if audio.ndim > 1:
+            audio = audio[:, 0]
+        return audio

tests/e2e/test_ui.py

@@ -118,14 +118,11 @@ class TestFormValidation:
             assert is_valid, f"Duration {val} should be valid but HTML5 validation rejected it"
 
     def test_audio_source_radios_exist(self, page: Page, base_url: str):
+        """Audio source radios are inline in the record hero section."""
         page.goto(base_url)
-        # Open settings drawer to access audio source radios
-        page.locator("#settings-btn").click()
-        page.wait_for_timeout(300)
-        expect(page.locator('input[name="audio-src"][value="mic"]')).to_be_visible()
-        expect(page.locator('input[name="audio-src"][value="none"]')).to_be_visible()
-        # Close drawer
-        page.locator("#settings-close").click()
+        expect(page.locator('input[name="audio-src"][value="silent"]')).to_be_visible()
+        expect(page.locator('input[name="audio-src"][value="upload"]')).to_be_visible()
+        expect(page.locator('input[name="audio-src"][value="robot"]')).to_be_visible()
 
     def test_label_field_exists(self, page: Page, base_url: str):
         page.goto(base_url)
@@ -140,13 +137,7 @@ class TestRecordingSubmission:
         page.goto(base_url)
         page.wait_for_timeout(2000)
 
-        # Open settings drawer and set audio source to "none"
-        page.locator("#settings-btn").click()
-        page.wait_for_timeout(300)
-        page.locator('input[name="audio-src"][value="none"]').check()
-        page.locator("#settings-close").click()
-        page.wait_for_timeout(300)
-
+        # Silent audio is the default — no need to change source
         page.locator("#rec-duration").fill("2")
         page.locator("#rec-name").fill("e2e-test")
 
@@ -189,12 +180,6 @@ class TestRecordingLifecycle:
         page.goto(base_url)
         page.wait_for_timeout(2000)
 
-        page.locator("#settings-btn").click()
-        page.wait_for_timeout(300)
-        page.locator('input[name="audio-src"][value="none"]').check()
-        page.locator("#settings-close").click()
-        page.wait_for_timeout(300)
-
         page.locator("#rec-duration").fill("2")
         page.locator("#rec-name").fill("lifecycle-test")
         page.locator("#record-btn").click()
@@ -211,12 +196,6 @@ class TestRecordingLifecycle:
         page.goto(base_url)
         page.wait_for_timeout(2000)
 
-        page.locator("#settings-btn").click()
-        page.wait_for_timeout(300)
-        page.locator('input[name="audio-src"][value="none"]').check()
-        page.locator("#settings-close").click()
-        page.wait_for_timeout(300)
-
         page.locator("#rec-duration").fill("2")
         page.locator("#record-btn").click()
         page.wait_for_timeout(2000)
@@ -232,12 +211,6 @@ class TestRecordingLifecycle:
         page.goto(base_url)
         page.wait_for_timeout(2000)
 
-        page.locator("#settings-btn").click()
-        page.wait_for_timeout(300)
-        page.locator('input[name="audio-src"][value="none"]').check()
-        page.locator("#settings-close").click()
-        page.wait_for_timeout(300)
-
         page.locator("#rec-duration").fill("2")
         page.locator("#record-btn").click()
         page.wait_for_timeout(2000)
@@ -514,41 +487,52 @@ class TestSwitchDataset:
 
 
 class TestAudioSourceRadios:
-    def test_default_audio_source(self, page: Page, base_url: str):
+    """Audio source radios are now inline in the record hero section."""
+
+    def test_default_audio_source_is_silent(self, page: Page, base_url: str):
         page.goto(base_url)
-        # Open settings drawer
-        page.locator("#settings-btn").click()
-        page.wait_for_timeout(300)
-        # Default may be mic (if audio available) or none
-        mic = page.locator('input[name="audio-src"][value="mic"]')
-        none = page.locator('input[name="audio-src"][value="none"]')
-        # At least one should be checked
-        mic_checked = mic.is_checked()
-        none_checked = none.is_checked()
-        assert mic_checked or none_checked
-        page.locator("#settings-close").click()
+        silent = page.locator('input[name="audio-src"][value="silent"]')
+        expect(silent).to_be_checked()
 
     def test_upload_radio_shows_upload_area(self, page: Page, base_url: str):
         page.goto(base_url)
-        page.locator("#settings-btn").click()
-        page.wait_for_timeout(300)
         page.locator('input[name="audio-src"][value="upload"]').check()
         page.wait_for_timeout(500)
         expect(page.locator("#audio-upload-section")).to_be_visible()
-        page.locator("#settings-close").click()
 
-    def test_none_radio_hides_upload_area(self, page: Page, base_url: str):
+    def test_robot_radio_shows_robot_area(self, page: Page, base_url: str):
+        page.goto(base_url)
+        page.locator('input[name="audio-src"][value="robot"]').check()
+        page.wait_for_timeout(500)
+        expect(page.locator("#robot-audio-section")).to_be_visible()
+
+    def test_silent_radio_hides_upload_area(self, page: Page, base_url: str):
         page.goto(base_url)
-        page.locator("#settings-btn").click()
-        page.wait_for_timeout(300)
         page.locator('input[name="audio-src"][value="upload"]').check()
         page.wait_for_timeout(500)
         expect(page.locator("#audio-upload-section")).to_be_visible()
 
-        page.locator('input[name="audio-src"][value="none"]').check()
+        page.locator('input[name="audio-src"][value="silent"]').check()
         page.wait_for_timeout(500)
         expect(page.locator("#audio-upload-section")).to_be_hidden()
-        page.locator("#settings-close").click()
+
+    def test_switching_source_hides_previous_panel(self, page: Page, base_url: str):
+        page.goto(base_url)
+        # Show upload panel
+        page.locator('input[name="audio-src"][value="upload"]').check()
+        page.wait_for_timeout(500)
+        expect(page.locator("#audio-upload-section")).to_be_visible()
+
+        # Switch to robot — upload should hide, robot should show
+        page.locator('input[name="audio-src"][value="robot"]').check()
+        page.wait_for_timeout(500)
+        expect(page.locator("#audio-upload-section")).to_be_hidden()
+        expect(page.locator("#robot-audio-section")).to_be_visible()
+
+        # Switch to silent — robot should hide
+        page.locator('input[name="audio-src"][value="silent"]').check()
+        page.wait_for_timeout(500)
+        expect(page.locator("#robot-audio-section")).to_be_hidden()
 
 
 # ──────── Settings panel tests ───────────────────────────────────────
@@ -564,18 +548,16 @@ class TestSettingsPanel:
         expect(page.locator("#dataset-root-input")).to_be_visible()
         page.locator("#settings-close").click()
 
-    def test_experimental_toggle(self, page: Page, base_url: str):
-        import httpx
-        # Enable motion_models via API first
-        httpx.post(f"{base_url}/api/experiments", json={"motion_models": True}, timeout=5)
-
+    def test_lead_compensation_section_visible(self, page: Page, base_url: str):
+        """Lead compensation settings should be visible in the settings drawer."""
         page.goto(base_url)
-        # Wait for poll to update the UI
-        page.wait_for_timeout(3000)
-
-        # After poll, the experimental checkbox should be attached
-        checkbox = page.locator("#feature-motion-models")
-        expect(checkbox).to_be_attached()
+        page.wait_for_timeout(2000)
+        page.locator("#settings-btn").click()
+        page.wait_for_timeout(300)
+        expect(page.locator("#lead-comp-section")).to_be_visible()
+        expect(page.locator("#lead-frames-head")).to_be_visible()
+        expect(page.locator("#lead-frames-antennas")).to_be_visible()
+        page.locator("#settings-close").click()
 
     def test_dataset_root_displayed(self, page: Page, base_url: str):
         page.goto(base_url)
@@ -597,12 +579,6 @@ class TestFormEdgeCases:
         page.goto(base_url)
         page.wait_for_timeout(2000)
 
-        page.locator("#settings-btn").click()
-        page.wait_for_timeout(300)
-        page.locator('input[name="audio-src"][value="none"]').check()
-        page.locator("#settings-close").click()
-        page.wait_for_timeout(300)
-
         page.locator("#rec-name").fill("")
         page.locator("#rec-duration").fill("2")
         page.locator("#record-btn").click()
@@ -618,12 +594,6 @@ class TestFormEdgeCases:
         page.goto(base_url)
         page.wait_for_timeout(2000)
 
-        page.locator("#settings-btn").click()
-        page.wait_for_timeout(300)
-        page.locator('input[name="audio-src"][value="none"]').check()
-        page.locator("#settings-close").click()
-        page.wait_for_timeout(300)
-
         long_label = "a" * 80
         page.locator("#rec-name").fill(long_label)
         page.locator("#rec-duration").fill("2")
@@ -640,12 +610,6 @@ class TestFormEdgeCases:
         page.goto(base_url)
         page.wait_for_timeout(2000)
 
-        page.locator("#settings-btn").click()
-        page.wait_for_timeout(300)
-        page.locator('input[name="audio-src"][value="none"]').check()
-        page.locator("#settings-close").click()
-        page.wait_for_timeout(300)
-
         page.locator("#rec-name").fill("my move @#$!")
         page.locator("#rec-duration").fill("2")
         page.locator("#record-btn").click()
@@ -709,17 +673,18 @@ class TestCommunitySection:
         tab = page.locator('.section-tab[data-tab="community"]')
         tab.click()
         page.wait_for_timeout(500)
-        fetch_btn = page.locator("#fetch-community-btn")
+        fetch_btn = page.locator("#download-community-btn")
         expect(fetch_btn).to_be_visible()
 
-    def test_fetch_community_button_clickable(self, page: Page, base_url: str):
+    def test_download_community_button_exists(self, page: Page, base_url: str):
+        """Download button should exist (disabled until items selected)."""
         page.goto(base_url)
         page.wait_for_timeout(2000)
         tab = page.locator('.section-tab[data-tab="community"]')
         tab.click()
         page.wait_for_timeout(500)
-        fetch_btn = page.locator("#fetch-community-btn")
-        expect(fetch_btn).to_be_enabled()
+        btn = page.locator("#download-community-btn")
+        expect(btn).to_be_attached()
 
 
 # ──────── HF upload section tests ─────────────────────────────────
@@ -760,13 +725,7 @@ class TestResponsiveness:
         page.goto(base_url)
         page.wait_for_timeout(2000)
 
-        # Set audio to silent to avoid audio dependency
-        page.locator("#settings-btn").click()
-        page.wait_for_timeout(300)
-        page.locator('input[name="audio-src"][value="none"]').check()
-        page.locator("#settings-close").click()
-        page.wait_for_timeout(300)
-
+        # Silent audio is the default — no settings drawer needed
         page.locator("#rec-duration").fill("10")
         page.locator("#record-btn").click()
         page.wait_for_timeout(2000)
@@ -826,13 +785,7 @@ class TestResponsiveness:
         page.goto(base_url)
         page.wait_for_timeout(2000)
 
-        # Set audio to silent
-        page.locator("#settings-btn").click()
-        page.wait_for_timeout(300)
-        page.locator('input[name="audio-src"][value="none"]').check()
-        page.locator("#settings-close").click()
-        page.wait_for_timeout(300)
-
+        # Silent audio is the default
         page.locator("#rec-duration").fill("10")
         page.locator("#record-btn").click()
         page.wait_for_timeout(2000)
@@ -854,27 +807,44 @@ class TestResponsiveness:
 # ──────── Mic-only radio tests ───────────────────────────────────────
 
 
-class TestMicOnlyOption:
-    """Tests for the mic-only (no motion) recording option."""
+class TestRecordAudioButton:
+    """Tests for the standalone Record Audio button (replaces mic-only radio)."""
 
-    def test_mic_only_radio_visible(self, page: Page, base_url: str):
-        """The mic-only radio option should be visible in settings."""
+    def test_record_audio_button_visible(self, page: Page, base_url: str):
+        """The Record Audio button should be visible in the record hero."""
         page.goto(base_url)
-        page.locator("#settings-btn").click()
-        page.wait_for_timeout(300)
-        mic_only = page.locator('input[name="audio-src"][value="mic-only"]')
-        expect(mic_only).to_be_attached()
-        page.locator("#settings-close").click()
+        btn = page.locator("#record-audio-btn")
+        expect(btn).to_be_visible()
 
-    def test_mic_only_radio_selectable(self, page: Page, base_url: str):
-        """The mic-only radio can be selected."""
+    def test_record_audio_button_has_label(self, page: Page, base_url: str):
+        """The Record Audio button should display its label."""
         page.goto(base_url)
-        page.locator("#settings-btn").click()
-        page.wait_for_timeout(300)
-        mic_only = page.locator('input[name="audio-src"][value="mic-only"]')
-        mic_only.check()
-        assert mic_only.is_checked()
-        page.locator("#settings-close").click()
+        btn = page.locator("#record-audio-btn")
+        expect(btn).to_contain_text("Record Audio")
+
+    def test_record_audio_hint_visible(self, page: Page, base_url: str):
+        """A hint below Record Audio explains where recordings go."""
+        page.goto(base_url)
+        hint = page.locator(".record-audio-hint")
+        expect(hint).to_be_visible()
+        hint_text = hint.text_content() or ""
+        assert "robot file" in hint_text.lower() or "moves list" in hint_text.lower()
+
+    def test_record_audio_triggers_recording(self, page: Page, base_url: str, test_marionette):
+        """Clicking Record Audio should start an audio-only recording."""
+        page.goto(base_url)
+        page.wait_for_timeout(2000)
+
+        page.locator("#rec-duration").fill("2")
+        page.locator("#record-audio-btn").click()
+        page.wait_for_timeout(2000)
+
+        badge_text = page.locator("#mode-badge").text_content() or ""
+        assert "idle" not in badge_text.lower()
+
+        # Cleanup
+        test_marionette._set_idle_state()
+        test_marionette._pending_recording = None
 
     def test_audio_only_badge_on_move(self, page: Page, base_url: str, test_marionette):
         """Audio-only moves should show an 'audio only' badge."""
@@ -952,3 +922,208 @@ class TestWelcomeMessagesUI:
         checked = page.locator('input[name="welcome-msgs"]:checked')
         assert checked.get_attribute("value") == "0"
         page.locator("#settings-close").click()
+
+
+# ──────── Move card display tests ──────────────────────────────────────
+
+
+class TestMoveCardDisplay:
+    """Tests for move card content — timestamps, badges, metadata."""
+
+    def _inject_move(self, test_marionette, move_id="e2e-card-test", audio_only=False):
+        import json, time
+        data_dir = test_marionette._dataset_dir
+        move_data = {
+            "description": "card display test",
+            "created_at": time.time(),
+            "time": [0.0, 0.01, 0.02],
+            "set_target_data": [
+                {"head": [[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1]], "antennas": [0,0], "body_yaw": 0.0}
+                for _ in range(3)
+            ],
+        }
+        if audio_only:
+            move_data["audio_only"] = True
+            move_data["set_target_data"] = []
+        (data_dir / f"{move_id}.json").write_text(json.dumps(move_data))
+        test_marionette._refresh_recordings()
+        return data_dir / f"{move_id}.json"
+
+    def test_move_card_shows_time(self, page: Page, base_url: str, test_marionette):
+        """Move cards should show time (hour:minute), not just the date."""
+        path = self._inject_move(test_marionette)
+        page.goto(base_url)
+        page.wait_for_timeout(2000)
+
+        meta = page.locator(".move-meta-row").first
+        meta_text = meta.text_content() or ""
+        # Should contain a colon-separated time (e.g. "14:32" or "2:32 PM")
+        assert ":" in meta_text
+
+        path.unlink(missing_ok=True)
+        test_marionette._refresh_recordings()
+
+    def test_audio_only_move_shows_badge(self, page: Page, base_url: str, test_marionette):
+        """Audio-only moves should display an 'audio only' badge."""
+        path = self._inject_move(test_marionette, "e2e-ao-card", audio_only=True)
+        page.goto(base_url)
+        page.wait_for_timeout(2000)
+
+        badge = page.locator(".move-badge.audio-only")
+        assert badge.count() > 0
+
+        path.unlink(missing_ok=True)
+        test_marionette._refresh_recordings()
+
+    def test_moves_list_stable_during_polling(self, page: Page, base_url: str, test_marionette):
+        """Move cards should not flicker during poll cycles (dirty-flag pattern)."""
+        path = self._inject_move(test_marionette, "e2e-stable-test")
+        page.goto(base_url)
+        page.wait_for_timeout(2000)
+
+        # Grab the first move card element reference
+        card = page.locator(".move-card").first
+        card_id = card.evaluate("el => el.dataset.moveId || el.textContent.slice(0,20)")
+
+        # Wait through two poll cycles (~3s) and verify the same element persists
+        page.wait_for_timeout(3500)
+        card_after = page.locator(".move-card").first
+        card_id_after = card_after.evaluate("el => el.dataset.moveId || el.textContent.slice(0,20)")
+        assert card_id == card_id_after
+
+        path.unlink(missing_ok=True)
+        test_marionette._refresh_recordings()
+
+
+# ──────── Robot file selection tests ────────────────────────────────────
+
+
+class TestRobotFileSelection:
+    """Tests for the 'Robot file' audio source tab and dropdown."""
+
+    def test_robot_tab_shows_dropdown(self, page: Page, base_url: str):
+        """Clicking the 'Robot file' radio should show the robot audio dropdown."""
+        page.goto(base_url)
+        page.locator('input[name="audio-src"][value="robot"]').check()
+        page.wait_for_timeout(500)
+        expect(page.locator("#robot-audio-section")).to_be_visible()
+        expect(page.locator("#robot-audio-select")).to_be_visible()
+
+    def test_robot_dropdown_has_options(self, page: Page, base_url: str, test_marionette):
+        """After injecting an audio-only move, the robot dropdown should list it."""
+        import json, time
+        data_dir = test_marionette._dataset_dir
+        # Create an audio-only move with a WAV file
+        move_data = {
+            "description": "robot file source",
+            "audio_only": True,
+            "created_at": time.time(),
+            "time": [0.0, 0.01],
+            "set_target_data": [],
+        }
+        (data_dir / "e2e-robot-src.json").write_text(json.dumps(move_data))
+        # Create a matching WAV file (robot audio list scans for WAV files)
+        import struct, wave
+        wav_path = data_dir / "e2e-robot-src.wav"
+        with wave.open(str(wav_path), "w") as wf:
+            wf.setnchannels(1)
+            wf.setsampwidth(2)
+            wf.setframerate(16000)
+            wf.writeframes(struct.pack("<" + "h" * 160, *([0] * 160)))
+        test_marionette._refresh_recordings()
+
+        page.goto(base_url)
+        page.locator('input[name="audio-src"][value="robot"]').check()
+        page.wait_for_timeout(1500)  # Allow time for file list to load
+
+        options = page.locator("#robot-audio-select option")
+        # Should have at least one file entry
+        assert options.count() >= 1
+
+        # Cleanup
+        (data_dir / "e2e-robot-src.json").unlink(missing_ok=True)
+        wav_path.unlink(missing_ok=True)
+        test_marionette._refresh_recordings()
+
+
+# ──────── Playback UI tests ────────────────────────────────────────────
+
+
+class TestPlaybackUI:
+    """Tests for playback UI controls — play button, phase overlay."""
+
+    def _inject_move(self, test_marionette, move_id="e2e-playui"):
+        import json, time
+        data_dir = test_marionette._dataset_dir
+        move_data = {
+            "description": "playback ui test",
+            "created_at": time.time(),
+            "time": [i * 0.01 for i in range(200)],
+            "set_target_data": [
+                {"head": [[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1]], "antennas": [0,0], "body_yaw": 0.0}
+                for _ in range(200)
+            ],
+        }
+        (data_dir / f"{move_id}.json").write_text(json.dumps(move_data))
+        test_marionette._refresh_recordings()
+        return data_dir / f"{move_id}.json"
+
+    def test_play_button_queues_playback(self, page: Page, base_url: str, test_marionette):
+        """Clicking play on a move should change mode from idle."""
+        path = self._inject_move(test_marionette)
+        page.goto(base_url)
+        page.wait_for_timeout(2000)
+
+        page.locator(".play-action").first.click()
+        page.wait_for_timeout(2000)
+
+        badge_text = page.locator("#mode-badge").text_content() or ""
+        assert "queued" in badge_text.lower() or "playing" in badge_text.lower()
+
+        test_marionette._set_idle_state()
+        test_marionette._pending_playback = None
+        path.unlink(missing_ok=True)
+        test_marionette._refresh_recordings()
+
+    def test_stop_button_exists_in_phase_overlay(self, page: Page, base_url: str):
+        """The phase overlay should contain a stop button."""
+        page.goto(base_url)
+        stop_btn = page.locator("#phase-stop-btn")
+        expect(stop_btn).to_be_attached()
+
+    def test_phase_overlay_hidden_when_idle(self, page: Page, base_url: str):
+        """Phase overlay should not have 'active' class in idle state."""
+        page.goto(base_url)
+        page.wait_for_timeout(2000)
+        overlay = page.locator("#phase-overlay")
+        expect(overlay).not_to_have_class(re.compile("active"))
+
+
+# ──────── Tab structure tests ──────────────────────────────────────────
+
+
+class TestTabStructure:
+    """Tests for the 3-tab layout: My Moves, Library, Community."""
+
+    def test_three_tabs_exist(self, page: Page, base_url: str):
+        page.goto(base_url)
+        expect(page.locator('.section-tab[data-tab="my-moves"]')).to_be_visible()
+        expect(page.locator('.section-tab[data-tab="library"]')).to_be_visible()
+        expect(page.locator('.section-tab[data-tab="community"]')).to_be_visible()
+
+    def test_my_moves_tab_active_by_default(self, page: Page, base_url: str):
+        page.goto(base_url)
+        expect(page.locator('.section-tab[data-tab="my-moves"]')).to_have_class(re.compile("active"))
+        expect(page.locator('#tab-my-moves')).to_have_class(re.compile("active"))
+
+    def test_library_tab_shows_library_panel(self, page: Page, base_url: str):
+        page.goto(base_url)
+        page.locator('.section-tab[data-tab="library"]').click()
+        page.wait_for_timeout(500)
+        expect(page.locator('#tab-library')).to_have_class(re.compile("active"))
+        expect(page.locator('#library-dataset-select')).to_be_visible()
+
+    def test_audio_source_label_visible(self, page: Page, base_url: str):
+        page.goto(base_url)
+        expect(page.locator(".audio-source-label")).to_be_visible()
+        expect(page.locator(".audio-source-label")).to_contain_text("Audio source")

tests/test_antenna_collision.py

@@ -0,0 +1,425 @@
+#!/usr/bin/env python3
+"""Test antenna collisions on Reachy Mini.
+
+Standalone script (no Marionette). Commands the left antenna to collide
+with the right antenna at known timestamps, using non-periodic intervals
+so detection alignment is unambiguous.
+
+Collision setup:
+  - Right antenna fixed at -0.68 rad
+  - Left antenna moves from 0.0 to 0.70 rad (collision at ~0.60 rad)
+  - Hold 100ms, then return to rest
+  - Low PID + flexible antennas = safe, produces audible click
+
+Records present antenna positions at 50Hz on the robot side (no network
+latency), saves to JSON, SCPs back, and analyzes to detect collision times
+from the trajectory.
+
+Usage:
+    python tests/test_antenna_collision.py [--host reachy-mini.local]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+import numpy as np
+
+# Collision parameters
+RIGHT_REST = -0.68    # right antenna fixed position (rad)
+LEFT_REST = 0.0       # left antenna rest position (rad)
+LEFT_COLLISION = 0.70 # left antenna collision target (past contact at ~0.60)
+HOLD_DURATION = 0.2   # seconds to hold at collision position
+
+# Non-periodic collision times — gaps are all different (1.3, 1.7, 2.3, 3.1s)
+# so there's no ambiguity when matching detected events to expected events.
+COLLISION_TIMES = [1.0, 2.3, 4.0, 6.3, 9.4]
+
+ROBOT_USER = "pollen"
+ROBOT_PYTHON = "/venvs/apps_venv/bin/python"
+REMOTE_RESULTS = "/tmp/collision_positions.json"
+
+ROBOT_COLLISION_SCRIPT = """\
+import numpy as np
+import os, sys, time, json
+
+collision_times = json.loads(sys.argv[1])
+right_rest = float(sys.argv[2])
+left_rest = float(sys.argv[3])
+left_collision = float(sys.argv[4])
+hold_duration = float(sys.argv[5])
+results_path = sys.argv[6]
+
+print(f"robot: connecting to ReachyMini", flush=True)
+from reachy_mini import ReachyMini
+from reachy_mini.utils import create_head_pose
+r = ReachyMini(media_backend="no_media")
+
+# Go to rest position
+r.goto_target(create_head_pose(), antennas=[left_rest, right_rest], duration=1.0)
+time.sleep(1.5)
+
+print(f"robot: rest position — left={left_rest}, right={right_rest}", flush=True)
+print(f"robot: will collide at times: {collision_times}", flush=True)
+print(f"robot: collision target: left={left_collision}, hold={hold_duration}s", flush=True)
+
+# State machine
+DT = 0.02  # 50Hz update rate
+total_duration = max(collision_times) + hold_duration + 1.0
+n_steps = int(total_duration / DT)
+
+# Build timeline: for each step, determine left antenna target
+left_targets = np.full(n_steps, left_rest, dtype=np.float64)
+for ct in collision_times:
+    start_step = int(ct / DT)
+    end_step = int((ct + hold_duration) / DT)
+    end_step = min(end_step, n_steps)
+    left_targets[start_step:end_step] = left_collision
+
+# Recording arrays
+timestamps = []
+left_present = []
+right_present = []
+left_target_log = []
+
+print("robot: MARK_START", flush=True)
+t0 = time.monotonic()
+
+for i in range(n_steps):
+    left = float(left_targets[i])
+    r.set_target(
+        head=np.eye(4),
+        body_yaw=0.0,
+        antennas=np.array([left, right_rest]),
+    )
+
+    # Read present position
+    pos = r.get_present_antenna_joint_positions()
+    elapsed = time.monotonic() - t0
+    timestamps.append(elapsed)
+    left_present.append(pos[0])
+    right_present.append(pos[1])
+    left_target_log.append(left)
+
+    # Real-time pacing
+    target_time = (i + 1) * DT
+    now = time.monotonic() - t0
+    if target_time > now:
+        time.sleep(target_time - now)
+
+elapsed = time.monotonic() - t0
+print(f"robot: finished {n_steps} steps in {elapsed:.3f}s (expected {total_duration:.3f}s)", flush=True)
+
+# Save results
+results = {
+    "collision_times": collision_times,
+    "left_collision_target": left_collision,
+    "right_rest": right_rest,
+    "hold_duration": hold_duration,
+    "timestamps": timestamps,
+    "left_present": left_present,
+    "right_present": right_present,
+    "left_target": left_target_log,
+}
+with open(results_path, "w") as f:
+    json.dump(results, f)
+print(f"robot: saved {len(timestamps)} samples to {results_path}", flush=True)
+
+# Return to rest
+r.goto_target(create_head_pose(), antennas=[left_rest, right_rest], duration=1.0)
+time.sleep(1.5)
+print("robot: done", flush=True)
+os._exit(0)
+"""
+
+
+def scp_to_robot(local_path: Path, remote_path: str, host: str) -> None:
+    """Copy a file to the robot via SCP."""
+    target = f"{ROBOT_USER}@{host}:{remote_path}"
+    result = subprocess.run(
+        ["scp", "-o", "ConnectTimeout=5", str(local_path), target],
+        capture_output=True, text=True, timeout=15,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"SCP failed: {result.stderr}")
+    print(f"  Copied to {target}")
+
+
+def scp_from_robot(remote_path: str, local_path: Path, host: str) -> None:
+    """Copy a file from the robot via SCP."""
+    source = f"{ROBOT_USER}@{host}:{remote_path}"
+    result = subprocess.run(
+        ["scp", "-o", "ConnectTimeout=5", source, str(local_path)],
+        capture_output=True, text=True, timeout=15,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"SCP failed: {result.stderr}")
+    print(f"  Copied from {source}")
+
+
+def run_on_robot(host: str) -> subprocess.Popen:
+    """SCP script to robot and start collision sequence (non-blocking)."""
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+        f.write(ROBOT_COLLISION_SCRIPT)
+        local_script = Path(f.name)
+
+    remote_script = "/tmp/collision_test.py"
+    try:
+        scp_to_robot(local_script, remote_script, host)
+    finally:
+        local_script.unlink()
+
+    args_str = (
+        f"{ROBOT_PYTHON} {remote_script} "
+        f"'{json.dumps(COLLISION_TIMES)}' "
+        f"{RIGHT_REST} {LEFT_REST} {LEFT_COLLISION} {HOLD_DURATION} "
+        f"{REMOTE_RESULTS}"
+    )
+    proc = subprocess.Popen(
+        ["ssh", "-o", "ConnectTimeout=5", f"{ROBOT_USER}@{host}", args_str],
+        stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
+    )
+    return proc
+
+
+def detect_collisions(data: dict) -> list[dict]:
+    """Detect collision events from present position trajectory.
+
+    For each commanded collision, finds the position peak time (when the
+    antenna reached its maximum excursion and reversed). This is the moment
+    of collision impact or max overshoot.
+
+    Returns list of dicts with detection details per event.
+    """
+    ts = np.array(data["timestamps"])
+    left_pos = np.array(data["left_present"])
+    left_tgt = np.array(data["left_target"])
+
+    # Find rising edges in target (rest → collision command)
+    tgt_diff = np.diff(left_tgt)
+    command_indices = np.where(tgt_diff > 0.3)[0]
+
+    events = []
+    for cmd_idx in command_indices:
+        cmd_time = ts[cmd_idx]
+
+        # Look 0-500ms after command for position peak
+        window_start = cmd_idx
+        window_end = min(cmd_idx + 25, len(ts))  # 500ms at 50Hz
+        if window_end <= window_start + 2:
+            continue
+
+        window_pos = left_pos[window_start:window_end]
+        window_ts = ts[window_start:window_end]
+
+        # Position peak = moment of max excursion (collision or overshoot)
+        peak_idx = np.argmax(window_pos)
+        peak_time = window_ts[peak_idx]
+        peak_pos = window_pos[peak_idx]
+
+        # Check for velocity stall (plateau = physical stop at collision)
+        dt = np.diff(window_ts)
+        dt[dt < 1e-6] = 1e-6
+        vel = np.diff(window_pos) / dt
+
+        # A stall is consecutive near-zero velocity while position > 0.1
+        stall_time = None
+        for j in range(len(vel) - 1):
+            if (abs(vel[j]) < 1.0 and abs(vel[j + 1]) < 1.0
+                    and window_pos[j + 1] > 0.1):
+                stall_time = window_ts[j + 1]
+                break
+
+        events.append({
+            "cmd_time": cmd_time,
+            "peak_time": peak_time,
+            "peak_pos": peak_pos,
+            "latency_ms": (peak_time - cmd_time) * 1000,
+            "stall_time": stall_time,
+        })
+
+    return events
+
+
+def plot_results(data: dict, events: list[dict], output_path: Path) -> None:
+    """Generate a plot of antenna trajectories with collision markers."""
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    ts = np.array(data["timestamps"])
+    left_pos = np.array(data["left_present"])
+    right_pos = np.array(data["right_present"])
+    left_tgt = np.array(data["left_target"])
+    expected_times = data["collision_times"]
+
+    fig, ax = plt.subplots(figsize=(14, 6))
+
+    # Plot antenna trajectories
+    ax.plot(ts, left_pos, "b-", linewidth=1.5, label="Left antenna (present)", zorder=3)
+    ax.plot(ts, right_pos, "r-", linewidth=1.5, label="Right antenna (present)", zorder=3)
+    ax.plot(ts, left_tgt, "b--", linewidth=0.8, alpha=0.4, label="Left antenna (target)")
+
+    # Expected collision times (green dashed)
+    for i, ct in enumerate(expected_times):
+        label = "Expected collision" if i == 0 else None
+        ax.axvline(ct, color="green", linestyle="--", linewidth=1.5, alpha=0.7, label=label)
+
+    # Detected collision times (red solid)
+    for i, ev in enumerate(events):
+        label = "Detected (peak)" if i == 0 else None
+        ax.axvline(ev["peak_time"], color="red", linestyle="-", linewidth=1.5, alpha=0.7, label=label)
+        # Annotate with peak position
+        ax.annotate(
+            f'{ev["peak_pos"]:.2f}r\n{ev["latency_ms"]:.0f}ms',
+            xy=(ev["peak_time"], ev["peak_pos"]),
+            xytext=(10, 10), textcoords="offset points",
+            fontsize=8, color="red",
+            arrowprops=dict(arrowstyle="->", color="red", lw=0.8),
+        )
+
+    ax.set_xlabel("Time (s)")
+    ax.set_ylabel("Position (rad)")
+    ax.set_title("Antenna Collision Test — Present Positions + Detection")
+    ax.legend(loc="upper right", fontsize=9)
+    ax.grid(True, alpha=0.3)
+    ax.set_xlim(ts[0] - 0.2, ts[-1] + 0.2)
+
+    fig.tight_layout()
+    fig.savefig(str(output_path), dpi=150)
+    plt.close(fig)
+    print(f"  Plot saved to {output_path}")
+
+
+def analyze_results(data: dict) -> dict:
+    """Analyze collision position data and print report."""
+    ts = np.array(data["timestamps"])
+    left_pos = np.array(data["left_present"])
+    left_tgt = np.array(data["left_target"])
+    expected_times = data["collision_times"]
+
+    print(f"\n{'='*60}")
+    print("Collision Detection Analysis")
+    print(f"{'='*60}")
+    print(f"  Samples: {len(ts)} at ~{1/np.mean(np.diff(ts)):.0f}Hz")
+    print(f"  Duration: {ts[-1]:.2f}s")
+    print(f"  Left antenna range: [{left_pos.min():.3f}, {left_pos.max():.3f}] rad")
+    print(f"  Expected collisions: {len(expected_times)} at {expected_times}")
+
+    # Detect collisions
+    events = detect_collisions(data)
+
+    # Per-collision detail
+    print(f"\n--- Per-collision detail ---")
+    for i, ev in enumerate(events):
+        stall_info = f", stall at t={ev['stall_time']:.3f}s" if ev["stall_time"] else ""
+        print(f"  Collision {i+1}: cmd t={ev['cmd_time']:.1f}s → "
+              f"peak {ev['peak_pos']:.3f} rad at t={ev['peak_time']:.3f}s "
+              f"(latency {ev['latency_ms']:.0f}ms{stall_info})")
+
+    # Match detected peaks to expected times
+    detected_peak_times = [ev["peak_time"] for ev in events]
+    print(f"\n--- Matching ---")
+    matched = 0
+    for i, et in enumerate(expected_times):
+        if not detected_peak_times:
+            print(f"  Expected {et:.1f}s: NO MATCH")
+            continue
+        nearest = min(detected_peak_times, key=lambda d: abs(d - et))
+        offset_ms = (nearest - et) * 1000
+        ok = abs(nearest - et) < 0.3
+        if ok:
+            matched += 1
+        status = "OK" if ok else "MISS"
+        print(f"  Expected {et:.1f}s → peak at {nearest:.3f}s "
+              f"(offset {offset_ms:+.0f}ms) [{status}]")
+
+    success = matched >= len(expected_times) - 1
+    print(f"\n  {'PASS' if success else 'FAIL'}: "
+          f"{matched}/{len(expected_times)} collisions matched")
+
+    # Generate plot
+    plot_path = Path("tests/collision_trajectory.png")
+    plot_results(data, events, plot_path)
+
+    return {
+        "success": success,
+        "expected": len(expected_times),
+        "detected": len(events),
+        "matched": matched,
+        "events": events,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Antenna collision test")
+    parser.add_argument("--host", default="reachy-mini.local", help="Robot hostname/IP")
+    args = parser.parse_args()
+
+    print(f"\n{'='*60}")
+    print("Antenna Collision Test")
+    print(f"{'='*60}")
+    print(f"  Right antenna fixed at {RIGHT_REST} rad")
+    print(f"  Left antenna: rest={LEFT_REST}, collision={LEFT_COLLISION} rad")
+    print(f"  Collision times: {COLLISION_TIMES}")
+    gaps = [COLLISION_TIMES[i+1] - COLLISION_TIMES[i] for i in range(len(COLLISION_TIMES)-1)]
+    print(f"  Gaps between collisions: {[f'{g:.1f}s' for g in gaps]}")
+    print(f"  Hold duration: {HOLD_DURATION}s\n")
+
+    # Stop any running app
+    print("[1/4] Stopping any running app on robot...")
+    subprocess.run(
+        ["ssh", "-o", "ConnectTimeout=5", f"{ROBOT_USER}@{args.host}",
+         "curl -sf -X POST http://127.0.0.1:8000/api/apps/stop-current-app >/dev/null 2>&1 || true"],
+        capture_output=True, timeout=10,
+    )
+    time.sleep(1)
+    print("  Done")
+
+    # Run collisions (with position recording)
+    print("\n[2/4] Running collision sequence + recording positions...")
+    proc = run_on_robot(args.host)
+
+    # Stream robot output in real time
+    print("\n--- Robot output ---")
+    for line in iter(proc.stdout.readline, ""):
+        line = line.rstrip()
+        if line:
+            print(f"  {line}")
+    proc.wait()
+    print("--- End robot output ---")
+
+    if proc.returncode != 0:
+        print(f"\nFAILED — Return code: {proc.returncode}")
+        return 1
+
+    # SCP results back
+    print("\n[3/4] Fetching position data from robot...")
+    local_results = Path("tests/collision_positions.json")
+    scp_from_robot(REMOTE_RESULTS, local_results, args.host)
+    print(f"  Saved to {local_results}")
+
+    # Load and analyze
+    print("\n[4/4] Analyzing collision trajectory...")
+    with open(local_results) as f:
+        data = json.load(f)
+
+    result = analyze_results(data)
+
+    print(f"\n{'='*60}")
+    if result["success"]:
+        print("RESULT: PASS — Collisions detected from present position trajectory")
+    else:
+        print("RESULT: FAIL — Could not reliably detect collisions")
+    print(f"{'='*60}\n")
+
+    return 0 if result["success"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/test_api.py

@@ -585,27 +585,27 @@ class TestHfAutoLogin:
         """When HF login is detected, username appears in state."""
         marionette._hf_checked = False
         marionette._hf_username = None
-        import marionette.main as mm
-        original_whoami = mm.hf_whoami
-        mm.hf_whoami = lambda: {"name": "testuser"}
+        import marionette.datasets as md
+        original_whoami = md.hf_whoami
+        md.hf_whoami = lambda: {"name": "testuser"}
         try:
             config = client.get("/api/state").json()["config"]
             assert config["hf_username"] == "testuser"
         finally:
-            mm.hf_whoami = original_whoami
+            md.hf_whoami = original_whoami
 
     def test_cached_after_first_check(self, marionette: Marionette):
         """HF login check is cached after first call."""
-        import marionette.main as mm
+        import marionette.datasets as md
         call_count = 0
-        original_whoami = mm.hf_whoami
+        original_whoami = md.hf_whoami
 
         def counting_whoami():
             nonlocal call_count
             call_count += 1
             return {"name": "cached-user"}
 
-        mm.hf_whoami = counting_whoami
+        md.hf_whoami = counting_whoami
         marionette._hf_checked = False
         marionette._hf_username = None
         try:
@@ -615,17 +615,17 @@ class TestHfAutoLogin:
             assert result2 == "cached-user"
             assert call_count == 1
         finally:
-            mm.hf_whoami = original_whoami
+            md.hf_whoami = original_whoami
 
     def test_sync_without_username_uses_autodetected(
         self, client: TestClient, marionette: Marionette, tmp_path: Path
     ):
         """Sync endpoint uses auto-detected username when none provided."""
-        import marionette.main as mm
-        original_whoami = mm.hf_whoami
+        import marionette.datasets as md
+        original_whoami = md.hf_whoami
         marionette._hf_checked = False
         marionette._hf_username = None
-        mm.hf_whoami = lambda: {"name": "auto-user"}
+        md.hf_whoami = lambda: {"name": "auto-user"}
         try:
             # No moves exist, so sync will fail with 400 (no moves found),
             # but we verify it gets past the username check
@@ -633,26 +633,26 @@ class TestHfAutoLogin:
             # 404 = move not found (got past the username validation)
             assert resp.status_code == 404
         finally:
-            mm.hf_whoami = original_whoami
+            md.hf_whoami = original_whoami
 
     def test_sync_without_username_and_no_login_returns_400(
         self, client: TestClient, marionette: Marionette
     ):
         """Sync without username and no HF login returns 400."""
-        import marionette.main as mm
-        original_whoami = mm.hf_whoami
-        original_get_token = mm.hf_get_token
+        import marionette.datasets as md
+        original_whoami = md.hf_whoami
+        original_get_token = md.hf_get_token
         marionette._hf_checked = False
         marionette._hf_username = None
-        mm.hf_whoami = None
-        mm.hf_get_token = lambda: None
+        md.hf_whoami = None
+        md.hf_get_token = lambda: None
         try:
             resp = client.post("/api/datasets/sync", json={"move_ids": ["some-move"]})
             assert resp.status_code == 400
             assert "not logged in" in resp.json()["detail"].lower()
         finally:
-            mm.hf_whoami = original_whoami
-            mm.hf_get_token = original_get_token
+            md.hf_whoami = original_whoami
+            md.hf_get_token = original_get_token
 
 
 class TestHfTokenLogin:
@@ -668,11 +668,11 @@ class TestHfTokenLogin:
 
     def test_save_token_success(self, client: TestClient, marionette: Marionette):
         """Valid token saves and returns username."""
-        import marionette.main as mm
-        original_login = mm.hf_login
-        original_whoami = mm.hf_whoami
-        mm.hf_login = lambda token, add_to_git_credential: None
-        mm.hf_whoami = lambda: {"name": "token-user"}
+        import marionette.datasets as md
+        original_login = md.hf_login
+        original_whoami = md.hf_whoami
+        md.hf_login = lambda token, add_to_git_credential: None
+        md.hf_whoami = lambda: {"name": "token-user"}
         try:
             resp = client.post("/api/hf-auth/save-token", json={"token": "hf_valid_token_12345"})
             assert resp.status_code == 200
@@ -683,14 +683,14 @@ class TestHfTokenLogin:
             config = client.get("/api/state").json()["config"]
             assert config["hf_username"] == "token-user"
         finally:
-            mm.hf_login = original_login
-            mm.hf_whoami = original_whoami
+            md.hf_login = original_login
+            md.hf_whoami = original_whoami
 
     def test_delete_token_success(self, client: TestClient, marionette: Marionette):
         """Logout clears the cached username."""
-        import marionette.main as mm
-        original_logout = mm.hf_logout
-        mm.hf_logout = lambda: None
+        import marionette.datasets as md
+        original_logout = md.hf_logout
+        md.hf_logout = lambda: None
         marionette._hf_username = "some-user"
         marionette._hf_checked = True
         try:
@@ -700,15 +700,15 @@ class TestHfTokenLogin:
             assert marionette._hf_username is None
             assert marionette._hf_checked is False
         finally:
-            mm.hf_logout = original_logout
+            md.hf_logout = original_logout
 
     def test_delete_token_clears_state(self, client: TestClient, marionette: Marionette):
         """After logout, state reports no username."""
-        import marionette.main as mm
-        original_logout = mm.hf_logout
-        original_whoami = mm.hf_whoami
-        mm.hf_logout = lambda: None
-        mm.hf_whoami = lambda: None  # whoami returns None after logout
+        import marionette.datasets as md
+        original_logout = md.hf_logout
+        original_whoami = md.hf_whoami
+        md.hf_logout = lambda: None
+        md.hf_whoami = lambda: None  # whoami returns None after logout
         marionette._hf_username = "old-user"
         marionette._hf_checked = True
         try:
@@ -716,8 +716,8 @@ class TestHfTokenLogin:
             config = client.get("/api/state").json()["config"]
             assert config["hf_username"] is None
         finally:
-            mm.hf_logout = original_logout
-            mm.hf_whoami = original_whoami
+            md.hf_logout = original_logout
+            md.hf_whoami = original_whoami
 
 
 class TestSensorData:
@@ -813,6 +813,9 @@ class TestTimingSync:
     def test_uploaded_audio_waits_for_capture_start(
         self, marionette: Marionette, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
     ):
+        """Audio preload is now done in _perform_recording before countdown.
+        _run_capture_and_save receives the pre-built audio thread and events.
+        Verify the audio thread waits for audio_start (fired by on_capture_start)."""
         wav_path = tmp_path / "uploaded.wav"
         wav_path.write_bytes(b"fake")
         request = RecordingRequest(
@@ -827,15 +830,14 @@ class TestTimingSync:
 
         events: list[tuple[str, bool | None]] = []
 
-        class _FakeMedia:
-            def get_output_audio_samplerate(self):
-                return 16000
-
-            def start_playing(self):
-                events.append(("pipeline_primed", None))
-
         class _FakeReachy:
-            media = _FakeMedia()
+            class media:
+                @staticmethod
+                def get_output_audio_samplerate():
+                    return 16000
+
+        audio_start = threading.Event()
+        audio_stop = threading.Event()
 
         def fake_play_preloaded_wav(
             _reachy, _wav_data, _stop_event, chunk_duration=0.02, pipeline_ready=False, start_signal=None
@@ -845,6 +847,14 @@ class TestTimingSync:
                 start_signal.wait(timeout=1.0)
             events.append(("audio_after_wait", start_signal.is_set() if start_signal else None))
 
+        audio_thread = threading.Thread(
+            target=fake_play_preloaded_wav,
+            args=(_FakeReachy(), (np.zeros(8, dtype=np.float32), 16000), audio_stop),
+            kwargs={"pipeline_ready": True, "start_signal": audio_start},
+            daemon=True,
+        )
+        audio_thread.start()
+
         def fake_capture_motion(
             _reachy,
             _stop_event,
@@ -857,15 +867,17 @@ class TestTimingSync:
                 on_capture_start()
             return [0.0, 0.01], [{"head": [], "antennas": [], "body_yaw": 0.0, "check_collision": False}], [], None
 
-        monkeypatch.setattr(marionette, "_preload_wav", lambda *_a, **_k: (np.zeros(8, dtype=np.float32), 16000))
-        monkeypatch.setattr(marionette, "_play_preloaded_wav", fake_play_preloaded_wav)
         monkeypatch.setattr(marionette, "_capture_motion", fake_capture_motion)
         monkeypatch.setattr(marionette, "_save_recording", lambda *_a, **_k: None)
         monkeypatch.setattr(marionette, "_refresh_recordings", lambda *_a, **_k: None)
 
-        marionette._run_capture_and_save(_FakeReachy(), threading.Event(), request)
+        marionette._run_capture_and_save(
+            _FakeReachy(), threading.Event(), request,
+            audio_thread=audio_thread,
+            audio_start=audio_start,
+            audio_stop=audio_stop,
+        )
 
-        assert ("pipeline_primed", None) in events
         assert ("audio_before_wait", False) in events
         assert ("audio_after_wait", True) in events
 
@@ -888,7 +900,7 @@ class TestTimingSync:
             def set_target_antenna_joint_positions(self, _antennas):
                 return None
 
-        monkeypatch.setattr("marionette.main.time.time", lambda: (_ for _ in ()).throw(RuntimeError("wall clock used")))
+        monkeypatch.setattr("marionette.recording.time.time", lambda: (_ for _ in ()).throw(RuntimeError("wall clock used")))
         marionette._playback_cancel_event.clear()
         assert marionette._stream_playback(_FakeReachy(), _FakeMove()) is True
 
@@ -949,15 +961,21 @@ class TestCommunityDatasets:
         resp = client.post("/api/datasets/download", json={"repo_id": "no-slash"})
         assert resp.status_code == 400
 
-    def test_download_rejects_duplicate_folder(self, client: TestClient, marionette: Marionette):
+    def test_download_removes_existing_folder_on_redownload(self, client: TestClient, marionette: Marionette):
         # Create a dataset first
         client.post("/api/datasets", json={"name": "existing-ds"})
-        # Try to download with the same folder name
+        old_ids = {e.dataset_id for e in marionette._datasets.values() if e.folder == "existing-ds"}
+        assert old_ids, "dataset should exist"
+        # Re-download replaces the old entry (will fail at HF fetch, but the old entry
+        # should already be removed before the network call).
         resp = client.post("/api/datasets/download", json={
             "repo_id": "someone/existing-ds",
             "name": "existing-ds",
         })
-        assert resp.status_code == 409
+        # Network call fails → 502, but old entry was cleaned up
+        assert resp.status_code == 502
+        remaining = {e.dataset_id for e in marionette._datasets.values() if e.folder == "existing-ds"}
+        assert remaining.isdisjoint(old_ids), "old dataset entry should have been removed"
 
 
 # ──────── Corrupt data tests ────────────────────────────────────────
@@ -1071,23 +1089,23 @@ class TestSyncDatasetExtended:
         assert resp.status_code == 422
 
     def test_sync_nonexistent_moves(self, client: TestClient, marionette: Marionette):
-        import marionette.main as mm
-        original_whoami = mm.hf_whoami
+        import marionette.datasets as md
+        original_whoami = md.hf_whoami
         marionette._hf_checked = False
         marionette._hf_username = None
-        mm.hf_whoami = lambda: {"name": "testuser"}
+        md.hf_whoami = lambda: {"name": "testuser"}
         try:
             resp = client.post("/api/datasets/sync", json={
                 "move_ids": ["fake-move-id"],
             })
             assert resp.status_code == 404
         finally:
-            mm.hf_whoami = original_whoami
+            md.hf_whoami = original_whoami
 
     def test_sync_no_active_dataset(self, client: TestClient, marionette: Marionette):
-        import marionette.main as mm
-        original_whoami = mm.hf_whoami
-        mm.hf_whoami = lambda: {"name": "testuser"}
+        import marionette.datasets as md
+        original_whoami = md.hf_whoami
+        md.hf_whoami = lambda: {"name": "testuser"}
         marionette._hf_checked = False
         marionette._hf_username = None
 
@@ -1104,7 +1122,7 @@ class TestSyncDatasetExtended:
             assert resp.status_code == 404
         finally:
             marionette._active_dataset_id = old_id
-            mm.hf_whoami = original_whoami
+            md.hf_whoami = original_whoami
 
     def test_record_on_downloaded_dataset_rejected(
         self, client: TestClient, marionette: Marionette
@@ -1118,81 +1136,6 @@ class TestSyncDatasetExtended:
         assert "downloaded" in resp.json()["detail"].lower()
 
 
-# ──────── Mic AGC config tests ────────────────────────────────────
-
-
-class TestMicAgcConfig:
-    """Tests for _disable_mic_agc / _restore_mic_agc."""
-
-    AGC_PATCH = "reachy_mini.media.audio_control_utils.init_respeaker_usb"
-
-    def _make_mock_respeaker(self, agc_value=None):
-        """Create a mock ReSpeaker device."""
-        mock = MagicMock()
-        mock.read.return_value = agc_value if agc_value is not None else [1]
-        return mock
-
-    def test_disable_agc_writes_zero(self, marionette: Marionette):
-        mock_dev = self._make_mock_respeaker(agc_value=[1])
-        with patch(self.AGC_PATCH, return_value=mock_dev):
-            marionette._disable_mic_agc()
-        mock_dev.read.assert_called_once_with("PP_AGCONOFF")
-        mock_dev.write.assert_called_once_with("PP_AGCONOFF", [0])
-        mock_dev.close.assert_called_once()
-        assert marionette._original_agc == [1]
-
-    def test_disable_agc_saves_original_value(self, marionette: Marionette):
-        mock_dev = self._make_mock_respeaker(agc_value=[0])
-        with patch(self.AGC_PATCH, return_value=mock_dev):
-            marionette._disable_mic_agc()
-        assert marionette._original_agc == [0]
-
-    def test_disable_agc_no_device(self, marionette: Marionette):
-        """Gracefully skips when no USB device is found."""
-        with patch(self.AGC_PATCH, return_value=None):
-            marionette._disable_mic_agc()  # Should not raise
-        assert not hasattr(marionette, "_original_agc") or marionette._original_agc is None
-
-    def test_disable_agc_import_error(self, marionette: Marionette):
-        """Gracefully skips when audio_control_utils is not importable."""
-        with patch.dict("sys.modules", {"reachy_mini.media.audio_control_utils": None}):
-            marionette._disable_mic_agc()  # Should not raise
-
-    def test_disable_agc_usb_error(self, marionette: Marionette):
-        """Gracefully handles USB communication errors."""
-        mock_dev = self._make_mock_respeaker()
-        mock_dev.read.side_effect = OSError("USB transfer failed")
-        with patch(self.AGC_PATCH, return_value=mock_dev):
-            marionette._disable_mic_agc()  # Should not raise
-
-    def test_restore_agc_writes_original(self, marionette: Marionette):
-        marionette._original_agc = [1]
-        mock_dev = self._make_mock_respeaker()
-        with patch(self.AGC_PATCH, return_value=mock_dev):
-            marionette._restore_mic_agc()
-        mock_dev.write.assert_called_once_with("PP_AGCONOFF", [1])
-        mock_dev.close.assert_called_once()
-
-    def test_restore_agc_skips_when_no_original(self, marionette: Marionette):
-        """Skips restore when AGC was never disabled (no _original_agc)."""
-        mock_dev = self._make_mock_respeaker()
-        with patch(self.AGC_PATCH, return_value=mock_dev):
-            marionette._restore_mic_agc()  # Should not raise
-        mock_dev.write.assert_not_called()
-
-    def test_restore_agc_skips_when_original_is_none(self, marionette: Marionette):
-        marionette._original_agc = None
-        mock_dev = self._make_mock_respeaker()
-        with patch(self.AGC_PATCH, return_value=mock_dev):
-            marionette._restore_mic_agc()
-        mock_dev.write.assert_not_called()
-
-    def test_restore_agc_device_gone(self, marionette: Marionette):
-        """Gracefully handles device disconnected at restore time."""
-        marionette._original_agc = [1]
-        with patch(self.AGC_PATCH, return_value=None):
-            marionette._restore_mic_agc()  # Should not raise
-
 
 # ──────── API contract tests (refactoring protection) ──────────────
 
@@ -1448,3 +1391,323 @@ class TestVersionEndpoint:
         data = client.get("/api/version").json()
         assert isinstance(data["version"], str)
         assert len(data["version"]) > 0
+
+
+# ──────── Robot audio endpoint tests ─────────────────────────────
+
+
+class TestRobotAudioEndpoints:
+    """Tests for GET /api/robot-audio and POST /api/robot-audio/select."""
+
+    def test_robot_audio_list_empty_by_default(self, client: TestClient):
+        resp = client.get("/api/robot-audio")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "files" in data
+        assert isinstance(data["files"], list)
+
+    def test_robot_audio_list_finds_audio_only_wav(
+        self, client: TestClient, marionette: Marionette
+    ):
+        """Audio-only recordings appear in robot-audio list."""
+        from conftest import make_wav_bytes
+        import json
+
+        wav_bytes = make_wav_bytes(1.0)
+        wav_path = marionette._dataset_dir / "robot-test.wav"
+        wav_path.write_bytes(wav_bytes)
+        json_path = marionette._dataset_dir / "robot-test.json"
+        json_path.write_text(json.dumps({
+            "time": [0.0], "set_target_data": [], "audio_only": True,
+        }))
+        marionette._refresh_recordings()
+
+        resp = client.get("/api/robot-audio")
+        assert resp.status_code == 200
+        files = resp.json()["files"]
+        names = [f["name"] for f in files]
+        assert "robot-test" in names
+
+        # Each file should have name, path, duration_seconds
+        for f in files:
+            assert "name" in f
+            assert "path" in f
+            assert "duration_seconds" in f
+
+        # Cleanup
+        wav_path.unlink(missing_ok=True)
+        json_path.unlink(missing_ok=True)
+        marionette._refresh_recordings()
+
+    def test_robot_audio_excludes_non_audio_only(
+        self, client: TestClient, marionette: Marionette
+    ):
+        """Normal motion moves with WAV files should NOT appear in robot-audio list."""
+        from conftest import make_wav_bytes
+        import json
+
+        wav_bytes = make_wav_bytes(1.0)
+        wav_path = marionette._dataset_dir / "motion-move.wav"
+        wav_path.write_bytes(wav_bytes)
+        json_path = marionette._dataset_dir / "motion-move.json"
+        json_path.write_text(json.dumps({
+            "time": [0.0, 0.01],
+            "set_target_data": [
+                {"head": [[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1]], "antennas": [0,0]},
+                {"head": [[1,0,0,0],[0,1,0,0],[0,0,1,0],[0,0,0,1]], "antennas": [0,0]},
+            ],
+        }))
+        marionette._refresh_recordings()
+
+        resp = client.get("/api/robot-audio")
+        assert resp.status_code == 200
+        files = resp.json()["files"]
+        names = [f["name"] for f in files]
+        assert "motion-move" not in names
+
+        # Cleanup
+        wav_path.unlink(missing_ok=True)
+        json_path.unlink(missing_ok=True)
+        marionette._refresh_recordings()
+
+    def test_robot_audio_select_returns_upload_id(
+        self, client: TestClient, marionette: Marionette
+    ):
+        """POST /api/robot-audio/select with valid WAV returns upload_id."""
+        from conftest import make_wav_bytes
+
+        wav_bytes = make_wav_bytes(1.5)
+        wav_path = marionette._dataset_dir / "selectable.wav"
+        wav_path.write_bytes(wav_bytes)
+
+        resp = client.post(
+            "/api/robot-audio/select",
+            json={"path": str(wav_path)},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "upload_id" in data
+        assert data["filename"] == "selectable.wav"
+
+        # Cleanup
+        wav_path.unlink(missing_ok=True)
+
+    def test_robot_audio_select_rejects_path_traversal(self, client: TestClient):
+        """Path outside dataset/temp dirs is rejected with 403."""
+        resp = client.post(
+            "/api/robot-audio/select",
+            json={"path": "/etc/passwd"},
+        )
+        assert resp.status_code in (403, 404)
+
+    def test_robot_audio_select_rejects_nonexistent(self, client: TestClient):
+        """Non-existent file returns 404."""
+        resp = client.post(
+            "/api/robot-audio/select",
+            json={"path": "/tmp/does-not-exist-at-all.wav"},
+        )
+        assert resp.status_code in (403, 404)
+
+    def test_robot_audio_select_rejects_non_wav(
+        self, client: TestClient, marionette: Marionette
+    ):
+        """Non-WAV file within allowed dirs is rejected."""
+        txt_path = marionette._dataset_dir / "notes.txt"
+        txt_path.write_text("not audio")
+
+        resp = client.post(
+            "/api/robot-audio/select",
+            json={"path": str(txt_path)},
+        )
+        assert resp.status_code == 400
+
+        # Cleanup
+        txt_path.unlink(missing_ok=True)
+
+
+# ──────── Move metadata tests ────────────────────────────────────
+
+
+class TestMoveMetadata:
+    """Tests for move metadata fields in the state endpoint."""
+
+    def test_move_created_at_is_float(
+        self, client: TestClient, marionette: Marionette, sample_move_json: dict
+    ):
+        """created_at should be a numeric Unix timestamp."""
+        data_dir = marionette._dataset_dir
+        (data_dir / "meta-test.json").write_text(json.dumps(sample_move_json))
+        marionette._refresh_recordings()
+
+        state = client.get("/api/state").json()
+        move = next((m for m in state["moves"] if m["id"] == "meta-test"), None)
+        assert move is not None
+        assert isinstance(move["created_at"], float)
+        assert move["created_at"] > 0
+
+        # Cleanup
+        (data_dir / "meta-test.json").unlink(missing_ok=True)
+        marionette._refresh_recordings()
+
+    def test_move_created_at_is_recent(
+        self, client: TestClient, marionette: Marionette, sample_move_json: dict
+    ):
+        """A freshly created move should have a recent timestamp."""
+        import time
+
+        data_dir = marionette._dataset_dir
+        (data_dir / "recent-test.json").write_text(json.dumps(sample_move_json))
+        marionette._refresh_recordings()
+
+        state = client.get("/api/state").json()
+        move = next((m for m in state["moves"] if m["id"] == "recent-test"), None)
+        assert move is not None
+        # Should be within last 60 seconds
+        assert abs(move["created_at"] - time.time()) < 60
+
+        # Cleanup
+        (data_dir / "recent-test.json").unlink(missing_ok=True)
+        marionette._refresh_recordings()
+
+    def test_audio_only_move_in_robot_audio_list(
+        self, client: TestClient, marionette: Marionette
+    ):
+        """Audio-only recordings with WAV files should appear in robot-audio list."""
+        from conftest import make_wav_bytes
+
+        data_dir = marionette._dataset_dir
+        move_data = {
+            "description": "audio only for robot list",
+            "audio_only": True,
+            "time": [0.0, 0.01, 0.02],
+            "set_target_data": [],
+        }
+        (data_dir / "ao-robot.json").write_text(json.dumps(move_data))
+        (data_dir / "ao-robot.wav").write_bytes(make_wav_bytes(1.0))
+        marionette._refresh_recordings()
+
+        resp = client.get("/api/robot-audio")
+        assert resp.status_code == 200
+        names = [f["name"] for f in resp.json()["files"]]
+        assert "ao-robot" in names
+
+        # Cleanup
+        (data_dir / "ao-robot.json").unlink(missing_ok=True)
+        (data_dir / "ao-robot.wav").unlink(missing_ok=True)
+        marionette._refresh_recordings()
+
+    def test_record_with_uploaded_audio_accepted(
+        self, client: TestClient, marionette: Marionette
+    ):
+        """Upload audio, then start a recording using that audio ID."""
+        from conftest import make_wav_bytes
+
+        wav = make_wav_bytes(2.0)
+        upload_resp = client.post(
+            "/api/upload-audio",
+            files={"file": ("track.wav", BytesIO(wav), "audio/wav")},
+        )
+        assert upload_resp.status_code == 200
+        upload_id = upload_resp.json()["upload_id"]
+
+        resp = client.post("/api/record", json={
+            "duration": 2.0,
+            "record_audio": False,
+            "record_motion": True,
+            "uploaded_audio_id": upload_id,
+            "label": "with-audio",
+        })
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["accepted"] is True
+        assert marionette._pending_recording is not None
+        assert marionette._pending_recording.uploaded_audio_path is not None
+
+        # Cleanup
+        marionette._set_idle_state()
+        marionette._pending_recording = None
+
+
+# ──────── Audio analysis unit tests ───────────────────────────────
+
+
+class TestAudioAnalysis:
+    """Unit tests for the audio analysis utilities (no hardware needed)."""
+
+    def test_generate_sync_test_audio(self):
+        from audio_analysis import generate_sync_test_audio
+
+        audio, beep_times = generate_sync_test_audio(sr=48000, duration=8.0)
+        assert audio.shape == (8 * 48000,)
+        assert len(beep_times) == 5
+        # Audio should have non-zero samples at beep positions
+        for t in beep_times:
+            idx = int(t * 48000)
+            assert np.max(np.abs(audio[idx : idx + 4800])) > 0.1
+
+    def test_detect_beep_onsets_synthetic(self):
+        from audio_analysis import detect_beep_onsets, generate_sync_test_audio
+
+        sr = 48000
+        audio, expected_times = generate_sync_test_audio(sr=sr, duration=8.0)
+        detected = detect_beep_onsets(audio, sr, freq=1000.0)
+
+        # Should detect all 5 beeps
+        assert len(detected) >= 4, f"Only detected {len(detected)}/5 beeps"
+
+        # Each detected onset should be within 100ms of an expected time
+        for dt in detected:
+            distances = [abs(dt - et) for et in expected_times]
+            assert min(distances) < 0.1, f"Detected onset {dt:.3f}s doesn't match any expected beep"
+
+    def test_generate_collision_trajectory(self):
+        from audio_analysis import generate_collision_trajectory
+
+        beep_times = [1.0, 2.5, 4.0]
+        timestamps, frames = generate_collision_trajectory(beep_times, duration=5.0)
+
+        assert len(timestamps) == 500  # 5s * 100Hz
+        assert len(frames) == 500
+
+        # At a beep time, antennas should be at 0 (collided)
+        idx_at_beep = int(1.0 * 100)
+        antennas = frames[idx_at_beep]["antennas"]
+        assert abs(antennas[0]) < 0.05, f"Antennas should be near 0 at collision: {antennas}"
+
+        # Between beeps, antennas should be apart
+        idx_between = int(1.5 * 100)
+        antennas = frames[idx_between]["antennas"]
+        assert abs(antennas[0]) > 0.1, f"Antennas should be apart between beeps: {antennas}"
+
+    def test_measure_sync_offsets(self):
+        from audio_analysis import measure_sync_offsets
+
+        beep_onsets = [1.0, 2.5, 4.0, 5.0, 7.0]
+        # Collisions arrive 50ms after each beep
+        collision_onsets = [1.05, 2.55, 4.05, 5.05, 7.05]
+
+        result = measure_sync_offsets(beep_onsets, collision_onsets)
+        assert result["n_matched"] == 5
+        assert abs(result["mean_offset_ms"] - 50.0) < 1.0
+        assert result["max_offset_ms"] < 55.0
+
+    def test_measure_sync_offsets_missing_collisions(self):
+        from audio_analysis import measure_sync_offsets
+
+        beep_onsets = [1.0, 2.5, 4.0, 5.0, 7.0]
+        collision_onsets = [1.02, 4.01]  # Only 2 matched
+
+        result = measure_sync_offsets(beep_onsets, collision_onsets)
+        assert result["n_matched"] == 2
+        assert result["n_beeps"] == 5
+
+    def test_datasets_payload_sorted_by_label(self, marionette: Marionette, tmp_path: Path):
+        """Verify _datasets_payload returns entries sorted by label."""
+        ds_root = marionette._dataset_root
+        (ds_root / "zzz_first_label").mkdir(exist_ok=True)
+        (ds_root / "aaa_last_label").mkdir(exist_ok=True)
+        marionette._load_dataset_registry()
+
+        payload = marionette._datasets_payload()
+        labels = [e.get("label", e["id"]) for e in payload["entries"]]
+        assert labels == sorted(labels, key=str.lower), f"Entries not sorted by label: {labels}"

tests/test_audio_roundtrip.py

@@ -0,0 +1,314 @@
+#!/usr/bin/env python3
+"""Standalone audio roundtrip test: generate beeps, play on robot, record on laptop mic.
+
+No Marionette involved. Tests raw audio pipeline:
+  laptop generates WAV → SCP to robot → robot plays via reachy_mini SDK
+  → laptop mic records → analyze for beep detection
+
+Usage:
+    python tests/test_audio_roundtrip.py [--host reachy-mini.local]
+"""
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+import numpy as np
+import sounddevice as sd
+import soundfile as sf
+
+# Add tests/ to path for audio_analysis imports
+sys.path.insert(0, str(Path(__file__).parent))
+from audio_analysis import detect_beep_onsets, generate_sync_test_audio
+
+ROBOT_USER = "pollen"
+ROBOT_PYTHON = "/venvs/apps_venv/bin/python"
+ROBOT_SR = 16000  # robot output sample rate
+LAPTOP_SR = 48000  # laptop mic sample rate
+
+
+BEEP_FREQ = 2000.0  # Hz — away from speech/noise band
+BEEP_DURATION = 0.2  # seconds — long enough for strong detection
+BEEP_AMPLITUDE = 0.9  # loud
+
+
+def generate_test_wav(path: Path, sr: int = ROBOT_SR) -> list[float]:
+    """Generate a WAV file with 5 loud beeps at non-periodic timestamps."""
+    # Non-periodic gaps (1.3, 1.7, 2.3, 3.1s) — no ambiguity when aligning
+    beep_times = [0.5, 1.8, 3.5, 5.8, 8.9]
+    duration = 10.0
+    n_total = int(sr * duration)
+    audio = np.zeros(n_total, dtype=np.float32)
+
+    for t in beep_times:
+        start = int(t * sr)
+        n_beep = int(BEEP_DURATION * sr)
+        if start + n_beep > n_total:
+            continue
+        t_arr = np.arange(n_beep, dtype=np.float32) / sr
+        beep = BEEP_AMPLITUDE * np.sin(2 * np.pi * BEEP_FREQ * t_arr).astype(np.float32)
+        # Fade in/out (5ms)
+        fade = int(0.005 * sr)
+        if fade > 0 and 2 * fade < n_beep:
+            beep[:fade] *= np.linspace(0, 1, fade, dtype=np.float32)
+            beep[-fade:] *= np.linspace(1, 0, fade, dtype=np.float32)
+        audio[start : start + n_beep] += beep
+
+    sf.write(str(path), audio, sr)
+    print(f"  Generated {path.name}: {duration}s, {sr}Hz, {BEEP_FREQ}Hz beeps, {len(beep_times)} at {beep_times}")
+    return beep_times
+
+
+def scp_to_robot(local_path: Path, remote_path: str, host: str) -> None:
+    """Copy a file to the robot via SCP."""
+    target = f"{ROBOT_USER}@{host}:{remote_path}"
+    result = subprocess.run(
+        ["scp", "-o", "ConnectTimeout=5", str(local_path), target],
+        capture_output=True, text=True, timeout=15,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"SCP failed: {result.stderr}")
+    print(f"  Copied to {target}")
+
+
+ROBOT_PLAY_SCRIPT = """\
+import numpy as np
+import soundfile as sf
+import os, sys, time
+
+wav_path = sys.argv[1]
+print("robot: loading WAV " + wav_path, flush=True)
+data, sr = sf.read(wav_path, dtype="float32")
+if data.ndim > 1:
+    data = data[:, 0]  # mono
+
+print("robot: connecting to ReachyMini", flush=True)
+from reachy_mini import ReachyMini
+r = ReachyMini()
+
+robot_sr = int(r.media.get_output_audio_samplerate() or 16000)
+print(f"robot: output sr={robot_sr}, file sr={sr}", flush=True)
+
+# Resample if needed
+if sr != robot_sr:
+    from scipy.signal import resample
+    n_out = int(len(data) * robot_sr / sr)
+    data = resample(data, n_out).astype(np.float32)
+    print(f"robot: resampled to {robot_sr}Hz ({len(data)} samples)", flush=True)
+
+# Play via push_audio_sample at real-time speed
+chunk_duration = 0.02  # 20ms
+chunk_size = int(robot_sr * chunk_duration)
+r.media.start_playing()
+
+print("robot: MARK_START", flush=True)
+t0 = time.monotonic()
+for i in range(0, len(data), chunk_size):
+    chunk = data[i:i+chunk_size]
+    if len(chunk) < chunk_size:
+        chunk = np.pad(chunk, (0, chunk_size - len(chunk)))
+    r.media.push_audio_sample(chunk)
+    # Sleep to maintain real-time pacing
+    elapsed = time.monotonic() - t0
+    target = (i + chunk_size) / robot_sr
+    if target > elapsed:
+        time.sleep(target - elapsed)
+
+elapsed = time.monotonic() - t0
+print(f"robot: pushed {len(data)} samples in {elapsed:.3f}s (audio={len(data)/robot_sr:.3f}s)", flush=True)
+
+# Wait for buffer to drain
+time.sleep(0.5)
+r.media.stop_playing()
+print("robot: done", flush=True)
+os._exit(0)
+"""
+
+REMOTE_PLAY_SCRIPT = "/tmp/roundtrip_play.py"
+
+
+def play_on_robot(host: str, wav_path: str) -> subprocess.Popen:
+    """Start playback on the robot via SSH (non-blocking).
+
+    SCPs a playback script to the robot, then executes it.
+    Returns the Popen process so we can wait/kill it.
+    """
+    # Write script to a temp file and SCP it
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+        f.write(ROBOT_PLAY_SCRIPT)
+        local_script = Path(f.name)
+    try:
+        scp_to_robot(local_script, REMOTE_PLAY_SCRIPT, host)
+    finally:
+        local_script.unlink()
+
+    proc = subprocess.Popen(
+        ["ssh", "-o", "ConnectTimeout=5", f"{ROBOT_USER}@{host}",
+         f"{ROBOT_PYTHON} {REMOTE_PLAY_SCRIPT} {wav_path}"],
+        stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
+    )
+    return proc
+
+
+def record_from_mic(duration: float, sr: int = LAPTOP_SR) -> np.ndarray:
+    """Record from default laptop mic for `duration` seconds."""
+    print(f"  Recording from laptop mic for {duration:.1f}s at {sr}Hz...")
+    audio = sd.rec(int(duration * sr), samplerate=sr, channels=1, dtype="float32")
+    sd.wait()
+    return audio.flatten()
+
+
+def analyze_recording(
+    captured: np.ndarray,
+    sr: int,
+    expected_beep_times: list[float],
+    beep_freq: float = BEEP_FREQ,
+) -> dict:
+    """Analyze captured audio for beep detection."""
+    detected = detect_beep_onsets(
+        captured, sr, freq=beep_freq, bandwidth=150.0, threshold_db=-12.0,
+        min_separation=1.0,  # beeps are ≥1.3s apart
+    )
+
+    print(f"\n=== Analysis ===")
+    print(f"  Captured: {len(captured)} samples ({len(captured)/sr:.2f}s)")
+    print(f"  Expected beeps: {len(expected_beep_times)} at {expected_beep_times}")
+    print(f"  Detected beeps: {len(detected)} at {[f'{t:.3f}' for t in detected]}")
+
+    # Compute RMS level
+    rms = np.sqrt(np.mean(captured ** 2))
+    peak = np.max(np.abs(captured))
+    print(f"  Audio levels: RMS={rms:.6f}, peak={peak:.6f}")
+
+    if not detected:
+        print("  FAIL: No beeps detected!")
+        return {"success": False, "detected": 0, "expected": len(expected_beep_times)}
+
+    # Try to match detected beeps to expected (with unknown offset)
+    # The mic recording starts before playback, so there's an offset
+    best_offset = None
+    best_matches = 0
+    for d in detected:
+        for e in expected_beep_times:
+            candidate_offset = d - e
+            matches = 0
+            for et in expected_beep_times:
+                shifted = et + candidate_offset
+                if any(abs(shifted - dt) < 0.15 for dt in detected):
+                    matches += 1
+            if matches > best_matches:
+                best_matches = matches
+                best_offset = candidate_offset
+
+    print(f"  Best alignment: offset={best_offset:.3f}s, matched {best_matches}/{len(expected_beep_times)}")
+
+    if best_offset is not None:
+        for et in expected_beep_times:
+            shifted = et + best_offset
+            match = min(detected, key=lambda d: abs(d - shifted))
+            error_ms = (match - shifted) * 1000
+            matched = abs(match - shifted) < 0.15
+            status = "OK" if matched else "MISS"
+            print(f"    expected {et:.1f}s → shifted {shifted:.3f}s, nearest {match:.3f}s ({error_ms:+.1f}ms) [{status}]")
+
+    success = best_matches >= max(1, len(expected_beep_times) - 1)
+    print(f"\n  {'PASS' if success else 'FAIL'}: {best_matches}/{len(expected_beep_times)} beeps matched")
+
+    return {
+        "success": success,
+        "detected": len(detected),
+        "expected": len(expected_beep_times),
+        "matched": best_matches,
+        "offset_s": best_offset,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Audio roundtrip test")
+    parser.add_argument("--host", default="reachy-mini.local", help="Robot hostname/IP")
+    args = parser.parse_args()
+
+    print(f"\n{'='*60}")
+    print("Audio Roundtrip Test: Laptop → Robot speakers → Laptop mic")
+    print(f"{'='*60}\n")
+
+    # Step 1: Stop any running app
+    print("[1/5] Stopping any running app on robot...")
+    subprocess.run(
+        ["ssh", "-o", "ConnectTimeout=5", f"{ROBOT_USER}@{args.host}",
+         "curl -sf -X POST http://127.0.0.1:8000/api/apps/stop-current-app >/dev/null 2>&1 || true"],
+        capture_output=True, timeout=10,
+    )
+    time.sleep(1)
+    print("  Done")
+
+    # Step 2: Generate test WAV
+    print("\n[2/5] Generating test audio...")
+    with tempfile.TemporaryDirectory() as tmpdir:
+        wav_path = Path(tmpdir) / "beeps.wav"
+        expected_times = generate_test_wav(wav_path, sr=ROBOT_SR)
+
+        # Step 3: SCP to robot
+        print("\n[3/5] Copying WAV to robot...")
+        remote_wav = "/tmp/roundtrip_test_beeps.wav"
+        scp_to_robot(wav_path, remote_wav, args.host)
+
+        # Also save locally for reference
+        local_ref = Path(tmpdir) / "beeps_reference.wav"
+
+    # Step 4: Start mic recording, then trigger playback
+    print("\n[4/5] Starting mic recording + robot playback...")
+    record_duration = 25.0  # 10s audio + ~8s SSH startup + buffer
+
+    # Start mic recording in background
+    print(f"  Starting {record_duration}s mic recording...")
+    mic_data = sd.rec(
+        int(record_duration * LAPTOP_SR),
+        samplerate=LAPTOP_SR, channels=1, dtype="float32",
+    )
+
+    # Give mic a moment to start, then trigger robot playback
+    time.sleep(0.5)
+    print("  Triggering robot playback...")
+    proc = play_on_robot(args.host, remote_wav)
+
+    # Wait for both mic recording and robot playback to finish
+    sd.wait()
+    print("  Mic recording done")
+
+    # Collect robot output
+    try:
+        stdout, _ = proc.communicate(timeout=30)
+        for line in stdout.strip().split("\n"):
+            print(f"  {line}")
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        print("  WARNING: Robot playback process timed out")
+
+    captured = mic_data.flatten()
+
+    # Save captured audio for manual inspection
+    captured_path = Path("tests/captured_roundtrip.wav")
+    sf.write(str(captured_path), captured, LAPTOP_SR)
+    print(f"  Saved captured audio to {captured_path}")
+
+    # Step 5: Analyze
+    print("\n[5/5] Analyzing captured audio...")
+    result = analyze_recording(captured, LAPTOP_SR, expected_times)
+
+    print(f"\n{'='*60}")
+    if result["success"]:
+        print("RESULT: PASS — Beeps successfully detected through roundtrip")
+    else:
+        print("RESULT: FAIL — Could not reliably detect beeps")
+    print(f"{'='*60}\n")
+
+    return 0 if result["success"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/test_beep_collision_sync.py

@@ -0,0 +1,486 @@
+#!/usr/bin/env python3
+"""Combined beep + collision sync test.
+
+The robot plays beeps through its speaker AND performs antenna collisions,
+with exactly 1.0s between each beep and its corresponding collision.
+The laptop mic records everything. Since both events are detected from
+the same mic recording, the measured interval is free of cross-clock bias.
+
+If audio and motion are perfectly synced, each beep-collision pair should
+be exactly 1.0s apart in the mic recording. Deviations measure the true
+audio-motion sync error.
+
+Beep times (non-periodic, gaps 1.3/1.7/2.3/3.1s):
+    [1.0, 2.3, 4.0, 6.3, 9.4]
+Collision times (each beep + 1.0s):
+    [2.0, 3.3, 5.0, 7.3, 10.4]
+
+Usage:
+    python tests/test_beep_collision_sync.py [--host reachy-mini.local]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+import numpy as np
+import sounddevice as sd
+import soundfile as sf
+
+sys.path.insert(0, str(Path(__file__).parent))
+from audio_analysis import detect_beep_onsets, detect_transient_onsets
+
+# Timing — non-periodic gaps (1.3, 1.7, 2.3, 3.1s)
+BEEP_TIMES = [1.0, 2.3, 4.0, 6.3, 9.4]
+BEEP_COLLISION_OFFSET = 1.0  # seconds between beep and its collision
+COLLISION_TIMES = [t + BEEP_COLLISION_OFFSET for t in BEEP_TIMES]
+
+# Audio parameters
+BEEP_FREQ = 2000.0
+BEEP_DURATION = 0.2
+BEEP_AMPLITUDE = 0.9
+ROBOT_SR = 16000
+
+# Collision parameters
+RIGHT_REST = -0.68
+LEFT_REST = 0.0
+LEFT_COLLISION = 0.70
+HOLD_DURATION = 0.2
+
+ROBOT_USER = "pollen"
+ROBOT_PYTHON = "/venvs/apps_venv/bin/python"
+LAPTOP_SR = 48000
+MIC_DURATION = 30.0
+REMOTE_RESULTS = "/tmp/beep_collision_results.json"
+
+ROBOT_SCRIPT = """\
+import numpy as np
+import os, sys, time, json
+
+beep_times = json.loads(sys.argv[1])
+collision_times = json.loads(sys.argv[2])
+right_rest = float(sys.argv[3])
+left_rest = float(sys.argv[4])
+left_collision = float(sys.argv[5])
+hold_duration = float(sys.argv[6])
+wav_path = sys.argv[7]
+results_path = sys.argv[8]
+beep_freq = float(sys.argv[9])
+beep_duration = float(sys.argv[10])
+beep_amplitude = float(sys.argv[11])
+
+print("robot: connecting to ReachyMini", flush=True)
+from reachy_mini import ReachyMini
+from reachy_mini.utils import create_head_pose
+r = ReachyMini()
+
+robot_sr = int(r.media.get_output_audio_samplerate() or 16000)
+print(f"robot: audio sr={robot_sr}", flush=True)
+
+# Generate beep audio
+total_duration = max(collision_times) + hold_duration + 1.0
+n_total = int(robot_sr * total_duration)
+audio = np.zeros(n_total, dtype=np.float32)
+for bt in beep_times:
+    start = int(bt * robot_sr)
+    n_beep = int(beep_duration * robot_sr)
+    if start + n_beep > n_total:
+        continue
+    t_arr = np.arange(n_beep, dtype=np.float32) / robot_sr
+    beep = beep_amplitude * np.sin(2 * np.pi * beep_freq * t_arr).astype(np.float32)
+    fade = int(0.005 * robot_sr)
+    if fade > 0 and 2 * fade < n_beep:
+        beep[:fade] *= np.linspace(0, 1, fade, dtype=np.float32)
+        beep[-fade:] *= np.linspace(1, 0, fade, dtype=np.float32)
+    audio[start:start + n_beep] += beep
+
+print(f"robot: generated {total_duration:.1f}s audio with {len(beep_times)} beeps", flush=True)
+
+# Build collision timeline at 50Hz
+DT = 0.02
+n_steps = int(total_duration / DT)
+left_targets = np.full(n_steps, left_rest, dtype=np.float64)
+for ct in collision_times:
+    start_step = int(ct / DT)
+    end_step = int((ct + hold_duration) / DT)
+    end_step = min(end_step, n_steps)
+    left_targets[start_step:end_step] = left_collision
+
+# Go to rest
+r.goto_target(create_head_pose(), antennas=[left_rest, right_rest], duration=1.0)
+time.sleep(1.5)
+print(f"robot: beeps at {beep_times}", flush=True)
+print(f"robot: collisions at {collision_times}", flush=True)
+
+# Recording arrays
+timestamps = []
+left_present = []
+right_present = []
+left_target_log = []
+
+# Start audio playback
+r.media.start_playing()
+r.media.push_audio_sample(np.zeros(160, dtype=np.float32))
+time.sleep(0.05)
+
+# Audio chunk tracking
+chunk_size = int(robot_sr * DT)  # 20ms audio chunks match motion DT
+audio_idx = 0
+
+print("robot: MARK_START", flush=True)
+t0 = time.monotonic()
+
+for i in range(n_steps):
+    # Push audio chunk
+    chunk_start = i * chunk_size
+    chunk_end = chunk_start + chunk_size
+    if chunk_end <= len(audio):
+        r.media.push_audio_sample(audio[chunk_start:chunk_end])
+
+    # Set antenna target
+    left = float(left_targets[i])
+    r.set_target(
+        head=np.eye(4),
+        body_yaw=0.0,
+        antennas=np.array([left, right_rest]),
+    )
+
+    # Read present position
+    pos = r.get_present_antenna_joint_positions()
+    elapsed = time.monotonic() - t0
+    timestamps.append(elapsed)
+    left_present.append(pos[0])
+    right_present.append(pos[1])
+    left_target_log.append(left)
+
+    # Real-time pacing
+    target_time = (i + 1) * DT
+    now = time.monotonic() - t0
+    if target_time > now:
+        time.sleep(target_time - now)
+
+elapsed = time.monotonic() - t0
+print(f"robot: finished {n_steps} steps in {elapsed:.3f}s", flush=True)
+
+# Drain audio buffer and stop
+time.sleep(0.5)
+r.media.stop_playing()
+
+# Save results
+results = {
+    "beep_times": beep_times,
+    "collision_times": collision_times,
+    "beep_collision_offset": collision_times[0] - beep_times[0],
+    "left_collision_target": left_collision,
+    "right_rest": right_rest,
+    "hold_duration": hold_duration,
+    "timestamps": timestamps,
+    "left_present": left_present,
+    "right_present": right_present,
+    "left_target": left_target_log,
+}
+with open(results_path, "w") as f:
+    json.dump(results, f)
+print(f"robot: saved {len(timestamps)} samples to {results_path}", flush=True)
+
+r.goto_target(create_head_pose(), antennas=[left_rest, right_rest], duration=1.0)
+time.sleep(1.5)
+print("robot: done", flush=True)
+os._exit(0)
+"""
+
+
+def scp_to_robot(local_path: Path, remote_path: str, host: str) -> None:
+    target = f"{ROBOT_USER}@{host}:{remote_path}"
+    result = subprocess.run(
+        ["scp", "-o", "ConnectTimeout=5", str(local_path), target],
+        capture_output=True, text=True, timeout=15,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"SCP failed: {result.stderr}")
+    print(f"  Copied to {target}")
+
+
+def scp_from_robot(remote_path: str, local_path: Path, host: str) -> None:
+    source = f"{ROBOT_USER}@{host}:{remote_path}"
+    result = subprocess.run(
+        ["scp", "-o", "ConnectTimeout=5", source, str(local_path)],
+        capture_output=True, text=True, timeout=15,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"SCP failed: {result.stderr}")
+    print(f"  Copied from {source}")
+
+
+def start_robot(host: str) -> subprocess.Popen:
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+        f.write(ROBOT_SCRIPT)
+        local_script = Path(f.name)
+
+    remote_script = "/tmp/beep_collision_sync.py"
+    try:
+        scp_to_robot(local_script, remote_script, host)
+    finally:
+        local_script.unlink()
+
+    args_str = (
+        f"{ROBOT_PYTHON} {remote_script} "
+        f"'{json.dumps(BEEP_TIMES)}' "
+        f"'{json.dumps(COLLISION_TIMES)}' "
+        f"{RIGHT_REST} {LEFT_REST} {LEFT_COLLISION} {HOLD_DURATION} "
+        f"/dev/null "  # wav_path unused, generated inline
+        f"{REMOTE_RESULTS} "
+        f"{BEEP_FREQ} {BEEP_DURATION} {BEEP_AMPLITUDE}"
+    )
+    proc = subprocess.Popen(
+        ["ssh", "-o", "ConnectTimeout=5", f"{ROBOT_USER}@{host}", args_str],
+        stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
+    )
+    return proc
+
+
+def plot_combined(
+    mic_audio: np.ndarray,
+    mic_sr: int,
+    mic_start: float,
+    mark_start: float,
+    robot_data: dict,
+    detected_beeps: list[float],
+    detected_collisions: list[float],
+    pairs: list[dict],
+    output_path: Path,
+) -> None:
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    mic_t = np.arange(len(mic_audio)) / mic_sr
+    robot_offset = mark_start - mic_start
+
+    robot_ts = np.array(robot_data["timestamps"])
+    left_pos = np.array(robot_data["left_present"])
+    right_pos = np.array(robot_data["right_present"])
+    left_tgt = np.array(robot_data["left_target"])
+
+    fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(18, 10), sharex=True)
+
+    # --- Top: Mic waveform ---
+    ax1.plot(mic_t, mic_audio, "k-", linewidth=0.3, alpha=0.5)
+    ax1.set_ylabel("Mic amplitude")
+    ax1.set_title("Beep + Collision Sync Test — Laptop Mic Recording")
+    ax1.grid(True, alpha=0.3)
+
+    # Detected beeps (blue)
+    for i, bt in enumerate(detected_beeps):
+        label = "Detected beep" if i == 0 else None
+        ax1.axvline(bt, color="blue", linestyle="-", linewidth=1.2, alpha=0.7, label=label)
+
+    # Detected collisions (red)
+    for i, ct in enumerate(detected_collisions):
+        label = "Detected collision" if i == 0 else None
+        ax1.axvline(ct, color="red", linestyle="-", linewidth=1.2, alpha=0.7, label=label)
+
+    # Annotate pairs
+    for p in pairs:
+        mid = (p["beep_mic_t"] + p["collision_mic_t"]) / 2
+        ax1.annotate(
+            f'{p["interval_ms"]:.0f}ms',
+            xy=(mid, ax1.get_ylim()[1] * 0.8),
+            ha="center", fontsize=9, color="purple", fontweight="bold",
+            bbox=dict(boxstyle="round,pad=0.2", facecolor="lightyellow", alpha=0.8),
+        )
+
+    ax1.legend(loc="upper right", fontsize=9)
+
+    # --- Bottom: Robot trajectory ---
+    ax2.plot(robot_ts + robot_offset, left_pos, "b-", linewidth=1.5, label="Left antenna (present)")
+    ax2.plot(robot_ts + robot_offset, right_pos, "r-", linewidth=1.5, label="Right antenna (present)")
+    ax2.plot(robot_ts + robot_offset, left_tgt, "b--", linewidth=0.8, alpha=0.4, label="Left antenna (target)")
+
+    # Expected command times (robot clock → mic clock)
+    for i, bt in enumerate(BEEP_TIMES):
+        mic_bt = robot_offset + bt
+        label = "Beep cmd" if i == 0 else None
+        ax2.axvline(mic_bt, color="blue", linestyle="--", linewidth=1.0, alpha=0.5, label=label)
+    for i, ct in enumerate(COLLISION_TIMES):
+        mic_ct = robot_offset + ct
+        label = "Collision cmd" if i == 0 else None
+        ax2.axvline(mic_ct, color="red", linestyle="--", linewidth=1.0, alpha=0.5, label=label)
+
+    # Detected events on trajectory panel too
+    for bt in detected_beeps:
+        ax2.axvline(bt, color="blue", linestyle="-", linewidth=0.8, alpha=0.4)
+    for ct in detected_collisions:
+        ax2.axvline(ct, color="red", linestyle="-", linewidth=0.8, alpha=0.4)
+
+    ax2.set_xlabel("Time since mic start (s)")
+    ax2.set_ylabel("Position (rad)")
+    ax2.set_title("Robot Antenna Trajectory (aligned to mic clock)")
+    ax2.legend(loc="upper right", fontsize=9)
+    ax2.grid(True, alpha=0.3)
+
+    # Zoom to active region
+    active_start = robot_offset - 0.5
+    active_end = robot_offset + max(COLLISION_TIMES) + 2.0
+    ax1.set_xlim(active_start, active_end)
+
+    fig.tight_layout()
+    fig.savefig(str(output_path), dpi=150)
+    plt.close(fig)
+    print(f"  Plot saved to {output_path}")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Beep + collision sync test")
+    parser.add_argument("--host", default="reachy-mini.local")
+    args = parser.parse_args()
+
+    print(f"\n{'='*60}")
+    print("Beep + Collision Sync Test")
+    print(f"{'='*60}")
+    print(f"  Beep times:      {BEEP_TIMES}")
+    print(f"  Collision times:  {COLLISION_TIMES}")
+    print(f"  Expected interval: {BEEP_COLLISION_OFFSET:.1f}s (beep → collision)")
+    gaps = [BEEP_TIMES[i+1] - BEEP_TIMES[i] for i in range(len(BEEP_TIMES)-1)]
+    print(f"  Gaps between pairs: {[f'{g:.1f}s' for g in gaps]}\n")
+
+    # Step 1: Stop running apps
+    print("[1/5] Stopping any running app...")
+    subprocess.run(
+        ["ssh", "-o", "ConnectTimeout=5", f"{ROBOT_USER}@{args.host}",
+         "curl -sf -X POST http://127.0.0.1:8000/api/apps/stop-current-app >/dev/null 2>&1 || true"],
+        capture_output=True, timeout=10,
+    )
+    time.sleep(1)
+
+    # Step 2: Start mic recording
+    print(f"[2/5] Starting mic recording ({MIC_DURATION}s)...")
+    mic_start = time.monotonic()
+    mic_data = sd.rec(
+        int(MIC_DURATION * LAPTOP_SR),
+        samplerate=LAPTOP_SR, channels=1, dtype="float32",
+    )
+
+    # Step 3: Start robot
+    time.sleep(0.3)
+    print("[3/5] Starting robot (beeps + collisions)...")
+    proc = start_robot(args.host)
+
+    # Read stdout, capture MARK_START
+    mark_start = None
+    print("\n--- Robot output ---")
+    for line in iter(proc.stdout.readline, ""):
+        line = line.rstrip()
+        if not line:
+            continue
+        laptop_time = time.monotonic()
+        print(f"  {line}")
+        if "MARK_START" in line:
+            mark_start = laptop_time
+    proc.wait()
+    print("--- End robot output ---")
+
+    sd.wait()
+    captured = mic_data.flatten()
+    print(f"\n  Mic recording done")
+
+    if mark_start is None:
+        print("\nFAILED: Never received MARK_START")
+        return 1
+
+    robot_offset = mark_start - mic_start
+    print(f"  MARK_START at mic_t={robot_offset:.3f}s")
+
+    # Save mic audio
+    mic_path = Path("tests/beep_collision_mic.wav")
+    sf.write(str(mic_path), captured, LAPTOP_SR)
+    print(f"  Saved mic to {mic_path}")
+
+    # Step 4: Fetch robot data
+    print("\n[4/5] Fetching robot data...")
+    local_results = Path("tests/beep_collision_positions.json")
+    scp_from_robot(REMOTE_RESULTS, local_results, args.host)
+    with open(local_results) as f:
+        robot_data = json.load(f)
+
+    # Step 5: Analyze
+    print("\n[5/5] Analyzing...")
+
+    # Detect beeps (tonal, bandpass around 2kHz)
+    detected_beeps = detect_beep_onsets(
+        captured, LAPTOP_SR, freq=BEEP_FREQ, bandwidth=150.0, threshold_db=-12.0,
+        min_separation=1.0,  # beeps are ≥1.3s apart
+    )
+    print(f"  Detected {len(detected_beeps)} beeps at: "
+          f"{[f'{t:.3f}' for t in detected_beeps]}")
+
+    # Detect collisions (impulsive, highpass >2kHz)
+    detected_collisions = detect_transient_onsets(
+        captured, LAPTOP_SR, highpass_freq=3000.0,
+    )
+    print(f"  Detected {len(detected_collisions)} collisions at: "
+          f"{[f'{t:.3f}' for t in detected_collisions]}")
+
+    # Match beep-collision pairs
+    # For each detected beep, find the nearest collision ~1s later
+    print(f"\n{'='*60}")
+    print("Beep → Collision Interval Analysis")
+    print(f"  (Expected interval: {BEEP_COLLISION_OFFSET*1000:.0f}ms)")
+    print(f"{'='*60}")
+
+    pairs = []
+    for i, bt in enumerate(detected_beeps):
+        # Look for a collision between 0.5s and 2.0s after the beep
+        candidates = [ct for ct in detected_collisions if 0.5 < (ct - bt) < 2.0]
+        if not candidates:
+            print(f"  Beep {i+1} at {bt:.3f}s: NO COLLISION FOUND in [+0.5, +2.0]s window")
+            continue
+
+        nearest = min(candidates, key=lambda ct: abs((ct - bt) - BEEP_COLLISION_OFFSET))
+        interval_ms = (nearest - bt) * 1000
+        error_ms = interval_ms - BEEP_COLLISION_OFFSET * 1000
+        pairs.append({
+            "beep_mic_t": bt,
+            "collision_mic_t": nearest,
+            "interval_ms": interval_ms,
+            "error_ms": error_ms,
+        })
+        print(f"  Pair {len(pairs)}: beep {bt:.3f}s → collision {nearest:.3f}s = "
+              f"{interval_ms:.0f}ms (error {error_ms:+.0f}ms)")
+
+    if pairs:
+        errors = [p["error_ms"] for p in pairs]
+        intervals = [p["interval_ms"] for p in pairs]
+        print(f"\n  Pairs matched: {len(pairs)}/{len(BEEP_TIMES)}")
+        print(f"  Mean interval: {np.mean(intervals):.0f}ms (expected {BEEP_COLLISION_OFFSET*1000:.0f}ms)")
+        print(f"  Mean error:    {np.mean(errors):+.0f}ms")
+        print(f"  Std error:     {np.std(errors):.0f}ms")
+        print(f"  Min/Max error: {min(errors):+.0f}ms / {max(errors):+.0f}ms")
+    else:
+        print(f"\n  No pairs matched!")
+
+    # Generate plot
+    plot_path = Path("tests/beep_collision_sync_plot.png")
+    plot_combined(
+        captured, LAPTOP_SR, mic_start, mark_start,
+        robot_data, detected_beeps, detected_collisions, pairs, plot_path,
+    )
+
+    success = len(pairs) >= len(BEEP_TIMES) - 1
+    print(f"\n{'='*60}")
+    if success:
+        print("RESULT: PASS — Beep-collision pairs detected and measured")
+    else:
+        print("RESULT: FAIL — Could not reliably detect pairs")
+    print(f"{'='*60}\n")
+
+    return 0 if success else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/test_collision_mic.py

@@ -0,0 +1,399 @@
+#!/usr/bin/env python3
+"""Measure laptop-to-collision delay using antenna collisions + laptop mic.
+
+Combines the collision test (robot-side position recording) with laptop mic
+recording to measure the full end-to-end delay from the laptop issuing a
+command to the collision sound being captured.
+
+Delay chain measured:
+  laptop SSH command → robot receives → daemon → motor → physical collision
+  → sound through air → laptop mic → detected
+
+Clock sync: Robot prints "MARK_START" to stdout. The laptop notes the time
+it receives this line. The robot's t=0 maps to that laptop timestamp (with
+~few ms SSH stdout latency).
+
+Usage:
+    python tests/test_collision_mic.py [--host reachy-mini.local]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+import numpy as np
+import sounddevice as sd
+import soundfile as sf
+
+sys.path.insert(0, str(Path(__file__).parent))
+from audio_analysis import detect_transient_onsets
+
+# Collision parameters (same as test_antenna_collision.py)
+RIGHT_REST = -0.68
+LEFT_REST = 0.0
+LEFT_COLLISION = 0.70
+HOLD_DURATION = 0.2
+COLLISION_TIMES = [1.0, 2.3, 4.0, 6.3, 9.4]
+
+ROBOT_USER = "pollen"
+ROBOT_PYTHON = "/venvs/apps_venv/bin/python"
+REMOTE_RESULTS = "/tmp/collision_positions.json"
+LAPTOP_SR = 48000
+MIC_DURATION = 30.0  # seconds — covers ~8s SSH startup + 10.5s sequence + buffer
+
+# Robot script: same as test_antenna_collision.py
+ROBOT_COLLISION_SCRIPT = """\
+import numpy as np
+import os, sys, time, json
+
+collision_times = json.loads(sys.argv[1])
+right_rest = float(sys.argv[2])
+left_rest = float(sys.argv[3])
+left_collision = float(sys.argv[4])
+hold_duration = float(sys.argv[5])
+results_path = sys.argv[6]
+
+print(f"robot: connecting to ReachyMini", flush=True)
+from reachy_mini import ReachyMini
+from reachy_mini.utils import create_head_pose
+r = ReachyMini(media_backend="no_media")
+
+r.goto_target(create_head_pose(), antennas=[left_rest, right_rest], duration=1.0)
+time.sleep(1.5)
+
+print(f"robot: rest position — left={left_rest}, right={right_rest}", flush=True)
+print(f"robot: will collide at times: {collision_times}", flush=True)
+
+DT = 0.02
+total_duration = max(collision_times) + hold_duration + 1.0
+n_steps = int(total_duration / DT)
+
+left_targets = np.full(n_steps, left_rest, dtype=np.float64)
+for ct in collision_times:
+    start_step = int(ct / DT)
+    end_step = int((ct + hold_duration) / DT)
+    end_step = min(end_step, n_steps)
+    left_targets[start_step:end_step] = left_collision
+
+timestamps = []
+left_present = []
+right_present = []
+left_target_log = []
+
+print("robot: MARK_START", flush=True)
+t0 = time.monotonic()
+
+for i in range(n_steps):
+    left = float(left_targets[i])
+    r.set_target(
+        head=np.eye(4),
+        body_yaw=0.0,
+        antennas=np.array([left, right_rest]),
+    )
+
+    pos = r.get_present_antenna_joint_positions()
+    elapsed = time.monotonic() - t0
+    timestamps.append(elapsed)
+    left_present.append(pos[0])
+    right_present.append(pos[1])
+    left_target_log.append(left)
+
+    target_time = (i + 1) * DT
+    now = time.monotonic() - t0
+    if target_time > now:
+        time.sleep(target_time - now)
+
+elapsed = time.monotonic() - t0
+print(f"robot: finished {n_steps} steps in {elapsed:.3f}s", flush=True)
+
+results = {
+    "collision_times": collision_times,
+    "left_collision_target": left_collision,
+    "right_rest": right_rest,
+    "hold_duration": hold_duration,
+    "timestamps": timestamps,
+    "left_present": left_present,
+    "right_present": right_present,
+    "left_target": left_target_log,
+}
+with open(results_path, "w") as f:
+    json.dump(results, f)
+print(f"robot: saved {len(timestamps)} samples to {results_path}", flush=True)
+
+r.goto_target(create_head_pose(), antennas=[left_rest, right_rest], duration=1.0)
+time.sleep(1.5)
+print("robot: done", flush=True)
+os._exit(0)
+"""
+
+
+def scp_to_robot(local_path: Path, remote_path: str, host: str) -> None:
+    target = f"{ROBOT_USER}@{host}:{remote_path}"
+    result = subprocess.run(
+        ["scp", "-o", "ConnectTimeout=5", str(local_path), target],
+        capture_output=True, text=True, timeout=15,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"SCP failed: {result.stderr}")
+    print(f"  Copied to {target}")
+
+
+def scp_from_robot(remote_path: str, local_path: Path, host: str) -> None:
+    source = f"{ROBOT_USER}@{host}:{remote_path}"
+    result = subprocess.run(
+        ["scp", "-o", "ConnectTimeout=5", source, str(local_path)],
+        capture_output=True, text=True, timeout=15,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"SCP failed: {result.stderr}")
+    print(f"  Copied from {source}")
+
+
+def start_robot(host: str) -> subprocess.Popen:
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+        f.write(ROBOT_COLLISION_SCRIPT)
+        local_script = Path(f.name)
+
+    remote_script = "/tmp/collision_mic_test.py"
+    try:
+        scp_to_robot(local_script, remote_script, host)
+    finally:
+        local_script.unlink()
+
+    args_str = (
+        f"{ROBOT_PYTHON} {remote_script} "
+        f"'{json.dumps(COLLISION_TIMES)}' "
+        f"{RIGHT_REST} {LEFT_REST} {LEFT_COLLISION} {HOLD_DURATION} "
+        f"{REMOTE_RESULTS}"
+    )
+    proc = subprocess.Popen(
+        ["ssh", "-o", "ConnectTimeout=5", f"{ROBOT_USER}@{host}", args_str],
+        stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
+    )
+    return proc
+
+
+def plot_combined(
+    mic_audio: np.ndarray,
+    mic_sr: int,
+    mic_start: float,
+    mark_start: float,
+    robot_data: dict,
+    detected_mic_times: list[float],
+    output_path: Path,
+) -> None:
+    """Plot mic waveform + robot trajectory on aligned time axes."""
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    # Time axis for mic (in "mic seconds since mic_start")
+    mic_t = np.arange(len(mic_audio)) / mic_sr
+
+    # Offset to align robot clock with mic clock:
+    # robot t=0 happened at laptop time mark_start
+    # mic t=0 happened at laptop time mic_start
+    # So robot t=X is at mic_t = (mark_start - mic_start) + X
+    robot_offset = mark_start - mic_start
+
+    robot_ts = np.array(robot_data["timestamps"])
+    left_pos = np.array(robot_data["left_present"])
+    right_pos = np.array(robot_data["right_present"])
+    left_tgt = np.array(robot_data["left_target"])
+
+    fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(16, 10), sharex=True)
+
+    # --- Top: Mic waveform ---
+    ax1.plot(mic_t, mic_audio, "k-", linewidth=0.3, alpha=0.6)
+    ax1.set_ylabel("Mic amplitude")
+    ax1.set_title("Laptop Mic Recording + Detected Collision Transients")
+    ax1.grid(True, alpha=0.3)
+
+    # Expected collision times in mic coordinates
+    for i, ct in enumerate(COLLISION_TIMES):
+        mic_expected = robot_offset + ct
+        label = "Expected (cmd time)" if i == 0 else None
+        ax1.axvline(mic_expected, color="green", linestyle="--", linewidth=1.2, alpha=0.7, label=label)
+
+    # Detected transients
+    for i, dt in enumerate(detected_mic_times):
+        label = "Detected transient" if i == 0 else None
+        ax1.axvline(dt, color="red", linestyle="-", linewidth=1.2, alpha=0.7, label=label)
+
+    ax1.legend(loc="upper right", fontsize=9)
+
+    # --- Bottom: Robot trajectory ---
+    # Plot in mic time coordinates
+    ax2.plot(robot_ts + robot_offset, left_pos, "b-", linewidth=1.5, label="Left antenna (present)")
+    ax2.plot(robot_ts + robot_offset, right_pos, "r-", linewidth=1.5, label="Right antenna (present)")
+    ax2.plot(robot_ts + robot_offset, left_tgt, "b--", linewidth=0.8, alpha=0.4, label="Left antenna (target)")
+
+    for i, ct in enumerate(COLLISION_TIMES):
+        mic_expected = robot_offset + ct
+        label = "Expected (cmd time)" if i == 0 else None
+        ax2.axvline(mic_expected, color="green", linestyle="--", linewidth=1.2, alpha=0.7, label=label)
+
+    for i, dt in enumerate(detected_mic_times):
+        label = "Detected transient" if i == 0 else None
+        ax2.axvline(dt, color="red", linestyle="-", linewidth=1.2, alpha=0.7, label=label)
+
+    ax2.set_xlabel("Time since mic start (s)")
+    ax2.set_ylabel("Position (rad)")
+    ax2.set_title("Robot Antenna Trajectory (aligned to mic clock)")
+    ax2.legend(loc="upper right", fontsize=9)
+    ax2.grid(True, alpha=0.3)
+
+    # Zoom to active region
+    active_start = robot_offset - 0.5
+    active_end = robot_offset + max(COLLISION_TIMES) + 2.0
+    ax1.set_xlim(active_start, active_end)
+
+    fig.tight_layout()
+    fig.savefig(str(output_path), dpi=150)
+    plt.close(fig)
+    print(f"  Plot saved to {output_path}")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Collision + mic delay measurement")
+    parser.add_argument("--host", default="reachy-mini.local")
+    args = parser.parse_args()
+
+    print(f"\n{'='*60}")
+    print("Collision + Mic Delay Measurement")
+    print(f"{'='*60}")
+    print(f"  Collision times: {COLLISION_TIMES}")
+    print(f"  Mic duration: {MIC_DURATION}s at {LAPTOP_SR}Hz\n")
+
+    # Step 1: Stop running apps
+    print("[1/5] Stopping any running app...")
+    subprocess.run(
+        ["ssh", "-o", "ConnectTimeout=5", f"{ROBOT_USER}@{args.host}",
+         "curl -sf -X POST http://127.0.0.1:8000/api/apps/stop-current-app >/dev/null 2>&1 || true"],
+        capture_output=True, timeout=10,
+    )
+    time.sleep(1)
+
+    # Step 2: Start mic recording
+    print(f"[2/5] Starting mic recording ({MIC_DURATION}s)...")
+    mic_start = time.monotonic()
+    mic_data = sd.rec(
+        int(MIC_DURATION * LAPTOP_SR),
+        samplerate=LAPTOP_SR, channels=1, dtype="float32",
+    )
+
+    # Step 3: Start robot collision sequence
+    time.sleep(0.3)  # let mic stabilize
+    print("[3/5] Starting collision sequence on robot...")
+    proc = start_robot(args.host)
+
+    # Read stdout, capture MARK_START timestamp
+    mark_start = None
+    print("\n--- Robot output ---")
+    for line in iter(proc.stdout.readline, ""):
+        line = line.rstrip()
+        if not line:
+            continue
+        laptop_time = time.monotonic()
+        print(f"  {line}")
+        if "MARK_START" in line:
+            mark_start = laptop_time
+    proc.wait()
+    print("--- End robot output ---")
+
+    # Wait for mic recording to finish
+    sd.wait()
+    captured = mic_data.flatten()
+    mic_end = time.monotonic()
+    print(f"\n  Mic recording done ({mic_end - mic_start:.1f}s)")
+
+    if mark_start is None:
+        print("\nFAILED: Never received MARK_START from robot")
+        return 1
+
+    robot_offset = mark_start - mic_start
+    print(f"  MARK_START received at mic_t={robot_offset:.3f}s")
+
+    # Save mic audio
+    mic_path = Path("tests/collision_mic.wav")
+    sf.write(str(mic_path), captured, LAPTOP_SR)
+    print(f"  Saved mic audio to {mic_path}")
+
+    # Step 4: Fetch robot position data
+    print("\n[4/5] Fetching position data from robot...")
+    local_results = Path("tests/collision_positions.json")
+    scp_from_robot(REMOTE_RESULTS, local_results, args.host)
+
+    with open(local_results) as f:
+        robot_data = json.load(f)
+
+    # Step 5: Analyze
+    print("\n[5/5] Analyzing...")
+
+    # Detect transient sounds in mic recording
+    detected_mic = detect_transient_onsets(captured, LAPTOP_SR, highpass_freq=2000.0)
+    print(f"  Detected {len(detected_mic)} transients in mic at: "
+          f"{[f'{t:.3f}' for t in detected_mic]}")
+
+    # Expected collision times in mic coordinates
+    expected_mic = [robot_offset + ct for ct in COLLISION_TIMES]
+    print(f"  Expected collision sounds at mic_t: "
+          f"{[f'{t:.3f}' for t in expected_mic]}")
+
+    # Match detected transients to expected collision times
+    print(f"\n{'='*60}")
+    print("Delay Analysis: Command → Audible Collision")
+    print(f"{'='*60}")
+
+    matched = 0
+    delays = []
+    for i, (et_mic, ct_robot) in enumerate(zip(expected_mic, COLLISION_TIMES)):
+        if not detected_mic:
+            print(f"  Collision {i+1} (cmd t={ct_robot:.1f}s): NO TRANSIENT DETECTED")
+            continue
+
+        nearest = min(detected_mic, key=lambda d: abs(d - et_mic))
+        delay_ms = (nearest - et_mic) * 1000
+        ok = abs(nearest - et_mic) < 0.5  # 500ms tolerance
+        if ok:
+            matched += 1
+            delays.append(delay_ms)
+        status = "OK" if ok else "MISS"
+        print(f"  Collision {i+1} (cmd t={ct_robot:.1f}s): "
+              f"expected mic_t={et_mic:.3f}s, detected={nearest:.3f}s, "
+              f"delay={delay_ms:+.0f}ms [{status}]")
+
+    if delays:
+        print(f"\n  Matched: {matched}/{len(COLLISION_TIMES)}")
+        print(f"  Mean delay: {np.mean(delays):+.0f}ms")
+        print(f"  Std delay:  {np.std(delays):.0f}ms")
+        print(f"  Min/Max:    {min(delays):+.0f}ms / {max(delays):+.0f}ms")
+        print(f"\n  (Positive = sound arrived AFTER command)")
+    else:
+        print(f"\n  No delays measured — no transients matched")
+
+    # Generate combined plot
+    plot_path = Path("tests/collision_mic_plot.png")
+    plot_combined(
+        captured, LAPTOP_SR, mic_start, mark_start,
+        robot_data, detected_mic, plot_path,
+    )
+
+    success = matched >= len(COLLISION_TIMES) - 1
+    print(f"\n{'='*60}")
+    if success:
+        print("RESULT: PASS — Collision sounds detected and matched")
+    else:
+        print("RESULT: FAIL — Could not reliably detect collision sounds")
+    print(f"{'='*60}\n")
+
+    return 0 if success else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/test_hardware.py

@@ -566,6 +566,18 @@ def _observe_playback(base_url, hw_reachy, duration):
     return observed_times, observed_frames
 
 
+def _write_silent_wav(path: Path, duration: float, sample_rate: int = 48000) -> None:
+    """Write a silent WAV file of the given duration."""
+    import struct
+
+    n_frames = int(duration * sample_rate)
+    with wave.open(str(path), "wb") as wf:
+        wf.setnchannels(1)
+        wf.setsampwidth(2)
+        wf.setframerate(sample_rate)
+        wf.writeframes(struct.pack(f"<{n_frames}h", *([0] * n_frames)))
+
+
 class TestMotionAccuracy:
     """Play back synthetic reference recordings and compare observed poses.
 
@@ -768,6 +780,149 @@ class TestMotionAccuracy:
         httpx.delete(f"{base_url}/api/moves/{move_id}", timeout=5)
 
 
+class TestAudioMotionSync:
+    """Verify that audio and motion play back together correctly.
+
+    Creates a synthetic move with a matching WAV file, plays it back,
+    measures wall-clock duration and observed joint positions, and
+    verifies both timing and trajectory accuracy.
+    """
+
+    def test_audio_motion_sync_playback(
+        self, base_url: str, hw_marionette, hw_reachy,
+    ):
+        """Inject synthetic move + WAV, play back, verify timing and accuracy."""
+        import httpx
+        import numpy as np
+        from pose_utils import compare_trajectories
+
+        duration = 3.0
+        _ensure_idle(base_url)
+
+        # Step 1: Create synthetic move — gentle yaw oscillation
+        move_id = _create_synthetic_move(
+            hw_marionette,
+            label="synth-audio-sync",
+            duration=duration,
+            trajectory_fn=lambda t: (0.0, 0.0, 0.3 * np.sin(2 * np.pi * 0.5 * t)),
+        )
+
+        # Step 2: Write matching silent WAV alongside the JSON
+        wav_path = hw_marionette._dataset_dir / f"{move_id}.wav"
+        _write_silent_wav(wav_path, duration=duration, sample_rate=48000)
+
+        # Step 3: Refresh and verify has_audio
+        hw_marionette._refresh_recordings()
+        state = httpx.get(f"{base_url}/api/state", timeout=5).json()
+        move = next((m for m in state["moves"] if m["id"] == move_id), None)
+        assert move is not None, f"Move {move_id} not in state after refresh"
+        assert move["has_audio"] is True, "Move should have audio (WAV exists)"
+
+        # Step 4: Load reference for comparison
+        ref_data = json.loads(
+            (hw_marionette._dataset_dir / f"{move_id}.json").read_text()
+        )
+        ref_times = ref_data["time"]
+        ref_frames = ref_data["set_target_data"]
+
+        # Step 5: Play back and measure wall-clock + poses
+        t0 = time.time()
+        resp = httpx.post(
+            f"{base_url}/api/play",
+            json={"move_id": move_id},
+            timeout=5,
+        )
+        assert resp.status_code == 200
+
+        observed_times, observed_frames = _observe_playback(
+            base_url, hw_reachy, duration,
+        )
+        _wait_for_mode(base_url, "idle", timeout=duration + 15)
+        wall_clock = time.time() - t0
+
+        # Step 6: Timing assertions — audio shouldn't cut short or hang
+        assert wall_clock > duration * 0.8, (
+            f"Playback too fast: {wall_clock:.2f}s — audio likely cut short "
+            f"(expected ≥{duration * 0.8:.1f}s)"
+        )
+        assert wall_clock < duration + 10, (
+            f"Playback too slow: {wall_clock:.2f}s — possibly stuck "
+            f"(expected <{duration + 10:.1f}s)"
+        )
+
+        # Step 7: Verify enough frames observed (robot actually moved)
+        assert len(observed_frames) > 10, (
+            f"Too few observed frames: {len(observed_frames)} — "
+            f"robot may not have moved"
+        )
+
+        # Step 8: Compare trajectories
+        metrics = compare_trajectories(
+            ref_times, ref_frames, observed_times, observed_frames,
+        )
+        print(f"\nAudio-motion sync ({len(observed_frames)} frames, "
+              f"wall={wall_clock:.2f}s):")
+        print(metrics.summary())
+
+        assert metrics.magic_mean < 50, (
+            f"Mean magic distance too high: {metrics.magic_mean:.1f}\n"
+            f"{metrics.summary()}"
+        )
+
+        # Cleanup
+        httpx.delete(f"{base_url}/api/moves/{move_id}", timeout=5)
+
+    def test_audio_does_not_truncate_motion(
+        self, base_url: str, hw_marionette,
+    ):
+        """Verify that audio playback doesn't end before motion completes.
+
+        Creates a 5s move + 5s WAV, plays back, measures wall-clock to
+        ensure the full duration plays out.
+        """
+        import httpx
+        import numpy as np
+
+        duration = 5.0
+        _ensure_idle(base_url)
+
+        move_id = _create_synthetic_move(
+            hw_marionette,
+            label="synth-audio-notrim",
+            duration=duration,
+            trajectory_fn=lambda t: (0.0, 0.0, 0.2 * np.sin(2 * np.pi * 0.3 * t)),
+        )
+
+        wav_path = hw_marionette._dataset_dir / f"{move_id}.wav"
+        _write_silent_wav(wav_path, duration=duration, sample_rate=48000)
+        hw_marionette._refresh_recordings()
+
+        # Play and measure
+        _ensure_idle(base_url)
+        t0 = time.time()
+        resp = httpx.post(
+            f"{base_url}/api/play",
+            json={"move_id": move_id},
+            timeout=5,
+        )
+        assert resp.status_code == 200
+        _wait_for_mode(base_url, "idle", timeout=duration + 20)
+        wall_clock = time.time() - t0
+
+        print(f"\nAudio-motion no-trim: wall={wall_clock:.2f}s for {duration}s move+audio")
+
+        # Playback should last at least 80% of the duration
+        assert wall_clock > duration * 0.8, (
+            f"Playback cut short: {wall_clock:.2f}s (expected ≥{duration * 0.8:.1f}s)"
+        )
+        assert wall_clock < duration + 15, (
+            f"Playback hung: {wall_clock:.2f}s (expected <{duration + 15:.1f}s)"
+        )
+
+        # Cleanup
+        httpx.delete(f"{base_url}/api/moves/{move_id}", timeout=5)
+
+
 class TestMultiDuration:
     """Test recording and playback across different durations.
 
@@ -1478,6 +1633,384 @@ class TestPlaybackWithCorruptFile:
         hw_marionette._refresh_recordings()
 
 
+class TestHardwarePlaybackWithAudio:
+    """Playback with uploaded audio — validates Fix 1 (audio lifecycle).
+
+    These tests upload a WAV file, record motion with it, then play back
+    to verify that both audio and motion complete fully (not cut short).
+    """
+
+    def test_playback_with_uploaded_audio_completes(self, base_url: str, hw_marionette):
+        """Upload WAV, record with it, play back — verify full completion."""
+        import httpx
+        import io
+        import struct
+        import wave as wave_mod
+
+        _ensure_idle(base_url)
+
+        # Create a 2s WAV file in memory
+        sr, dur = 44100, 2.0
+        n_frames = int(dur * sr)
+        buf = io.BytesIO()
+        with wave_mod.open(buf, "wb") as wf:
+            wf.setnchannels(1)
+            wf.setsampwidth(2)
+            wf.setframerate(sr)
+            wf.writeframes(struct.pack(f"<{n_frames}h", *([0] * n_frames)))
+        wav_bytes = buf.getvalue()
+
+        # Upload the WAV
+        upload_resp = httpx.post(
+            f"{base_url}/api/upload-audio",
+            files={"file": ("test-play.wav", wav_bytes, "audio/wav")},
+            timeout=10,
+        )
+        assert upload_resp.status_code == 200
+        upload_id = upload_resp.json()["upload_id"]
+
+        # Record motion with uploaded audio
+        _ensure_idle(base_url)
+        resp = httpx.post(
+            f"{base_url}/api/record",
+            json={
+                "duration": 2.0,
+                "record_audio": False,
+                "record_motion": True,
+                "uploaded_audio_id": upload_id,
+                "label": "hw-upload-play",
+            },
+            timeout=5,
+        )
+        assert resp.status_code == 200
+        move_id = resp.json()["move_id"]
+        _wait_for_mode(base_url, "idle", timeout=COUNTDOWN_SECONDS + 2 + 15)
+
+        # Verify recording has audio
+        state = httpx.get(f"{base_url}/api/state", timeout=5).json()
+        move = next((m for m in state["moves"] if m["id"] == move_id), None)
+        assert move is not None
+        assert move["has_audio"] is True
+
+        # Play it back and measure duration
+        _ensure_idle(base_url)
+        t0 = time.time()
+        resp = httpx.post(
+            f"{base_url}/api/play",
+            json={"move_id": move_id},
+            timeout=5,
+        )
+        assert resp.status_code == 200
+        _wait_for_mode(base_url, "idle", timeout=move["duration"] + 20)
+        playback_time = time.time() - t0
+
+        # Playback should last approximately the move duration (not 1s!)
+        assert playback_time > 1.5, (
+            f"Playback too short: {playback_time:.2f}s — audio/motion likely cut short"
+        )
+        print(f"\nPlayback with uploaded audio: {playback_time:.2f}s")
+
+        # Cleanup
+        httpx.delete(f"{base_url}/api/moves/{move_id}", timeout=5)
+
+    def test_multiple_playback_cycles_with_audio(self, base_url: str, hw_marionette):
+        """Play the same move 3 times — verify no resource leaks."""
+        import httpx
+
+        _ensure_idle(base_url)
+        state = httpx.get(f"{base_url}/api/state", timeout=5).json()
+        move = next((m for m in state["moves"] if m["has_audio"]), None)
+        if move is None:
+            pytest.skip("No audio move available for cycle test")
+
+        for i in range(3):
+            _ensure_idle(base_url)
+            t0 = time.time()
+            resp = httpx.post(
+                f"{base_url}/api/play",
+                json={"move_id": move["id"]},
+                timeout=5,
+            )
+            assert resp.status_code == 200, f"Cycle {i}: play failed"
+            _wait_for_mode(base_url, "idle", timeout=move["duration"] + 20)
+            elapsed = time.time() - t0
+            print(f"  Cycle {i+1}/3: {elapsed:.2f}s")
+
+            state = httpx.get(f"{base_url}/api/state", timeout=5).json()
+            assert state["mode"] == "idle", f"Cycle {i}: not idle after playback"
+
+
+class TestHardwareAudioOnlyRecording:
+    """Audio-only recording (mic, no motion) on real hardware."""
+
+    def test_audio_only_recording_and_playback(self, base_url: str, hw_marionette):
+        """Record audio-only, verify WAV created, play it back."""
+        import httpx
+
+        _ensure_idle(base_url)
+        resp = httpx.post(
+            f"{base_url}/api/record",
+            json={
+                "duration": 2.0,
+                "record_audio": True,
+                "record_motion": False,
+                "label": "hw-audio-only",
+            },
+            timeout=5,
+        )
+        assert resp.status_code == 200
+        move_id = resp.json()["move_id"]
+
+        try:
+            _wait_for_mode(base_url, "idle", timeout=COUNTDOWN_SECONDS + 2 + 20)
+        except TimeoutError:
+            global _server_stuck
+            _server_stuck = True
+            pytest.skip("Audio-only recording timed out")
+
+        # Verify it's marked as audio_only
+        state = httpx.get(f"{base_url}/api/state", timeout=5).json()
+        move = next((m for m in state["moves"] if m["id"] == move_id), None)
+        assert move is not None
+        assert move["audio_only"] is True
+
+        # Play it back (audio-only playback)
+        _ensure_idle(base_url)
+        resp = httpx.post(
+            f"{base_url}/api/play",
+            json={"move_id": move_id},
+            timeout=5,
+        )
+        assert resp.status_code == 200
+        _wait_for_mode(base_url, "idle", timeout=15)
+
+        state = httpx.get(f"{base_url}/api/state", timeout=5).json()
+        assert state["mode"] == "idle"
+
+        # Cleanup
+        httpx.delete(f"{base_url}/api/moves/{move_id}", timeout=5)
+
+    def test_audio_only_appears_in_robot_audio_list(self, base_url: str, hw_marionette):
+        """After audio-only recording, WAV should appear in robot-audio list."""
+        import httpx
+
+        _ensure_idle(base_url)
+        resp = httpx.post(
+            f"{base_url}/api/record",
+            json={
+                "duration": 1.5,
+                "record_audio": True,
+                "record_motion": False,
+                "label": "hw-ao-list",
+            },
+            timeout=5,
+        )
+        assert resp.status_code == 200
+        move_id = resp.json()["move_id"]
+
+        try:
+            _wait_for_mode(base_url, "idle", timeout=COUNTDOWN_SECONDS + 1.5 + 20)
+        except TimeoutError:
+            global _server_stuck
+            _server_stuck = True
+            pytest.skip("Audio-only recording timed out")
+
+        # Check robot-audio endpoint
+        resp = httpx.get(f"{base_url}/api/robot-audio", timeout=5)
+        assert resp.status_code == 200
+        names = [f["name"] for f in resp.json()["files"]]
+        assert move_id in names, (
+            f"Expected {move_id} in robot-audio list, got: {names}"
+        )
+
+        # Cleanup
+        httpx.delete(f"{base_url}/api/moves/{move_id}", timeout=5)
+
+
+class TestHardwareRobotFileSelection:
+    """Test the robot file selection workflow on real hardware."""
+
+    def test_robot_audio_list_populated(self, base_url: str):
+        """GET /api/robot-audio should return files after recordings exist."""
+        import httpx
+
+        _ensure_idle(base_url)
+        resp = httpx.get(f"{base_url}/api/robot-audio", timeout=5)
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "files" in data
+        # Files may or may not exist depending on test order
+        for f in data["files"]:
+            assert "name" in f
+            assert "path" in f
+
+    def test_select_robot_audio_sets_upload_id(self, base_url: str):
+        """POST /api/robot-audio/select with a valid file returns upload_id."""
+        import httpx
+
+        _ensure_idle(base_url)
+        # Get a file from the list
+        list_resp = httpx.get(f"{base_url}/api/robot-audio", timeout=5)
+        files = list_resp.json().get("files", [])
+        if not files:
+            pytest.skip("No robot audio files available")
+
+        resp = httpx.post(
+            f"{base_url}/api/robot-audio/select",
+            json={"path": files[0]["path"]},
+            timeout=5,
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "upload_id" in data
+        assert data["upload_id"]  # non-empty
+        assert "filename" in data
+
+    def test_select_robot_audio_and_record(self, base_url: str):
+        """Select a robot audio file, then record motion with it."""
+        import httpx
+
+        _ensure_idle(base_url)
+        list_resp = httpx.get(f"{base_url}/api/robot-audio", timeout=5)
+        files = list_resp.json().get("files", [])
+        if not files:
+            pytest.skip("No robot audio files available")
+
+        # Select the first file
+        select_resp = httpx.post(
+            f"{base_url}/api/robot-audio/select",
+            json={"path": files[0]["path"]},
+            timeout=5,
+        )
+        assert select_resp.status_code == 200
+        upload_id = select_resp.json()["upload_id"]
+
+        # Record with the selected audio
+        resp = httpx.post(
+            f"{base_url}/api/record",
+            json={
+                "duration": 2.0,
+                "record_audio": False,
+                "record_motion": True,
+                "uploaded_audio_id": upload_id,
+                "label": "hw-robot-file",
+            },
+            timeout=5,
+        )
+        assert resp.status_code == 200
+        move_id = resp.json()["move_id"]
+
+        _wait_for_mode(base_url, "idle", timeout=COUNTDOWN_SECONDS + 2 + 15)
+
+        state = httpx.get(f"{base_url}/api/state", timeout=5).json()
+        move = next((m for m in state["moves"] if m["id"] == move_id), None)
+        assert move is not None
+        assert move["has_audio"] is True
+
+        # Cleanup
+        httpx.delete(f"{base_url}/api/moves/{move_id}", timeout=5)
+
+
+class TestHardwareStopResponsiveness:
+    """Verify stop commands respond quickly during all phases."""
+
+    def test_stop_recording_during_countdown(self, base_url: str):
+        """Stop during countdown — should return to idle within a few seconds."""
+        import httpx
+
+        _ensure_idle(base_url)
+        resp = httpx.post(
+            f"{base_url}/api/record",
+            json={"duration": 10.0, "record_audio": False, "label": "stop-countdown"},
+            timeout=5,
+        )
+        assert resp.status_code == 200
+
+        # Wait for countdown to start
+        time.sleep(0.3)
+        t0 = time.time()
+        resp = httpx.post(f"{base_url}/api/record/stop", timeout=5)
+        assert resp.status_code == 200
+
+        state = _wait_for_mode(base_url, "idle", timeout=5)
+        stop_time = time.time() - t0
+        assert state["mode"] == "idle"
+        print(f"\nStop during countdown: {stop_time:.2f}s")
+
+    def test_stop_recording_during_capture(self, base_url: str):
+        """Stop during active recording — should return to idle within 5s."""
+        import httpx
+
+        _ensure_idle(base_url)
+        resp = httpx.post(
+            f"{base_url}/api/record",
+            json={"duration": 10.0, "record_audio": False, "label": "stop-capture"},
+            timeout=5,
+        )
+        assert resp.status_code == 200
+
+        # Wait for recording phase
+        _wait_for_mode(base_url, "recording", timeout=COUNTDOWN_SECONDS + 5)
+        time.sleep(1.0)
+
+        t0 = time.time()
+        resp = httpx.post(f"{base_url}/api/record/stop", timeout=5)
+        assert resp.status_code == 200
+
+        state = _wait_for_mode(base_url, "idle", timeout=5)
+        stop_time = time.time() - t0
+        assert state["mode"] == "idle"
+        assert stop_time < 5.0, f"Stop took too long: {stop_time:.2f}s"
+        print(f"\nStop during capture: {stop_time:.2f}s")
+
+        # Cleanup
+        state = httpx.get(f"{base_url}/api/state", timeout=5).json()
+        for m in state["moves"]:
+            if "stop-capture" in m.get("label", ""):
+                httpx.delete(f"{base_url}/api/moves/{m['id']}", timeout=5)
+
+    def test_stop_playback_responds_quickly(self, base_url: str, hw_marionette):
+        """Stop playback mid-stream — should return to idle within 5s."""
+        import httpx
+
+        _ensure_idle(base_url)
+
+        # Record a 5s move
+        resp = httpx.post(
+            f"{base_url}/api/record",
+            json={"duration": 5.0, "record_audio": False, "label": "stop-play-resp"},
+            timeout=5,
+        )
+        assert resp.status_code == 200
+        move_id = resp.json()["move_id"]
+        _wait_for_mode(base_url, "idle", timeout=COUNTDOWN_SECONDS + 5 + 10)
+
+        # Play it
+        _ensure_idle(base_url)
+        resp = httpx.post(
+            f"{base_url}/api/play",
+            json={"move_id": move_id},
+            timeout=5,
+        )
+        assert resp.status_code == 200
+        _wait_for_mode(base_url, "playing", timeout=15)
+        time.sleep(1.0)
+
+        # Stop and measure
+        t0 = time.time()
+        resp = httpx.post(f"{base_url}/api/play/stop", timeout=5)
+        assert resp.status_code == 200
+
+        state = _wait_for_mode(base_url, "idle", timeout=10)
+        stop_time = time.time() - t0
+        assert state["mode"] == "idle"
+        assert stop_time < 5.0, f"Stop took too long: {stop_time:.2f}s"
+        print(f"\nStop during playback: {stop_time:.2f}s")
+
+        # Cleanup
+        httpx.delete(f"{base_url}/api/moves/{move_id}", timeout=5)
+
+
 class TestHardwareAudio:
     """Audio recording/playback tests — run last.
 
@@ -1582,3 +2115,105 @@ class TestHardwareAudio:
 
         state = httpx.get(f"{base_url}/api/state", timeout=5).json()
         assert state["mode"] == "idle"
+
+
+class TestAntennaCollisionSync:
+    """Test audio-motion sync using antenna collisions + laptop mic.
+
+    Generates a move where beeps are synchronized with antenna collisions.
+    Replays it on the robot, records via laptop mic, and measures the
+    temporal offset between beep onsets and collision transients.
+
+    Requires: laptop with microphone, sounddevice pip package.
+    """
+
+    def test_playback_sync_via_mic(self, base_url: str, hw_marionette, hw_reachy):
+        """Inject sync test move, play back, record mic, measure offsets."""
+        import httpx
+        import soundfile as sf
+        from audio_analysis import (
+            MicRecorder,
+            detect_beep_onsets,
+            detect_transient_onsets,
+            generate_collision_trajectory,
+            generate_sync_test_audio,
+            measure_sync_offsets,
+        )
+
+        _ensure_idle(base_url)
+
+        duration = 8.0
+        beep_freq = 1000.0
+
+        # 1. Generate sync test audio + collision trajectory
+        audio_data, beep_times = generate_sync_test_audio(
+            duration=duration, beep_freq=beep_freq,
+        )
+        timestamps, collision_frames = generate_collision_trajectory(
+            beep_times, duration=duration,
+        )
+
+        # 2. Write WAV + JSON to dataset dir
+        move_id = "antenna-sync-test"
+        wav_path = hw_marionette._dataset_dir / f"{move_id}.wav"
+        json_path = hw_marionette._dataset_dir / f"{move_id}.json"
+        sf.write(str(wav_path), audio_data, 48000)
+        json_path.write_text(json.dumps({
+            "description": "Antenna collision sync test",
+            "time": timestamps,
+            "set_target_data": collision_frames,
+        }), encoding="utf-8")
+        hw_marionette._refresh_recordings()
+
+        # 3. Start laptop mic recording
+        recorder = MicRecorder(sr=48000)
+        recorder.start()
+        # Brief delay to ensure mic is capturing
+        time.sleep(0.5)
+
+        try:
+            # 4. Trigger playback via API
+            resp = httpx.post(
+                f"{base_url}/api/play",
+                json={"move_id": move_id},
+                timeout=5,
+            )
+            assert resp.status_code == 200
+
+            # Wait for playback to finish
+            _wait_for_mode(base_url, "idle", timeout=duration + 20)
+            time.sleep(0.5)  # Capture tail end
+        finally:
+            captured = recorder.stop()
+
+        # 5. Analyze captured audio
+        print(f"\nCaptured {len(captured)} samples ({len(captured)/48000:.2f}s)")
+
+        beep_onsets = detect_beep_onsets(captured, 48000, freq=beep_freq)
+        collision_onsets = detect_transient_onsets(captured, 48000)
+
+        print(f"Detected {len(beep_onsets)} beeps: {[f'{t:.3f}s' for t in beep_onsets]}")
+        print(f"Detected {len(collision_onsets)} collisions: {[f'{t:.3f}s' for t in collision_onsets]}")
+
+        # 6. Measure sync quality
+        result = measure_sync_offsets(beep_onsets, collision_onsets)
+        print(f"Matched {result['n_matched']}/{result['n_beeps']} beeps")
+        for bt, ct, offset in result["pairs"]:
+            print(f"  beep@{bt:.3f}s -> collision@{ct:.3f}s = {offset:+.1f}ms")
+        print(f"Mean offset: {result['mean_offset_ms']:.1f}ms")
+        print(f"Max offset:  {result['max_offset_ms']:.1f}ms")
+        print(f"Std offset:  {result['std_offset_ms']:.1f}ms")
+
+        # Assertions — generous thresholds for first iteration
+        assert result["n_matched"] >= 3, (
+            f"Only matched {result['n_matched']}/{result['n_beeps']} beep-collision pairs"
+        )
+        assert abs(result["mean_offset_ms"]) < 300, (
+            f"Mean sync offset {result['mean_offset_ms']:.1f}ms exceeds 300ms"
+        )
+        assert result["max_offset_ms"] < 500, (
+            f"Max sync offset {result['max_offset_ms']:.1f}ms exceeds 500ms"
+        )
+
+        # Cleanup
+        httpx.delete(f"{base_url}/api/moves/{move_id}", timeout=5)

tests/test_marionette_sync.py

@@ -0,0 +1,614 @@
+#!/usr/bin/env python3
+"""End-to-end sync tests through the Marionette stack.
+
+Tests audio-motion synchronization by playing a synthetic move through
+Marionette's full playback pipeline (push_audio_sample + motion loop)
+and measuring beep-to-collision intervals with a laptop microphone.
+
+Requires:
+  - Marionette running on the robot (via deploy_wireless.sh or daemon)
+  - Laptop microphone connected and working
+  - Robot accessible at --host (default: reachy-mini.local)
+
+Usage:
+    python tests/test_marionette_sync.py [--host reachy-mini.local]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import numpy as np
+import requests
+import sounddevice as sd
+import soundfile as sf
+
+sys.path.insert(0, str(Path(__file__).parent))
+from audio_analysis import detect_beep_onsets, detect_transient_onsets
+
+# ── Timing (same as all previous sync tests) ──────────────────────────
+BEEP_TIMES = [1.0, 2.3, 4.0, 6.3, 9.4]
+BEEP_COLLISION_OFFSET = 1.0
+COLLISION_TIMES = [t + BEEP_COLLISION_OFFSET for t in BEEP_TIMES]
+
+# Audio
+BEEP_FREQ = 2000.0
+BEEP_DURATION = 0.2
+BEEP_AMPLITUDE = 0.9
+ROBOT_SR = 16000
+
+# Collision
+RIGHT_REST = -0.68
+LEFT_REST = 0.0
+LEFT_COLLISION = 0.70
+HOLD_DURATION = 0.2
+
+MOTION_SR = 100
+MOVE_ID = "sync-test-e2e"
+
+ROBOT_USER = "pollen"
+LAPTOP_SR = 48000
+MIC_DURATION = 35.0  # longer: Marionette has goto + playback
+MARIONETTE_PORT = 8042
+
+
+def get_marionette_url(host: str) -> str:
+    return f"http://{host}:{MARIONETTE_PORT}"
+
+
+def wait_for_mode(base_url: str, target: str, timeout: float = 30.0) -> dict:
+    """Poll GET /api/state until mode matches target."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            r = requests.get(f"{base_url}/api/state", timeout=3)
+            state = r.json()
+            if state.get("mode") == target:
+                return state
+        except Exception:
+            pass
+        time.sleep(0.3)
+    raise TimeoutError(f"Mode never reached '{target}' within {timeout}s")
+
+
+def ensure_idle(base_url: str) -> dict:
+    """Make sure Marionette is idle, stopping anything in progress."""
+    try:
+        state = requests.get(f"{base_url}/api/state", timeout=3).json()
+    except Exception as exc:
+        raise RuntimeError(f"Cannot reach Marionette at {base_url}: {exc}") from exc
+
+    mode = state.get("mode", "unknown")
+    if mode == "idle":
+        return state
+
+    # Try to stop whatever is running
+    if mode == "playing":
+        requests.post(f"{base_url}/api/play/stop", timeout=3)
+    elif mode in {"recording", "countdown", "preparing"}:
+        requests.post(f"{base_url}/api/record/stop", timeout=3)
+    return wait_for_mode(base_url, "idle", timeout=10)
+
+
+def generate_move_json() -> dict:
+    """Generate Marionette-format move data with collision trajectory."""
+    total_duration = max(COLLISION_TIMES) + HOLD_DURATION + 1.0
+    dt = 1.0 / MOTION_SR
+    n_frames = int(total_duration * MOTION_SR)
+
+    identity_head = np.eye(4).tolist()
+    left_targets = np.full(n_frames, LEFT_REST, dtype=np.float64)
+    for ct in COLLISION_TIMES:
+        start = int(ct * MOTION_SR)
+        end = min(int((ct + HOLD_DURATION) * MOTION_SR), n_frames)
+        left_targets[start:end] = LEFT_COLLISION
+
+    timestamps = []
+    frames = []
+    for i in range(n_frames):
+        t = round(i * dt, 4)
+        timestamps.append(t)
+        frames.append({
+            "head": identity_head,
+            "antennas": [float(left_targets[i]), RIGHT_REST],
+            "body_yaw": 0.0,
+            "check_collision": False,
+        })
+
+    return {
+        "description": "E2E sync test: beeps + antenna collisions",
+        "time": timestamps,
+        "set_target_data": frames,
+    }
+
+
+def generate_move_wav(path: Path) -> None:
+    """Generate WAV with beeps at known times."""
+    total_duration = max(COLLISION_TIMES) + HOLD_DURATION + 1.0
+    n_audio = int(total_duration * ROBOT_SR)
+    audio = np.zeros(n_audio, dtype=np.float32)
+    for bt in BEEP_TIMES:
+        start = int(bt * ROBOT_SR)
+        n_beep = int(BEEP_DURATION * ROBOT_SR)
+        if start + n_beep > n_audio:
+            continue
+        t_arr = np.arange(n_beep, dtype=np.float32) / ROBOT_SR
+        beep = BEEP_AMPLITUDE * np.sin(2 * np.pi * BEEP_FREQ * t_arr).astype(np.float32)
+        fade = int(0.005 * ROBOT_SR)
+        if fade > 0 and 2 * fade < n_beep:
+            beep[:fade] *= np.linspace(0, 1, fade, dtype=np.float32)
+            beep[-fade:] *= np.linspace(1, 0, fade, dtype=np.float32)
+        audio[start:start + n_beep] += beep
+    sf.write(str(path), audio, ROBOT_SR)
+
+
+def inject_move(host: str, base_url: str) -> None:
+    """Inject the synthetic move into the running Marionette's dataset."""
+    # Get the active dataset path from Marionette
+    state = requests.get(f"{base_url}/api/state", timeout=3).json()
+    dataset_path = state["config"]["active_dataset_path"]
+    active_id = state.get("datasets", {}).get("active_id")
+    print(f"  Active dataset path: {dataset_path}")
+
+    # Generate move files locally
+    import tempfile
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmpdir = Path(tmpdir)
+        json_path = tmpdir / f"{MOVE_ID}.json"
+        wav_path = tmpdir / f"{MOVE_ID}.wav"
+
+        move_data = generate_move_json()
+        json_path.write_text(json.dumps(move_data), encoding="utf-8")
+        generate_move_wav(wav_path)
+
+        total_duration = max(COLLISION_TIMES) + HOLD_DURATION + 1.0
+        print(f"  Generated move: {total_duration:.1f}s, {len(BEEP_TIMES)} beeps, {len(COLLISION_TIMES)} collisions")
+
+        # SCP to robot's dataset directory
+        for local_file in [json_path, wav_path]:
+            remote_target = f"{ROBOT_USER}@{host}:{dataset_path}/{local_file.name}"
+            result = subprocess.run(
+                ["scp", "-o", "ConnectTimeout=5", str(local_file), remote_target],
+                capture_output=True, text=True, timeout=15,
+            )
+            if result.returncode != 0:
+                raise RuntimeError(f"SCP failed: {result.stderr}")
+
+    # Trigger Marionette to re-scan recordings by re-selecting the active dataset
+    if active_id:
+        requests.post(
+            f"{base_url}/api/datasets/select",
+            json={"dataset_id": active_id},
+            timeout=5,
+        )
+    time.sleep(0.5)
+
+    # Verify the move is visible
+    state = requests.get(f"{base_url}/api/state", timeout=3).json()
+    move_ids = [m["id"] for m in state.get("moves", [])]
+    if MOVE_ID not in move_ids:
+        raise RuntimeError(
+            f"Move '{MOVE_ID}' not found after injection. "
+            f"Available: {move_ids}"
+        )
+    print(f"  Move '{MOVE_ID}' injected and visible in Marionette")
+
+
+def cleanup_move(host: str, base_url: str) -> None:
+    """Remove the synthetic test move."""
+    try:
+        requests.delete(f"{base_url}/api/moves/{MOVE_ID}", timeout=5)
+    except Exception:
+        pass
+
+
+def plot_results(
+    mic_audio, mic_sr, detected_beeps, detected_collisions, pairs, output_path,
+):
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    mic_t = np.arange(len(mic_audio)) / mic_sr
+
+    fig, ax = plt.subplots(1, 1, figsize=(18, 6))
+    ax.plot(mic_t, mic_audio, "k-", linewidth=0.3, alpha=0.5)
+    ax.set_ylabel("Mic amplitude")
+    ax.set_title("Marionette E2E Playback Sync Test — Laptop Mic Recording")
+    ax.grid(True, alpha=0.3)
+
+    for i, bt in enumerate(detected_beeps):
+        ax.axvline(bt, color="blue", linestyle="-", linewidth=1.2, alpha=0.7,
+                    label="Detected beep" if i == 0 else None)
+    for i, ct in enumerate(detected_collisions):
+        ax.axvline(ct, color="red", linestyle="-", linewidth=1.2, alpha=0.7,
+                    label="Detected collision" if i == 0 else None)
+    for p in pairs:
+        mid = (p["beep_t"] + p["collision_t"]) / 2
+        ax.annotate(f'{p["interval_ms"]:.0f}ms', xy=(mid, 0),
+                    ha="center", fontsize=9, color="purple", fontweight="bold",
+                    bbox=dict(boxstyle="round,pad=0.2", facecolor="lightyellow", alpha=0.8))
+
+    ax.legend(loc="upper right", fontsize=9)
+
+    all_events = detected_beeps + detected_collisions
+    if all_events:
+        ax.set_xlim(min(all_events) - 1.0, max(all_events) + 1.0)
+    ax.set_xlabel("Time since mic start (s)")
+
+    fig.tight_layout()
+    fig.savefig(str(output_path), dpi=150)
+    plt.close(fig)
+    print(f"  Plot saved to {output_path}")
+
+
+def run_playback_test(host: str) -> dict:
+    """Run the Marionette playback sync test.
+
+    Returns a results dict with pairs, errors, and verdict.
+    """
+    base_url = get_marionette_url(host)
+    print(f"\n{'='*60}")
+    print("Marionette E2E Playback Sync Test")
+    print(f"{'='*60}")
+    print(f"  Server: {base_url}")
+    print(f"  Beep times:      {BEEP_TIMES}")
+    print(f"  Collision times:  {COLLISION_TIMES}")
+    print(f"  Expected interval: {BEEP_COLLISION_OFFSET*1000:.0f}ms\n")
+
+    # Step 1: Ensure idle
+    print("[1/6] Ensuring Marionette is idle...")
+    ensure_idle(base_url)
+    print("  Idle.")
+
+    # Step 2: Inject synthetic move
+    print("[2/6] Injecting synthetic move into dataset...")
+    inject_move(host, base_url)
+
+    # Step 3: Start mic recording
+    print(f"\n[3/6] Starting mic recording ({MIC_DURATION}s)...")
+    mic_start = time.monotonic()
+    mic_data = sd.rec(
+        int(MIC_DURATION * LAPTOP_SR),
+        samplerate=LAPTOP_SR, channels=1, dtype="float32",
+    )
+
+    # Step 4: Trigger playback
+    time.sleep(0.3)
+    print("[4/6] Triggering playback via API...")
+    play_start = time.monotonic()
+    r = requests.post(f"{base_url}/api/play", json={"move_id": MOVE_ID}, timeout=5)
+    if r.status_code != 200:
+        sd.stop()
+        raise RuntimeError(f"Play failed: {r.status_code} {r.text}")
+    print(f"  Play accepted at mic_t={play_start - mic_start:.3f}s")
+
+    # Step 5: Wait for playback to finish
+    print("[5/6] Waiting for playback to finish...")
+    try:
+        state = wait_for_mode(base_url, "idle", timeout=30)
+        play_end = time.monotonic()
+        print(f"  Playback done at mic_t={play_end - mic_start:.3f}s")
+    except TimeoutError:
+        print("  WARNING: Playback did not finish in time")
+
+    sd.wait()
+    captured = mic_data.flatten()
+    print(f"  Mic recording done ({len(captured)/LAPTOP_SR:.1f}s)")
+
+    mic_path = Path("tests/marionette_sync_mic.wav")
+    sf.write(str(mic_path), captured, LAPTOP_SR)
+    print(f"  Saved to {mic_path}")
+
+    # Step 6: Analyze
+    print(f"\n[6/6] Analyzing...")
+    detected_beeps = detect_beep_onsets(
+        captured, LAPTOP_SR, freq=BEEP_FREQ, bandwidth=150.0,
+        threshold_db=-12.0, min_separation=1.0,
+    )
+    detected_collisions = detect_transient_onsets(
+        captured, LAPTOP_SR, highpass_freq=3000.0,
+    )
+    print(f"  Detected {len(detected_beeps)} beeps at: {[f'{t:.3f}' for t in detected_beeps]}")
+    print(f"  Detected {len(detected_collisions)} collisions at: {[f'{t:.3f}' for t in detected_collisions]}")
+
+    # Match pairs
+    print(f"\n{'='*60}")
+    print("Beep → Collision Interval Analysis (Marionette E2E)")
+    print(f"  (Expected interval: {BEEP_COLLISION_OFFSET*1000:.0f}ms)")
+    print(f"{'='*60}")
+
+    pairs = []
+    for i, bt in enumerate(detected_beeps):
+        candidates = [ct for ct in detected_collisions if 0.3 < (ct - bt) < 2.0]
+        if not candidates:
+            print(f"  Beep {i+1} at {bt:.3f}s: NO COLLISION FOUND")
+            continue
+        nearest = min(candidates, key=lambda ct: abs((ct - bt) - BEEP_COLLISION_OFFSET))
+        interval_ms = (nearest - bt) * 1000
+        error_ms = interval_ms - BEEP_COLLISION_OFFSET * 1000
+        pairs.append({
+            "beep_t": bt,
+            "collision_t": nearest,
+            "interval_ms": interval_ms,
+            "error_ms": error_ms,
+        })
+        print(f"  Pair {len(pairs)}: beep {bt:.3f}s → collision {nearest:.3f}s = "
+              f"{interval_ms:.0f}ms (error {error_ms:+.0f}ms)")
+
+    result = {
+        "test": "marionette_playback_sync",
+        "n_beeps_detected": len(detected_beeps),
+        "n_collisions_detected": len(detected_collisions),
+        "n_pairs": len(pairs),
+        "pairs": pairs,
+    }
+
+    if pairs:
+        errors = [p["error_ms"] for p in pairs]
+        intervals = [p["interval_ms"] for p in pairs]
+        result["mean_interval_ms"] = float(np.mean(intervals))
+        result["mean_error_ms"] = float(np.mean(errors))
+        result["std_error_ms"] = float(np.std(errors))
+        result["min_error_ms"] = float(min(errors))
+        result["max_error_ms"] = float(max(errors))
+        print(f"\n  Pairs matched: {len(pairs)}/{len(BEEP_TIMES)}")
+        print(f"  Mean interval: {np.mean(intervals):.0f}ms (expected {BEEP_COLLISION_OFFSET*1000:.0f}ms)")
+        print(f"  Mean error:    {np.mean(errors):+.0f}ms")
+        print(f"  Std error:     {np.std(errors):.0f}ms")
+        print(f"  Min/Max error: {min(errors):+.0f}ms / {max(errors):+.0f}ms")
+
+    # Plot
+    plot_path = Path("tests/marionette_sync_plot.png")
+    plot_results(captured, LAPTOP_SR, detected_beeps, detected_collisions, pairs, plot_path)
+
+    # Cleanup
+    cleanup_move(host, base_url)
+
+    success = len(pairs) >= len(BEEP_TIMES) - 1
+    result["success"] = success
+
+    print(f"\n{'='*60}")
+    if success:
+        print("RESULT: PASS — Beep-collision pairs detected via Marionette E2E")
+    else:
+        print("RESULT: FAIL — Could not reliably detect pairs")
+    print(f"{'='*60}\n")
+
+    return result
+
+
+def run_recording_test(host: str) -> dict:
+    """Test the 3-2-1 countdown timing accuracy.
+
+    Triggers a recording with a known audio file, records with the
+    laptop mic, and measures:
+      - Countdown beep timing (3 beeps at 440Hz, 1s apart)
+      - "Go" beep timing (880Hz)
+      - When the uploaded audio actually starts playing
+    """
+    base_url = get_marionette_url(host)
+    print(f"\n{'='*60}")
+    print("Marionette Recording Countdown Sync Test")
+    print(f"{'='*60}")
+    print(f"  Server: {base_url}\n")
+
+    # Step 1: Ensure idle
+    print("[1/5] Ensuring Marionette is idle...")
+    ensure_idle(base_url)
+
+    # Step 2: Upload a known audio file (a single 2kHz beep at t=0.5)
+    # This beep will play after the countdown, so we can measure
+    # the delay from "go" beep to actual audio playback start.
+    print("[2/5] Generating and uploading test audio...")
+    import tempfile
+    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
+        test_wav = Path(f.name)
+
+    # 3-second audio with a single 2kHz marker beep at t=0.2
+    # (early, so it's clearly after the go beep)
+    marker_time = 0.2
+    audio_duration = 3.0
+    n_audio = int(audio_duration * 48000)  # 48kHz for upload
+    audio = np.zeros(n_audio, dtype=np.float32)
+    start = int(marker_time * 48000)
+    n_beep = int(BEEP_DURATION * 48000)
+    t_arr = np.arange(n_beep, dtype=np.float32) / 48000
+    beep = BEEP_AMPLITUDE * np.sin(2 * np.pi * BEEP_FREQ * t_arr).astype(np.float32)
+    fade = int(0.005 * 48000)
+    if fade > 0:
+        beep[:fade] *= np.linspace(0, 1, fade, dtype=np.float32)
+        beep[-fade:] *= np.linspace(1, 0, fade, dtype=np.float32)
+    audio[start:start + n_beep] = beep
+    sf.write(str(test_wav), audio, 48000)
+    print(f"  Test audio: {audio_duration}s, marker beep at {marker_time}s (2kHz)")
+
+    # Upload via Marionette API
+    with open(test_wav, "rb") as f:
+        r = requests.post(
+            f"{base_url}/api/upload-audio",
+            files={"file": ("countdown_test.wav", f, "audio/wav")},
+            timeout=10,
+        )
+    test_wav.unlink()
+    if r.status_code != 200:
+        raise RuntimeError(f"Upload failed: {r.status_code} {r.text}")
+    upload_info = r.json()
+    upload_id = upload_info["upload_id"]
+    print(f"  Uploaded: id={upload_id}")
+
+    # Step 3: Start mic recording
+    print(f"\n[3/5] Starting mic recording (15s)...")
+    mic_duration = 15.0
+    mic_start = time.monotonic()
+    mic_data = sd.rec(
+        int(mic_duration * LAPTOP_SR),
+        samplerate=LAPTOP_SR, channels=1, dtype="float32",
+    )
+
+    # Step 4: Trigger recording
+    time.sleep(0.3)
+    print("[4/5] Triggering recording with audio...")
+    rec_start = time.monotonic()
+    r = requests.post(
+        f"{base_url}/api/record",
+        json={
+            "label": "countdown-test",
+            "duration": 3.0,
+            "record_audio": False,
+            "record_motion": True,
+            "uploaded_audio_id": upload_id,
+        },
+        timeout=5,
+    )
+    if r.status_code != 200:
+        sd.stop()
+        raise RuntimeError(f"Record failed: {r.status_code} {r.text}")
+    rec_move_id = r.json().get("move_id")
+    print(f"  Recording accepted at mic_t={rec_start - mic_start:.3f}s, move_id={rec_move_id}")
+
+    # Wait for recording to finish (countdown ~3s + recording ~3s)
+    print("[5/5] Waiting for recording to finish...")
+    try:
+        wait_for_mode(base_url, "idle", timeout=20)
+        rec_end = time.monotonic()
+        print(f"  Recording done at mic_t={rec_end - mic_start:.3f}s")
+    except TimeoutError:
+        print("  WARNING: Recording did not finish in time")
+
+    sd.wait()
+    captured = mic_data.flatten()
+
+    mic_path = Path("tests/marionette_countdown_mic.wav")
+    sf.write(str(mic_path), captured, LAPTOP_SR)
+    print(f"  Saved to {mic_path}")
+
+    # Analyze: detect countdown beeps (440Hz) and go beep (880Hz) and marker (2kHz)
+    print(f"\n{'='*60}")
+    print("Countdown Timing Analysis")
+    print(f"{'='*60}")
+
+    # Detect countdown beeps at 440Hz
+    countdown_beeps = detect_beep_onsets(
+        captured, LAPTOP_SR, freq=440.0, bandwidth=80.0,
+        threshold_db=-12.0, min_separation=0.8,
+    )
+    print(f"  Countdown beeps (440Hz): {len(countdown_beeps)} at {[f'{t:.3f}' for t in countdown_beeps]}")
+
+    # Detect "go" beep at 880Hz
+    go_beeps = detect_beep_onsets(
+        captured, LAPTOP_SR, freq=880.0, bandwidth=80.0,
+        threshold_db=-12.0, min_separation=0.5,
+    )
+    print(f"  Go beep (880Hz): {len(go_beeps)} at {[f'{t:.3f}' for t in go_beeps]}")
+
+    # Detect marker beep at 2kHz (from uploaded audio)
+    marker_beeps = detect_beep_onsets(
+        captured, LAPTOP_SR, freq=BEEP_FREQ, bandwidth=150.0,
+        threshold_db=-12.0, min_separation=0.5,
+    )
+    print(f"  Marker beep (2kHz): {len(marker_beeps)} at {[f'{t:.3f}' for t in marker_beeps]}")
+
+    result = {
+        "test": "marionette_recording_countdown",
+        "countdown_beeps": countdown_beeps,
+        "go_beeps": go_beeps,
+        "marker_beeps": marker_beeps,
+    }
+
+    # Analyze countdown spacing
+    if len(countdown_beeps) >= 2:
+        gaps = [countdown_beeps[i+1] - countdown_beeps[i] for i in range(len(countdown_beeps)-1)]
+        print(f"\n  Countdown gaps: {[f'{g:.3f}s' for g in gaps]} (expected ~1.0s each)")
+        result["countdown_gaps"] = gaps
+        gap_errors = [abs(g - 1.0) * 1000 for g in gaps]
+        print(f"  Gap errors: {[f'{e:.0f}ms' for e in gap_errors]}")
+
+    # Analyze go-to-marker delay
+    # Filter go beeps: discard any that overlap with countdown beeps (440Hz
+    # harmonic leaks into the 880Hz band).  The real "go" beep comes AFTER the
+    # last countdown beep.
+    if countdown_beeps and go_beeps:
+        last_cd = countdown_beeps[-1]
+        go_beeps_filtered = [t for t in go_beeps if t > last_cd + 0.3]
+        print(f"  Go beeps after countdown: {[f'{t:.3f}' for t in go_beeps_filtered]}")
+    else:
+        go_beeps_filtered = go_beeps
+
+    if go_beeps_filtered and marker_beeps:
+        go_t = go_beeps_filtered[0]
+        marker_t = marker_beeps[0]
+        delay_ms = (marker_t - go_t) * 1000
+        print(f"\n  Go beep → Marker beep: {delay_ms:.0f}ms")
+        print(f"  (Marker is at {marker_time}s in audio file)")
+        print(f"  Expected if no pipeline latency: ~{marker_time*1000:.0f}ms")
+        print(f"  Extra delay (pipeline latency): ~{delay_ms - marker_time*1000:.0f}ms")
+        result["go_to_marker_ms"] = delay_ms
+        result["estimated_pipeline_latency_ms"] = delay_ms - marker_time * 1000
+
+    # Cleanup: delete the test recording
+    if rec_move_id:
+        try:
+            requests.delete(f"{base_url}/api/moves/{rec_move_id}", timeout=5)
+        except Exception:
+            pass
+
+    success = len(countdown_beeps) >= 2 and len(marker_beeps) >= 1
+    result["success"] = success
+
+    print(f"\n{'='*60}")
+    if success:
+        print("RESULT: PASS — Countdown and marker beeps detected")
+    else:
+        print("RESULT: FAIL — Could not detect expected beeps")
+    print(f"{'='*60}\n")
+
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Marionette E2E sync tests")
+    parser.add_argument("--host", default="reachy-mini.local")
+    parser.add_argument("--test", choices=["playback", "recording", "both"],
+                        default="both", help="Which test to run")
+    args = parser.parse_args()
+
+    results = {}
+
+    if args.test in ("playback", "both"):
+        results["playback"] = run_playback_test(args.host)
+
+    if args.test in ("recording", "both"):
+        results["recording"] = run_recording_test(args.host)
+
+    # Save results
+    results_path = Path("tests/marionette_sync_results.json")
+    results_path.write_text(json.dumps(results, indent=2, default=str))
+    print(f"\nResults saved to {results_path}")
+
+    # Summary
+    print(f"\n{'='*60}")
+    print("SUMMARY")
+    print(f"{'='*60}")
+    for name, r in results.items():
+        status = "PASS" if r.get("success") else "FAIL"
+        if name == "playback" and "mean_error_ms" in r:
+            print(f"  {name}: {status} — mean error {r['mean_error_ms']:+.0f}ms, "
+                  f"std {r['std_error_ms']:.0f}ms")
+        elif name == "recording" and "go_to_marker_ms" in r:
+            print(f"  {name}: {status} — go→marker {r['go_to_marker_ms']:.0f}ms, "
+                  f"pipeline latency ~{r.get('estimated_pipeline_latency_ms', 0):.0f}ms")
+        else:
+            print(f"  {name}: {status}")
+    print(f"{'='*60}\n")
+
+    all_pass = all(r.get("success", False) for r in results.values())
+    return 0 if all_pass else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/test_move_sync.py

@@ -0,0 +1,464 @@
+#!/usr/bin/env python3
+"""Test beep+collision sync using a Marionette-format move played via SDK.
+
+Intermediate test between the direct-control script and the full Marionette
+frontend. Creates a synthetic move (JSON + WAV) matching the beep+collision
+test, plays it on the robot via reachy_mini SDK's play_move(), and records
+with the laptop mic.
+
+This tests the SDK's built-in audio-motion sync mechanism (play_sound +
+motion loop) rather than our manual push_audio_sample approach.
+
+Usage:
+    python tests/test_move_sync.py [--host reachy-mini.local]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+import numpy as np
+import sounddevice as sd
+import soundfile as sf
+
+sys.path.insert(0, str(Path(__file__).parent))
+from audio_analysis import detect_beep_onsets, detect_transient_onsets
+
+# Timing — same as test_beep_collision_sync.py
+BEEP_TIMES = [1.0, 2.3, 4.0, 6.3, 9.4]
+BEEP_COLLISION_OFFSET = 1.0
+COLLISION_TIMES = [t + BEEP_COLLISION_OFFSET for t in BEEP_TIMES]
+
+# Audio
+BEEP_FREQ = 2000.0
+BEEP_DURATION = 0.2
+BEEP_AMPLITUDE = 0.9
+ROBOT_SR = 16000
+
+# Collision
+RIGHT_REST = -0.68
+LEFT_REST = 0.0
+LEFT_COLLISION = 0.70
+HOLD_DURATION = 0.2
+
+MOTION_SR = 100  # 100Hz motion sampling, standard for Marionette
+
+ROBOT_USER = "pollen"
+ROBOT_PYTHON = "/venvs/apps_venv/bin/python"
+LAPTOP_SR = 48000
+MIC_DURATION = 30.0
+REMOTE_DIR = "/tmp/sync_test_move"
+REMOTE_RESULTS = "/tmp/move_sync_positions.json"
+
+
+def generate_move_files(tmpdir: Path) -> tuple[Path, Path]:
+    """Generate Marionette-format JSON + WAV for the beep+collision test."""
+    total_duration = max(COLLISION_TIMES) + HOLD_DURATION + 1.0
+    dt = 1.0 / MOTION_SR
+    n_frames = int(total_duration * MOTION_SR)
+
+    identity_head = np.eye(4).tolist()
+
+    # Build collision timeline
+    left_targets = np.full(n_frames, LEFT_REST, dtype=np.float64)
+    for ct in COLLISION_TIMES:
+        start = int(ct * MOTION_SR)
+        end = int((ct + HOLD_DURATION) * MOTION_SR)
+        end = min(end, n_frames)
+        left_targets[start:end] = LEFT_COLLISION
+
+    timestamps = []
+    frames = []
+    for i in range(n_frames):
+        t = i * dt
+        timestamps.append(round(t, 4))
+        frames.append({
+            "head": identity_head,
+            "antennas": [float(left_targets[i]), RIGHT_REST],
+            "body_yaw": 0.0,
+            "check_collision": False,
+        })
+
+    move_data = {
+        "description": "Sync test: beeps + antenna collisions",
+        "time": timestamps,
+        "set_target_data": frames,
+    }
+
+    json_path = tmpdir / "sync-test.json"
+    json_path.write_text(json.dumps(move_data), encoding="utf-8")
+
+    # Generate WAV with beeps
+    n_audio = int(total_duration * ROBOT_SR)
+    audio = np.zeros(n_audio, dtype=np.float32)
+    for bt in BEEP_TIMES:
+        start = int(bt * ROBOT_SR)
+        n_beep = int(BEEP_DURATION * ROBOT_SR)
+        if start + n_beep > n_audio:
+            continue
+        t_arr = np.arange(n_beep, dtype=np.float32) / ROBOT_SR
+        beep = BEEP_AMPLITUDE * np.sin(2 * np.pi * BEEP_FREQ * t_arr).astype(np.float32)
+        fade = int(0.005 * ROBOT_SR)
+        if fade > 0 and 2 * fade < n_beep:
+            beep[:fade] *= np.linspace(0, 1, fade, dtype=np.float32)
+            beep[-fade:] *= np.linspace(1, 0, fade, dtype=np.float32)
+        audio[start:start + n_beep] += beep
+
+    wav_path = tmpdir / "sync-test.wav"
+    sf.write(str(wav_path), audio, ROBOT_SR)
+
+    print(f"  Generated move: {n_frames} frames at {MOTION_SR}Hz, {total_duration:.1f}s")
+    print(f"  Generated WAV: {n_audio} samples at {ROBOT_SR}Hz, {len(BEEP_TIMES)} beeps")
+    return json_path, wav_path
+
+
+def scp_to_robot(local_path: Path, remote_path: str, host: str) -> None:
+    target = f"{ROBOT_USER}@{host}:{remote_path}"
+    result = subprocess.run(
+        ["scp", "-o", "ConnectTimeout=5", str(local_path), target],
+        capture_output=True, text=True, timeout=15,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"SCP failed: {result.stderr}")
+
+
+def scp_from_robot(remote_path: str, local_path: Path, host: str) -> None:
+    source = f"{ROBOT_USER}@{host}:{remote_path}"
+    result = subprocess.run(
+        ["scp", "-o", "ConnectTimeout=5", source, str(local_path)],
+        capture_output=True, text=True, timeout=15,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"SCP failed: {result.stderr}")
+
+
+# Robot-side playback script: loads the move, plays via SDK, records positions
+ROBOT_PLAY_SCRIPT = """\
+import json, os, sys, time
+import numpy as np
+from pathlib import Path
+
+move_dir = sys.argv[1]
+results_path = sys.argv[2]
+
+print("robot: connecting to ReachyMini", flush=True)
+from reachy_mini import ReachyMini
+from reachy_mini.motion.recorded_move import RecordedMove
+
+r = ReachyMini()
+
+# Load move
+json_path = Path(move_dir) / "sync-test.json"
+wav_path = Path(move_dir) / "sync-test.wav"
+move_data = json.loads(json_path.read_text())
+sound_path = wav_path if wav_path.exists() else None
+move = RecordedMove(move_data, sound_path=sound_path)
+print(f"robot: loaded move: {move.duration:.1f}s, sound={sound_path is not None}", flush=True)
+
+# Record present positions during playback at 50Hz
+# We do this in a background thread while play_move runs
+import threading
+
+timestamps = []
+left_present = []
+right_present = []
+recording = True
+
+def record_positions():
+    t0 = time.monotonic()
+    while recording:
+        pos = r.get_present_antenna_joint_positions()
+        timestamps.append(time.monotonic() - t0)
+        left_present.append(pos[0])
+        right_present.append(pos[1])
+        time.sleep(0.02)  # 50Hz
+
+recorder = threading.Thread(target=record_positions, daemon=True)
+
+print("robot: MARK_START", flush=True)
+recorder.start()
+r.play_move(move, initial_goto_duration=1.0)
+recording = False
+recorder.join(timeout=1.0)
+
+print(f"robot: playback done, recorded {len(timestamps)} position samples", flush=True)
+
+# Save results
+results = {
+    "beep_times": move_data.get("_beep_times", []),
+    "collision_times": move_data.get("_collision_times", []),
+    "timestamps": timestamps,
+    "left_present": left_present,
+    "right_present": right_present,
+}
+with open(results_path, "w") as f:
+    json.dump(results, f)
+print(f"robot: saved to {results_path}", flush=True)
+print("robot: done", flush=True)
+os._exit(0)
+"""
+
+
+def start_robot(host: str) -> subprocess.Popen:
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+        f.write(ROBOT_PLAY_SCRIPT)
+        local_script = Path(f.name)
+
+    remote_script = "/tmp/move_sync_play.py"
+    try:
+        target = f"{ROBOT_USER}@{host}:{remote_script}"
+        subprocess.run(
+            ["scp", "-o", "ConnectTimeout=5", str(local_script), target],
+            capture_output=True, text=True, timeout=15, check=True,
+        )
+    finally:
+        local_script.unlink()
+
+    args_str = f"{ROBOT_PYTHON} {remote_script} {REMOTE_DIR} {REMOTE_RESULTS}"
+    proc = subprocess.Popen(
+        ["ssh", "-o", "ConnectTimeout=5", f"{ROBOT_USER}@{host}", args_str],
+        stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
+    )
+    return proc
+
+
+def plot_combined(
+    mic_audio, mic_sr, mic_start, mark_start,
+    robot_data, detected_beeps, detected_collisions, pairs,
+    output_path,
+):
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    mic_t = np.arange(len(mic_audio)) / mic_sr
+    robot_offset = mark_start - mic_start
+
+    fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(18, 10), sharex=True)
+
+    # Mic waveform
+    ax1.plot(mic_t, mic_audio, "k-", linewidth=0.3, alpha=0.5)
+    ax1.set_ylabel("Mic amplitude")
+    ax1.set_title("Move Sync Test (SDK play_move) — Laptop Mic Recording")
+    ax1.grid(True, alpha=0.3)
+
+    for i, bt in enumerate(detected_beeps):
+        ax1.axvline(bt, color="blue", linestyle="-", linewidth=1.2, alpha=0.7,
+                     label="Detected beep" if i == 0 else None)
+    for i, ct in enumerate(detected_collisions):
+        ax1.axvline(ct, color="red", linestyle="-", linewidth=1.2, alpha=0.7,
+                     label="Detected collision" if i == 0 else None)
+    for p in pairs:
+        mid = (p["beep_mic_t"] + p["collision_mic_t"]) / 2
+        ax1.annotate(f'{p["interval_ms"]:.0f}ms', xy=(mid, 0),
+                     ha="center", fontsize=9, color="purple", fontweight="bold",
+                     bbox=dict(boxstyle="round,pad=0.2", facecolor="lightyellow", alpha=0.8))
+    ax1.legend(loc="upper right", fontsize=9)
+
+    # Robot trajectory
+    if robot_data.get("timestamps"):
+        robot_ts = np.array(robot_data["timestamps"])
+        left_pos = np.array(robot_data["left_present"])
+        right_pos = np.array(robot_data["right_present"])
+        # Note: robot timestamps start from MARK_START, which includes goto_duration
+        ax2.plot(robot_ts + robot_offset, left_pos, "b-", linewidth=1.5,
+                 label="Left antenna (present)")
+        ax2.plot(robot_ts + robot_offset, right_pos, "r-", linewidth=1.5,
+                 label="Right antenna (present)")
+
+    # Command times (approximate, via MARK_START)
+    for i, bt in enumerate(BEEP_TIMES):
+        # Beep times are relative to move start, not MARK_START
+        # play_move does a 1.0s goto first, so beeps start ~1s after MARK_START
+        mic_bt = robot_offset + 1.0 + bt  # +1.0 for initial_goto_duration
+        ax2.axvline(mic_bt, color="blue", linestyle="--", linewidth=0.8, alpha=0.4,
+                     label="Beep cmd (+goto)" if i == 0 else None)
+    for i, ct in enumerate(COLLISION_TIMES):
+        mic_ct = robot_offset + 1.0 + ct
+        ax2.axvline(mic_ct, color="red", linestyle="--", linewidth=0.8, alpha=0.4,
+                     label="Collision cmd (+goto)" if i == 0 else None)
+
+    for bt in detected_beeps:
+        ax2.axvline(bt, color="blue", linestyle="-", linewidth=0.8, alpha=0.4)
+    for ct in detected_collisions:
+        ax2.axvline(ct, color="red", linestyle="-", linewidth=0.8, alpha=0.4)
+
+    ax2.set_xlabel("Time since mic start (s)")
+    ax2.set_ylabel("Position (rad)")
+    ax2.set_title("Robot Antenna Trajectory (aligned to mic clock)")
+    ax2.legend(loc="upper right", fontsize=9)
+    ax2.grid(True, alpha=0.3)
+
+    # Auto-zoom to active region
+    all_events = detected_beeps + detected_collisions
+    if all_events:
+        ax1.set_xlim(min(all_events) - 1.0, max(all_events) + 1.0)
+
+    fig.tight_layout()
+    fig.savefig(str(output_path), dpi=150)
+    plt.close(fig)
+    print(f"  Plot saved to {output_path}")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Move sync test via SDK play_move")
+    parser.add_argument("--host", default="reachy-mini.local")
+    args = parser.parse_args()
+
+    print(f"\n{'='*60}")
+    print("Move Sync Test (SDK play_move)")
+    print(f"{'='*60}")
+    print(f"  Beep times:      {BEEP_TIMES}")
+    print(f"  Collision times:  {COLLISION_TIMES}")
+    print(f"  Expected interval: {BEEP_COLLISION_OFFSET:.1f}s\n")
+
+    # Step 1: Stop running apps
+    print("[1/6] Stopping any running app...")
+    subprocess.run(
+        ["ssh", "-o", "ConnectTimeout=5", f"{ROBOT_USER}@{args.host}",
+         "curl -sf -X POST http://127.0.0.1:8000/api/apps/stop-current-app >/dev/null 2>&1 || true"],
+        capture_output=True, timeout=10,
+    )
+    time.sleep(1)
+
+    # Step 2: Generate move files
+    print("[2/6] Generating Marionette-format move...")
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmpdir = Path(tmpdir)
+        json_path, wav_path = generate_move_files(tmpdir)
+
+        # Embed beep/collision times in JSON for the robot script to pass back
+        move_data = json.loads(json_path.read_text())
+        move_data["_beep_times"] = BEEP_TIMES
+        move_data["_collision_times"] = COLLISION_TIMES
+        json_path.write_text(json.dumps(move_data))
+
+        # Step 3: SCP to robot
+        print("[3/6] Copying move files to robot...")
+        subprocess.run(
+            ["ssh", "-o", "ConnectTimeout=5", f"{ROBOT_USER}@{args.host}",
+             f"mkdir -p {REMOTE_DIR}"],
+            capture_output=True, timeout=10,
+        )
+        scp_to_robot(json_path, f"{REMOTE_DIR}/sync-test.json", args.host)
+        scp_to_robot(wav_path, f"{REMOTE_DIR}/sync-test.wav", args.host)
+        print("  Done")
+
+    # Step 4: Start mic recording
+    print(f"[4/6] Starting mic recording ({MIC_DURATION}s)...")
+    mic_start = time.monotonic()
+    mic_data = sd.rec(
+        int(MIC_DURATION * LAPTOP_SR),
+        samplerate=LAPTOP_SR, channels=1, dtype="float32",
+    )
+
+    # Step 5: Start robot playback
+    time.sleep(0.3)
+    print("[5/6] Starting SDK play_move on robot...")
+    proc = start_robot(args.host)
+
+    mark_start = None
+    print("\n--- Robot output ---")
+    for line in iter(proc.stdout.readline, ""):
+        line = line.rstrip()
+        if not line:
+            continue
+        laptop_time = time.monotonic()
+        print(f"  {line}")
+        if "MARK_START" in line:
+            mark_start = laptop_time
+    proc.wait()
+    print("--- End robot output ---")
+
+    sd.wait()
+    captured = mic_data.flatten()
+    print(f"\n  Mic recording done")
+
+    if mark_start is None:
+        print("\nFAILED: Never received MARK_START")
+        return 1
+
+    robot_offset = mark_start - mic_start
+    print(f"  MARK_START at mic_t={robot_offset:.3f}s")
+
+    mic_path = Path("tests/move_sync_mic.wav")
+    sf.write(str(mic_path), captured, LAPTOP_SR)
+    print(f"  Saved mic to {mic_path}")
+
+    # Fetch robot position data
+    print("\n[6/6] Fetching robot data + analyzing...")
+    local_results = Path("tests/move_sync_positions.json")
+    scp_from_robot(REMOTE_RESULTS, local_results, args.host)
+    with open(local_results) as f:
+        robot_data = json.load(f)
+
+    # Detect beeps and collisions
+    detected_beeps = detect_beep_onsets(
+        captured, LAPTOP_SR, freq=BEEP_FREQ, bandwidth=150.0, threshold_db=-12.0,
+        min_separation=1.0,
+    )
+    detected_collisions = detect_transient_onsets(
+        captured, LAPTOP_SR, highpass_freq=3000.0,
+    )
+    print(f"  Detected {len(detected_beeps)} beeps at: "
+          f"{[f'{t:.3f}' for t in detected_beeps]}")
+    print(f"  Detected {len(detected_collisions)} collisions at: "
+          f"{[f'{t:.3f}' for t in detected_collisions]}")
+
+    # Match pairs
+    print(f"\n{'='*60}")
+    print("Beep → Collision Interval Analysis (SDK play_move)")
+    print(f"  (Expected interval: {BEEP_COLLISION_OFFSET*1000:.0f}ms)")
+    print(f"{'='*60}")
+
+    pairs = []
+    for i, bt in enumerate(detected_beeps):
+        candidates = [ct for ct in detected_collisions if 0.3 < (ct - bt) < 2.0]
+        if not candidates:
+            print(f"  Beep {i+1} at {bt:.3f}s: NO COLLISION FOUND")
+            continue
+        nearest = min(candidates, key=lambda ct: abs((ct - bt) - BEEP_COLLISION_OFFSET))
+        interval_ms = (nearest - bt) * 1000
+        error_ms = interval_ms - BEEP_COLLISION_OFFSET * 1000
+        pairs.append({
+            "beep_mic_t": bt,
+            "collision_mic_t": nearest,
+            "interval_ms": interval_ms,
+            "error_ms": error_ms,
+        })
+        print(f"  Pair {len(pairs)}: beep {bt:.3f}s → collision {nearest:.3f}s = "
+              f"{interval_ms:.0f}ms (error {error_ms:+.0f}ms)")
+
+    if pairs:
+        errors = [p["error_ms"] for p in pairs]
+        intervals = [p["interval_ms"] for p in pairs]
+        print(f"\n  Pairs matched: {len(pairs)}/{len(BEEP_TIMES)}")
+        print(f"  Mean interval: {np.mean(intervals):.0f}ms (expected {BEEP_COLLISION_OFFSET*1000:.0f}ms)")
+        print(f"  Mean error:    {np.mean(errors):+.0f}ms")
+        print(f"  Std error:     {np.std(errors):.0f}ms")
+        print(f"  Min/Max error: {min(errors):+.0f}ms / {max(errors):+.0f}ms")
+
+    plot_path = Path("tests/move_sync_plot.png")
+    plot_combined(
+        captured, LAPTOP_SR, mic_start, mark_start,
+        robot_data, detected_beeps, detected_collisions, pairs, plot_path,
+    )
+
+    success = len(pairs) >= len(BEEP_TIMES) - 1
+    print(f"\n{'='*60}")
+    if success:
+        print("RESULT: PASS — Beep-collision pairs detected via SDK play_move")
+    else:
+        print("RESULT: FAIL — Could not reliably detect pairs")
+    print(f"{'='*60}\n")
+
+    return 0 if success else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())