Command line
automation params
List automatable parameters for a device
required
Track handle (trk_42) OR 1-based number (1, 2, …) OR ordinal (first, second, …)
required
Device ID, 1-based position number, or name substring
automation slots
Enumerate symbolic automation slot vocabulary for a PartType
required
Any PartType enum value. Melodic/textural types (Pad | Lead | Bass | Arp | Ambience | Chords | Riff | Melody | Solo | Hook | Loop | Other) and FX types (FxRiser | FxRelease) have slots; drum types return an empty list.
automation get
Read arrangement automation for a track (merged ledger + live, provenance-tagged). Arrangement automation is bounced, not directly LOM-readable — this merges the write ledger, so save the set (Cmd-S) if you need read-back across separate CLI invocations.
required
Track handle (trk_42) OR 1-based number (1, 2, …) OR ordinal (first, second, …)
Path to the .vibrai file whose declared meter positions bar.beat inputs (defaults to <current-directory-name>.vibrai; falls back to Live’s transport, then 4/4)
Optional window start: bar.beat (e.g. ‘17.1’) or raw beats. Provide together with —length, or omit both.
Optional window length in beats. Provide together with —from, or omit both.
Optional device filter (id / 1-based position / name substring)
Optional parameter filter: parameter id as authored (index or display name — match what you wrote; ‘vibrai automation params’ shows both)
automation write
Write automation onto the arrangement timeline (chunked per clip, ledger-backed). Not directly LOM-readable afterward — confirm with ‘automation get’ (it merges the write ledger); save the set (Cmd-S) so the ledger persists for read-back across separate CLI invocations.
required
Track handle (trk_42) OR 1-based number (1, 2, …) OR ordinal (first, second, …)
required
Arrangement start: bar.beat (e.g. ‘17.1’) or raw beats
required
Window length in beats
Path to the .vibrai file whose declared meter positions bar.beat inputs (defaults to <current-directory-name>.vibrai; falls back to Live’s transport, then 4/4)
Device ID, 1-based position number, or name substring. Required for the single-envelope form (—curve or —json-data/—file); unused with —envelopes.
Parameter index from ‘vibrai automation params’, or the param name (e.g., “Cutoff”). Required for the single-envelope form; unused with —envelopes.
Curve shape: LinearUp|LinearDown|ExpUp|ExpDown|Sine|Triangle|SawUp|SawDown|Hold|Wander. Curve length is the <length> argument. Mutually exclusive with —json-data/—file/—envelopes.
Curve start value as a fraction of the parameter’s travel (0 = its min, 1 = its max); scaled to native units at write time. Defaults to 0. For Linear/Exp/Sine/Triangle/Saw/Hold.
Curve end value as a fraction of the parameter’s travel (0 = min, 1 = max). Defaults to 1. For Linear/Exp/Sine/Triangle/Saw.
Number of teeth (for SawUp/SawDown only). Default 4.
Wander center as a fraction of the parameter’s travel. Defaults to 0.5 (midpoint).
Wander deviation amplitude as a fraction of the parameter’s travel (must be > 0 and <= 1).
Wander knot density (0=jittery, 1=lazy drift).
Wander RNG seed. Auto-generated if omitted.
Automation points as a JSON array (free-form). Mutually exclusive with —curve/—envelopes.
Path to a JSON file containing an automation points array. Mutually exclusive with —curve/—envelopes.
Path to a JSON file: an array of envelope entries (multi-envelope write). Each entry has a flat
target — device_id+param_id (a device parameter) OR rack_kind+macro_index (a rack macro; inferred, no kind field) — plus points or curve_spec. Supports macro targets, unlike the single-envelope form. Mutually exclusive with —curve/—json-data/—file.Deliver exactly this set, dropping ledger-known envelopes in the window.
Skip clip-less gaps instead of filling them with envelope-bearing curve-slice clips (default: fill — a skipped gap is an audible reset to the dial value; the lane does not interpolate).
Allow a window whose edge lands mid-clip (rewrites the whole clip). Without this, a mid-clip window is refused.
automation clear
Clear arrangement automation by track, optionally narrowed by device/param/window
required
Track handle (trk_42) OR 1-based number (1, 2, …) OR ordinal (first, second, …)
Path to the .vibrai file whose declared meter positions bar.beat inputs (defaults to <current-directory-name>.vibrai; falls back to Live’s transport, then 4/4)
Optional device filter (id / 1-based position / name substring)
Optional parameter filter: parameter id as authored (index or display name — match what you wrote; ‘vibrai automation params’ shows both)
Optional window start: bar.beat or raw beats. Provide together with —length, or omit both.
Optional window length in beats. Provide together with —from, or omit both.
automation apply
Apply an automation slot to project sections (mutates Template.Automation)
Part id (the Id of an entry in the project’s Parts list)
Symbolic slot key (e.g. “cutoff”, “resonance”, “macro_3”, “synth_cutoff”). Use ‘vibrai automation slots <part-type>’ to list supported keys.
LinearUp | LinearDown | ExpUp | ExpDown | Sine | Triangle | SawUp | SawDown | Hold | Wander (default LinearUp)
Comma-separated section ids, or ‘all’ for every section
Path to the .vibrai file (default: <current-directory-name>.vibrai in the working directory)
Mutate but do not save (preview mode)
Curve start value (overrides the default 0 or 1 for the chosen shape).
Curve end value.
Saw teeth (default 4).
Wander center value.
Wander deviation amplitude, 0-1 (must be > 0).
Wander knot density.
Wander RNG seed (auto if omitted).
Also push the applied slots into the running Live set via the safe bouncer. Requires an existing populated arrangement; slots without a clip at the section are skipped.
automation render
Apply the project composition’s arrangement automation to the already-rendered Live set. Run after generate (and after instruments are loaded). Re-plans from the .vibrai; pass the same —seed generate used.
Path to the .vibrai file (default: <current-directory-name>.vibrai in the working directory)
Override the project’s T2mHash seed for this run. Pass the same value generate used, or the re-planned composition may not match what was rendered. Seed is the ONLY plan input this command threads: generate’s —keep-empty-clips, style knobs and bass knobs are not re-applied, and the meter is re-resolved from the project or the live transport, so a transport meter changed since generate can shift the bounce window on a project that declares no meter.
MCP tools
list_automation_params
List the automatable parameters of a device on a track. Each parameter’s value is a number in its own [min_value, max_value] domain — NOT display units: an Auto Filter’s Frequency runs 0..1, where 0.5 reads as 632 Hz. display_value (Live’s str_for_value) shows what the number means. Quantized parameters (is_quantized: true) also carry value_items, the ordered label vocabulary the value indexes into (e.g. Filter Type’s “Band-pass”) — default_value is the opposite case: present on continuous parameters, absent (null) on quantized ones, where Live reports no default to reset to. This is the metadata set_device_param / apply_device_params expect you to have read first.
String
required
Track handle from list_tracks, e.g. “trk_42”. Copy verbatim.
String
required
1-based position: 1 = the first device in the chain, 2 = the second. NOT the
device_id list_devices reports — that field is 0-based, so add 1 to it. A name substring also works (case-insensitive, must match exactly one device).write_automation
Write automation onto the ARRANGEMENT timeline (Live’s primary automation home). One logical write may span several arrangement clips: the curve is sliced per clip (chunked delivery — clip names/colors/boundaries preserved; no coalescing). Gaps are FILLED with envelope-bearing curve-slice clips by default (create_clip:false skips them instead — a skipped gap is an audible reset to the dial value; the lane does not interpolate). A window starting/ending mid-clip refuses without force:true. Sequential writes to the same window are safe: ledger-known envelopes re-deliver automatically (replace:true opts out). Session-view clips use write_clip_envelope instead. Bounced automation is not directly LOM-readable afterward — confirm with get_automation (it merges the write ledger); save the set (Cmd-S) so the ledger persists for read-back across separate CLI/MCP invocations.
String
required
Track handle from list_tracks, e.g. “trk_42”. Copy verbatim.
String
required
Arrangement start: bar.beat (e.g. ‘17.1’) or raw beats
String
required
Window length in beats
AutomationEnvelopeDto[]
required
Envelope specs. Each has a flat
target plus points OR curve_spec. target = a device parameter (device_id + param_id) OR a rack macro (rack_kind + macro_index); the kind is inferred from which fields you supply — no discriminator needed.Boolean
true = deliver exactly this set, dropping ledger-known envelopes in the window
Boolean
Default true: fill clip-less gaps with envelope-bearing curve-slice clips. false = skip gaps (audible reset to dial value while crossing them).
Boolean
Overrides the mid-clip refusal (the whole clip is rewritten; unledgered automation on it is replaced)
String
Path to the .vibrai file whose declared meter positions bar.beat inputs (defaults to <current-directory-name>.vibrai in the working directory; falls back to Live’s transport, then 4/4)
get_automation
Read ARRANGEMENT automation for a track — one merged, honest answer. Each envelope is provenance-tagged: source=“ledger” (authored by Vibrai; exact points; survives restarts for SAVED Live sets, process-lifetime only for unsaved ones) or source=“live” (visible to the LOM; 0.25-beat sampled). Optional window/target filters. Arrangement automation is bounced, not directly LOM-readable — this merges the write ledger, so save the set (Cmd-S) if you need read-back across separate CLI/MCP invocations.
String
required
Track handle from list_tracks, e.g. “trk_42”. Copy verbatim.
String
Optional window start: bar.beat or raw beats
String
Optional window length in beats
String
Optional device filter (id / 1-based position / name substring)
String
Optional parameter filter: parameter id as authored (index or display name — match what you wrote; list_automation_params shows both)
String
Path to the .vibrai file whose declared meter positions bar.beat inputs (defaults to <current-directory-name>.vibrai in the working directory; falls back to Live’s transport, then 4/4)
clear_automation
Clear ARRANGEMENT automation by track, optionally narrowed by device+param and/or window. Always clears by unconditional baseline-overwrite: each ledger-known (Vibrai-authored) entry in scope is overwritten with a flat envelope at its final authored value, then forgotten. Native LOM deletion is never used as the effect mechanism — its supported:true is not proof of an effect on Vibrai-delivered clips. Automation the ledger doesn’t know about (hand-drawn in Live, or written before the ledger existed) cannot be targeted this way; the result reports that honestly instead of pretending to have cleared it.
String
required
Track handle from list_tracks, e.g. “trk_42”. Copy verbatim.
String
Optional device filter (id / 1-based position / name substring)
String
Optional parameter filter: parameter id as authored (index or display name — match what you wrote; list_automation_params shows both)
String
Optional window start: bar.beat or raw beats
String
Optional window length in beats
String
Path to the .vibrai file whose declared meter positions bar.beat inputs (defaults to <current-directory-name>.vibrai in the working directory; falls back to Live’s transport, then 4/4)
apply_automation_template
Author a composition-level automation slot on the .vibrai project’s arrangement template. The slot is a symbolic key resolved through AutomationTargetMap (see list_automation_slots for the vocabulary per PartType). Slots fall into two families: bare-synth slots (synth_cutoff, synth_resonance, synth_volume) target a parameter on device 0 by LOM name; rack-macro slots (cutoff, resonance, macro_1..macro_16) target a macro on the first Instrument Rack on the chain, resolved at bounce-time. The project is loaded, mutated, validated, and saved. Idempotent on (sectionId, partId, slot). Use “all” in sections to apply to every section. Sparse captured projects are supported: a targeted section where the part has no clip source (literal-clip-only part, no clip for that section) is skipped and listed in skipped_no_clip_source rather than failing — “all” means everywhere the part plays. Set apply_to_live: true to also push the just-applied slots into the running Live set via the safe bouncer (Spec A’s atomic-rollback contract applies per slot). The .vibrai file is updated first, then each applied (section, part, slot) tuple is resolved to a bouncer-shaped envelope and bounced onto the existing arrangement clip at the section’s position. Slots whose section has no arrangement clip are skipped with status skipped_no_arrangement_clip — Spec B is an iteration tool, not bootstrapping. Verify what landed via get_automation (arrangement-scoped read). Default false preserves the file-only flow that callers depend on today.
String
required
Absolute filesystem path to the .vibrai file.
String
required
Canonical part id from project.Parts[].Id
String
required
Symbolic slot key (e.g. “cutoff”, “resonance”, “macro_3”, “synth_cutoff”). Use list_automation_slots to enumerate keys for a PartType.
AutomationCurve
required
AutomationCurve enum: LinearUp | LinearDown | ExpUp | ExpDown | Sine | Triangle | SawUp | SawDown | Hold | Wander
String[]
required
Section ids to apply to, or the single literal “all” (case-insensitive) to apply to every section in project.Sections. Sections where the part has no clip source are skipped and reported in skipped_no_clip_source.
Nullable`1
Curve start value: a fraction of the parameter’s travel, 0-1. Default per shape.
Nullable`1
Curve end value: a fraction of the parameter’s travel, 0-1.
Nullable`1
Saw teeth (default 4).
Nullable`1
Wander center as a fraction of travel, 0-1.
Nullable`1
Wander deviation amplitude as a fraction of travel, 0-1 (must be > 0).
Nullable`1
Wander knot density, 0-1.
Nullable`1
Wander RNG seed (auto if omitted).
Boolean
If true, also push the applied slots into the running Live set via the safe bouncer. Default false — file-only authoring. Requires an existing populated arrangement; slots whose section has no arrangement clip are skipped with a status. See recipe
apply_automation_template_live for the iteration flow.render_automation
Apply the project composition’s arrangement automation to the already-rendered Live set. Run this AFTER generate, and after the parts’ instruments are loaded — automation resolves against the live device tree, so a deviceless track can only be skipped. Re-plans the composition from the .vibrai (PlanComposition is deterministic given project + seed + meter), so pass the same seed generate used. Automates clips that EXIST; it never creates them. A planned placement with no arrangement clip under it is reported as a skip, not bounced. Never throws on an unresolvable target: each is reported in skipped_entries with the slot, the parameter, and why it could not land. Each skipped entry carries live_track_id — the 1-based live address matching list_tracks and load_device, or null when the part bound to no live track; use that, not track_id, if you need an address to pass to another tool. If the bounce deletes arrangement clips it cannot restore, the top-level data_loss field carries a plain-language alarm and rollback_failures names the clips — check data_loss before treating a run as successful. Arrangement automation is bounced and not directly LOM-readable — verify with get_automation, which merges the write ledger, and save the set (Cmd-S) so the ledger persists. The CLI sibling is vibrai automation render.
String
required
Absolute filesystem path to the .vibrai file.
Nullable`1
Optional seed override. Pass the same value generate used, or the re-planned composition may not match what was rendered. Seed is the ONLY plan input this tool threads: generate’s keep_empty_clips, style knobs and bass knobs are not re-applied, and the meter is re-resolved from the project or the live transport, so a transport meter changed since generate can shift the bounce window on a project that declares no meter.
list_automation_slots
Enumerate the symbolic automation slots supported for a PartType. Returns a list of {slot_key, target_kind, target_details, description}. target_kind is “device_param” or “macro”. Macro slots resolve at bounce-time; device_param slots resolve to a fixed (device_index, param_name) pair. Returns an empty list for PartTypes with no entries (e.g. Bd, Sd, Hh).
PartType
required
Any PartType enum value. Melodic/textural types (Pad, Lead, Bass, Arp, Ambience, Chords, Riff, Melody, Solo, Hook, Loop, Other) and FX types (FxRiser, FxRelease) have slots; drum types return an empty list.