Automation - Vibrai

Read, write, and manage automation envelopes.

Command line

`automation params`

List automatable parameters for a device

vibrai automation params <track> <device>

track

required

Track number (1-based: 1, 2, … or first, second, …)

device

required

Device ID, 1-based position number, or name substring

`automation slots`

Enumerate symbolic automation slot vocabulary for a PartType

vibrai automation slots <part-type>

part-type

required

`automation get`

Read arrangement automation for a track (merged ledger + live, provenance-tagged)

vibrai automation get <track> --from <BAR.BEAT|BEATS> --length <BEATS> --device <ID> --param <ID>

track

required

Track number (1-based: 1, 2, … or first, second, …)

--from

Optional window start: bar.beat (e.g. ‘17.1’) or raw beats. Provide together with —length, or omit both.

--length

Optional window length in beats. Provide together with —from, or omit both.

--device

Optional device filter (id / 1-based position / name substring)

--param

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)

vibrai automation write <track> <start> <length> --device <ID> --param <ID> --curve <SHAPE> --from <0-1> --to <0-1> --subdivisions <N> --center <0-1> --range <0-1> --smoothness <0-1> --seed <INT> --json-data <JSON> --file <PATH> --envelopes <PATH> --replace --no-create-clip --force

track

required

Track number (1-based: 1, 2, … or first, second, …)

start

required

Arrangement start: bar.beat (e.g. ‘17.1’) or raw beats

length

required

Window length in beats

--device

Device ID, 1-based position number, or name substring. Required for the single-envelope form (—curve or —json-data/—file); unused with —envelopes.

--param

Parameter index from ‘vibrai automation params’, or the param name (e.g., “Cutoff”). Required for the single-envelope form; unused with —envelopes.

--curve

--from

Curve start value (for Linear/Exp/Sine/Triangle/Saw/Hold).

--to

Curve end value (for Linear/Exp/Sine/Triangle/Saw).

--subdivisions

Number of teeth (for SawUp/SawDown only). Default 4.

--center

Wander center value.

--range

Wander deviation amplitude.

--smoothness

Wander knot density (0=jittery, 1=lazy drift).

--seed

Wander RNG seed. Auto-generated if omitted.

--json-data

Automation points as a JSON array (free-form). Mutually exclusive with —curve/—envelopes.

--file

Path to a JSON file containing an automation points array. Mutually exclusive with —curve/—envelopes.

--envelopes

Path to a JSON file containing an array of AutomationEnvelopeSpec entries (multi-envelope write; each entry carries its own device_param/macro target — supports macro targets, unlike the single-envelope form). Mutually exclusive with —curve/—json-data/—file.

--replace

Deliver exactly this set, dropping ledger-known envelopes in the window.

--no-create-clip

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).

--force

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

vibrai automation clear <track> --device <ID> --param <ID> --from <BAR.BEAT|BEATS> --length <BEATS>

track

required

Track number (1-based: 1, 2, … or first, second, …)

--device

Optional device filter (id / 1-based position / name substring)

--param

Optional parameter filter: parameter id as authored (index or display name — match what you wrote; ‘vibrai automation params’ shows both)

--from

Optional window start: bar.beat or raw beats. Provide together with —length, or omit both.

--length

Optional window length in beats. Provide together with —from, or omit both.

`automation apply`

Apply an automation slot to project sections (mutates Template.Automation)

vibrai automation apply --part <ID> --slot <KEY> --curve <CURVE> --sections <CSV|ALL> --project <PATH> --in-memory --from <0-1> --to <0-1> --subdivisions <N> --center <0-1> --range <0-1> --smoothness <0-1> --seed <INT> --apply-to-live

--part

Part id (the Id of an entry in the project’s Parts list)

--slot

Symbolic slot key (e.g. “cutoff”, “resonance”, “macro_3”, “synth_cutoff”). Use ‘vibrai automation slots <part-type>’ to list supported keys.

--curve

default:"LinearUp"

--sections

Comma-separated section ids, or ‘all’ for every section

--project

Path to .vibrai file (default: Untitled.vibrai in CWD)

--in-memory

Mutate but do not save (preview mode)

--from

