midi-events 0.5.0

data/lib/midi-events/constant.rb

@@ -0,0 +1,260 @@
+module MIDIEvents
+
+  # Refer to a MIDI message by its usage
+  # eg *C4* for MIDI note *60* or *Bank Select* for MIDI control change *0*
+  module Constant
+
+    # Get a Mapping object for the specified constant
+    # @param [Symbol, String] group_name
+    # @param [String] const_name
+    # @return [MIDIEvents::Constant::Map, nil]
+    def self.find(group_name, const_name)
+      group = Group[group_name]
+      group.find(const_name)
+    end
+
+    # Get the value of the specified constant
+    # @param [Symbol, String] group_name
+    # @param [String] const_name
+    # @return [Object]
+    def self.value(group_name, const_name)
+      map = find(group_name, const_name)
+      map.value
+    end
+
+    module Name
+
+      extend self
+
+      # eg "Control Change" -> "control_change"
+      # @param [Symbol, String] string
+      # @return [String]
+      def underscore(string)
+        string.to_s.downcase.gsub(/(\ )+/, "_")
+      end
+
+      # @param [Symbol, String] key
+      # @param [Symbol, String] other
+      # @return [Boolean]
+      def match?(key, other)
+        match_key = key.to_s.downcase
+        [match_key, Name.underscore(match_key)].include?(other.to_s.downcase)
+      end
+
+    end
+
+    # MIDI Constant container
+    class Group
+
+      attr_reader :constants, :key
+
+      # @param [String] key
+      # @param [Hash] constants
+      def initialize(key, constants)
+        @key = key
+        @constants = constants.map { |k, v| Constant::Map.new(k, v) }
+      end
+
+      # Find a constant by its name
+      # @param [String, Symbol] name
+      # @return [Constant::Map]
+      def find(name)
+        @constants.find { |const| Name.match?(const.key, name) }
+      end
+
+      # Find a constant by its value
+      # @param [Object] value
+      # @return [Constant::Map]
+      def find_by_value(value)
+        @constants.find { |const| Name.match?(const.value, value) }
+      end
+
+      class << self
+
+        # All constant groups
+        # @return [Array<ConstantGroup>]
+        def all
+          ensure_initialized
+          @groups
+        end
+
+        # Find a constant group by its key
+        # @param [String, Symbol] key
+        # @return [ConstantGroup]
+        def find(key)
+          ensure_initialized
+          @groups.find { |group| Name.match?(group.key, key) }
+        end
+        alias_method :[], :find
+
+        private
+
+        # Lazy initialize
+        # @return [Boolean]
+        def ensure_initialized
+          populate_dictionary | populate_groups
+        end
+
+        # Populate the dictionary of constants
+        # @return [Boolean]
+        def populate_dictionary
+          if @dict.nil?
+            file = File.expand_path('../../midi.yml', __FILE__)
+            @dict = YAML.load_file(file)
+            @dict.freeze
+            true
+          end
+        end
+
+        # Populate the constant groups using the dictionary
+        # @return [Boolean]
+        def populate_groups
+          if @groups.nil? && !@dict.nil?
+            @groups = @dict.map { |k, v| new(k, v) }
+            true
+          end
+        end
+
+      end
+
+    end
+
+    # The mapping of a constant key to its value eg "Note On" => 0x9
+    class Map
+
+      attr_reader :key, :value
+
+      # @param [String] key
+      # @param [Object] value
+      def initialize(key, value)
+        @key = key
+        @value = value
+      end
+
+    end
+
+    class MessageBuilder
+
+      # @param [MIDIEvents] klass The message class to build
+      # @param [MIDIEvents::Constant::Map] const The constant to build the message with
+      def initialize(klass, const)
+        @klass = klass
+        @const = const
+      end
+
+      # @param [*Object] args
+      # @return [Message]
+      def new(*args)
+        args = args.dup
+        args.last.kind_of?(Hash) ? args.last[:const] = @const : args.push(:const => @const)
+        @klass.new(*args)
+      end
+
+    end
+
+    # Shortcuts for dealing with message status
+    module Status
+
+      extend self
+
+      # The value of the Status constant with the name status_name
+      # @param [String] status_name The key to use to look up a constant value
+      # @return [String] The constant value that was looked up
+      def find(status_name)
+        const = Constant.find("Status", status_name)
+        const.value unless const.nil?
+      end
+      alias_method :[], :find
+
+    end
+
+    # Loading constants from the spec file into messages
+    module Loader
+
+      extend self
+
+      # Get the index of the constant from the given message's type
+      # @param [Message] message
+      # @return [Fixnum]
+      def get_index(message)
+        key = message.class.constant_property
+        message.class.properties.index(key) || 0
+      end
+
+      # Used to populate message metadata with information gathered from midi.yml
+      # @param [Message] message
+      # @return [Hash, nil]
+      def get_info(message)
+        const_group_name = message.class.display_name
+        group_name_alias = message.class.constant_name
+        property = message.class.constant_property
+        value = message.send(property) unless property.nil?
+        value ||= message.status[1] # default property to use for constants
+        group = Constant::Group[group_name_alias] || Constant::Group[const_group_name]
+        unless group.nil?
+          unless (const = group.find_by_value(value)).nil?
+            {
+              :const => const,
+              :name => const.key,
+              :verbose_name => "#{message.class.display_name}: #{const.key}"
+            }
+          end
+        end
+      end
+
+      # DSL type class methods for loading constants into messages
+      module DSL
+
+        # Find a constant value in this class's group for the passed in key
+        # @param [String] name The constant key
+        # @return [String] The constant value
+        def get_constant(name)
+          key = constant_name || display_name
+          unless key.nil?
+            group = Group[key]
+            group.find(name)
+          end
+        end
+
+        # @return [String]
+        def display_name
+          const_get("DISPLAY_NAME") if const_defined?("DISPLAY_NAME")
+        end
+
+        # @return [Hash]
+        def constant_map
+          const_get("CONSTANT") if const_defined?("CONSTANT")
+        end
+
+        # @return [String]
+        def constant_name
+          constant_map.keys.first unless constant_map.nil?
+        end
+
+        # @return [Symbol]
+        def constant_property
+          constant_map[constant_name] unless constant_map.nil?
+        end
+
+        # Get the status nibble for this particular message type
+        # @return [Fixnum] The status nibble
+        def type_for_status
+          Constant::Status[display_name]
+        end
+
+        # This returns a MessageBuilder for the class, preloaded with the selected const
+        # @param [String, Symbol] const_name The constant key to use to build the message
+        # @return [MIDIEvents::MessageBuilder] A MessageBuilder object for the passed in constant
+        def find(const_name)
+          const = get_constant(const_name.to_s)
+          MessageBuilder.new(self, const) unless const.nil?
+        end
+        alias_method :[], :find
+
+      end
+
+    end
+
+  end
+
+end

