patch 0.4.13

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

@@ -0,0 +1,112 @@
+module Patch
+
+  module IO
+
+    module MIDI
+
+      # Convert between MIDI message objects and Patch::Message objects
+      module Message
+
+        extend self
+
+        # @param [::Patch::Patch] patch
+        # @param [Array<::Patch::Message>, ::Patch::Message] messages
+        # @return [Array<::MIDIMessage>]
+        def to_midi_messages(patch, patch_messages)
+          patch_messages = [patch_messages].flatten
+          midi_messages = patch_messages.map do |patch_message|
+            unless (action = patch.actions.at(patch_message.index)).nil?
+              to_midi_message(action, patch_message) unless action[:midi].nil?
+            end
+          end
+          midi_messages.compact
+        end
+
+        # Convert the given MIDI message to Patch::Message objects using the context of the given patch
+        # @param [::Patch::Patch] patch
+        # @param [Array<MIDIMessage>, MIDIMessage] midi_messages
+        # @return [Array<::Patch::Message>]
+        def to_patch_messages(patch, midi_messages)
+          midi_messages = [midi_messages].flatten
+          patch_messages = midi_messages.map do |midi_message|
+            unless (action = Action.find_by_index(patch.actions, midi_message.index)).nil?
+              index = patch.actions.index(action)
+              to_patch_message(action, index, patch.name, midi_message)
+            end
+          end
+          patch_messages.compact
+        end
+
+        private
+
+        # @param [Hash] action An action to contextualize the conversion
+        # @param [::Patch::Message] patch_message
+        def get_midi_value_from_action(action, patch_message)
+          to = action[:midi][:scale]
+          to ||= 0..127
+          from = action[:default][:scale] unless action[:default].nil?
+          from ||= to
+          get_value(patch_message.value, from, to)
+        end
+
+        # @param [Hash] action An action to contextualize the conversion
+        # @param [MIDIMessage] midi_message
+        def get_patch_values_from_action(action, midi_message)
+          from = action[:midi][:scale]
+          from ||= 0..127
+          to = action[:default][:scale] unless action[:default].nil?
+          to ||= from
+          get_value(midi_message.value, from, to)
+        end
+
+        # Convert a patch message to a MIDI message
+        # @param [Hash] action An action to contextualize the conversion
+        # @param [::Patch::Message] patch_message
+        # @return [::MIDIMessage::ControlChange, nil]
+        def to_midi_message(action, patch_message)
+          if !action[:midi].nil?
+            index = action[:midi][:index] || patch_message.index
+            channel = action[:midi][:channel] || 0
+            value = get_midi_value_from_action(action, patch_message)
+            MIDIMessage::ControlChange.new(channel, index, value)
+          end
+        end
+
+        # Convert a MIDI message to a patch message
+        # @param [Hash] action An action to contextualize the conversion
+        # @param [Fixnum] index The index of the message
+        # @param [Symbol] patch_name A patch name
+        # @param [::MIDIMessage::ControlChange] midi_message
+        # @return [::Patch::Message, nil]
+        def to_patch_message(action, index, patch_name, midi_message)
+          if action[:midi][:channel].nil? || action[:midi][:channel] == midi_message.channel
+            value = get_patch_values_from_action(action, midi_message)
+            properties = {
+              :index => index,
+              :patch_name => patch_name,
+              :value => value
+            }
+            ::Patch::Message.new(properties)
+          end
+        end
+
+        # Translate a value
+        # @param [Fixnum] value
+        # @param [Range] from
+        # @param [Range] to
+        # @return [Fixnum]
+        def get_value(value, from, to)
+          if from == to
+            value
+          else
+            Scale.transform(value).from(from).to(to)
+          end
+        end
+
+      end
+
+    end
+
+  end
+
+end

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

@@ -0,0 +1,58 @@
+module Patch
+
+  module IO
+
+    module MIDI
+
+      # MIDI Output functions
+      class Output
+
+        attr_reader :id, :device
+
+        # @param [Fixnum] id
+        # @param [String, UniMIDI::Output] device
+        # @param [Hash] options
+        # @option options [Debug] :log
+        def initialize(id, device, options = {})
+          @log = options[:log]
+          @id = id
+          @device = get_output(device)
+        end
+
+        # Convert Patch::Message objects to MIDI and send
+        # @param [Patch::Patch] patch Context
+        # @param [Array<Patch::Message>, Patch::Message] messages Message(s) to send via MIDI
+        # @return [Array<MIDIMessage>]
+        def puts(patch, patch_messages)
+          patch_messages = [patch_messages].flatten
+          messages = ::Patch::IO::MIDI::Message.to_midi_messages(patch, patch_messages)
+          @device.puts(messages) unless messages.empty?
+          messages
+        end
+
+        private
+
+        # Initialize the output device given a name or device object.  If the name of the device is the string "choose",
+        # the user is prompted to select an availble MIDI output.
+        # @param [String, UniMIDI::Output, nil] device
+        # @return [UniMIDI::Output]
+        def get_output(device)
+          if device.kind_of?(String)
+            if device == "choose"
+              UniMIDI::Output.gets
+            else
+              UniMIDI::Output.find_by_name(device)
+            end
+          elsif device.respond_to?(:puts)
+            device.open if device.kind_of?(UniMIDI::Output)
+            device
+          end
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/patch/io/midi.rb