Curve start value (overrides the default 0 or 1 for the chosen shape).

--to

Curve end value.

--subdivisions

Saw teeth (default 4).

--center

Wander center value.

--range

Wander deviation amplitude.

--smoothness

Wander knot density.

--seed

Wander RNG seed (auto if omitted).

--apply-to-live

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.

MCP tools

`list_automation_params`

List the automatable parameters of a device on a track.

{
  "tool": "list_automation_params",
  "arguments": {
    "track_id": "<String>",
    "device_id": "<String>"
  }
}

track_id

String

required

Track number (1-based: 1, 2, … or ‘first’, ‘second’, …)

device_id

String

required

Device ID or 1-based position number or name substring

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

{
  "tool": "write_automation",
  "arguments": {
    "track_id": "<String>",
    "start": "<String>",
    "length_beats": "<String>",
    "envelopes": "<AutomationEnvelopeSpec[]>",
    "replace": "<Boolean>",
    "create_clip": "<Boolean>",
    "force": "<Boolean>"
  }
}

track_id

String

required

Track number (1-based: 1, 2, … or ‘first’, ‘second’, …)

start

String

required

Arrangement start: bar.beat (e.g. ‘17.1’) or raw beats

length_beats

String

required

Window length in beats

envelopes

AutomationEnvelopeSpec[]

required

Envelope specs. Each: discriminated target (kind=“device_param”|“macro”) + points OR curve_spec.

replace

Boolean

true = deliver exactly this set, dropping ledger-known envelopes in the window

create_clip

Boolean

Default true: fill clip-less gaps with envelope-bearing curve-slice clips. false = skip gaps (audible reset to dial value while crossing them).

force

Boolean

Overrides the mid-clip refusal (the whole clip is rewritten; unledgered automation on it is replaced)

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

{
  "tool": "get_automation",
  "arguments": {
    "track_id": "<String>",
    "start": "<String>",
    "length_beats": "<String>",
    "device_id": "<String>",
    "param_id": "<String>"
  }
}

track_id

String

required

Track number (1-based)

start

String

Optional window start: bar.beat or raw beats

length_beats

String

Optional window length in beats

device_id

String

Optional device filter (id / 1-based position / name substring)

param_id

String

Optional parameter filter: parameter id as authored (index or display name — match what you wrote; list_automation_params shows both)

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

{
  "tool": "clear_automation",
  "arguments": {
    "track_id": "<String>",
    "device_id": "<String>",
    "param_id": "<String>",
    "start": "<String>",
    "length_beats": "<String>"
  }
}

track_id

String

required

Track number (1-based)

device_id

String

Optional device filter (id / 1-based position / name substring)

param_id

String

Optional parameter filter: parameter id as authored (index or display name — match what you wrote; list_automation_params shows both)

start

String

Optional window start: bar.beat or raw beats

length_beats

String

Optional window length in beats

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

{
  "tool": "apply_automation_template",
  "arguments": {
    "path": "<String>",
    "part_id": "<String>",
    "slot": "<String>",
    "curve": "<AutomationCurve>",
    "sections": "<String[]>",
    "apply_to_live": "<Boolean>"
  }
}

path

String

required

Absolute filesystem path to the .vibrai file.

part_id

String

required

Canonical part id from project.Parts[].Id

slot

String

required

Symbolic slot key (e.g. “cutoff”, “resonance”, “macro_3”, “synth_cutoff”). Use list_automation_slots to enumerate keys for a PartType.

curve

AutomationCurve

required

sections

String[]

required

Section ids to apply to, or the single literal “all” 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.

apply_to_live

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.

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

{
  "tool": "list_automation_slots",
  "arguments": {
    "part_type": "<PartType>"
  }
}

part_type

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.

​Command line

​automation params

​automation slots

​automation get

​automation write

​automation clear

​automation apply

​MCP tools

​list_automation_params

​write_automation

​get_automation

​clear_automation

​apply_automation_template

​list_automation_slots

Command line

`automation params`

`automation slots`

`automation get`

`automation write`

`automation clear`

`automation apply`

MCP tools

`list_automation_params`

`write_automation`

`get_automation`

`clear_automation`

`apply_automation_template`

`list_automation_slots`