https://github.com/arirusso/patch
Universal controller message hub
https://github.com/arirusso/patch
Last synced: over 1 year ago
JSON representation
Universal controller message hub
- Host: GitHub
- URL: https://github.com/arirusso/patch
- Owner: arirusso
- License: other
- Created: 2014-06-21T15:50:53.000Z (about 12 years ago)
- Default Branch: master
- Last Pushed: 2015-09-28T23:05:55.000Z (almost 11 years ago)
- Last Synced: 2025-03-24T12:56:21.342Z (over 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 949 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Patch
Patch is a universal hub for controller messages
These message protocols are currently supported
* [MIDI](http://en.wikipedia.org/wiki/MIDI)
* [OSC](http://en.wikipedia.org/wiki/Open_Sound_Control)
* JSON over [Websocket](http://en.wikipedia.org/wiki/WebSocket)
Other possibilities:
* [HTML5 Server-Sent Events](http://www.w3schools.com/html/html5_serversentevents.asp)
* HTTP
* [JSON RPC 2.0](http://en.wikipedia.org/wiki/JSON-RPC)
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
## 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](#in-ruby)
* [Using configuration files](#using-configuration-files)
### In Ruby
```ruby
require "patch"
```
A *node* is a single source and/or destination of control messages. Here, we define three nodes:
```ruby
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.
```ruby
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.
```ruby
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:
```ruby
patch = Patch::Patch.new(:simple, map, action)
hub = Patch::Hub.new(:patch => patch)
hub.listen
```
The full example can be found [here](https://github.com/arirusso/patch/blob/master/examples/simple/simple.rb).
### Using Configuration Files
It's also possible to configure Patch using configuration files. To do that, two files are necessary:
* [nodes.yml](#nodesyml)
* [patches.yml](#patchesyml)
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.
```yaml
: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`.
```yaml
: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](http://github.com/arirusso)
## License
Apache 2.0, See the file LICENSE
Copyright (c) 2014-2015 [Ari Russo](http://arirusso.com)