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

# Generation

> Generate or plan a composition from a .vibrai project file.

Generate or plan a composition from a .vibrai project file.

## Command line

### `generate`

Generate clips and arrangement from a .vibrai project file

```bash theme={null}
vibrai generate --project <PATH> --force --dry-run --seed <VALUE> --allow-skip --with-instruments --stock-only --on-existing-tracks <MODE> --keep-empty-clips --swing <PCT> --humanize <PCT> --ornaments <PCT> --dropout <PCT>
```

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

<ParamField path="--force">
  Overwrite existing session clips and arrangement content in project tracks
</ParamField>

<ParamField path="--dry-run">
  Plan only — do not call the bridge
</ParamField>

<ParamField path="--seed">
  Override the project's T2mHash seed for this run
</ParamField>

<ParamField path="--allow-skip">
  Continue when arrangement-automation entries cannot be resolved; default fails fast.
</ParamField>

<ParamField path="--with-instruments">
  After rendering, load each part's default instrument (drum kits for drum parts) so the song is audible.
</ParamField>

<ParamField path="--stock-only">
  Resolve instruments from stock content only: skips explicit defaults.instruments overrides AND tagged instruments, using genre stock defaults + built-in generic. For demos/testing without third-party packs.
</ParamField>

<ParamField path="--on-existing-tracks">
  How to treat existing MIDI tracks: replace (delete them) or append (keep, add after last MIDI track). Default: append. Audio/return tracks are always left in place.
</ParamField>

<ParamField path="--keep-empty-clips">
  Keep generator-produced clips that resolve to zero notes. By default these are skipped, leaving a gap in both session and arrangement views. Authored literal empty clips are always kept.
</ParamField>

<ParamField path="--swing">
  Swing amount 0-100 (0 straight, 100 hard triplet). Overrides genre/preset default.
</ParamField>

<ParamField path="--humanize">
  Velocity/timing jitter 0-100. Overrides genre/preset default.
</ParamField>

<ParamField path="--ornaments">
  Grace-note/roll density 0-100. Overrides genre/preset default.
</ParamField>

<ParamField path="--dropout">
  Tension-section note thinning 0-100. Overrides genre/preset default.
</ParamField>

### `plan`

Plan a composition from a .vibrai project file without writing to Live

```bash theme={null}
vibrai plan --project <PATH> --seed <VALUE> --keep-empty-clips --swing <PCT> --humanize <PCT> --ornaments <PCT> --dropout <PCT>
```

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

<ParamField path="--seed">
  Override the project's T2mHash seed for this run
</ParamField>

<ParamField path="--keep-empty-clips">
  Keep generator-produced clips that resolve to zero notes. By default these are skipped, leaving a gap in both session and arrangement views. Authored literal empty clips are always kept.
</ParamField>

<ParamField path="--swing">
  Swing amount 0-100 (0 straight, 100 hard triplet). Overrides genre/preset default.
</ParamField>

<ParamField path="--humanize">
  Velocity/timing jitter 0-100. Overrides genre/preset default.
</ParamField>

<ParamField path="--ornaments">
  Grace-note/roll density 0-100. Overrides genre/preset default.
</ParamField>

<ParamField path="--dropout">
  Tension-section note thinning 0-100. Overrides genre/preset default.
</ParamField>

## MCP tools

### `plan`

Plan a composition from a .vibrai file without writing to Live. Returns a slim summary. Track ids in the summary (session\_clips, arrangement\_placements, instruments, current\_tracks) are 1-based, matching list\_tracks and load\_device.

```json theme={null}
{
  "tool": "plan",
  "arguments": {
    "project_path": "<String>",
    "seed": "<Nullable`1>",
    "keep_empty_clips": "<Boolean>",
    "swing": "<Nullable`1>",
    "humanize": "<Nullable`1>",
    "ornament_density": "<Nullable`1>",
    "dropout": "<Nullable`1>"
  }
}
```

<ParamField path="project_path" type="String">
  Path to the .vibrai file (defaults to Untitled.vibrai in CWD when omitted)
</ParamField>

<ParamField path="seed" type="Nullable`1">
  Optional seed override
