Web server for participative art performances and installations.
rhizome is a web server for participative performances and installations.
rhizome is a solution for transmitting messages and files between OSC applications, web pages, midi devices, ... therefore allowing you to control the user's devices with your installation, or allowing the participants to control your installation with their smartphones, computers or tablets.
rhizome was used to realize the following projects : https://github.com/sebpiq/rhizome/wiki/Gallery
Open a terminal, and simply run
npm install -g rhizome-server. If this succeeded, you can try to run
rhizome. This should print rhizome help message.
A sample configuration file with all available options can be found here, you can use it to get started.
Say you have created a configuration file called
myConfig.js. You can now start the server by running
rhizome myConfig.js in your terminal.
Now that the server is running, the only thing left is to create your application by programming a few clients for rhizome. There is a full example here, providing bare bones for a web page (and websocket client), a Pure Data client and a SuperCollider client.
If you have any feedback, any problem, if you need help, don't hesitate to drop a message in the issue tracker.
Also, if you would like to add your rhizome project to the gallery, please contact me.
Simple communication protocol. The rhizome server receives connections from different clients (OSC, websockets, ...) and allows them to communicate together through a protocol that looks a lot like OSC :
/some/address ["big", "bang"]/other/address [1.123456, Blob(100000)]
Publish / Subscribe. To receive messages sent at a given address, a client has to subscribe to that address. This avoids all messages to be sent to all clients, and therefore offers an optimized yet flexible messaging system.
OSC support. Any OSC client such as Pure Data, Max/MSP, SuperCollider, Processing, ... is supported out of the box.
websocket support. A websocket client is included with rhizome. It can be used in your web pages, and handles all the dirty bits of websocket communication : automatic reconnection and so on ...
Transferring files over OSC. While file transfer (or binary data transfer) is not supported by many OSC clients, rhizome provides a simple tool called rhizome-blobs to handle this. This allows you to receive / send files from / to any OSC client through rhizome.
Reliability. Crashes shouldn't happen, but in case they do, your server can be restarted cleanly, and its whole state will be restored.
Blog post on how to set-up your wireless network for use with rhizome : http://funktion.fm/#post/rhizome-interactive-performances-and-network-topologies
Rhizome is made of many parts integrated together, and the maximum amount of people that can use the system simultaneously varies dramatically depending on many factors : how many messages go through the system in a very short time? do you transfer big files? etc ... To figure this out, you might need to do some testing. As a general rule, if you don't send big files, and don't bombard the system with messages, 100 simultaneous connections should work fine.
If the system alone can't handle the load, it might be necessary to implement a more modular architecture with several servers (both rhizome and HTTP server) running at the same time (possibly on different machines) and a load balancer.
At the moment, the rhizome command only runs one server and even by programming yourself using rhizome node API, it is not really possible ... but in a near future it will work (see issues #76, #90, #112)
The following messages are used for communication between one connection and the server
/sys/subscribe <appPort> <address>: subscribes the OSC client running at
<appPort>to all messages sent at
/sys/resend <appPort> <address>: resends the last message sent at
<address>to the OSC client running at
/sys/blob <appPort> <address> <blobPath> [<arg1> <arg2> ...]: sends the file
<blobPath>from an OSC application to the server using rhizome-blobs.
/sys/config <appPort> <parameter> [<arg1> <arg2> ...]: sends configuration for the OSC client running at
<appPort>to the rhizome server. Available parameters are :
blobClient [<blobsPort>]: tell the server that the OSC client uses rhizome-blobs for file transfers.
blobsPortis the port on which rhizome-blobs is listening for incoming files. If not provided a default value will be chosen.
/sys/subscribe <address>: subscribes the web client to messages sent at
/sys/resend <address>: resends the last message sent at
/sys/connections/sendlist <clientType>: sends the list of ids of all connections of
<clientType>currently opened on the server. The response is sent at address
The following messages are sent by the server. To receive them, you should subscribe to them.
/broadcast/open/<clientType> <id>: client
<id>has just connected.
/broadcast/close/<clientType> <id>: client
<id>has just disconnected.
This event is sent when the client successfully connected (or re-connected) with the server.
This is the event you need to listen in order to receive messages. For example :
rhizomeon'message'if address === '/background/color' setBgColorargs0
This event is sent when connection fails because the server is full.
rhizomestartrhizomeon'server full'showMessage'Waiting for an available space'rhizomeon'connected'hideMessage
Emitted when the connection to the server has been lost. You can use this e.g. to deactivate the user interface if the device is not connected anymore :
rhizomeon'connection lost'hideControlsshowMessage'Reconnecting ... be patient'
Starts the client, and executes
done(err) when complete. The fact that the client is started, doesn't mean that the client is connected. For example, if the server is full, the client will start properly but connection will be delayed until space become available.
Sends a message to
address, with an optional list of arguments
args. For example :
rhizomesend'/ring' 'wake up' 8.0rhizomesend'/mood/bad'
This is a helper to limit the number of messages sent to the server. Sending too many messages, too fast, might overload the network and cause the system to be unresponsive. This function can help you tackle this issue by forcing
callback(value) to be called at most every
time milliseconds. Example :
// Let's assume for the sake of the example, the function `onMouseMove`// is called every 5 milliseconds each time the mouse moves.// We don't want to send all those messages, so we're gonna use// `rhizome.utils.throttle` to send every 100 milliseconds instead.var sendValue = rhizomeutilsthrottle100rhizomesend'/mouse/xy' xyvar onMouseMovesendValuex y
true if the current browser is supported,
Unique id of the client. It is
null if the web client is not connected.
Then from the root folder of the project, run tests like so :
And generate a coverage report like so :
npm run coverage
WebSocket client can be tested on the browser locally by running
node test/browser/websocket-server, and opening your browser to http://localhost:8000/index.html.
There is also a test runner for saucelabs, which allow to test the client on different browser. First you need to create a saucelabs account, and then in
test/browser/ create a file
config.js like this :
moduleexports =username: "<saucelabs_username>"password: "<saucelabs_key>"
node test/browser/saucelabs to start the tests.
Changed config file format for
/sys/connections/getlistto get a list of connected clients
startjust returns an error if server is full and
clientsremoved. Now OSC connection are created on the fly instead of being declared in the config file.
appPortremoved. Clients don't need to be declared anymore
fileExtensionto save files with a given extension
get the last message sent to an address by sending to
isSupportedto test browser support
Server : added different transports (TCP, UDP) for OSC.
utils.throttleto limit messages sent to server
isSupportedto test browser support
Server : more robust UDP connection handling
/broadcast/websockets/openwhen a websocket connection is opened or closed
blob, now blob sent with
Blob client for sending blobs web client <-> OSC
Added address validation
0.1.0 Initial release