patch 0.4.13

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 222f130c3489c502fab026e74c0d669a9a84fb43
+  data.tar.gz: a2a352a10308ee799ea3053606b29229cc523376
+SHA512:
+  metadata.gz: 0d51314a03aa34d4bdf3ddb9fe42af9315c810bdf72b0d43e636b854e0aa267211a826ebb26f10024a19bf80713d6742999d724a86df10960eb49a5552d9e7d0
+  data.tar.gz: ba72546ab948910ffe80cf20aa68c64274642fa8e5be8672d522fb4aac5eae4462f2c58af3f5b1130b7e93f267c452bc092295ae3a8fe5bbe4f30b97c9b7040b

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2014-2015 Ari Russo
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,176 @@
+# 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 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](#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.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) <ari.russo at gmail.com>
+
+## License
+
+This version under Apache 2.0, See the file LICENSE
+Copyright (c) 2014-2015 [Ari Russo](http://arirusso.com)

data/bin/patchrb

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+lib = File.expand_path(File.dirname(__FILE__) + '/../lib')
+$LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
+
+require "optparse"
+require "patch"
+
+nodes_config_path, patches_config_path = *ARGV
+
+options = {}
+
+args = OptionParser.new do |opts|
+  opts.banner = "Usage: patch [nodes config file] [patches config file] [options]"
+
+  opts.on("-l", "--log [FILE]", "Enable logging with optional file name") do |file|
+    options[:log] = file || true
+  end
+  opts.on("-q", "--quiet", "Quiet mode for no console output") do
+    options[:quiet] = true
+  end
+end
+
+args.parse!
+
+if nodes_config_path.nil? || !File.exist?(nodes_config_path) || patches_config_path.nil? || !File.exist?(patches_config_path)
+  puts args.help
+  exit 0
+else
+  nodes_config_file = File.new(nodes_config_path)
+  patches_config_file = File.new(patches_config_path)
+end
+
+if !!options[:log]
+  log_filename = options[:log] === true ? "patch_#{Time.now.to_i}.log" : options[:log]
+  log_file = File.open(log_filename, "w")
+end
+
+hub = Patch::Config.to_hub(nodes_config_file, :log => log_file, :patches => patches_config_file)
+Patch::Report.print(hub) unless options[:quiet]
+hub.listen

data/lib/patch/config.rb

@@ -0,0 +1,124 @@
+module Patch
+
+  # Deal with config files, hashes
+  module Config
+
+    extend self
+
+    # @param [Hash] nodes_config
+    # @param [Hash] options
+    # @option options [IO] :log
+    # @return [Hub]
+    def to_hub(nodes_config, options = {})
+      log = Log.new(options.fetch(:log, $>)) unless options[:log].nil?
+      nodes = to_nodes(nodes_config, :log => log)
+      patches = to_patches(nodes, options[:patches]) unless options[:patches].nil?
+      Hub.new(:log => log, :patches => patches)
+    end
+
+    # Instantiate patch objects from the given patch config file, filename or hash
+    # @param [NodeContainer] nodes
+    # @param [File, Hash, String] config
+    # @return [Array<Patch>]
+    def to_patches(nodes, config)
+      config = ensure_hash(config)
+      patches = []
+      config[:patches].each do |name, patch_config|
+        patches << to_patch(name, nodes, patch_config)
+      end
+      patches
+    end
+
+    # Instantiate node objects from the given node config or config file
+    # @param [File, Hash, String] config
+    # @param [Hash] options
+    # @option options [Log] :log
+    # @return [Node::Container]
+    def to_nodes(config, options = {})
+      config = ensure_hash(config)
+      node_array = config[:nodes].map { |node_config| to_node(node_config, options) }
+      Node::Container.new(node_array)
+    end
+
+    # Instantiate Node::Map objects given a map config hash
+    # @param [NodeContainer] nodes
+    # @param [Hash] config
+    # @return [Array<Node::Map>]
+    def to_node_maps(nodes, config)
+      config.map { |from, to| get_node_map(nodes, from, to) }
+    end
+
+    private
+
+    # @param [NodeContainer] nodes
+    # @param [Array<Object>, Object] from (id)
+    # @param [Array<Object>, Object] to (id)
+    # @return [Node::Map]
+    def get_node_map(nodes, from, to)
+      from_nodes = get_nodes(nodes, from)
+      to_nodes = get_nodes(nodes, to)
+      Node::Map.new(from_nodes, to_nodes)
+    end
+
+    # @param [NodeContainer] nodes
+    # @param [Array<Object>, Object] from (id)
+    # @return [Array<Patch::IO::MIDI, Patch::IO::OSC, Patch::IO::Websocket>]
+    def get_nodes(nodes, ids)
+      ids = [ids].flatten
+      ids.map { |id| nodes.find_by_id(id) }
+    end
+
+    # Instantiate a node from the given node config
+    # @param [Hash] config
+    # @param [Hash] options
+    # @option options [Log] :log
+    # @return [Patch::IO::MIDI, Patch::IO::OSC, Patch::IO::Websocket]
+    def to_node(node_config, options = {})
+      module_key = node_config[:type].to_sym
+      mod = IO::Module.find_by_key(module_key)
+      mod.new_from_config(node_config, :log => options[:log])
+    end
+
+    # Instantiate a patch object for the given config hash
+    # @param [Symbol, String] name
+    # @param [NodeContainer] nodes
+    # @param [Hash] config
+    # @return [Patch]
+    def to_patch(name, nodes, config)
+      actions = config[:actions] || config[:action]
+      maps = to_node_maps(nodes, config[:node_map])
+      Patch.new(name, maps, actions)
+    end
+
+    # @param [File, Hash, String] object
+    # @return [File, String]
+    def get_config_file(object)
+      case object
+      when File, String then object
+      end
+    end
+
+    # Given a file name, file or hash, populate a config hash and freeze it
+    # @param [File, Hash, String] object
+    # @return [Hash]
+    def ensure_hash(object)
+      hash = if (config_file = get_config_file(object)).nil?
+        object
+      else
+        YAML.load_file(config_file)
+      end
+      deep_freeze_config(hash) unless hash.nil?
+    end
+
+    # @param [Enumerable] container
+    # @return [Enumerable]
+    def deep_freeze_config(container)
+      container.freeze
+      values = container.respond_to?(:values) ? container.values : container
+      enums = values.select { |item| item.kind_of?(Array) || item.kind_of?(Hash) }
+      enums.each { |item| deep_freeze_config(item) }
+      container
+    end
+
+  end
+end

data/lib/patch/em_patch.rb

@@ -0,0 +1,47 @@
+# These patches will allow starting both an OSC and Websocket server concurrently
+#
+module OSC
+  class EMServer
+
+    def run
+      open
+    end
+
+    def open
+      EM::open_datagram_socket("0.0.0.0", @port, Connection)
+    end
+
+    def remove_method(address_pattern)
+      matcher = AddressPattern.new( address_pattern )
+
+      @tuples.delete_if { |pattern, proc| pattern == matcher }
+    end
+
+  end
+end
+
+module EventMachine
+  module WebSocket
+    def self.start(options, &blk)
+      #EM.epoll
+      #EM.run {
+        trap("TERM") { stop }
+        trap("INT")  { stop }
+
+        run(options, &blk)
+      #}
+    end
+
+    def self.run(options)
+      host, port = options.values_at(:host, :port)
+      EM.start_server(host, port, Connection, options) do |c|
+        ::Thread.current.abort_on_exception = true
+        begin
+          yield c
+        rescue Exception => exception
+          ::Thread.main.raise(exception)
+        end
+      end
+    end
+  end
+end

data/lib/patch/hub.rb

@@ -0,0 +1,68 @@
+module Patch
+
+  # The main application object
+  class Hub
+
+    attr_reader :log, :patches
+
+    # @param [Hash] options
+    # @option options [IO] :log
+    # @option options [Array<Patch>] :patches
+    def initialize(options = {})
+      @log = Log.new(options[:log]) unless options[:log].nil?
+      populate_patches(options[:patches] || options[:patch])
+    end
+
+    # Collected IP addresses for the nodes
+    # @return [Array<String>]
+    def ips
+      regex = /\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/
+      all_ips = Socket.ip_address_list.map(&:inspect_sockaddr)
+      all_ips.select { |ip| !!ip.match(regex) }
+    end
+
+    # Start the hub
+    # @param [Hash] options
+    # @option options [Boolean] :background Run in a background thread (default: false)
+    # @return [Hub] self
+    def listen(options = {})
+      begin
+        enable_nodes
+        @thread.join unless !!options[:background]
+        self
+      rescue SystemExit, Interrupt => exception
+        exit 0
+      end
+    end
+
+    # All of the nodes used by the patches
+    # @return [Node::Container]
+    def nodes
+      nodes = @patches.map { |patch| patch.maps.map(&:nodes) }.flatten.compact.uniq
+      Node::Container.new(nodes)
+    end
+
+    private
+
+    # Enable the nodes
+    # @return [Thread]
+    def enable_nodes
+      @thread = ::Patch::Thread.new do
+        EM.epoll
+        EM.run {
+          @patches.each(&:enable)
+          nodes.enable
+        }
+        !nodes.empty?
+      end
+    end
+
+    # Populate the patches given various arg formats
+    # @param [Array<Patch>, Patch] patches
+    # @return [Array<Patch>]
+    def populate_patches(patches)
+      @patches = [patches].flatten.compact
+    end
+
+  end
+end

data/lib/patch/io/midi/action.rb

@@ -0,0 +1,42 @@
+module Patch
+
+  module IO
+
+    module MIDI
+
+      # Find and identify MIDI Actions
+      module Action
+
+        extend self
+
+        # Is the given action MIDI?
+        # @param [Hash] action
+        # @return [Boolean]
+        def midi?(action)
+          !action[:midi].nil? && !action[:midi][:index].nil?
+        end
+
+        # Filter the given actions only to return MIDI actions
+        # @param [Array<Hash>] actions
+        # @return [Array<Hash>]
+        def midi_actions(actions)
+          actions.select { |action| midi?(action) }
+        end
+
+        # Find an action in the given patch for the given cc index
+        # @param [Array<Hash>] actions
+        # @param [Fixnum] index
+        # @return [Hash]
+        def find_by_index(actions, index)
+          midi_actions(actions).find do |action|
+            action[:midi][:index] == index
+          end
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/patch/io/midi/input.rb

@@ -0,0 +1,110 @@
+module Patch
+
+  module IO
+
+    module MIDI
+
+      # MIDI Input functions
+      class Input
+
+        attr_reader :device, :id, :listener
+
+        # @param [Fixnum] id
+        # @param [String, UniMIDI::Input] device
+        # @param [Hash] options
+        # @option options [Log] :log
+        def initialize(id, device, options = {})
+          @log = options[:log]
+          @id = id
+          @device = get_input(device)
+          @listener = MIDIEye::Listener.new(@device) unless @device.nil?
+        end
+
+        # Start listening for MIDI messages
+        # @return [Boolean] Whether the listener was started
+        def start
+          if !@listener.nil?
+            @listener.run(:background => true)
+            true
+          else
+            false
+          end
+        end
+
+        # Is the input active?
+        # @return [Boolean]
+        def active?
+          @listener.running?
+        end
+
+        # Stop the MIDI listener
+        # @return [Boolean]
+        def stop
+          if !@listener.nil?
+            @listener.stop
+            true
+          else
+            false
+          end
+        end
+
+        # Clear message handlers
+        # @return [Boolean]
+        def disable(patch)
+          @listener.event.clear
+          true
+        end
+
+        # Specify a mpatch context and handler callback to use when messages are received
+        # @param [::Patch::Patch] patch
+        # @param [Proc] callback
+        # @return [Boolean] Whether adding the callback was successful
+        def listen(patch, &callback)
+          if !@listener.nil?
+            @listener.listen_for(:class => [MIDIMessage::ControlChange]) do |event|
+              handle_event_received(patch, event, &callback)
+            end
+            true
+          else
+            false
+          end
+        end
+
+        private
+
+        # Handle receiving new MIDI messages from the input
+        # @param [::Patch::Patch] patch
+        # @param [Hash] event
+        # @param [Proc] callback
+        # @return [Array<::Patch::Message>]
+        def handle_event_received(patch, event, &callback)
+          messages = event[:message]
+          patch_messages = ::Patch::IO::MIDI::Message.to_patch_messages(patch, messages)
+          yield(patch_messages) if block_given?
+          patch_messages
+        end
+
+        # Initialize the input device using the given string or input.  If the device is the string "choose",
+        # the user is prompted to select an available MIDI input.
+        # @param [String, UniMIDI::Input, nil] device
+        # @return [UniMIDI::Input, nil]
+        def get_input(device)
+          if device.kind_of?(String)
+            if device == "choose"
+              UniMIDI::Input.gets
+            else
+              UniMIDI::Input.find_by_name(device)
+            end
+          elsif device.respond_to?(:gets)
+            device.open if device.kind_of?(UniMIDI::Input)
+            device
+          end
+        end
+
+      end
+
+    end
+
+  end
+
+end