</ParamField>

<ParamField path="keep_empty_clips" type="Boolean">
  Keep generator-produced clips that resolve to zero notes. Default false: such clips (and their arrangement placements) are skipped, leaving a gap. Authored literal empty clips are always kept.
</ParamField>

<ParamField path="swing" type="Nullable`1">
  Swing 0-100 (0 straight, 100 hard triplet); overrides genre/preset default
</ParamField>

<ParamField path="humanize" type="Nullable`1">
  Velocity/timing jitter 0-100; overrides genre/preset default
</ParamField>

<ParamField path="ornament_density" type="Nullable`1">
  Grace-note/roll density 0-100; overrides genre/preset default
</ParamField>

<ParamField path="dropout" type="Nullable`1">
  Tension-section note thinning 0-100; overrides genre/preset default
</ParamField>

### `generate`

Plan + render a composition into Live's session view and arrangement view. force=true is required only when append re-renders onto an existing part track whose target slots are non-empty; replace implies consent and never requires force. By default, fails fast when any ArrangementAutomationEntry cannot be resolved against the live device tree; pass allow\_skip=true to log warnings and continue. Track ids in the summary (session\_clips, arrangement\_placements, instruments, current\_tracks) are 1-based, matching list\_tracks and load\_device.

```json theme={null}
{
  "tool": "generate",
  "arguments": {
    "project_path": "<String>",
    "force": "<Boolean>",
    "allow_skip": "<Boolean>",
    "with_instruments": "<Boolean>",
    "stock_only": "<Boolean>",
    "on_existing_tracks": "<String>",
    "seed": "<Nullable`1>",
    "keep_empty_clips": "<Boolean>",
    "swing": "<Nullable`1>",
    "humanize": "<Nullable`1>",
    "ornament_density": "<Nullable`1>",
    "dropout": "<Nullable`1>"
  }
}
```

<ParamField path="project_path" type="String">
  Path to the .vibrai file (defaults to Untitled.vibrai in CWD when omitted)
</ParamField>

<ParamField path="force" type="Boolean">
  Overwrite existing session clips and arrangement content
</ParamField>

<ParamField path="allow_skip" type="Boolean">
  Continue when arrangement-automation entries cannot be resolved; default fails fast.
</ParamField>

<ParamField path="with_instruments" type="Boolean">
  After rendering, load each part's default instrument (drum kits for drum parts) so the song is audible.
</ParamField>

<ParamField path="stock_only" type="Boolean">
  Resolve instruments from stock content only: skips explicit defaults.instruments overrides AND tagged instruments, using genre stock defaults + built-in generic. For demos/testing on installs without third-party packs.
</ParamField>

<ParamField path="on_existing_tracks" type="String">
  How to treat MIDI tracks already in the Live set: "replace" (delete existing MIDI tracks, audio/return untouched) or "append" (keep them, add new tracks after the last MIDI track). Omit to receive a needs\_decision result listing the current tracks.
</ParamField>

<ParamField path="seed" type="Nullable`1">
  Optional seed override
</ParamField>

<ParamField path="keep_empty_clips" type="Boolean">
  Keep generator-produced clips that resolve to zero notes. Default false: such clips (and their arrangement placements) are skipped, leaving a gap. Authored literal empty clips are always kept.
</ParamField>

<ParamField path="swing" type="Nullable`1">
  Swing 0-100 (0 straight, 100 hard triplet); overrides genre/preset default
</ParamField>

<ParamField path="humanize" type="Nullable`1">
  Velocity/timing jitter 0-100; overrides genre/preset default
</ParamField>

<ParamField path="ornament_density" type="Nullable`1">
  Grace-note/roll density 0-100; overrides genre/preset default
</ParamField>

<ParamField path="dropout" type="Nullable`1">
  Tension-section note thinning 0-100; overrides genre/preset default
</ParamField>