Implement JACK backend

5 files changed, 909 insertions, 3 deletions

diff --git a/README.md b/README.md
index 3cdac99..f23e696 100644
--- a/README.md
+++ b/README.md
@@ -7,13 +7,14 @@ Currently, the MIDIMonster supports the following protocols:
 
 | Protocol			| Operating Systems	| Notes				| Backends			|
 |-------------------------------|-----------------------|-------------------------------|-------------------------------|
-| MIDI				| Linux, Windows	| Linux: via ALSA		| [`midi`](backends/midi.md), [`winmidi`](backends/winmidi.md) |
+| MIDI				| Linux, Windows	| Linux: via ALSA/JACK		| [`midi`](backends/midi.md), [`winmidi`](backends/winmidi.md), [`jack`](backends/jack.md) |
 | ArtNet			| Linux, Windows, OSX	| Version 4			| [`artnet`](backends/artnet.md)|
 | Streaming ACN (sACN / E1.31)	| Linux, Windows, OSX	|				| [`sacn`](backends/sacn.md)	|
 | OpenSoundControl (OSC)	| Linux, Windows, OSX	|				| [`osc`](backends/osc.md)	|
 | evdev input devices		| Linux			| Virtual output supported	| [`evdev`](backends/evdev.md)	|
 | Open Lighting Architecture	| Linux, OSX		|				| [`ola`](backends/ola.md)	|
 | MA Lighting Web Remote	| Linux, Windows, OSX	| GrandMA and dot2 (incl. OnPC)	| [`maweb`](backends/maweb.md)	|
+| JACK/LV2 Control Voltage (CV)	| Linux			|				| [`jack`](backends/jack.md)	|
 
 with additional flexibility provided by a [Lua scripting environment](backends/lua.md).
 
@@ -117,6 +118,7 @@ configuration options, channel specification syntax and any known problems or ot
 special information. These documentation files are located in the `backends/` directory.
 
 * [`midi` backend documentation](backends/midi.md)
+* [`jack` backend documentation](backends/jack.md)
 * [`winmidi` backend documentation](backends/winmidi.md)
 * [`artnet` backend documentation](backends/artnet.md)
 * [`sacn` backend documentation](backends/sacn.md)
@@ -137,10 +139,11 @@ This section will explain how to build the provided sources to be able to run
 In order to build the MIDIMonster, you'll need some libraries that provide
 support for the protocols to translate.
 
-* `libasound2-dev` (for the MIDI backend)
+* `libasound2-dev` (for the ALSA MIDI backend)
 * `libevdev-dev` (for the evdev backend)
 * `liblua5.3-dev` (for the lua backend)
 * `libola-dev` (for the optional OLA backend)
+* `libjack-jackd2-dev` (for the JACK backend)
 * `pkg-config` (as some projects and systems like to spread their files around)
 * `libssl-dev` (for the MA Web Remote backend)
 * A C compiler
diff --git a/backends/Makefile b/backends/Makefile
index 293b434..c5755c9 100644
--- a/backends/Makefile
+++ b/backends/Makefile
@@ -1,5 +1,5 @@
 .PHONY: all clean full
-LINUX_BACKENDS = midi.so evdev.so
+LINUX_BACKENDS = midi.so evdev.so jack.so
 WINDOWS_BACKENDS = artnet.dll osc.dll loopback.dll sacn.dll maweb.dll winmidi.dll
 BACKENDS = artnet.so osc.so loopback.so sacn.so lua.so maweb.so
 OPTIONAL_BACKENDS = ola.so
@@ -41,6 +41,7 @@ maweb.dll: CFLAGS += -DMAWEB_NO_LIBSSL
 winmidi.dll: ADDITIONAL_OBJS += $(BACKEND_LIB)
 winmidi.dll: LDLIBS += -lwinmm -lws2_32
 
+jack.so: LDLIBS = -ljack -lpthread
 midi.so: LDLIBS = -lasound
 evdev.so: CFLAGS += $(shell pkg-config --cflags libevdev)
 evdev.so: LDLIBS = $(shell pkg-config --libs libevdev)
