mtk 0.0.3.2 → 0.0.3.3

data/lib/mtk/core/pitch_class.rb

@@ -0,0 +1,194 @@
+module MTK
+  module Core
+
+    # A set of all pitches that are an integer number of octaves apart.
+    # A {Pitch} has the same PitchClass as the pitches one or more octaves away.
+    # @see https://en.wikipedia.org/wiki/Pitch_class
+    #
+    class PitchClass
+
+      # The normalized names of the 12 pitch classes in the chromatic scale.
+      # The index of each {#name} is the pitch class's numeric {#value}.
+      NAMES = %w( C Db D Eb E F Gb G Ab A Bb B ).freeze
+
+      # All enharmonic names of the 12 pitch classes, including sharps, flats, double-sharps, and double-flats,
+      # organized such that each index contains the allowed names of the pitch class with a {#value} equal to that index.
+      # @see VALID_NAMES
+      VALID_NAMES_BY_VALUE =
+      [ # (valid names ), # value # normalized name
+        %w( B#  C  Dbb ), #   0   #   C
+        %w( B## C# Db  ), #   1   #   Db
+        %w( C## D  Ebb ), #   2   #   D
+        %w( D#  Eb Fbb ), #   3   #   Eb
+        %w( D## E  Fb  ), #   4   #   E
+        %w( E#  F  Gbb ), #   5   #   F
+        %w( E## F# Gb  ), #   6   #   Gb
+        %w( F## G  Abb ), #   7   #   G
+        %w( G#     Ab  ), #   8   #   Ab
+        %w( G## A  Bbb ), #   9   #   A
+        %w( A#  Bb Cbb ), #  10   #   Bb
+        %w( A## B  Cb  )  #  11   #   B
+      ].freeze
+
+      # All valid enharmonic pitch class names in a flat list.
+      # @see VALID_NAMES_BY_VALUE
+      VALID_NAMES = VALID_NAMES_BY_VALUE.flatten.freeze
+
+      # A mapping from valid names to the value of the pitch class with that name
+      VALUES_BY_NAME = Hash[ # a map from a list of name,value pairs
+        VALID_NAMES_BY_VALUE.map.with_index do |valid_names,value|
+          valid_names.map{|name| [name,value] }
+        end.flatten(1)
+      ].freeze
+
+
+      # The name of this pitch class.
+      # One of the {NAMES} defined by this class.
+      attr_reader :name
+
+      # The value of this pitch class.
+      # An integer from 0..11 that indexes this pitch class in {PITCH_CLASSES} and the {#name} in {NAMES}.
+      attr_reader :value
+
+
+      private  ######
+      # Even though new is a private_class_method, YARD gets confused so we temporarily go private
+
+      def initialize(name, value)
+        @name, @value = name, value
+      end
+      private_class_method :new
+
+      @flyweight = {}
+
+      public   ######
+
+
+      # Lookup a PitchClass by name or value.
+      # @param name_or_value [String,Symbol,Numeric] one of {VALID_NAMES} or 0..12
+      # @return the PitchClass representing the argument
+      # @raise ArgumentError for arguments that cannot be converted to a PitchClass
+      def self.[] name_or_value
+        @flyweight[name_or_value] ||= case name_or_value
+          when String,Symbol then from_name(name_or_value)
+          when Numeric       then from_value(name_or_value.round)
+          else raise ArgumentError.new("PitchClass.[] doesn't understand #{name_or_value.class}")
+        end
+      end
+
+      # Lookup a PitchClass by name.
+      # @param name [String,#to_s] one of {VALID_NAMES} (case-insensitive)
+      def self.from_name(name)
+        @flyweight[name] ||= (
+          valid_name = name.to_s.capitalize
+          value = VALUES_BY_NAME[valid_name] or raise ArgumentError.new("Invalid PitchClass name: #{name}")
+          new(valid_name,value)
+        )
+      end
+
+      class << self
+        alias from_s from_name
+      end
+
+      # All 12 pitch classes in the chromatic scale.
+      # The index of each pitch class is the pitch class's numeric {#value}.
+      PITCH_CLASSES = NAMES.map{|name| from_name name }.freeze
+
+      # return the pitch class with the given integer value mod 12
+      # @param value [Integer,#to_i]
+      def self.from_value(value)
+        PITCH_CLASSES[value.to_i % 12]
+      end
+
+      class << self
+        alias from_i from_value
+      end
+
+      # return the pitch class with the given float rounded to the nearest integer, mod 12
+      # @param value [Float,#to_f]
+      def self.from_f(value)
+        from_i value.to_f.round
+      end
+
+      # Compare 2 pitch classes for equal values.
+      # @param other [PitchClass]
+      # @return true if this pitch class's value is equal to the other pitch class's value
+      def == other
+        other.is_a? PitchClass and other.value == @value
+      end
+
+      # Compare a pitch class with another pitch class or integer value
+      # @param other [PitchClass,#to_i]
+      # @return -1, 0, or +1 depending on whether this pitch class's value is less than, equal to, or greater than the other object's integer value
+      # @see http://ruby-doc.org/core-1.9.3/Comparable.html
+      def <=> other
+        @value <=> other.to_i
+      end
+
+      # This pitch class's normalized {#name}.
+      # @see NAMES
+      def to_s
+        @name.to_s
+      end
+
+      # This pitch class's integer {#value}
+      def to_i
+        @value.to_i
+      end
+
+      # This pitch class's {#value} as a floating point number
+      def to_f
+        @value.to_f
+      end
+
+      # Transpose this pitch class by adding it's value to the value given (mod 12)
+      # @param interval [PitchClass,Float,#to_f]
+      def + interval
+        new_value = (value + interval.to_f).round
+        self.class.from_value new_value
+      end
+      alias transpose +
+
+      # Transpose this pitch class by subtracing the given value from this value (mod 12)
+      # @param interval [PitchClass,Float,#to_f]
+      def - interval
+        new_value = (value - interval.to_f).round
+        self.class.from_value new_value
+      end
+
+      # Inverts (mirrors) the pitch class around the given center
+      # @param center [PitchClass,Pitch,Float,#to_f] the value to "mirror" this pitch class around
+      def invert(center)
+        delta = (2*(center.to_f - value)).round
+        self + delta
+      end
+
+      # the smallest interval in semitones that needs to be added to this PitchClass to reach the given PitchClass
+      # @param pitch_class [PitchClass,#value]
+      def distance_to(pitch_class)
+        delta = (pitch_class.value - value) % 12
+        if delta > 6
+          delta -= 12
+        elsif delta == 6 and to_i >= 6
+          # this is a special edge case to prevent endlessly ascending pitch sequences when alternating between two pitch classes a tritone apart
+          delta = -6
+        end
+        delta
+      end
+
+    end
+  end
+
+  # Construct a {PitchClass} from any supported type
+  # @param anything [PitchClass,String,Symbol,Numeric]
+  def PitchClass(anything)
+    case anything
+      when Numeric then MTK::Core::PitchClass.from_f(anything)
+      when String, Symbol then MTK::Core::PitchClass.from_s(anything)
+      when MTK::Core::PitchClass then anything
+      else raise ArgumentError.new("PitchClass doesn't understand #{anything.class}")
+    end
+  end
+  module_function :PitchClass
+
+end

data/lib/mtk/events/event.rb

@@ -29,7 +29,7 @@ module MTK
 
       def duration= duration
         @duration = duration
-        @duration = ::MTK::Duration[@duration || 0] unless @duration.is_a? ::MTK::Duration
+        @duration = ::MTK::Core::Duration[@duration || 0] unless @duration.is_a? ::MTK::Core::Duration
         @duration
       end
 
@@ -42,15 +42,15 @@ module MTK
         @value = options[:value]
         @number = options[:number]
         @duration = options.fetch(:duration, 0)
-        @duration = ::MTK::Duration[@duration] unless @duration.is_a? ::MTK::Duration
+        @duration = ::MTK::Core::Duration[@duration] unless @duration.is_a? ::MTK::Core::Duration
         @channel = options[:channel]
       end
 
-      def self.from_hash(hash)
+      def self.from_h(hash)
         new(hash[:type], hash)
       end
 
-      def to_hash
+      def to_h
         hash = {:type => @type}
         hash[:value] = @value unless @value.nil?
         hash[:duration] = @duration unless @duration.nil?

data/lib/mtk/events/note.rb

@@ -5,8 +5,8 @@ module MTK
     # A musical {Event} defined by a {Pitch}, intensity, and duration
     class Note < Event
 
-      DEFAULT_DURATION  = MTK::Duration[1]
-      DEFAULT_INTENSITY = MTK::Intensity[0.75]
+      DEFAULT_DURATION  = MTK::Core::Duration[1]
+      DEFAULT_INTENSITY = MTK::Core::Intensity[0.75]
 
       # Frequency of the note as a {Pitch}.
       alias :pitch :number
@@ -24,16 +24,16 @@ module MTK
         super :note, number:pitch, duration:duration, value:intensity, channel:channel
       end
 
-      def self.from_hash(hash)
+      def self.from_h(hash)
         new(hash[:pitch]||hash[:number], hash[:duration], hash[:intensity]||hash[:value], hash[:channel])
       end
 
-      def to_hash
+      def to_h
         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 )
+        new( MTK::Lang::Pitches::PITCHES[pitch.to_i], MTK::Core::Duration[duration_in_beats], MTK::Core::Intensity[velocity/127.0], channel )
       end
 
       def midi_pitch
@@ -74,7 +74,7 @@ module MTK
     case anything
       when MTK::Events::Note then anything
 
-      when MTK::Pitch then MTK::Events::Note.new(anything)
+      when MTK::Core::Pitch then MTK::Events::Note.new(anything)
 
       when Array
         pitch = nil
@@ -84,18 +84,18 @@ module MTK
         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
+            when MTK::Core::Pitch then pitch = item
+            when MTK::Core::Duration then duration = item
+            when MTK::Core::Intensity then intensity = item
             else unknowns << item
           end
         end
 
-        pitch = MTK::Pitch(unknowns.shift) if pitch.nil? and not unknowns.empty?
+        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?
+        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

data/lib/mtk/events/timeline.rb

@@ -0,0 +1,232 @@
+module MTK
+  module Events
+
+    # A collection of timed events. The core data structure used to interface with input and output.
+    #
+    # Maps sorted floating point times to lists of events.
+    #
+    # Enumerable as [time,event_list] pairs.
+    #
+    class Timeline
+      include Enumerable
+
+      def initialize()
+        @timeline = {}
+      end
+
+      class << self
+        def from_a(enumerable)
+          new.merge enumerable
+        end
+        alias from_h from_a
+      end
+
+      def merge enumerable
+        enumerable.each do |time,events|
+          add(time,events)
+        end
+        self
+      end
+
+      def clear
+        @timeline.clear
+        self
+      end
+
+      def to_h
+        @timeline
+      end
+
+      def == other
+        other = other.to_h unless other.is_a? Hash
+        @timeline == other
+      end
+
+      def [](time)
+        @timeline[time.to_f]
+      end
+
+      def []=(time, events)
+        time = time.to_f unless time.is_a? Numeric
+        case events
+          when nil?
+            @timeline.delete time.to_f
+          when Array
+            @timeline[time.to_f] = events
+          else
+            @timeline[time.to_f] = [events]
+        end
+      end
+
+      def add(time, event)
+        events = @timeline[time.to_f]
+        if events
+          if event.is_a? Array
+            events.concat event
+          else
+            events << event
+          end
+        else
+           self[time] = event
+        end
+      end
+
+      def delete(time)
+        @timeline.delete(time.to_f)
+      end
+
+      def has_time? time
+        @timeline.has_key? time.to_f
+      end
+
+      def times
+        @timeline.keys.sort
+      end
+
+      def length
+        last_time = times.last
+        events = @timeline[last_time]
+        last_time + events.map{|event| event.duration }.max
+      end
+
+      def empty?
+        @timeline.empty?
+      end
+
+      def events
+        times.map{|t| @timeline[t] }.flatten
+      end
+
+      def each
+        # this is similar to @timeline.each, but by iterating over #times, we yield the events in chronological order
+        times.each do |time|
+          yield time, @timeline[time]
+        end
+      end
+
+      # the original Enumerable#map implementation, which returns an Array
+      alias enumerable_map map
+
+      # Constructs a new Timeline by mapping each [time,event_list] pair
+      # @see #map!
+      def map &block
+        self.class.from_a enumerable_map(&block)
+      end
+
+      # Perform #map in place
+      # @see #map
+      def map! &block
+        mapped = enumerable_map(&block)
+        clear
+        merge mapped
+      end
+
+      # Map every individual event, without regard for the time at which is occurs
+      def map_events
+        mapped_timeline = Timeline.new
+        self.each do |time,events|
+          mapped_timeline[time] = events.map{|event| yield event }
+        end
+        mapped_timeline
+      end
+
+      # Map every individual event in place, without regard for the time at which is occurs
+      def map_events!
+        each do |time,events|
+          self[time] = events.map{|event| yield event }
+        end
+      end
+
+      def clone
+        self.class.from_h(to_h)
+      end
+
+      def compact!
+        @timeline.delete_if {|t,events| events.empty? }
+      end
+
+      def flatten
+        flattened = Timeline.new
+        self.each do |time,events|
+          events.each do |event|
+            if event.is_a? Timeline
+              event.flatten.each do |subtime,subevent|
+                flattened.add(time+subtime, subevent)
+              end
+            else
+              flattened.add(time,event)
+            end
+          end
+        end
+        flattened
+      end
+
+      # @return a new Timeline where all times have been quantized to multiples of the given interval
+      # @example timeline.quantize(0.5)  # quantize to eight notes (assuming the beat is a quarter note)
+      # @see quantize!
+      def quantize interval
+        map{|time,events| [self.class.quantize_time(time,interval), events] }
+      end
+
+      def quantize! interval
+        map!{|time,events| [self.class.quantize_time(time,interval), events] }
+      end
+
+      # shifts all times by the given amount
+      # @see #shift!
+      # @see #shift_to
+      def shift time_delta
+        map{|time,events| [time+time_delta, events] }
+      end
+
+      # shifts all times in place by the given amount
+      # @see #shift
+      # @see #shift_to!
+      def shift! time_delta
+        map!{|time,events| [time+time_delta, events] }
+      end
+
+      # shifts the times so that the start of the timeline is at the given time
+      # @see #shift_to!
+      # @see #shift
+      def shift_to absolute_time
+        start = times.first
+        if start
+          shift absolute_time - start
+        else
+          clone
+        end
+      end
+
+      # shifts the times in place so that the start of the timeline is at the given time
+      # @see #shift_to
+      # @see #shift!
+      def shift_to! absolute_time
+        start = times.first
+        if start
+          shift! absolute_time - start
+        end
+        self
+      end
+
+      def to_s
+        times = self.times
+        last = times.last
+        width = sprintf("%d",last).length + 3 # nicely align the '=>' against the longest number
+        times.map{|t| sprintf("%#{width}.2f",t)+" => #{@timeline[t].join ', '}" }.join "\n"
+      end
+
+      def inspect
+        @timeline.inspect
+      end
+
+      def self.quantize_time time, interval
+        upper = interval * (time.to_f/interval).ceil
+        lower = upper - interval
+        (time - lower) < (upper - time) ? lower : upper
+      end
+
+    end
+
+  end
+end

data/lib/mtk/groups/chord.rb

@@ -0,0 +1,56 @@
+module MTK
+  module Groups
+
+    # A sorted collection of distinct {Pitch}es.
+    #
+    # The "vertical" (simultaneous) pitch collection.
+    #
+    # @see Melody
+    # @see Groups::PitchClassSet
+    #
+    class Chord < Melody
+
+      # @param pitches [#to_a] the collection of pitches
+      # @note duplicate pitches will be removed. See #{Melody} if you want to maintain duplicates.
+      #
+      def initialize(pitches)
+        pitches = pitches.to_a.clone
+        pitches.uniq!
+        pitches.sort!
+        @pitches = pitches.freeze
+      end
+
+      # Generate a chord inversion (positive numbers move the lowest notes up an octave, negative moves the highest notes down)
+      def inversion(number)
+        number = number.to_i
+        pitch_set = Array.new(@pitches.uniq.sort)
+        if number > 0
+          number.times do |count|
+            index = count % pitch_set.length
+            pitch_set[index] += 12
+          end
+        else
+          number.abs.times do |count|
+            index = -(count + 1) % pitch_set.length # count from -1 downward to go backwards through the list starting at the end
+            pitch_set[index] -= 12
+          end
+        end
+        self.class.new pitch_set.sort
+      end
+
+      # Transpose the chord so that it's lowest pitch is the given pitch class.
+      def nearest(pitch_class)
+        self.transpose @pitches.first.pitch_class.distance_to(pitch_class)
+      end
+    end
+  end
+
+  # Construct an ordered {MTK::Groups::Chord} with no duplicates.
+  # @see #MTK::Groups::Chord
+  # @see #MTK::Groups::Melody
+  def Chord(*anything)
+    MTK::Groups::Chord.new MTK::Groups.to_pitches(*anything)
+  end
+  module_function :Chord
+
+end

data/lib/mtk/{helpers → groups}/collection.rb

@@ -1,5 +1,5 @@
 module MTK
-  module Helpers
+  module Groups
 
      # Given a method #elements, which returns an Array of elements in the collection,
      # including this module will make the class Enumerable and provide various methods you'd expect from an Array.
@@ -160,5 +160,37 @@ module MTK
        end
 
      end
+
+
+     ######################################################################
+     # MTK::Groups
+
+     def to_pitch_classes(*anything)
+       anything = anything.first if anything.length == 1
+       if anything.respond_to? :to_pitch_classes
+         anything.to_pitch_classes
+       else
+         case anything
+           when ::Enumerable then anything.map{|item| MTK.PitchClass(item) }
+           else [MTK.PitchClass(anything)]
+         end
+       end
+     end
+     module_function :to_pitch_classes
+
+
+     def to_pitches(*anything)
+       anything = anything.first if anything.length == 1
+       if anything.respond_to? :to_pitches
+         anything.to_pitches
+       else
+         case anything
+           when ::Enumerable then anything.map{|item| MTK.Pitch(item) }
+           else [MTK.Pitch(anything)]
+         end
+       end
+     end
+     module_function :to_pitches
+
   end
 end