@@ -0,0 +1,45 @@
+# Modules
+require "patch/io/midi/action"
+require "patch/io/midi/message"
+# Classes
+require "patch/io/midi/input"
+require "patch/io/midi/output"
+
+module Patch
+
+  module IO
+
+    # MIDI IO
+    module MIDI
+
+      # Key that will be used by Patch to identify the module
+      KEY = :midi
+      extend self
+      ::Patch::IO::Module.add(self)
+
+      # Instantiate a MIDI device based on the given config
+      # @param [Hash] config
+      # @param [Hash] options
+      # @option options [Log] :log
+      # @return [MIDI::Input, MIDI::Output]
+      def new_from_config(config, options = {})
+        klass = get_direction_class(config[:direction])
+        klass.new(config[:id], config[:name], :log => options[:log])
+      end
+
+      private
+
+      # Get the direction class for the given key
+      # @param [Symbol] key
+      # @return [Class]
+      def get_direction_class(key)
+        case key.to_sym
+        when :input then Input
+        when :output then Output
+        end
+      end
+
+    end
+
+  end
+end

data/lib/patch/io/module.rb

@@ -0,0 +1,35 @@
+module Patch
+
+  module IO
+
+    # Manage node modules
+    class Module
+
+      class << self
+
+        # Find an IO module by its key
+        # @param [Symbol] key
+        # @return [Module]
+        def find_by_key(key)
+          all.find { |mod| mod::KEY === key }
+        end
+
+        # Add an IO module to the list of modules available to Patch
+        # @param [Module] mod
+        # @return [Array<Module>]
+        def add(mod)
+          @modules ||= []
+          @modules << mod
+        end
+
+        # Mapping of node modules and names
+        # @return [Array<Module>]
+        def all
+          @modules ||= []
+        end
+
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+module Patch
+
+  module IO
+
+    module OSC
+
+      # Find and identify OSC Actions
+      module Action
+
+        extend self
+
+        # Is the given action OSC?
+        # @param [Hash] action
+        # @return [Boolean]
+        def osc?(action)
+          !action[:osc].nil?
+        end
+
+        # Filter the given actions only to return OSC actions
+        # @param [Array<Hash>] actions
+        # @return [Array<Hash>]
+        def osc_actions(actions)
+          actions.select { |action| osc?(action) }
+        end
+
+        # Find an action by its OSC address
+        # @param [Array<Hash>] actions
+        # @param [String] address
+        # @return [Hash]
+        def find_by_address(actions, address)
+          osc_actions(actions).find do |action|
+            regex = Regexp.new(action[:osc][:address])
+            address.match(regex)
+          end
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/patch/io/osc/client.rb

@@ -0,0 +1,60 @@
+module Patch
+
+  module IO
+
+    module OSC
+
+      # OSC Client
+      class Client
+
+        attr_reader :id
+
+        # @param [String] host
+        # @param [Fixnum] port
+        # @param [Hash] options
+        # @option options [Fixnum] :id
+        # @option options [Log] :log
+        def initialize(host, port, options = {})
+          @id = options[:id]
+          @log = options[:log]
+          @client = ::OSC::Client.new(host, port)
+        end
+
+        # Convert message objects to OSC and send
+        # @param [Patch::Patch] patch Context
+        # @param [Array<Patch::Message, ::OSC::Message>, ::OSC::Message, Patch::Message] messages Message(s) to send
+        # @return [Array<::OSC::Message>]]
+        def puts(patch, messages)
+          osc_messages = get_osc_messages(patch, messages)
+          osc_messages.each { |osc_message| @client.send(osc_message) }
+          osc_messages
+        end
+
+        private
+
+        # @param [::Patch::Patch] patch
+        # @param [Array<Patch::Message, ::OSC::Message>, ::OSC::Message, Patch::Message] messages Message(s) to send
+        # @return [Array<::OSC::Message>]]
+        def get_osc_messages(patch, messages)
+          messages = [messages].flatten
+          messages.map { |message| ensure_osc_message(patch, message) }
+        end
+
+        # @param [::Patch::Patch] patch
+        # @param [::OSC::Message, Patch::Message] message
+        # @return [::OSC::Message]
+        def ensure_osc_message(patch, message)
+          unless message.kind_of?(::OSC::Message)
+            osc_message = ::Patch::IO::OSC::Message.to_osc_messages(patch, message)
+          end
+          osc_message ||= message
+          osc_message
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/patch/io/osc/message.rb

