seedbox/docs/concept.md

# Concept

Seedbox grows a whole tune from one 32-bit number. The seed decides the groove, the key, the chords, the melody and the form. Two knobs push it around while it plays, and eleven buttons decide which parts you hear. It is a performance instrument: there is no step editing.

## Tracks, not lanes

Following Eric Lyon's reading of Aphex Twin ("Techno Counterpoint"), a tune is a set of looped tracks that the player brings in and out. Every track is rendered every bar; the buttons only decide what reaches MIDI. Muting never changes the pattern underneath, so a track comes back exactly where it would have been.

| # | Track | Goes to | What it is |
|---|---|---|---|
| 0 | KICK | kit | main kicks (accented, and the one) |
| 1 | KICK 2 | kit | the other kicks |
| 2 | SNARE | kit | backbeats and loud snares (vel ≥ 90) |
| 3 | GHOST | kit | quiet snares |
| 4 | HAT | kit | hat accents (vel ≥ 85) |
| 5 | HAT 16 | kit | the rest of the hats |
| 6 | PERC | kit | percussion, shares the melody's phase offset |
| 7 | BASS | synth | root and chord degrees, follows the kick |
| 8 | MEL A | synth | the motif, first half of a hocket split |
| 9 | MEL B | synth | the other half of the hocket |
| 10 | PAD | synth | a chord held for the bar |

The synth runs in poly mode on one channel, so bass, melody and pad share one voice pool.

## The genome

`genome(seed, salts)` picks, in three parts. Each part has its own random stream, so ROLL KIT and ROLL KEYS each renew one half only.

| Part | Renewed by | Picks |
|---|---|---|
| shared | SEED | **steps** (16 mostly; 12, 14 or 20), **form** (AAAB, AABA, ABAB, AAAA, ABAC, ABAA), **swing** (none to triplet feel), **arc** (flat, build, break), **layback** (snares sit late), melody/perc phase offset, fill odds |
| kit | SEED, ROLL KIT | kit density, **frame** (below), **accent cycle** (off, or every 3, 5 or 7 sixteenths across the bar line), free-snare settings |
| keys | SEED, ROLL KEYS | **scale and root** (any of the 21 below; the ROOT and SCALE pages override them), **progression** (one chord root per bar, e.g. i–vi–iv–v), keys density, motif length, hocket mask, bass colour tone, note-length style, range |

### Frames

All four kit generators share the frame, so a seed has a recognisable skeleton whichever generator plays it.

| Frame | Kick | Snare |
|---|---|---|
| backbeat | 1 | 2 and 4 |
| half-time | 1 | 3 |
| four-floor | every beat (layered) | 2 and 4 |
| 3-3-2 | 1, 1a, 3, 3a | between |
| broken | 1 and 3+ | 2+ and 4 |
| displaced | off the one | 3 |
| over the bar | every 12 sixteenths, across bar lines | halfway between |
| free snare | 1 | a Euclidean snare instead |

## Scales

Bass, melody and pad follow the scale. Chords stack every other scale note, so the scale's size changes the harmony: 5 notes give open chords, whole tone gives augmented, octatonic gives diminished.

| # | Name | Steps |
|---|---|---|
| 0 | MAJOR | 0 2 4 5 7 9 11 |
| 1 | MINOR | 0 2 3 5 7 8 10 |
| 2 | DORIAN | 0 2 3 5 7 9 10 |
| 3 | MIXOLYDIAN | 0 2 4 5 7 9 10 |
| 4 | LYDIAN | 0 2 4 6 7 9 11 |
| 5 | PHRYGIAN | 0 1 3 5 7 8 10 |
| 6 | HARM MINOR | 0 2 3 5 7 8 11 |
| 7 | MINOR PENT | 0 3 5 7 10 |
| 8 | MAJOR PENT | 0 2 4 7 9 |
| 9 | PHRYG DOM | 0 1 4 5 7 8 10 |
| 10 | DBL HARM | 0 1 4 5 7 8 11 |
| 11 | HUNG MINOR | 0 2 3 6 7 8 11 |
| 12 | UKR DORIAN | 0 2 3 6 7 9 10 |
| 13 | LYD DOM | 0 2 4 6 7 9 10 |
| 14 | HIRAJOSHI | 0 2 3 7 8 |
| 15 | IN SEN | 0 1 5 7 10 |
| 16 | IWATO | 0 1 5 6 10 |
| 17 | PROMETHEUS | 0 2 4 6 9 10 |
| 18 | WHOLE TONE | 0 2 4 6 8 10 |
| 19 | OCTATONIC | 0 1 3 4 6 7 9 10 |
| 20 | LOCRIAN | 0 1 3 5 6 8 10 |

