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