lpx-toolkit 0.2.1

Read-only Logic Pro project inspector — extracts AU plugin manifest, tracks, and metadata from .logicx bundles.

lpx-toolkit

Inspect a Logic Pro project from the command line — see every plugin, track, and bit of metadata without opening Logic.

[!WARNING] Use at your own risk. lpx-toolkit parses an undocumented binary format that Apple may change at any time. It is strictly read-only — there is a SHA-256 invariant test that fails the build if any byte of a project is ever modified — but you are still pointing it at irreplaceable creative work. Always keep backups. The author accepts no liability for project corruption, data loss, or anything else that might go wrong.

$ lpxtool ~/Music/Logic/piano.logicx

Project:        piano
Created:        2024-02-29 20:23
Modified:       2024-03-01 13:55
Key:            C major
Time signature: 4/4
Tempo:          105 BPM
Tracks:         3

=== TRACKS (3 active) ===
   1. EZkeys 2  (Inst 1)  [instrument]
        Instrument: Toontrack: EZkeys 2 [aumu/EZk2/Toon]
   2. Scaler 2  (Inst 2)  [instrument]
        Instrument: Plugin Boutique: Scaler 2 [aumu/Scl2/eMai]
   3. Pigments  (Inst 3)  [instrument]
        Instrument: Arturia: Pigments [aumu/Kat1/Artu]

Why you might want this

• "Will this project open cleanly on this Mac?" The Inventory tab cross-references the project's plug-ins against your local AU registry. Missing plug-ins surface in a banner at the top before you ever launch Logic; every installed plug-in shows its version and signing authority.
• "Which plugins does this project need?" See the full plugin manifest up front.
• "Which of my installed plugins do I actually use?" Run --rollup across your whole library to find out.
• "What's in this project file?" Inspect tempo, key, track list, and FX chains for any project — even ones you can't open because a plugin is missing.
• Scripting and automation. Pipe --json into other tools, generate reports, audit project archives.

Requirements

• macOS
• Python 3.10 or newer
• A .logicx project to inspect

Install

The easiest route is uv — no clone, no venv, no install:

uvx lpx-toolkit ~/Music/Logic/SomeProject.logicx

uvx fetches the package from PyPI on first run and caches it; subsequent runs are instant. This is the Python equivalent of npx.

Prefer a permanent install? Use pipx:

pipx install lpx-toolkit
lpxtool ~/Music/Logic/SomeProject.logicx

Or via Homebrew for a system-wide install:

brew install rhydlewis/tap/lpxtool
lpxtool ~/Music/Logic/SomeProject.logicx

Or with plain pip in a virtual environment:

python3 -m venv .venv
.venv/bin/pip install lpx-toolkit
.venv/bin/lpxtool ~/Music/Logic/SomeProject.logicx

Both lpx-toolkit and lpxtool invoke the same tool — lpxtool is the shorter alias for typing once installed.

Usage

# Plain text report
lpxtool ~/Music/Logic/SomeProject.logicx

# Self-contained HTML dashboard (opens in your browser)
lpxtool --html ~/Music/Logic/SomeProject.logicx

# Browse your whole library in a local web app
lpxtool --serve ~/Music/Logic

# Structured JSON for piping into other tools
lpxtool --json ~/Music/Logic/SomeProject.logicx

# Audit plugin usage across many projects (opens browser)
lpxtool --rollup ~/Music/Logic/*.logicx

# Same audit as JSON, for scripting
lpxtool --rollup --json ~/Music/Logic/*.logicx

Run lpxtool --help for the full flag list.

HTML dashboard

--html produces a single self-contained HTML file with four tabs:

• Tracks — the registry-derived canonical track list, with kind, strip number, and region count per row.
• Plugin chains — every active strip's instrument and FX chain.
• Inventory — every Audio Unit installed on this Mac (auval -l data), cross-referenced against the current project. A red banner warns about plug-ins the project references but you don't have installed; each installed AU shows version, signing authority (parsed from codesign), and any installed .aupreset files.
• Diagnostics — phantom plug-ins (referenced from undo history but not on any active track), unresolved AUs, duplicate FX warnings.

The file lands in $TMPDIR/lpx-toolkit-<slug>.html and opens in your default browser. Use the ◐ toggle for light/dark mode (persists across reloads).

Library browser

--serve [DIR] starts a local-only HTTP server (bound to 127.0.0.1) and opens the index in your default browser. Click any project to view its dashboard, with the same look as --html. Defaults to ~/Music/Logic if DIR is omitted.

lpxtool --serve                       # browse ~/Music/Logic
lpxtool --serve --port 8080 ~/Music   # explicit port + directory

The index lists every project as a card with a chip row showing key, BPM, track count, bundle size, and modified time. Type into the search box (or press / to focus it) to filter the list — the query persists across reloads.

JSON endpoints are exposed for tooling: /api/projects, /api/projects/<index>, /api/rollup. Press Ctrl-C to stop the server.

JSON output

--json emits a structured payload (project metadata, per-track strip + plugin chain, vendor rollup). The schema is versioned via a top-level schema_version field (currently 1).

Cross-project rollup

--rollup aggregates plugin usage across many projects and opens the result in your browser. The view shows the most-used plug-ins, top manufacturers, and a clickable list of projects you can drill into.

lpxtool --rollup ~/Music/Logic/*.logicx

For scripting, add --json to dump the same data to stdout:

lpxtool --rollup --json ~/Music/Logic/*.logicx | jq '.fingerprints'

JSON shape: per-project summaries plus aggregated counts — fingerprints (how many projects each plug-in appears in) and vendors (total plug-in count per manufacturer). Unparseable projects are skipped with a warning to stderr; the rollup still completes.

You can also reach the rollup view via --serve: the library index links to /rollup for the directory you're browsing.

Caveats

• Not a live state read. A .logicx project retains references to plugins from undo history, alternative takes, and previously-deleted tracks. The output is "every plugin this project has ever referenced", not "what's loaded right now".
• Display names can truncate. Logic stores plugin names as ~11-character fields in the binary. Full names are recovered via auval when the plugin is installed.
• auval needs the plugins installed to resolve full names. Missing plugins still surface as a fingerprint — useful for "what do I need before opening this on another machine".
• Format is undocumented. Apple does not publish the .logicx internal format. Extraction relies on observed patterns and may need updates for future Logic versions.
• Read-only. This tool never writes to a .logicx file. There is no plan to ever support writing — the format is too risky to modify safely.

Privacy

Everything runs locally. Your projects never leave your machine. The only external commands invoked are auval -l (to resolve plug-in display names) and codesign -dv (to read each AU's signing authority for the Inventory tab). There is no telemetry, network call, or upload of any kind.

Cache files live under ~/.cache/lpx-toolkit/ (auval.json, au-bundles.json, au-presets.json, index.json). They are mtime-keyed and self-invalidating; delete the directory at any time to force a fresh scan.

Contributing

Bug reports, feature ideas, and PRs are all welcome. See CONTRIBUTING.md for development setup and the areas where help is wanted.

Licence

MIT — see LICENSE.