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) picks, once per seed:

• steps: 16 most of the time, sometimes 12, 14 or 20 (bar length = steps × 16th)
• form: AAAB, AABA, ABAB, AAAA, ABAC or ABAA over a 4-bar phrase
• scale and root: any of the 21 scales below, any root. The ROOT and SCALE pages override them; AUTO keeps the seed's pick.
• progression: one chord root per bar of the phrase (e.g. i–vi–iv–v)
• frame: where the main kick and snare live (below)
• swing: none, light, medium, heavy or triplet feel
• arc: flat, build (bars 1–2 thin out) or break (bar 3 strips back)
• accent cycle: off, or an accent every 3, 5 or 7 sixteenths running across the bar line
• motif length (3–5 notes), hocket mask, bass degree, melody phase offset, layback (snares sit a little late), densities, fill odds

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

Selected on the GEN page. They only change the kit; the synth tracks are the same for all of them.

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

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