osc-access 0.0.15

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2011-2012 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.rdoc

@@ -0,0 +1,85 @@
+= OSC Access
+
+A simple way to bind {OSC}[http://en.wikipedia.org/wiki/Open_Sound_Control] directly to Ruby classes and objects.
+
+== Features
+
+* Works with MRI 1.9 and JRuby (in 1.9 mode)
+* Binding OSC events can be done by class or by instance
+* Network resources are invisible to the user even when shared or multiplexed
+* Shortcuts for common tasks associated with OSC such as translating numeric values from one range to another
+* Make OSC-accessible objects discoverable on a network using {Zeroconf}[http://en.wikipedia.org/wiki/Zero_configuration_networking]
+
+== Requirements
+
+Requires {eventmachine}[http://github.com/eventmachine/eventmachine] and {osc-ruby}[http://github.com/aberant/osc-ruby].  These should install automatically with the gem
+
+For Zeroconf support, {dnssd}[http://github.com/tenderlove/dnssd] is required.
+
+== Installation
+
+  gem install osc-access
+  
+== Usage
+
+  require "osc-access"
+
+In this example when OSC messages for <em>/1/fader1</em> are received, <em>velocity=</em> is called and another message is outputted confirming that the first message was received
+
+  class Instrument
+  
+    include OSCAccessible
+
+    osc_receive("/1/fader1", :translate => { :remote => 0..1, :local => 0..127 }) do |instance, val|
+      instance.velocity = val
+      instance.osc_send("/receipt", "val set to #{val}")
+    end
+  
+    def velocity=(val)
+      puts "setting velocity to #{val}"
+    end
+  
+  end
+
+  i = Instrument.new
+  i.osc_start(:input_port => 8000, :output => { :host => "192.168.1.8", :port => 9000}).join  
+
+The <em>:translate</em> option means that the first OSC argument will be translated from a number between 0 to 1 to the analogous value between 0 and 127 before being passed to the code block.
+
+Or, here is an example that produces the same object, but it's created by passing a Hash map to the instance:
+
+  map = {
+    "/1/fader1" => { 
+      :translate => { :remote => 0..1, :local => 0..127 }
+      :action => Proc.new do |instance, val| 
+        instance.pitch = val
+        instance.osc_send("/receipt", "val set to #{val}")
+      end
+    }
+  }
+  
+  class Instrument
+  
+    include OSCAccessible
+  
+    def pitch=(val)
+      p "setting pitch to #{val}"
+      ...
+    end
+
+  end
+
+  i = Instrument.new
+  i.osc_start(:map => map, :input_port => 8000, :output => { :host => "192.168.1.8", :port => 9000}).join
+  
+{Here's a blog post}[http://tx81z.blogspot.com/2011/10/osc-access-build-osc-into-ruby-objects.html] that explains these examples in further depth and much more.
+
+== Other Documentation
+
+* {rdoc}[http://rubydoc.info/github/arirusso/osc-access] 
+
+== License
+
+Licensed under Apache 2.0, See the file LICENSE
+
+Copyright �2011-2012 Ari Russo

data/lib/osc-access.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+#
+# OSCAccess
+# Control Ruby objects with OSC
+# (c)2011-2012 Ari Russo and licensed under the Apache 2.0 License
+# 
+
+# libs
+require "osc-ruby"
+require "osc-ruby/em_server"
+
+# modules
+require "osc-access/accessible"
+require "osc-access/class"
+
+# classes
+require "osc-access/class_scheme"
+require "osc-access/emittable_property"
+require "osc-access/emitter"
+require "osc-access/message"
+require "osc-access/receiver"
+require "osc-access/translate"
+require "osc-access/zeroconf"
+
+# other
+require "osc-access/default"
+
+module OSCAccess
+  
+  VERSION = "0.0.15"
+  
+end
+OSCAccessible = OSCAccess::Accessible

data/lib/osc-access/accessible.rb

@@ -0,0 +1,144 @@
+#!/usr/bin/env ruby
+module OSCAccess
+
+  module Accessible
+    
+    def self.included(base)
+      base.extend(Class)
+    end
+
+    def osc_receive(pattern, options = {}, &block)
+      osc_initialize
+      @osc_receiver.add_receiver(self, pattern, options, &block)
+      if !options[:accessor].nil?
+        @osc_properties << EmittableProperty.new(options[:accessor], pattern, options)
+      elsif !options[:initialize].nil?
+        @osc_properties << EmittableProperty.new(options[:initialize], pattern, options)
+      end
+    end
+        
+    def osc_send_property(prop)
+      prop = @osc_properties.find { |ep| ep.subject == prop } if prop.kind_of?(Symbol)
+      val = prop.translated(self)
+      msg = OSC::Message.new(prop.pattern, *val)
+      @osc_emitter.transmit(msg)
+      local_msg = OSC::Message.new(prop.pattern, *prop.value(self))
+      local_val = osc_process_arg_option(local_msg, :arg => prop.arg)
+      prop.action.call(self, local_val, local_msg) unless prop.action.nil?
+    end
+    
+    def osc_send(*a)
+      osc_initialize
+      a.first.kind_of?(Symbol) ? osc_send_property(a.first) : @osc_emitter.transmit(*a)      
+    end
+
+    def osc_join(options = {})
+      osc_initialize
+      @osc_receiver.join(options)
+    end
+
+    # osc_output takes arguments as such:
+    #
+    # osc_output(:host => "localhost", :port => 9000)
+    # osc_output(:host => "localhost", :port => [9000, 9002, 9005])
+    # osc_output(:host => "localhost", :port => 9000..9010)
+    #    
+    def osc_output(pair)
+      osc_initialize
+      ports = osc_process_ports_args(pair[:port])
+      ports.each { |port| @osc_emitter.add_client(pair[:host], port) }
+    end
+    
+    # osc_input takes arguments as such:
+    #
+    # osc_input(8000)
+    # osc_input(:port => 8000)
+    # osc_input(8000, 8005, 8010)
+    # osc_input(8000..8010)
+    #
+    def osc_input(*args)
+      osc_initialize
+      ports = osc_process_ports_args(args)
+      ports.each { |port| @osc_receiver.add_server(port) }
+    end
+    
+    def osc_start(options = {})
+      osc_initialize(options)
+      osc_initialize_from_class_def
+      osc_load_map(options[:map]) unless options[:map].nil?
+      
+      osc_input(options[:input_port]) unless options[:input_port].nil?
+      osc_output(options[:output]) unless options[:output].nil?
+      
+      Thread.new do 
+        sleep(1) 
+        osc_send_all_properties
+      end
+      
+      @osc_receiver.threads.first || Thread.new { Thread.abort_on_exception = true; loop {} }
+    end
+    
+    def osc_send_all_properties
+      osc_initialize
+      @osc_properties.each { |prop| osc_send_property(prop) }
+    end
+    
+    def osc_load_map(map)
+      osc_initialize
+      map.each { |attr, mapping| osc_add_map_row(attr, mapping) }      
+    end
+    
+    def osc_translate(value, range, options = {})
+      Translate.using(value, range, options)
+    end
+
+    protected
+
+    def osc_on_receive(msg, options = {}, &block)
+      val = osc_process_arg_option(msg, options)
+      val = osc_translate(val, options[:translate]) unless options[:translate].nil?
+      osc_send(msg) if options[:thru]
+      accessor = options[:accessor]
+      self.send("#{accessor.to_s}=", val) unless accessor.nil?
+      yield(self, val, msg) unless block.nil?
+    end
+
+    private
+
+    def osc_initialize(options = {})
+      @osc_emitter ||= Emitter.new
+      @osc_properties ||= []
+      @osc_receiver ||= Receiver.new
+    end
+        
+    def osc_initialize_from_class_def
+      scheme = self.class.osc_class_scheme
+      scheme.inputs.each { |port| @osc_receiver.add_server(port) }
+      scheme.outputs.each { |hash| @osc_emitter.add_client(hash) }
+      scheme.receivers.each { |hash| osc_receive(hash[:pattern], hash[:options], &hash[:action]) }  
+    end
+    
+    def osc_add_map_row(pattern, mapping)
+      options = mapping.kind_of?(Hash) ? mapping : {}
+      action = mapping.kind_of?(Hash) ? mapping[:action] : mapping
+      osc_receive(pattern, options, &action)
+    end
+    
+    def osc_process_arg_option(msg, options = {})
+      arg = options[:arg] || 0
+      array = (!arg.nil? && arg == :all)
+      array ? msg.args : msg.args[arg]
+    end
+    
+    def osc_process_ports_args(args)
+      case args
+        when Array then args.map { |a| osc_process_ports_args(a) }.flatten
+        when Hash then osc_process_ports_args(args[:port])
+        when Range then args.to_a
+        when Numeric then [args]
+      end
+    end
+    
+  end
+
+end

data/lib/osc-access/class.rb

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+module OSCAccess
+
+  module Class
+
+    def osc_class_scheme
+      osc_ensure_initialized
+      @osc_class_scheme
+    end
+    
+    def osc_receive(pattern, options = {}, &block)
+      osc_ensure_initialized
+      @osc_class_scheme.add_receiver(pattern, options, &block)
+    end
+    
+    def osc_output(args)
+      osc_ensure_initialized
+      @osc_class_scheme.outputs << args
+    end
+    
+    def osc_input(val)
+      osc_ensure_initialized
+      @osc_class_scheme.inputs << val
+    end
+    
+    private
+    
+    def osc_ensure_initialized
+      @osc_class_scheme ||= ClassScheme.new
+    end
+
+  end
+
+end

data/lib/osc-access/class_scheme.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+module OSCAccess
+  
+  class ClassScheme
+
+    attr_reader :inputs, 
+                :outputs, 
+                :receivers
+    
+    def initialize
+      @inputs, @outputs, @receivers = [], [], []
+    end
+    
+    def add_receiver(pattern, options = {}, &block)
+      @receivers << { :pattern => pattern, :options => options, :action => block }
+    end
+    
+  end
+
+end

data/lib/osc-access/default.rb

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+module OSCAccess
+  
+  DefaultPattern = /.*/
+  DefaultRemoteRange = 0..1
+
+end

data/lib/osc-access/emittable_property.rb

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+module OSCAccess
+
+  class EmittableProperty
+    
+    attr_reader :action, :arg, :pattern, :subject
+    
+    def initialize(subject, pattern, options = {})
+      @subject = subject
+      @pattern = pattern
+      @arg = options[:arg]
+      @translate = options[:translate]
+      @action = options[:action]
+    end
+    
+    def value(target_obj)
+      val = case @subject
+        when Proc then @subject.call(target_obj)
+        when Symbol then target_obj.send(@subject)
+      end
+      [val].flatten   
+    end
+    
+    def translated(target_obj)        
+      raw_val = value(target_obj)
+      @translate.nil? ? raw_val : Translate.using(raw_val, @translate, :to_local => false)  
+    end
+    
+  end
+
+end

data/lib/osc-access/emitter.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+module OSCAccess
+
+  class Emitter
+    
+    attr_reader :clients
+    
+    def initialize
+      @clients = []
+    end
+       
+    def add_client(host, port)
+      @clients << self.class.client(host, port)
+    end
+    
+    def transmit(*a)
+      msg = a.first.kind_of?(OSC::Message) ? a.first : OSC::Message.new(*a)
+      @clients.each { |c| c.send(msg) }
+    end
+    
+    def self.client(host, port)
+      @clients ||= {}
+      @clients[host] ||= {}
+      @clients[host][port] ||= OSC::Client.new(host, port)
+      @clients[host][port]
+    end
+    
+  end
+
+end

data/lib/osc-access/message.rb

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+module OSC
+  
+  class Message
+    
+    alias_method :args, :to_a
+    
+  end
+  
+end

data/lib/osc-access/receiver.rb

@@ -0,0 +1,75 @@
+#!/usr/bin/env ruby
+module OSCAccess
+
+  class Receiver
+
+    attr_reader :servers 
+             
+    def initialize(options = {})
+      @receivers = []
+      @servers = {}
+      @cached_message = nil
+    end
+    
+    def threads
+      @servers.values.map { |server| server[:thread] }
+    end
+    
+    def join(options = {})
+      port = options[:port]
+      thread = port.nil? ? threads.last : @servers[port][:thread]
+      thread.join
+    end
+    
+    def add_server(port)
+      server = self.class.server(port)
+      @servers[port] = server
+      @receivers.each { |receiver| add_method(server[:server], receiver) }
+      @servers[port][:thread]
+    end
+    
+    def add_receiver(target_obj, pattern, options = {}, &block)
+      receiver = { 
+        :target_obj => target_obj, 
+        :pattern => pattern, 
+        :options => options, 
+        :action => block 
+      }
+      @receivers << receiver
+      @servers.values.each { |server| add_method(server[:server], receiver) }     
+    end
+
+    def self.server(port)
+      @servers ||= {}
+      @servers[port] ||= { :server => OSC::EMServer.new(port) }
+      @servers[port][:thread] ||= thread_for(port)
+      @servers[port]
+    end
+    
+    def self.thread_for(port)
+      @servers[port][:thread] ||= Thread.new do
+        @servers[port][:service] ||= Zeroconf::Service.new("Ruby", port).start
+        Thread.abort_on_exception = true
+        @servers[port][:server].run
+      end
+    end
+    
+    private
+    
+    def add_method(server, receiver)
+      options = receiver[:options]
+      obj = receiver[:target_obj]
+      pattern = receiver[:pattern].dup
+      # this prevents the same action being called multiple times when
+      # an receiver object has multiple servers
+      server.add_method(pattern) do |message| 
+        unless @cached_message === message
+          obj.send(:osc_on_receive, message, options, &receiver[:action]) 
+          @cached_message = message
+        end
+      end
+    end
+
+  end
+
+end