nostoi-livecli 0.2.0__tar.gz

nostoi_livecli-0.2.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 0.2.0 (2026-11-10)
+
+Tested in Live 12.4.16 with Reference/Loudline Probe 0.1.4, on a studio with an Antelope Orion 32+ Gen 4, outboard (Empirical Labs Distressor and Fatso, Bricasti M7, Hologram and OTO pedals) and a Digitakt II on Overbridge.
+
+### Release
+- Packaging: `pip`/`pipx install nostoi-livecli` (the command stays `live`, the Remote Script is inside the package), Homebrew tap `nostoi-labs/tap`, `live version`.
+- Hardware tests: `fingerprint` on ten outboard units (gain, latency, polarity, noise, THD+N, response); `gainstage --hardware` (dBu into a Distressor); `recall` with SessionRecall and `fingerprint --compare`; `sync` on Overbridge.
+- `recall save --fingerprint --tracks t1,t2`: measure only the inserts on those tracks; the master is skipped unless named (an insert there sends the test signals to the speakers).
+- Fixes from the hardware tests: `sync` subtracts the latency the track's devices declare (Live compensates it; an Overbridge plugin declares about 44 ms) and says that it cannot see a Track Delay once set; `grid` reads WAV/AIFF with the standard library (ffmpeg only for other formats); `bounce`/`grid` work when the start is past the end of a short set, restore the automatically armed track and the play position; commands stopped with kill or a dropped ssh session clean up like Ctrl-C (probes removed, track volume restored). README: Overbridge sync instead of Live's MIDI clock.
+- Docs: config keys for `gainstage` and SessionRecall, everyday examples, probes are Apple Silicon only. The source package on PyPI includes tests and docs.
+
+### New since 0.1.0
+- Setup and reliability: `setup`, `doctor`, `wait`, `config`, `completion`, `skill`; error codes, hints, exit codes; CI.
+- Devices: `preset` (plugin presets and hidden parameters), `sidechain`.
+- MIDI: `notes-edit` (humanize, swing, ratchet, retrograde, arp, scale degrees, legato, velocity curve), `pattern`, `euclid`; `groove`, `warp-move`, `arr-from-session`.
+- Offline: `als-lint`, `als-diff`. `docs/API-GAPS.md` for agents.
+- `events` pushed by Live listeners (song, tracks, mixer, every device parameter).
+- New: `abx` (level-matched A/B), `gainstage` (VU and dBu, hardware inputs), `phase`, `explain` (+ `snapshot --measure`), `refcompare`, `check`, `fingerprint`, `recall` (SessionRecall).
+- Fixes: snapshot diff/restore recognise devices by name and order, not position (a device insertion no longer looks like removals); Utility parameter names of Live 12.
+- Protocol: `signal` (§5.12), `thd` (§5.13). `fingerprint` reports THD+N and harmonics with probes 0.1.4.
+
+## 0.1.0 (2026-11-03, not published)
+
+First complete version, tested in Ableton Live 12.4.16 on macOS 27 (Apple Silicon).
+
+- **Remote Script** `LiveCLI` (local JSON API, reloadable without restarting Live) and the `live` command, `--json` everywhere, Italian aliases, extensions.
+- Song and transport, tracks (create, delete, duplicate, routing in/out, arm, monitor), mixer (volume, pan, split pan, sends, activator, crossfade, cue), devices (parameters by display value also on AU/VST plugins, insert Live devices, load from the browser, replace safely with hardware inserts, A/B compare, latency per device), racks (chains, variations, Drum Rack pads), scenes and clips (properties, bulk changes, quantize, transpose, MIDI notes, automation envelopes, arrangement clips), locators, undo grouping.
+- `inspect` to discover what Live's API offers on any object.
+- `snapshot` / `diff` / `restore` / `events`: a safety net and a live view of changes.
+- `bounce`: record a track or the master inside Live with punch in/out (the API has no export).
+- `plugins`: installed plugins and Live devices by category, style and emulated hardware (`livecli/catalog.json`, plus a user catalog).
+- `als`: read a Live set without opening it.
+- **Live Probe Protocol v0.1** (`docs/PROTOCOL.md`): probes that publish real-time measurements over a local socket; reference probe (VST3, MIT) and a mock probe.
+- Probe commands: `probes`, `probe-add`, `measure`, `watch`, `compare` (band gain across a plugin or a hardware insert), `mix`, `latency` (real vs assumed latency of a device), `sync` / `grid` (timing against the grid, Track Delay for Overbridge and hardware on MIDI clock).
+- Tests: the real `commands.py` on a fake Live API, probe commands on the mock probe.

nostoi_livecli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nostoi
+
+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.

nostoi_livecli-0.2.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include CHANGELOG.md live
+recursive-include tests *.py
+recursive-include docs *.md
+include probes/mock/mock_probe.py

