logicxkit 0.1.0__py3-none-any.whl

logicxkit/__init__.py

@@ -0,0 +1,18 @@
+"""logicxkit — tools for Logic Pro projects, channel strips and Audio Unit state.
+
+Subpackages:
+- ``logicxkit.logic``  — Logic Pro channel-strip (.cst) build/decode, .logicx analysis.
+- ``logicxkit.au``     — 3rd-party plugin presets/states via a headless AU host.
+- ``logicxkit.logicx`` — the .logicx container format; a leaf both logic and au read through.
+
+A pf-core consumer (foundation tier). Each gear domain owns a subpackage; ``logicxkit.utils``
+and ``logicxkit.logicx`` are support leaves (only what ≥2 domains actually call). The
+subpackage import graph is a DAG — enforced by tests/test_package_layering.py.
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _version
+
+try:
+    __version__ = _version("logicxkit")
+except PackageNotFoundError:      # a source tree that was never installed
+    __version__ = "0+unknown"

logicxkit/au/__init__.py

@@ -0,0 +1,16 @@
+"""logicxkit.au — Audio Unit preset/state intelligence (read-only).
+
+Decodes plugin settings wherever Logic or the plugin stores them: standalone
+.aupreset / .ffp preset files, and AU ClassInfo plists embedded in .cst strips
+and .logicx ProjectData. Static parsers cover FabFilter/classic-AU parameter
+tables and Waves XPst; the AU host (vendored Swift probe) instantiates the real
+plugin headless for named, UI-formatted values of everything else.
+"""
+
+from logicxkit.au.services.aupreset import AuState, parse_au_state  # noqa: F401
+from logicxkit.au.services.embed import find_au_plists, fourcc  # noqa: F401
+from logicxkit.au.services.ffp import FfpError, FfpPreset, parse_ffp  # noqa: F401
+from logicxkit.au.services.host import (  # noqa: F401
+    AuDump, AuHost, AuHostError, AuParam, is_headless_safe,
+)
+from logicxkit.au.services.waves import extract_xpst  # noqa: F401

logicxkit/au/_views.py

@@ -0,0 +1,74 @@
+"""Terminal rendering for au decode results (data assembly lives in services)."""
+
+from __future__ import annotations
+
+
+def _fmt_value(row: dict) -> str:
+    if row.get("display"):
+        return row["display"]
+    unit = f" {row['unit']}" if row.get("unit") and row["unit"] != "generic" else ""
+    return f"{row['value']:.4g}{unit}"
+
+
+def _fmt_rows(params: list[dict], all_rows: bool) -> list[str]:
+    rows = params if all_rows else [r for r in params if r.get("changed")]
+    lines = []
+    for r in rows:
+        dflt = "" if r.get("default") is None else f"  (default {r['default']:.4g})"
+        lines.append(f"  [{r['id']:>5}] {r['name']:<44} = {_fmt_value(r)}{dflt}")
+    if not all_rows and len(rows) < len(params):
+        lines.append(f"  … {len(params) - len(rows)} more at default (--all to show)")
+    return lines
+
+
+def _header(out: dict) -> str:
+    plug = out["plugin"]
+    comp = plug.get("component") or f"{plug['manufacturer']}/{plug['subtype']}"
+    name = f"  preset {out['preset_name']!r}" if out.get("preset_name") else ""
+    return f"{comp} ({plug['manufacturer']}/{plug['subtype']}){name}  [{out['decode_path']}]"
+
+
+def format_preset(out: dict, all_rows: bool) -> str:
+    lines = [_header(out)]
+    if out.get("host_error"):
+        lines.append(f"  ! AU host failed, static fallback: {out['host_error']}")
+    if out.get("neural"):
+        n = out["neural"]
+        secs = ", ".join(f"{k}({len(v)})" for k, v in n.get("sections", {}).items())
+        lines.append(f"  Neural DSP state [{n['format']}]: {secs}")
+        lines.append("  (full knob detail: logicxkit logic neural)")
+    if out.get("sonible"):
+        s = out["sonible"]
+        lines.append(f"  sonible protobuf fields (unnamed; plugin {s.get('plugin')!r}):")
+        for k, v in s["fields"].items():
+            if isinstance(v, dict):
+                inner = "  ".join(f"{ik}={iv}" for ik, iv in v.items())
+                lines.append(f"    msg {k}: {inner}")
+            else:
+                lines.append(f"    {k} = {v}")
+    if out.get("tr5"):
+        t = out["tr5"]
+        lines.append(f"  TR5 chain (current preset: {t.get('current_preset')})")
+        for snap in t["snapshots"]:
+            active = [s for s in snap["slots"] if s.get("bypass") != "1"]
+            lines.append(f"    snapshot {snap['snapshot']}: {len(active)} active module(s)")
+            for s in active:
+                params = "  ".join(f"{k}={v}" for k, v in list(s["params"].items())[:8])
+                lines.append(f"      {s['slot']} [{(s.get('guid') or '?')[:8]}]  {params}")
+    lines.extend(_fmt_rows(out.get("params", []), all_rows))
+    if not out.get("params") and out.get("blobs"):
+        blobs = ", ".join(f"{k} ({v}B)" for k, v in out["blobs"].items())
+        lines.append(f"  opaque state blobs: {blobs}")
+    return "\n".join(lines)
+
+
+def format_strip(states: list[dict], all_rows: bool) -> str:
+    if not states:
+        return "no embedded 3rd-party AU states found"
+    chunks = []
+    for st in states:
+        where = f"@{st.get('offset', '?')}"
+        if st.get("channel"):
+            where += f"  {st['channel']}"
+        chunks.append(f"— {where}\n" + format_preset(st, all_rows))
+    return "\n\n".join(chunks)

logicxkit/au/cli.py

@@ -0,0 +1,94 @@
+"""au CLI — decode plugin presets and embedded strip states.
+
+    logicxkit au preset <file>                 .ffp / .aupreset / .pst / extracted .plist
+    logicxkit au strip  <file.cst|Song.logicx> every embedded 3rd-party state
+    logicxkit au params <type> <subtype> <manu>  live AU parameter table (needs swift)
+    logicxkit au tables                        list the AU parameter tables in the data root
+
+Decode ladder per state: NDSP -> JUCE decoders, Waves -> static XPst, else the
+headless AU host (--no-host to force the static table join).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from logicxkit.au._views import format_preset, format_strip
+from logicxkit.au.services.host import AuHost
+from logicxkit.au.services.report import decode_preset_bytes, decode_strip_path
+from logicxkit.au.services.tables import available_tables
+
+
+def _host_or_none(args) -> AuHost | None:
+    if args.no_host or not AuHost.available():
+        return None
+    return AuHost()
+
+
+def _emit(payload, text: str, as_json: bool) -> int:
+    print(json.dumps(payload, indent=2) if as_json else text)
+    return 0
+
+
+def cmd_preset(args) -> int:
+    p = Path(args.file).expanduser()   # every real preset lives under ~/Library or ~/Music
+    out = decode_preset_bytes(p.read_bytes(), suffix=p.suffix.lower(),
+                              host=_host_or_none(args), name_hint=p.stem)
+    return _emit(out, format_preset(out, args.all), args.json)
+
+
+def cmd_strip(args) -> int:
+    states = decode_strip_path(args.file, host=_host_or_none(args))
+    return _emit(states, format_strip(states, args.all), args.json)
+
+
+def cmd_params(args) -> int:
+    dump = AuHost().list_params(args.type, args.subtype, args.manufacturer)
+    payload = {"component": dump.component, "params": [vars(p) for p in dump.params]}
+    text = "\n".join(f"[{p.id:>5}] {p.name:<44} {p.unit:<8} "
+                     f"{p.min:.4g}..{p.max:.4g} (default {p.default:.4g})"
+                     for p in dump.params)
+    return _emit(payload, f"{dump.component} — {len(dump.params)} params\n{text}", args.json)
+
+
+def cmd_tables(args) -> int:
+    names = available_tables()
+    print("\n".join(names) if names else "no tables checked in")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="logicxkit au", description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    def common(p):
+        p.add_argument("--all", action="store_true", help="show unchanged params too")
+        p.add_argument("--json", action="store_true")
+        p.add_argument("--no-host", action="store_true",
+                       help="skip the AU host; static decode only")
+
+    p = sub.add_parser("preset", help="decode a preset file")
+    p.add_argument("file")
+    common(p)
+    p.set_defaults(fn=cmd_preset)
+
+    p = sub.add_parser("strip", help="decode embedded states in a .cst/.pst/.logicx")
+    p.add_argument("file")
+    common(p)
+    p.set_defaults(fn=cmd_strip)
+
+    p = sub.add_parser("params", help="live AU parameter table")
+    p.add_argument("type")
+    p.add_argument("subtype")
+    p.add_argument("manufacturer")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(fn=cmd_params)
+
+    p = sub.add_parser("tables", help="list the AU parameter tables in the data root")
+    p.set_defaults(fn=cmd_tables)
+
+    args = ap.parse_args(argv)
+    return args.fn(args)

