Patch

Patch is a universal hub for controller messages

These message protocols are currently supported

• MIDI
• OSC
• JSON over Websocket

Other possibilities:

• HTML5 Server-Sent Events
• HTTP
• JSON RPC 2.0

Patch receives messages in these formats and instantly translates and sends them to others

For example:

Patch receive messages from an OSC controller, and relays them to a web API. The web API in turn responds with JSON that Patch relays to a MIDI synthesizer

While this particular example can probably be accomplished using other specialized utilities or scripts, Patch makes it possible to receive, merge, split and send different types of messages like this in a general way, with much less configuration

Patch is packaged as a Ruby gem.

It can be installed by using gem install patch on the command line or by adding gem "patch" to a project's Gemfile.

Configuring Patch can be done two ways:

• In Ruby code
• Using configuration files

require "patch"

A node is a single source and/or destination of control messages. Here, we define three nodes:

websocket = Patch::IO::Websocket::Node.new(1, "localhost", 9006)

midi = Patch::IO::MIDI::Input.new(2, "Apple Inc. IAC Driver")

osc = Patch::IO::OSC::Server.new(3, 8000)

A node map defines where messages should flow to and from.

In this example, when our MIDI and OSC nodes receive messages, those messages are then echoed to the Websocket node.

map = { [midi, osc] => websocket }

The message protocols used by Patch have no implicit way to translate between each other. Therefore actions are used to describe how to do that.

action = {
  :name => "Zoom",
  :key => "zoom",
  :default => {
    :scale => 10..200.0
  },
  :midi => {
    :channel => 0,
    :index => 1
  },
  :osc => {
    :address=>"/1/rotaryA",
    :scale => 0..1.0
  }
}

Given these example actions,

1. When a MIDI control change message is received on channel 0 with index 1, send a JSON over websocket message with the key zoom. The value of the MIDI message should be scaled to a float between 10 and 200.

2. When an OSC message is received for address /1/rotaryA, send a JSON over websocket message with the key zoom. Scale the OSC value, which will be a float between 0 and 1 to a float between 10 and 200.

Now start Patch listening for messages:

patch = Patch::Patch.new(:simple, map, action)

hub = Patch::Hub.new(:patch => patch)
hub.listen

The full example can be found here.

It's also possible to configure Patch using configuration files. To do that, two files are necessary:

• nodes.yml
• patches.yml

The configuration in these example files is similar to the one in Ruby above.

nodes.yml describes what nodes to use and how to configure them.

In addition, each node is given an ID number for reference later.

:nodes:
  - :id: 1
    :type: websocket
    :host: localhost
    :port: 9006
  - :id: 2
    :type: midi
    :direction: input
    :name: Apple Inc. IAC Driver
  - :id: 3
    :type: osc
    :server:
      :port: 8000
    :client:
      :host: 192.168.1.136
      :port: 9000

Node maps and actions are specified in the second configuration file, patches.yml.

:patches:
  :simple:
    :node_map:
      [2, 3]: 1
    :actions:
    - :name: Zoom
      :key: zoom
      :default:
        :scale: !ruby/range 10..200.0
      :midi:
        :channel: 0
        :index: 1
      :osc:
        :address: /1/rotaryA
        :scale: !ruby/range 0..1.0

The patches.yml file can contain any number of patches, they will all be run concurrently.

You can run Patch at the command line by executing patchrb nodes.yml patches.yml.

Ari Russo <ari.russo at gmail.com>

Apache 2.0, See the file LICENSE

Copyright (c) 2014-2015 Ari Russo