Cagire/docs/midi_output.md

MIDI Output

Send MIDI messages using the m. word. Build up parameters on the stack, then emit. The system determines message type based on which parameters you set.

Note Messages

The default message type is a note. Set note and velocity, then emit:

60 note 100 velocity m.   ;; middle C, velocity 100
c4 note 80 velocity m.    ;; same pitch, lower velocity

Parameter	Stack	Range	Description
note	(n --)	0-127	MIDI note number
velocity	(n --)	0-127	Note velocity
chan	(n --)	1-16	MIDI channel
dur	(f --)	steps	Note duration
dev	(n --)	0-3	Output device slot

Duration (dur) is measured in steps. If not set, the note plays until the next step. Channel defaults to 1, device defaults to 0.

Control Change

Set both ccnum (controller number) and ccout (value) to send a CC message:

74 ccnum 64 ccout m.   ;; CC 74, value 64
1 ccnum 127 ccout m.   ;; mod wheel full

Parameter	Stack	Range	Description
ccnum	(n --)	0-127	Controller number
ccout	(n --)	0-127	Controller value

Pitch Bend

Set bend to send pitch bend. The range is -1.0 (full down) to 1.0 (full up), with 0.0 as center:

0.5 bend m.    ;; bend up halfway
-1.0 bend m.   ;; full bend down

Channel Pressure

Set pressure to send channel aftertouch:

64 pressure m.   ;; medium pressure

Program Change

Set program to send a program change message:

0 program m.    ;; select program 0
127 program m.  ;; select program 127

Message Priority

When multiple message types are set, only one is sent per emit. Priority order:

1. Control Change (if ccnum AND ccout set)
2. Pitch Bend
3. Channel Pressure
4. Program Change
5. Note (default)

To send multiple message types, use multiple emits:

74 ccnum 100 ccout m.   ;; CC first
60 note 100 velocity m. ;; then note

Real-Time Messages

Transport and clock messages for external synchronization:

Word	Description
mclock	Send MIDI clock pulse
mstart	Send MIDI start
mstop	Send MIDI stop
mcont	Send MIDI continue

These ignore all parameters and send immediately.