nostoi_livecli-0.2.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: nostoi-livecli
+Version: 0.2.0
+Summary: Command line for Ableton Live, built for AI agents: control the set and measure the sound with probe plugins
+Author: Nostoi
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nostoi-labs/livecli
+Project-URL: Issues, https://github.com/nostoi-labs/livecli/issues
+Project-URL: Changelog, https://github.com/nostoi-labs/livecli/blob/main/CHANGELOG.md
+Keywords: ableton,live,cli,audio,ai-agents,mixing,measurement
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# LiveCLI
+
+A command line for **Ableton Live**, designed to be driven by **AI agents** (Claude Code and similar) and by humans.
+
+- **No MCP server, no daemon:** a small Remote Script inside Live plus a `live` command. Each call is one short JSON line on localhost. The output is compact text, or JSON with `--json`, which keeps agent token usage low.
+- **Sees the whole set:** tracks, **return tracks and master**, devices inside racks, plugin parameters, routing (including External Audio Effect hardware inserts), clips, scenes, notes, locators, transport.
+- **Changes things safely:** set parameters by their display value (`-3 dB`, `250 Hz`, `Bell`), even on AU/VST plugins (set, read back, binary search). Replace devices without feedback loops through hardware. Use undo.
+- **Measures the studio, not just the set:** level-matched A/B, gain staging in dBu with your interface calibration, phase and polarity between tracks, the measured effect of a change, a live reference comparison, the real latency of plugins and hardware inserts, Track Delay for Overbridge and MIDI-clock hardware, fingerprints of outboard gear (response, noise, THD, latency) over time, session recall with SessionRecall.
+- **Listens:** the **Live Probe Protocol** ([docs/PROTOCOL.md](docs/PROTOCOL.md)) lets probe plugins on any track publish real-time measurements: LUFS, true peak, 1/3-octave bands, stereo correlation. `live compare` tells you what a plugin, or an outboard insert, really does to the signal. `live mix` tells you which tracks crowd the same frequencies.
+
+```
+$ live tracks
+t0   Vox Main                -> Master                EQ Eight, soothe2
+t1   Bass                    -> Master                Glue Rack
+r0   A-Reverb                -> Master                Reverb
+m    Main                                             Limiter
+
+$ live set vox eq "1 Gain A" -3dB
+Vox Main / EQ Eight / 1 Gain A: 0.0 dB -> -3.0 dB
+
+$ live probe-add vox first pre
+probe #1 on Vox Main (device 0) [pre]
+$ live probe-add vox after soothe2 post
+probe #2 on Vox Main (device 3) [post]
+$ live compare pre post 10
+#1 Vox Main [pre] -> #2 Vox Main [post], 10s (server)
+  broadband -0.4 dB (median of the bands)
+  cut   -4.2 dB at 3.2k Hz (2.5k-5.1k Hz)
+```
+
+## Install
+
+Requirements: macOS, Ableton Live 11.3 or later (tested on Live 12.4), Python 3.9+ (standard library only). The probe plugins are built for Apple Silicon only (macOS 12 or later; Loudline Probe needs macOS 13).
+
+1. Install the `live` command, one of:
+   - Homebrew: `brew install nostoi-labs/tap/livecli`
+   - pipx or pip: `pipx install nostoi-livecli`
+   - from git: `git clone https://github.com/nostoi-labs/livecli` and `ln -s "$PWD/livecli/live" ~/.local/bin/live`
+2. `live setup` copies the Remote Script into Live's User Library (`Remote Scripts/LiveCLI`).
+3. In Live, open **Settings > Link, Tempo & MIDI**. In a free **Control Surface** slot choose **LiveCLI**, with Input and Output set to None.
+4. Check: `live doctor`, then `live ping` should print `pong`.
+5. Optional, for measurements: the probe plugins (VST3, Apple Silicon, notarized) from the [Releases](https://github.com/nostoi-labs/livecli/releases) page, or `brew install --cask nostoi-labs/tap/reference-probe` (MIT) and `nostoi-labs/tap/loudline-probe` (freeware). Install them with Live closed, then **Settings > Plug-ins > Rescan**.
+
+Live loads Remote Scripts at startup. After updating LiveCLI run `live setup` again: changes to `commands.py` are reloaded without a restart, changes to `__init__.py` need a Live restart.
+
+## Install with an AI agent
+
+A user can simply tell their agent: *"I want to use LiveCLI: install it and add the skill."* This section is for that agent.
+
+**What the agent does (terminal):**
+1. Check the platform: macOS with Ableton Live 11.3 or later (12.x recommended), Python 3.9+.
+2. Get LiveCLI: `brew install nostoi-labs/tap/livecli`, or `pipx install nostoi-livecli`, or `git clone https://github.com/nostoi-labs/livecli` and link `live` into the PATH (`ln -s "$PWD/livecli/live" ~/.local/bin/live`).
+3. `live setup`: copies the Remote Script into Live's User Library (`Remote Scripts/LiveCLI`).
+4. Optional probes for measurements (Apple Silicon Macs only): install the Reference Probe or Loudline Probe package (VST3, notarized) from the Releases page, or the Homebrew casks `nostoi-labs/tap/reference-probe` and `nostoi-labs/tap/loudline-probe`.
+5. `live skill install` (Claude Code; `--dir <project>/.claude/skills/livecli` for a project skill). Next session the agent knows the commands.
+6. `live doctor` until every line is ✓, then `live ping`.
+
+**What only the user can do (ask for these, don't guess):**
+- In Live: **Settings > Link, Tempo & MIDI**, a free **Control Surface** slot: **LiveCLI**, Input and Output: None. If LiveCLI is not in the list, restart Live (it reads Remote Scripts at startup).
+- If probes were installed: **Settings > Plug-ins > Rescan** (Live must be closed while a probe is being replaced).
+- The administrator password if the probe installer asks for it, and any macOS permission prompt.
+
+**Rules for the agent once it works:**
+- Reading is free. Ask before changing the user's set; `live snapshot` before a series of changes.
+- Never change Live's audio preferences (device, buffer, sample rate) or the user's projects on disk.
+- When trying things, use new tracks of your own, not the user's tracks; delete them afterwards.
+- Run `live doctor` first whenever a command fails; error codes and hints say what to do.
+
+## Commands
+
+`live help` lists everything; `live help <command>` shows one command.
+
+A few everyday jobs, to give the idea:
+
+| You want to | Command |
+|---|---|
+| know if the open set has problems (armed tracks, overridden automation, heavy plugins left on, latency) | `live check` |
+| check an old project before opening it (missing samples, two inserts on the same hardware outputs) | `live als-lint project.als` |
+| see levels in dBu going into every hardware insert | `live gainstage 10 --hardware` |
+| know the real latency of a plugin or of an outboard insert | `live latency vox soothe2` |
+| find the Track Delay for an Overbridge device | `live sync digitakt` |
+| compare a compressor on and off at the same loudness | `live abx vox comp` |
+| switch off the heavy plugins while recording, and back on later | `live mode recording`, `live mode restore` |
+| try things and go back | `live snapshot before`, `live diff`, `live restore before` |
+| know which of your plugins do an LA-2A | `live plugins la-2a` |
+| check that an outboard unit still measures like last month | `live fingerprint vox distressor --compare` |
+
+All the commands, by group:
+
+- **Info:** `ping`, `song`, `events` (what changes in the set while it happens, pushed by Live's listeners), `cpu`, `impact` (CPU impact per track), `tracks`, `devices`, `params`, `mixer`, `meters`, `routing`, `input`, `locators`, `scenes`, `clips`, `arrangement`, `notes`, `automation` (automated and overridden parameters)
+- **Transport:** `play`, `stop`, `continue`, `stop-clips`, `record`, `undo`, `redo`, `jump <bar>`, `tempo`, `signature`, `metronome`, `loop`, `tap`, `capture-midi`, `locator`, `locator-delete`, `re-enable-automation`, `back-to-arrangement`
+- **Tracks and mixer:** `track-new`, `track-delete`, `track-duplicate`, `track-rename`, `track-color`, `solo`, `mute`, `arm`, `monitor`, `volume`, `pan`, `send`, `pan-mode` (stereo or split), `crossfade`, `activator`, `cue`
+- **Devices:** `set`, `on`, `off`, `ab` (Live 12 A/B compare), `preset` (a plugin's presets, when it publishes them to Live, and which parameters it hides from Live), `sidechain`, `insert` (a Live device by name, no browser), `duplicate`, `load`, `delete`, `move`, `rename`, `replace`, `mode`. `devices` also shows the latency Live assumes for each device.
+- **Racks:** `rack` (chains with their mixer, macros, variations, Drum Rack pads), `chain` (name, mute, solo, volume, pan of a chain), `chain-new`, `variation store|recall|delete|randomize`, `pad` (mute/solo a Drum Rack pad)
+- **Scenes and clips:** `scene ...`, `clip ...`, `set-notes`, `clip-info`, `clip-set` (launch mode and quantization, legato, markers, loop, warp mode, gain, pitch...), `clip-set-all` (many clips at once, e.g. `clip-set-all all --audio warping=off` after importing files), `clip-edit` (quantize, transpose, velocity, crop, duplicate-loop), `warp-markers`, `warp-move`, `groove`, `notes-edit` (humanize, swing, ratchet, retrograde, arp, scale degrees, legato, velocity curve), `pattern` (`x...X...`), `euclid`, `arr-from-session`, `envelope` / `envelope-set` / `envelope-clear` (clip automation), `arr-add` (copy a session clip, an audio file or a new MIDI clip into the arrangement). `@N` addresses arrangement clips (`live clip delete t3 @2`).
+- **Browser and plugins:** `search`, `browse`, `plugins` (inventory by category and style, see below)
+- **Audio:** `bounce <track|master> <start-bar> <bars>` (records a track's output or the master into a new audio track, in real time, with Live's punch in/out: the API has no export, this is the next best thing; prints the file and where the region starts in it), `capture` (optional, see below)
+- **Probes:** `probes`, `probe-add`, `measure`, `watch`, `compare`, `mix`, `latency`, `sync`, `probe-reset`, `probe-label`
+- **Timing:** `grid <track> [bars] [start-bar] [--grid 1/8]` records a track (bounce) and measures where its transients fall against Live's grid; `sync` does the same live with probes (`onsets`). See *Track Delay* below.
+- **Setup and reliability:** `setup` (installs the Remote Script), `doctor`, `version`, `wait`, `config`, `completion`, `skill` (a SKILL.md for agents, generated from these commands). Errors are JSON with a stable `code` and a `hint`; exit codes 3 Live not running, 4 not found or ambiguous, 5 not supported by Live's API, 6 probe.
+- **Safety net:** `snapshot [name]` saves every mixer, device and chain value; `diff` shows what changed since (or between two snapshots); `restore <name> [filter]` puts values back, in one undo step; `snapshots` lists them.
+- **View and offline:** `show` (bring a track, device or clip into view for the user), `view` (Session, Arranger, Detail/Clip...), `als`, `als-lint` (missing samples, hardware outputs shared by several External Audio Effects, devices off...), `als-diff` (what changed between two versions of a set). Read-only.
+- **Mix tools (with probes):** `abx` (level-matched A/B of a device: equal loudness, honest comparison), `gainstage` (peak, VU and dBu per track and into every hardware insert, with your interface calibration), `phase` (delay and polarity between two tracks), `explain` (what a set of changes did to the sound: `snapshot --measure` first), `refcompare` (your mix against a reference playing in Live, tonal balance per band), `check` (set health).
+- **Hybrid studio:** `fingerprint` (frequency response, gain, noise, latency and polarity of a hardware insert or a device, with test signals from the probes, compared over time; `fingerprints` lists the history), `recall` (Live snapshot + outboard settings from SessionRecall + fingerprints).
+- **Other:** `inspect` (what Live's API offers on the song, a track, mixer, device, parameter, clip or scene: properties with values and methods; read-only), `reload` (re-read the Remote Script commands inside Live), `call <cmd> '<json>'` (raw call to any Remote Script command), `help`.
+- **Italian aliases:** `stato`, `tracce`, `parametri`, `imposta`, `accendi`/`spegni`, `carica`, `cancella`, `sposta`, `sostituisci`, `cerca`, `livelli`, `mandata`, `locatori`, `vai`, `modo`, `cattura`, `sonde`, `misura`, `confronta`, …
+
+References are short:
+- **track:** `t3`, `r0`, `m` (master), a return letter (`A`), or part of the name;
+- **device:** an index, a path into racks (`2.0.1` = device 2, chain 0, device 1), or part of the name;
+- **probe:** `#<probe id>`, a label, or the track name.
+
+### Notes for agents
+- Read freely. Ask the user before changing their set: there is `live undo`, but hardware and ears are real. `replace` and `mode` are grouped into a single undo step.
+- Not reachable from Live's API (Live 12.4): saving, opening or exporting the set, preferences (audio device, buffer, sample rate, driver error compensation), the Delay Compensation switch, track delay, the Hardware Latency of External Audio Effect, creating group tracks. Use `inspect` to check your Live version.
+- `live --json <command>` always returns JSON. Errors come back as `{"ok": false, "error": "..."}` with exit code 1.
+- `live meters` reads Live's own meters (0 to 1 scale, not dBFS). For real levels use probes.
+
+## Which plugin should I use? (`live plugins`)
+
+`live plugins` lists every plugin Live sees (from its browser, so plugins packed in shells like Waves are expanded) plus Live's own devices, grouped by category with style and emulated hardware from [livecli/catalog.json](livecli/catalog.json). With Live closed it reads the installed AU and VST3 bundles instead. The inventory is cached for a week (`--refresh` to rebuild).
+
+```
+$ live plugins la-2a
+compressor (6)
+  Universal Audio (UADx) / UADx LA-2A Gray Compressor  AUv2+VST3  Teletronix LA-2A leveling amplifier | opto, tube, smooth, vocals, bass
+  Waves / CLA-2A                                       AUv2+VST3  Teletronix LA-2A leveling amplifier | ...
+  Universal Audio (UADx) / UADx Empirical Labs Distressor     ...  note: its 'Opt' detector mode gives an opto-like (LA-2A style) curve
+```
+
+So an agent can answer "what would you put on this vocal for an LA-2A feel, and what are my options?" from the plugins the user actually owns. The catalog is a list of regex rules (category, styles, emulates, notes); anything it doesn't know shows as `uncategorized`, and the agent can still reason from the name. Add your own plugins in `~/.config/live-cli/catalog.json` (same format): your rules come before the built-in ones. Pull requests with more plugins are welcome.
+
+## Probes
+
+A probe is a pass-through audio plugin that measures and publishes, following the [Live Probe Protocol](docs/PROTOCOL.md). `live` discovers every probe server under `~/Library/Application Support/LiveProbes/`.
+
+- **Loudline Probe** (free VST3 by Nostoi, closed source, uses the [Loudline](https://fwradar.com/loudline/) engine): LUFS M/S/I, LRA, true peak, PLR, 31 bands mid/side, correlation, history, in-process compare.
+- **Reference probe** (`probes/reference/`, MIT): a minimal implementation to copy when you build your own.
+- **Mock probe** (`probes/mock/mock_probe.py`): a fake server with synthetic signals, for developing clients without a DAW.
+
+Write your own probe in any language. If it speaks the protocol, `live` will use it.
+
+`live latency <track> <device>` puts a probe before and after a device (a plugin, or an External Audio Effect with your outboard), measures the real delay on the music while it plays, and compares it with the latency Live assumes for that device. For a hardware insert it tells you how much to add to or remove from **Hardware Latency**: Live's API does not expose that setting, so you change it by hand.
+
+`probe-add` loads the plugin set in config (`probe_plugin`, default "Loudline Probe"), gives it a free **Probe ID** through its parameter, and waits until it reports. That ID is how the CLI ties a probe to a device position in Live, even when two probes sit on the same track.
+
+## Track Delay for devices with their own sequencer
+
+Overbridge devices and hardware synced to MIDI clock play from their own sequencer: Live compensates only the latency the plugin *declares*. If the real one differs, the track is early or late and you fix it with Track Delay (Live's API cannot set it).
+
+1. **Sync first.** For Overbridge devices use the plugin's own sync (Clock and Transport in the plugin header) and turn off Live's MIDI clock (Sync) on that device's output port. Live's MIDI clock is not delay-compensated, and over plain MIDI clock a device can lock with a different phase at every start: no Track Delay can fix that. Tested with a Digitakt II: phase changing by up to 300 ms between starts on MIDI clock, stable to 0.3 ms with Overbridge sync.
+2. **Measure** with a dry sound from the device's own sequencer (its metronome, or a kick on the grid): the latency belongs to the path (device, USB, buffers), not to the sound. `live sync <track>` (playback running) reads the transients with probes and subtracts the latency the track's devices declare, since Live compensates that itself (an Overbridge plugin declares tens of ms). `live grid <track>` records the track after the mixer instead; subtract the offset of a reference sequenced by Live (the detector's attack bias, e.g. +1.4 ms for a Drift click).
+3. **Set** the Track Delay to the value with the sign flipped, and check it with `live grid` or by ear against Live's metronome: `sync` reads its probes inside the device chain, before Live applies Track Delay, so it keeps showing the original offset.
+
+Tested in Live 12.4.16: a hidden 21 ms delay on a click track measured as 21.0 ms; after Track Delay -21 ms the track was back on the reference within 0.01 ms. A Digitakt II on Overbridge sync (44.4 ms declared by the plugin) measured +1.9 ms: no Track Delay needed.
+
+## Config
+
+`~/.config/live-cli/config.json` (optional):
+
+```json
+{
+  "port": 9878,
+  "modes": {"recording": ["soothe2", "Ozone"]},
+  "probe_plugin": "Loudline Probe",
+  "capture": {"enabled": false, "device": "Your Audio Interface", "max_seconds": 600},
+  "gainstage": {"dbu_at_0dbfs": 24, "vu_ref_dbfs": -18, "peak_max_dbfs": -6, "vu_ref_by_device": {"Distressor": -20}},
+  "sessionrecall_db": "~/Documents/SessionRecall/SessionRecall.db",
+  "extensions": ["~/my-studio/live_ext.py"]
+}
+```
+
+- **modes:** `live mode recording` switches off every device whose name contains one of these strings, and saves the list. `live mode restore` switches them back on. Useful to record at low latency with heavy look-ahead plugins in the set.
+- **capture:** `live capture <seconds> <file.wav>` records an input device with ffmpeg launched **by Live**, so it inherits Live's microphone permission (a terminal or tmux usually lacks it). Off by default; it needs `ffmpeg` (`brew install ffmpeg`).
+- **gainstage:** the calibration `live gainstage` uses. `dbu_at_0dbfs` is the analog level of your interface at digital full scale (default +24 dBu: check the manual of your converter, +18, +20 and +24 are common). `vu_ref_dbfs` is the level that reads 0 VU (default -18 dBFS), `peak_max_dbfs` the highest peak you accept (default -6). `vu_ref_by_device` sets a different VU reference for inserts whose name contains the key, for units you like to drive hotter or cooler.
+- **sessionrecall_db:** where `live recall` finds the SessionRecall database (read-only; the path above is the default). `sessionrecall_labels` (`{"Model name": ["Input", "Output", ...]}`) names the controls of a unit, in SessionRecall's order, when you want names instead of "control 1".
+- **probe_plugins:** names that identify probe devices in a set (default `["Loudline Probe", "Reference Probe", "Probe"]`), for probes of your own. `probe_browser_path` loads the probe from a fixed browser path instead of searching for `probe_plugin`.
+- **extensions:** Python files (also any `*.py` in `~/.config/live-cli/extensions/`) that add your own commands:
+
+```python
+def register(cli):
+    @cli.command("hello", "hello <track>", "say hello to a track", "ext")
+    def hello(a):
+        t = cli.track(a[0])
+        print("hello", t["name"])
+```
+
+## For agents: the skill
+
+`live skill install` writes `SKILL.md` (generated from the commands, plus rules and recipes) to `~/.claude/skills/livecli/`, or to `--dir`, for example a project's `.claude/skills/livecli/`. Claude Code then knows the commands without reading this README. Regenerate it after updating LiveCLI.
+
+## Develop
+
+```
+python3 -m unittest discover -s tests
+```
+The tests run the real `remote_script/LiveCLI/commands.py` against a fake Live API (`tests/fake_live.py`), and the probe commands against the mock probe.
+
+## License
+
+MIT, see [LICENSE](LICENSE). Loudline and Loudline Probe are separate products and are not covered by this license.

nostoi_livecli-0.2.0/README.md

@@ -0,0 +1,201 @@
+# LiveCLI
+
+A command line for **Ableton Live**, designed to be driven by **AI agents** (Claude Code and similar) and by humans.
+
+- **No MCP server, no daemon:** a small Remote Script inside Live plus a `live` command. Each call is one short JSON line on localhost. The output is compact text, or JSON with `--json`, which keeps agent token usage low.
+- **Sees the whole set:** tracks, **return tracks and master**, devices inside racks, plugin parameters, routing (including External Audio Effect hardware inserts), clips, scenes, notes, locators, transport.
+- **Changes things safely:** set parameters by their display value (`-3 dB`, `250 Hz`, `Bell`), even on AU/VST plugins (set, read back, binary search). Replace devices without feedback loops through hardware. Use undo.
+- **Measures the studio, not just the set:** level-matched A/B, gain staging in dBu with your interface calibration, phase and polarity between tracks, the measured effect of a change, a live reference comparison, the real latency of plugins and hardware inserts, Track Delay for Overbridge and MIDI-clock hardware, fingerprints of outboard gear (response, noise, THD, latency) over time, session recall with SessionRecall.
+- **Listens:** the **Live Probe Protocol** ([docs/PROTOCOL.md](docs/PROTOCOL.md)) lets probe plugins on any track publish real-time measurements: LUFS, true peak, 1/3-octave bands, stereo correlation. `live compare` tells you what a plugin, or an outboard insert, really does to the signal. `live mix` tells you which tracks crowd the same frequencies.
+
+```
+$ live tracks
+t0   Vox Main                -> Master                EQ Eight, soothe2
+t1   Bass                    -> Master                Glue Rack
+r0   A-Reverb                -> Master                Reverb
+m    Main                                             Limiter
+
+$ live set vox eq "1 Gain A" -3dB
+Vox Main / EQ Eight / 1 Gain A: 0.0 dB -> -3.0 dB
+
+$ live probe-add vox first pre
+probe #1 on Vox Main (device 0) [pre]
+$ live probe-add vox after soothe2 post
+probe #2 on Vox Main (device 3) [post]
+$ live compare pre post 10
+#1 Vox Main [pre] -> #2 Vox Main [post], 10s (server)
+  broadband -0.4 dB (median of the bands)
+  cut   -4.2 dB at 3.2k Hz (2.5k-5.1k Hz)
+```
+
+## Install
+
+Requirements: macOS, Ableton Live 11.3 or later (tested on Live 12.4), Python 3.9+ (standard library only). The probe plugins are built for Apple Silicon only (macOS 12 or later; Loudline Probe needs macOS 13).
+
+1. Install the `live` command, one of:
+   - Homebrew: `brew install nostoi-labs/tap/livecli`
+   - pipx or pip: `pipx install nostoi-livecli`
+   - from git: `git clone https://github.com/nostoi-labs/livecli` and `ln -s "$PWD/livecli/live" ~/.local/bin/live`
+2. `live setup` copies the Remote Script into Live's User Library (`Remote Scripts/LiveCLI`).
+3. In Live, open **Settings > Link, Tempo & MIDI**. In a free **Control Surface** slot choose **LiveCLI**, with Input and Output set to None.
+4. Check: `live doctor`, then `live ping` should print `pong`.
+5. Optional, for measurements: the probe plugins (VST3, Apple Silicon, notarized) from the [Releases](https://github.com/nostoi-labs/livecli/releases) page, or `brew install --cask nostoi-labs/tap/reference-probe` (MIT) and `nostoi-labs/tap/loudline-probe` (freeware). Install them with Live closed, then **Settings > Plug-ins > Rescan**.
+
+Live loads Remote Scripts at startup. After updating LiveCLI run `live setup` again: changes to `commands.py` are reloaded without a restart, changes to `__init__.py` need a Live restart.
+
+## Install with an AI agent
+
+A user can simply tell their agent: *"I want to use LiveCLI: install it and add the skill."* This section is for that agent.
+
+**What the agent does (terminal):**
+1. Check the platform: macOS with Ableton Live 11.3 or later (12.x recommended), Python 3.9+.
+2. Get LiveCLI: `brew install nostoi-labs/tap/livecli`, or `pipx install nostoi-livecli`, or `git clone https://github.com/nostoi-labs/livecli` and link `live` into the PATH (`ln -s "$PWD/livecli/live" ~/.local/bin/live`).
+3. `live setup`: copies the Remote Script into Live's User Library (`Remote Scripts/LiveCLI`).
+4. Optional probes for measurements (Apple Silicon Macs only): install the Reference Probe or Loudline Probe package (VST3, notarized) from the Releases page, or the Homebrew casks `nostoi-labs/tap/reference-probe` and `nostoi-labs/tap/loudline-probe`.
+5. `live skill install` (Claude Code; `--dir <project>/.claude/skills/livecli` for a project skill). Next session the agent knows the commands.
+6. `live doctor` until every line is ✓, then `live ping`.
+
+**What only the user can do (ask for these, don't guess):**
+- In Live: **Settings > Link, Tempo & MIDI**, a free **Control Surface** slot: **LiveCLI**, Input and Output: None. If LiveCLI is not in the list, restart Live (it reads Remote Scripts at startup).
+- If probes were installed: **Settings > Plug-ins > Rescan** (Live must be closed while a probe is being replaced).
+- The administrator password if the probe installer asks for it, and any macOS permission prompt.
+
+**Rules for the agent once it works:**
+- Reading is free. Ask before changing the user's set; `live snapshot` before a series of changes.
+- Never change Live's audio preferences (device, buffer, sample rate) or the user's projects on disk.
+- When trying things, use new tracks of your own, not the user's tracks; delete them afterwards.
+- Run `live doctor` first whenever a command fails; error codes and hints say what to do.
+
+## Commands
+
+`live help` lists everything; `live help <command>` shows one command.
+
+A few everyday jobs, to give the idea:
+
+| You want to | Command |
+|---|---|
+| know if the open set has problems (armed tracks, overridden automation, heavy plugins left on, latency) | `live check` |
+| check an old project before opening it (missing samples, two inserts on the same hardware outputs) | `live als-lint project.als` |
+| see levels in dBu going into every hardware insert | `live gainstage 10 --hardware` |
+| know the real latency of a plugin or of an outboard insert | `live latency vox soothe2` |
+| find the Track Delay for an Overbridge device | `live sync digitakt` |
+| compare a compressor on and off at the same loudness | `live abx vox comp` |
+| switch off the heavy plugins while recording, and back on later | `live mode recording`, `live mode restore` |
+| try things and go back | `live snapshot before`, `live diff`, `live restore before` |
+| know which of your plugins do an LA-2A | `live plugins la-2a` |
+| check that an outboard unit still measures like last month | `live fingerprint vox distressor --compare` |
+
+All the commands, by group:
+
+- **Info:** `ping`, `song`, `events` (what changes in the set while it happens, pushed by Live's listeners), `cpu`, `impact` (CPU impact per track), `tracks`, `devices`, `params`, `mixer`, `meters`, `routing`, `input`, `locators`, `scenes`, `clips`, `arrangement`, `notes`, `automation` (automated and overridden parameters)
+- **Transport:** `play`, `stop`, `continue`, `stop-clips`, `record`, `undo`, `redo`, `jump <bar>`, `tempo`, `signature`, `metronome`, `loop`, `tap`, `capture-midi`, `locator`, `locator-delete`, `re-enable-automation`, `back-to-arrangement`
+- **Tracks and mixer:** `track-new`, `track-delete`, `track-duplicate`, `track-rename`, `track-color`, `solo`, `mute`, `arm`, `monitor`, `volume`, `pan`, `send`, `pan-mode` (stereo or split), `crossfade`, `activator`, `cue`
+- **Devices:** `set`, `on`, `off`, `ab` (Live 12 A/B compare), `preset` (a plugin's presets, when it publishes them to Live, and which parameters it hides from Live), `sidechain`, `insert` (a Live device by name, no browser), `duplicate`, `load`, `delete`, `move`, `rename`, `replace`, `mode`. `devices` also shows the latency Live assumes for each device.
+- **Racks:** `rack` (chains with their mixer, macros, variations, Drum Rack pads), `chain` (name, mute, solo, volume, pan of a chain), `chain-new`, `variation store|recall|delete|randomize`, `pad` (mute/solo a Drum Rack pad)
+- **Scenes and clips:** `scene ...`, `clip ...`, `set-notes`, `clip-info`, `clip-set` (launch mode and quantization, legato, markers, loop, warp mode, gain, pitch...), `clip-set-all` (many clips at once, e.g. `clip-set-all all --audio warping=off` after importing files), `clip-edit` (quantize, transpose, velocity, crop, duplicate-loop), `warp-markers`, `warp-move`, `groove`, `notes-edit` (humanize, swing, ratchet, retrograde, arp, scale degrees, legato, velocity curve), `pattern` (`x...X...`), `euclid`, `arr-from-session`, `envelope` / `envelope-set` / `envelope-clear` (clip automation), `arr-add` (copy a session clip, an audio file or a new MIDI clip into the arrangement). `@N` addresses arrangement clips (`live clip delete t3 @2`).
+- **Browser and plugins:** `search`, `browse`, `plugins` (inventory by category and style, see below)
+- **Audio:** `bounce <track|master> <start-bar> <bars>` (records a track's output or the master into a new audio track, in real time, with Live's punch in/out: the API has no export, this is the next best thing; prints the file and where the region starts in it), `capture` (optional, see below)
+- **Probes:** `probes`, `probe-add`, `measure`, `watch`, `compare`, `mix`, `latency`, `sync`, `probe-reset`, `probe-label`
+- **Timing:** `grid <track> [bars] [start-bar] [--grid 1/8]` records a track (bounce) and measures where its transients fall against Live's grid; `sync` does the same live with probes (`onsets`). See *Track Delay* below.
+- **Setup and reliability:** `setup` (installs the Remote Script), `doctor`, `version`, `wait`, `config`, `completion`, `skill` (a SKILL.md for agents, generated from these commands). Errors are JSON with a stable `code` and a `hint`; exit codes 3 Live not running, 4 not found or ambiguous, 5 not supported by Live's API, 6 probe.
+- **Safety net:** `snapshot [name]` saves every mixer, device and chain value; `diff` shows what changed since (or between two snapshots); `restore <name> [filter]` puts values back, in one undo step; `snapshots` lists them.
+- **View and offline:** `show` (bring a track, device or clip into view for the user), `view` (Session, Arranger, Detail/Clip...), `als`, `als-lint` (missing samples, hardware outputs shared by several External Audio Effects, devices off...), `als-diff` (what changed between two versions of a set). Read-only.
+- **Mix tools (with probes):** `abx` (level-matched A/B of a device: equal loudness, honest comparison), `gainstage` (peak, VU and dBu per track and into every hardware insert, with your interface calibration), `phase` (delay and polarity between two tracks), `explain` (what a set of changes did to the sound: `snapshot --measure` first), `refcompare` (your mix against a reference playing in Live, tonal balance per band), `check` (set health).
+- **Hybrid studio:** `fingerprint` (frequency response, gain, noise, latency and polarity of a hardware insert or a device, with test signals from the probes, compared over time; `fingerprints` lists the history), `recall` (Live snapshot + outboard settings from SessionRecall + fingerprints).
+- **Other:** `inspect` (what Live's API offers on the song, a track, mixer, device, parameter, clip or scene: properties with values and methods; read-only), `reload` (re-read the Remote Script commands inside Live), `call <cmd> '<json>'` (raw call to any Remote Script command), `help`.
+- **Italian aliases:** `stato`, `tracce`, `parametri`, `imposta`, `accendi`/`spegni`, `carica`, `cancella`, `sposta`, `sostituisci`, `cerca`, `livelli`, `mandata`, `locatori`, `vai`, `modo`, `cattura`, `sonde`, `misura`, `confronta`, …
+
+References are short:
+- **track:** `t3`, `r0`, `m` (master), a return letter (`A`), or part of the name;
+- **device:** an index, a path into racks (`2.0.1` = device 2, chain 0, device 1), or part of the name;
+- **probe:** `#<probe id>`, a label, or the track name.
+
+### Notes for agents
+- Read freely. Ask the user before changing their set: there is `live undo`, but hardware and ears are real. `replace` and `mode` are grouped into a single undo step.
+- Not reachable from Live's API (Live 12.4): saving, opening or exporting the set, preferences (audio device, buffer, sample rate, driver error compensation), the Delay Compensation switch, track delay, the Hardware Latency of External Audio Effect, creating group tracks. Use `inspect` to check your Live version.
+- `live --json <command>` always returns JSON. Errors come back as `{"ok": false, "error": "..."}` with exit code 1.
+- `live meters` reads Live's own meters (0 to 1 scale, not dBFS). For real levels use probes.
+
+## Which plugin should I use? (`live plugins`)
+
+`live plugins` lists every plugin Live sees (from its browser, so plugins packed in shells like Waves are expanded) plus Live's own devices, grouped by category with style and emulated hardware from [livecli/catalog.json](livecli/catalog.json). With Live closed it reads the installed AU and VST3 bundles instead. The inventory is cached for a week (`--refresh` to rebuild).
+
+```
+$ live plugins la-2a
+compressor (6)
+  Universal Audio (UADx) / UADx LA-2A Gray Compressor  AUv2+VST3  Teletronix LA-2A leveling amplifier | opto, tube, smooth, vocals, bass
+  Waves / CLA-2A                                       AUv2+VST3  Teletronix LA-2A leveling amplifier | ...
+  Universal Audio (UADx) / UADx Empirical Labs Distressor     ...  note: its 'Opt' detector mode gives an opto-like (LA-2A style) curve
+```
+
+So an agent can answer "what would you put on this vocal for an LA-2A feel, and what are my options?" from the plugins the user actually owns. The catalog is a list of regex rules (category, styles, emulates, notes); anything it doesn't know shows as `uncategorized`, and the agent can still reason from the name. Add your own plugins in `~/.config/live-cli/catalog.json` (same format): your rules come before the built-in ones. Pull requests with more plugins are welcome.
+
+## Probes
+
+A probe is a pass-through audio plugin that measures and publishes, following the [Live Probe Protocol](docs/PROTOCOL.md). `live` discovers every probe server under `~/Library/Application Support/LiveProbes/`.
+
+- **Loudline Probe** (free VST3 by Nostoi, closed source, uses the [Loudline](https://fwradar.com/loudline/) engine): LUFS M/S/I, LRA, true peak, PLR, 31 bands mid/side, correlation, history, in-process compare.
+- **Reference probe** (`probes/reference/`, MIT): a minimal implementation to copy when you build your own.
+- **Mock probe** (`probes/mock/mock_probe.py`): a fake server with synthetic signals, for developing clients without a DAW.
+
+Write your own probe in any language. If it speaks the protocol, `live` will use it.
+
+`live latency <track> <device>` puts a probe before and after a device (a plugin, or an External Audio Effect with your outboard), measures the real delay on the music while it plays, and compares it with the latency Live assumes for that device. For a hardware insert it tells you how much to add to or remove from **Hardware Latency**: Live's API does not expose that setting, so you change it by hand.
+
+`probe-add` loads the plugin set in config (`probe_plugin`, default "Loudline Probe"), gives it a free **Probe ID** through its parameter, and waits until it reports. That ID is how the CLI ties a probe to a device position in Live, even when two probes sit on the same track.
+
+## Track Delay for devices with their own sequencer
+
+Overbridge devices and hardware synced to MIDI clock play from their own sequencer: Live compensates only the latency the plugin *declares*. If the real one differs, the track is early or late and you fix it with Track Delay (Live's API cannot set it).
+
+1. **Sync first.** For Overbridge devices use the plugin's own sync (Clock and Transport in the plugin header) and turn off Live's MIDI clock (Sync) on that device's output port. Live's MIDI clock is not delay-compensated, and over plain MIDI clock a device can lock with a different phase at every start: no Track Delay can fix that. Tested with a Digitakt II: phase changing by up to 300 ms between starts on MIDI clock, stable to 0.3 ms with Overbridge sync.
+2. **Measure** with a dry sound from the device's own sequencer (its metronome, or a kick on the grid): the latency belongs to the path (device, USB, buffers), not to the sound. `live sync <track>` (playback running) reads the transients with probes and subtracts the latency the track's devices declare, since Live compensates that itself (an Overbridge plugin declares tens of ms). `live grid <track>` records the track after the mixer instead; subtract the offset of a reference sequenced by Live (the detector's attack bias, e.g. +1.4 ms for a Drift click).
+3. **Set** the Track Delay to the value with the sign flipped, and check it with `live grid` or by ear against Live's metronome: `sync` reads its probes inside the device chain, before Live applies Track Delay, so it keeps showing the original offset.
+
+Tested in Live 12.4.16: a hidden 21 ms delay on a click track measured as 21.0 ms; after Track Delay -21 ms the track was back on the reference within 0.01 ms. A Digitakt II on Overbridge sync (44.4 ms declared by the plugin) measured +1.9 ms: no Track Delay needed.
+
+## Config
+
+`~/.config/live-cli/config.json` (optional):
+
+```json
+{
+  "port": 9878,
+  "modes": {"recording": ["soothe2", "Ozone"]},
+  "probe_plugin": "Loudline Probe",
+  "capture": {"enabled": false, "device": "Your Audio Interface", "max_seconds": 600},
+  "gainstage": {"dbu_at_0dbfs": 24, "vu_ref_dbfs": -18, "peak_max_dbfs": -6, "vu_ref_by_device": {"Distressor": -20}},
+  "sessionrecall_db": "~/Documents/SessionRecall/SessionRecall.db",
+  "extensions": ["~/my-studio/live_ext.py"]
+}
+```
+
+- **modes:** `live mode recording` switches off every device whose name contains one of these strings, and saves the list. `live mode restore` switches them back on. Useful to record at low latency with heavy look-ahead plugins in the set.
+- **capture:** `live capture <seconds> <file.wav>` records an input device with ffmpeg launched **by Live**, so it inherits Live's microphone permission (a terminal or tmux usually lacks it). Off by default; it needs `ffmpeg` (`brew install ffmpeg`).
+- **gainstage:** the calibration `live gainstage` uses. `dbu_at_0dbfs` is the analog level of your interface at digital full scale (default +24 dBu: check the manual of your converter, +18, +20 and +24 are common). `vu_ref_dbfs` is the level that reads 0 VU (default -18 dBFS), `peak_max_dbfs` the highest peak you accept (default -6). `vu_ref_by_device` sets a different VU reference for inserts whose name contains the key, for units you like to drive hotter or cooler.
+- **sessionrecall_db:** where `live recall` finds the SessionRecall database (read-only; the path above is the default). `sessionrecall_labels` (`{"Model name": ["Input", "Output", ...]}`) names the controls of a unit, in SessionRecall's order, when you want names instead of "control 1".
+- **probe_plugins:** names that identify probe devices in a set (default `["Loudline Probe", "Reference Probe", "Probe"]`), for probes of your own. `probe_browser_path` loads the probe from a fixed browser path instead of searching for `probe_plugin`.
+- **extensions:** Python files (also any `*.py` in `~/.config/live-cli/extensions/`) that add your own commands:
+
+```python
+def register(cli):
+    @cli.command("hello", "hello <track>", "say hello to a track", "ext")
+    def hello(a):
+        t = cli.track(a[0])
+        print("hello", t["name"])
+```
+
+## For agents: the skill
+
+`live skill install` writes `SKILL.md` (generated from the commands, plus rules and recipes) to `~/.claude/skills/livecli/`, or to `--dir`, for example a project's `.claude/skills/livecli/`. Claude Code then knows the commands without reading this README. Regenerate it after updating LiveCLI.
+
+## Develop
+
+```
+python3 -m unittest discover -s tests
+```
+The tests run the real `remote_script/LiveCLI/commands.py` against a fake Live API (`tests/fake_live.py`), and the probe commands against the mock probe.
+
+## License
+
+MIT, see [LICENSE](LICENSE). Loudline and Loudline Probe are separate products and are not covered by this license.

nostoi_livecli-0.2.0/docs/API-GAPS.md

@@ -0,0 +1,34 @@
+# What Live's API cannot do (and what to do instead)
+
+Verified with Ableton Live 12.4.16 on macOS 27 using `live inspect`. Run `live inspect song|app|track <t>|mixer <t>|device <t> <d>` on your own Live version: the API changes between releases.
+
+| Operation | Status in the API | What to do |
+|---|---|---|
+| Save, open or export the set; render | not exposed (no method on Song or Application) | ask the user; for audio use `live bounce` (real-time recording inside Live) |
+| Track Delay | not exposed | `live sync` / `live grid` measure the value; the user types it in the mixer |
+| Delay Compensation, Reduced Latency When Monitoring (Options menu) | not exposed | ask the user; `live latency` tells you whether a device is compensated correctly |
+| Hardware Latency of External Audio Effect | not a parameter (the device exposes Device On, Dry/Wet, Output and Input Gain only) | `live latency` measures the real delay and tells how much to add or remove; the user sets it |
+| Audio preferences (device, buffer, sample rate, driver error compensation) | not exposed | never change them without the user |
+| Plugin parameters not configured in Live | invisible (a plugin publishes only what it exposes; some show only Device On) | ask the user to use Configure in the device title bar; then `live set` works |
+| Plugin internal presets | some plugins only: see `live preset` | the plugin's own browser |
+| Arrangement automation of track/device parameters | read/write only as clip envelopes on session clips; arrangement clip envelopes are refused | session clip envelopes (`live envelope-set`), or the user draws them |
+| Creating group tracks, freeze, flatten | not exposed | ask the user |
+| Max for Live modulator mapping (Map button) | not exposed | ask the user |
+| Native devices by name in `insert` | only Live's built-in devices; Max for Live devices (Align Delay, LFO…) must be loaded from the browser | `live load <track> audio_effects/<name>` |
+| Pad names in a Drum Rack | read-only | rename the chain inside the pad |
+| Replace the sample of an audio clip | not exposed | load the file in a new clip (`live arr-add <track> <bar> file <path>`) |
+| Add or remove warp markers | only reading and moving (`live warp-move`); the last marker is a "shadow" marker and cannot be moved | the user, in the clip view |
+| Remove a clip's groove | setting none is refused (applying one works: `live groove <track> <clip> <index>`) | the user: Groove chooser in the clip view |
+| Plugin presets | `presets` lists only "Default" for the AU and VST3 plugins tested (Apple, Waves, LiquidSonics, FabFilter, SSL): selection works only for plugins that publish programs to Live | the plugin's own preset browser |
+| Plugin parameters | `live preset` lists all of a plugin's parameter names and tells which ones are not exposed (e.g. FabFilter Pro-Q 4: 1 of 600) | Configure in Live, then `live set` |
+
+## Traps found while testing
+- **Automatic arm.** Live arms the selected MIDI track on its own (`implicit_arm`). Any arrangement recording also records on it, overwriting its clips in the recorded region. `live bounce` selects its own track and refuses to record while any other track is armed in any way.
+- **Back to Arrangement.** After a session clip plays, a track ignores the arrangement until "Back to Arrangement". `live back-to-arrangement` resets it per track (setting it only on the song is not enough).
+- **Play position.** With the transport stopped, Live starts from its own start marker and ignores the playhead set by the API: move the playhead after starting playback.
+- **Recorded clip offsets.** A recorded clip's beat 0 is not the file's first sample: use the clip's warp markers to map beats to seconds.
+- **Display rounding.** Setting by display text needs a final check of the neighbouring raw values ("-3.0 dB" vs "-3.1 dB"), and units change inside one parameter ("600 ms" then "1.00 s").
+- **Pan.** Live's pan text is not monotonic (50L … C … 50R): convert L/C/R to raw values.
+- **Automation boundaries.** `value_at_time` at the exact start of a step returns the previous value.
+- **Touching a parameter to convert text** marks its automation as overridden: convert text to values without writing to the parameter.
+- **Cue points** can be created only with the transport stopped, one tick after moving the playhead.