## Generators

Kit generators, selected on the KIT GEN page.

- **EUCLID**: Euclidean rhythms. Kick E(k,n) with a rotation that keeps the one, hats and perc often on their own cycle length (polymeter).
- **SKELETON**: the frame, plus a few kick moves and hat patterns. The most "drummer-like".
- **SUBDIV**: recursive subdivision of each beat. Clusters and rolls, calmer than it used to be.
- **AUTOMATA**: a 1-D cellular automaton decides the hits inside the frame.
- **AMENIZER**: the four bars of the Amen break, velocities included, with its own humanising and chopping (below).

## Keys generators

Selected on the KEYS GEN page. All of them follow the bar's chord in the current scale and are split over BASS, MEL A, MEL B and PAD.

| Name | BASS | MEL A / B | PAD |
|---|---|---|---|
| **MOTIF** | the chord root on the kicks, a colour tone on alternate kicks, an approach note into the next bar | a 3–5 note motif stated and answered, hocket split | the bar's triad |
| **303** | a 16-step acid line looped over the bar: gates, accents, octave jumps, slides; moves with the chord root | 1–2 note answers in the bass's rests | silent, or a drone on the key's root |
| **TURING** | the chord root wherever the shift register's bit 0 is set; another bit lifts it an octave | the register read as a scale degree, hocket split | the bar's triad |
| **ARP** | the chord root on every kick | the chord (triad or 7th) arpeggiated up, down, up-down or shuffled, alternating A / B | the arpeggio's chord |

- **303**: ENERGY opens more gates. DRIFT variants flip accents, slides and octaves. A slide is a note held into the next one; whether it glides is up to the synth's glide or legato setting.
- **TURING**: an 8- or 16-bit register stepping every 16th. DRIFT flips the bit coming round (0 = locked loop, a quarter of the knob ≈ one flip a bar). Flips stick for 16 bars, then fall away.
- **ARP**: 8ths at low density, 16ths at high, and 16ths in fill bars.

## Sections

The form says which bars are A, B or C. B and C are transformations of A rather than new patterns, so the phrase hangs together. The transforms: kick answer, hat doubling, thin the first half, perc shift, ghost pickups, snare drag, drop the one, half-time switch.

## ENERGY

Pattern density. Kicks, snares, ghosts, perc and the melody thicken with it. Hats move only a quarter as much, so energy doesn't just mean "busier hats".

## DRIFT

One knob, several layers that fade in at different points. At 0 the loop is locked.

| Range | What comes in |
|---|---|
| 0–42 | phrase variations, from never to every phrase |
| 20–127 | microtiming: hats drag, snares rush, kick and bass move together |
| 40–127 | swing wobbles from bar to bar |
| 55–127 | accents slip, velocities loosen |
| 80–127 | whole parts slide a 16th early or late for a bar |
| 105–127 | now and then a beat is squeezed onto a triplet grid |

## AMENIZER

- The Amen break as a 4-bar table of step, drum, velocity and main/secondary.
- **Humanised**: each hit moves ±6 in velocity. A hit that quickly follows the same drum plays at 80%. The ride level drifts per bar.
- **Feel**: kicks ±4 ticks, main snares 10 ticks late (±5), ghosts ±10, ride 4 ticks early (±6).
- **Drift chops it per beat**, like a jungle edit. A beat can be swapped for:
  - the same beat from another bar
  - any beat
  - a repeat
  - a half-beat stutter
  - a ratchet
- The chop chance rises with DRIFT. Beat 1 stays intact below DRIFT 88.
- The generic drift layers come in later and softer.
- Swing, transforms, arc and accent shaping are off.
- Bar 4 of the break is its own fill.

## Fills

There's no FILL button. Bar 4 of a phrase fills on its own now and then (roll, stutter or drop-out with pickup); how often depends on the seed. The engine still takes a fill flag, so a manual fill can come back later without touching the music.

## Determinism

The engine uses integers only, a seeded xorshift32 and a hash, so a given seed, generator, ENERGY, DRIFT and bar always give the same events. That is what lets the Pico firmware be tested against the simulator: see [the firmware plan](../firmware/README.md) and `test/`.

Timing is 840 ticks per quarter note (210 per 16th; 840 divides by 2, 3, 4, 5 and 7 for tuplets). MIDI clock goes out every 35 ticks (24 PPQN).