midi-eye 0.2.2

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2011 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,73 @@
+= midi-eye
+
+A transparent MIDI input event listener for Ruby 
+
+== Requirements
+
+* {midi-message}[http://github.com/arirusso/midi-message]
+* {nibbler}[http://github.com/arirusso/nibbler]
+* {unimidi}[http://github.com/arirusso/unimidi]
+
+== Install
+
+  gem install midi-eye
+	
+== Usage
+
+  require 'midi-eye'
+
+The following is an example that takes any note messages received from a unimidi input, transposes them up one octave and then sends them to an output  
+  
+First, initialize the MIDI IO ports
+  
+  @input = UniMIDI::Input.gets
+  @output = UniMIDI::Output.gets
+  
+Then create a listener for the input port
+ 
+  transpose = MIDIEye::Listener.new(@input)
+
+You can bind an event to the listener using Listener#listen_for
+
+The listener will try to positively match the parameters you pass in to the properties of the messages it receives.
+
+In this example, we will tell the listener to listen for note on/off messages which are easily identifiable by their class
+
+You also have the option of leaving out the parameters altogether and including using conditional if/unless/case/etc statements in your callback
+
+  transpose.listen_for(:class => [MIDIMessage::NoteOn, MIDIMessage::NoteOff]) do |event|
+   
+    # raise the note value by an octave
+    event[:message].note += 12
+    
+    # send the altered note message to the output you chose earlier 
+    @output.puts(event[:message])
+  
+  end
+  
+You can bind as many events to a listener as you wish, just keep calling Listener#listen_for
+
+Once all the events are bound, start the listener
+    
+  transpose.run
+   
+A listener can also be run in a background thread by passing in :background => true.
+
+  transpose.run(:background => true)
+  
+  transpose.join # join the background thread later
+
+== Documentation
+
+* {examples}[http://github.com/arirusso/midi-eye/tree/master/examples]
+* {rdoc}[http://rdoc.info/gems/midi-eye]
+    
+== Author
+
+* {Ari Russo}[http://github.com/arirusso] <ari.russo at gmail.com>
+
+== License
+
+Apache 2.0, See the file LICENSE
+
+Copyright (c) 2011 Ari Russo

data/lib/midi-eye.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+#
+# midi-eye
+# Transparent MIDI event listener for Ruby
+# (c)2011 Ari Russo 
+# licensed under the Apache 2.0 License
+# 
+
+require 'midi-message'
+require 'nibbler'
+require 'unimidi'
+
+require 'midi-eye/listener'
+require 'midi-eye/unimidi_input'
+
+module MIDIEye
+  
+  VERSION = "0.2.2"
+  
+end

data/lib/midi-eye/listener.rb

@@ -0,0 +1,150 @@
+#!/usr/bin/env ruby
+module MIDIEye
+  
+  class Listener
+    
+    attr_reader :events 
+    attr_accessor :sources
+      
+    @input_types = []
+      
+    class << self
+      # a registry of input types
+      attr_reader :input_types      
+    end
+        
+    def initialize(input, options = {})
+      @sources = []
+      @event_queue = []
+      @events = []
+  
+      add_input(input)
+    end
+    
+    # does this listener use <em>input</em>?
+    def uses_input?(input)
+      !@sources.find_all { |source| source.uses?(input) }.empty?
+    end
+    
+    # add a source
+    # takes a raw input or array of
+    def add_input(input)
+      @sources += [input].flatten.map do |i|
+        klass = self.class.input_types.find { |type| type.is_compatible?(i) }
+        raise "Input class type #{i.class.name} not compatible" if klass.nil?
+        klass.new(i) unless uses_input?(i)
+      end.compact
+    end
+    
+    # remove a source
+    # takes a raw input or array of
+    def remove_input(inputs)
+      to_remove = [inputs].flatten
+      to_remove.each do |input|
+        @sources.delete_if { |source| source.uses?(input) }
+      end
+    end
+    
+    def delete_event(name)
+      @events.delete_if { |e| e[:listener_name] == name }
+    end
+    
+    # start the listener. pass in :background => true to run only in a background thread. returns self
+    def run(options = {})      
+      listen!
+      unless options[:background]
+        @listener.join  
+      end
+      self
+    end
+    alias_method :start, :run
+    
+    # stop the listener. returns self
+    def close
+      @listener.kill unless @listener.nil?
+      @events.clear
+      @sources.clear
+      @event_queue.clear
+      self
+    end
+    alias_method :stop, :close
+    
+    # join the listener if it's being run in the background. returns self
+    def join
+      @listener.join
+      self
+    end
+    
+    # add an event to listen for. returns self
+    def listen_for(options = {}, &proc)
+      raise 'listener must have a block' if proc.nil?
+      name = options[:listener_name]
+      options.delete(:listener_name)
+      @events << { :conditions => options, :proc => proc, :listener_name => name }
+      self      
+    end
+    alias_method :on_message, :listen_for
+    alias_method :listen, :listen_for
+    
+    # poll the input source for new input. this will normally be done by the background thread 
+    def poll
+      @sources.each do |input|
+        input.poll do |objs|
+          objs.each do |batch|
+            [batch[:messages]].flatten.each do |single_message|
+              unless single_message.nil?
+                data = { :message => single_message, :timestamp => batch[:timestamp] }
+                @events.each { |name| queue_event(name, data) }
+              end
+            end 
+          end
+        end
+      end
+    end
+
+    private
+    
+    # start the background listener thread    
+    def listen!   
+      t = 1.0/1000
+      @listener = Thread.fork do       
+        Thread.abort_on_exception = true
+        loop do
+          poll
+          trigger_queued_events unless @event_queue.empty?
+          sleep(t)
+        end
+      end
+    end
+    
+    # trigger all queued events
+    def trigger_queued_events
+      @event_queue.length.times { trigger_event(@event_queue.shift) }
+    end
+    
+    # does <em>message</em> meet <em>conditions</em>?
+    def meets_conditions?(conditions, message)
+      !conditions.map do |key, value|
+        message.respond_to?(key) && (value.kind_of?(Array) ? value.include?(message.send(key)) : value.eql?(message.send(key))) 
+      end.include?(false)
+    end
+    
+    # trigger an event
+    def trigger_event(event)
+      begin
+        action = event[:action]
+        if meets_conditions?(action[:conditions], event[:message][:message]) || action[:conditions].nil?
+          action[:proc].call(event[:message])
+        end
+      rescue
+      end
+    end
+    
+    # add an event to the trigger queue 
+    def queue_event(event, message)  
+      @event_queue << { :action => event, :message => message }
+    end
+                
+  end  
+  
+end

data/lib/midi-eye/unimidi_input.rb

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+#
+module MIDIEye
+  
+  # this class deals with retrieving new messages from
+  # a unimidi input buffer
+  class UniMIDIInput
+    
+    attr_reader :device, :pointer
+    
+    def initialize(input)   
+      @parser = Nibbler.new   
+      @pointer = 0      
+      @device = input      
+    end
+    
+    # this grabs new messages from the unimidi buffer
+    def poll(&block)
+      msgs = @device.buffer.slice(@pointer, @device.buffer.length - @pointer)
+      @pointer = @device.buffer.length
+      msgs.each do |raw_msg| 
+        unless raw_msg.nil?      
+          objs = [@parser.parse(raw_msg[:data], :timestamp => raw_msg[:timestamp])].flatten.compact rescue []
+          yield(objs)
+        end
+      end    
+    end
+    
+    # if <em>input</em> looks like a unimidi input, this returns true
+    def self.is_compatible?(input)
+      input.respond_to?(:gets) && input.respond_to?(:buffer)
+    end
+    
+    # if this source was created from <em>input</em>
+    def uses?(input)
+      @device == input
+    end
+    
+    # add this class to the Listener class' known input types
+    Listener.input_types << self 
+    
+  end
+            
+end

data/test/helper.rb

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+
+dir = File.dirname(File.expand_path(__FILE__))
+$LOAD_PATH.unshift dir + '/../lib'
+
+require 'test/unit'
+require 'midi-eye'
+
+module TestHelper
+  
+  def self.select_devices
+    $test_device ||= {}
+    { :input => UniMIDI::Input, :output => UniMIDI::Output }.each do |type, klass|
+      $test_device[type] = klass.gets
+    end
+  end
+  
+  def close_all(input, output, listener)
+    listener.close
+    input.clear_buffer
+    input.close
+    output.close
+    sleep(0.1)
+  end
+     
+end
+
+TestHelper.select_devices

data/test/test_listener.rb

@@ -0,0 +1,156 @@
+#!/usr/bin/env ruby
+
+require 'helper'
+
+class ListenerTest < Test::Unit::TestCase
+
+  include MIDIEye
+  include MIDIMessage
+  include TestHelper
+  
+  def test_rapid_control_change_message
+    sleep(0.2)
+    output = $test_device[:output]
+    input = $test_device[:input]
+    listener = Listener.new(input)
+    @i = 0
+    listener.listen_for(:class => ControlChange) do |event|
+      @i += 1
+      if @i == 5 * 126
+        close_all(input, output, listener)
+        assert_equal(5 * 126, @i)
+      end
+    end
+    listener.start(:background => true)
+    sleep(0.5)
+    5.times do
+      126.times do |i|
+        output.puts(176, 1, i+1)
+      end
+    end
+    listener.join    
+  end
+  
+  def test_control_change_message
+    sleep(0.2)
+    output = $test_device[:output]
+    input = $test_device[:input]
+    listener = Listener.new(input)
+    listener.listen_for(:class => ControlChange) do |event|
+      assert_equal(ControlChange, event[:message].class)
+      assert_equal(1, event[:message].index)      
+      assert_equal(35, event[:message].value)
+      assert_equal([176, 1, 35], event[:message].to_bytes)
+      close_all(input, output, listener)
+    end
+    listener.start(:background => true)
+    sleep(0.5)
+    output.puts(176, 1, 35)
+    listener.join    
+  end
+  
+  def test_delete_event
+    sleep(0.2)
+    output = $test_device[:output]
+    input = $test_device[:input]
+    listener = Listener.new(input)
+    listener.listen_for(:listener_name => :test) do |event|
+      assert_equal(1, listener.events.size)
+      listener.delete_event(:test)
+      assert_equal(0, listener.events.size)
+      close_all(input, output, listener)
+    end
+    listener.start(:background => true)
+    sleep(0.5)
+    output.puts(0x90, 0x70, 0x20)
+    listener.join 
+  end
+  
+  def test_uses_input
+    sleep(0.2)
+    output = $test_device[:output]
+    input = $test_device[:input]
+    listener = Listener.new(input)
+    assert_equal(true, listener.uses_input?(input))    
+  end
+  
+  def test_reject_dup_input
+    sleep(0.2)
+    output = $test_device[:output]
+    input = $test_device[:input]
+    listener = Listener.new(input)
+    listener.add_input(input)
+    assert_equal(1, listener.sources.size)     
+  end
+  
+  def test_remove_input
+    sleep(0.2)
+    output = $test_device[:output]
+    input = $test_device[:input]
+    listener = Listener.new(input)
+    assert_equal(1, listener.sources.size)
+    listener.remove_input(input)
+    assert_equal(0, listener.sources.size)  
+  end
+  
+  def test_recognize_input_class
+    sleep(0.2)
+    input = $test_device[:input]
+    output = $test_device[:output]
+    listener = Listener.new(input)
+    assert_equal(UniMIDIInput, listener.sources.first.class)
+    close_all(input, output, listener)
+  end
+  
+  def test_listen_for_basic
+    sleep(0.2)
+    @i = 0
+    output = $test_device[:output]
+    input = $test_device[:input]
+    listener = Listener.new(input)
+    listener.listen_for do |event|
+      @i += 1
+      assert_equal(1, @i)
+      close_all(input, output, listener)
+    end
+    listener.start(:background => true)
+    sleep(0.5)
+    output.puts(0x90, 0x40, 0x10)
+    listener.join
+  end
+
+  def test_listen_for_sysex
+    sleep(0.2)
+    output = $test_device[:output]
+    input = $test_device[:input]
+    listener = Listener.new(input)
+    listener.listen_for(:class => SystemExclusive::Command) do |event|
+      assert_equal(SystemExclusive::Command, event[:message].class)
+      assert_equal([0xF0, 0x41, 0x10, 0x42, 0x12, 0x40, 0x00, 0x7F, 0x00, 0x41, 0xF7], event[:message].to_byte_array)
+      close_all(input, output, listener)
+    end
+    listener.start(:background => true)
+    sleep(0.5)
+    output.puts(0xF0, 0x41, 0x10, 0x42, 0x12, 0x40, 0x00, 0x7F, 0x00, 0x41, 0xF7)
+    listener.join
+  end
+  
+  def test_listen_for_note_on
+    sleep(0.2)
+    output = $test_device[:output]
+    input = $test_device[:input]
+    listener = Listener.new(input)
+    listener.listen_for(:class => NoteOff) do |event|
+      assert_equal(NoteOff, event[:message].class)
+      assert_equal(0x50, event[:message].note)      
+      assert_equal(0x40, event[:message].velocity)
+      assert_equal([0x80, 0x50, 0x40], event[:message].to_bytes)
+      close_all(input, output, listener)
+    end
+    listener.start(:background => true)
+    sleep(0.5)
+    output.puts(0x80, 0x50, 0x40)
+    listener.join
+  end
+  
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: midi-eye
+version: !ruby/object:Gem::Version
+  version: 0.2.2
+  prerelease: 
+platform: ruby
+authors:
+- Ari Russo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-10-05 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: midi-message
+  requirement: &70223965375620 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70223965375620
+- !ruby/object:Gem::Dependency
+  name: midi-nibbler
+  requirement: &70223965375080 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70223965375080
+- !ruby/object:Gem::Dependency
+  name: unimidi
+  requirement: &70223965374640 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70223965374640
+description: MIDI event listener for Ruby
+email:
+- ari.russo@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/midi-eye/listener.rb
+- lib/midi-eye/unimidi_input.rb
+- lib/midi-eye.rb
+- test/helper.rb
+- test/test_listener.rb
+- LICENSE
+- README.rdoc
+homepage: http://github.com/arirusso/midi-eye
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.3.6
+requirements: []
+rubyforge_project: midi-eye
+rubygems_version: 1.8.6
+signing_key: 
+specification_version: 3
+summary: MIDI event listener for Ruby
+test_files: []