Feat: mixed bag

docs/tutorials/soundfont.md

@@ -0,0 +1,111 @@
+# Soundfonts
+
+General MIDI playback via SF2 soundfont files. Native only -- not available in the WASM build.
+
+## Setup
+
+Drop an `.sf2` file into one of your samples directories. The engine finds and loads it automatically when Cagire starts. Only one soundfont is active at a time.
+
+## Playing
+
+Use `gm` as the sound source. The `n` parameter selects a program by name or number (0-127):
+
+```forth
+gm s piano n .              ;; acoustic piano
+gm s strings n c4 note .    ;; strings playing middle C
+gm s 0 n e4 note .          ;; program 0 (piano) playing E4
+```
+
+## Drums
+
+Drums live on a separate bank. Use `drums` or `percussion` as the `n` value. Each MIDI note triggers a different instrument:
+
+```forth
+gm s drums n 36 note .      ;; kick
+gm s drums n 38 note .      ;; snare
+gm s drums n 42 note .      ;; closed hi-hat
+gm s percussion n 49 note . ;; crash cymbal
+```
+
+## Envelope
+
+The soundfont embeds ADSR envelope data per preset. The engine applies it automatically. Override any parameter explicitly:
+
+```forth
+gm s piano n 0.01 attack 0.3 decay .
+gm s strings n 0.5 attack 2.0 release .
+```
+
+If you set `attack`, `decay`, `sustain`, or `release`, your value wins. Unspecified parameters keep the soundfont default.
+
+## Effects
+
+All standard engine parameters work on GM voices. Filter, distort, spatialize:
+
+```forth
+gm s bass n 800 lpf 0.3 verb .
+gm s epiano n 0.5 delay 1.5 distort .
+gm s choir n 0.8 pan 2000 hpf .
+```
+
+## Preset Names
+
+| # | Name | # | Name | # | Name | # | Name |
+|---|------|---|------|---|------|---|------|
+| 0 | piano | 24 | guitar | 48 | strings | 72 | piccolo |
+| 1 | brightpiano | 25 | steelguitar | 49 | slowstrings | 73 | flute |
+| 4 | epiano | 26 | jazzguitar | 52 | choir | 74 | recorder |
+| 6 | harpsichord | 27 | cleangt | 56 | trumpet | 75 | panflute |
+| 7 | clavinet | 29 | overdrive | 57 | trombone | 79 | whistle |
+| 8 | celesta | 30 | distgt | 58 | tuba | 80 | ocarina |
+| 9 | glockenspiel | 33 | bass | 60 | horn | 81 | lead |
+| 10 | musicbox | 34 | pickbass | 61 | brass | 82 | sawlead |
+| 11 | vibraphone | 35 | fretless | 64 | sopranosax | 89 | pad |
+| 12 | marimba | 36 | slapbass | 65 | altosax | 90 | warmpad |
+| 13 | xylophone | 38 | synthbass | 66 | tenorsax | 91 | polysynth |
+| 14 | bells | 40 | violin | 67 | barisax | 104 | sitar |
+| 16 | organ | 41 | viola | 68 | oboe | 105 | banjo |
+| 19 | churchorgan | 42 | cello | 70 | bassoon | 108 | kalimba |
+| 21 | accordion | 43 | contrabass | 71 | clarinet | 114 | steeldrum |
+| 22 | harmonica | 45 | pizzicato | | | | |
+| | | 46 | harp | | | | |
+| | | 47 | timpani | | | | |
+
+Drums are on a separate bank: use `drums` or `percussion` as the `n` value.
+
+## Examples
+
+A simple GM drum pattern across four steps:
+
+```forth
+;; step 1: kick
+gm s drums n 36 note .
+
+;; step 2: closed hat
+gm s drums n 42 note 0.6 gain .
+
+;; step 3: snare
+gm s drums n 38 note .
+
+;; step 4: closed hat
+gm s drums n 42 note 0.6 gain .
+```
+
+Layer piano chords with randomness:
+
+```forth
+gm s piano n
+c4 e4 g4 3 choose note
+0.3 0.8 rand gain
+0.1 0.4 rand verb
+.
+```
+
+A bass line with envelope override:
+
+```forth
+gm s bass n
+c2 e2 g2 a2 4 cycle note
+0.01 attack 0.2 decay 0.0 sustain
+.
+```