dymokomi/luce-midi
Source of release 0.1.0
0.1.0 / README.md
# luce-midi
MIDI for Luce programs. macOS (CoreMIDI) first; Windows and Linux answer
`unsupported` for now.
## Modules
- `midi` — list the MIDI sources and destinations; open an input that
hears every source (or a chosen set, by unique id), turning each message
into a fixed-size `Event` stamped on the host clock in nanoseconds; send
short messages through an `Output`.
## Two rings, two threads
An `Input` pushes every message into two lock-free single-producer rings:
- `audio()` for a realtime audio thread, drained at the start of each block
so notes play with no lock and no allocation;
- `main()` for the UI thread, for recording, an activity light or MIDI learn.
The read proc runs on CoreMIDI's own (non-realtime) thread and calls a wake
you pass to `Input.open` — a luce-std `wake.Waker` (a luce-ui
`Notifier.waker()`), or a plain function and context — so the UI hears new
messages without polling. The sources coming and going reconnect the port,
bump `generation` and wake the same way.
```
from luce_midi import midi
var input = try midi.Input.open(waker = notifier_waker)
defer input.close()
var event: midi.Event
let ring = input.main() else return
while ring.next(&event):
# event.status, event.data1, event.data2, event.source, event.nanos
```
## Messages
Channel messages and system common become events, running status expanded.
A note on with velocity 0 is kept raw (callers treat it as a note off).
SysEx is dropped; clock, start, continue and stop are kept; active sensing
is dropped. See the module header in `src/midi.lucb` for the details.
## Tools
`tools/midi-probe` lists the sources and destinations and logs what comes
in for a few seconds; given a destination id it sends a note and listens
for it back (a loopback through a virtual bus).
## Licence
MIT or Apache-2.0, at your option.