Metadata-Version: 2.4
Name: lpx-toolkit
Version: 0.2.0
Summary: Read-only Logic Pro project inspector — extracts AU plugin manifest, tracks, and metadata from .logicx bundles.
Author: Rhyd Lewis
License-Expression: MIT
Project-URL: Homepage, https://github.com/rhydlewis/lpx-toolkit
Project-URL: Repository, https://github.com/rhydlewis/lpx-toolkit
Project-URL: Issues, https://github.com/rhydlewis/lpx-toolkit/issues
Keywords: logic-pro,audio-units,music-production,macos
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Sound/Audio :: Editors
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# lpx-toolkit

[![tests](https://github.com/rhydlewis/lpx-toolkit/actions/workflows/test.yml/badge.svg)](https://github.com/rhydlewis/lpx-toolkit/actions/workflows/test.yml)

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.

![lpx-toolkit HTML dashboard](lpxtool.png)

```
$ 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`](https://docs.astral.sh/uv/) — no clone, no venv, no install:

```sh
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`](https://pipx.pypa.io/):

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

Or via [Homebrew](https://brew.sh) for a system-wide install:

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

Or with plain `pip` in a virtual environment:

```sh
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

```sh
# 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.

```sh
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.

![lpx-toolkit rollup view](rollup.png)

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

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

```sh
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`](CONTRIBUTING.md) for development setup and the areas where help is wanted.

## Licence

MIT — see `LICENSE`.
