mtk 0.0.2 → 0.0.3

data/lib/mtk/duration.rb

@@ -0,0 +1,211 @@
+module MTK
+
+  # A measure of time in musical beats.
+  # May be negative to indicate a rest, which uses the absolute value for the effective duration.
+  class Duration
+
+    include Comparable
+
+    # The names of the base durations. See {MTK::Constants::Durations} for more info.
+    NAMES = %w[w h q i s r x].freeze
+
+    VALUES_BY_NAME = {
+      'w' => 4,
+      'h' => 2,
+      'q' => 1,
+      'i' => Rational(1,2),
+      's' => Rational(1,4),
+      'r' => Rational(1,8),
+      'x' => Rational(1,16)
+    }
+
+    @flyweight = {}
+
+    # The number of beats, typically represented as a Rational
+    attr_reader :value
+
+    def initialize( length_in_beats )
+      @value = length_in_beats
+    end
+
+    # Return a duration, only constructing a new instance when not already in the flyweight cache
+    def self.[](length_in_beats)
+      if length_in_beats.is_a? Fixnum
+        value = length_in_beats
+      else
+        value = Rational(length_in_beats)
+      end
+      @flyweight[value] ||= new(value)
+    end
+
+    class << self
+      alias :from_f :[]
+      alias :from_i :[]
+    end
+
+    # Lookup a duration by name.
+    # This method supports appending any combination of '.' and 't' for more fine-grained values.
+    # each '.' multiplies by 3/2, and each 't' multiplies by 2/3.
+    # You may use the prefix '-' to negate the duration (which turns it into a rest of the same length).
+    # You may also prefix (after the '-' if present) the base duration name with an integer, float, or rational number
+    # to multiply the base duration value. Rationals are in the form "#{{numerator_integer}}/#{{denominator_integer}}".
+    # @example lookup value of 'q.', which is 1.5 times a quarter note (1.5 beats):
+    #          MTK::Duration.from_s('q.')
+    # @example lookup the value of 3/4w, which three-quarters of a whole note (3 beats):
+    #          MTK::Duration.from_s('3/4w')
+    def self.from_s(s)
+      if s =~ /^(-)?(\d+([\.\/]\d+)?)?([whqisrx])((\.|t)*)$/i
+        name = $4.downcase
+        modifier = $5.downcase
+        modifier << $1 if $1 # negation
+        multiplier = $2
+      else
+        raise ArgumentError.new("Invalid Duration string '#{s}'")
+      end
+
+      value = VALUES_BY_NAME[name]
+      modifier.each_char do |mod|
+        case mod
+          when '-' then value *= -1
+          when '.' then value *= Rational(3,2)
+          when 't' then value *= Rational(2,3)
+        end
+      end
+
+      if multiplier
+        case multiplier
+          when /\./
+            value *= multiplier.to_f
+          when /\//
+            numerator, denominator = multiplier.split('/')
+            value *= Rational(numerator.to_i, denominator.to_i)
+          else
+            value *= multiplier.to_i
+        end
+      end
+
+      self[value]
+    end
+
+    class << self
+      alias :from_name :from_s
+    end
+
+    # The magnitude (absolute value) of the duration.
+    # This is the actual duration for rests.
+    # @see #rest?
+    def length
+      @value < 0 ? -@value : @value
+    end
+
+    # Durations with negative values are rests.
+    # @see #length
+    # @see #-@
+    def rest?
+      @value < 0
+    end
+
+    # The number of beats as a floating point number
+    def to_f
+      @value.to_f
+    end
+
+    # The numerical value for the nearest whole number of beats
+    def to_i
+      @value.round
+    end
+
+    def to_s
+      value = @value.to_s
+      value = sprintf '%.2f', @value if value.length > 6 # threshold is 6 for no particular reason...
+      "#{value} #{@value.abs > 1 || @value==0 ? 'beats' : 'beat'}"
+    end
+
+    def inspect
+      "#<#{self.class}:#{object_id} @value=#{@value}>"
+    end
+
+    def ==( other )
+      if other.is_a? MTK::Duration
+        other.value == @value
+      else
+        other == @value
+      end
+    end
+
+    def <=> other
+      if other.respond_to? :value
+        @value <=> other.value
+      else
+        @value <=> other
+      end
+    end
+
+    # Add this duration to another.
+    # @return a new Duration that has a value of the sum of the arguments.
+    def + duration
+      if duration.is_a? MTK::Duration
+        MTK::Duration[@value + duration.value]
+      else
+        MTK::Duration[@value + duration]
+      end
+    end
+
+    # Subtract another duration from this one.
+    # @return a new Duration that has a value of the difference of the arguments.
+    def - duration
+      if duration.is_a? MTK::Duration
+        MTK::Duration[@value - duration.value]
+      else
+        MTK::Duration[@value - duration]
+      end
+    end
+
+    # Multiply this duration with another.
+    # @return a new Duration that has a value of the product of the arguments.
+    def * duration
+      if duration.is_a? MTK::Duration
+        MTK::Duration[@value * duration.value]
+      else
+        MTK::Duration[@value * duration]
+      end
+    end
+
+    # Divide this duration with another.
+    # @return a new Duration that has a value of the division of the arguments.
+    def / duration
+      if duration.is_a? MTK::Duration
+        MTK::Duration[to_f / duration.value]
+      else
+        MTK::Duration[to_f / duration]
+      end
+    end
+
+    # Negate the duration value.
+    # Turns normal durations into rests and vice versa.
+    # @return a new Duration that has a negated value.
+    # @see #rest?
+    def -@
+      MTK::Duration[@value * -1]
+    end
+
+    # Allow basic math operations with Numeric objects.
+    def coerce(other)
+      return MTK::Duration[other], self
+    end
+
+  end
+
+  # Construct a {Duration} from any supported type
+  def Duration(*anything)
+    anything = anything.first if anything.length == 1
+    case anything
+      when Numeric then MTK::Duration[anything]
+      when String, Symbol then MTK::Duration.from_s(anything)
+      when Duration then anything
+      else raise "Duration doesn't understand #{anything.class}"
+    end
+  end
+  module_function :Duration
+
+end

