mtk 0.0.2 → 0.0.3

data/lib/mtk/pitch_class_set.rb

@@ -1,44 +1,53 @@
 module MTK
 
-  # An ordered Set of PitchClasses, for 12-tone set-theory pitch analysis and manipulations
+  # An ordered collection of {PitchClass}es.
+  #
+  # Unlike a mathematical Set, a PitchClassSet is ordered and may contain duplicates.
+  #
+  # @see Melody
+  # @see Chord
   #
   class PitchClassSet
-
-    include Helper::Collection
-    include Transform::Mappable
-    include Transform::Transposable
-    include Transform::Invertible
-    include Transform::SetTheoryOperations
+    include Helpers::PitchCollection
 
     attr_reader :pitch_classes
 
     def self.random_row
-      new(PitchClasses::PITCH_CLASSES.shuffle)
+      new(Constants::PitchClasses::PITCH_CLASSES.shuffle)
     end
 
     def self.all
-      @all ||= new(PitchClasses::PITCH_CLASSES)
+      @all ||= new(Constants::PitchClasses::PITCH_CLASSES)
     end
 
+    # @param pitch_classes [#to_a] the collection of pitch classes
+    #
+    # @see MTK#PitchClassSet
+    #
     def initialize(pitch_classes)
-      @pitch_classes = pitch_classes.to_a.uniq.freeze
+      @pitch_classes = pitch_classes.to_a.clone.freeze
     end
 
+    # @see Helper::Collection
     def elements
       @pitch_classes
     end
 
+    # Convert to an Array of pitch_classes.
+    # @note this returns a mutable copy the underlying @pitch_classes attribute, which is otherwise unmutable
+    alias :to_pitch_classes :to_a
+
     def self.from_a enumerable
       new enumerable
     end
 
     def normal_order
-      ordering = Array.new(@pitch_classes.sort)
+      ordering = Array.new(@pitch_classes.uniq.sort)
       min_span, start_index_for_normal_order = nil, nil
 
       # check every rotation for the minimal span:
       size.times do |index|
-        span = self.class.span_for ordering
+        span = self.class.span_between ordering.first, ordering.last
 
         if min_span.nil? or span < min_span
           # best so far
@@ -79,6 +88,31 @@ module MTK
       norder.map{|pitch_class| (pitch_class.to_i - first_pc_val) % 12 }
     end
 
+    # the collection of elements present in both sets
+    def intersection(other)
+      self.class.from_a(to_a & other.to_a)
+    end
+
+    # the collection of all elements present in either set
+    def union(other)
+      self.class.from_a(to_a | other.to_a)
+    end
+
+    # the collection of elements from this set with any elements from the other set removed
+    def difference(other)
+      self.class.from_a(to_a - other.to_a)
+    end
+
+    # the collection of elements that are members of exactly one of the sets
+    def symmetric_difference(other)
+      union(other).difference( intersection(other) )
+    end
+
+    # the collection of elements that are not members of this set
+    def complement
+      self.class.all.difference(self)
+    end
+
     # @param other [#pitch_classes, #to_a, Array]
     def == other
       if other.respond_to? :pitch_classes
@@ -90,19 +124,15 @@ module MTK
       end
     end
 
-    # Compare for equality, ignoring order
-    # @param other [#pitch_classes, #to_a, #sort, Array]
+    # Compare for equality, ignoring order and duplicates
+    # @param other [#pitch_classes, Array, #to_a]
     def =~ other
-      if other.is_a? Array and other.frozen?
-        @pitch_classes.sort == other
-      elsif other.respond_to? :pitch_classes
-        @pitch_classes.sort == other.pitch_classes.sort
-      elsif other.respond_to? :to_a
-        @pitch_classes.sort == other.to_a.sort
-      elsif other.respond_to? :sort
-        @pitch_classes.sort == other.sort
-      else
-        @pitch_classes.sort == other
+      @normalized_pitch_classes ||= @pitch_classes.uniq.sort
+      @normalized_pitch_classes == case
+        when other.respond_to?(:pitch_classes) then other.pitch_classes.uniq.sort
+        when (other.is_a? Array and other.frozen?) then other
+        when other.respond_to?(:to_a) then other.to_a.uniq.sort
+        else other
       end
     end
 
