livepilot 1.9.23 → 1.10.0

package/mcp_server/tools/arrangement.py

@@ -143,6 +143,48 @@ def create_arrangement_clip(
     return _get_ableton(ctx).send_command("create_arrangement_clip", params)
 
 
+@mcp.tool()
+def create_native_arrangement_clip(
+    ctx: Context,
+    track_index: int,
+    start_time: float,
+    length: float,
+    name: str = "",
+    color_index: Optional[int] = None,
+) -> dict:
+    """Create an empty MIDI clip directly in Arrangement View (Live 12.1.10+).
+
+    Unlike create_arrangement_clip (which duplicates a session clip), this creates
+    a native arrangement clip with full automation envelope support — volume rides,
+    filter sweeps, send automation all work natively.
+
+    Requires Live 12.1.10+. Falls back with a clear error on older versions.
+
+    track_index: 0+ for regular MIDI tracks
+    start_time:  beat position (0.0 = song start, 4.0 = bar 2 in 4/4)
+    length:      clip length in beats
+    name:        optional clip display name
+    color_index: optional 0-69 Ableton color
+    """
+    _validate_track_index(track_index)
+    if start_time < 0:
+        raise ValueError("start_time must be >= 0")
+    if length <= 0:
+        raise ValueError("length must be > 0")
+
+    params = {
+        "track_index": track_index,
+        "start_time": start_time,
+        "length": length,
+    }
+    if name:
+        params["name"] = name
+    if color_index is not None:
+        params["color_index"] = color_index
+
+    return _get_ableton(ctx).send_command("create_native_arrangement_clip", params)
+
+
 @mcp.tool()
 def add_arrangement_notes(
     ctx: Context,
@@ -288,6 +330,33 @@ def back_to_arranger(ctx: Context) -> dict:
     return _get_ableton(ctx).send_command("back_to_arranger")
 
 
+@mcp.tool()
+def force_arrangement(
+    ctx: Context,
+    beat_time: float = 0,
+    loop_start: float = 0,
+    loop_length: float = 0,
+    play: bool = True,
+) -> dict:
+    """Force ALL tracks to follow the arrangement and start playback.
+
+    Atomically: stops all session clips, releases every track from
+    session override, sets back-to-arranger, jumps to position, and
+    starts playing. This is the "play my arrangement from the top"
+    command.
+
+    beat_time: position to start from (default 0 = beginning)
+    loop_start: loop region start in beats (default 0)
+    loop_length: loop region length in beats (0 = no loop change)
+    play: whether to start playback (default True)
+    """
+    params: dict = {"beat_time": beat_time, "play": play}
+    if loop_length > 0:
+        params["loop_start"] = loop_start
+        params["loop_length"] = loop_length
+    return _get_ableton(ctx).send_command("force_arrangement", params)
+
+
 @mcp.tool()
 def get_arrangement_notes(
     ctx: Context,

package/mcp_server/tools/automation.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 from typing import Any, Optional
 
 from fastmcp import Context
+from pydantic import BaseModel, Field
 
 from ..curves import generate_curve, generate_from_recipe, list_recipes
 from ..server import mcp
@@ -27,10 +28,22 @@ def _ensure_list(v: Any) -> list:
         except json.JSONDecodeError as exc:
             raise ValueError(f"Invalid JSON in parameter: {exc}") from exc
     if isinstance(v, list):
-        return v
+        normalized = []
+        for item in v:
+            if isinstance(item, BaseModel):
+                normalized.append(item.model_dump(exclude_none=True))
+            else:
+                normalized.append(item)
+        return normalized
     return [v]
 
 
+class AutomationPoint(BaseModel):
+    time: float
+    value: float
+    duration: Optional[float] = Field(default=None, ge=0.0)
+
+
 @mcp.tool()
 def get_clip_automation(
     ctx: Context,
@@ -62,7 +75,7 @@ def set_clip_automation(
     track_index: int,
     clip_index: int,
     parameter_type: str,
-    points: Any,
+    points: list[AutomationPoint] | str,
     device_index: Optional[int] = None,
     parameter_index: Optional[int] = None,
     send_index: Optional[int] = None,

package/mcp_server/tools/devices.py

@@ -1,6 +1,6 @@
 """Device MCP tools — parameters, racks, browser loading, plugin deep control.
 
-15 tools matching the Remote Script devices domain + M4L bridge.
+16 tools matching the Remote Script devices domain + M4L bridge.
 """
 
 from __future__ import annotations
@@ -359,14 +359,15 @@ def find_and_load_device(ctx: Context, track_index: int, device_name: str) -> di
     if not device_name.strip():
         raise ValueError("device_name cannot be empty")
 
-    # Guardrail: bare Drum Rack produces silence (no samples loaded)
+    # Guardrail: bare Drum Rack produces silence unless building programmatically (12.3+)
     if device_name.strip().lower() == "drum rack":
         raise ValueError(
             "Loading a bare 'Drum Rack' creates an empty rack that produces silence. "
-            "Instead, use search_browser(path='drums') to find a kit preset "
-            "(e.g., '808 Core Kit'), then load it with load_browser_item(). "
-            "Or use DS drum synths (DS Kick, DS Snare, DS HH, DS Tom, DS Clap, "
-            "DS Cymbal) which are self-contained."
+            "Options: (1) search_browser(path='drums') to find a kit preset "
+            "(e.g., '808 Core Kit'), then load with load_browser_item(). "
+            "(2) On Live 12.3+: use insert_device('Drum Rack') + insert_rack_chain "
+            "+ set_drum_chain_note to build a kit programmatically. "
+            "(3) DS drum synths (DS Kick, DS Snare, DS HH) are self-contained."
         )
 
     result = _get_ableton(ctx).send_command("find_and_load_device", {
@@ -376,6 +377,116 @@ def find_and_load_device(ctx: Context, track_index: int, device_name: str) -> di
     return _postflight_loaded_device(ctx, result)
 
 
+@mcp.tool()
+def insert_device(
+    ctx: Context,
+    track_index: int,
+    device_name: str,
+    position: int = -1,
+    device_index: Optional[int] = None,
+    chain_index: Optional[int] = None,
+) -> dict:
+    """Insert a native Live device by name — 10x faster than browser search (Live 12.3+).
+
+    Only works for native devices (Reverb, Compressor, EQ Eight, Drift, etc.).
+    For plugins, M4L devices, or presets, use find_and_load_device or load_browser_item.
+
+    track_index:  0+ for regular tracks, -1/-2 for returns, -1000 for master
+    device_name:  exact device name (e.g. 'Reverb', 'Auto Filter', 'Wavetable')
+    position:     device chain position (0 = first, -1 = end of chain)
+    device_index: required when inserting into a rack chain (identifies the rack)
+    chain_index:  insert into this chain of a rack device (for building drum kits)
+
+    Drum Rack construction workflow (12.3+):
+    1. insert_device(track_index, 'Drum Rack')       — create empty rack
+    2. insert_rack_chain(track_index, device_index)   — add chains
+    3. set_drum_chain_note(chain_index, note=36)      — assign C1 (kick)
+    4. insert_device(track_index, 'Simpler',          — add instrument
+       device_index=rack_idx, chain_index=0)            into chain
+
+    On Live < 12.3: returns an error suggesting find_and_load_device instead.
+    """
+    _validate_track_index(track_index)
+    if not device_name.strip():
+        raise ValueError("device_name cannot be empty")
+
+    params = {
+        "track_index": track_index,
+        "device_name": device_name,
+        "position": position,
+    }
+    if device_index is not None:
+        params["device_index"] = device_index
+    if chain_index is not None:
+        if device_index is None:
+            raise ValueError("device_index is required when chain_index is provided")
+        _validate_device_index(device_index)
+        _validate_chain_index(chain_index)
+        params["chain_index"] = chain_index
+
+    result = _get_ableton(ctx).send_command("insert_device", params)
+    return _postflight_loaded_device(ctx, result)
+
+
+@mcp.tool()
+def insert_rack_chain(
+    ctx: Context,
+    track_index: int,
+    device_index: int,
+    position: int = -1,
+) -> dict:
+    """Insert a new chain into a Rack device — Instrument Rack, Audio Effect Rack, or Drum Rack (Live 12.3+).
+
+    Use with insert_device + set_drum_chain_note to build Drum Racks from scratch:
+    1. insert_device(track, 'Drum Rack') to create the rack
+    2. insert_rack_chain(track, rack_device_index) to add chains
+    3. set_drum_chain_note(chain_index=0, note=36) to assign C1 (kick)
+    4. insert_device(track, 'Simpler', device_index=rack, chain_index=0) into chain
+
+    track_index:  track containing the rack
+    device_index: rack device index on the track
+    position:     chain position (-1 = append to end)
+    """
+    _validate_track_index(track_index)
+    _validate_device_index(device_index)
+
+    return _get_ableton(ctx).send_command("insert_rack_chain", {
+        "track_index": track_index,
+        "device_index": device_index,
+        "position": position,
+    })
+
+
+@mcp.tool()
+def set_drum_chain_note(
+    ctx: Context,
+    track_index: int,
+    device_index: int,
+    chain_index: int,
+    note: int,
+) -> dict:
+    """Set which MIDI note triggers a Drum Rack chain (Live 12.3+).
+
+    Standard drum mapping:
+    C1 (36) = Kick, D1 (38) = Snare, F#1 (42) = Closed HH,
+    A#1 (46) = Open HH, C#2 (49) = Crash, D#2 (51) = Ride
+
+    note: MIDI note 0-127, or -1 for 'All Notes'
+    """
+    _validate_track_index(track_index)
+    _validate_device_index(device_index)
+    _validate_chain_index(chain_index)
+    if note < -1 or note > 127:
+        raise ValueError("note must be -1 (All Notes) or 0-127")
+
+    return _get_ableton(ctx).send_command("set_drum_chain_note", {
+        "track_index": track_index,
+        "device_index": device_index,
+        "chain_index": chain_index,
+        "note": note,
+    })
+
+
 @mcp.tool()
 def set_simpler_playback_mode(
     ctx: Context,

package/mcp_server/tools/notes.py

@@ -9,6 +9,7 @@ import json
 from typing import Any, Optional
 
 from fastmcp import Context
+from pydantic import BaseModel, Field
 
 from ..server import mcp
 
@@ -25,9 +26,36 @@ def _ensure_list(value: Any) -> list:
             return json.loads(value)
         except json.JSONDecodeError as exc:
             raise ValueError(f"Invalid JSON in parameter: {exc}") from exc
+    if isinstance(value, list):
+        normalized = []
+        for item in value:
+            if isinstance(item, BaseModel):
+                normalized.append(item.model_dump(exclude_none=True))
+            else:
+                normalized.append(item)
+        return normalized
     return value
 
 
+class NoteSpec(BaseModel):
+    pitch: int = Field(ge=0, le=127)
+    start_time: float
+    duration: float = Field(gt=0)
+    velocity: Optional[float] = Field(default=None, ge=0.0, le=127.0)
+    probability: Optional[float] = Field(default=None, ge=0.0, le=1.0)
+    velocity_deviation: Optional[float] = Field(default=None, ge=-127.0, le=127.0)
+    release_velocity: Optional[float] = Field(default=None, ge=0.0, le=127.0)
+
+
+class NoteModification(BaseModel):
+    note_id: int
+    pitch: Optional[int] = Field(default=None, ge=0, le=127)
+    start_time: Optional[float] = None
+    duration: Optional[float] = Field(default=None, gt=0)
+    velocity: Optional[float] = Field(default=None, ge=0.0, le=127.0)
+    probability: Optional[float] = Field(default=None, ge=0.0, le=1.0)
+
+
 def _validate_track_index(track_index: int):
     """Validate track index. Must be >= 0 for regular tracks."""
     if track_index < 0:
@@ -78,7 +106,7 @@ def _validate_note(note: dict):
 
 
 @mcp.tool()
-def add_notes(ctx: Context, track_index: int, clip_index: int, notes: Any) -> dict:
+def add_notes(ctx: Context, track_index: int, clip_index: int, notes: list[NoteSpec] | str) -> dict:
     """Add MIDI notes to a clip. notes is a JSON array: [{pitch, start_time, duration, velocity?, probability?, velocity_deviation?, release_velocity?}]."""
     _validate_track_index(track_index)
     _validate_clip_index(clip_index)
@@ -157,7 +185,7 @@ def remove_notes(
 
 
 @mcp.tool()
-def remove_notes_by_id(ctx: Context, track_index: int, clip_index: int, note_ids: Any) -> dict:
+def remove_notes_by_id(ctx: Context, track_index: int, clip_index: int, note_ids: list[int] | str) -> dict:
     """Remove specific MIDI notes by their IDs (JSON array of ints). Use undo to revert."""
     _validate_track_index(track_index)
     _validate_clip_index(clip_index)
@@ -172,7 +200,12 @@ def remove_notes_by_id(ctx: Context, track_index: int, clip_index: int, note_ids
 
 
 @mcp.tool()
-def modify_notes(ctx: Context, track_index: int, clip_index: int, modifications: Any) -> dict:
+def modify_notes(
+    ctx: Context,
+    track_index: int,
+    clip_index: int,
+    modifications: list[NoteModification] | str,
+) -> dict:
     """Modify existing MIDI notes by ID. modifications is a JSON array: [{note_id, pitch?, start_time?, duration?, velocity?, probability?}]."""
     _validate_track_index(track_index)
     _validate_clip_index(clip_index)
@@ -202,7 +235,7 @@ def duplicate_notes(
     ctx: Context,
     track_index: int,
     clip_index: int,
-    note_ids: Any,
+    note_ids: list[int] | str,
     time_offset: float = 0.0,
 ) -> dict:
     """Duplicate specific notes by ID (JSON array of ints), with optional time offset (in beats)."""

package/mcp_server/wonder_mode/diagnosis.py

@@ -23,6 +23,11 @@ _DOMAIN_MAP: dict[str, list[str]] = {
     "too_safe_to_progress": ["sound_design", "transition"],
     "section_missing": ["arrangement", "transition"],
     "transition_not_earned": ["transition", "arrangement"],
+    # Sample-domain patterns (session-state analysis, not action-history)
+    "no_organic_texture": ["sample", "sound_design"],
+    "stale_drums": ["sample", "arrangement"],
+    "vocal_processing_monotony": ["sample", "sound_design"],
+    "dense_but_static": ["sample", "mix"],
 }
 
 _STUCKNESS_THRESHOLD = 0.2  # Below this, treat as user_request

package/mcp_server/wonder_mode/engine.py

@@ -390,8 +390,86 @@ def _all_same_family(variants: list[dict]) -> bool:
     return len(families) <= 1 and len(variants) > 1
 
 
-# ── Pipeline orchestrator ────────────────────────────────────────
+# ── Corpus intelligence enrichment ──────────────────────────────
+
+
+def _get_corpus_hints(request_text: str, diagnosis: dict | None) -> dict | None:
+    """Query the corpus for creative hints relevant to the request.
+
+    Returns a dict with emotional_recipe, genre_chain, automation_density,
+    and technique_suggestions — or None if corpus is unavailable.
+    """
+    try:
+        from ..corpus import get_corpus
+    except ImportError:
+        return None
+
+    corpus = get_corpus()
+    if not corpus.emotional_recipes and not corpus.genre_chains:
+        return None
+
+    hints: dict = {}
+    request_lower = request_text.lower()
+
+    # Check for emotional keywords
+    _EMOTION_KEYWORDS = {
+        "warm": "warmth & comfort", "cold": "tension & anxiety",
+        "dark": "melancholy", "bright": "euphoria",
+        "aggressive": "danger", "soft": "warmth & comfort",
+        "anxious": "tension & anxiety", "nostalgic": "nostalgia",
+        "vast": "vastness", "ethereal": "vastness",
+        "sad": "melancholy", "happy": "euphoria",
+        "tension": "tension & anxiety", "release": "euphoria",
+    }
+    for keyword, emotion_key in _EMOTION_KEYWORDS.items():
+        if keyword in request_lower:
+            recipe = corpus.suggest_for_emotion(emotion_key)
+            if recipe:
+                hints["emotional_recipe"] = {
+                    "emotion": recipe.emotion,
+                    "technique_count": len(recipe.techniques),
+                    "first_techniques": [t[:100] for t in recipe.techniques[:3]],
+                }
+                break
+
+    # Check for genre keywords
+    _GENRE_KEYWORDS = ["dub", "techno", "minimal", "ambient", "idm", "trap",
+                       "sophie", "arca", "house", "trance", "drum and bass"]
+    for genre in _GENRE_KEYWORDS:
+        if genre in request_lower:
+            chain = corpus.get_genre_chain(genre)
+            if chain:
+                hints["genre_chain"] = {
+                    "genre": chain.genre,
+                    "devices": chain.devices[:5],
+                    "description": chain.description[:120],
+                }
+                break
+
+    # Check for physical model keywords
+    _MATERIAL_KEYWORDS = ["water", "metal", "glass", "breath", "fire", "electric"]
+    for material in _MATERIAL_KEYWORDS:
+        if material in request_lower:
+            model = corpus.suggest_for_material(material)
+            if model:
+                hints["physical_model"] = {
+                    "material": model.material,
+                    "devices": model.devices[:4],
+                }
+                break
 
+    # Automation density from diagnosis section type
+    if diagnosis:
+        problem_class = diagnosis.get("problem_class", "")
+        if "static" in problem_class or "flat" in problem_class:
+            hints["automation_density"] = corpus.get_automation_density_for_section("peak")
+        elif "breakdown" in problem_class:
+            hints["automation_density"] = corpus.get_automation_density_for_section("breakdown")
+
+    return hints if hints else None
+
+
+# ── Pipeline orchestrator ────────────────────────────────────────
 
 
 def generate_wonder_variants(
@@ -414,6 +492,9 @@ def generate_wonder_variants(
     labels = ["safe", "strong", "unexpected"]
     variants = []
 
+    # Load corpus intelligence for variant enrichment
+    corpus_hints = _get_corpus_hints(request_text, diagnosis)
+
     # Build executable variants from distinct moves
     for i, move in enumerate(distinct):
         label = labels[i]
@@ -429,6 +510,9 @@ def generate_wonder_variants(
             # Score taste on envelope-adjusted move for consistency with targets_snapshot
             v["taste_fit"] = compute_taste_fit(move_with_envelope, taste_graph)
         v["distinctness_reason"] = _explain_distinctness(move, distinct, i)
+        # Enrich with corpus knowledge
+        if corpus_hints:
+            v["corpus_hints"] = corpus_hints
         variants.append(v)
 
     executable_count = len(variants)

package/mcp_server/wonder_mode/tools.py

@@ -29,9 +29,14 @@ def _get_taste_graph(ctx: Context):
         from ..memory.taste_graph import build_taste_graph
         from ..memory.taste_memory import TasteMemoryStore
         from ..memory.anti_memory import AntiMemoryStore
+        from ..persistence.taste_store import PersistentTasteStore
         taste_store = ctx.lifespan_context.setdefault("taste_memory", TasteMemoryStore())
         anti_store = ctx.lifespan_context.setdefault("anti_memory", AntiMemoryStore())
-        return build_taste_graph(taste_store=taste_store, anti_store=anti_store)
+        persistent = ctx.lifespan_context.setdefault("persistent_taste", PersistentTasteStore())
+        return build_taste_graph(
+            taste_store=taste_store, anti_store=anti_store,
+            persistent_store=persistent,
+        )
     except Exception:
         pass
     return None

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "livepilot",
-  "version": "1.9.23",
+  "version": "1.10.0",
   "mcpName": "io.github.dreamrec/livepilot",
-  "description": "Agentic production system for Ableton Live 12 — 293 tools, 39 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
+  "description": "Agentic production system for Ableton Live 12 — 316 tools, 43 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "author": "Pilot Studio",
   "license": "MIT",
   "type": "commonjs",
@@ -17,6 +17,16 @@
   "bugs": {
     "url": "https://github.com/dreamrec/LivePilot/issues"
   },
+  "funding": [
+    {
+      "type": "patreon",
+      "url": "https://www.patreon.com/c/dreamrec"
+    },
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/dreamrec"
+    }
+  ],
   "keywords": [
     "mcp",
     "mcp-server",

package/remote_script/LivePilot/__init__.py

@@ -5,7 +5,7 @@ Entry point for the ControlSurface. Ableton calls create_instance(c_instance)
 when this script is selected in Preferences > Link, Tempo & MIDI.
 """
 
-__version__ = "1.9.23"
+__version__ = "1.10.0"
 
 from _Framework.ControlSurface import ControlSurface
 from .server import LivePilotServer
@@ -20,6 +20,7 @@ from . import browser      # noqa: F401  — registers browser handlers
 from . import arrangement  # noqa: F401  — registers arrangement handlers
 from . import diagnostics       # noqa: F401  — registers diagnostics handler
 from . import clip_automation   # noqa: F401  — registers clip automation handlers
+from . import version_detect    # noqa: F401  — version detection
 
 
 def create_instance(c_instance):
@@ -36,6 +37,12 @@ class LivePilot(ControlSurface):
         self._server.start()
         self.log_message("LivePilot v%s starting..." % __version__)
         self.show_message("LivePilot v%s starting..." % __version__)
+        v = version_detect.version_string()
+        self.log_message("LivePilot detected Ableton Live %s" % v)
+        features = version_detect.get_api_features()
+        enabled = [k for k, flag in features.items() if flag]
+        if enabled:
+            self.log_message("  Enabled features: %s" % ", ".join(enabled))
 
     def disconnect(self):
         """Called by Ableton when the script is unloaded."""

package/remote_script/LivePilot/arrangement.py

@@ -169,6 +169,70 @@ def create_arrangement_clip(song, params):
     }
 
 
+@register("create_native_arrangement_clip")
+def create_native_arrangement_clip(song, params):
+    """Create an empty MIDI clip in arrangement using the native 12.1.10+ API.
+
+    Unlike create_arrangement_clip (which duplicates a session clip),
+    this creates a true native clip with full automation envelope support.
+
+    Required: track_index, start_time, length
+    Optional: name, color_index
+    """
+    from .version_detect import has_feature
+
+    if not has_feature("create_midi_clip_arrangement"):
+        raise RuntimeError(
+            "create_native_arrangement_clip requires Live 12.1.10+. "
+            "Use create_arrangement_clip (session clip duplication) instead."
+        )
+
+    track_index = int(params["track_index"])
+    start_time = float(params["start_time"])
+    length = float(params["length"])
+    if length <= 0:
+        raise ValueError("length must be > 0")
+    if start_time < 0:
+        raise ValueError("start_time must be >= 0")
+
+    track = get_track(song, track_index)
+    if not track.has_midi_input:
+        raise ValueError(
+            "Track %d is not a MIDI track — create_native_arrangement_clip "
+            "only works on MIDI tracks" % track_index
+        )
+
+    song.begin_undo_step()
+    try:
+        clip = track.create_midi_clip(start_time, length)
+
+        name = params.get("name")
+        if name:
+            clip.name = str(name)
+        color_index = params.get("color_index")
+        if color_index is not None:
+            clip.color_index = int(color_index)
+    finally:
+        song.end_undo_step()
+
+    # Find the clip index in arrangement_clips
+    clip_index = None
+    for i, c in enumerate(track.arrangement_clips):
+        if abs(c.start_time - start_time) < 0.01:
+            clip_index = i
+            break
+
+    return {
+        "track_index": track_index,
+        "clip_index": clip_index,
+        "start_time": start_time,
+        "length": length,
+        "name": clip.name,
+        "has_envelope_support": True,
+        "native": True,
+    }
+
+
 @register("add_arrangement_notes")
 def add_arrangement_notes(song, params):
     """Add MIDI notes to an arrangement clip (by index in arrangement_clips)."""
@@ -713,3 +777,53 @@ def back_to_arranger(song, params):
     """Switch playback from session clips back to the arrangement timeline."""
     song.back_to_arranger = True
     return {"back_to_arranger": True}
+
+
+@register("force_arrangement")
+def force_arrangement(song, params):
+    """Force ALL tracks to follow the arrangement timeline.
+
+    Stops all session clips, releases every track from session override,
+    sets back_to_arranger, and optionally jumps to a start position.
+
+    This is the atomic "play the arrangement from the top" command.
+    """
+    # 1. Stop playback
+    was_playing = song.is_playing
+    if was_playing:
+        song.stop_playing()
+
+    # 2. Stop playing clip slots individually to release session overrides
+    #    (track.stop_all_clips() throws STATE_ERROR when tracks have no clips)
+    for track in list(song.tracks) + list(song.return_tracks):
+        try:
+            for slot in track.clip_slots:
+                if slot.has_clip and slot.is_playing:
+                    slot.clip.stop()
+        except Exception:
+            pass
+
+    # 3. Global back-to-arranger
+    song.back_to_arranger = True
+
+    # 4. Jump to position (default: start)
+    beat_time = float(params.get("beat_time", 0))
+    song.current_song_time = max(0, beat_time)
+
+    # 5. Set loop if requested
+    if "loop_length" in params:
+        song.loop_start = float(params.get("loop_start", 0))
+        song.loop_length = float(params["loop_length"])
+        song.loop = True
+
+    # 6. Start playback if requested (default: yes)
+    play = params.get("play", True)
+    if play:
+        song.start_playing()
+
+    return {
+        "arrangement_active": True,
+        "position": song.current_song_time,
+        "is_playing": song.is_playing,
+        "loop": song.loop,
+    }