data/lib/mtk/events/event.rb

@@ -0,0 +1,119 @@
+module MTK
+
+  module Events
+
+    # An abstract musical event
+    # @abstract
+    class Event
+
+      # The type of event: :note, :control, :pressure, :bend, or :program
+      attr_reader :type
+
+      # The specific element effected by this type of event, when applicable.
+      # Depends on the event type. For example, the number of a :note type Event is the pitch,
+      # and the number of a :control type Event is the controller (CC) number.
+      # This value is nil for inapplicable event types.
+      attr_accessor :number
+
+      # The value of event.
+      # Depends on event type. For example, the value of a :note type Event is the intensity,
+      # and the value of a :control type Event is the controller (CC) value.
+      attr_accessor :value
+
+      # Duration of the Event in beats (e.g. 1.0 is a quarter note in 4/4 time signatures)
+      # @see length
+      # @see rest?
+      # @see instantaneous?
+      # @see duration_in_pulses
+      attr_reader :duration
+
+      def duration= duration
+        @duration = duration
+        @duration = ::MTK::Duration[@duration || 0] unless @duration.is_a? ::MTK::Duration
+        @duration
+      end
+
+      # The channel of the event, for multi-tracked events.
+      attr_accessor :channel
+
+
+      def initialize(type, options={})
+        @type = type
+        @value = options[:value]
+        @number = options[:number]
+        @duration = options.fetch(:duration, 0)
+        @duration = ::MTK::Duration[@duration] unless @duration.is_a? ::MTK::Duration
+        @channel = options[:channel]
+      end
+
+      def self.from_hash(hash)
+        new(hash[:type], hash)
+      end
+
+      def to_hash
+        hash = {:type => @type}
+        hash[:value] = @value unless @value.nil?
+        hash[:duration] = @duration unless @duration.nil?
+        hash[:number] = @number unless @number.nil?
+        hash[:channel] = @channel unless @channel.nil?
+        hash
+      end
+
+      def midi_value
+        if @value and @value.respond_to? :to_midi
+          @value.to_midi
+        else
+          value = @value
+          midi_value = (127 * (value || 0)).round
+          midi_value = 0 if midi_value < 0
+          midi_value = 127 if midi_value > 127
+          midi_value
+        end
+      end
+
+      def midi_value= value
+        @value = value/127.0
+      end
+
+      # The magnitude (absolute value) of the duration.
+      # Indicate the "real" duration for rests.
+      # @see rest?
+      def length
+        @duration.length
+      end
+
+      # By convention, any events with negative durations are a rest
+      def rest?
+        @duration.rest?
+      end
+
+      # By convention, any events with 0 duration are instantaneous
+      def instantaneous?
+        @duration.nil? or @duration == 0
+      end
+
+      # Convert duration to an integer number of MIDI pulses, given the pulses_per_beat
+      def duration_in_pulses(pulses_per_beat)
+        (length.to_f * pulses_per_beat).round
+      end
+
+      def == other
+        other.respond_to? :type and @type == other.type and
+        other.respond_to? :number and @number == other.number and
+        other.respond_to? :value and @value == other.value and
+        other.respond_to? :duration and @duration == other.duration and
+        other.respond_to? :channel and @channel == other.channel
+      end
+
+      def to_s
+        "Event(#@type" + (@number ? "[#@number]" : '') + ", #{sprintf '%.2f',@value}, #{sprintf '%.2f',@duration})"
+      end
+
+      def inspect
+        "Event(#@type" + (@number ? "[#@number]" : '') + ", #@value, #{@duration.to_f})"
+      end
+
+    end
+
+  end
+end

data/lib/mtk/events/note.rb

