dymokomi/luce-midi
Source of release 0.1.0
## MIDI 1.0 input and output through macOS CoreMIDI.
##
## `sources` and `destinations` list the endpoints. `Input.open` makes a
## CoreMIDI client and an input port, connects every source (or a chosen
## set, by unique id), and turns each incoming message into a fixed-size
## `Event` pushed into two single-producer/single-consumer rings: one the
## realtime audio thread drains at the start of each block (`audio`), one
## the main thread drains for recording, the activity light and learn
## (`main`). `Output` sends short messages now.
##
## Threads.
## - CoreMIDI's own high-priority (not realtime) thread runs the read proc:
## it parses the packets, pushes into both rings, and calls the wake once
## per packet list that put anything into the main ring. It allocates
## nothing and takes no lock.
## - The notify proc runs on the run loop of the thread that called
## `Input.open` (CoreMIDI's rule for MIDIClientCreate), so that thread must
## run a CFRunLoop (an app's main thread does; a tool pumps
## CFRunLoopRunInMode). On a setup or property change it reconnects the
## port to the current sources, bumps `generation` and calls the wake.
## - The audio thread only calls `Ring.next`/`Ring.drain` on `audio()`.
## - Everything else (`open`, `listen_to`, `listen_to_all`, `close`,
## `main()` draining, `generation`) belongs to the opening thread.
##
## Messages. Channel messages (note on/off, poly and channel pressure,
## control change, program change, pitch bend) and system common (MTC
## quarter frame F1, song position F2, song select F3, tune request F6)
## become events; running status is expanded. A note on with velocity 0
## is kept raw (status 9n, data2 0): callers treat it as a note off.
## SysEx (F0 ... F7) is dropped, as are its continuation packets.
## Real-time: clock F8, start FA, continue FB and stop FC are kept;
## active sensing FE, reset FF and the undefined F4, F5, F9, FD are dropped.
## A real-time byte between a message's data bytes does not disturb it.
import c
import memory
import platform
import strings
import interop
import result
import coremidi
from coremidi import Notification, Timebase
from luce_std import wake
## One MIDI message.
pub struct Event:
## The source endpoint's kMIDIPropertyUniqueID.
pub var source: i32
pub var status: u8
pub var data1: u8
pub var data2: u8
## When it arrived, in host nanoseconds (the mach clock).
pub var nanos: u64
# ---------------------------------------------------------------- parsing
## The byte stream state of one source: running status and SysEx.
pub struct Parser:
var current: u8
var need: u8
var have: u8
var first: u8
var sysex: bool
## Take one byte. When it completes a message, its status and data are
## written to `out` (source and nanos are left as they are) and the
## answer is true.
pub func feed(byte: u8, out: Event*) -> bool:
if byte >= 0xF8:
if byte == 0xF8 or byte == 0xFA or byte == 0xFB or byte == 0xFC:
out.status = byte
out.data1 = 0
out.data2 = 0
return true
return false
if byte >= 0x80:
self.sysex = byte == 0xF0
self.have = 0
self.current = 0
if byte < 0xF0:
self.current = byte
self.need = 1 if byte >= 0xC0 and byte < 0xE0 else 2
return false
if byte == 0xF6:
out.status = byte
out.data1 = 0
out.data2 = 0
return true
if byte == 0xF1 or byte == 0xF3:
self.current = byte
self.need = 1
elif byte == 0xF2:
self.current = byte
self.need = 2
return false
if self.sysex or self.current == 0:
return false
if self.have == 0 and self.need == 2:
self.first = byte
self.have = 1
return false
out.status = self.current
if self.need == 2:
out.data1 = self.first
out.data2 = byte
else:
out.data1 = byte
out.data2 = 0
self.have = 0
if self.current >= 0xF0:
self.current = 0
return true
## Parse `bytes` as one source's stream, writing up to `out.length` events
## stamped `source` and `nanos`; answers how many were written.
pub func parse(bytes: const u8[], source: i32, nanos: u64, out: Event[]) -> usize:
var parser = Parser(current = 0, need = 0, have = 0, first = 0, sysex = false)
var event = Event(source = source, status = 0, data1 = 0, data2 = 0, nanos = nanos)
var count: usize = 0
for byte in bytes:
if count >= out.length:
break
if parser.feed(byte, &event):
out[count] = event
count += 1
return count
# ---------------------------------------------------------------- rings
pub let ring_capacity: usize = 1024
## A single-producer/single-consumer ring of events. When full, a push
## drops the newest event and counts it.
pub struct Ring:
var events: Event[1024]
var written: @u64
var taken: @u64
var lost: @u64
## Producer only. False when the ring was full and `event` was dropped.
pub func push(event: Event) -> bool:
let written = self.written.load(.relaxed)
if written -% self.taken.load(.acquire) >= (u64)ring_capacity:
_ = self.lost.add(1, .relaxed)
return false
self.events[(usize)(written % (u64)ring_capacity)] = event
self.written.store(written +% 1, .release)
return true
## Consumer only. Take the oldest event into `out`; false when empty.
pub func next(out: Event*) -> bool:
let taken = self.taken.load(.relaxed)
if taken == self.written.load(.acquire):
return false
*out = self.events[(usize)(taken % (u64)ring_capacity)]
self.taken.store(taken +% 1, .release)
return true
## Consumer only. Take up to `out.length` events, oldest first; answers how many.
pub func drain(out: Event[]) -> usize:
let written = self.written.load(.acquire)
var taken = self.taken.load(.relaxed)
var count: usize = 0
while taken != written and count < out.length:
out[count] = self.events[(usize)(taken % (u64)ring_capacity)]
taken +%= 1
count += 1
self.taken.store(taken, .release)
return count
## Events waiting; either side may ask.
pub func pending() -> usize:
return (usize)(self.written.load(.acquire) -% self.taken.load(.acquire))
## Events dropped because the ring was full, since it was made.
pub func dropped() -> u64:
return self.lost.load(.relaxed)
# ---------------------------------------------------------------- endpoints
## A source or destination as `sources` and `destinations` list it.
pub struct Endpoint:
## kMIDIPropertyUniqueID: stable across runs and replugging.
pub var id: i32
pub var online: bool
var text: u8[128]
var length: usize
## kMIDIPropertyDisplayName, cut to 127 bytes.
pub func name() -> str:
return (str)self.text[0..<self.length]
## How many sources there are now.
pub func source_count() -> usize:
if not platform.macos:
return 0
return coremidi.MIDIGetNumberOfSources()
## Fill `out` with the current sources; answers how many were written.
pub func sources(out: Endpoint[]) -> usize:
if not platform.macos:
return 0
let count = coremidi.MIDIGetNumberOfSources()
var written: usize = 0
for index in 0..<count:
if written >= out.length:
break
let endpoint = coremidi.MIDIGetSource(index)
if endpoint == 0:
continue
out[written] = describe(endpoint)
written += 1
return written
## How many destinations there are now.
pub func destination_count() -> usize:
if not platform.macos:
return 0
return coremidi.MIDIGetNumberOfDestinations()
## Fill `out` with the current destinations; answers how many were written.
pub func destinations(out: Endpoint[]) -> usize:
if not platform.macos:
return 0
let count = coremidi.MIDIGetNumberOfDestinations()
var written: usize = 0
for index in 0..<count:
if written >= out.length:
break
let endpoint = coremidi.MIDIGetDestination(index)
if endpoint == 0:
continue
out[written] = describe(endpoint)
written += 1
return written
func describe(endpoint: u32) -> Endpoint:
var made: Endpoint
made.id = unique_id(endpoint)
made.online = true
let (offline_status, offline) = coremidi.MIDIObjectGetIntegerProperty(endpoint, coremidi.kMIDIPropertyOffline)
if offline_status == 0 and offline != 0:
made.online = false
let (name_status, named) = coremidi.MIDIObjectGetStringProperty(endpoint, coremidi.kMIDIPropertyDisplayName)
if name_status == 0:
if let text = named:
if coremidi.CFStringGetCString(text, &made.text[0], 128, coremidi.utf8):
var length: usize = 0
while length < 127 and made.text[length] != 0:
length += 1
made.length = length
coremidi.CFRelease(text)
return made
func unique_id(endpoint: u32) -> i32:
let (status, id) = coremidi.MIDIObjectGetIntegerProperty(endpoint, coremidi.kMIDIPropertyUniqueID)
return id if status == 0 else 0
# ---------------------------------------------------------------- input
pub let most_chosen: usize = 64
let most_connected: usize = 256
## What CoreMIDI's threads reach through their context; on the heap so the
## Input value may move. The rings, `generation` and the wake are shared;
## the rest belongs to the opening thread.
struct Shared:
var audio: Ring
var main: Ring
var generation: @u64
var call: (func(void*?) -> unit)?
var context: void*?
var numer: u64
var denom: u64
var client: u32
var port: u32
var everything: bool
var chosen: i32[64]
var chosen_count: usize
var connected: u32[256]
var connected_count: usize
pub struct Input:
var shared: Shared*?
var held: interop.Reference[wake.Waker]?
## Open an input listening to every source (`listen_to` narrows it).
## `on_wake(wake_context)` and `waker.wake()` (either, both or neither) are
## called on CoreMIDI's thread after events reach the main ring, and on
## the opening thread after the sources change; each must be safe on
## any thread and must not block. The waker is held until `close`.
pub static func open(waker: interop.Reference[wake.Waker]? = none, on_wake: (func(void*?) -> unit)? = none, wake_context: void*? = none, name: c.str = "luce-audio") -> Input!:
if not platform.macos:
error(result.unsupported, "MIDI is implemented on macOS only")
var input = Input(shared = none, held = none)
errdefer input.close()
let shared = try new Shared in memory.heap
input.shared = shared
var timebase = Timebase(numer = 0, denom = 0)
_ = coremidi.mach_timebase_info(&timebase)
shared.numer = (u64)(timebase.numer if timebase.numer != 0 else 1)
shared.denom = (u64)(timebase.denom if timebase.denom != 0 else 1)
shared.everything = true
if let told = waker:
let target = try told.get()
if let plain = on_wake:
_ = plain
error(result.invalid, "give a waker or a wake function, not both")
shared.call = call_waker
shared.context = (void*)target
input.held = told.clone()
elif let plain = on_wake:
shared.call = plain
shared.context = wake_context
let text = coremidi.CFStringCreateWithCString(none, name, coremidi.utf8) else error(result.failed, "could not make the client name")
defer coremidi.CFRelease(text)
let (client_status, client) = coremidi.MIDIClientCreate(text, notify_proc, (void*)shared)
try check(client_status, "MIDIClientCreate")
shared.client = client
let (port_status, port) = coremidi.MIDIInputPortCreate(client, text, read_proc, (void*)shared)
try check(port_status, "MIDIInputPortCreate")
shared.port = port
reconnect(shared)
return input
## Listen to the sources whose unique ids are in `ids` only (at most 64),
## present now or plugged in later.
pub func listen_to(ids: const i32[]) -> !:
let shared = self.shared else error(result.invalid, "the input is closed")
if ids.length > most_chosen:
error(result.invalid, "an input listens to at most 64 chosen sources")
for index in 0..<ids.length:
shared.chosen[index] = ids[index]
shared.chosen_count = ids.length
shared.everything = false
reconnect(shared)
## Listen to every source again.
pub func listen_to_all():
let shared = self.shared else return
shared.everything = true
reconnect(shared)
## Reconnect to the sources there are now; the notify proc does this on
## its own, and this is for a thread that runs no run loop.
pub func refresh():
let shared = self.shared else return
reconnect(shared)
## The ring the realtime audio thread drains; stays valid until `close`.
pub func audio() -> Ring*?:
let shared = self.shared else return none
return &shared.audio
## The ring the main thread drains; stays valid until `close`.
pub func main() -> Ring*?:
let shared = self.shared else return none
return &shared.main
## Advances whenever the set of sources or their properties change: a
## UI that saw another value lists the sources again.
pub func generation() -> u64:
let shared = self.shared else return 0
return shared.generation.load(.acquire)
## How many sources the port is connected to now.
pub func connected() -> usize:
let shared = self.shared else return 0
return shared.connected_count
## Dispose the port and the client, then free the rings and let the
## waker go. When it returns, neither proc is running or will run, so
## the audio thread must have stopped draining `audio()` first.
pub func close():
if let shared = self.shared:
if shared.port != 0:
_ = coremidi.MIDIPortDispose(shared.port)
if shared.client != 0:
_ = coremidi.MIDIClientDispose(shared.client)
free(shared) in memory.heap
self.shared = none
if let told = self.held:
self.held = none
told.release()
func call_waker(context: void*?):
let raw = context else return
let target = (wake.Waker*)raw
target.wake()
func wanted(shared: Shared*, id: i32) -> bool:
if shared.everything:
return true
for index in 0..<shared.chosen_count:
if shared.chosen[index] == id:
return true
return false
## Connect the port to every wanted source not yet connected, and
## disconnect the ones that are gone or no longer wanted.
func reconnect(shared: Shared*):
if shared.port == 0:
return
var now: u32[256] = ---
var now_count: usize = 0
let count = coremidi.MIDIGetNumberOfSources()
for index in 0..<count:
if now_count >= most_connected:
break
let endpoint = coremidi.MIDIGetSource(index)
if endpoint == 0:
continue
let id = unique_id(endpoint)
if not wanted(shared, id):
continue
now[now_count] = endpoint
now_count += 1
if not contains(shared.connected[0..<shared.connected_count], endpoint):
_ = coremidi.MIDIPortConnectSource(shared.port, endpoint, (void*?)(usize)(u32)id)
for index in 0..<shared.connected_count:
let old = shared.connected[index]
if not contains(now[0..<now_count], old):
_ = coremidi.MIDIPortDisconnectSource(shared.port, old)
for index in 0..<now_count:
shared.connected[index] = now[index]
shared.connected_count = now_count
func contains(endpoints: const u32[], endpoint: u32) -> bool:
for each in endpoints:
if each == endpoint:
return true
return false
## CoreMIDI's notify proc, on the opening thread's run loop.
func notify_proc(message: const Notification*, context: void*?):
let raw = context else return
let shared = (Shared*)raw
if message.id < coremidi.setup_changed or message.id > coremidi.property_changed:
return
if message.id == coremidi.setup_changed:
reconnect(shared)
_ = shared.generation.add(1, .release)
if let call = shared.call:
call(shared.context)
## CoreMIDI's read proc, on its own thread: one MIDIPacketList from the
## source whose unique id is `source_context`.
func read_proc(list: const void*, context: void*?, source_context: void*?):
let raw = context else return
let shared = (Shared*)raw
var source: i32 = 0
if let tag = source_context:
source = (i32)(usize)tag
let base = (const u8*)list
let packets = read_u32(base, 0)
var at: usize = 4
var parser = Parser(current = 0, need = 0, have = 0, first = 0, sysex = false)
var news = false
for _ in 0..<packets:
let stamp = read_u64(base, at)
let length = (usize)read_u16(base, at + 8)
let data = at + 10
var event = Event(source = source, status = 0, data1 = 0, data2 = 0, nanos = to_nanos(shared, stamp))
for index in 0..<length:
if parser.feed(base[data + index], &event):
_ = shared.audio.push(event)
_ = shared.main.push(event)
news = true
at = data + length
if platform.arm64:
# MIDIPacketNext aligns to 4 on arm64.
let address = (usize)base + at
at = (address + 3) // 4 * 4 - (usize)base
if news:
if let call = shared.call:
call(shared.context)
func to_nanos(shared: Shared*, ticks: u64) -> u64:
var stamp = ticks
if stamp == 0:
stamp = coremidi.mach_absolute_time()
return stamp // shared.denom * shared.numer + stamp % shared.denom * shared.numer // shared.denom
## Host nanoseconds now, on the clock events are stamped in.
pub func now_nanos() -> u64:
if not platform.macos:
return 0
var timebase = Timebase(numer = 0, denom = 0)
_ = coremidi.mach_timebase_info(&timebase)
let numer = (u64)(timebase.numer if timebase.numer != 0 else 1)
let denom = (u64)(timebase.denom if timebase.denom != 0 else 1)
let ticks = coremidi.mach_absolute_time()
return ticks // denom * numer + ticks % denom * numer // denom
func read_u16(base: const u8*, at: usize) -> u16:
return (u16)base[at] | (u16)base[at + 1] << 8
func read_u32(base: const u8*, at: usize) -> u32:
return (u32)base[at] | (u32)base[at + 1] << 8 | (u32)base[at + 2] << 16 | (u32)base[at + 3] << 24
func read_u64(base: const u8*, at: usize) -> u64:
return (u64)read_u32(base, at) | (u64)read_u32(base, at + 4) << 32
func check(status: i32, what: str) -> !:
if status != 0:
var text: u8[128]
let message = strings.format(text, f"{what} failed (OSStatus {status})") catch failure:
recover what
error(result.failed, message)
# ---------------------------------------------------------------- output
## Sends short messages to destinations, now.
pub struct Output:
var client: u32
var port: u32
pub static func open(name: c.str = "luce-audio out") -> Output!:
if not platform.macos:
error(result.unsupported, "MIDI is implemented on macOS only")
var output = Output(client = 0, port = 0)
errdefer output.close()
let text = coremidi.CFStringCreateWithCString(none, name, coremidi.utf8) else error(result.failed, "could not make the client name")
defer coremidi.CFRelease(text)
let (client_status, client) = coremidi.MIDIClientCreate(text, none, none)
try check(client_status, "MIDIClientCreate")
output.client = client
let (port_status, port) = coremidi.MIDIOutputPortCreate(client, text)
try check(port_status, "MIDIOutputPortCreate")
output.port = port
return output
## Send one message of 1 to 3 bytes (`status`, then `data1` and `data2`
## as the status needs) to the destination whose unique id is `destination`.
pub func send(destination: i32, status: u8, data1: u8 = 0, data2: u8 = 0) -> !:
if self.port == 0:
error(result.invalid, "the output is closed")
var endpoint: u32 = 0
let count = coremidi.MIDIGetNumberOfDestinations()
for index in 0..<count:
let candidate = coremidi.MIDIGetDestination(index)
if candidate != 0 and unique_id(candidate) == destination:
endpoint = candidate
break
if endpoint == 0:
error(result.invalid, "no MIDI destination has that id")
let length = message_length(status)
if length == 0:
error(result.invalid, "not a short MIDI message")
# MIDIPacketList: count, then one packet: time stamp 0 (now), length, data.
var list: u8[32]
list[0] = 1
list[12] = (u8)length
list[14] = status
list[15] = data1
list[16] = data2
try check(coremidi.MIDISend(self.port, endpoint, &list[0]), "MIDISend")
pub func close():
if self.port != 0:
_ = coremidi.MIDIPortDispose(self.port)
if self.client != 0:
_ = coremidi.MIDIClientDispose(self.client)
self.port = 0
self.client = 0
## Bytes in a short message with this status, or 0 for SysEx and non-status bytes.
pub func message_length(status: u8) -> usize:
if status < 0x80:
return 0
if status < 0xF0:
return 2 if status >= 0xC0 and status < 0xE0 else 3
if status == 0xF1 or status == 0xF3:
return 2
if status == 0xF2:
return 3
if status == 0xF0 or status == 0xF7 or status == 0xF4 or status == 0xF5 or status == 0xF9 or status == 0xFD:
return 0
return 1
# ---------------------------------------------------------------- tests
test "running status, two messages in a packet, and note on with velocity 0":
let bytes: u8[7] = [0x90, 60, 100, 64, 90, 60, 0]
var out: Event[8] = ---
let count = parse(bytes, 7, 1000, out)
assert(count == 3, "three notes")
assert(out[0].status == 0x90 and out[0].data1 == 60 and out[0].data2 == 100, "the first")
assert(out[1].status == 0x90 and out[1].data1 == 64 and out[1].data2 == 90, "running status")
assert(out[2].status == 0x90 and out[2].data1 == 60 and out[2].data2 == 0, "velocity 0 stays a note on")
assert(out[2].source == 7 and out[2].nanos == 1000, "stamped")
test "a SysEx is skipped and the message after it parses":
let bytes: u8[11] = [0xF0, 0x7E, 0x7F, 0x06, 0x01, 0xF7, 0xB0, 7, 127, 0xC1, 5]
var out: Event[8] = ---
let count = parse(bytes, 1, 0, out)
assert(count == 2, "the control change and the program change")
assert(out[0].status == 0xB0 and out[0].data1 == 7 and out[0].data2 == 127, "control change")
assert(out[1].status == 0xC1 and out[1].data1 == 5 and out[1].data2 == 0, "program change has one data byte")
test "SysEx data never runs on an earlier running status":
let bytes: u8[8] = [0x90, 60, 100, 0xF0, 1, 2, 3, 4]
var out: Event[8] = ---
assert(parse(bytes, 1, 0, out) == 1, "only the note")
test "real-time bytes interleave and keep running status":
let bytes: u8[8] = [0x90, 60, 0xF8, 100, 62, 0xFE, 101, 0xFA]
var out: Event[8] = ---
let count = parse(bytes, 1, 0, out)
assert(count == 4, "clock, note, note, start")
assert(out[0].status == 0xF8, "the clock comes first")
assert(out[1].status == 0x90 and out[1].data1 == 60 and out[1].data2 == 100, "the note around the clock")
assert(out[2].status == 0x90 and out[2].data1 == 62 and out[2].data2 == 101, "active sensing dropped, running status kept")
assert(out[3].status == 0xFA, "start")
test "a pitch bend and a song position":
let bytes: u8[6] = [0xE3, 0x00, 0x40, 0xF2, 0x10, 0x02]
var out: Event[4] = ---
assert(parse(bytes, 1, 0, out) == 2, "two")
assert(out[0].status == 0xE3 and out[0].data2 == 0x40, "bend")
assert(out[1].status == 0xF2 and out[1].data1 == 0x10 and out[1].data2 == 0x02, "song position")
test "the ring wraps around and keeps order":
let ring = try new Ring in memory.heap
defer free(ring) in memory.heap
var event = Event(source = 1, status = 0x90, data1 = 0, data2 = 0, nanos = 0)
var expected: u64 = 0
var taken = event
for round in 0..<5:
for i in 0..<700:
event.nanos = (u64)(round * 700 + i)
assert(ring.push(event), "room")
for _ in 0..<700:
assert(ring.next(&taken), "an event")
assert(taken.nanos == expected, "in order")
expected += 1
assert(not ring.next(&taken), "empty")
assert(ring.dropped() == 0, "nothing dropped")
test "a full ring drops the newest and counts it":
let ring = try new Ring in memory.heap
defer free(ring) in memory.heap
var event = Event(source = 1, status = 0x90, data1 = 0, data2 = 0, nanos = 0)
for i in 0..<ring_capacity + 3:
event.nanos = (u64)i
_ = ring.push(event)
assert(ring.pending() == ring_capacity, "full")
assert(ring.dropped() == 3, "three dropped")
var out: Event[1024] = ---
assert(ring.drain(out) == ring_capacity, "all of it")
assert(out[0].nanos == 0 and out[1023].nanos == 1023, "the oldest kept")
event.nanos = 5000
assert(ring.push(event), "room again")
assert(ring.next(&event) and event.nanos == 5000, "and it works")