midi-message 0.2.2

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2010-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,100 @@
+= MIDI Message
+
+{pic}[http://images.treetrouble.net/images/mks80_small.jpg]
+
+MIDI messages, objectified in Ruby
+
+== Features
+
+* Flexible API to accommodate various sources and destinations of MIDI data
+* Simple OO approach to System Exclusive data and devices
+* {YAML dictionary of MIDI constants}[https://github.com/arirusso/midi-message/blob/master/lib/midi.yml]
+	
+== Install
+
+  gem install midi-message
+
+== Usage
+
+  require 'midi-message'
+  
+  include MIDIMessage
+  
+==== Basic Messages
+
+There are a few ways to create a new MIDI message.  Here are some examples
+    
+  NoteOn.new(0, 64, 64)
+  
+  NoteOn["E4"].new(0, 100)
+  
+  with(:channel => 0, :velocity => 100) { note_on("E4") }
+
+Those expressions all evaluate to the same object
+
+  #<MIDIMessage::NoteOn:0x9c1c240
+   @channel=0,
+   @data=[64, 64],
+   @name="E4",
+   @note=64,
+   @status=[9, 0],
+   @velocity=64,
+   @verbose_name="Note On: E4">
+
+==== SysEx Messages
+
+As with any kind of message, you can begin with raw data
+  
+  SystemExclusive.new(0xF0, 0x41, 0x10, 0x42, 0x12, 0x40, 0x00, 0x7F, 0x00, 0x41, 0xF7)
+  
+Or in a more object oriented way
+  
+  synth = SystemExclusive::Node.new(0x41, :model_id => 0x42, :device_id => 0x10)
+    
+  SystemExclusive::Command.new([0x40, 0x7F, 0x00], 0x00, :node => synth)
+  
+A Node represents a device that you're sending a message to (eg. your Yamaha DX7 is a Node).  Sysex messages can either be a Command or Request
+  
+You can use the Node to instantiate a message
+  
+  synth.command([0x40, 0x7F, 0x00], 0x00)
+  
+One way or another, you will wind up with a pair of objects like this
+
+   #<MIDIMessage::SystemExclusive::Command:0x9c1e57c
+   @address=[64, 0, 127],
+   @checksum=[65],
+   @data=[0],
+   @node=
+    #<MIDIMessage::SystemExclusive::Node:0x9c1e5a4
+     @device_id=16,
+     @manufacturer_id=65,
+     @model_id=66>>
+     
+==== Parsing
+
+The parse method will take any valid message data and return the object representation
+
+  MIDIMessage.parse(0x90, 0x40, 0x40)
+  
+    #<MIDIMessage::NoteOn:0x9c1c240 ..>
+  
+  MIDIMessage.parse(0xF0, 0x41, 0x10, 0x42, 0x12, 0x40, 0x00, 0x7F, 0x00, 0x41, 0xF7)
+  
+    #<MIDIMessage::SystemExclusive::Command:0x9c1e57c ..>
+  
+Check out {nibbler}[http://github.com/arirusso/nibbler] for more advanced parsing
+
+== API Documentation
+
+* {rdoc}[http://rubydoc.info/github/arirusso/midi-message]
+
+== 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-message/channel_message.rb

@@ -0,0 +1,179 @@
+#!/usr/bin/env ruby
+#
+module MIDIMessage
+
+  # common behavior amongst Channel Message types
+  module ChannelMessage
+
+    attr_reader :data,
+                :name
+                
+    def self.new(*a, &block)
+      RawChannelMessage.new(*a, &block)
+    end
+                  
+    def initialize(*a)
+      options = a.last.kind_of?(Hash) ? a.pop : {}
+      @const = options[:const]        
+      unless @const.nil?
+        key = self.class.map_constants_to
+        ind = self.class.properties.index(key)
+        ind ||= 0
+        a.insert(ind, @const.value)               
+      end
+      initialize_channel_message(self.class.type_for_status, *a)
+    end
+    
+    def initialize_properties
+      props = [
+        { :name => :status, :index => 1 },
+        { :name => :data, :index => 0 },
+        { :name => :data, :index => 1 }
+      ]
+      properties = self.class.properties
+      unless properties.nil? 
+        properties.each_with_index do |prop,i|
+          self.class.send(:attr_reader, prop)
+          self.class.send(:define_method, "#{prop}=") do |val|
+            send(:instance_variable_set, "@#{prop.to_s}", val)
+            send(props[i][:name])[props[i][:index]] = val
+            update
+            return self
+          end
+          instance_variable_set("@#{prop}", send(props[i][:name])[props[i][:index]])
+        end
+      end
+    end
+    
+    protected
+    
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    private
+    
+    def initialize_channel_message(status_nibble_1, status_nibble_2, data_byte_1, data_byte_2 = 0)
+      @status = [status_nibble_1, status_nibble_2]
+      @data = [data_byte_1]
+      @data[1] = data_byte_2 if self.class.second_data_byte?
+      initialize_properties
+      initialize_short_message(status_nibble_1, status_nibble_2)
+    end
+    
+    module ClassMethods
+      
+      attr_reader :properties
+            
+      def type_for_status
+        @display_name.nil? ? nil : Status[@display_name] 
+      end
+
+      def schema(*args)
+        @properties = args
+      end
+      alias_method :layout, :schema
+
+      def second_data_byte?
+        @properties.nil? || (@properties.length-1) > 1
+      end
+
+    end
+        
+  end
+
+  # use this if you want to instantiate a raw channel message
+  #
+  # example = ChannelMessage.new(0x9, 0x0, 0x40, 0x57) # creates a raw note-on message
+  #
+  class RawChannelMessage
+
+    include ShortMessage
+    include ChannelMessage
+
+    use_display_name 'Channel Message'
+    
+    def initialize(*a)
+      initialize_channel_message(*a)
+    end        
+    
+    def to_type
+      status = (@status[0] << 4) + (@status[1])
+      MIDIMessage.parse(status, *@data)
+    end
+
+  end
+
+  #
+  # MIDI Channel Aftertouch message
+  #
+  class ChannelAftertouch
+
+    include ShortMessage
+    include ChannelMessage
+
+    schema :channel, :value
+    use_display_name 'Channel Aftertouch'
+
+  end
+  ChannelPressure = ChannelAftertouch
+
+  #
+  # MIDI Control Change message
+  #
+  class ControlChange
+
+    include ShortMessage
+    include ChannelMessage
+
+    schema :channel, :index, :value
+    use_display_name 'Control Change'
+    use_constants 'Control Change', :for => :index
+   
+  end  
+  Controller = ControlChange #shortcut
+
+  #
+  # MIDI Pitch Bend message
+  #
+  class PitchBend
+
+    include ShortMessage
+    include ChannelMessage
+
+    schema :channel, :low, :high
+    use_display_name 'Pitch Bend'
+
+  end
+
+  #
+  # MIDI Polyphonic (note specific) Aftertouch message
+  #
+  class PolyphonicAftertouch
+
+    include ShortMessage
+    include ChannelMessage
+
+    schema :channel, :note, :value
+    use_display_name 'Polyphonic Aftertouch'
+    use_constants 'Note', :for => :note
+
+  end
+  PolyAftertouch = PolyphonicAftertouch
+  PolyPressure = PolyphonicAftertouch
+  PolyphonicPressure = PolyphonicAftertouch
+
+  #
+  # MIDI Program Change message
+  #
+  class ProgramChange
+
+    include ShortMessage
+    include ChannelMessage
+
+    schema :channel, :program
+    use_display_name 'Program Change'
+
+  end
+  
+end

data/lib/midi-message/constant.rb

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+#
+
+module MIDIMessage
+
+  # MIDI Constants
+  class ConstantGroup
+    
+    attr_reader :key, :value
+    
+    def initialize(key, constants)
+      @key = key
+      @constants = constants.map { |k, v| Constant.new(k, v) }
+    end
+    
+    def find(name)
+      @constants.find { |const| const.key.to_s.downcase.eql?(name.to_s.downcase) }       
+    end
+    alias_method :[], :find
+    
+    def find_by_value(value)
+      @constants.find { |const| const.value.to_s.downcase.eql?(value.to_s.downcase) }
+    end
+    
+    def self.all
+      ensure_initialized
+      @groups
+    end
+
+    def self.[](key)      
+      ensure_initialized
+      @groups.find { |g| g.key.to_s.downcase.eql?(key.to_s.downcase) }
+    end
+    
+    private
+    
+    # lazy initialize
+    def self.ensure_initialized
+      @dict ||= YAML.load_file(File.expand_path('../../midi.yml', __FILE__))
+      @groups ||= @dict.map { |k, v| new(k, v) }
+    end
+
+  end
+  
+  class Constant
+    
+    attr_reader :key, :value
+    
+    def initialize(key, value)
+      @key = key
+      @value = value      
+    end
+    
+    def self.find(group_name, const_name)
+      group = ConstantGroup[group_name]
+      group.find(const_name)      
+    end
+    
+  end
+
+end

data/lib/midi-message/context.rb

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+#
+#
+
+module MIDIMessage
+
+  class Context
+    
+    attr_accessor :channel,
+                  :velocity
+    
+    def initialize(options = {})
+      @channel = options[:channel]
+      @velocity = options[:velocity]  
+    end
+
+    def note_off(note, options = {})
+      channel = options[:channel] || @channel
+      velocity = options[:velocity] || @velocity
+      raise 'note_off requires both channel and velocity' if channel.nil? || velocity.nil?
+      if note.kind_of?(String)
+        NoteOff[note].new(channel, velocity, options)
+      else
+        NoteOff.new(channel, note, velocity, options)
+      end
+    end
+    alias_method :NoteOff, :note_off
+    
+    def note_on(note, options = {})
+      channel = options[:channel] || @channel
+      velocity = options[:velocity] || @velocity
+      raise 'note_on requires both channel and velocity' if channel.nil? || velocity.nil?
+      if note.kind_of?(String)
+        NoteOn[note].new(channel, velocity, options)
+      else
+        NoteOn.new(channel, note, velocity, options)
+      end
+    end
+    alias_method :NoteOn, :note_on
+    
+    def program_change(program, options = {})
+      channel = options[:channel] || @channel
+      raise 'program_change requires channel' if channel.nil?
+      if program.kind_of?(String)
+        ProgramChange[program].new(channel, options)
+      else
+        ProgramChange.new(channel, program, options)
+      end    
+    end
+    alias_method :ProgramChange, :program_change
+    
+    def control_change(index, value, options = {})
+      channel = options[:channel] || @channel
+      raise 'control_change requires channel' if channel.nil?
+      if index.kind_of?(String)
+        ControlChange[index].new(channel, value, options)
+      else
+        ControlChange.new(channel, index, value, options)
+      end    
+    end
+    alias_method :ControlChange, :control_change
+    alias_method :Controller, :control_change
+    alias_method :controller, :control_change
+    
+    def polyphonic_aftertouch(note, value, options = {})
+      channel = options[:channel] || @channel
+      raise 'channel_aftertouch requires a channel' if channel.nil?
+      if note.kind_of?(String)
+        PolyphonicAftertouch[note].new(channel, value, options)
+      else
+        PolyphonicAftertouch.new(channel, note, value, options)
+      end    
+    end
+    alias_method :PolyphonicAftertouch, :polyphonic_aftertouch
+    alias_method :PolyAftertouch, :polyphonic_aftertouch    
+    alias_method :PolyphonicPressure, :polyphonic_aftertouch
+    alias_method :PolyPressure, :polyphonic_aftertouch    
+    alias_method :poly_aftertouch, :polyphonic_aftertouch
+    alias_method :poly_pressure, :polyphonic_aftertouch
+        
+    def channel_aftertouch(value, options = {})
+      channel = options[:channel] || @channel
+      raise 'channel_aftertouch requires a channel' if channel.nil?
+      ChannelAftertouch.new(channel, value, options)    
+    end
+    alias_method :ChannelAftertouch, :channel_aftertouch
+    alias_method :ChannelPressure, :channel_aftertouch    
+    alias_method :channel_pressure, :channel_aftertouch
+    
+    def pitch_bend(low, high, options = {})
+      channel = options[:channel] || @channel
+      raise 'channel_aftertouch requires a channel' if channel.nil?
+      PitchBend.new(channel, low, high, options)    
+    end
+    alias_method :PitchBend, :pitch_bend
+    
+  end
+  
+  def with_context(options = {}, &block)
+    Context.new(options, &block).instance_eval(&block)
+  end
+  alias_method :with, :with_context
+
+end

data/lib/midi-message/note_message.rb

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+#
+module MIDIMessage
+
+  #
+  # Common Note Message Behavior
+  #
+  module NoteMessage
+
+    # the octave number of the note
+    def octave
+      (note / 12) -1
+    end
+    alias_method :oct, :octave
+    
+    # set the octave number of the note
+    def octave=(val)
+      self.note = ((val + 1) * 12) + abs_note
+      self
+    end
+    alias_method :oct=, :octave=
+    
+    # how many half-steps is this note above the closest C
+    def abs_note
+      note - ((note / 12) * 12)
+    end
+    
+    # the name of the note without its octave e.g. F#
+    def note_name
+      name.split(/-?\d\z/).first
+    end
+        
+  end
+
+  #
+  # MIDI Note-Off message
+  #
+  class NoteOff
+
+    include NoteMessage
+    include ShortMessage
+    include ChannelMessage
+
+    schema :channel, :note, :velocity
+    use_display_name 'Note Off'
+    use_constants 'Note', :for => :note
+
+  end
+
+  #
+  # MIDI Note-On message
+  #
+  class NoteOn
+    
+    include NoteMessage
+    include ShortMessage
+    include ChannelMessage    
+
+    schema :channel, :note, :velocity
+    use_display_name 'Note On'
+    use_constants 'Note', :for => :note
+    
+    # returns the NoteOff equivalent of this object
+    def to_note_off
+      NoteOff.new(channel, note, velocity)
+    end
+
+  end
+  
+end

data/lib/midi-message/parser.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+#
+
+module MIDIMessage
+
+    # very simple parsing
+    # for more advanced parsing check out {nibbler}[http://github.com/arirusso/nibbler]
+    class Parser
+      
+      # can take either a hex string eg Parser.new("904040")
+      # or bytes eg Parser.new(0x90, 0x40, 0x40)
+      # or an array of bytes eg Parser.new([0x90, 0x40, 0x40])
+      def initialize(*a)
+        @data = case a.first
+          when Array then a.first
+          when Numeric then a 
+          when String then TypeConversion.hex_string_to_numeric_byte_array(a.first)
+        end
+      end
+      
+      def parse
+        first_nibble = ((@data.first & 0xF0) >> 4)
+        second_nibble = (@data.first & 0x0F)
+        case first_nibble
+          when 0x8 then NoteOff.new(second_nibble, @data[1], @data[2])
+          when 0x9 then NoteOn.new(second_nibble, @data[1], @data[2])
+          when 0xA then PolyphonicAftertouch.new(second_nibble, @data[1], @data[2])
+          when 0xB then ControlChange.new(second_nibble, @data[1], @data[2])
+          when 0xC then ProgramChange.new(second_nibble, @data[1])
+          when 0xD then ChannelAftertouch.new(second_nibble, @data[1])
+          when 0xE then PitchBend.new(second_nibble, @data[1], @data[2])
+          when 0xF then case second_nibble
+            when 0x0 then SystemExclusive.new(*@data)
+            when 0x1..0x6 then SystemCommon.new(second_nibble, @data[1], @data[2])
+            when 0x8..0xF then SystemRealtime.new(second_nibble)
+            else nil
+          end
+          else nil
+        end
+      end
+    
+    end
+    
+    def self.parse(*a)
+      Parser.new(*a).parse
+    end
+
+end

data/lib/midi-message/process/filter.rb

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+
+module MIDIMessage
+
+  module Process
+
+    # Use the Filter superclass when you need a multi-band filter
+    class Filter
+
+      include Processor
+
+      attr_reader :bandwidth, :property, :reject
+      
+      def initialize(message, prop, bandwidth, options = {})
+        @bandwidth = [bandwidth].flatten
+        @message = message
+        @property = prop
+        @reject = options[:reject] || false
+        initialize_processor(message)
+      end
+
+      def process
+        val = @message.send(@property)
+        result = @bandwidth.map { |bw| val >= bw.min && val <= bw.max ? @message : nil }
+        result.include?(@message) ^ @reject ? @message : nil
+      end
+
+    end
+
+    class LowPassFilter < Filter
+      def initialize(message, prop, max, options = {})
+        super(message, prop, (0..max), options)
+      end
+    end
+
+    class HighPassFilter < Filter
+      def initialize(message, prop, min, options = {})
+        super(message, prop, (min..127), options)
+      end
+    end
+
+    class BandPassFilter < Filter
+      def initialize(message, prop, accept_range, options = {})
+        options[:reject] = false
+        super(message, prop, accept_range, options)
+      end
+    end
+
+    class BandRejectFilter < Filter
+      def initialize(message, prop, reject_range, options = {})
+        options[:reject] = true
+        super(message, prop, reject_range, options)
+      end
+    end
+    NotchFilter = BandRejectFilter
+
+  end
+end

data/lib/midi-message/process/limit.rb

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+
+module MIDIMessage
+
+  module Process
+    
+    class Limit
+
+      include Processor
+
+      attr_reader :property, :range
+      
+      def initialize(message, prop, range, options = {})
+        @range = range
+        @message = message
+        @property = prop
+        initialize_processor(message)
+      end
+
+      def process
+        val = @message.send(@property)
+        @message.send("#{@property}=", @range.min) if val < @range.min
+        @message.send("#{@property}=", @range.max) if val > @range.max
+        @message
+      end
+
+    end
+
+  end
+  
+end

data/lib/midi-message/process/processor.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+module MIDIMessage
+
+  module Process
+
+    module Processor
+      
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.send(:attr_reader, :message)
+      end
+
+      module ClassMethods
+        def process(*a, &block)
+          new(*a).process(&block)
+        end
+      end
+
+      private
+
+      def initialize_processor(message)
+        @message = message
+      end
+
+    end
+
+  end
+  
+end