@@ -114,24 +144,17 @@ module MTK
       @pitch_classes.inspect
     end
 
-    def self.span_for(pitch_classes)
-      span_between pitch_classes.first, pitch_classes.last
-    end
-
     def self.span_between(pc1, pc2)
       (pc2.to_i - pc1.to_i) % 12
     end
 
   end
 
-  # Construct a {PitchClassSet} from any supported type
+
+  # Construct a {PitchClassSet}
+  # @see PitchClassSet#initialize
   def PitchClassSet(*anything)
-    anything = anything.first if anything.size == 1
-    case anything
-      when Array then PitchClassSet.new(anything.map{|elem| PitchClass(elem) })
-      when PitchClassSet then anything
-      else PitchClassSet.new([PitchClass(anything)])
-    end
+    PitchClassSet.new Helpers::Convert.to_pitch_classes(*anything)
   end
   module_function :PitchClassSet
 

data/lib/mtk/sequencers/event_builder.rb

@@ -0,0 +1,131 @@
+module MTK
+  module Sequencers
+
+    # A special pattern that takes a list of event properties and/or patterns and emits lists of {Events::Event}s
+    class EventBuilder
+
+      DEFAULT_PITCH = ::MTK::Constants::Pitches::C4
+      DEFAULT_DURATION = ::MTK::Constants::Durations::q
+      DEFAULT_INTENSITY = ::MTK::Constants::Intensities::o
+
+      def initialize(patterns, options={})
+        @patterns = patterns
+        @options = options
+        @default_pitch     = if options.has_key? :default_pitch     then MTK::Pitch(    options[:default_pitch])     else DEFAULT_PITCH     end
+        @default_duration  = if options.has_key? :default_duration  then MTK::Duration( options[:default_duration])  else DEFAULT_DURATION  end
+        @default_intensity = if options.has_key? :default_intensity then MTK::Intensity(options[:default_intensity]) else DEFAULT_INTENSITY end
+        @max_interval = options.fetch(:max_interval, 127)
+        rewind
+      end
+
+      # Build a list of events from the next element in each {Patterns::Pattern}
+      # @return [Array] an array of events
+      def next
+        pitches = []
+        intensities = []
+        duration = nil
+
+        @patterns.each do |pattern|
+          pattern_value = pattern.next
+
+          elements = pattern_value.is_a?(Enumerable) ? pattern_value : [pattern_value]
+          elements.each do |element|
+            return nil if element.nil? or element == :skip
+
+            case element
+              when ::MTK::Pitch         then pitches << element
+              when ::MTK::PitchClass    then pitches += pitches_for_pitch_classes([element], @previous_pitch)
+              when ::MTK::PitchClassSet then pitches += pitches_for_pitch_classes(element, @previous_pitch)
+              when ::MTK::Helpers::PitchCollection then pitches += element.pitches # this must be after the PitchClassSet case, because that is also a PitchCollection
+
+              when ::MTK::Duration
+                duration ||= 0
+                duration += element
+
+              when ::MTK::Intensity
+                intensities << element
+
+              when ::MTK::Interval
+                if @previous_pitches
+                  pitches += @previous_pitches.map{|pitch| pitch + element }
+                else
+                  pitches << (@previous_pitch + element)
+                end
+
+              # TODO? String/Symbols for special behaviors like :skip, or :break (something like StopIteration for the current Pattern?)
+
+              else STDERR.puts "#{self.class}#next: Unexpected type '#{element.class}'"
+            end
+
+          end
+        end
+
+        pitches     << @previous_pitch if pitches.empty?
+        duration   ||= @previous_duration
+
+        if intensities.empty?
+          intensity = @previous_intensity
+        else
+          intensity = MTK::Intensity[intensities.map{|i| i.to_f }.inject(:+)/intensities.length] # average the intensities
+        end
+
+        # Not using this yet, maybe later...
+        # return nil if duration==:skip or intensities.include? :skip or pitches.include? :skip
+
+        constrain_pitch(pitches)
+
+        @previous_pitch = pitches.last   # Consider doing something different, maybe averaging?
+        @previous_pitches = pitches.length > 1 ? pitches : nil
+        @previous_intensity = intensity
+        @previous_duration = duration
+
+        pitches.map{|pitch| MTK::Events::Note.new(pitch,duration,intensity) }
+      end
+
+      # Reset the EventBuilder to its initial state
+      def rewind
+        @previous_pitch     = @default_pitch
+        @previous_pitches   = [@default_pitch]
+        @previous_intensity = @default_intensity
+        @previous_duration  = @default_duration
+        @max_pitch = nil
+        @min_pitch = nil
+        @patterns.each{|pattern| pattern.rewind if pattern.is_a? MTK::Patterns::Pattern }
+      end
+
+      ########################
+      private
+
+      def pitches_for_pitch_classes(pitch_classes, previous_pitch)
+        pitch_classes.map{|pitch_class| previous_pitch.nearest(pitch_class) }
+      end
+
+      def constrain_pitch(pitches)
+        if @max_pitch.nil? or @min_pitch.nil?
+          first_pitch = pitches.first
+
+          @max_pitch = first_pitch + @max_interval
+          @max_pitch = 127 if @max_pitch > 127
+
+          @min_pitch = first_pitch - @max_interval
+          @min_pitch = 0 if @min_pitch < 0
+
+          @small_max_span = (@max_pitch - @min_pitch < 12)
+        end
+
+        pitches.map! do |pitch|
+          if @small_max_span
+            pitch = @max_pitch if pitch > @max_pitch
+            pitch = @min_pitch if pitch < @max_pitch
+          else
+            pitch -= 12 while pitch > @max_pitch
+            pitch += 12 while pitch < @min_pitch
+          end
+          pitch
+        end
+      end
+
+    end
+
+  end
+end

