jamidi/README.md

Jamidi v0.1b 
By llstr, Sam Neurohack

LICENCE : CC NC

Midi and more exchanges over LAN/Internet 

Imagine Bob own a TR 808 at home and Alice a nozoid OCS-2. They can control each other devices in a webpage or a midi controller.
If John has a mutliple encoders midi controller at home and want to control Alice and Bob devices, all changes made by John will be displayed to everyone and played by devices.

More you can use also a vcvrack complex patch to drive light fixtures, laser abstract generators, midi instruments, wherever they are...





# Jamidi features

- Jamidi vs rtpmidi ? rtpmidi is transport efficiency, but bound to midi specifications. Jamidi support midi cc and note but is more OSC style : you can add any type of "command".

- Jamidi is websocket based, so accept anything (webpage, home made client,...). 

- Jamidi doesn't broadcast audio. Use whatever solution you like. We use icecast and VLC to listen.

- Jamidi is experimental and nowhere safe. You need to understand safety risks with opening a network port, especially over Internet. Ask someone who knows if you don't. 




# How it work : Websocket


Websocket transport a string like :

/ocs2/cc/2 0

or 

/tr808/note/1

cc   			: is a "command". Currently cc, reset (highly specific to nozoid synthetiser). You can add any tyoe of "command".

ocs2 			: is a "device", that must be described, follow examples in jamidi.json. Here the Alice OCS2 will reveive broadcasted midi informations. 

/ocs2 and /tr808 changes made by John will be displayed to everyone and played by devices.


Websocket default port is 8081 but one can change.




#  How it work : Server

Will receive all "commands" from all clients, forward them to local devices and broadcast them too.


Options : 

servername 		: 'local', 'llstrvpn'. Servers (IP, port,...) must be described in jamidi.json

--broadcast 	: Broadcast all incomings commands to all client. Default option. 

--no-broadcast	: Do not broadcast all incomings commands to all client.


--reset 		: Send reset values to local device a startup. Default option.

--no-reset 		: Do not send reset values to local device a startup.


--current 		: Send all current CC values to all new client. Default option.

--no-current 	: Do not send all current CC values to all new client.



#  How it work : Clients

Can be webpages or midi instrument/software. Multiple clients types is supported.


Options :

servername : Remote server 'local', 'xrkia' ('local' by default). Servers must be described in jamidi.json

default    : Network <-> default midi device (True or False)


Some "rules" are available. Say you want all network incoming midi CC 1 channel 0 goes to a specific device on channel 3 CC 48. Rules must be described in rules.json

Each rule may happen at all time or only during a "song".

How to Run python client :

python3 client.py



# Webpages examples

1/ Run :


python3 main.py


2/ In a browser open 2 instances of each of these :


indexaurora.html is a three rotating encoders example.

mmo3.html and ocs2.html demo to control 2 real life nozoids.


3/ Each aurora pages talk to each other. Each mmo3 to each other and so on..


These pages will work with local jamidi server, but they can't guess your online configuration. You need to modify IP and port in line :

var LJ = 'ws://127.0.0.1:8081/'



# Midi instrument usage

1/ You need to edit jamidi.json and follow ocs2 example.

2/ Create a client/webpage that will send /ocs2/xxx

3/ Run :

python3 main.py

4/ 




# Install

You need python3 and pip3 

sudo apt-get install python3-pip 

pip3 install python-rtmidi (sudo apt install libasound2-dev, sudo apt install libjack-dev)

pip3 install mido

pip3 install numpy


for Websocket client :
Download : https://files.pythonhosted.org/packages/8b/0f/52de51b9b450ed52694208ab952d5af6ebbcbce7f166a48784095d930d8c/websocket_client-0.57.0.tar.gz

Decompress

python3 setup.py install