# 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 snd piano n .              ;; acoustic piano
gm snd strings n c4 note .    ;; strings playing middle C
gm snd 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 snd drums n 36 note .      ;; kick
gm snd drums n 38 note .      ;; snare
gm snd drums n 42 note .      ;; closed hi-hat
gm snd 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 snd piano n 0.01 attack 0.3 decay .
gm snd 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 snd bass n 800 lpf 0.3 verb .
gm snd epiano n 0.5 delay 1.5 distort .
gm snd 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 snd drums n 36 note .

;; step 2: closed hat
gm snd drums n 42 note 0.6 gain .

;; step 3: snare
gm snd drums n 38 note .

;; step 4: closed hat
gm snd drums n 42 note 0.6 gain .
```

Layer piano chords with randomness:

```forth
gm snd 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 snd bass n
c2 e2 g2 a2 4 cycle note
0.01 attack 0.2 decay 0.0 sustain
.
```