feat(audio-sequences): beat phase sync and aligned playback

Add bar-phase tracking, audio reset/anchor APIs, BPM holdover, beat-phase
sequence switching, sync-phase endpoint, and sample sequence data.

Co-authored-by: Cursor <cursoragent@cursor.com>

src/util/beat_driver_route.py

@@ -299,6 +299,10 @@ def _apply_manual_beat_route_standalone_overlay(
         return
     names = [str(n).strip() for n in device_names if str(n).strip()]
     with _route_lock:
+        if _sequence_lane_covers_standalone_overlay(names, str(wire_preset_id).strip()):
+            _lane_manual.pop(-1, None)
+            _sync_public_beat_route_from_lane_table()
+            return
         _lane_manual[-1] = {
             "device_names": names,
             "wire_preset_id": str(wire_preset_id).strip(),
@@ -350,6 +354,11 @@ def set_sequence_manual_lane_route(
             "manual_beat_n": mn,
             "beat_counter": bc,
         }
+        overlay = _lane_manual.get(-1)
+        if overlay and _lane_route_targets_key(names, wid) == _lane_route_targets_key(
+            overlay.get("device_names") or [], str(overlay.get("wire_preset_id") or "")
+        ):
+            _lane_manual.pop(-1, None)
         _sync_public_beat_route_from_lane_table()
 
 
@@ -362,6 +371,49 @@ def clear_sequence_manual_lane_route(lane_index: int) -> None:
         _sync_public_beat_route_from_lane_table()
 
 
+def _lane_route_targets_key(device_names: List[str], wire_preset_id: str) -> Tuple[Tuple[str, ...], str]:
+    names = tuple(sorted({str(n).strip() for n in (device_names or []) if str(n).strip()}))
+    return names, str(wire_preset_id or "").strip()
+
+
+def _sequence_lane_covers_standalone_overlay(device_names: List[str], wire_preset_id: str) -> bool:
+    """True when a sequence lane (0..n) already routes the same device(s) and wire preset."""
+    key = _lane_route_targets_key(device_names, wire_preset_id)
+    for lane_key, entry in _lane_manual.items():
+        if not isinstance(lane_key, int) or lane_key < 0:
+            continue
+        other = _lane_route_targets_key(
+            entry.get("device_names") or [], str(entry.get("wire_preset_id") or "")
+        )
+        if other == key:
+            return True
+    return False
+
+
+def mark_manual_select_sent_for_targets(
+    device_names: List[str], wire_preset_id: str
+) -> None:
+    """A ``select`` was just sent for these targets; skip one duplicate on the next beat."""
+    key = _lane_route_targets_key(device_names, wire_preset_id)
+    with _route_lock:
+        for entry in _lane_manual.values():
+            if not isinstance(entry, dict):
+                continue
+            other = _lane_route_targets_key(
+                entry.get("device_names") or [], str(entry.get("wire_preset_id") or "")
+            )
+            if other == key:
+                entry["suppress_next_notify"] = True
+
+
+def mark_sequence_manual_lane_select_sent(lane_index: int) -> None:
+    """A ``select`` was just sent for this lane; skip one duplicate on the next beat."""
+    with _route_lock:
+        e = _lane_manual.get(lane_index)
+        if e is not None:
+            e["suppress_next_notify"] = True
+
+
 def sync_beat_route_from_push_sequence(
     sequence: List[Any],
     target_macs: Optional[List[str]] = None,
@@ -438,6 +490,7 @@ def sync_beat_route_from_push_sequence(
             )
         else:
             _apply_manual_beat_route(device_names, wire_preset_id, preset_body)
+        mark_manual_select_sent_for_targets(device_names, wire_preset_id)
         return
 
     wire_id, body = _single_manual_wire_preset(merged_presets)
@@ -547,6 +600,7 @@ def notify_beat_detected() -> None:
         if not _lane_manual:
             return
         work = []
+        seen_targets: Set[Tuple[Tuple[str, ...], str]] = set()
         for key in sorted(_lane_manual.keys()):
             e = _lane_manual[key]
             names = e.get("device_names") or []
@@ -555,6 +609,8 @@ def notify_beat_detected() -> None:
             pattern = str(e.get("pattern") or "")
             if pattern and not _pattern_supports_manual(pattern):
                 continue
+            if e.pop("suppress_next_notify", False):
+                continue
             try:
                 n = int(e.get("manual_beat_n") or 1)
             except (TypeError, ValueError):
@@ -564,7 +620,12 @@ def notify_beat_detected() -> None:
             c = int(e["beat_counter"])
             if (c - 1) % n != 0:
                 continue
-            work.append((list(names), str(e.get("wire_preset_id") or "2")))
+            wire = str(e.get("wire_preset_id") or "2")
+            target_key = _lane_route_targets_key(names, wire)
+            if target_key in seen_targets:
+                continue
+            seen_targets.add(target_key)
+            work.append((list(names), wire))
         if work:
             _preset_session_beats += 1
     if not work: