mtk 0.0.3.2 → 0.0.3.3

data/lib/mtk/groups/melody.rb

@@ -0,0 +1,96 @@
+module MTK
+  module Groups
+
+    # An ordered collection of {Pitch}es.
+    #
+    # The "horizontal" (sequential) pitch collection.
+    #
+    # Unlike the strict definition of melody, this class is fairly abstract and only models a succession of pitches.
+    # To create a true, playable melody one must combine an MTK::Melody and rhythms into a {Events::Timeline}.
+    #
+    # @see Chord
+    #
+    class Melody
+      include PitchCollection
+
+      attr_reader :pitches
+
+      # @param pitches [#to_a] the collection of pitches
+      # @see MTK#Melody
+      #
+      def initialize(pitches)
+        @pitches = pitches.to_a.clone.freeze
+      end
+
+      def self.from_pitch_classes(pitch_classes, start=MTK::Lang::Pitches::C4, max_distance=12)
+        pitch = start
+        pitches = []
+        pitch_classes.each do |pitch_class|
+          pitch = pitch.nearest(pitch_class)
+          pitch -= 12 if pitch > start+max_distance # keep within max_distance of start (default is one octave)
+          pitch += 12 if pitch < start-max_distance
+          pitches << pitch
+        end
+        new pitches
+      end
+
+      # @see Helper::Collection
+      def elements
+        @pitches
+      end
+
+      # Convert to an Array of pitches.
+      # @note this returns a mutable copy the underlying @pitches attribute, which is otherwise unmutable
+      alias :to_pitches :to_a
+
+      def self.from_a enumerable
+        new enumerable
+      end
+
+      def to_pitch_class_set(remove_duplicates=true)
+        PitchClassSet.new(remove_duplicates ? pitch_classes.uniq : pitch_classes)
+      end
+
+      def pitch_classes
+        @pitch_classes ||= @pitches.map{|p| p.pitch_class }
+      end
+
+      # @param other [#pitches, Enumerable]
+      def == other
+        if other.respond_to? :pitches
+          @pitches == other.pitches
+        elsif other.is_a? Enumerable
+          @pitches == other.to_a
+        else
+          @pitches == other
+        end
+      end
+
+      # Compare for equality, ignoring order and duplicates
+      # @param other [#pitches, Array, #to_a]
+      def =~ other
+        @normalized_pitches ||= @pitches.uniq.sort
+        @normalized_pitches == case
+          when other.respond_to?(:pitches) then other.pitches.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
+
+      def to_s
+        '[' + @pitches.map{|pitch| pitch.to_s}.join(', ') + ']'
+      end
+
+    end
+  end
+
+  # Construct an ordered {MTK::Groups::Melody} that allows duplicates
+  # @see #MTK::Groups::Melody
+  # @see #MTK::Groups::Chord
+  def Melody(*anything)
+    MTK::Groups::Melody.new MTK::Groups.to_pitches(*anything)
+  end
+  module_function :Melody
+
+end

data/lib/mtk/groups/pitch_class_set.rb

@@ -0,0 +1,163 @@
+module MTK
+
+  module Groups
+
+    # An ordered collection of {PitchClass}es.
+    #
+    # Unlike a mathematical Set, a PitchClassSet is ordered and may contain duplicates.
+    #
+    # @see MTK::Groups::Melody
+    # @see MTK::Groups::Chord
+    #
+    class PitchClassSet
+      include PitchCollection
+
+      attr_reader :pitch_classes
+
+      def self.random_row
+        new(MTK::Lang::PitchClasses::PITCH_CLASSES.shuffle)
+      end
+
+      def self.all
+        @all ||= new(MTK::Lang::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.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.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_between ordering.first, ordering.last
+
+          if min_span.nil? or span < min_span
+            # best so far
+            min_span = span
+            start_index_for_normal_order = index
+
+          elsif span == min_span
+            # handle ties, minimize distance between first and second-to-last note, then first and third-to-last, etc
+            span1, span2 = nil, nil
+            tie_breaker = 1
+            while span1 == span2 and tie_breaker < size
+              span1 = self.class.span_between( ordering[0], ordering[-1 - tie_breaker] )
+              span2 = self.class.span_between( ordering[start_index_for_normal_order], ordering[start_index_for_normal_order - tie_breaker] )
+              tie_breaker -= 1
+            end
+            if span1 != span2
+              # tie cannot be broken, pick the one starting with the lowest pitch class
+              if ordering[0].to_i < ordering[start_index_for_normal_order].to_i
+                start_index_for_normal_order = index
+              end
+            elsif span1 < span2
+              start_index_for_normal_order = index
+            end
+
+          end
+          ordering << ordering.shift  # rotate
+        end
+
+        # we've rotated all the way around, so we now need to rotate back to the start index we just found:
+        start_index_for_normal_order.times{ ordering << ordering.shift }
+
+        ordering
+      end
+
+      def normal_form
+        norder = normal_order
+        first_pc_val = norder.first.to_i
+        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
+          @pitch_classes == other.pitch_classes
+        elsif other.respond_to? :to_a
+          @pitch_classes == other.to_a
+        else
+          @pitch_classes == other
+        end
+      end
+
+      # Compare for equality, ignoring order and duplicates
+      # @param other [#pitch_classes, Array, #to_a]
+      def =~ 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
+
+      def to_s
+        @pitch_classes.join(' ')
+      end
+
+      def inspect
+        @pitch_classes.inspect
+      end
+
+      def self.span_between(pc1, pc2)
+        (pc2.to_i - pc1.to_i) % 12
+      end
+
+    end
+  end
+
+  # Construct a {Groups::PitchClassSet}
+  # @see Groups::PitchClassSet#initialize
+  def PitchClassSet(*anything)
+    MTK::Groups::PitchClassSet.new MTK::Groups.to_pitch_classes(*anything)
+  end
+  module_function :PitchClassSet
+
+end

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

@@ -1,5 +1,5 @@
 module MTK
-  module Helpers
+  module Groups
 
     # An extension to {Collection}, which provides additional transformations for pitch-like collections.
     #

data/lib/mtk/{midi → io}/dls_synth_device.rb

@@ -1,16 +1,18 @@
 require 'ffi'
 
 module MTK
-  module MIDI
+  module IO
 
     # An output device for Apple's built-in "DLS" synthesizer on OS X
     class DLSSynthDevice
 
+      # @private
       module AudioToolbox
         extend FFI::Library
         ffi_lib '/System/Library/Frameworks/AudioToolbox.framework/Versions/Current/AudioToolbox'
         ffi_lib '/System/Library/Frameworks/AudioUnit.framework/Versions/Current/AudioUnit'
 
+        # @private
         class ComponentDescription < FFI::Struct
           layout :componentType, :int,
                  :componentSubType, :int,

data/lib/mtk/{midi → io}/dls_synth_output.rb

@@ -1,12 +1,12 @@
-require 'mtk/midi/dls_synth_device'
+require 'mtk/io/dls_synth_device'
 
 module MTK
-  module MIDI
+  module IO
 
     # Provides realtime MIDI output on OS X to the built-in "DLS" Synthesizer
     # @note This class is optional and only available if you require 'mtk/midi/dls_synth_output'.
     #       It depends on the 'gamelan' gem.
-    class DLSSynthOutput < Output
+    class DLSSynthOutput < MIDIOutput
 
       public_class_method :new
 
@@ -22,37 +22,37 @@ module MTK
       ######################
       protected
 
-      # (see Output#note_on)
+      # (see MIDIOutput#note_on)
       def note_on(pitch, velocity, channel)
         @device.message(0x90|channel, pitch, velocity)
       end
 
-      # (see Output#note_off)
+      # (see MIDIOutput#note_off)
       def note_off(pitch, velocity, channel)
         @device.message(0x80|channel, pitch, velocity)
       end
 
-      # (see Output#control)
+      # (see MIDIOutput#control)
       def control(number, midi_value, channel)
         @device.message(0xB0|channel, number, midi_value)
       end
 
-      # (see Output#channel_pressure)
+      # (see MIDIOutput#channel_pressure)
       def channel_pressure(midi_value, channel)
         @device.message(0xD0|channel, midi_value, 0)
       end
 
-      # (see Output#poly_pressure)
+      # (see MIDIOutput#poly_pressure)
       def poly_pressure(pitch, midi_value, channel)
         @device.message(0xA0|channel, pitch, midi_value)
       end
 
-      # (see Output#bend)
+      # (see MIDIOutput#bend)
       def bend(midi_value, channel)
         @device.message(0xE0|channel, midi_value & 127, (midi_value >> 7) & 127)
       end
 
-      # (see Output#program)
+      # (see MIDIOutput#program)
       def program(number, channel)
         @device.message(0xC0|channel, number, 0)
       end

data/lib/mtk/{midi → io}/jsound_input.rb

@@ -1,12 +1,12 @@
 require 'jsound'
 
 module MTK
-  module MIDI
+  module IO
 
     # Provides realtime MIDI input for JRuby via the jsound gem.
     # @note This class is optional and only available if you require 'mtk/midi/jsound_input'.
     #       It depends on the 'jsound' gem.
-    class JSoundInput < Input
+    class JSoundInput < MIDIInput
 
       public_class_method :new
 

data/lib/mtk/{midi → io}/jsound_output.rb

@@ -1,12 +1,12 @@
 require 'jsound'
 
 module MTK
-  module MIDI
+  module IO
 
     # Provides realtime MIDI output for JRuby via the jsound and gamelan gems.
     # @note This class is optional and only available if you require 'mtk/midi/jsound_output'.
     #       It depends on the 'jsound' and 'gamelan' gems.
-    class JSoundOutput < Output
+    class JSoundOutput < MIDIOutput
 
       public_class_method :new
 
@@ -41,37 +41,37 @@ module MTK
       ######################
       protected
 
-      # (see Output#note_on)
+      # (see MIDIOutput#note_on)
       def note_on(pitch, velocity, channel)
         @generator.note_on(pitch, velocity, channel)
       end
 
-      # (see Output#note_off)
+      # (see MIDIOutput#note_off)
       def note_off(pitch, velocity, channel)
         @generator.note_off(pitch, velocity, channel)
       end
 
-      # (see Output#control)
+      # (see MIDIOutput#control)
       def control(number, midi_value, channel)
         @generator.control_change(number, midi_value, channel)
       end
 
-      # (see Output#channel_pressure)
+      # (see MIDIOutput#channel_pressure)
       def channel_pressure(midi_value, channel)
         @generator.channel_pressure(midi_value, channel)
       end
 
-      # (see Output#poly_pressure)
+      # (see MIDIOutput#poly_pressure)
       def poly_pressure(pitch, midi_value, channel)
         @generator.poly_pressure(pitch, midi_value, channel)
       end
 
-      # (see Output#bend)
+      # (see MIDIOutput#bend)
       def bend(midi_value, channel)
         @generator.pitch_bend(midi_value, channel)
       end
 
-      # (see Output#program)
+      # (see MIDIOutput#program)
       def program(number, channel)
         @generator.program_change(number, channel)
       end

data/lib/mtk/{midi/file.rb → io/midi_file.rb}

@@ -1,12 +1,12 @@
 require 'midilib'
 
 module MTK
-  module MIDI
+  module IO
 
-    # MIDI file I/O: reads MIDI files into {Timeline}s and writes {Timeline}s to MIDI files.
+    # MIDI file I/O: reads MIDI files into {Events::Timeline}s and writes {Events::Timeline}s to MIDI files.
     # @note This class is optional and only available if you require 'mtk/midi/file'.
     #       It depends on the 'midilib' gem.
-    class File
+    class MIDIFile
       def initialize file
         if file.respond_to? :path
           @file = file.path
@@ -15,7 +15,7 @@ module MTK
         end
       end
 
-      # Read a MIDI file into an Array of {Timeline}s
+      # Read a MIDI file into an Array of {Events::Timeline}s
       #
       # @return [Timeline]
       #
@@ -30,7 +30,7 @@ module MTK
 
           sequence.each do |track|
             track_idx += 1
-            timeline = Timeline.new
+            timeline =  MTK::Events::Timeline.new
             note_ons = {}
             #puts "TRACK #{track_idx}"
 
@@ -46,7 +46,7 @@ module MTK
                   on_time,on_event = note_ons.delete(event.note)
                   if on_event
                     duration = time - on_time
-                    note = MTK::Events::Note.from_midi(event.note, on_event.velocity, duration)
+                    note = MTK::Events::Note.from_midi(event.note, on_event.velocity, duration, event.channel)
                     timeline.add on_time, note
                   end
 
@@ -66,7 +66,7 @@ module MTK
 
       def write(anything)
         case anything
-          when Timeline then write_timeline(anything)
+          when  MTK::Events::Timeline then write_timeline(anything)
           when Enumerable then write_timelines(anything)
           else raise "#{self.class}#write doesn't understand #{anything.class}"
         end
@@ -92,7 +92,7 @@ module MTK
           events.each do |event|
             next if event.rest?
 
-            channel = event.channel || 0
+            channel = (event.channel || 1) - 1 # midilib seems to count channels from 0, hence the -1
 
             case event.type
               when :note
@@ -132,7 +132,7 @@ module MTK
       private
 
       def write_to_disk(sequence)
-        puts "Writing file #{@file}"
+        puts "Writing file #{@file}" unless $__RUNNING_RSPEC_TESTS__
         ::File.open(@file, 'wb') { |f| sequence.write f }
       end
 
@@ -198,12 +198,12 @@ module MTK
     end
   end
 
-  # Shortcut for MTK::MIDI::File.new
+  # Shortcut for MTK::IO::MIDIFile.new
   # @note Only available if you require 'mtk/midi/file'
-  def MIDI_File(f)
-    MIDI::File.new(f)
+  def MIDIFile(f)
+    ::MTK::IO::MIDIFile.new(f)
   end
-  module_function :MIDI_File
+  module_function :MIDIFile
 
 end
 

data/lib/mtk/{midi/input.rb → io/midi_input.rb}

@@ -1,9 +1,9 @@
 module MTK
-  module MIDI
+  module IO
 
     # Common behavior for realtime MIDI input.
     #
-    class Input
+    class MIDIInput
 
       class << self
 
@@ -90,8 +90,8 @@ end
 
 unless $__RUNNING_RSPEC_TESTS__ # I can't get this working on Travis-CI, problem installing native dependencies
   if RUBY_PLATFORM == 'java'
-    require 'mtk/midi/jsound_input'
+    require 'mtk/io/jsound_input'
   else
-    require 'mtk/midi/unimidi_input'
+    require 'mtk/io/unimidi_input'
   end
 end

data/lib/mtk/{midi/output.rb → io/midi_output.rb}

@@ -2,13 +2,13 @@ require 'rbconfig'
 require 'gamelan'
 
 module MTK
-  module MIDI
+  module IO
 
     # Provides a scheduler and common behavior for realtime MIDI output, using the gamelan gem for scheduling.
     #
     # @abstract Subclasses must provide {.devices}, {.devices_by_name}, {#note_on}, {#note_off}, {#control}, {#channel_pressure}, {#poly_pressure}, {#bend}, and {#program} to implement a MIDI output.
     #
-    class Output
+    class MIDIOutput
 
       class << self
 
@@ -80,9 +80,9 @@ module MTK
 
       def play(anything, options={})
         timeline = case anything
-          when MTK::Timeline then anything
-          when Hash then MTK::Timeline.from_hash anything
-          when Enumerable,MTK::Events::Event then MTK::Timeline.from_hash(0 => anything)
+          when MTK::Events::Timeline then anything
+          when Hash then  MTK::Events::Timeline.from_h anything
+          when Enumerable,MTK::Events::Event then  MTK::Events::Timeline.from_h(0 => anything)
           else raise "#{self.class}.play() doesn't understand #{anything} (#{anything.class})"
         end
         timeline = timeline.flatten
@@ -184,12 +184,12 @@ end
 unless $__RUNNING_RSPEC_TESTS__ # I can't get this working on Travis-CI, problem installing native dependencies
   if RbConfig::CONFIG['host_os'] =~ /darwin/
     # We're running on OS X
-    require 'mtk/midi/dls_synth_output'
+    require 'mtk/io/dls_synth_output'
   end
 
   if RUBY_PLATFORM == 'java'
-    require 'mtk/midi/jsound_output'
+    require 'mtk/io/jsound_output'
   else
-    require 'mtk/midi/unimidi_output'
+    require 'mtk/io/unimidi_output'
   end
 end

data/lib/mtk/{helpers/lilypond.rb → io/notation.rb}

@@ -3,14 +3,14 @@ require 'tmpdir'
 require 'fileutils'
 
 module MTK
-  module Helpers
+  module IO
 
-    # Uses {Timeline}s to generates music notation graphics with {http://lilypond.org/ Lilypond}.
-    # @note This class is optional and only available if you require 'mtk/helpers/lilypond'.
+    # Uses {Events::Timeline}s to generates music notation graphics with {http://lilypond.org/ Lilypond}.
+    # @note This class is optional and only available if you require 'mtk/io/lilypond'.
     # @note To make notation graphics, {http://lilypond.org/download.html Lilypond} must be installed
     #       and you must follow the "Running on the command-line" instructions (found on the download page for
     #       your operating system). If the lilypond command is not on your PATH, set the environment variable LILYPOND_PATH
-    class Lilypond
+    class Notation
 
       LILYPOND_PATH = ENV['LILYPOND_PATH'] || 'lilypond'
 
@@ -150,7 +150,7 @@ module MTK
 
       def syntax_for_duration(duration)
         # TODO: handle dots, triplets, and ties of arbitrary durations
-        duration = MTK::Timeline.quantize_time(duration.to_f.abs, QUANTIZATION_INTERVAL)
+        duration = MTK::Events::Timeline.quantize_time(duration.to_f.abs, QUANTIZATION_INTERVAL)
         syntax = (4.0/duration).round
         syntax = 1 if syntax < 1
         syntax.to_s

data/lib/mtk/{midi → io}/unimidi_input.rb

@@ -2,12 +2,12 @@ require 'unimidi'
 require 'ostruct'
 
 module MTK
-  module MIDI
+  module IO
 
     # Provides realtime MIDI input for MRI/YARV Ruby via the unimidi gem.
     # @note This class is optional and only available if you require 'mtk/midi/unimidi_input'.
     #       It depends on the 'unimidi' gem.
-    class UniMIDIInput < Input
+    class UniMIDIInput < MIDIInput
 
       public_class_method :new