midi-nibbler 0.1.1 → 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e8413384db29c1e35d128afb0d982cfd866472c8
+  data.tar.gz: 1652fbc29119c0d0cb0f97f4e7c66167cf906253
+SHA512:
+  metadata.gz: 66610505ed6b6111864ca1467d90ab72366bdb874ec3f401b56608e857ba2139b7fe3fe8144fee7bceafe5ef4c7eb6ce16e4f931399fccb998cc3682bfb58f52
+  data.tar.gz: 228e832b552cac66f79b46d2ea9cd6bf1edd67d7535e791e00ec4621a1a74180f6f365ee661268c87936379e06c370abd7adeccc2feefa54438b401eaf6b08a2

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2010-2011 Ari Russo
+Copyright 2011-2014 Ari Russo
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -10,4 +10,4 @@ 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.
+limitations under the License.

data/README.md

@@ -0,0 +1,139 @@
+# Nibbler
+
+![nibbler](http://img17.imageshack.us/img17/1713/dogwithsynth.jpg)
+
+Parse MIDI Messages
+	
+## Install
+
+`gem install midi-nibbler`
+
+or using Bundler, add this to your Gemfile
+
+`gem "midi-nibbler"`
+
+## Usage
+
+```ruby
+require 'nibbler'
+  
+nibbler = Nibbler.new
+```
+
+Enter a message piece by piece
+  
+```ruby
+nibbler.parse("90")
+  => nil
+
+nibbler.parse("40")
+  => nil
+
+nibbler.parse("40")
+  => #<MIDIMessage::NoteOn:0x98c9818 
+       @channel=0, 
+       @data=[64, 100], 
+       @name="C3", 
+       @note=64, 
+       @status=[9, 0], 
+       @velocity=100, 
+       @verbose_name="Note On: C3">
+```
+  
+Enter a message all at once
+  
+```ruby
+nibbler.parse("904040")
+  
+  => #<MIDIMessage::NoteOn:0x98c9818 
+        @channel=0, 
+        @data=[64, 100], 
+        @name="C3", 
+        @note=64, 
+        @status=[9, 0], 
+        @velocity=100, 
+        @verbose_name="Note On: C3">
+```
+ 
+Use bytes
+
+```ruby
+nibbler.parse(0x90, 0x40, 0x40)
+  => #<MIDIMessage::NoteOn:0x98c9818 ...>
+```
+
+You can use nibbles in string format
+ 
+```ruby
+nibbler.parse("9", "0", "4", "0", "4", "0")
+  => #<MIDIMessage::NoteOn:0x98c9818 ...>
+```
+
+Interchange the different types
+  
+```ruby
+nibbler.parse("9", "0", 0x40, 64)
+  => #<MIDIMessage::NoteOn:0x98c9818 ...>
+```
+
+Use running status
+
+```ruby
+nibbler.parse(0x40, 64)
+  => #<MIDIMessage::NoteOn:0x98c9818 ...>
+```
+
+Look at the messages we've parsed
+  
+```ruby
+nibbler.messages
+  => [#<MIDIMessage::NoteOn:0x98c9804 ...>
+      #<MIDIMessage::NoteOn:0x98c9811 ...>]
+```
+
+Add an incomplete message
+  
+```ruby
+nibbler.parse("9")
+nibbler.parse("40")
+```
+
+See progress
+
+```ruby
+nibbler.buffer
+  => ["9", "4", "0"]
+
+nibbler.buffer_s
+  => "940"
+```
+  
+Pass in a timestamp
+
+```ruby
+nibbler.parse("904040", :timestamp => Time.now.to_i)
+  => { :messages=> #<MIDIMessage::NoteOn:0x92f4564 ..>, :timestamp=>1304488440 }
+```
+
+Nibbler defaults to generate [midi-message](http://github.com/arirusso/midi-message) objects, but it is also possible to use [midilib](https://github.com/jimm/midilib)
+
+```ruby
+Nibbler.new(:message_lib => :midilib)
+  
+nibbler.parse("9", "0", 0x40, "40")
+  => "0: ch 00 on 40 40"
+```
+
+## Also see
+
+* [midi-eye](http://github.com/arirusso/midi-eye), a MIDI event listener based on nibbler
+
+## Author
+
+* [Ari Russo](http://github.com/arirusso) <ari.russo at gmail.com>
+
+## License
+
+Apache 2.0, See the file LICENSE
+
+Copyright (c) 2011-2014 Ari Russo

data/lib/nibbler.rb

@@ -1,26 +1,29 @@
-#!/usr/bin/env ruby
 #
 # Parse MIDI Messages
-# (c)2011 Ari Russo and licensed under the Apache 2.0 License
+# (c)2011-2014 Ari Russo and licensed under the Apache 2.0 License
 # 
 
-require 'forwardable'
+# libs
+require "forwardable"
 
-require 'nibbler/nibbler'
-require 'nibbler/parser'
-require 'nibbler/type_conversion'
-require 'nibbler/hex_char_array_filter'
+# modules
+require "nibbler/hex_processor"
+require "nibbler/type_conversion"
+
+# classes
+require "nibbler/parser"
+require "nibbler/session"
 
 #
 # Parse MIDI Messages
 #
 module Nibbler
   
-  VERSION = "0.1.1"
+  VERSION = "0.2.1"
 
-  # shortcut to Parser.new
+  # Shortcut to a new parser session
   def self.new(*a, &block)
-    Nibbler.new(*a, &block)
+    Session.new(*a, &block)
   end
 
 end

data/lib/nibbler/hex_processor.rb

@@ -0,0 +1,47 @@
+module Nibbler  
+  
+  # Accepts various types of input and returns an array of hex digit chars
+  module HexProcessor
+
+    extend self
+       
+    # Accepts various types of input and returns an array of hex digit chars
+    # Invalid input is disregarded
+    #
+    # @param [*String, *Fixnum] args
+    # @return [Array<String>] An array of hex string nibbles eg "6", "a"
+    def process(*args)
+      args.map { |arg| convert(arg) }.flatten.compact.map(&:upcase) 
+    end
+    
+    private
+
+    # Convert a single value to hex chars
+    # @param [Array<Fixnum>, Array<String>, Fixnum, String] value
+    # @return [Array<String>]
+    def convert(value)
+      case value
+        when Array then value.map { |arr| process(*arr) }.reduce(:+)
+        when String then TypeConversion.hex_str_to_hex_chars(filter_string(value))
+        when Fixnum then TypeConversion.numeric_byte_to_hex_chars(filter_numeric(value))
+      end
+    end
+    
+    # Limit the given number to bytes usable in MIDI ie values (0..240)
+    # returns nil if the byte is outside of that range
+    # @param [Fixnum] num
+    # @return [Fixnum, nil]
+    def filter_numeric(num)
+      num if (0x00..0xFF).include?(num)
+    end
+    
+    # Only return valid hex string characters
+    # @param [String] string
+    # @return [String]
+    def filter_string(string)
+      string.gsub(/[^0-9a-fA-F]/, "").upcase
+    end
+  
+  end
+
+end

data/lib/nibbler/midi-message.rb

@@ -0,0 +1,53 @@
+require "midi-message"
+
+module Nibbler
+
+  # Construct messages with MIDIMessage in a generic way
+  # http://github.com/arirusso/midi-message
+  module MIDIMessage
+
+    extend self
+        
+    def note_off(second_nibble, data_byte_1, data_byte_2)
+      ::MIDIMessage::NoteOff.new(second_nibble, data_byte_1, data_byte_2)
+    end
+    
+    def note_on(second_nibble, data_byte_1, data_byte_2)
+      ::MIDIMessage::NoteOn.new(second_nibble, data_byte_1, data_byte_2)
+    end
+    
+    def polyphonic_aftertouch(second_nibble, data_byte_1, data_byte_2)
+      ::MIDIMessage::PolyphonicAftertouch.new(second_nibble, data_byte_1, data_byte_2)
+    end
+      
+    def control_change(second_nibble, data_byte_1, data_byte_2)
+      ::MIDIMessage::ControlChange.new(second_nibble, data_byte_1, data_byte_2)
+    end
+    
+    def program_change(second_nibble, data_byte)
+      ::MIDIMessage::ProgramChange.new(second_nibble, data_byte)
+    end
+    
+    def channel_aftertouch(second_nibble, data_byte)
+      ::MIDIMessage::ChannelAftertouch.new(second_nibble, data_byte)
+    end
+    
+    def pitch_bend(second_nibble, data_byte_1, data_byte_2)
+      ::MIDIMessage::PitchBend.new(second_nibble, data_byte_1, data_byte_2)
+    end
+    
+    def system_exclusive(*a)
+      ::MIDIMessage::SystemExclusive.new(*a)
+    end
+    
+    def system_common(second_nibble, data_byte_1 = nil, data_byte_2 = nil)
+      ::MIDIMessage::SystemCommon.new(second_nibble, data_byte_1, data_byte_2)
+    end
+    
+    def system_realtime(second_nibble)
+      ::MIDIMessage::SystemRealtime.new(second_nibble)
+    end
+
+  end
+
+end

data/lib/nibbler/midilib.rb

@@ -0,0 +1,67 @@
+require "midilib"
+
+module Nibbler
+
+  # Construct messages with midilib in a generic way
+  # https://github.com/jimm/midilib
+  # midilib is copyright © 2003-2010 Jim Menard
+  module Midilib
+
+    extend self
+    
+    def note_off(second_nibble, data_byte_1, data_byte_2)
+      MIDI::NoteOff.new(second_nibble, data_byte_1, data_byte_2)
+    end
+    
+    def note_on(second_nibble, data_byte_1, data_byte_2)
+      MIDI::NoteOn.new(second_nibble, data_byte_1, data_byte_2)
+    end
+    
+    def polyphonic_aftertouch(second_nibble, data_byte_1, data_byte_2)
+      MIDI::PolyPressure.new(second_nibble, data_byte_1, data_byte_2)
+    end
+      
+    def control_change(second_nibble, data_byte_1, data_byte_2)
+      MIDI::Controller.new(second_nibble, data_byte_1, data_byte_2)
+    end
+    
+    def program_change(second_nibble, data_byte)
+      MIDI::ProgramChange.new(second_nibble, data_byte)
+    end
+    
+    def channel_aftertouch(second_nibble, data_byte)
+      MIDI::ChannelPressure.new(second_nibble, data_byte)
+    end
+    
+    def pitch_bend(second_nibble, data_byte_1, data_byte_2)
+      # to-do handle the midilib lsb/msb
+      # right now the second data byte is being thrown away
+      MIDI:: PitchBend.new(second_nibble, data_byte_1, data_byte_2)
+    end
+    
+    def system_exclusive(*a)
+      MIDI::SystemExclusive.new(a)
+    end
+    
+    def system_common(second_nibble, data_byte_1 = nil, data_byte_2 = nil)
+      case second_nibble
+        when 0x2 then MIDI::SongPointer.new(data_byte_1) # similar issue to pitch bend here
+        when 0x3 then MIDI::SongSelect.new(data_byte_1)
+        when 0x6 then MIDI::TuneRequest.new
+      end      
+    end
+    
+    def system_realtime(second_nibble)
+      case second_nibble
+        when 0x8 then MIDI::Clock.new
+        when 0xA then MIDI::Start.new
+        when 0xB then MIDI::Continue.new
+        when 0xC then MIDI::Stop.new
+        when 0xE then MIDI::ActiveSense.new
+        when 0xF then MIDI::SystemReset.new
+      end      
+    end  
+    
+  end
+
+end

data/lib/nibbler/parser.rb

@@ -1,32 +1,23 @@
-#!/usr/bin/env ruby
-#
 module Nibbler
- 
 
-  # this is where messages go
   class Parser
-    
+
     attr_reader :buffer
-    
+
+    # @param [Hash] options
+    # @option options [Symbol] :message_lib
     def initialize(options = {})
       @running_status = nil
       @buffer = []
       @iterator = 0
-      
-      case options[:message_lib]
-        when :midilib then    
-          require 'midilib'
-          require 'nibbler/midilib_factory'
-          @message_factory = MidilibFactory.new
-        else    
-          require 'midi-message'    
-          require 'nibbler/midi-message_factory'    
-          @message_factory = MIDIMessageFactory.new    
-      end 
+
+      initialize_message_library(options[:message_lib])
     end
 
+    # @param [Array<String, Fixnum>] nibbles
+    # @return [Hash]
     def process(nibbles)
-      output = { 
+      report = { 
         :messages => [], 
         :processed => [], 
         :rejected => [] 
@@ -37,118 +28,119 @@ module Nibbler
         # iterate through nibbles until a status message is found        
         # see if there really is a message there
         populate_current
-        # current is the current piece of the buffer we're dealing with
-        processed = nibbles_to_message
-        unless processed[:message].nil?
-          # if it's a real message, reject previous nibbles
-          output[:rejected] += @buffer.slice(0, @iterator)          
+        # current is the current piece of the buffer we"re dealing with
+        unless (processed = nibbles_to_message).nil?
+          # if it"s a real message, reject previous nibbles
+          report[:rejected] += @buffer.slice(0, @iterator)          
           # and record it          
           @buffer = @current # current now has the remaining nibbles for next pass
           @current = nil # reset current
           @iterator = 0 # reset iterator
-          output[:messages] << processed[:message]
-          output[:processed] += processed[:processed]          
+          report[:messages] << processed[:message]
+          report[:processed] += processed[:processed]          
         else
           @running_status = nil
           @iterator += 1
         end         
       end
-      output
+      report
     end
-    
+
+    # @return [Hash, nil]
     def nibbles_to_message
-      output = { 
-        :message => nil, 
-        :processed => [], 
-        :remaining => nil 
-      } 
-      return output if @current.length < 2
-      first = @current[0].hex
-      second = @current[1].hex
-      
-      output[:message], output[:processed] = *case first
-        when 0x8 then lookahead(6) { |status_2, bytes| @message_factory.note_off(status_2, bytes[1], bytes[2]) }
-        when 0x9 then lookahead(6) { |status_2, bytes| @message_factory.note_on(status_2, bytes[1], bytes[2]) }
-        when 0xA then lookahead(6) { |status_2, bytes| @message_factory.polyphonic_aftertouch(status_2, bytes[1], bytes[2]) }
-        when 0xB then lookahead(6) { |status_2, bytes| @message_factory.control_change(status_2, bytes[1], bytes[2]) }
-        when 0xC then lookahead(4) { |status_2, bytes| @message_factory.program_change(status_2, bytes[1]) }
-        when 0xD then lookahead(4) { |status_2, bytes| @message_factory.channel_aftertouch(status_2, bytes[1]) }
-        when 0xE then lookahead(6) { |status_2, bytes| @message_factory.pitch_bend(status_2, bytes[1], bytes[2]) }
-        when 0xF then case second
-          when 0x0 then lookahead_sysex { |bytes| @message_factory.system_exclusive(*bytes) }
-          when 0x1..0x6 then lookahead(6, :recursive => true) { |status_2, bytes| @message_factory.system_common(status_2, bytes[1], bytes[2]) }
-          when 0x8..0xF then lookahead(2) { |status_2, bytes| @message_factory.system_realtime(status_2) }
-        end
-        else
-          use_running_status if running_status_possible?            
+      if @current.length >= 2
+        nibbles = @current.slice(0..1).map(&:hex)
+        compute_message(nibbles)           
       end
-      output
     end
-    
+
     private
-    
-    def running_status_possible?
+
+    # @param [Array<Fixnum>] nibbles
+    # @return [Hash, nil]
+    def compute_message(nibbles)
+      case nibbles[0]
+      when 0x8 then lookahead(6) { |status_2, bytes| @message.note_off(status_2, bytes[1], bytes[2]) }
+      when 0x9 then lookahead(6) { |status_2, bytes| @message.note_on(status_2, bytes[1], bytes[2]) }
+      when 0xA then lookahead(6) { |status_2, bytes| @message.polyphonic_aftertouch(status_2, bytes[1], bytes[2]) }
+      when 0xB then lookahead(6) { |status_2, bytes| @message.control_change(status_2, bytes[1], bytes[2]) }
+      when 0xC then lookahead(4) { |status_2, bytes| @message.program_change(status_2, bytes[1]) }
+      when 0xD then lookahead(4) { |status_2, bytes| @message.channel_aftertouch(status_2, bytes[1]) }
+      when 0xE then lookahead(6) { |status_2, bytes| @message.pitch_bend(status_2, bytes[1], bytes[2]) }
+      when 0xF then 
+        case nibbles[1]
+        when 0x0 then lookahead_sysex { |bytes| @message.system_exclusive(*bytes) }
+        when 0x1..0x6 then lookahead(6, :recursive => true) { |status_2, bytes| @message.system_common(status_2, bytes[1], bytes[2]) }
+        when 0x8..0xF then lookahead(2) { |status_2, bytes| @message.system_realtime(status_2) }
+        end
+      else
+        use_running_status if possible_running_status? 
+      end
+    end
+
+    # Choose a MIDI message object library
+    def initialize_message_library(lib)
+      @message = case lib
+      when :midilib then    
+        require "nibbler/midilib"
+        ::Nibbler::Midilib
+      else      
+        require "nibbler/midi-message"    
+        ::Nibbler::MIDIMessage    
+      end
+    end
+
+    def possible_running_status?
       !@running_status.nil?
     end
-    
+
     def use_running_status
-      lookahead(@running_status[:num], :status_nibble => @running_status[:status_nibble], &@running_status[:block])
+      lookahead(@running_status[:num], :status_nibble => @running_status[:status_nibble], &@running_status[:callback])
     end  
-    
+
     def populate_current
       @current = (@buffer[@iterator, (@buffer.length - @iterator)])
     end
-    
-    def lookahead(num, options = {}, &block)
-      recursive = !options[:recursive].nil? && options[:recursive]
-      status_nibble = options[:status_nibble]
-      processed = []
-      msg = nil             
+
+    def lookahead(num, options = {}, &callback)
       # do we have enough nibbles for num bytes?
-      if @current.slice(0, num).length >= num
+      if @current.size >= num
+        # if so shift those nibbles off of the array and call block with them
+        nibbles = @current.slice!(0, num)
+        status_nibble ||= options[:status_nibble] || nibbles[1]  
 
-        # if so shift those nibbles off of the array and call block with them        
-        processed += @current.slice!(0, num)
-        status_nibble ||= processed[1]       
         # send the nibbles to the block as bytes         
         # return the evaluated block and the remaining nibbles       
-        bytes = TypeConversion.hex_chars_to_numeric_bytes(processed)
+        bytes = TypeConversion.hex_chars_to_numeric_bytes(nibbles)
+
         # record the current situation in case running status comes up next round
         @running_status = { 
-          :block => block, 
+          :callback => callback, 
           :num => num - 2, 
           :status_nibble => status_nibble 
         }
-        msg = block.call(status_nibble.hex, bytes)
-      elsif num > 0 && recursive
-        msg, processed = *lookahead(num-2, options, &block)
+
+        {
+          :message => yield(status_nibble.hex, bytes),
+          :processed => nibbles
+        }
+      elsif num > 0 && !!options[:recursive]
+        lookahead(num - 2, options, &callback)
       end
-      [msg, processed]
     end
-        
+
     def lookahead_sysex(&block)
-      processed = []
-      msg = nil      
       @running_status = nil
-      
+
       bytes = TypeConversion.hex_chars_to_numeric_bytes(@current)
-      ind = bytes.index(0xF7)
-      unless ind.nil?
-        msg = block.call(bytes.slice!(0, ind + 1))
-        processed += @current.slice!(0, (ind + 1) * 2)
+      unless (index = bytes.index(0xF7)).nil?
+        {
+          :message => yield(bytes.slice!(0, index + 1)),
+          :processed => @current.slice!(0, (index + 1) * 2)
+        }
       end
-      [msg, processed]
     end
-    
-    # for testing
-    def buffer=(val)
-      @buffer=val
-    end
-    
-    def current
-      @current
-    end
-    
+
   end
 
-end
+end