# 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.