Cagire/docs/tutorials/soundfont.md

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

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:

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:

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:

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:

;; 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:

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:

gm snd bass n
c2 e2 g2 a2 4 cycle note
0.01 attack 0.2 decay 0.0 sustain
.