livesession-mcp 2.0.0__tar.gz

livesession_mcp-2.0.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Siddharth Ahuja (original AbletonMCP)
+Copyright (c) 2026 Uri Rosen (LiveSession MCP)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

livesession_mcp-2.0.0/MCP_Server/__init__.py

@@ -0,0 +1,6 @@
+"""Ableton Live integration through the Model Context Protocol."""
+
+__version__ = "0.1.0"
+
+# Expose key classes and functions for easier imports
+from .server import AbletonConnection, get_ableton_connection

livesession_mcp-2.0.0/MCP_Server/als.py

@@ -0,0 +1,513 @@
+"""Read Ableton Live Sets (.als) and device presets (.adg/.adv) without Live running.
+
+These files are gzip-compressed XML. Everything here is read-only: summary, lint, diff between two
+versions, MIDI extraction (with a small Standard MIDI File writer) and preset inspection.
+Works with sets from Live 10-12 (MasterTrack/MainTrack, old and new scene layouts).
+"""
+
+from __future__ import annotations
+
+import gzip
+import math
+import re
+import struct
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+TRACK_TAGS = ("MidiTrack", "AudioTrack", "GroupTrack", "ReturnTrack")
+NOTE_NAMES = ["C", "C#", "D", "Eb", "E", "F", "F#", "G", "Ab", "A", "Bb", "B"]
+# Live's own devices that only ship with Suite (an .adg/.adv using them won't load in Standard/Intro).
+SUITE_ONLY = {"Operator", "InstrumentVector", "UltraAnalog", "Collision", "StringStudio", "LoungeLizard",
+              "Meld", "Roar", "MultiSampler", "InstrumentMeld", "Granulator", "Corpus", "Vocoder", "Spectral",
+              "Shifter", "HybridReverb", "Transmute", "Resonator"}
+MAX_FOR_LIVE_PREFIX = "Mx"
+
+
+# ── loading ───────────────────────────────────────────────────────────────────
+
+def load(path: str | Path) -> ET.Element:
+    """The root <Ableton> element of an .als/.adg/.adv (gzip or plain XML)."""
+    data = Path(path).read_bytes()
+    if data[:2] == b"\x1f\x8b":
+        data = gzip.decompress(data)
+    root = ET.fromstring(data)
+    if root.tag != "Ableton":
+        raise ValueError(f"{path} is not an Ableton document (root <{root.tag}>)")
+    return root
+
+
+def _v(el: Optional[ET.Element], path: str, default: Any = None) -> Any:
+    if el is None:
+        return default
+    found = el.find(path)
+    return found.get("Value", default) if found is not None else default
+
+
+def _f(el: Optional[ET.Element], path: str, default: float = 0.0) -> float:
+    try:
+        return float(_v(el, path, default))
+    except (TypeError, ValueError):
+        return default
+
+
+def _db(gain: float) -> float:
+    return round(20 * math.log10(gain), 1) if gain > 0 else -math.inf
+
+
+def _time_signature(code: float) -> str:
+    """Live stores the global time signature as (numerator - 1) + 99 * log2(denominator)."""
+    code = int(code)
+    denominator = 2 ** (code // 99)
+    return f"{code % 99 + 1}/{denominator}"
+
+
+# ── devices ───────────────────────────────────────────────────────────────────
+
+def device_name(dev: ET.Element) -> str:
+    if dev.tag in ("PluginDevice", "AuPluginDevice"):
+        for p in ("PluginDesc/Vst3PluginInfo/Name", "PluginDesc/VstPluginInfo/PlugName",
+                  "PluginDesc/AuPluginInfo/Name", "PluginDesc/AuPluginInfo/ComponentName"):
+            name = _v(dev, p)
+            if name:
+                return name
+        return "Plug-in"
+    user = _v(dev, "UserName")
+    return user or DISPLAY_NAMES.get(dev.tag, dev.tag)
+
+
+# Live's internal device tags -> the names Live shows.
+DISPLAY_NAMES = {
+    "OriginalSimpler": "Simpler", "MultiSampler": "Sampler", "InstrumentVector": "Wavetable",
+    "UltraAnalog": "Analog", "LoungeLizard": "Electric", "StringStudio": "Tension", "InstrumentImpulse": "Impulse",
+    "InstrumentGroupDevice": "Instrument Rack", "AudioEffectGroupDevice": "Audio Effect Rack",
+    "MidiEffectGroupDevice": "MIDI Effect Rack", "DrumGroupDevice": "Drum Rack", "AutoFilter2": "Auto Filter",
+    "AutoFilter": "Auto Filter", "Eq8": "EQ Eight", "Compressor2": "Compressor", "GlueCompressor": "Glue Compressor",
+    "MultibandDynamics": "Multiband Dynamics", "StereoGain": "Utility", "FilterDelay": "Filter Delay",
+    "PingPongDelay": "Ping Pong Delay", "GrainDelay": "Grain Delay", "HybridReverb": "Hybrid Reverb",
+    "AutoPan": "Auto Pan", "Tuner": "Tuner", "Limiter": "Limiter", "Saturator": "Saturator", "Redux2": "Redux",
+    "Vinyl": "Vinyl Distortion", "DrumBuss": "Drum Buss", "ChannelEq": "Channel EQ", "Echo": "Echo",
+    "InstrumentMeld": "Meld", "Drift": "Drift", "MidiArpeggiator": "Arpeggiator", "MidiChord": "Chord",
+    "MidiScale": "Scale", "MidiNoteLength": "Note Length", "MidiPitcher": "Pitch", "MidiRandom": "Random",
+    "MidiVelocity": "Velocity", "Collision": "Collision", "Operator": "Operator", "Vocoder": "Vocoder",
+}
+
+
+def device_info(dev: ET.Element) -> Dict[str, Any]:
+    info: Dict[str, Any] = {"name": device_name(dev), "type": dev.tag, "on": _v(dev, "On/Manual", "true") == "true"}
+    if dev.tag in ("PluginDevice", "AuPluginDevice"):
+        info["plugin"] = True
+        info["format"] = ("VST3" if dev.find("PluginDesc/Vst3PluginInfo") is not None else
+                          "AU" if dev.find("PluginDesc/AuPluginInfo") is not None else "VST2")
+        if any(_v(dev, p) == "true" for p in ("PluginDesc/Vst3PluginInfo/IsPlaceholderDevice",
+                                               "PluginDesc/VstPluginInfo/IsPlaceholderDevice")):
+            info["missing_when_saved"] = True
+    if dev.tag.startswith(MAX_FOR_LIVE_PREFIX):
+        info["max_for_live"] = True
+    chains = dev.findall("Branches/*/DeviceChain/MidiToAudioDeviceChain/Devices") + \
+        dev.findall("Branches/*/DeviceChain/AudioToAudioDeviceChain/Devices") + \
+        dev.findall("Branches/*/DeviceChain/MidiToMidiDeviceChain/Devices")
+    inner = [device_info(d) for devs in chains for d in devs]
+    if inner:
+        info["contains"] = inner
+    return info
+
+
+def _devices(track: ET.Element) -> List[ET.Element]:
+    devs = track.find("DeviceChain/DeviceChain/Devices")
+    return list(devs) if devs is not None else []
+
+
+def _walk_devices(infos: Iterable[Dict[str, Any]]) -> Iterable[Dict[str, Any]]:
+    for d in infos:
+        yield d
+        yield from _walk_devices(d.get("contains", []))
+
+
+# ── clips ─────────────────────────────────────────────────────────────────────
+
+def _notes(clip: ET.Element) -> List[Dict[str, Any]]:
+    notes = []
+    for kt in clip.findall("Notes/KeyTracks/KeyTrack"):
+        pitch = int(_v(kt, "MidiKey", 60))
+        for ev in kt.findall("Notes/MidiNoteEvent"):
+            notes.append({"pitch": pitch, "start_time": float(ev.get("Time", 0)),
+                          "duration": float(ev.get("Duration", 0.25)), "velocity": int(float(ev.get("Velocity", 100))),
+                          "mute": ev.get("IsEnabled", "true") == "false",
+                          "probability": float(ev.get("Probability", 1))})
+    notes.sort(key=lambda n: (n["start_time"], n["pitch"]))
+    return notes
+
+
+def _clip_info(clip: ET.Element, where: str, slot: Optional[int] = None) -> Dict[str, Any]:
+    start = _f(clip, "CurrentStart")
+    end = _f(clip, "CurrentEnd", start)
+    info: Dict[str, Any] = {"name": _v(clip, "Name", ""), "kind": "midi" if clip.tag == "MidiClip" else "audio",
+                            "where": where, "start": start if where == "arrangement" else None,
+                            "length": round(end - start, 4) if where == "arrangement" else
+                            round(_f(clip, "Loop/LoopEnd") - _f(clip, "Loop/LoopStart"), 4),
+                            "loop_start": _f(clip, "Loop/LoopStart"), "loop_end": _f(clip, "Loop/LoopEnd"),
+                            "muted": _v(clip, "Disabled", "false") == "true"}
+    if slot is not None:
+        info["slot"] = slot
+    if clip.tag == "MidiClip":
+        info["notes"] = len(clip.findall("Notes/KeyTracks/KeyTrack/Notes/MidiNoteEvent"))
+    else:
+        info["sample"] = sample_path(clip.find("SampleRef/FileRef"))
+    return info
+
+
+def _session_clips(track: ET.Element) -> List[ET.Element]:
+    out = []
+    for slot in track.findall("DeviceChain/MainSequencer/ClipSlotList/ClipSlot"):
+        clip = slot.find("ClipSlot/Value/*")
+        out.append(clip)
+    return out
+
+
+def _arrangement_clips(track: ET.Element) -> List[ET.Element]:
+    return track.findall("DeviceChain/MainSequencer//ArrangerAutomation/Events/*")
+
+
+def sample_path(fileref: Optional[ET.Element]) -> Optional[str]:
+    if fileref is None:
+        return None
+    return _v(fileref, "Path") or _v(fileref, "RelativePath")
+
+
+# ── summary ───────────────────────────────────────────────────────────────────
+
+def _track_kind(tag: str) -> str:
+    return {"MidiTrack": "midi", "AudioTrack": "audio", "GroupTrack": "group", "ReturnTrack": "return"}[tag]
+
+
+def track_info(track: ET.Element, groups: Dict[str, str]) -> Dict[str, Any]:
+    mixer = track.find("DeviceChain/Mixer")
+    devices = [device_info(d) for d in _devices(track)]
+    session = [(i, c) for i, c in enumerate(_session_clips(track)) if c is not None]
+    arrangement = _arrangement_clips(track)
+    info = {
+        "name": _v(track, "Name/EffectiveName", ""),
+        "kind": _track_kind(track.tag),
+        "id": track.get("Id"),
+        "group": groups.get(_v(track, "TrackGroupId", "-1")),
+        "volume_db": _db(_f(mixer, "Volume/Manual", 1.0)),
+        "pan": round(_f(mixer, "Pan/Manual"), 2),
+        "muted": _v(mixer, "Speaker/Manual", "true") == "false",
+        "solo": _v(mixer, "SoloSink", "false") == "true",
+        "frozen": _v(track, "Freeze", "false") == "true",
+        "output": _v(track, "DeviceChain/AudioOutputRouting/Target", ""),
+        "sends_db": [_db(_f(s, "Send/Manual")) for s in mixer.findall("Sends/TrackSendHolder")] if mixer is not None else [],
+        "devices": devices,
+        "session_clips": [_clip_info(c, "session", i) for i, c in session],
+        "arrangement_clips": [_clip_info(c, "arrangement") for c in arrangement],
+    }
+    return info
+
+
+def _live_set(root: ET.Element) -> ET.Element:
+    ls = root.find("LiveSet")
+    if ls is None:
+        raise ValueError("Not a Live Set (no <LiveSet>)")
+    return ls
+
+
+def _main_track(ls: ET.Element) -> Optional[ET.Element]:
+    return ls.find("MainTrack") if ls.find("MainTrack") is not None else ls.find("MasterTrack")
+
+
+def summary(root: ET.Element, path: str | Path = "") -> Dict[str, Any]:
+    ls = _live_set(root)
+    tracks_el = [t for t in ls.find("Tracks") if t.tag in TRACK_TAGS]
+    groups = {t.get("Id"): _v(t, "Name/EffectiveName", "") for t in tracks_el if t.tag == "GroupTrack"}
+    tracks = [track_info(t, groups) for t in tracks_el if t.tag != "ReturnTrack"]
+    returns = [track_info(t, groups) for t in tracks_el if t.tag == "ReturnTrack"]
+    main = _main_track(ls)
+    scenes = [_v(s, "Name", "") for s in ls.findall("Scenes/Scene")] or \
+        [_v(s, "Value", "") for s in ls.findall("SceneNames/Scene")]
+    root_note = _v(ls, "ScaleInformation/RootNote")
+    ends = [c["start"] + c["length"] for t in tracks for c in t["arrangement_clips"]]
+    plugins = sorted({d["name"] for t in tracks + returns for d in _walk_devices(t["devices"]) if d.get("plugin")})
+    return {
+        "file": str(path),
+        "created_with": root.get("Creator", ""),
+        "tempo": _f(main, "DeviceChain/Mixer/Tempo/Manual", 120.0),
+        "time_signature": _time_signature(_f(main, "DeviceChain/Mixer/TimeSignature/Manual", 201)),
+        "scale": (f"{NOTE_NAMES[int(root_note) % 12]} {_v(ls, 'ScaleInformation/Name', '')}".strip()
+                  if root_note is not None else None),
+        "arrangement_length_beats": round(max(ends), 2) if ends else 0.0,
+        "locators": [{"name": _v(l, "Name", ""), "time": _f(l, "Time")} for l in ls.findall("Locators/Locators/Locator")],
+        "scenes": [s for s in scenes],
+        "tracks": tracks,
+        "returns": returns,
+        "main": {"volume_db": _db(_f(main, "DeviceChain/Mixer/Volume/Manual", 1.0)),
+                 "devices": [device_info(d) for d in _devices(main)] if main is not None else []},
+        "plugins": plugins,
+        "counts": {"tracks": len(tracks), "returns": len(returns),
+                   "midi_clips": sum(c["kind"] == "midi" for t in tracks
+                                     for c in t["session_clips"] + t["arrangement_clips"]),
+                   "audio_clips": sum(c["kind"] == "audio" for t in tracks
+                                      for c in t["session_clips"] + t["arrangement_clips"])},
+    }
+
+
+def compact(summary_: Dict[str, Any]) -> Dict[str, Any]:
+    """A shorter summary for chat: device names instead of full device trees, clip counts."""
+    def short(t: Dict[str, Any]) -> Dict[str, Any]:
+        return {"name": t["name"], "kind": t["kind"], "group": t["group"], "volume_db": t["volume_db"],
+                "muted": t["muted"], "frozen": t["frozen"],
+                "devices": [d["name"] + ("" if d["on"] else " (off)") for d in t["devices"]],
+                "session_clips": len(t["session_clips"]), "arrangement_clips": len(t["arrangement_clips"])}
+    out = {k: v for k, v in summary_.items() if k not in ("tracks", "returns", "main")}
+    out["tracks"] = [short(t) for t in summary_["tracks"]]
+    out["returns"] = [short(t) for t in summary_["returns"]]
+    out["main"] = {"volume_db": summary_["main"]["volume_db"],
+                   "devices": [d["name"] for d in summary_["main"]["devices"]]}
+    return out
+
+
+# ── lint ──────────────────────────────────────────────────────────────────────
+
+_DEFAULT_NAME = re.compile(r"^\d+[- ](MIDI|Audio|Group)$|^(MIDI|Audio)( \d+)?$", re.I)
+
+
+def lint(root: ET.Element, path: str | Path = "",
+         installed_plugins: Optional[Iterable[str]] = None) -> List[Dict[str, str]]:
+    """Problems worth fixing before sharing or mixing, most serious first."""
+    s = summary(root, path)
+    project = Path(path).parent if path else None
+    issues: List[Dict[str, str]] = []
+
+    def add(severity: str, where: str, message: str) -> None:
+        issues.append({"severity": severity, "where": where, "message": message})
+
+    # Missing and uncollected samples (other FileRefs are preset history, e.g. where a factory kit was authored)
+    for fr in _live_set(root).findall(".//SampleRef/FileRef"):
+        p = _v(fr, "Path")
+        rel = _v(fr, "RelativePath")
+        if not p and not rel:
+            continue
+        exists = bool(p and Path(p).exists()) or bool(project and rel and (project / rel).exists())
+        if not exists:
+            add("error", "files", f"Missing file: {p or rel}")
+        elif (project and p and not _v(fr, "LivePackName") and "/resources/" not in p.replace("\\", "/").lower()
+              and not str(Path(p)).lower().startswith(str(project).lower())):
+            add("warning", "files", f"File outside the project folder (use File > Collect All and Save): {p}")
+
+    installed = {n.lower() for n in installed_plugins} if installed_plugins else None
+    names = [t["name"] for t in s["tracks"]]
+    for t in s["tracks"] + s["returns"]:
+        where = f"track '{t['name']}'" if t["kind"] != "return" else f"return '{t['name']}'"
+        for d in _walk_devices(t["devices"]):
+            if d.get("missing_when_saved"):
+                add("error", where, f"Plug-in '{d['name']}' was missing when the set was saved")
+            elif d.get("plugin") and installed is not None and d["name"].lower() not in installed:
+                add("error", where, f"Plug-in '{d['name']}' is not installed on this computer")
+            if not d["on"]:
+                add("info", where, f"Device '{d['name']}' is switched off")
+        if t["output"].endswith("/None"):
+            add("warning", where, "Output is routed to nowhere: it won't be heard or exported")
+        if t["volume_db"] > 6:
+            add("warning", where, f"Fader at {t['volume_db']:+.1f} dB: gain-stage earlier in the chain instead")
+        if t["kind"] in ("midi", "audio"):
+            has_content = t["session_clips"] or t["arrangement_clips"]
+            if not has_content and not t["devices"]:
+                add("info", where, "Empty track (no clips, no devices)")
+            if t["muted"] and has_content:
+                add("info", where, "Muted track with clips: delete it or unmute before export")
+            if t["kind"] == "midi" and has_content and not t["devices"]:
+                add("warning", where, "MIDI clips but no instrument: the track is silent")
+            if t["solo"]:
+                add("warning", where, "Track is soloed: everything else is silent on export")
+        if t["frozen"]:
+            add("info", where, "Frozen track (unfreeze to edit it)")
+        if _DEFAULT_NAME.match(t["name"]):
+            add("info", where, "Default track name: name it for collaborators")
+    for n in sorted({n for n in names if names.count(n) > 1}):
+        add("info", "tracks", f"Several tracks are named '{n}'")
+    if s["main"]["volume_db"] > 0:
+        add("warning", "main", f"Main fader above 0 dB ({s['main']['volume_db']:+.1f} dB): risk of clipping")
+    if not s["locators"] and s["arrangement_length_beats"] > 64:
+        add("info", "arrangement", "No locators: mark the song sections for faster navigation")
+    order = {"error": 0, "warning": 1, "info": 2}
+    issues.sort(key=lambda i: order[i["severity"]])
+    return issues
+
+
+# ── diff ──────────────────────────────────────────────────────────────────────
+
+def diff(a: Dict[str, Any], b: Dict[str, Any]) -> Dict[str, Any]:
+    """Changes from summary a (older) to summary b (newer)."""
+    out: Dict[str, Any] = {}
+    for key in ("tempo", "time_signature", "scale", "arrangement_length_beats"):
+        if a.get(key) != b.get(key):
+            out[key] = {"from": a.get(key), "to": b.get(key)}
+
+    def by_id(tracks: List[Dict[str, Any]]) -> Dict[str, Dict[str, Any]]:
+        return {t["id"]: t for t in tracks}
+
+    for section in ("tracks", "returns"):
+        ta, tb = by_id(a[section]), by_id(b[section])
+        added = [tb[i]["name"] for i in tb if i not in ta]
+        removed = [ta[i]["name"] for i in ta if i not in tb]
+        changed = []
+        for i in ta.keys() & tb.keys():
+            x, y = ta[i], tb[i]
+            c: Dict[str, Any] = {}
+            if x["name"] != y["name"]:
+                c["renamed"] = {"from": x["name"], "to": y["name"]}
+            if abs((x["volume_db"] if math.isfinite(x["volume_db"]) else -200) -
+                   (y["volume_db"] if math.isfinite(y["volume_db"]) else -200)) >= 0.1:
+                c["volume_db"] = {"from": x["volume_db"], "to": y["volume_db"]}
+            for k in ("muted", "solo", "frozen", "pan", "output", "group"):
+                if x[k] != y[k]:
+                    c[k] = {"from": x[k], "to": y[k]}
+            dx, dy = [d["name"] for d in x["devices"]], [d["name"] for d in y["devices"]]
+            if dx != dy:
+                c["devices"] = {"from": dx, "to": dy}
+            for kind in ("session_clips", "arrangement_clips"):
+                cx = [(cl["name"], cl.get("start"), cl["length"], cl.get("notes")) for cl in x[kind]]
+                cy = [(cl["name"], cl.get("start"), cl["length"], cl.get("notes")) for cl in y[kind]]
+                if cx != cy:
+                    c[kind] = {"from": len(cx), "to": len(cy),
+                               "notes_from": sum(n or 0 for *_, n in cx), "notes_to": sum(n or 0 for *_, n in cy)}
+            if c:
+                changed.append({"track": y["name"], **c})
+        if added or removed or changed:
+            out[section] = {"added": added, "removed": removed, "changed": changed}
+    la = {(l["name"], l["time"]) for l in a["locators"]}
+    lb = {(l["name"], l["time"]) for l in b["locators"]}
+    if la != lb:
+        out["locators"] = {"added": sorted(lb - la, key=lambda x: x[1]), "removed": sorted(la - lb, key=lambda x: x[1])}
+    if a["scenes"] != b["scenes"]:
+        out["scenes"] = {"from": a["scenes"], "to": b["scenes"]}
+    pa, pb = set(a["plugins"]), set(b["plugins"])
+    if pa != pb:
+        out["plugins"] = {"added": sorted(pb - pa), "removed": sorted(pa - pb)}
+    return out or {"identical": True}
+
+
+# ── MIDI ──────────────────────────────────────────────────────────────────────
+
+def midi_clips(root: ET.Element, track: Optional[str] = None) -> List[Dict[str, Any]]:
+    """Every MIDI clip with its notes; track filters by (part of) the track name."""
+    ls = _live_set(root)
+    out = []
+    for t in ls.find("Tracks"):
+        if t.tag != "MidiTrack":
+            continue
+        name = _v(t, "Name/EffectiveName", "")
+        if track and track.lower() not in name.lower():
+            continue
+        for i, clip in enumerate(_session_clips(t)):
+            if clip is not None and clip.tag == "MidiClip":
+                out.append({"track": name, **_clip_info(clip, "session", i), "note_list": _notes(clip)})
+        for clip in _arrangement_clips(t):
+            if clip.tag == "MidiClip":
+                out.append({"track": name, **_clip_info(clip, "arrangement"), "note_list": _notes(clip)})
+    return out
+
+
+def _vlq(n: int) -> bytes:
+    out = [n & 0x7F]
+    n >>= 7
+    while n:
+        out.append((n & 0x7F) | 0x80)
+        n >>= 7
+    return bytes(reversed(out))
+
+
+def write_midi(path: str | Path, notes: List[Dict[str, Any]], tempo: float = 120.0, numerator: int = 4,
+               denominator: int = 4, ppq: int = 480, name: str = "") -> Path:
+    """A one-track Standard MIDI File (format 0) from note dicts (times in beats)."""
+    events = []
+    for n in notes:
+        if n.get("mute"):
+            continue
+        on = round(n["start_time"] * ppq)
+        off = round((n["start_time"] + n["duration"]) * ppq)
+        pitch, vel = int(n["pitch"]), max(1, min(127, int(n["velocity"])))
+        events.append((on, 1, bytes([0x90, pitch, vel])))
+        events.append((max(off, on + 1), 0, bytes([0x80, pitch, 0])))
+    events.sort(key=lambda e: (e[0], e[1]))
+    us = round(60_000_000 / tempo)
+    track = b"\x00\xff\x51\x03" + us.to_bytes(3, "big")
+    track += b"\x00\xff\x58\x04" + bytes([numerator, int(math.log2(denominator)), 24, 8])
+    if name:
+        raw = name.encode("utf-8")[:120]
+        track += b"\x00\xff\x03" + _vlq(len(raw)) + raw
+    last = 0
+    for tick, _, msg in events:
+        track += _vlq(tick - last) + msg
+        last = tick
+    track += b"\x00\xff\x2f\x00"
+    data = b"MThd" + struct.pack(">IHHH", 6, 0, 1, ppq) + b"MTrk" + struct.pack(">I", len(track)) + track
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(data)
+    return path
+
+
+def estimate_key(notes: List[Dict[str, Any]]) -> Optional[str]:
+    """Key from MIDI notes (duration-weighted Krumhansl profiles)."""
+    major = [6.35, 2.23, 3.48, 2.33, 4.38, 4.09, 2.52, 5.19, 2.39, 3.66, 2.29, 2.88]
+    minor = [6.33, 2.68, 3.52, 5.38, 2.60, 3.53, 2.54, 4.75, 3.98, 2.69, 3.34, 3.17]
+    hist = [0.0] * 12
+    for n in notes:
+        if not n.get("mute"):
+            hist[n["pitch"] % 12] += n["duration"]
+    if sum(hist) == 0:
+        return None
+
+    def corr(x: List[float], y: List[float]) -> float:
+        mx, my = sum(x) / 12, sum(y) / 12
+        num = sum((a - mx) * (b - my) for a, b in zip(x, y))
+        den = math.sqrt(sum((a - mx) ** 2 for a in x) * sum((b - my) ** 2 for b in y))
+        return num / den if den else 0.0
+    best = max(((corr(hist, prof[-i:] + prof[:-i]), f"{NOTE_NAMES[i]} {mode}")
+                for i in range(12) for prof, mode in ((major, "major"), (minor, "minor"))))
+    return best[1]
+
+
+# ── presets ───────────────────────────────────────────────────────────────────
+
+def _preset_device(preset: ET.Element) -> Optional[Dict[str, Any]]:
+    """Device info for one preset element: a rack (GroupDevicePreset, with its chains), a device
+    preset (AbletonDevicePreset / PluginPreset wrapping <Device>) or a bare device (.adv)."""
+    if preset.tag == "GroupDevicePreset" or preset.find("Device") is not None:
+        dev_holder = preset.find("Device")
+        if dev_holder is None or not len(dev_holder):
+            return None
+        info = device_info(dev_holder[0])
+        chains = []
+        for branch in preset.findall("BranchPresets/*"):
+            devices = [d for d in (_preset_device(p) for p in branch.findall("DevicePresets/*")) if d]
+            chains.append({"name": _v(branch, "Name", ""), "devices": devices})
+        if chains:
+            info["chains"] = chains
+            info["contains"] = [d for c in chains for d in c["devices"]]
+        return info
+    return device_info(preset)
+
+
+def preset_info(root: ET.Element) -> Dict[str, Any]:
+    """What an .adg (rack) or .adv (device preset) contains, and which Live edition it needs."""
+    top = next(iter(root), None)
+    if top is None:
+        raise ValueError("Empty preset")
+    info = _preset_device(top) or device_info(top)
+    holder = top.find("Device")
+    top = holder[0] if holder is not None and len(holder) else top
+    macros = []
+    for i in range(16):
+        name = _v(top, f"MacroDisplayNames.{i}")
+        if name is None:
+            break
+        macros.append({"index": i, "name": name, "value": _f(top, f"MacroControls.{i}/Manual")})
+    devices = list(_walk_devices([info]))
+    tags = {d["type"] for d in devices}
+    needs = "Suite" if tags & SUITE_ONLY or any(d.get("max_for_live") for d in devices) else "Standard or Suite"
+    return {"device": info["name"], "type": info["type"], "macros": macros, "devices": info,
+            "plugins": sorted({d["name"] for d in devices if d.get("plugin")}),
+            "max_for_live": sorted({d["name"] for d in devices if d.get("max_for_live")}),
+            "needs_edition": needs, "created_with": root.get("Creator", "")}