> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibrai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Automation

> Read, write, and manage automation envelopes.

Read, write, and manage automation envelopes.

## Command line

### `automation params`

List automatable parameters for a device

```bash theme={null}
vibrai automation params <track> <device>
```

<ParamField path="track" required>
  Track number (1-based: 1, 2, … or first, second, …)
</ParamField>

<ParamField path="device" required>
  Device ID, 1-based position number, or name substring
</ParamField>

### `automation slots`

Enumerate symbolic automation slot vocabulary for a PartType

```bash theme={null}
vibrai automation slots <part-type>
```

<ParamField path="part-type" 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.
</ParamField>

### `automation get`

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

```bash theme={null}
vibrai automation get <track> --from <BAR.BEAT|BEATS> --length <BEATS> --device <ID> --param <ID>
```

<ParamField path="track" required>
  Track number (1-based: 1, 2, … or first, second, …)
</ParamField>

<ParamField path="--from">
  Optional window start: bar.beat (e.g. '17.1') or raw beats. Provide together with --length, or omit both.
</ParamField>

<ParamField path="--length">
  Optional window length in beats. Provide together with --from, or omit both.
</ParamField>

<ParamField path="--device">
  Optional device filter (id / 1-based position / name substring)
</ParamField>

<ParamField path="--param">
  Optional parameter filter: parameter id as authored (index or display name — match what you wrote; 'vibrai automation params' shows both)
</ParamField>

### `automation write`

Write automation onto the arrangement timeline (chunked per clip, ledger-backed)

```bash theme={null}
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
```

<ParamField path="track" required>
  Track number (1-based: 1, 2, … or first, second, …)
</ParamField>

<ParamField path="start" required>
  Arrangement start: bar.beat (e.g. '17.1') or raw beats
</ParamField>

<ParamField path="length" required>
  Window length in beats
</ParamField>

<ParamField path="--device">
  Device ID, 1-based position number, or name substring. Required for the single-envelope form (--curve or --json-data/--file); unused with --envelopes.
</ParamField>

<ParamField path="--param">
  Parameter index from 'vibrai automation params', or the param name (e.g., "Cutoff"). Required for the single-envelope form; unused with --envelopes.
</ParamField>

<ParamField path="--curve">
  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.
</ParamField>

<ParamField path="--from">
  Curve start value (for Linear/Exp/Sine/Triangle/Saw/Hold).
</ParamField>

<ParamField path="--to">
  Curve end value (for Linear/Exp/Sine/Triangle/Saw).
</ParamField>

<ParamField path="--subdivisions">
  Number of teeth (for SawUp/SawDown only). Default 4.
</ParamField>

<ParamField path="--center">
  Wander center value.
</ParamField>

<ParamField path="--range">
  Wander deviation amplitude.
</ParamField>

<ParamField path="--smoothness">
  Wander knot density (0=jittery, 1=lazy drift).
</ParamField>

<ParamField path="--seed">
  Wander RNG seed. Auto-generated if omitted.
</ParamField>

<ParamField path="--json-data">
  Automation points as a JSON array (free-form). Mutually exclusive with --curve/--envelopes.
</ParamField>

<ParamField path="--file">
  Path to a JSON file containing an automation points array. Mutually exclusive with --curve/--envelopes.
</ParamField>

<ParamField path="--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.
</ParamField>

<ParamField path="--replace">
  Deliver exactly this set, dropping ledger-known envelopes in the window.
</ParamField>

<ParamField path="--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).
</ParamField>

<ParamField path="--force">
  Allow a window whose edge lands mid-clip (rewrites the whole clip). Without this, a mid-clip window is refused.
</ParamField>

### `automation clear`

Clear arrangement automation by track, optionally narrowed by device/param/window

```bash theme={null}
vibrai automation clear <track> --device <ID> --param <ID> --from <BAR.BEAT|BEATS> --length <BEATS>
```

<ParamField path="track" required>
  Track number (1-based: 1, 2, … or first, second, …)
</ParamField>

<ParamField path="--device">
  Optional device filter (id / 1-based position / name substring)
</ParamField>

<ParamField path="--param">
  Optional parameter filter: parameter id as authored (index or display name — match what you wrote; 'vibrai automation params' shows both)
</ParamField>

<ParamField path="--from">
  Optional window start: bar.beat or raw beats. Provide together with --length, or omit both.
</ParamField>

<ParamField path="--length">
  Optional window length in beats. Provide together with --from, or omit both.
</ParamField>

### `automation apply`

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

```bash theme={null}
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
```