data/lib/midi-events/context.rb

@@ -0,0 +1,161 @@
+module MIDIEvents
+
+  # A DSL for instantiating message objects
+  class Context
+
+    attr_accessor :channel, :velocity
+
+    # Open a context with the given options
+    # @param [Hash] options
+    # @param [Proc] block
+    # @option options [Fixnum] :channel
+    # @option options [Fixnum] :velocity
+    def self.with(options = {}, &block)
+      new(options, &block).instance_eval(&block)
+    end
+
+    # @param [Hash] options
+    # @option options [Fixnum] :channel
+    # @option options [Fixnum] :velocity
+    def initialize(options = {})
+      @channel = options[:channel]
+      @velocity = options[:velocity]
+    end
+
+    # A note off message
+    # @param [Fixnum, String] note
+    # @param [Hash] options
+    # @option options [Fixnum] :channel
+    # @option options [Fixnum] :velocity
+    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.is_a?(String)
+        NoteOff[note].new(channel, velocity, options)
+      else
+        NoteOff.new(channel, note, velocity, options)
+      end
+    end
+    alias_method :NoteOff, :note_off
+
+    # A note on message
+    # @param [Fixnum, String] note
+    # @param [Hash] options
+    # @option options [Fixnum] :channel
+    # @option options [Fixnum] :velocity
+    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.is_a?(String)
+        NoteOn[note].new(channel, velocity, options)
+      else
+        NoteOn.new(channel, note, velocity, options)
+      end
+    end
+    alias_method :NoteOn, :note_on
+
+    # A program change message
+    # @param [Fixnum, String] program
+    # @param [Hash] options
+    # @option options [Fixnum] :channel
+    def program_change(program, options = {})
+      channel = options[:channel] || @channel
+      raise 'program_change requires channel' if channel.nil?
+
+      if program.is_a?(String)
+        ProgramChange[program].new(channel, options)
+      else
+        ProgramChange.new(channel, program, options)
+      end
+    end
+    alias_method :ProgramChange, :program_change
+
+    # A control change message
+    # @param [Fixnum, String] index
+    # @param [Fixnum] value
+    # @param [Hash] options
+    # @option options [Fixnum] :channel
+    # @option options [Fixnum] :velocity
+    def control_change(index, value, options = {})
+      channel = options[:channel] || @channel
+      raise 'control_change requires channel' if channel.nil?
+
+      if index.is_a?(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
+
+    # A poly pressure message
+    # @param [Fixnum, String] note
+    # @param [Fixnum] value
+    # @param [Hash] options
+    # @option options [Fixnum] :channel
+    def polyphonic_aftertouch(note, value, options = {})
+      channel = options[:channel] || @channel
+      raise 'channel_aftertouch requires a channel' if channel.nil?
+
+      if note.is_a?(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
+
+    # A channel pressure message
+    # @param [Fixnum] value
+    # @param [Hash] options
+    # @option options [Fixnum] :channel
+    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
+
+    # A poly pressure message
+    # @param [Fixnum] low
+    # @param [Fixnum] high
+    # @param [Hash] options
+    # @option options [Fixnum] :channel
+    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
+
+  # Shortcut to MIDIMessage::Context.with
+  # @param [Hash] options
+  # @param [Proc] block
+  # @option options [Fixnum] :channel
+  # @option options [Fixnum] :velocity
+  def self.with_context(options = {}, &block)
+    Context.with(options, &block)
+  end
+  class << self
+    alias_method :with, :with_context
+  end
+
+end

data/lib/midi-events/message.rb

@@ -0,0 +1,62 @@
+module MIDIEvents
+  # Common behavior amongst all Message types
+  module Message
+    # Initialize the message status
+    # @param [Fixnum] status_nibble_1 The first nibble of the status
+    # @param [Fixnum] status_nibble_2 The second nibble of the status
+    def initialize_message(status_nibble_1, status_nibble_2)
+      @status = [status_nibble_1, status_nibble_2]
+      populate_using_const
+    end
+
+    # Byte array representation of the message eg [0x90, 0x40, 0x40] for NoteOn(0x40, 0x40)
+    # @return [Array<Fixnum>] The array of bytes in the MIDI message
+    def to_a
+      data = [@data[0], @data[1]] unless @data.nil?
+      data ||= []
+      [status_as_byte, *data].compact
+    end
+    alias_method :to_byte_a, :to_a
+    alias_method :to_byte_array, :to_a
+    alias_method :to_bytes, :to_a
+
+    # String representation of the message's bytes eg "904040" for NoteOn(0x40, 0x40)
+    # @return [String] The bytes of the message as a string of hex bytes
+    def to_hex_s
+      TypeConversion.numeric_byte_array_to_hex_string(to_a)
+    end
+    alias_method :to_bytestr, :to_hex_s
+
+    def update
+      populate_using_const
+    end
+
+    def ==(other_message)
+      self.class == other_message.class &&
+        to_a == other_message.to_a
+    end
+
+    private
+
+    # Convert the status nibbles to a single byte
+    # Eg [0x9, 0xF] -> 0x9F
+    # @return [Fixnum]
+    def status_as_byte
+      (@status[0] << 4) + @status[1]
+    end
+
+    def populate_using_const
+      unless (info = Constant::Loader.get_info(self)).nil?
+        @const = info[:const]
+        @name = info[:name]
+        @verbose_name = info[:verbose_name]
+      end
+    end
+
+    def self.included(base)
+      base.send(:extend, Constant::Loader::DSL)
+      base.send(:include, MIDIEvents) # this enables ..kind_of?(MIDIMessage)
+      base.send(:attr_reader, :name, :status, :verbose_name)
+    end
+  end
+end

data/lib/midi-events/messages.rb

@@ -0,0 +1,215 @@
+module MIDIEvents
+  #
+  # MIDI Channel Aftertouch message
+  #
+  class ChannelAftertouch
+    include ChannelMessage
+
+    STATUS = 0xD
+    DATA = [:channel, :value].freeze
+    DISPLAY_NAME = 'Channel Aftertouch'.freeze
+
+    ChannelMessage::Accessors.decorate(self)
+  end
+  ChannelPressure = ChannelAftertouch
+
+  #
+  # MIDI Control Change message
+  #
+  class ControlChange
+    include ChannelMessage
+
+    STATUS = 0xB
+    DATA = [:channel, :index, :value].freeze
+    DISPLAY_NAME = 'Control Change'.freeze
+    CONSTANT = { 'Control Change' => :index }.freeze
+
+    ChannelMessage::Accessors.decorate(self)
+  end
+  Controller = ControlChange #shortcut
+
+  #
+  # MIDI Pitch Bend message
+  #
+  class PitchBend
+    include ChannelMessage
+
+    STATUS = 0xE
+    DATA = [:channel, :low, :high].freeze
+    DISPLAY_NAME = 'Pitch Bend'.freeze
+
+    ChannelMessage::Accessors.decorate(self)
+  end
+
+  #
+  # MIDI Polyphonic (note specific) Aftertouch message
+  #
+  class PolyphonicAftertouch
+    include ChannelMessage
+
+    STATUS = 0xA
+    DATA = [:channel, :note, :value].freeze
+    DISPLAY_NAME = 'Polyphonic Aftertouch'.freeze
+    CONSTANT = { 'Note' => :note }.freeze
+
+    ChannelMessage::Accessors.decorate(self)
+  end
+  PolyAftertouch = PolyphonicAftertouch
+  PolyPressure = PolyphonicAftertouch
+  PolyphonicPressure = PolyphonicAftertouch
+
+  #
+  # MIDI Program Change message
+  #
+  class ProgramChange
+    include ChannelMessage
+
+    STATUS = 0xC
+    DATA = [:channel, :program].freeze
+    DISPLAY_NAME = 'Program Change'.freeze
+
+    ChannelMessage::Accessors.decorate(self)
+  end
+
+  #
+  # MIDI Note-Off message
+  #
+  class NoteOff
+    include NoteMessage
+
+    STATUS = 0x8
+    DATA = [:channel, :note, :velocity].freeze
+    DISPLAY_NAME = 'Note Off'.freeze
+    CONSTANT = { 'Note' => :note }.freeze
+
+    ChannelMessage::Accessors.decorate(self)
+  end
+
+  #
+  # MIDI Note-On message
+  #
+  class NoteOn
+    include NoteMessage
+
+    STATUS = 0x9
+    DATA = [:channel, :note, :velocity].freeze
+    DISPLAY_NAME = 'Note On'.freeze
+    CONSTANT = { 'Note' => :note }.freeze
+
+    ChannelMessage::Accessors.decorate(self)
+
+    # returns the NoteOff equivalent of this object
+    def to_note_off
+      NoteOff.new(channel, note, velocity)
+    end
+  end
+
+  #
+  # MIDI System-Common message
+  #
+  class SystemCommon
+    include SystemMessage
+
+    ID = (0x1..0x6).freeze
+    DISPLAY_NAME = 'System Common'.freeze
+
+    attr_reader :data
+
+    def initialize(*args)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      @const = options[:const]
+      id = @const.nil? ? args.shift : @const.value
+      id = strip_redundant_nibble(id)
+      initialize_message(SystemMessage::STATUS, id)
+      @data = args.slice(0..1)
+    end
+  end
+
+  #
+  # MIDI System-Realtime message
+  #
+  class SystemRealtime
+    include SystemMessage
+
+    ID = (0x8..0xF).freeze
+    DISPLAY_NAME = 'System Realtime'.freeze
+
+    def initialize(*args)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      @const = options[:const]
+      id = @const.nil? ? args.first : @const.value
+      id = strip_redundant_nibble(id)
+      initialize_message(SystemMessage::STATUS, id)
+    end
+
+    def id
+      @status[1]
+    end
+  end
+
+  module SystemExclusive
+    ID = 0x0
+    DELIMITER = {
+      start: 0xF0,
+      finish: 0xF7
+    }.freeze
+    DISPLAY_NAME = 'System Exclusive'.freeze
+
+    # A SysEx command message
+    # A command message is identified by having a status byte equal to 0x12
+    class Command
+      include SystemExclusive
+
+      attr_accessor :data
+      alias_method :value, :data
+
+      TYPE = 0x12
+
+      def initialize(address, data, options = {})
+        # store as a byte if it's a single byte
+        @data = if data.is_a?(Array) && data.length == 1
+          data.first
+        else
+          data
+        end
+        initialize_sysex(address, options)
+      end
+    end
+
+    # A SysEx request message
+    # A request message is identified by having a status byte equal to 0x11
+    class Request
+      include SystemExclusive
+
+      attr_reader :size
+      alias_method :value, :size
+
+      TYPE = 0x11
+
+      def initialize(address, size, options = {})
+        self.size = if size.is_a?(Array) && size.count == 1
+          size.first
+        else
+          size
+        end
+        initialize_sysex(address, options)
+      end
+
+      def size=(value)
+        # accepts a Numeric or Array but
+        # must always store value as an array of three bytes
+        size = []
+        if value.is_a?(Array) && value.size <= 3
+          size = value
+        elsif value.is_a?(Numeric) && (value + 1) / 247 <= 2
+          size = []
+          div, mod = *value.divmod(247)
+          size << mod unless mod.zero?
+          div.times { size << 247 }
+        end
+        (3 - size.size).times { size.unshift 0 }
+        @size = size
+      end
+    end
+  end
+end