seedbox/docs/decisions.md

Design decisions

Short record of why things are the way they are, so they don't get undone by accident.

Music

• Tracks are only on or off.
  • There's no auto mode. Bringing parts in and out is the performance (Lyon, "Techno Counterpoint").
  • Every track is rendered every bar, so muting doesn't change the pattern.
• No break lane. Chopping breaks is the M8's job. Seedbox makes rhythm and melody. AMENIZER is a generator that plays a break pattern on the kit, not a sample player.
• Energy moves hats only a quarter as much as the rest. Before that, energy mostly meant busier hats.
• Rhythmic frames per seed. Before frames, most seeds put the kick on 1 and the snare on 3.
• Sections are transforms of A, not new patterns. The phrase hangs together.
• Drift is continuous overlapping layers, not steps. Wide knob spans used to do little. Drift adds displacement and weirdness at the top end.
• AMENIZER keeps its own feel. Its humanising and chops are tuned so that DRIFT past halfway isn't too extreme. The generic layers come in later and at half strength.
• Kit and keys are split (2026-10-11). One seed drives both through their own generator (KIT GEN, KEYS GEN). The keys-only choices (progression, scale, motif) moved into the keys half so ROLL KEYS renews the harmony too. Every seed changed sound; vectors regenerated. ENERGY, DRIFT, bar length, form and swing stay shared, and bass may still lock to the kicks.
• 303 slides are overlaps only. No portamento CCs: the synth channel is shared and poly, so a CC would bend every voice.
• ROOT and SCALE are global and sticky (2026-10-11). They survive SEED, ROLL and slot loads, so a seed can be fitted to an existing idea. AUTO lets the seed pick from all 21 scales, which changed every seed's sound (vectors regenerated). Slots don't store the key.
• Integer-only engine with a seeded RNG. This makes it deterministic and portable, and testable by golden vectors.

MIDI

• Kit pads are learned, not configured. The bank/pad/mode tables were dropped. BANK was dropped too (2026-10-11): it only made sense for the SP-404MKII's bank layout, and the kit side should work with any sampler or drum machine. Re-learn to change kit.
• STOP sends CC 120 on the kit channels because some samplers (the SP-404MKII) ignore All Notes Off. SPP isn't sent.
• The synth is in poly mode on one channel. Bass, melody and pad share it.
• MIDI OUT follows the 3.3 V spec (CA-033): 10 Ω on TX, 33 Ω on 3.3 V. An earlier draft had them swapped; the independent review caught it.
• Generic kit and synth (2026-10-11). Jacks, screens and docs say KIT and SYNTH, not 404 and MiniFreak. Those two are the test rig, nothing more.

Hardware

• 6N137 for MIDI IN, because that's the part on hand. It's pin-compatible with the 6N138 here except pin 7, which is the enable input and must be high: a link ties it to pin 8, and the 4.7 kΩ pin 7 resistor is gone. C1 (supply bypass) is required and sits right beside the chip. Never fit a 6N138 with that link in place: on a 6N138, pin 7 is the transistor base.
• 3.5 mm TRS MIDI jacks (Type A) instead of 5-pin DIN: the DIN jacks didn't fit the box. Type A TRS gear takes a plain stereo cable; DIN gear gets a Type A adapter.
• The Pico's USB end is at the stripboard edge (its first pin row is strip A), so the box is powered and flashed through a slot in the back wall, with no extension cable.
• 11 momentary track buttons in a diode matrix, with the state shown on the LCD map. Latching or lit buttons weren't available locally, and LEDs would need more pins.
• No FILL button. Dropped after trying the panel; fills still happen on their own in bar 4. The RUN toggle took the free corner of the grid (row 1 / column 4, outside the matrix), and GHOST moved into FILL's matrix slot (row 2 / column 4).
• Nokia 5110 instead of a 0.91" OLED, which was too small to read.
• Landscape panel in an enclosure of about 80 × 150 mm.
• One stripboard in a plastic box, Pico socketed, everything else panel mounted. No standoffs, screws or USB extension.
• GP0/GP4 links run under the Pico between its headers. That keeps them from crossing header pins; it's the reason for the col-13 cut length.
• Pad names P1–P35, not W…, to avoid clashing with strip W.

Process

• The stripboard was reviewed by blind agents with no access to the design reasoning, as well as by check-layout.js.
  • First review (30-row DIN board): 6 issues, all fixed, then clean.
  • Second review (USB at the edge, TRS jacks): no electrical faults, 12 doc and mechanical findings, all fixed. The biggest was a link note that named the ground strip instead of strip Y. The rest: USB slot height, SEED above R4, and the panel tool defaulting to portrait.
  • R4 now lies flat along strip X across a cut at X23, so a normal ¼ W part fits under SEED.
  • The re-check came back clean.
• The firmware port happens in Claude Code (this repo), against the golden vectors.