@@ -0,0 +1,112 @@
+module MTK
+
+  module Events
+
+    # A musical {Event} defined by a {Pitch}, intensity, and duration
+    class Note < Event
+
+      DEFAULT_DURATION  = MTK::Duration[1]
+      DEFAULT_INTENSITY = MTK::Intensity[0.75]
+
+      # Frequency of the note as a {Pitch}.
+      alias :pitch :number
+      alias :pitch= :number=
+
+      # Intensity of the note as a value in the range 0.0 - 1.0.
+      alias :intensity :value
+      alias :intensity= :value=
+
+      # intensity scaled to the MIDI range 0-127
+      alias :velocity :midi_value
+      alias :velocity= :midi_value=
+
+      def initialize(pitch, duration=DEFAULT_DURATION, intensity=DEFAULT_INTENSITY, channel=nil)
+        super :note, number:pitch, duration:duration, value:intensity, channel:channel
+      end
+
+      def self.from_hash(hash)
+        new(hash[:pitch]||hash[:number], hash[:duration], hash[:intensity]||hash[:value], hash[:channel])
+      end
+
+      def to_hash
+        super.merge({ pitch: @number, intensity: @value })
+      end
+
+      def self.from_midi(pitch, velocity, duration_in_beats, channel=0)
+        new( MTK::Constants::Pitches::PITCHES[pitch.to_i], MTK::Duration[duration_in_beats], MTK::Intensity[velocity/127.0], channel )
+      end
+
+      def midi_pitch
+        pitch.to_i
+      end
+
+      def transpose(interval)
+        self.pitch += interval
+        self
+      end
+
+      def invert(around_pitch)
+        self.pitch = self.pitch.invert(around_pitch)
+        self
+      end
+
+      def ==(other)
+        ( other.respond_to? :pitch and pitch == other.pitch and
+          other.respond_to? :intensity and intensity == other.intensity and
+          other.respond_to? :duration and duration == other.duration
+        ) or super
+      end
+
+      def to_s
+        "Note(#{@number}, #{@duration}, #{@value.to_percent}%)"
+      end
+
+      def inspect
+        "#<#{self.class}:#{object_id} @pitch=#{@number.inspect}, @duration=#{@duration.inspect}, @intensity=#{@value.inspect}>"
+      end
+
+    end
+  end
+
+  # Construct a {Events::Note} from a list of any supported type for the arguments: pitch, intensity, duration, channel
+  def Note(*anything)
+    anything = anything.first if anything.size == 1
+    case anything
+      when MTK::Events::Note then anything
+
+      when MTK::Pitch then MTK::Events::Note.new(anything)
+
+      when Array
+        pitch = nil
+        duration = nil
+        intensity = nil
+        channel = nil
+        unknowns = []
+        anything.each do |item|
+          case item
+            when MTK::Pitch then pitch = item
+            when MTK::Duration then duration = item
+            when MTK::Intensity then intensity = item
+            else unknowns << item
+          end
+        end
+
+        pitch = MTK::Pitch(unknowns.shift) if pitch.nil? and not unknowns.empty?
+        raise "MTK::Note() couldn't find a pitch in arguments: #{anything.inspect}" if pitch.nil?
+
+        duration  = MTK::Duration(unknowns.shift)  if duration.nil?  and not unknowns.empty?
+        intensity = MTK::Intensity(unknowns.shift) if intensity.nil? and not unknowns.empty?
+        channel = unknowns.shift.to_i if channel.nil? and not unknowns.empty?
+
+        duration  ||= MTK::Events::Note::DEFAULT_DURATION
+        intensity ||= MTK::Events::Note::DEFAULT_INTENSITY
+
+        MTK::Events::Note.new( pitch, duration, intensity, channel )
+
+      else
+        raise "MTK::Note() doesn't understand #{anything.class}"
+    end
+  end
+  module_function :Note
+
+end

data/lib/mtk/events/parameter.rb

@@ -0,0 +1,54 @@
+module MTK
+
+  module Events
+
+    class Parameter < Event
+
+      def self.from_midi(status, data1, data2)
+        if status.is_a? Array
+          type,channel = *status
+        else
+          type,channel = status & 0xF0, status & 0x0F
+        end
+        type, number, value = *(
+          case type
+            when 0xA0,:poly_pressure    then [:pressure, data1, data2]
+            when 0xB0,:control_change   then [:control, data1, data2]
+            when 0xC0,:program_change   then [:program, data1]
+            when 0xD0,:channel_pressure then [:pressure, nil, data1] # no number means all notes on channel
+            when 0xE0,:pitch_bend       then [:bend, nil, (data1 + (data2 << 7))]
+            else [:unknown, data1, data2]
+          end
+        )
+        if type == :bend
+          if value == 16383
+            value = 1.0 # special case since the math doesn't quite work out to convert to -1..1 for all values
+          else
+            value = (value / 8192.0) - 1.0
+          end
+        elsif value.is_a? Numeric
+          value /= 127.0
+        end
+        new type, :number => number, :value => value, :channel => channel
+      end
+
+      def midi_value
+        if @type == :bend
+          (16383*(@value+1)/2).round
+        else
+          super
+        end
+      end
+
+      def to_s
+        "Parameter(#@type" + (@number ? "[#@number], " : ', ') + "#{sprintf '%.2f', @value || Float::NAN})"
+      end
+
+      def inspect
+        "Parameter(#@type" + (@number ? "[#@number], " : ', ') + "#@value)"
+      end
+
+    end
+
+  end
+end