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

# Concepts

> The ideas behind Vibrai: .vibrai files, generators, and theme & variation.

## `.vibrai` project files

A `.vibrai` file is a plain YAML text file — a song blueprint. It sits next to your `.als` file and describes:

* **Sections** — the named parts of the arrangement (Verse 1, Chorus 1, Drop, etc.), their lengths, tension category, and positions.
* **Parts** — what plays in each section: which track, which generator, and any scale or variation overrides.
* **Templates** — arrangement-view clip placements and automation slot definitions.
* **Generation settings** — global tempo, scale (root + name), and a deterministic seed.

```yaml theme={null}
meta:
  name: "My Song"

generation:
  scale_root: 0      # C (MIDI pitch class 0–11)
  scale_name: Minor
  t2m_seed: "session-1"

sections:
  - id: s1
    name: Verse 1
    category: Verse
    tension: Tension
    modifier: 1.0
    position: 0

parts:
  - id: p_kick
    name: Kick
    type: Bd
    track_id: 1
    generator: Euclidean
```

Project files are human-readable, version-controllable, and round-trippable. The same file + the same seed always produces byte-identical output, so `.vibrai` files are a lightweight way to version-control your music. The `vibrai capture` command (CLI) or `capture_project` tool (MCP) creates a `.vibrai` from whatever is currently in your Live set — you don't have to write one from scratch.

## Generators

The engine ships four generators. Each generator receives a section's tension level, the active scale, and a stable seed, and produces a set of MIDI notes:

**Euclidean** — for rhythmic parts (kick, snare, hi-hat, percussion, crash, fill, roll). Uses the Bjorklund algorithm to spread hits evenly across a step grid. Tension controls density: higher tension = more hits; lower tension = sparser patterns.

**Melodic** — for line-based parts (bass, lead, arp, riff, melody, hook, solo). Walks a 16-step grid over a chord progression chosen per tension category, drawing pitches from a per-genre *melodic cell* that defines step density, interval pool, octave range, and accent shape. Scale-aware and deterministic per seed.

**Ambient** — for sustained harmonic parts (pads, chords, ambience, loops). Generates drop-2 chord voicings from a bank of chord progressions, chosen per tension category. Scale-aware: output respects the resolved scale for each (section, part) pair.

**FxSweep** — for FX risers and releases. Emits one whole-note trigger per bar of the section; the rising or falling motion itself is a filter-cutoff sweep the arrangement engine writes as automation (exponential up for a riser, exponential down for a release).

In a `.vibrai` part, the `generator:` field accepts `Euclidean`, `Melodic`, `Ambient`, or `FxSweep`.

Genre presets (`.vibraigenre` files) wire each part type to the appropriate generator and configure section lengths, tempo, and templates. Fourteen genre libraries ship with Vibrai today.

## Theme and variation

A Vibrai arrangement is built around a **theme** extracted from the first section (by position). Every other section's output is derived from that theme, not from scratch — this guarantees coherence across a song.

**Variation operators** let you modify the theme per-section without breaking coherence. Three operators ship today, applied in fixed order (`transpose` → `density` → `motif`) regardless of the order you write them in YAML:

| Operator    | Field                 | Effect                                                                               |
| ----------- | --------------------- | ------------------------------------------------------------------------------------ |
| `transpose` | `semitones` (int)     | Shifts all generated pitches by N semitones                                          |
| `density`   | `delta` (-1.0 to 1.0) | Scales step density — more or fewer hits for drums, longer or shorter notes for pads |
| `motif`     | `amount` (0.0 to 1.0) | Blends an alternate motif over the theme                                             |

Variation is **relative to the theme, not cumulative**. Section 3's output depends only on the theme + section 3's own variation block — never on section 2. This means you can re-render a single section without affecting any other, and `vibrai generate --dry-run` can preview individual sections safely.

```yaml theme={null}
sections:
  - id: s1
    name: Verse 1
    position: 0          # this is the theme

  - id: s2
    name: Chorus 1
    position: 1
    variation:
      - { type: transpose, semitones: 5 }   # up a fourth
      - { type: density,   delta: 0.3 }     # slightly denser
```

Scale overrides follow a **Part > Section > Global** precedence, resolved field-by-field. A Part can override only the root note while inheriting the Section's scale name. This lets a single section set a key for all its parts while one part (say, the arp) plays in a different mode.