data/lib/mtk/sequencers/legato_sequencer.rb

@@ -0,0 +1,24 @@
+module MTK
+  module Sequencers
+
+    # A Sequencer which uses the longest duration of the events at each step to determine
+    # the delta times between entries in the {Timeline}.
+    class LegatoSequencer < Sequencer
+
+      # (see Sequencer#next)
+      def next
+        @previous_events = super
+      end
+
+     ########################
+      protected
+
+      # (see Sequencer#advance)
+      def advance
+        @time += @previous_events.map{|event| event.length }.max
+      end
+
+    end
+
+  end
+end

data/lib/mtk/sequencers/rhythmic_sequencer.rb

@@ -0,0 +1,28 @@
+module MTK
+  module Sequencers
+
+    # A Sequencer which uses a :rhythm type {Patterns::Pattern} to determine the delta times between entries in the {Timeline}.
+    class RhythmicSequencer < Sequencer
+
+      def initialize(patterns, options={})
+        super
+        @rhythm = options[:rhythm] or raise ArgumentError.new(":rhythm option is required")
+      end
+
+      def rewind
+        super
+        @rhythm.rewind if @rhythm
+      end
+
+     ########################
+      protected
+
+      # (see Sequencer#advance)
+      def advance
+        @time += @rhythm.next.length
+      end
+
+    end
+
+  end
+end

data/lib/mtk/{sequencer/abstract_sequencer.rb → sequencers/sequencer.rb}

@@ -1,11 +1,11 @@
 module MTK
-  module Sequencer
+  module Sequencers
 
