MIDI Documentation and optional mouse event support

docs/midi_input.md

@@ -0,0 +1,68 @@
+# MIDI Input
+
+Read incoming MIDI control change values with the `ccval` word. This lets you use hardware controllers to modulate parameters in your scripts.
+
+## Reading CC Values
+
+The `ccval` word takes a CC number and channel from the stack, and returns the last received value:
+
+```forth
+1 1 ccval   ;; read CC 1 (mod wheel) on channel 1
+```
+
+Stack effect: `(cc chan -- val)`
+
+The returned value is `0`-`127`. If no message has been received for that CC/channel combination, the value is `0`.
+
+## Device Selection
+
+Use `dev` to select which input device slot to read from:
+
+```forth
+1 dev 1 1 ccval   ;; read from device slot 1
+```
+
+Device defaults to `0` if not specified.
+
+## Practical Examples
+
+Map a controller knob to filter cutoff:
+
+```forth
+74 1 ccval 127 / 200 2740 range lpf
+```
+
+Use mod wheel for vibrato depth:
+
+```forth
+1 1 ccval 127 / 0 0.5 range vibdepth
+```
+
+Crossfade between two sounds:
+
+```forth
+1 1 ccval 127 /    ;; normalize to 0.0-1.0
+dup saw s swap gain .
+1 swap - tri s swap gain .
+```
+
+## Scaling Values
+
+CC values are integers `0`-`127`. Normalize to `0.0`-`1.0` first, then use `range` to scale:
+
+```forth
+;; normalize to 0.0-1.0
+74 1 ccval 127 /
+
+;; scale to custom range (e.g., 200-4000)
+74 1 ccval 127 / 200 4000 range
+
+;; bipolar range (-1.0 to 1.0)
+74 1 ccval 127 / -1 1 range
+```
+
+The `range` word takes a normalized value (`0.0`-`1.0`) and scales it to your target range: `(val min max -- scaled)`.
+
+## Latency
+
+CC values are sampled at the start of each step. Changes during a step take effect on the next step. For smoothest results, turn knobs slowly or use higher step rates.

docs/midi_intro.md

@@ -0,0 +1,26 @@
+# MIDI
+
+Cagire speaks MIDI. You can send notes, control changes, and other messages to external synthesizers, drum machines, and DAWs. You can also read incoming control change values from MIDI controllers and use them to modulate your scripts.
+
+## Device Slots
+
+Cagire provides four input slots and four output slots, numbered `0` through `3`. Each slot can connect to one MIDI device. By default, slot `0` is used for both input and output.
+
+## Configuration
+
+Configure your MIDI devices in the **Options** view. Select input and output devices for each slot. Changes take effect immediately.
+
+## MIDI vs Audio
+
+The audio engine (`Doux`) and MIDI are independent systems. Use `.` to emit audio commands, use `m.` to emit MIDI messages. You can use both in the same script:
+
+```forth
+saw s c4 note 0.5 gain .  ;; audio
+60 note 100 velocity m.   ;; MIDI
+```
+
+MIDI is useful when you want to sequence external gear, layer Cagire with hardware synths, or integrate into a larger studio setup. The audio engine is self-contained and needs no external equipment.
+
+## Clock and Transport
+
+Cagire can send MIDI clock and transport messages to synchronize external gear. Use `mclock` to send a single clock pulse, and `mstart`, `mstop`, `mcont` for transport control. MIDI clock requires 24 pulses per quarter note, so you need to call `mclock` at the appropriate rate for your tempo.

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.