diff --git a/backends/jack.c b/backends/jack.c
new file mode 100644
index 0000000..5a88cf2
--- /dev/null
+++ b/backends/jack.c
@@ -0,0 +1,742 @@
+#include <string.h>
+#include <signal.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <unistd.h>
+
+#include "jack.h"
+#include <jack/midiport.h>
+#include <jack/metadata.h>
+
+#define BACKEND_NAME "jack"
+#define JACKEY_SIGNAL_TYPE "http://jackaudio.org/metadata/signal-type"
+
+//FIXME pitchbend range is somewhat oob
+
+static struct /*_mmjack_backend_cfg*/ {
+	unsigned verbosity;
+	volatile sig_atomic_t jack_shutdown;
+} config = {
+	.verbosity = 1,
+	.jack_shutdown = 0
+};
+
+int init(){
+	backend mmjack = {
+		.name = BACKEND_NAME,
+		.conf = mmjack_configure,
+		.create = mmjack_instance,
+		.conf_instance = mmjack_configure_instance,
+		.channel = mmjack_channel,
+		.handle = mmjack_set,
+		.process = mmjack_handle,
+		.start = mmjack_start,
+		.shutdown = mmjack_shutdown
+	};
+
+	if(sizeof(mmjack_channel_ident) != sizeof(uint64_t)){
+		fprintf(stderr, "jack channel identification union out of bounds\n");
+		return 1;
+	}
+
+	//register backend
+	if(mm_backend_register(mmjack)){
+		fprintf(stderr, "Failed to register jack backend\n");
+		return 1;
+	}
+	return 0;
+}
+
+static void mmjack_message_print(const char* msg){
+	fprintf(stderr, "JACK message: %s\n", msg);
+}
+
+static void mmjack_message_ignore(const char* msg){
+}
+
+static int mmjack_midiqueue_append(mmjack_port* port, mmjack_channel_ident ident, uint16_t value){
+	//append events
+	if(port->queue_len == port->queue_alloc){
+		//extend the queue
+		port->queue = realloc(port->queue, (port->queue_len + JACK_MIDIQUEUE_CHUNK) * sizeof(mmjack_midiqueue));
+		if(!port->queue){
+			fprintf(stderr, "Failed to allocate memory\n");
+			return 1;
+		}
+		port->queue_alloc += JACK_MIDIQUEUE_CHUNK;
+	}
+
+	port->queue[port->queue_len].ident.label = ident.label;
+	port->queue[port->queue_len].raw = value;
+	port->queue_len++;
+	DBGPF("Appended event to queue for %s, now at %" PRIsize_t " entries\n", port->name, port->queue_len);
+	return 0;
+}
+
+static int mmjack_process_midi(instance* inst, mmjack_port* port, size_t nframes, size_t* mark){
+	void* buffer = jack_port_get_buffer(port->port, nframes);
+	jack_nframes_t event_count = jack_midi_get_event_count(buffer);
+	jack_midi_event_t event;
+	jack_midi_data_t* event_data;
+	mmjack_channel_ident ident;
+	size_t u;
+	uint16_t value;
+
+	if(port->input){
+		if(event_count){
+			DBGPF("Reading %u MIDI events from jack port %s\n", event_count, port->name);
+			for(u = 0; u < event_count; u++){
+				ident.label = 0;
+				//read midi data from stream
+				jack_midi_event_get(&event, buffer, u);
+				//ident.fields.port set on output in mmjack_handle_midi
+				ident.fields.sub_channel = event.buffer[0] & 0x0F;
+				ident.fields.sub_type = event.buffer[0] & 0xF0;
+				if(ident.fields.sub_type == 0x80){
+					ident.fields.sub_type = midi_note;
+					value = 0;
+				}
+				else if(ident.fields.sub_type == midi_pitchbend){
+					value = event.buffer[1] | (event.buffer[2] << 7);
+				}
+				else if(ident.fields.sub_type == midi_aftertouch){
+					value = event.buffer[1];
+				}
+				else{
+					ident.fields.sub_control = event.buffer[1];
+					value = event.buffer[2];
+				}
+				//append midi data
+				mmjack_midiqueue_append(port, ident, value);
+			}
+			port->mark = 1;
+			*mark = 1;
+		}
+	}
+	else{
+		//clear buffer
+		jack_midi_clear_buffer(buffer);
+
+		for(u = 0; u < port->queue_len; u++){
+			//build midi event
+			ident.label = port->queue[u].ident.label;
+			event_data = jack_midi_event_reserve(buffer, u, (ident.fields.sub_type == midi_aftertouch) ? 2 : 3);
+			if(!event_data){
+				fprintf(stderr, "Failed to reserve MIDI stream data\n");
+				return 1;
+			}
+			event_data[0] = ident.fields.sub_channel | ident.fields.sub_type;
+			if(ident.fields.sub_type == midi_pitchbend){
+				event_data[1] = port->queue[u].raw & 0x7F;
+				event_data[2] = (port->queue[u].raw >> 7) & 0x7F;
+			}
+			else if(ident.fields.sub_type == midi_aftertouch){
+				event_data[1] = port->queue[u].raw & 0x7F;
+			}
+			else{
+				event_data[1] = ident.fields.sub_control;
+				event_data[2] = port->queue[u].raw & 0x7F;
+			}
+		}
+
+		if(port->queue_len){
+			DBGPF("Wrote %" PRIsize_t " MIDI events to jack port %s\n", port->queue_len, port->name);
+		}
+		port->queue_len = 0;
+	}
+	return 0;
+}
+
+static int mmjack_process_cv(instance* inst, mmjack_port* port, size_t nframes, size_t* mark){
+	jack_default_audio_sample_t* audio_buffer = jack_port_get_buffer(port->port, nframes);
+	size_t u;
+
+	if(port->input){
+		//read updated data into the local buffer
+		//FIXME maybe we dont want to always use the first sample...
+		if((double) audio_buffer[0] != port->last){
+			port->last = audio_buffer[0];
+			port->mark = 1;
+			*mark = 1;
+		}
+	}
+	else{
+		for(u = 0; u < nframes; u++){
+			audio_buffer[u] = port->last;
+		}
+	}
+	return 0;
+}
+
+static int mmjack_process(jack_nframes_t nframes, void* instp){
+	instance* inst = (instance*) instp;
+	mmjack_instance_data* data = (mmjack_instance_data*) inst->impl;
+	size_t p, mark = 0;
+	int rv = 0;
+
+	//DBGPF("jack callback for %d frames on %s\n", nframes, inst->name);
+
+	for(p = 0; p < data->ports; p++){
+		pthread_mutex_lock(&data->port[p].lock);
+		switch(data->port[p].type){
+			case port_midi:
+				//DBGPF("Handling MIDI port %s.%s\n", inst->name, data->port[p].name);
+				rv |= mmjack_process_midi(inst, data->port + p, nframes, &mark);
+				break;
+			case port_cv:
+				//DBGPF("Handling CV port %s.%s\n", inst->name, data->port[p].name);
+				rv |= mmjack_process_cv(inst, data->port + p, nframes, &mark);
+				break;
+			default:
+				fprintf(stderr, "Unhandled jack port type in processing callback\n");
+				pthread_mutex_unlock(&data->port[p].lock);
+				return 1;
+		}
+		pthread_mutex_unlock(&data->port[p].lock);
+	}
+
+	//notify the main thread
+	if(mark){
+		DBGPF("Notifying handler thread for jack instance %s\n", inst->name);
+		send(data->fd, "c", 1, 0);
+	}
+	return rv;
+}
+
+static void mmjack_server_shutdown(void* inst){
+	fprintf(stderr, "jack server shutdown notification\n");
+	config.jack_shutdown = 1;
+}
+
+static int mmjack_configure(char* option, char* value){
+	if(!strcmp(option, "debug")){
+		if(!strcmp(value, "on")){
+			config.verbosity |= 2;
+			return 0;
+		}
+		config.verbosity &= ~2;
+		return 0;
+	}
+	if(!strcmp(option, "errors")){
+		if(!strcmp(value, "on")){
+			config.verbosity |= 1;
+			return 0;
+		}
+		config.verbosity &= ~1;
+		return 0;
+	}
+
+	fprintf(stderr, "Unknown jack backend option %s\n", option);
+	return 1;
+}
+
+static int mmjack_parse_portconfig(mmjack_port* port, char* spec){
+	char* token = NULL;
+
+	for(token = strtok(spec, " "); token; token = strtok(NULL, " ")){
+		if(!strcmp(token, "in")){
+			port->input = 1;
+		}
+		else if(!strcmp(token, "out")){
+			port->input = 0;
+		}
+		else if(!strcmp(token, "midi")){
+			port->type = port_midi;
+		}
+		else if(!strcmp(token, "osc")){
+			port->type = port_osc;
+		}
+		else if(!strcmp(token, "cv")){
+			port->type = port_cv;
+		}
+		else if(!strcmp(token, "max")){
+			token = strtok(NULL, " ");
+			if(!token){
+				fprintf(stderr, "jack port %s configuration missing argument\n", port->name);
+				return 1;
+			}
+			port->max = strtod(token, NULL);
+		}
+		else if(!strcmp(token, "min")){
+			token = strtok(NULL, " ");
+			if(!token){
+				fprintf(stderr, "jack port %s configuration missing argument\n", port->name);
+				return 1;
+			}
+			port->min = strtod(token, NULL);
+		}
+		else{
+			fprintf(stderr, "Unknown jack channel configuration token %s on port %s\n", token, port->name);
+			return 1;
+		}
+	}
+
+	if(port->type == port_none){
+		fprintf(stderr, "jack channel %s assigned no port type\n", port->name);
+		return 1;
+	}
+	return 0;
+}
+
+static int mmjack_configure_instance(instance* inst, char* option, char* value){
+	mmjack_instance_data* data = (mmjack_instance_data*) inst->impl;
+	size_t p;
+
+	if(!strcmp(option, "name")){
+		if(data->client_name){
+			free(data->client_name);
+		}
+		data->client_name = strdup(value);
+		return 0;
+	}
+	else if(!strcmp(option, "server")){
+		if(data->server_name){
+			free(data->server_name);
+		}
+		data->server_name = strdup(value);
+		return 0;
+	}
+
+	//register new port, first check for unique name
+	for(p = 0; p < data->ports; p++){
+		if(!strcmp(data->port[p].name, option)){
+			fprintf(stderr, "jack instance %s has duplicate port %s\n", inst->name, option);
+			return 1;
+		}
+	}
+	if(strchr(option, '.')){
+		fprintf(stderr, "Invalid jack channel spec %s.%s\n", inst->name, option);
+	}
+
+	//add port to registry
+	//TODO for OSC ports we need to configure subchannels for each message
+	data->port = realloc(data->port, (data->ports + 1) * sizeof(mmjack_port));
+	if(!data->port){
+		fprintf(stderr, "Failed to allocate memory\n");
+		return 1;
+	}
+	data->port[data->ports].name = strdup(option);
+	if(!data->port[data->ports].name){
+		fprintf(stderr, "Failed to allocate memory\n");
+		return 1;
+	}
+	if(mmjack_parse_portconfig(data->port + p, value)){
+		return 1;
+	}
+	data->ports++;
+	return 0;
+}
+
+static instance* mmjack_instance(){
+	instance* inst = mm_instance();
+	if(!inst){
+		return NULL;
+	}
+
+	inst->impl = calloc(1, sizeof(mmjack_instance_data));
+	if(!inst->impl){
+		fprintf(stderr, "Failed to allocate memory\n");
+		return NULL;
+	}
+
+	return inst;
+}
+
+static int mmjack_parse_midispec(mmjack_channel_ident* ident, char* spec){
+	char* next_token = NULL;
+
+	if(!strncmp(spec, "ch", 2)){
+		next_token = spec + 2;
+		if(!strncmp(spec, "channel", 7)){
+			next_token = spec + 7;
+		}
+	}
+
+	if(!next_token){
+		fprintf(stderr, "Invalid jack MIDI spec %s\n", spec);
+		return 1;
+	}
+
+	ident->fields.sub_channel = strtoul(next_token, &next_token, 10);
+	if(ident->fields.sub_channel > 15){
+		fprintf(stderr, "Invalid jack MIDI spec %s, channel out of range\n", spec);
+		return 1;
+	}
+
+	if(*next_token != '.'){
+		fprintf(stderr, "Invalid jack MIDI spec %s\n", spec);
+		return 1;
+	}
+
+	next_token++;
+
+	if(!strncmp(next_token, "cc", 2)){
+		ident->fields.sub_type = midi_cc;
+		next_token += 2;
+	}
+	else if(!strncmp(next_token, "note", 4)){
+		ident->fields.sub_type = midi_note;
+		next_token += 4;
+	}
+	else if(!strncmp(next_token, "pressure", 8)){
+		ident->fields.sub_type = midi_pressure;
+		next_token += 8;
+	}
+	else if(!strncmp(next_token, "pitch", 5)){
+		ident->fields.sub_type = midi_pitchbend;
+	}
+	else if(!strncmp(next_token, "aftertouch", 10)){
+		ident->fields.sub_type = midi_aftertouch;
+	}
+	else{
+		fprintf(stderr, "Unknown jack MIDI control type in spec %s\n", spec);
+		return 1;
+	}
+
+	ident->fields.sub_control = strtoul(next_token, NULL, 10);
+
+	if(ident->fields.sub_type == midi_none
+			|| ident->fields.sub_control > 127){
+		fprintf(stderr, "Invalid jack MIDI spec %s\n", spec);
+		return 1;
+	}
+	return 0;
+}
+
+static channel* mmjack_channel(instance* inst, char* spec){
+	mmjack_instance_data* data = (mmjack_instance_data*) inst->impl;
+	mmjack_channel_ident ident = {
+		.label = 0
+	};
+	size_t u;
+
+	for(u = 0; u < data->ports; u++){
+		if(!strncmp(spec, data->port[u].name, strlen(data->port[u].name))
+				&& (spec[strlen(data->port[u].name)] == '.' || spec[strlen(data->port[u].name)] == 0)){
+			ident.fields.port = u;
+			break;
+		}
+	}
+
+	if(u == data->ports){
+		fprintf(stderr, "jack port %s.%s not found\n", inst->name, spec);
+		return NULL;
+	}
+
+	if(data->port[u].type == port_midi){
+		//parse midi subspec
+		if(!spec[strlen(data->port[u].name)]
+				|| mmjack_parse_midispec(&ident, spec + strlen(data->port[u].name) + 1)){
+			return NULL;
+		}
+	}
+	else if(data->port[u].type == port_osc){
+		//TODO parse osc subspec
+	}
+
+	return mm_channel(inst, ident.label, 1);
+}
+
+static int mmjack_set(instance* inst, size_t num, channel** c, channel_value* v){
+	mmjack_instance_data* data = (mmjack_instance_data*) inst->impl;
+	mmjack_channel_ident ident = {
+		.label = 0
+	};
+	size_t u;
+	double range;
+	uint16_t value;
+
+	for(u = 0; u < num; u++){
+		ident.label = c[u]->ident;
+
+		if(data->port[ident.fields.port].input){
+			fprintf(stderr, "jack port %s.%s is an input port, no output is possible\n", inst->name, data->port[ident.fields.port].name);
+			continue;
+		}
+		range = data->port[ident.fields.port].max - data->port[ident.fields.port].min;
+
+		pthread_mutex_lock(&data->port[ident.fields.port].lock);
+		switch(data->port[ident.fields.port].type){
+			case port_cv:
+				//scale value to given range
+				data->port[ident.fields.port].last = (range * v[u].normalised) + data->port[ident.fields.port].min;
+				DBGPF("CV port %s updated to %f\n", data->port[ident.fields.port].name, data->port[ident.fields.port].last);
+				break;
+			case port_midi:
+				value = v[u].normalised * 127.0;
+				if(ident.fields.sub_type == midi_pitchbend){
+					value = ((uint16_t)(v[u].normalised * 16384.0));
+				}
+				if(mmjack_midiqueue_append(data->port + ident.fields.port, ident, value)){
+					pthread_mutex_unlock(&data->port[ident.fields.port].lock);
+					return 1;
+				}
+				break;
+			default:
+				fprintf(stderr, "No handler implemented for jack port type %s.%s\n", inst->name, data->port[ident.fields.port].name);
+				break;
+		}
+		pthread_mutex_unlock(&data->port[ident.fields.port].lock);
+	}
+
+	return 0;
+}
+
+static void mmjack_handle_midi(instance* inst, size_t index, mmjack_port* port){
+	size_t u;
+	channel* chan = NULL;
+	channel_value val;
+
+	for(u = 0; u < port->queue_len; u++){
+		port->queue[u].ident.fields.port = index;
+		chan = mm_channel(inst, port->queue[u].ident.label, 0);
+		if(chan){
+			if(port->queue[u].ident.fields.sub_type == midi_pitchbend){
+				val.normalised = ((double)port->queue[u].raw) / 16384.0;
+			}
+			else{
+				val.normalised = ((double)port->queue[u].raw) / 127.0;
+			}
+			DBGPF("Pushing MIDI channel %d type %02X control %d value %f raw %d label %" PRIu64 "\n",
+					port->queue[u].ident.fields.sub_channel,
+					port->queue[u].ident.fields.sub_type,
+					port->queue[u].ident.fields.sub_control,
+					val.normalised,
+					port->queue[u].raw,
+					port->queue[u].ident.label);
+			if(mm_channel_event(chan, val)){
+				fprintf(stderr, "Failed to push MIDI event to core on jack port %s.%s\n", inst->name, port->name);
+			}
+		}
+	}
+
+	if(port->queue_len){
+		DBGPF("Pushed %" PRIsize_t " MIDI events to core for jack port %s.%s\n", port->queue_len, inst->name, port->name);
+	}
+	port->queue_len = 0;
+}
+
+static void mmjack_handle_cv(instance* inst, size_t index, mmjack_port* port){
+	mmjack_channel_ident ident = {
+		.fields.port = index
+	};
+	double range;
+	channel_value val;
+
+	channel* chan = mm_channel(inst, ident.label, 0);
+	if(!chan){
+		//this might happen if a channel is registered but not mapped
+		DBGPF("Failed to match jack CV channel %s.%s to core channel\n", inst->name, port->name);
+		return;
+	}
+
+	//normalize value
+	range = port->max - port->min;
+	val.normalised = port->last - port->min;
+	val.normalised /= range;
+	val.normalised = clamp(val.normalised, 1.0, 0.0);
+	DBGPF("Pushing CV channel %s value %f raw %f min %f max %f\n", port->name, val.normalised, port->last, port->min, port->max);
+	if(mm_channel_event(chan, val)){
+		fprintf(stderr, "Failed to push CV event to core for %s.%s\n", inst->name, port->name);
+	}
+}
+
+static int mmjack_handle(size_t num, managed_fd* fds){
+	size_t u, p;
+	instance* inst = NULL;
+	mmjack_instance_data* data = NULL;
+	ssize_t bytes;
+	uint8_t recv_buf[1024];
+
+	if(num){
+		for(u = 0; u < num; u++){
+			bytes = recv(fds[u].fd, recv_buf, sizeof(recv_buf), 0);
+			if(bytes < 0){
+				fprintf(stderr, "Failed to receive on feedback socket for instance %s\n", inst->name);
+				return 1;
+			}
+			inst = (instance*) fds[u].impl;
+			data = (mmjack_instance_data*) inst->impl;
+
+			for(p = 0; p < data->ports; p++){
+				if(data->port[p].input && data->port[p].mark){
+					pthread_mutex_lock(&data->port[p].lock);
+					switch(data->port[p].type){
+						case port_cv:
+							mmjack_handle_cv(inst, p, data->port + p);
+							break;
+						case port_midi:
+							mmjack_handle_midi(inst, p, data->port + p);
+							break;
+						default:
+							fprintf(stderr, "Output handler not implemented for unknown jack channel type on %s.%s\n", inst->name, data->port[p].name);
+							break;
+					}
+
+					data->port[p].mark = 0;
+					pthread_mutex_unlock(&data->port[p].lock);
+				}
+			}
+		}
+	}
+	
+	if(config.jack_shutdown){
+		fprintf(stderr, "JACK server disconnected\n");
+		return 1;
+	}
+	return 0;
+}
+
+static int mmjack_start(){
+	int rv = 1, feedback_fd[2];
+	size_t n, u, p;
+	instance** inst = NULL;
+	pthread_mutexattr_t mutex_attr;
+	mmjack_instance_data* data = NULL;
+	jack_status_t error;
+
+	//set jack logging functions
+	jack_set_error_function(mmjack_message_ignore);
+	if(config.verbosity & 1){
+		jack_set_error_function(mmjack_message_print);
+	}
+	jack_set_info_function(mmjack_message_ignore);
+	if(config.verbosity & 2){
+		jack_set_info_function(mmjack_message_print);
+	}
+
+	//prepare mutex attributes because the initializer macro for adaptive mutexes is a GNU extension...
+	if(pthread_mutexattr_init(&mutex_attr)
+			|| pthread_mutexattr_settype(&mutex_attr, PTHREAD_MUTEX_ADAPTIVE_NP)){
+		fprintf(stderr, "Failed to initialize mutex attributes\n");
+		goto bail;
+	}
+
+	//fetch all instances
+	if(mm_backend_instances(BACKEND_NAME, &n, &inst)){
+		fprintf(stderr, "Failed to fetch instance list\n");
+		goto bail;
+	}
+
+	for(u = 0; u < n; u++){
+		data = (mmjack_instance_data*) inst[u]->impl;
+
+		//connect to the jack server
+		data->client = jack_client_open(data->client_name ? data->client_name : JACK_DEFAULT_CLIENT_NAME,
+				JackServerName | JackNoStartServer,
+				&error,
+				data->server_name ? data->server_name : JACK_DEFAULT_SERVER_NAME);
+
+		if(!data->client){
+			//TODO pretty-print failures
+			fprintf(stderr, "jack backend failed to connect to server, return status %u\n", error);
+			goto bail;
+		}
+
+		//set up the feedback fd
+		if(socketpair(AF_LOCAL, SOCK_DGRAM, 0, feedback_fd)){
+			fprintf(stderr, "Failed to create feedback socket pair\n");
+			goto bail;
+		}
+
+		data->fd = feedback_fd[0];
+		if(mm_manage_fd(feedback_fd[1], BACKEND_NAME, 1, inst[u])){
+			fprintf(stderr, "jack backend failed to register feedback fd with core\n");
+			goto bail;
+		}
+
+		//connect jack callbacks
+		jack_set_process_callback(data->client, mmjack_process, inst[u]);
+		jack_on_shutdown(data->client, mmjack_server_shutdown, inst[u]);
+
+		fprintf(stderr, "jack instance %s assigned client name %s\n", inst[u]->name, jack_get_client_name(data->client));
+
+		//create and initialize jack ports
+		for(p = 0; p < data->ports; p++){
+			if(pthread_mutex_init(&(data->port[p].lock), &mutex_attr)){
+				fprintf(stderr, "Failed to create port mutex\n");
+				goto bail;
+			}
+
+			data->port[p].port = jack_port_register(data->client,
+					data->port[p].name,
+					(data->port[p].type == port_cv) ? JACK_DEFAULT_AUDIO_TYPE : JACK_DEFAULT_MIDI_TYPE,
+					data->port[p].input ? JackPortIsInput : JackPortIsOutput,
+					0);
+
+			jack_set_property(data->client, jack_port_uuid(data->port[p].port), JACKEY_SIGNAL_TYPE, "CV", "text/plain");
+
+			if(!data->port[p].port){
+				fprintf(stderr, "Failed to create jack port %s.%s\n", inst[u]->name, data->port[p].name);
+				return 1;
+			}
+		}
+
+		//do the thing
+		if(jack_activate(data->client)){
+			fprintf(stderr, "Failed to activate jack client for instance %s\n", inst[u]->name);
+			return 1;
+		}
+	}
+
+	fprintf(stderr, "jack backend registered %" PRIsize_t " descriptors to core\n", n);
+	rv = 0;
+bail:
+	pthread_mutexattr_destroy(&mutex_attr);
+	free(inst);
+	return rv;
+}
+
+static int mmjack_shutdown(){
+	size_t n, u, p;
+	instance** inst = NULL;
+	mmjack_instance_data* data = NULL;
+
+	if(mm_backend_instances(BACKEND_NAME, &n, &inst)){
+		fprintf(stderr, "Failed to fetch instance list\n");
+		return 1;
+	}
+
+	for(u = 0; u < n; u++){
+		data = (mmjack_instance_data*) inst[u]->impl;
+
+		//deactivate client to stop processing before free'ing channel data
+		if(data->client){
+			jack_deactivate(data->client);
+		}
+
+		//iterate and close ports
+		for(p = 0; p < data->ports; p++){
+			jack_remove_property(data->client, jack_port_uuid(data->port[p].port), JACKEY_SIGNAL_TYPE);
+			if(data->port[p].port){
+				jack_port_unregister(data->client, data->port[p].port);
+			}
+			free(data->port[p].name);
+			data->port[p].name = NULL;
+
+			free(data->port[p].queue);
+			data->port[p].queue = NULL;
+			data->port[p].queue_alloc = data->port[p].queue_len = 0;
+
+			pthread_mutex_destroy(&data->port[p].lock);
+		}
+
+		//terminate jack connection
+		if(data->client){
+			jack_client_close(data->client);
+		}
+
+		//clean up instance data
+		free(data->server_name);
+		data->server_name = NULL;
+		free(data->client_name);
+		data->client_name = NULL;
+		close(data->fd);
+		data->fd = -1;
+	}
+
+	free(inst);
+
+	fprintf(stderr, "jack backend shut down\n");
+	return 0;
+}
diff --git a/backends/jack.h b/backends/jack.h
new file mode 100644
index 0000000..dd59cd2
--- /dev/null
+++ b/backends/jack.h
@@ -0,0 +1,76 @@
+#include "midimonster.h"
+#include <jack/jack.h>
+#include <pthread.h>
+
+int init();
+static int mmjack_configure(char* option, char* value);
+static int mmjack_configure_instance(instance* inst, char* option, char* value);
+static instance* mmjack_instance();
+static channel* mmjack_channel(instance* inst, char* spec);
+static int mmjack_set(instance* inst, size_t num, channel** c, channel_value* v);
+static int mmjack_handle(size_t num, managed_fd* fds);
+static int mmjack_start();
+static int mmjack_shutdown();
+
+#define JACK_DEFAULT_CLIENT_NAME "MIDIMonster"
+#define JACK_DEFAULT_SERVER_NAME "default"
+#define JACK_MIDIQUEUE_CHUNK 10
+
+enum /*mmjack_midi_channel_type*/ {
+	midi_none = 0,
+	midi_note = 0x90,
+	midi_cc = 0xB0,
+	midi_pressure = 0xA0,
+	midi_aftertouch = 0xD0,
+	midi_pitchbend = 0xE0
+};
+
+typedef union {
+	struct {
+		uint32_t port;
+		uint8_t pad;
+		uint8_t sub_type;
+		uint8_t sub_channel;
+		uint8_t sub_control;
+	} fields;
+	uint64_t label;
+} mmjack_channel_ident;
+
+typedef enum /*_mmjack_port_type*/ {
+	port_none = 0,
+	port_midi,
+	port_osc,
+	port_cv
+} mmjack_port_type;
+
+typedef struct /*_mmjack_midiqueue_entry*/ {
+	mmjack_channel_ident ident;
+	uint16_t raw;
+} mmjack_midiqueue;
+
+typedef struct /*_mmjack_port_data*/ {
+	char* name;
+	mmjack_port_type type;
+	uint8_t input;
+	jack_port_t* port;
+
+	double max;
+	double min;
+	uint8_t mark;
+	double last;
+	size_t queue_len;
+	size_t queue_alloc;
+	mmjack_midiqueue* queue;
+
+	pthread_mutex_t lock;
+} mmjack_port;
+
+typedef struct /*_jack_instance_data*/ {
+	char* server_name;
+	char* client_name;
+	int fd;
+
+	jack_client_t* client;
+	size_t ports;
+	mmjack_port* port;
+} mmjack_instance_data;
diff --git a/backends/jack.md b/backends/jack.md
new file mode 100644
index 0000000..b6ff5a9
--- /dev/null
+++ b/backends/jack.md
@@ -0,0 +1,84 @@
+### The `jack` backend
+
+This backend provides read-write access to the JACK Audio Connection Kit low-latency audio transport server for the
+transport of control data via either JACK midi ports or control voltage (CV) inputs and outputs.
+
+#### Global configuration
+
+| Option	| Example value		| Default value 	| Description		|
+|---------------|-----------------------|-----------------------|-----------------------|
+| `debug`	| `on`			| `off`			| Print `info` level notices from the JACK connection	|
+| `errors`      | `on`                  | `off`                 | Print `error` level notices from the JACK connection	|
+
+#### Instance configuration
+
+| Option	| Example value		| Default value 	| Description		|
+|---------------|-----------------------|-----------------------|-----------------------|
+| `name`	| `Controller`		| `MIDIMonster`		| Client name for the JACK connection |
+| `server`	| `jackserver`		| `default`		| JACK server identifier to connect to |
+
+Channels (corresponding to JACK ports) need to be configured with their type and, if applicable, value limits.
+To configure a port, specify it in the instance configuration using the following syntax:
+
+```
+port_name = <type> <direction> min <minimum> max <maximum>
+```
+
+Port names may be any string except for the instance configuration keywords `name` and `server`.
+
+The following `type` values are currently supported:
+
+* `midi`: JACK MIDI port for transmitting MIDI event messages
+* `cv`: JACK audio port for transmitting DC offset "control voltage" samples (requires `min`/`max` configuration)
+
+`direction` may be one of `in` or `out`, as seen from the perspective of the MIDIMonster core, thus
+`in` means data is being read from the JACK server and `out` transfers data into the JACK server.
+
+The following example instance configuration would create a MIDI port sending data into JACK, a control voltage output
+sending data between `-1` and `1`, and a control voltage input receiving data with values between `0` and `10`.
+
+```
+midi_out = midi out
+cv_out = cv out min -1 max 1
+cv_in = cv in min 0.0 max 10.0
+```
+
+Input CV samples outside the configured range will be clipped. The MIDIMonster will not generate output CV samples
+outside of the configured range.
+
+#### Channel specification
+
+CV ports are exposed as single MIDIMonster channel and directly map to their normalised values.
+
+MIDI ports provide subchannels for the various MIDI controls available. Each MIDI port carries
+16 MIDI channels (numbered 0 through 15), each of which has 128 note controls (numbered 0 through 127),
+corresponding pressure controls for each note, 128 control change (CC) controls (numbered likewise),
+one channel wide "aftertouch" control and one channel-wide pitchbend control.
+
+A MIDI port subchannel is specified using the syntax `channel<channel>.<type><index>`. The shorthand `ch` may be
+used instead of the word `channel` (Note that `channel` here refers to the MIDI channel number).
+
+The following values are recognized for `type`:
+
+* `cc` - Control Changes
+* `note` - Note On/Off messages
+* `pressure` - Note pressure/aftertouch messages
+* `aftertouch` - Channel-wide aftertouch messages
+* `pitch` - Channel pitchbend messages
+
+The `pitch` and `aftertouch` events are channel-wide, thus they can be specified as `channel<channel>.<type>`.
+
+Example mappings:
+```
+jack1.cv_in > jack1.midi_out.ch0.note3
+jack1.midi_in.ch0.pitch > jack1.cv_out
+```
+
+The MIDI subchannel syntax is intentionally kept compatible to the different MIDI backends also supported
+by the MIDIMonster
+
+#### Known bugs / problems
+
+While JACK has rudimentary capabilities for transporting OSC messages, configuring and parsing such channels
+with this backend would take a great amount of dedicated syntax & code. CV ports can provide fine-grained single
+control channels as an alternative to MIDI. This feature may be implemented at some point in the future.