-    # A Sequencer produces {Timeline}s from a collection of {Pattern}s.
+    # A Sequencer produces {Timeline}s from a collection of {Patterns::Pattern}s.
     #
     # @abstract Subclass and override {#advance} to implement a Sequencer.
     #
-    class AbstractSequencer
+    class Sequencer
 
       # The maximum number of [time,event_list] entries that will be generated for the {Timeline}.
       # nil means no maximum (be careful of infinite loops!)
@@ -15,7 +15,7 @@ module MTK
       # nil means no maximum (be careful of infinite loops!)
       attr_accessor :max_time
 
-      # Used by {#to_timeline} to builds event lists from the results of #{Pattern::Enumerator#next} for the {Pattern}s in this Sequencer.
+      # Used by {#to_timeline} to builds event lists from the results of {Patterns::Pattern#next} for the {Patterns::Pattern}s in this Sequencer.
       attr_reader :event_builder
 
       # The current time offset for the sequencer. Used for the {Timeline} times.
@@ -24,24 +24,37 @@ module MTK
       # The current sequencer step index (the number of times-1 that {#next} has been called), or -1 if the sequencer has not yet started.
       attr_reader :step
 
+      attr_reader :patterns
+
+      # @param patterns [Array] the list of patterns to be sequenced into a {Timeline}
+      # @param  options [Hash] the options to create a message with.
+      # @option options [String] :max_steps set {#max_steps}
+      # @option options [String] :max_time set {#max_time}
+      # @option options [Proc] :filter a Proc that will replace the events generated by {#next} with the results of the Proc[events]
+      # @option options [Class] :event_builder replace the {Sequencers::EventBuilder} with a custom Event pattern
       def initialize(patterns, options={})
         @patterns = patterns
         @max_steps = options[:max_steps]
         @max_time = options[:max_time]
+        @filter = options[:filter]
 
-        event_builder_class = options.fetch :event_builder, Helper::EventBuilder
+        event_builder_class = options.fetch :event_builder, ::MTK::Sequencers::EventBuilder
         @event_builder = event_builder_class.new(patterns, options)
+
         rewind
       end
 
 
-      # Produce a {Timeline} from the {Pattern}s in this Sequencer.
+      # Produce a {Timeline} from the {Patterns::Pattern}s in this Sequencer.
       def to_timeline
         rewind
         timeline = Timeline.new
         loop do
           events = self.next
-          timeline[@time] = events if events
+          if events
+            events = events.reject{|e| e.rest? }
+            timeline[@time] = events unless events.empty?
+          end
         end
         timeline
       end
@@ -52,12 +65,14 @@ module MTK
       #    so you can ignore this method unless you want to hack on sequencers at a lower level.
       def next
         if @step >= 0
-          advance!
+          advance
           raise StopIteration if @max_time and @time > @max_time
         end
         @step += 1
         raise StopIteration if @max_steps and @step >= @max_steps
-        @event_builder.next
+        events = @event_builder.next
+        events = @filter[events] if @filter
+        events
       end
 
 
@@ -67,7 +82,7 @@ module MTK
       def rewind
         @time = 0
         @step = -1
-        event_builder.rewind
+        @event_builder.rewind
       end
 
 
@@ -75,10 +90,21 @@ module MTK
       protected
 
       # Advance @time to the next time for the {Timeline} being produced by {#to_timeline}
-      def advance!
+      def advance
         @time += 1 # default behavior simply advances one beat at a time
       end
 
+      def self.inherited(subclass)
+        # Define a convenience method like MTK::Patterns.Sequence()
+        # that can handle varargs or a single array argument, plus any Hash options
+        classname = subclass.name.sub /.*::/, '' # Strip off module prefixes
+        MTK::Sequencers.define_singleton_method classname do |*args|
+          options  = (args[-1].is_a? Hash) ? args.pop : {}
+          args = args[0] if args.length == 1 and args[0].is_a? Array
+          subclass.new(args,options)
+        end
+      end
+
     end
 
   end