logicxkit/au/services/aupreset.py

@@ -0,0 +1,54 @@
+"""AU ClassInfo dicts (.aupreset files and .cst/.logicx-embedded plists) -> typed state.
+
+Two state shapes appear in the wild:
+
+- the AU-standard ``data`` key — 12B header (8 reserved bytes + u32 BE pair
+  count) + (u32 BE param id, f32 BE value) pairs. Classic FabFilter plugins
+  (Pro-C 2, Pro-MB) store their whole state here; param ids match .ffp
+  positions.
+- vendor blob keys (``FabFilterPluginState``, ``jucePluginState``,
+  ``Waves_XPst``, ``Line6PresetData``, …) — kept raw for the specialist
+  decoders or the AU host.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+from logicxkit.au.services.embed import fourcc
+
+_IDENTITY_KEYS = ("type", "subtype", "manufacturer", "version", "name", "data")
+
+
+@dataclass(frozen=True)
+class AuState:
+    type: str
+    subtype: str
+    manufacturer: str
+    name: str | None
+    param_pairs: list[tuple[int, float]] | None
+    blobs: dict[str, bytes]
+
+
+def _parse_pairs(blob: bytes) -> list[tuple[int, float]] | None:
+    if len(blob) < 12:
+        return None
+    count = struct.unpack_from(">I", blob, 8)[0]
+    if len(blob) != 12 + 8 * count:
+        return None
+    return [struct.unpack_from(">If", blob, 12 + 8 * i) for i in range(count)]
+
+
+def parse_au_state(plist: dict) -> AuState:
+    data = plist.get("data")
+    name = plist.get("name")
+    return AuState(
+        type=fourcc(plist.get("type", 0)),
+        subtype=fourcc(plist.get("subtype", 0)),
+        manufacturer=fourcc(plist.get("manufacturer", 0)),
+        name=name if isinstance(name, str) else None,
+        param_pairs=_parse_pairs(data) if isinstance(data, bytes) else None,
+        blobs={k: v for k, v in plist.items()
+               if isinstance(v, bytes) and k not in _IDENTITY_KEYS},
+    )

logicxkit/au/services/embed.py

@@ -0,0 +1,37 @@
+"""Embedded AU state scanning — Logic stores 3rd-party plugin state as raw XML
+plists inside its binaries (identically in ``.cst`` files and ``.logicx``
+``ProjectData``). Each plist is a full AU ClassInfo dict: identity fourccs
+(``type``/``subtype``/``manufacturer``), preset ``name``, and the state itself
+(``data`` pairs and/or vendor blob keys)."""
+
+from __future__ import annotations
+
+import plistlib
+import struct
+
+
+def find_au_plists(data: bytes) -> list[tuple[int, dict]]:
+    """Every embedded XML plist that parses to a dict, as ``(offset, plist)``."""
+    out: list[tuple[int, dict]] = []
+    pos = 0
+    while True:
+        i = data.find(b"<?xml", pos)
+        if i < 0:
+            break
+        end = data.find(b"</plist>", i)
+        if end < 0:
+            break
+        try:
+            pl = plistlib.loads(data[i : end + len(b"</plist>")])
+        except Exception:
+            pos = i + len(b"<?xml")
+            continue
+        if isinstance(pl, dict):
+            out.append((i, pl))
+        pos = end + len(b"</plist>")
+    return out
+
+
+def fourcc(n: int) -> str:
+    s = struct.pack(">I", n & 0xFFFFFFFF).decode("latin-1")
+    return s if s.isascii() and s.isprintable() else f"0x{n:08X}"

logicxkit/au/services/ffp.py

@@ -0,0 +1,41 @@
+"""FabFilter ``.ffp`` preset files.
+
+Layout (verified against Pro-C 2 / Pro-L / Pro-MB / Pro-Q 2 factory presets):
+4CC magic (``FC2p``, ``FPLr``, ``FPMb``, …) + u32 LE version + u32 LE param
+count + count × float32 LE. Param position i corresponds to AU parameter id i
+of the same plugin, so the AU parameter table names every value.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+_MAX_PARAMS = 8192  # sanity bound: real plugins top out in the hundreds
+
+
+class FfpError(ValueError):
+    """Not a parseable .ffp file."""
+
+
+@dataclass(frozen=True)
+class FfpPreset:
+    magic: str
+    version: int
+    values: tuple[float, ...]
+
+
+def parse_ffp(data: bytes) -> FfpPreset:
+    if len(data) < 12:
+        raise FfpError("too short for an .ffp header")
+    magic = data[:4]
+    if not all(32 <= b < 127 for b in magic):
+        raise FfpError(f"implausible magic {magic!r}")
+    version, count = struct.unpack_from("<II", data, 4)
+    if count > _MAX_PARAMS:
+        raise FfpError(f"implausible param count {count}")
+    need = 12 + 4 * count
+    if len(data) < need:
+        raise FfpError(f"truncated value table: need {need}B, have {len(data)}B")
+    values = struct.unpack_from(f"<{count}f", data, 12)
+    return FfpPreset(magic.decode("ascii"), version, values)