@@ -0,0 +1,109 @@
+module Patch
+
+  module IO
+
+    module OSC
+
+      # Convert between OSC message and Patch::Message objects
+      module Message
+
+        extend self
+
+        # Convert a message object to an OSC message given the context of the given patch
+        # @param [::Patch::Patch] patch
+        # @param [::Patch::Message] message
+        # @return [Array<::OSC::Message>]
+        def to_osc_messages(patch, patch_message)
+          messages = []
+          unless (action = get_osc_action(patch.actions, patch_message)).nil?
+            messages << get_osc_message(action, patch_message)
+          end
+          messages
+        end
+
+        # Convert the given OSC message to Patch::Message objects using the context of the given patch
+        # @param [::Patch::Patch] patch
+        # @param [Object] raw_osc
+        # @return [Array<::Patch::Message>]
+        def to_patch_messages(patch, raw_osc)
+          messages = []
+          unless (action = Action.find_by_address(patch.actions, raw_osc.address)).nil?
+            messages << get_patch_message(patch, action, raw_osc)
+          end
+          messages
+        end
+
+        private
+
+        # @param [::Patch::Patch] patch
+        # @param [Hash] action
+        # @param [Object] raw_osc
+        # @return [::Patch::Message]
+        def get_patch_message(patch, action, raw_osc)
+          index = patch.actions.index(action)
+          values = get_patch_values_from_action(raw_osc, action)
+          properties = {
+            :index => index,
+            :patch_name => patch.name,
+            :value => values[0]
+          }
+          ::Patch::Message.new(properties)
+        end
+
+        # @param [Hash] action
+        # @param [::Patch::Message] patch_message
+        # @return [::OSC::Message]
+        def get_osc_message(action, patch_message)
+          address = action[:osc][:address]
+          value = get_osc_value_from_action(patch_message.value, action)
+          ::OSC::Message.new(address, value)
+        end
+
+        # @param [Object] raw_osc
+        # @param [Hash] action
+        # @return [Array<Object>]
+        def get_patch_values_from_action(raw_osc, action)
+          from = action[:osc][:scale]
+          to = action[:default][:scale] unless action[:default].nil?
+          to ||= from
+          raw_osc.to_a.map { |value| get_value(value.to_f, from, to) }
+        end
+
+        # @param [Object] value
+        # @param [Hash] action
+        # @return [Object]
+        def get_osc_value_from_action(value, action)
+          to = action[:osc][:scale]
+          from = action[:default][:scale] unless action[:default].nil?
+          from ||= to
+          get_value(value, from, to)
+        end
+
+        # @param [Array<Hash>] actions
+        # @param [::Patch::Message] patch_message
+        # @return [Hash]
+        def get_osc_action(actions, patch_message)
+          action = actions.at(patch_message.index)
+          action unless action.nil? || action[:osc].nil?
+        end
+
+        # Translate a value
+        # @param [Fixnum] value
+        # @param [Range] from
+        # @param [Range] to
+        # @return [Fixnum]
+        def get_value(value, from, to)
+          if from == to
+            value
+          else
+            Scale.transform(value).from(from).to(to)
+          end
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/patch/io/osc/server.rb

