midi-parser 0.3.0

data/LICENSE.nibbler

@@ -0,0 +1,13 @@
+Copyright 2011-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,187 @@
+# MIDI Parser
+
+**Ruby Parser for Raw MIDI Messages**
+
+This library is part of a suite of Ruby libraries for MIDI:
+
+| Function | Library |
+| --- | --- |
+| MIDI Events representation | [MIDI Events](https://github.com/javier-sy/midi-events) |
+| MIDI Data parsing | [MIDI Parser](https://github.com/javier-sy/midi-parser) |
+| MIDI communication with Instruments and Control Surfaces | [MIDI Communications](https://github.com/javier-sy/midi-communications) |
+| Low level MIDI interface to MacOS | [MIDI Communications MacOS Layer](https://github.com/javier-sy/midi-communications-macos) |
+| Low level MIDI interface to Linux | **TO DO** | 
+| Low level MIDI interface to JRuby | **TO DO** | 
+| Low level MIDI interface to Windows | **TO DO** | 
+
+This library is based on [Ari Russo's](http://github.com/arirusso) library [Nibbler](https://github.com/arirusso/nibbler).
+
+## Install
+
+`gem install midi-parser`
+
+or using Bundler, add this to your Gemfile
+
+`gem "midi-parser"`
+
+## Usage
+
+```ruby
+require 'midi-parser'
+
+midi_parser = MIDIParser.new
+```
+
+Enter a message piece by piece:
+
+```ruby
+midi_parser.parse("90")
+  => nil
+
+midi_parser.parse("40")
+  => nil
+
+midi_parser.parse("40")
+  => #<MIDIEvents::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
+midi_parser.parse("904040")
+
+  => #<MIDIEvents::NoteOn:0x98c9818
+        @channel=0,
+        @data=[64, 100],
+        @name="C3",
+        @note=64,
+        @status=[9, 0],
+        @velocity=100,
+        @verbose_name="Note On: C3">
+```
+
+Use bytes:
+
+```ruby
+midi_parser.parse(0x90, 0x40, 0x40)
+  => #<MIDIEvents::NoteOn:0x98c9818 ...>
+```
+
+You can use nibbles in string format:
+
+```ruby
+midi_parser.parse("9", "0", "4", "0", "4", "0")
+  => #<MIDIEvents::NoteOn:0x98c9818 ...>
+```
+
+Interchange the different types:
+
+```ruby
+midi_parser.parse("9", "0", 0x40, 64)
+  => #<MIDIEvents::NoteOn:0x98c9818 ...>
+```
+
+Use running status:
+
+```ruby
+midi_parser.parse(0x40, 64)
+  => #<MIDIMEvents::NoteOn:0x98c9818 ...>
+```
+
+Add an incomplete message:
+
+```ruby
+midi_parser.parse("9")
+midi_parser.parse("40")
+```
+
+See progress:
+
+```ruby
+midi_parser.buffer
+  => ["9", "4", "0"]
+
+midi_parser.buffer_s
+  => "940"
+```
+
+MIDI Parser generates [midi-events](http://github.com/javier-sy/midi-events) objects.
+
+## Documentation
+
+* (**TO DO**) [rdoc](http://rubydoc.info/github/javier-sy/midi-parser) 
+
+## Differences between [MIDI Parser](https://github.com/javier-sy/midi-parser) and [Nibbler](https://github.com/arirusso/nibbler)
+[MIDI Parser](https://github.com/javier-sy/midi-parser) is mostly a clone of [Nibbler](https://github.com/arirusso/nibbler) with some modifications:
+* Removed logging attributes (messages, rejected, processed) to reduce parsing overhead 
+* Updated dependencies versions
+* Source updated to Ruby 2.7 code conventions (method keyword parameters instead of options = {}, hash keys as 'key:' instead of ':key =>', etc.)
+* Changed backend library midi-message to midi-events
+* Removed backend library MIDIlib
+* Renamed module to MIDIParser instead of Nibbler
+* Renamed gem to midi-parser instead of nibbler
+* Minor docs fixing 
+* TODO: update tests to use rspec instead of rake
+* TODO: migrate to (or confirm it's working ok on) Ruby 3.0 or Ruby 3.1
+
+## Then, why does exist this library if it is mostly a clone of another library?
+
+The author has been developing since 2016 a Ruby project called
+[Musa DSL](https://github.com/javier-sy/musa-dsl) that needs a way
+of representing MIDI Events and a way of communicating with
+MIDI Instruments and MIDI Control Surfaces.
+
+[Ari Russo](https://github.com/arirusso) has done a great job creating
+several interdependent Ruby libraries that allow
+MIDI Events representation ([MIDI Message](https://github.com/arirusso/midi-message)
+and [Nibbler](https://github.com/arirusso/nibbler))
+and communication with MIDI Instruments and MIDI Control Surfaces
+([unimidi](https://github.com/arirusso/unimidi),
+[ffi-coremidi](https://github.com/arirusso/ffi-coremidi) and others)
+that, **with some modifications**, I've been using in MusaDSL.
+
+After thinking about the best approach to publish MusaDSL
+I've decided to publish my own renamed version of the modified dependencies because:
+
+* Some differences on the approach of the modifications vs the original library doesn't allow to merge the modifications on the original libraries.
+* Then the renaming of the libraries is needed to avoid confusing existent users of the original libraries.
+* Due to some of the interdependencies of Ari Russo libraries,
+  the modification and renaming on some of the low level libraries (ffi-coremidi, etc.)
+  forces to modify and rename unimidi library.
+* The original libraries have features
+  (very detailed logging and processing history information, not locking behaviour when waiting input midi messages)
+  that are not needed in MusaDSL and, in fact,
+  can degrade the performance on some use case scenarios in MusaDSL.
+
+All in all I have decided to publish a suite of libraries optimized for MusaDSL use case that also can be used by other people in their projects.
+
+| Function | Library | Based on Ari Russo's| Difference |
+| --- | --- | --- | --- |
+| MIDI Events representation | [MIDI Events](https://github.com/javier-sy/midi-events) | [MIDI Message](https://github.com/arirusso/midi-message) | removed parsing, small improvements |
+| MIDI Data parsing | [MIDI Parser](https://github.com/javier-sy/midi-parser) | [Nibbler](https://github.com/arirusso/nibbler) | removed process history information, minor optimizations |
+| MIDI communication with Instruments and Control Surfaces | [MIDI Communications](https://github.com/javier-sy/midi-communications) | [unimidi](https://github.com/arirusso/unimidi) | use of [MIDI Communications MacOS Layer](https://github.com/javier-sy/midi-communications-macos)
+| Low level MIDI interface to MacOS | [MIDI Communications MacOS Layer](https://github.com/javier-sy/midi-communications-macos) | [ffi-coremidi](https://github.com/arirusso/ffi-coremidi) | removed process history information, locking behaviour when waiting midi events, improved midi devices name detection, minor optimizations |
+| Low level MIDI interface to Linux | **TO DO** | | |
+| Low level MIDI interface to JRuby | **TO DO** | | |
+| Low level MIDI interface to Windows | **TO DO** | | |
+
+## Author
+
+* [Javier Sánchez Yeste](https://github.com/javier-sy)
+
+## Acknowledgements
+
+Thanks to [Ari Russo](http://github.com/arirusso) for his ruby library [Nibbler](https://github.com/arirusso/nibbler) licensed as Apache License 2.0.
+
+## License
+
+[MIDI Parser](https://github.com/javier-sy/midi-parser) Copyright (c) 2021 [Javier Sánchez Yeste](https://yeste.studio), licensed under LGPL 3.0 License
+
+[Nibbler](https://github.com/arirusso/nibbler) Copyright (c) 2011-2015 [Ari Russo](http://arirusso.com), licensed under Apache License 2.0 (see the file LICENSE.nibbler)

data/Rakefile

@@ -0,0 +1,10 @@
+require 'rake'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+task default: [:test]

data/examples/usage.rb

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+$:.unshift(File.join('..', 'lib'))
+
+#
+# Walk through different ways to use Nibbler
+#
+
+require 'midi-parser'
+
+midi_parser = MIDIParser.new
+
+pp 'Enter a message piece by piece'
+
+pp midi_parser.parse('90')
+
+pp midi_parser.parse('40')
+
+pp midi_parser.parse('40')
+
+pp 'Enter a message all at once'
+
+pp midi_parser.parse('904040')
+
+pp 'Use Bytes'
+
+pp midi_parser.parse(0x90, 0x40, 0x40) # this should return a message
+
+pp 'Use nibbles in string format'
+
+pp midi_parser.parse('9', '0', 0x40, 0x40) # this should return a message
+
+pp 'Interchange the different types'
+
+pp midi_parser.parse('9', '0', 0x40, 64)
+
+pp 'Use running status'
+
+pp midi_parser.parse(0x40, 64)
+
+pp 'Add an incomplete message'
+
+pp midi_parser.parse('9')
+pp midi_parser.parse('40')
+
+pp 'See progress'
+
+pp midi_parser.buffer # should give you an array of bits
+
+pp midi_parser.buffer_s # should give you an array of bytestrs
+
+pp 'Pass in a timestamp'
+
+# note:
+# once you pass in a timestamp for the first time, midi-parser.messages will then return
+# an array of message/timestamp hashes
+# if there was no timestamp for a particular message it will be nil
+#
+
+pp midi_parser.parse('904040', timestamp: Time.now.to_i)
+
+pp 'Add callbacks'
+
+# you can list any properties of the message to check against.
+# if they are all true, the callback will fire
+#
+# if you wish to use "or" or any more advanced matching I would just process the message after it"s
+# returned
+#
+midi_parser.when({ class: MIDIMessage::NoteOn }) { |msg| puts 'bark' }
+pp midi_parser.parse('904040')
+pp midi_parser.parse('804040')

data/lib/midi-parser/data_processor.rb

@@ -0,0 +1,49 @@
+module MIDIParser
+  # Accepts various types of input and returns an array of hex digit chars
+  #
+  # Ideally this would output Integer objects. However, given that Ruby numerics 0x0 and 0x00 result in the same
+  # object (0 Integer), this would limit the parser to only working with bytes instead of both nibbles and bytes.
+  #
+  # For example, if the input were "5" then the processor would return an ambiguous 0x5
+  #
+  module DataProcessor
+    extend self
+
+    # Accepts various types of input and returns an array of hex digit chars
+    # Invalid input is disregarded
+    #
+    # @param [*String, *Integer] 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<Integer>, Array<String>, Integer, 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 Integer 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 [Integer] num
+    # @return [Integer, 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/midi-parser/message_builder.rb

@@ -0,0 +1,79 @@
+module MIDIParser
+  class MessageBuilder
+    CHANNEL_MESSAGE = [
+      {
+        status: 0x8,
+        class: MIDIEvents::NoteOff,
+        nibbles: 6
+      },
+      {
+        status: 0x9,
+        class: MIDIEvents::NoteOn,
+        nibbles: 6
+      },
+      {
+        status: 0xA,
+        class: MIDIEvents::PolyphonicAftertouch,
+        nibbles: 6
+      },
+      {
+        status: 0xB,
+        class: MIDIEvents::ControlChange,
+        nibbles: 6
+      },
+      {
+        status: 0xC,
+        class: MIDIEvents::ProgramChange,
+        nibbles: 4
+      },
+      {
+        status: 0xD,
+        class: MIDIEvents::ChannelAftertouch,
+        nibbles: 4
+      },
+      {
+        status: 0xE,
+        class: MIDIEvents::PitchBend,
+        nibbles: 6
+      }
+    ].freeze
+
+    SYSTEM_MESSAGE = [
+      {
+        status: 0x1..0x6,
+        class: MIDIEvents::SystemCommon,
+        nibbles: 6
+      },
+      {
+        status: 0x8..0xF,
+        class: MIDIEvents::SystemRealtime,
+        nibbles: 2
+      }
+    ].freeze
+
+    attr_reader :num_nibbles, :name, :clazz
+
+    def self.build_system_exclusive(*message_data)
+      MIDIEvents::SystemExclusive.new(*message_data)
+    end
+
+    def self.for_system_message(status)
+      type = SYSTEM_MESSAGE.find { |type| type[:status].cover?(status) }
+      new(type[:nibbles], type[:class])
+    end
+
+    def self.for_channel_message(status)
+      type = CHANNEL_MESSAGE.find { |type| type[:status] == status }
+      new(type[:nibbles], type[:class])
+    end
+
+    def initialize(num_nibbles, clazz)
+      @num_nibbles = num_nibbles
+      @clazz = clazz
+    end
+
+    def build(*message_data)
+      @clazz.new(*message_data)
+    end
+  end
+end

data/lib/midi-parser/parser.rb

@@ -0,0 +1,154 @@
+module MIDIParser
+  class Parser
+    attr_reader :buffer
+
+    def initialize
+      @running_status = RunningStatus.new
+      @buffer = []
+    end
+
+    # Process the given nibbles and add them to the buffer
+    # @param [Array<String, Integer>] nibbles
+    # @return [Array<MIDIEvent>]
+    def process(nibbles)
+      messages = []
+      pointer = 0
+      @buffer += nibbles
+      # Iterate through nibbles in the buffer until a status message is found
+      while pointer <= (@buffer.length - 1)
+        # fragment is the piece of the buffer to look at
+        fragment = get_fragment(pointer)
+        # See if there really is a message there
+        unless (processed = nibbles_to_message(fragment)).nil?
+          # if fragment contains a real message, reject the nibbles that precede it
+          @buffer = fragment.dup # fragment now has the remaining nibbles for next pass
+          fragment = nil # Reset fragment
+          pointer = 0 # Reset iterator
+          messages << processed[:message]
+        else
+          @running_status.cancel
+          pointer += 1
+        end
+      end
+      messages
+    end
+
+    # If possible, convert the given fragment to a MIDI message
+    # @param [Array<String>] fragment A fragment of data eg ["9", "0", "4", "0", "5", "0"]
+    # @return [Hash, nil]
+    def nibbles_to_message(fragment)
+      if fragment.length >= 2
+        # convert the part of the fragment to start with to a numeric
+        slice = fragment.slice(0..1).map(&:hex)
+        compute_message(slice, fragment)
+      end
+    end
+
+    private
+
+    # Attempt to convert the given nibbles into a MIDI message
+    # @param [Array<Integer>] nibbles
+    # @return [Hash, nil]
+    def compute_message(nibbles, fragment)
+      case nibbles[0]
+      when 0x8..0xE then lookahead(fragment, MessageBuilder.for_channel_message(nibbles[0]))
+      when 0xF
+        case nibbles[1]
+        when 0x0 then lookahead_for_sysex(fragment)
+        else lookahead(fragment, MessageBuilder.for_system_message(nibbles[1]), recursive: true)
+        end
+      else
+        lookahead_using_running_status(fragment) if @running_status.possible?
+      end
+    end
+
+    # Attempt to convert the fragment to a MIDI message using the given fragment and cached running status
+    # @param [Array<String>] fragment A fragment of data eg ["4", "0", "5", "0"]
+    # @return [Hash, nil]
+    def lookahead_using_running_status(fragment)
+      lookahead(fragment, @running_status[:message_builder], offset: @running_status[:offset], status_nibble_2: @running_status[:status_nibble_2])
+    end
+
+    # Get the data in the buffer for the given pointer
+    # @param [Integer] pointer
+    # @return [Array<String>]
+    def get_fragment(pointer)
+      @buffer[pointer, (@buffer.length - pointer)]
+    end
+
+    # If the given fragment has at least the given number of nibbles, use it to build a hash that can be used
+    # to build a MIDI message
+    #
+    # @param [Integer] num_nibbles
+    # @param [Array<String>] fragment
+    # @param [Hash] options
+    # @option options [String] :status_nibble_2
+    # @option options [Boolean] :recursive
+    # @return [Hash, nil]
+    def lookahead(fragment, message_builder, options = {})
+      offset = options.fetch(:offset, 0)
+      num_nibbles = message_builder.num_nibbles + offset
+      if fragment.size >= num_nibbles
+        # if so shift those nibbles off of the array and call block with them
+        nibbles = fragment.slice!(0, num_nibbles)
+        status_nibble_2 ||= options[:status_nibble_2] || nibbles[1]
+
+        # send the nibbles to the block as bytes
+        # return the evaluated block and the remaining nibbles
+        bytes = TypeConversion.hex_chars_to_numeric_bytes(nibbles)
+        bytes = bytes[1..-1] if options[:status_nibble_2].nil?
+
+        # record the fragment situation in case running status comes up next round
+        @running_status.set(offset - 2, message_builder, status_nibble_2)
+
+        message_args = [status_nibble_2.hex]
+        message_args += bytes if num_nibbles > 2
+
+        message = message_builder.build(*message_args)
+        {
+          message: message,
+          processed: nibbles
+        }
+      elsif num_nibbles > 0 && !!options[:recursive]
+        lookahead(fragment, message_builder, options.merge({ offset: offset - 2 }))
+      end
+    end
+
+    def lookahead_for_sysex(fragment)
+      @running_status.cancel
+      bytes = TypeConversion.hex_chars_to_numeric_bytes(fragment)
+      unless (index = bytes.index(0xF7)).nil?
+        message_data = bytes.slice!(0, index + 1)
+        message = MessageBuilder.build_system_exclusive(*message_data)
+        {
+          message: message,
+          processed: fragment.slice!(0, (index + 1) * 2)
+        }
+      end
+    end
+
+    class RunningStatus
+      extend Forwardable
+
+      def_delegators :@state, :[]
+
+      def cancel
+        @state = nil
+      end
+
+      # Is there an active cached running status?
+      # @return [Boolean]
+      def possible?
+        !@state.nil?
+      end
+
+      def set(offset, message_builder, status_nibble_2)
+        @state = {
+          message_builder: message_builder,
+          offset: offset,
+          status_nibble_2: status_nibble_2
+        }
+      end
+    end
+  end
+end

data/lib/midi-parser/session.rb

@@ -0,0 +1,38 @@
+module MIDIParser
+  # A parser session
+  #
+  # Holds on to data that is not relevant to the parser between calls. For instance,
+  # past messages, rejected bytes
+  #
+  class Session
+    def initialize
+      @parser = Parser.new
+    end
+
+    # The buffer
+    # @return [Array<Object>]
+    def buffer
+      @parser.buffer
+    end
+
+    # The buffer as a single hex string
+    # @return [String]
+    def buffer_s
+      @parser.buffer.join
+    end
+    alias buffer_hex buffer_s
+
+    # Clear the parser buffer
+    def clear_buffer
+      @parser.buffer.clear
+    end
+
+    # Parse some input
+    # @param [*Object] args
+    # @return [Array<MIDIEvent>]
+    def parse(*args)
+      queue = DataProcessor.process(args)
+      @parser.process(queue)
+    end
+  end
+end

data/lib/midi-parser/type_conversion.rb

@@ -0,0 +1,72 @@
+module MIDIParser
+  # A helper for converting between different types of nibbles and bytes
+  module TypeConversion
+    extend self
+
+    # Converts an array of hex nibble strings to numeric bytes
+    # eg ["9", "0", "5", "0", "4", "0"] => [0x90, 0x50, 0x40]
+    # @param [Array<String>] nibbles
+    # @return [Array<Integer>]
+    def hex_chars_to_numeric_bytes(nibbles)
+      nibbles = nibbles.dup
+      # get rid of last nibble if there's an odd number
+      # it will be processed later anyway
+      nibbles.slice!(nibbles.length - 2, 1) if nibbles.length.odd?
+      bytes = []
+      until (nibs = nibbles.slice!(0, 2)).empty?
+        byte = (nibs[0].hex << 4) + nibs[1].hex
+        bytes << byte
+      end
+      bytes
+    end
+
+    # Converts a string of hex digits to string nibbles
+    # eg "905040" => ["9", "0", "5", "0", "4", "0"]
+    # @param [String] string
+    # @return [Array<String>]
+    def hex_str_to_hex_chars(string)
+      string.split(//)
+    end
+
+    # Converts a string of hex digits to numeric nibbles
+    # eg "905040" => [0x9, 0x0, 0x5, 0x0, 0x4, 0x0]
+    # @param [String] string
+    # @return [Array<String>]
+    def hex_str_to_numeric_nibbles(string)
+      bytes = hex_str_to_numeric_bytes(string)
+      numeric_bytes_to_numeric_nibbles(bytes)
+    end
+
+    # Converts a string of hex digits to numeric bytes
+    # eg "905040" => [0x90, 0x50, 0x40]
+    # @param [String] string
+    # @return [Array<String>]
+    def hex_str_to_numeric_bytes(string)
+      chars = hex_str_to_hex_chars(string)
+      hex_chars_to_numeric_bytes(chars)
+    end
+
+    # Converts an array bytes to an array of nibbles
+    # eg [0x90, 0x50, 0x40] => [0x9, 0x0, 0x5, 0x0, 0x4, 0x0]
+    # @param [Array<Integer>] bytes
+    # @return [Array<String>]
+    def numeric_bytes_to_numeric_nibbles(bytes)
+      bytes.map { |byte| numeric_byte_to_numeric_nibbles(byte) }.flatten
+    end
+
+    # Converts a numeric byte to an array of hex nibble strings eg 0x90 => ["9", "0"]
+    # @param [Integer] num
+    # @return [Array<String>]
+    def numeric_byte_to_hex_chars(num)
+      nibbles = numeric_byte_to_numeric_nibbles(num)
+      nibbles.map { |n| n.to_s(16) }
+    end
+
+    # Converts a numeric byte to an array of numeric nibbles eg 0x90 => [0x9, 0x0]
+    # @param [Integer] num
+    # @return [Array<String>]
+    def numeric_byte_to_numeric_nibbles(num)
+      [((num & 0xF0) >> 4), (num & 0x0F)]
+    end
+  end
+end