<ParamField path="--part">
  Part id (the Id of an entry in the project's Parts list)
</ParamField>

<ParamField path="--slot">
  Symbolic slot key (e.g. "cutoff", "resonance", "macro\_3", "synth\_cutoff"). Use 'vibrai automation slots \<part-type>' to list supported keys.
</ParamField>

<ParamField path="--curve" default="LinearUp">
  LinearUp | LinearDown | ExpUp | ExpDown | Sine | Triangle | SawUp | SawDown | Hold | Wander
</ParamField>

<ParamField path="--sections">
  Comma-separated section ids, or 'all' for every section
</ParamField>

<ParamField path="--project">
  Path to .vibrai file (default: Untitled.vibrai in CWD)
</ParamField>

<ParamField path="--in-memory">
  Mutate but do not save (preview mode)
</ParamField>

<ParamField path="--from">
  Curve start value (overrides the default 0 or 1 for the chosen shape).
</ParamField>

<ParamField path="--to">
  Curve end value.
</ParamField>

<ParamField path="--subdivisions">
  Saw teeth (default 4).
</ParamField>

<ParamField path="--center">
  Wander center value.
</ParamField>

<ParamField path="--range">
  Wander deviation amplitude.
</ParamField>

<ParamField path="--smoothness">
  Wander knot density.
</ParamField>

<ParamField path="--seed">
  Wander RNG seed (auto if omitted).
</ParamField>

<ParamField path="--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.
</ParamField>

## MCP tools

### `list_automation_params`

List the automatable parameters of a device on a track.

```json theme={null}
{
  "tool": "list_automation_params",
  "arguments": {
    "track_id": "<String>",
    "device_id": "<String>"
  }
}
```

<ParamField path="track_id" type="String" required>
  Track number (1-based: 1, 2, … or 'first', 'second', …)
</ParamField>

<ParamField path="device_id" type="String" required>
  Device ID or 1-based position number or name substring
</ParamField>

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

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

<ParamField path="track_id" type="String" required>
  Track number (1-based: 1, 2, … or 'first', 'second', …)
</ParamField>

<ParamField path="start" type="String" required>
  Arrangement start: bar.beat (e.g. '17.1') or raw beats
</ParamField>

<ParamField path="length_beats" type="String" required>
  Window length in beats
</ParamField>

<ParamField path="envelopes" type="AutomationEnvelopeSpec[]" required>
  Envelope specs. Each: discriminated target (kind="device\_param"|"macro") + points OR curve\_spec.
</ParamField>

<ParamField path="replace" type="Boolean">
  true = deliver exactly this set, dropping ledger-known envelopes in the window
</ParamField>

<ParamField path="create_clip" type="Boolean">
  Default true: fill clip-less gaps with envelope-bearing curve-slice clips. false = skip gaps (audible reset to dial value while crossing them).
</ParamField>

<ParamField path="force" type="Boolean">
  Overrides the mid-clip refusal (the whole clip is rewritten; unledgered automation on it is replaced)
</ParamField>

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

```json theme={null}
{
  "tool": "get_automation",
  "arguments": {
    "track_id": "<String>",
    "start": "<String>",
    "length_beats": "<String>",
    "device_id": "<String>",
    "param_id": "<String>"
  }
}
```

<ParamField path="track_id" type="String" required>
  Track number (1-based)
</ParamField>

<ParamField path="start" type="String">
  Optional window start: bar.beat or raw beats
</ParamField>

<ParamField path="length_beats" type="String">
  Optional window length in beats
</ParamField>

<ParamField path="device_id" type="String">
  Optional device filter (id / 1-based position / name substring)
</ParamField>

<ParamField path="param_id" type="String">
  Optional parameter filter: parameter id as authored (index or display name — match what you wrote; list\_automation\_params shows both)
</ParamField>

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

```json theme={null}
{
  "tool": "clear_automation",
  "arguments": {
    "track_id": "<String>",
    "device_id": "<String>",
    "param_id": "<String>",
    "start": "<String>",
    "length_beats": "<String>"
  }
}
```

<ParamField path="track_id" type="String" required>
  Track number (1-based)
</ParamField>

<ParamField path="device_id" type="String">
  Optional device filter (id / 1-based position / name substring)
</ParamField>

<ParamField path="param_id" type="String">
  Optional parameter filter: parameter id as authored (index or display name — match what you wrote; list\_automation\_params shows both)
</ParamField>

<ParamField path="start" type="String">
  Optional window start: bar.beat or raw beats
</ParamField>

<ParamField path="length_beats" type="String">
  Optional window length in beats
</ParamField>

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

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

<ParamField path="path" type="String" required>
  Absolute filesystem path to the .vibrai file.
</ParamField>

<ParamField path="part_id" type="String" required>
  Canonical part id from project.Parts\[].Id
</ParamField>

<ParamField path="slot" type="String" required>
  Symbolic slot key (e.g. "cutoff", "resonance", "macro\_3", "synth\_cutoff"). Use list\_automation\_slots to enumerate keys for a PartType.
</ParamField>

<ParamField path="curve" type="AutomationCurve" required>
  AutomationCurve enum: LinearUp | LinearDown | ExpUp | ExpDown | Sine | Triangle | SawUp | SawDown | Hold | Wander
</ParamField>

<ParamField path="sections" type="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.
</ParamField>

<ParamField path="apply_to_live" type="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.
</ParamField>

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

```json theme={null}
{
  "tool": "list_automation_slots",
  "arguments": {
    "part_type": "<PartType>"
  }
}
```

<ParamField path="part_type" 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.
</ParamField>