@@ -0,0 +1,159 @@
+module Patch
+
+  module IO
+
+    module OSC
+
+      # OSC server
+      class Server
+
+        attr_reader :id
+
+        # @param [Fixnum] id
+        # @param [Fixnum] port
+        # @param [Hash] options
+        # @option options [Hash] :echo
+        # @option options [Log] :log
+        def initialize(id, port, options = {})
+          @log = options[:log]
+          @server = nil
+          @active = false
+          @id = id
+          @is_failsafe = true
+
+          configure(port, options)
+        end
+
+        # Is the server active?
+        # @return [Boolean]
+        def active?
+          @active
+        end
+
+        # Start the server
+        # @return [Boolean] Whether the server was started
+        def start
+          @active = true
+          @connection = @server.run
+          true
+        end
+
+        # Stop the server
+        # @return [Boolean]
+        def stop
+          @active = false
+          true
+        end
+
+        # Disable the message handlers
+        # @return [Boolean]
+        def disable(patch)
+          addresses = get_addresses(patch)
+          addresses.select { |address| @server.remove_method(address) }.any?
+        end
+
+        # Listen for messages
+        # @param [::Patch::Patch] patch The patch to use for context
+        # @param [Proc] callback A callback to fire when messages are received
+        # @return [Boolean] Whether any actions were configured
+        def listen(patch, &callback)
+          addresses = get_addresses(patch)
+          addresses.select { |address| listen_for(address, patch, &callback) }.any?
+        end
+
+        protected
+
+        # @param [::Patch::Patch] patch The patch to use for context
+        # @return [Array<String, Regexp>]
+        def get_addresses(patch)
+          actions = ::Patch::IO::OSC::Action.osc_actions(patch.actions)
+          actions.map { |action| action[:osc][:address] }.compact.uniq
+        end
+
+        # Handle a new message
+        # @param [::Patch::Patch] patch A patch for context
+        # @param [OSC::Message] message The OSC message object
+        # @param [Proc] callback A callback to fire when a message or messages is received
+        # @return [Array<Patch::Message>]
+        def handle_message_received(patch, raw_osc, &callback)
+          messages = ::Patch::IO::OSC::Message.to_patch_messages(patch, raw_osc)
+          echo(patch, raw_osc) if echo?
+          # yield to custom behavior
+          yield(messages) if block_given?
+          messages
+        end
+
+        private
+
+        # @param [Fixnum] port
+        # @param [Hash] options
+        # @option options [Hash] :echo
+        # @return [Boolean]
+        def configure(port, options = {})
+          configure_server(port)
+          unless options[:echo].nil?
+            configure_echo(options[:echo][:host], options[:echo][:port])
+          end
+          true
+        end
+
+        # Listen for messages on the given address
+        # @param [::Patch::Patch] patch The patch to use for context
+        # @param [Proc] callback A callback to fire when messages are received
+        # @return [Boolean] Whether an action was configured
+        def listen_for(address, patch, &callback)
+          @server.add_method(address) do |message|
+            handle_message_received(patch, message, &callback)
+          end
+          true
+        end
+
+        # Configure the underlying server
+        # @param [Fixnum] port
+        # @return [::OSC::Server]
+        def configure_server(port)
+          @server = ::OSC::EMServer.new(port)
+          if @log
+            @server.add_method(/.*/) { |message| @log.puts("Received: #{message.address}") }
+          end
+          @server
+        end
+
+        # Will received messages be echoed back to the client?
+        # @return [Boolean]
+        def echo?
+          !@client.nil?
+        end
+
+        # Echo a message back to the client to update the UI or whatever
+        # @param [::Patch::Patch] patch
+        # @param [OSC::Message] osc_message
+        # @return [Boolean] Whether the echo occurred
+        def echo(patch, osc_message)
+          begin
+            @client.puts(patch, osc_message)
+            true
+          rescue Exception => exception # failsafe
+            @log.exception(exception) if @log
+            ::Thread.main.raise(exception) unless @is_failsafe
+            false
+          end
+        end
+
+        # Configure the echo client
+        # @param [String] host
+        # @param [Fixnum] echo
+        # @param [Hash] options
+        # @param [Log] :log
+        # @return [::Patch::IO::OSC::Client]
+        def configure_echo(host, port, options = {})
+          @client = Client.new(host, port, :log => options.fetch(:log, @log))
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/patch/io/osc.rb

@@ -0,0 +1,43 @@
+# Modules
+require "patch/io/osc/action"
+require "patch/io/osc/message"
+# Classes
+require "patch/io/osc/client"
+require "patch/io/osc/server"
+
+module Patch
+
+  module IO
+
+    # Receive OSC messages and do something with them
+    module OSC
+
+      # Key that will be used by Patch to identify the module
+      KEY = :osc
+      extend self
+      ::Patch::IO::Module.add(self)
+
+      # Instantiate an OSC server and/or client using the given config
+      # @param [Hash] config
+      # @param [Hash] options
+      # @option options [Action::Container] :actions
+      # @option options [Log] :log
+      # @return [::Patch::IO::OSC::Server]
+      def new_from_config(config, options = {})
+        instance_options = {
+          :log => options[:log]
+        }
+        if config[:server].nil?
+          unless config[:client].nil?
+            instance_options[:id] = config[:id]
+            Client.new(config[:client][:host], config[:client][:port], instance_options)
+          end
+        else
+          instance_options[:echo] = config[:client]
+          Server.new(config[:id], config[:server][:port], instance_options)
+        end
+      end
+
+    end
+  end
+end