Feat: refactoring codebase

docs/midi/output.md

@@ -0,0 +1,92 @@
+# 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:
+
+```forth
+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:
+
+```forth
+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:
+
+```forth
+0.5 bend m.    ;; bend up halfway
+-1.0 bend m.   ;; full bend down
+```
+
+## Channel Pressure
+
+Set `pressure` to send channel aftertouch:
+
+```forth
+64 pressure m.   ;; medium pressure
+```
+
+## Program Change
+
+Set `program` to send a program change message:
+
+```forth
+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:
+
+```forth
+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.