Patch

Patch is a universal hub for controller messages

These message protocols are currently supported

MIDI
OSC
JSON over Websocket

Other possibilities:

Patch receives messages in these formats and converts them to a generic Patch::Message object.

At that point, these generic objects can be converted to another one of these formats and sent accordingly.

For example:

Patch can receive messages from a MIDI drum machine and relay them to a web API. The web API can then respond with JSON which Patch converts to MIDI and sends back to the drum machine.

While this particular example can probably be accomplished using other utilities or scripts, Patch makes it possible to receive, merge, split and send different types of messages like this freely in one session.

By doing so, Patch creates an interface that functions as though devices like that with different control messaging protocols had been designed to control each other.

Usage

Installation

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.

Configuration

Configuring Patch can be done two ways:

In Ruby code
Using configuration files

In Ruby

require "patch"

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

websocket = Patch::IO::Websocket.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,

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.
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.

Using Configuration Files

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

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

patches.yml

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.

Command Line

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

Author

Ari Russo