abletoolz 2.0.0__tar.gz → 2.1.0__tar.gz

{abletoolz-2.0.0 → abletoolz-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: abletoolz
-Version: 2.0.0
+Version: 2.1.0
 Summary: Tools made for editing, fixing and analyzing Ableton Live sets.
 Author: ElixirBeats
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -707,23 +707,24 @@ Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
 Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: types-colorama; extra == "dev"
+Requires-Dist: types-tqdm; extra == "dev"
 Dynamic: license-file
 
 ![Abletoolz](https://github.com/elixirbeats/abletoolz/raw/master/doc/gradient.png)
 # Abletoolz
 
-Abletoolz is a Python command line tool to edit, fix and analyze Ableton Live sets. Primarily the purpose is to
-automate things that aren't available in Live and make your life easier.
+Abletoolz is a command line tool to edit, fix and analyze Ableton Live sets. Primarily the purpose is
+to automate things that aren't available in Live and make your life easier. It is also a Python library —
+if you write Python, jump down to [Using as a library](#using-as-a-library).
 It can:
 - Run on one set, or an entire directory of sets. So you can fix/analyze everything with one command.
 - Color all your tracks/clips with random color gradients.
 - Create a sample database of all your sample folders, which can then be used to automatically fix any broken samples in your ableton sets.
 - Set all your Master/Cue outputs to a specific output, so if you buy a new audio interface you can fix all your master outs to point to 7/8 in one go.
-- Validate all plugins in a set are installed. MacOS VST3s currently do not work for this.
-- Analyze plugin state with plugin-specific parsers, and fix what they understand (Serato Sample's missing sample paths, for a start).
+- Validate all plugins in a set are installed.
+- Analyze plugin state with plugin-specific parsers, and fix what they understand — like sample paths inside a plugin's saved state that no longer exist on disk. `--list-parsers` shows what's registered.
 - Fold/Unfold all tracks, and/or set track height and widths.
-- Prepend the set version name to the beginning of the file.
-- Append the number of bars of the track, and the bpm to the end of the file.
 - Dump the XML of the set, in case you want to dissect how they are structured or contribute to this project : )
 
 It also:
@@ -732,6 +733,27 @@ It also:
 - Works on sets from Ableton 8.2 through Live 12, including current Live 12 betas (not every command works with the oldest versions).
 - Preserves the original set modification time.
 
+## What's new in 2.1
+
+- **Repair plugins Live can no longer load.** `--repair-plugins` rewrites dead VST2 devices as the VST3 you
+  have installed and brings the saved patch along, so an old set comes back with its settings instead of
+  blank devices. You decide what becomes what: `--suggest-plugin-mappings` drafts that table from the
+  plugins on your machine and `--plugin-db` scans them once so it's quick.
+- **Every run writes down what it found.** Each set gets a `.meta.yaml` sidecar — Live version, bars, bpm,
+  what was missing, what was fixed — with `status` and `notes` fields that are yours to fill in and are
+  never overwritten. Each run also writes a JSON report of everything it did. The sidecar doubles as a
+  cache, so scanning a big library a second time is much faster, and `--output` keeps it all in a folder
+  of your choosing instead of next to your sets.
+- **Plugin checks work properly on macOS.** VST3s are found as bundles and Audio Units are matched by their
+  component identity, so a plugin that moved or got renamed is still found.
+- **A lot more you can do from Python.** `AbletonSet` picked up `clips` and `devices`, so writing MIDI notes,
+  copying a section of the arrangement and grafting a device chain from one set onto another are all
+  possible now. See [Using as a library](#using-as-a-library).
+- **More sampler parsers**, so more plugins can have the broken sample and kit paths inside their own saved
+  state found and fixed. `--list-parsers` shows the current roster.
+- `--append-bars-bpm` and `--prepend-version` are deprecated — they still work, but the bars, bpm and Live
+  version now land in each set's sidecar without renaming your files.
+
 ## What's new in 2.0
 
 - **Live 12 support.** Live 12 renamed core elements (`MasterTrack` → `MainTrack`, and it finally fixed the
@@ -746,7 +768,6 @@ It also:
   projects: a set full of dead 32-bit plugins can be retargeted at the modern versions you actually have
   installed, and where a translator exists for the plugin's state format, your old settings come along instead
   of being lost. It can even translate one plugin into a different one once someone decodes both formats.
-  Serato Sample is the first supported parser (finds and fixes its broken sample paths).
 - **Safer saves.** Sets are serialized before anything on disk is touched — a failure can no longer leave you
   without your original file (which was always backed up, but still).
 - **Honest batch results.** Directory runs process sets concurrently (`--jobs`), report `N ok, M failed`, and
@@ -775,9 +796,10 @@ Once you verify you have python 3.12+, install with pip:
 pip install abletoolz
 ```
 This will install abletoolz as a command in your command line, you can now call `abletoolz` from anywhere if the
-installation completed successfully. (Create an issue if you run into any errors please!)
+installation completed successfully, but make sure to open a new shell before trying.
 
 ## Usage:
+
 `-h` Print argument usage.
 `-v` Verbosity. For some commands, displays more information.
 
@@ -808,15 +830,15 @@ without quotes, backslashes are fine (but you'll need to use quotes if you have
 sample as long as one of the two are valid. If relative path doesn't exist(Not collected and saved) only absolute path
 is checked. By default only missing samples are displayed to reduce clutter, use `-v` to show all found samples as well.
 
-`--check-plugins` Checks plugin VST paths and verifies they exist. **Note**: When loading a set, if Ableton finds the
+`--check-plugins` Checks installed VST and Audio Unit references. **Note**: When loading a set, if Ableton finds the
 same plugin name in a different path it will automatically fix any broken paths the next time you save your project. This
 command attempts to find missing VSTs and show an updated path if it finds one that Ableton will most likely load.
-Mac Audio Units/AU are not stored with paths, just plugin names. Mac OS is not supported for this yet.
 ```
 [MidiTrack: 1-Serum] Plugin: Serum_x64.dll, Path: C:\Program Files\VstPlugins\Xfer\Serum_x64.dll, Exists: True
 [AudioTrack: 2-Audio] Plugin: Effectrix.dll, Path: C:\Program Files\VstPlugins\Effectrix.dll, Exists: True
 [AudioTrack: 3-Audio] Plugin: DrumLeveler.dll, Path: None, Exists: False
-Mac OS Audio Units are not saved with paths. Plugin FabFilter: FF Pro-Q 2 cannot be verified.
+[AudioTrack: 4-Audio] Plugin: Apple: AUBandpass, Path: None, Exists: True
+[MidiTrack: 5-MIDI] Plugin: Arturia: Analog Lab V, Path: /Library/Audio/Plug-Ins/Components/Analog Lab V.component, Exists: True
 ```
 
 `--list-tracks` List track information.
@@ -832,17 +854,58 @@ Track type  ReturnTrack, Name   A-Reverb, Id    2, Group id   -1, Color  60, Wid
 
 Plugin state inside a set is an opaque buffer per plugin; parsers teach abletoolz specific formats.
 
+Only a handful of plugins are covered currently, so out of the box this won't fix your sets.. but the value is in the framework being able to manipulate those plugin buffers/shapes easily so it is possible to reverse engineer and recover old sets or turn them into newer plugins even. This depends entirely on if you'll be able to decode the buffer. Once you figure out the format (and I recommend using agents to help you do this), from then on every device of that plugin across every set you own is fixable
+with one command. Old collections tend to be broken by the same few plugins over and over, so each one
+cracked recovers sets in bulk.
+
 `--list-parsers` List registered plugin parsers and their buffer formats.
 
-`--analyze-plugins` Deep analysis using the registered parsers — reports issues like missing samples inside
-Serato Sample instances.
+`--analyze-plugins` Deep analysis using the registered parsers — reports issues like sample or kit
+references inside a plugin's state that are no longer on disk.
 
-`--fix-plugins` Fix what a parser knows how to fix (e.g. broken sample paths inside Serato Sample), using the
-sample database. Use with `-s` to write changes.
+`--fix-plugins` Fix what a parser knows how to fix — typically broken sample paths inside a plugin's
+state — using the sample database. Use with `-s` to write changes.
 
 `--upgrade-plugins` Upgrade plugin paths when a rule and an installed target exist. Rules live in a config file
 so nothing is guessed.
 
+`--repair-plugins` Replace the plugin devices Live can no longer load with what your mappings say they
+become, keeping the patch they were saved with. A device that still loads is left alone, and a broken device
+with no mapping is reported by name rather than guessed at. Use with `-s` to write changes.
+
+There is no format to choose on the command line, because the mapping says which way each plugin goes:
+
+```yaml
+plugin_translation:
+  targets:
+    "Some Plugin.64":       # the name the VST2 device stores
+      to: vst3              # the format it becomes (this is the default)
+      name: "Some Plugin"   # the name the VST3 goes by
+      state: verbatim       # or a named state policy a parser provides
+```
+
+`--plugin-db` Scan every plugin installed on this machine into a local plugin database — the plugin half of
+`--db`. `--repair-plugins` and `--suggest-plugin-mappings` read it, so run this once first (and again after
+installing plugins). Takes no set and no folders; add folders under `plugin_database.paths` in your config,
+the way `sample_database.paths` works.
+
+```yaml
+plugin_database:
+  paths:
+    - "D:/VstPlugins"
+```
+
+`--suggest-plugin-mappings [file.yaml]` Write that mapping table for you, or most of it. It takes no set: it
+pairs the names that look like the same plugin in two formats and writes a YAML file for you to read. Every
+suggestion aims at something you actually have installed; where nothing can perform a translation yet, it
+says so.
+
+**Everything it writes comes out commented, including the suggestions that look certain.** Uncommenting a
+line is how you enable it, and that is meant to be a decision you make one plugin at a time. Each line says
+how sure the match is and flags the ones to watch — a version change that won't load the old patch, or two
+plugins whose names agree and whose vendors do not, which is a different plugin wearing a familiar name.
+Nothing is in force until you move a line into your own config file, which this never touches.
+
 `--dump-plugins` Dump plugin buffer hex + decoded preview — the starting point for writing a new parser.
 Contributions welcome.
 
@@ -919,12 +982,39 @@ development. You can edit this xml file, rename it from `.xml` to  `.als` and Ab
 option multiple times, the previous xml file will be moved into the `abletoolz_backup`
 folder with the same renaming behavior as `-s/--save`.
 
-`--append-bars-bpm` Used with `-s/--save`, appends the longest clip or furthest arrangement bar length and bpm to the
-set name. For example,
-`myset.als` --> `myset_32bars_90bpm.als`. Running this multiple times overwrites this section only (so your filename
-wont keep growing).
+### Records - what a run writes down
+
+Runs also save their results to files, so you can look back later or process them with other tools.
+
+**Per-set sidecars.** Any run that checks or fixes plugins or samples leaves a `<set name>.meta.yaml` beside
+each set it looked at: the Live version, bars and bpm, the missing plugins by device count, what was fixed,
+the missing samples, and the hash of the set as it was read. Underneath there are two fields that are yours —
+`status` and `notes` — plus anything else you care to add. abletoolz reads them, carries them across every
+rescan and never writes them itself.
+```yaml
+status: needs work
+notes: reverb tail runs long in the breakdown
+scan:
+  scanned: '2026-08-17T10:16:07.959317-07:00'
+  scanned_with: abletoolz 2.0.0
+  set_hash: 499af899b43a5ad850688c93ddbdeaae30602101fc005f7d2a7adec1e329eea9
+  live_version: Ableton Live 11.3.42
+  bars: 128
+  bpm: 174.0
+  plugins_missing:
+    Serum_x64: 2
+  samples_missing: 3
+```
+The sidecar also acts as a cache: if a set hasn't changed since the last scan, the run reuses the stored
+results and prints `Cached`, which makes a second pass over a big library much faster. Edit the set and it
+gets scanned again from scratch. `--no-meta` turns the whole thing off.
 
-`--prepend-version` Puts the ableton version used to create set at beginning of file name.
+**Run reports.** Every run writes `abletoolz_report_<timestamp>.json` into the folder it processed: one
+record per set (what changed, what was fixed, what was missing, what was refused and why, what failed to
+parse), plus totals for the whole run — like every missing plugin across your library with counts. Useful
+when you want to script against results instead of reading console output.
+
+With `--output`, both land in the output folder instead. Nothing is written next to the originals.
 
 ## Examples
 Check all samples in sets
@@ -967,35 +1057,136 @@ Saved set to D:\all_sets\myset.als
 Took 0:00:00.371096 to process 1 set(s): 1 ok, 0 failed
 ```
 
+## Using as a library
+
+abletoolz started life as a command line tool, but the more powerful way to use it now is as a Python
+library. The command line above is this library pointed at a whole collection. A set is an object: open
+one, read what is in it, change it, save it or create one from scratch. `AbletonSet` is the
+document, and what a set holds hangs off it as `transport`, `tracks`, `clips`, `devices`, `samples` and
+`plugins`. Nothing reaches disk until you call `save_set()`, which moves the original into the backup
+folder first, exactly as `-s/--save` does.
+
+**Read a set's tempo, length and tracks.**
+
+```python
+import pathlib
+
+from abletoolz.live_set import AbletonSet
+
+live_set = AbletonSet(pathlib.Path("my_set.als"))
+live_set.parse()
+length = live_set.transport.length()
+print(f"{live_set.version}: {length.bpm} bpm, {length.bars} bars, {length}")
+for track in live_set.tracks.load():
+    print(track.type, track.name, "height", track.height, "color", track.color)
 ```
-abletoolz "D:\all_sets\myset.als" -s --append-bars-bpm
+
+**Find missing samples and fix them.** Build the sample database once — this is what `--db` does — and hand it to
+any set.
+
+```python
+import pathlib
+
+from abletoolz.live_set import AbletonSet
+from abletoolz.sample_databaser import create_db
+
+create_db.create_or_update_db(["D:/samples"], db_path=pathlib.Path("sample_db.json"))
+db = create_db.load_db(pathlib.Path("sample_db.json"))
+live_set = AbletonSet(pathlib.Path("my_set.als"))
+live_set.parse()
+live_set.find_project_root_folder()  # where collect-and-save copies to
+for ref in live_set.samples.check():
+    print("missing:", ref.name, ref.absolute)
+if live_set.samples.fix(db, collect_and_save=True):
+    live_set.save_set()
 ```
+
+**Check that every plugin a set uses is still installed.** Each reference comes back with where it points, whether
+that file is there, and the closest thing found on this machine when it is not.
+
+```python
+import pathlib
+
+from abletoolz.live_set import AbletonSet
+
+live_set = AbletonSet(pathlib.Path("my_set.als"))
+live_set.parse()
+for ref in live_set.plugins.scan([pathlib.Path("D:/VstPlugins")]):
+    where = ref.path if ref.exists else ref.alternative or "nowhere on this machine"
+    print(f"{ref.track_location}: {ref.name} ({ref.kind}) -> {where}")
 ```
-Appending bars and bpm, new set name: myset_400bars_124.00bpm.als
-Saved set to D:\all_sets\myset_400bars_124.00bpm.als
-Restored creation and modification times: 05/17/2020 05:13:08, 05/17/2020 05:13:12
+
+**Write MIDI notes into a clip.** A note is pitch, start and duration in beats; everything else defaults to what
+Live gives a freshly drawn note.
+
+```python
+import pathlib
+
+from abletoolz.live_set import AbletonSet
+from abletoolz.live_set.clips import MidiNote
+
+live_set = AbletonSet(pathlib.Path("my_set.als"))
+live_set.parse()
+clip = live_set.clips.midi()[0]
+bar = [MidiNote(pitch, start=float(beat), duration=0.5) for beat, pitch in enumerate((36, 42, 38, 42))]
+live_set.clips.set_notes(clip, bar)
+live_set.save_set()
 ```
 
-## Library use
+**Copy a section of the arrangement somewhere else.** Clips and track automation inside the window travel
+together, and a clip crossing either edge is reported rather than trimmed.
 
-Everything the CLI does is available programmatically:
+```python
+import pathlib
+
+from abletoolz.live_set import AbletonSet
+from abletoolz.live_set.sections import SectionMode
+
+live_set = AbletonSet(pathlib.Path("my_set.als"))
+live_set.parse()
+report = live_set.clips.copy_section(64.0, 128.0, 448.0, mode=SectionMode.REFUSE)  # beats
+for line in report.lines():
+    print(line)
+live_set.save_set()
+```
+
+**Graft a device chain from one set onto a track in another.** Both sets have to be the same major Live version,
+and the chain arrives as a copy Live will open rather than a paste that takes the set down with it.
 
 ```python
+import pathlib
+
 from abletoolz.live_set import AbletonSet
 
-live_set = AbletonSet(pathlib.Path("myset.als"))
+donor = AbletonSet(pathlib.Path("donor_set.als"))
+donor.parse()
+chain = next(track for track in donor.devices.inventory() if track.track_name == "Kick")
+live_set = AbletonSet(pathlib.Path("my_set.als"))
 live_set.parse()
-print(live_set.version_tuple, live_set.transport.bpm())
-for track in live_set.tracks.load():
-    print(track.type, track.name, track.color)
-missing = live_set.samples.check()
+for device in live_set.devices.graft_chain(chain, "2-Audio", mode="append"):
+    print("grafted", device.display_name)
+live_set.save_set()
+```
+
+**Read back the sidecar a scan left.** It comes out as an object rather than a blob of YAML, your own `status` and
+`notes` included — enough to triage a whole library without opening a set.
+
+```python
+import pathlib
+
+from abletoolz import meta
+
+sidecar = meta.read(pathlib.Path("my_set.als"))
+if sidecar is not None and sidecar.scan is not None:
+    print(sidecar.scan.live_version, sidecar.scan.bars, sidecar.scan.bpm)
+    print("missing plugins:", sidecar.scan.plugins_missing)
+    print("missing samples:", sidecar.scan.samples_missing)
+    print("yours:", sidecar.status, "--", sidecar.notes)
 ```
 
 ## Future plans:
-- Export sets as an older Live version (Live's compatibility is one-directional; most of the schema differences
-are mechanical).
+- Export sets as an any / older Live versions (Live's compatibility is one-directional; most of the schema differences
+are mechanical). Some of this is partially implemented.
 - More plugin parsers — the upgrade framework is in place, formats need decoding one plugin at a time.
-- Figure out way to verify AU plugins on MacOs.
-- Analyze audio clips and color them based on a Serato like gradient(red for bass, turqoise for hi end etc...)
 - Figure out how ableton calculates CRC's for samples and use it to make perfect sample fixing. The current algorithm has a very low probability of being wrong, but this would guarantee each result is correct.
-- Attempt to detect key based on non drum track midi notes.
+- More AI agentic tool interaction interfacing