Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-midi

Source of release 0.1.0

0.1.0 / src / midi.lucb

## 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")