logicxkit/au/services/host.py

@@ -0,0 +1,108 @@
+"""Headless AU introspection via the vendored Swift probe (``logicxkit/native/auprobe.swift``).
+
+The probe instantiates an installed Audio Unit, optionally restores a preset /
+ClassInfo plist (kAudioUnitProperty_ClassInfo), and prints one JSON document:
+component identity plus every parameter with name, unit, min/max/default,
+current value, and the UI-formatted display string
+(kAudioUnitProperty_ParameterStringFromValue). This wrapper shells out and
+parses; everything degrades to the static decoders when Swift or the AU is
+absent.
+
+Some AUs crash when instantiated without a UI host — denylisted from batch
+decodes via :func:`is_headless_safe` (Waves state decodes statically in
+``waves.py`` instead; sonible state is a protobuf ``jucePluginState``).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from logicxkit.utils.swiftrun import SwiftRunError, run_swift, swift_available
+
+# Observed crashes: sonible (dyld abort), Waves (WaveShell objc class collision).
+_HEADLESS_UNSAFE = {"Soni", "ksWV"}
+_TIMEOUT_S = 120
+
+
+class AuHostError(RuntimeError):
+    """The probe failed: missing toolchain/component, crash, or bad output."""
+
+
+def is_headless_safe(manufacturer_cc: str) -> bool:
+    return manufacturer_cc not in _HEADLESS_UNSAFE
+
+
+def auprobe_path() -> Path:
+    return Path(__file__).resolve().parents[4] / "native" / "auprobe.swift"
+
+
+@dataclass(frozen=True)
+class AuParam:
+    id: int
+    name: str
+    unit: str
+    min: float
+    max: float
+    default: float
+    value: float | None = None
+    display: str | None = None
+
+
+@dataclass(frozen=True)
+class AuDump:
+    component: str
+    type: str
+    subtype: str
+    manufacturer: str
+    params: tuple[AuParam, ...]
+
+    def changed_params(self, eps: float = 1e-6) -> list[AuParam]:
+        return [p for p in self.params
+                if p.value is not None and abs(p.value - p.default) > eps]
+
+
+def _default_runner(args: list[str], timeout: float) -> tuple[int, str, str]:
+    try:
+        return run_swift(Path(args[0]), list(args[1:]), timeout)
+    except SwiftRunError as e:
+        raise AuHostError(str(e)) from e
+
+
+class AuHost:
+    def __init__(self, runner=None, timeout: float = _TIMEOUT_S):
+        self._runner = runner or _default_runner
+        self._timeout = timeout
+
+    @staticmethod
+    def available() -> bool:
+        return swift_available() and auprobe_path().exists()
+
+    def dump_preset(self, plist_path: str | Path) -> AuDump:
+        """Instantiate the AU named inside the plist, restore it, dump values."""
+        return self._invoke(["preset", str(plist_path)])
+
+    def list_params(self, type_cc: str, subtype_cc: str, manu_cc: str) -> AuDump:
+        """Parameter table (names/units/ranges/defaults) without preset state."""
+        return self._invoke(["list", type_cc, subtype_cc, manu_cc])
+
+    def _invoke(self, args: list[str]) -> AuDump:
+        rc, out, err = self._runner([str(auprobe_path()), *args], self._timeout)
+        if rc != 0:
+            tail = (err or out).strip().splitlines()
+            raise AuHostError(tail[-1] if tail else f"probe exited {rc}")
+        start = out.find("{")
+        if start < 0:
+            raise AuHostError(f"unparseable probe output: {out[:120]!r}")
+        try:
+            d = json.loads(out[start:])
+        except json.JSONDecodeError as e:
+            raise AuHostError(f"bad probe JSON: {e}") from e
+        params = tuple(
+            AuParam(id=p["id"], name=p["name"], unit=p["unit"], min=p["min"],
+                    max=p["max"], default=p["default"],
+                    value=p.get("value"), display=p.get("display"))
+            for p in d["params"])
+        return AuDump(component=d["component"], type=d["type"], subtype=d["subtype"],
+                      manufacturer=d["manufacturer"], params=params)

logicxkit/au/services/juce.py

@@ -0,0 +1,164 @@
+"""JUCE plugin-state decode — what AU plugins put in ``jucePluginState``.
+
+Two container shapes, vendor-independent: an XML document wrapped by ``copyXmlToBinary``,
+or a binary ValueTree. Extraction-only; writing state back is out of scope.
+"""
+
+from __future__ import annotations
+
+import struct
+import xml.etree.ElementTree as ET
+
+from logicxkit.au.services.embed import fourcc
+
+_MAX_NODES = 4096  # sanity bound so garbage never parses as a huge ValueTree
+
+
+def decode_juce_xml(state: bytes) -> str | None:
+    """Unwrap a JUCE ``copyXmlToBinary`` container; None if it isn't one."""
+    if len(state) < 8 or not state.startswith(b"VC2!"):
+        return None
+    n = struct.unpack_from("<I", state, 4)[0]
+    return state[8 : 8 + n].rstrip(b"\x00").decode("utf-8", "replace")
+
+
+# ---- JUCE binary ValueTree ------------------------------------------------------------
+
+def _read_string(data: bytes, pos: int) -> tuple[str, int]:
+    end = data.index(b"\x00", pos)
+    return data[pos:end].decode("utf-8"), end + 1
+
+
+def _read_cint(data: bytes, pos: int) -> tuple[int, int]:
+    n = data[pos]
+    pos += 1
+    if n == 0:
+        return 0, pos
+    if n > 8 or pos + n > len(data):
+        raise ValueError("not a JUCE compressed int")
+    return int.from_bytes(data[pos : pos + n], "little"), pos + n
+
+
+def _read_var(data: bytes, pos: int):
+    size, pos = _read_cint(data, pos)
+    if size == 0:
+        return None, pos
+    kind, payload = data[pos], data[pos + 1 : pos + size]
+    pos += size
+    if kind == 1:
+        return struct.unpack("<i", payload)[0], pos
+    if kind == 2:
+        return True, pos
+    if kind == 3:
+        return False, pos
+    if kind == 4:
+        return struct.unpack("<d", payload)[0], pos
+    if kind == 5:
+        return payload.rstrip(b"\x00").decode("utf-8", "replace"), pos
+    if kind == 6:
+        return struct.unpack("<q", payload)[0], pos
+    if kind == 8:
+        return payload, pos  # binary blob (e.g. TR5's Chain XML) — caller decodes
+    return None, pos  # unknown var kind: skip payload, keep parsing
+
+
+def _read_tree(data: bytes, pos: int) -> tuple[dict, int]:
+    type_, pos = _read_string(data, pos)
+    if not type_ or not type_[0].isascii() or not type_.isprintable():
+        raise ValueError(f"implausible ValueTree type {type_!r}")
+    nprops, pos = _read_cint(data, pos)
+    if nprops > _MAX_NODES:
+        raise ValueError("implausible prop count")
+    props = {}
+    for _ in range(nprops):
+        name, pos = _read_string(data, pos)
+        props[name], pos = _read_var(data, pos)
+    nkids, pos = _read_cint(data, pos)
+    if nkids > _MAX_NODES:
+        raise ValueError("implausible child count")
+    children = []
+    for _ in range(nkids):
+        child, pos = _read_tree(data, pos)
+        children.append(child)
+    return {"type": type_, "props": props, "children": children}, pos
+
+
+def parse_value_tree(state: bytes) -> dict | None:
+    """Parse a JUCE binary ValueTree to ``{type, props, children}``; None on garbage."""
+    try:
+        tree, _ = _read_tree(state, 0)
+        return tree
+    except (ValueError, IndexError, struct.error, UnicodeDecodeError):
+        return None
+
+
+# ---- state -> meta/sections -----------------------------------------------------------
+
+def _convert(v: str):
+    if v == "true":
+        return True
+    if v == "false":
+        return False
+    try:
+        return int(v)
+    except ValueError:
+        try:
+            return float(v)
+        except ValueError:
+            return v
+
+
+def _xml_sections(xml_text: str) -> tuple[dict, dict]:
+    """Root attrs -> meta; every attributed descendant element -> a section by tag."""
+    root = ET.fromstring(xml_text)
+    meta = {k: _convert(v) for k, v in root.attrib.items()}
+    sections: dict[str, dict] = {}
+    for el in root.iter():
+        if el is root or not el.attrib:
+            continue
+        sections.setdefault(el.tag, {}).update(
+            {k: _convert(v) for k, v in el.attrib.items()})
+    return meta, sections
+
+
+def _tree_sections(root: dict) -> tuple[dict, dict]:
+    """Root + descendant metadata props -> meta; PARAM id/value children -> params."""
+    meta = dict(root["props"])
+    params: dict = {}
+
+    def walk(node: dict) -> None:
+        if node["type"] == "PARAM":
+            pid = node["props"].get("id")
+            if pid is not None:
+                params[pid] = node["props"].get("value")
+            return
+        for k, v in node["props"].items():
+            meta.setdefault(k, v)
+        for child in node["children"]:
+            walk(child)
+
+    for child in root["children"]:
+        walk(child)
+    return meta, {"params": params}
+
+
+def state_from_plist(pl: dict) -> dict | None:
+    """Decode one AU ClassInfo plist's ``jucePluginState``; None if undecodable."""
+    state = pl.get("jucePluginState")
+    if not isinstance(state, bytes):
+        return None
+    xml_text = decode_juce_xml(state)
+    if xml_text is not None:
+        try:
+            meta, sections = _xml_sections(xml_text)
+        except ET.ParseError:
+            return None
+        fmt = "xml"
+    else:
+        tree = parse_value_tree(state)
+        if tree is None:
+            return None
+        meta, sections = _tree_sections(tree)
+        fmt = "tree"
+    return {"subtype": fourcc(pl.get("subtype", 0)),
+            "format": fmt, "meta": meta, "sections": sections}