jmtk 0.0.3.3-java → 0.4-java

data/lib/mtk/lang/tutorial.rb

@@ -0,0 +1,279 @@
+# encoding: UTF-8
+
+require 'mtk/io/midi_output'
+require 'mtk/lang/tutorial_lesson'
+
+module MTK
+  module Lang
+
+    # @private
+    class Tutorial
+
+      def initialize
+        @current_lesson_index = 0
+
+        @lessons = [
+              ###################### 79 character width for description #####################
+          {
+            title: 'Pitch Classes (diatonic)',
+            description: "
+              The diatonic pitch classes are the 7 white keys on a piano in a given octave.
+              They can be used to play, for example, the C major or A natural minor scales.
+
+              To play a diatonic pitch class, enter #{'one'.bold.underline} of the following letters
+              (must be upper-case):
+
+              C D E F G A B
+              ",
+            validation: :diatonic_pitch_class,
+          },
+          {
+            title: 'Pitch Classes (chromatic)',
+            description: "
+              The chromatic pitch classes are the 12 white or black keys on a piano in a
+              given octave. They form the basis of all 'western' music theory.
+
+              To play a chromatic pitch class, enter any of the 7 diatonic pitch classes
+              immediately followed by 0, 1, or 2 flats (b) or sharps (#). Each flat (b)
+              lowers the pitch by a half step and each sharp (#) raises by a half step.
+
+              Here are some examples, try entering #{'one'.bold.underline} of the following:
+
+              C# Bb A## Ebb F
+              ",
+            validation: :pitch_class,
+          },
+          {
+            title: 'Pitches',
+            description: "
+              To play a pitch, enter a (chromatic) pitch class immediately following by an
+              octave number.
+
+              There is no universal standard numbering scheme for octaves in music.
+              This library uses \"scientific pitch notation\", which defines
+              C4 as \"Middle C\" and A4 as the standard tuning pitch A440.
+
+              In this library, C-1 is the lowest note available and G9 is the highest,
+              corresponding to MIDI pitch values 0 and 127. If you try to play a pitch
+              outside this range, it will be mapped to the closest available pitch.
+
+              Here are some examples, try entering #{'one'.bold.underline} of the following:
+
+              G3 Eb4 F#5 B-1 C##9 Dbb6
+              ",
+            validation: :pitch,
+          },
+          {
+            title: 'Sequences',
+            description: "
+              To play a sequence of pitches or pitch classes, enter them with spaces in
+              between. Pitches and pitch classes may be interchanged in a given sequence.
+              Any pitch class will output a pitch closest to the previous pitch (starting
+              from C4 at the beginning of the sequence).
+
+              Here is an example (Note, unlike previous lessons, enter the #{'entire line'.bold.underline}):
+
+              C5 C G5 G A A G
+              ",
+            validation: :bare_sequence,
+          },
+          {
+            title: 'Repetition',
+            description: "
+              To repeat a note, suffix a pitch or pitch class with *N, where N is the
+              number of repetitions. You can also wrap a subsequence of notes with
+              parentheses and repeat them. Here is an example sequence with repetition:
+
+              C*3 D (E D)*2 C
+
+              You can also nest repetitions (optional whitespace added for readability):
+
+              ( C5 (E G)*2 )*2
+              ",
+            validation: /\*/,
+          },
+
+        ].map{|lesson_options| TutorialLesson.new(lesson_options) }
+      end
+
+
+      def run(output)
+        puts SEPARATOR
+        puts
+        puts "Welcome to the MTK syntax tutorial!".bold.yellow
+        puts
+        puts "MTK is the Music Tool Kit for Ruby, which includes a custom syntax for"
+        puts "generating musical patterns. This tutorial has a variety of lessons to teach"
+        puts "you the syntax. It assumes basic familiarity with music theory."
+        puts
+        puts "Make sure your speakers are on and the volume is turned up."
+        puts
+        puts "This is a work in progress. Check back in future versions for more lessons."
+        puts
+        puts "#{'NOTE:'.bold} MTK syntax is case-sensitive. Upper vs lower-case matters."
+        puts
+
+        output = ensure_output(output)
+        loop{ select_lesson.run(output) }
+
+      rescue SystemExit, Interrupt
+        puts
+        puts
+        puts "Goodbye!"
+        puts
+      end
+
+
+      # table of contents
+      def toc
+        @lessons.map.with_index do |lesson,index|
+          "#{'> '.bold.yellow if @current_lesson_index == index}#{index+1}: #{lesson}"
+        end.join("\n")
+      end
+
+
+      def select_lesson
+        puts
+        puts SEPARATOR
+        puts
+        puts "Lessons".bold.yellow
+        puts
+
+        all_done = @current_lesson_index >= @lessons.length
+        lesson = nil
+        while lesson == nil
+          puts toc
+          puts
+          if all_done
+            puts "You've completed the last lesson!"
+            puts "To explore more, try running #{$0} with the --eval option."
+            puts
+          end
+          puts "Press Ctrl+C to exit at any time.".bold
+          puts
+          print "Select a lesson number, or press enter to ".blue
+          if all_done
+            puts "exit:".blue
+          else
+            puts "go to the next one ".blue + "(indicated by " + '>'.bold.yellow + "):"
+          end
+
+          input = gets.strip
+          lesson_index = case input
+            when /^\d+$/
+              input.to_i - 1
+            when ''
+              if all_done then raise SystemExit.new else @current_lesson_index end
+            else
+              nil
+          end
+
+          lesson = @lessons[lesson_index] if lesson_index and lesson_index >= 0
+
+          puts "Invalid lesson number: #{input}\n\n" if lesson.nil?
+        end
+
+        @current_lesson_index = lesson_index + 1
+        lesson
+      end
+
+
+      #####################################################
+      private
+
+      def ensure_output(output)
+        unless output
+          puts SEPARATOR
+          puts
+          puts "Select an output".bold.yellow
+          puts
+          puts "You need to select a MIDI output device before you can hear sound."
+          puts
+
+          require 'rbconfig'
+          case RbConfig::CONFIG['host_os'].downcase
+            when /darwin/
+              puts "You appear to be on OS X."
+              puts "You can use the \"Apple DLS Synthesizer\" to hear sound with no extra setup."
+              puts "It's recommended you use this unless you have a good reason to do otherwise."
+            when /win/
+              puts "You appear to be on Windows"
+              puts "You can use the \"Microsoft Synthesizer\" to hear sound with no extra setup."
+              puts "It's recommended you use this unless you have a good reason to do otherwise."
+          end
+
+          until output
+            puts
+            puts "Available MIDI outputs:".bold.yellow
+            MTK::IO::MIDIOutput.devices.each.with_index do |device,index|
+              name = device.name
+              name += " (#{device.id})" if device.respond_to? :id
+              puts "#{index+1}: #{name}"
+            end
+
+            puts "Select an output number:".blue
+
+            input = STDIN.gets.strip
+            if input =~ /^\d+$/
+              number = input.to_i
+              if number > 0
+                device = MTK::IO::MIDIOutput.devices[number-1]
+                output = MTK::IO::MIDIOutput.open(device) if device
+              end
+            end
+
+            puts "Invalid selection.".red unless device
+          end
+
+          puts
+          puts "OK! Using output '#{output.name}'".bold.green
+          puts "#{'NOTE:'.bold} You can skip the output selection step in the future by running "
+          puts "#{$0} with the --output option."
+          puts "Press enter to continue".blue
+          gets
+        end
+        output
+      end
+
+    end
+  end
+end
+
+
+####################################################################################################
+# Patch String to support terminal colors
+
+# @private
+class String
+  {
+    bold: 1,
+    underline: 4,
+    red: 31,
+    green: 32,
+    yellow: 33,
+    blue: 36 # really this cyan but the standard blue is too dark IMO
+  }.each do |effect,code|
+    if $tutorial_color
+      define_method effect do
+        "\e[#{code}m#{self}\e[0m"
+      end
+    else
+      define_method effect do
+        self
+      end
+    end
+  end
+
+end
+
+
+####################################################################################################
+# And now that we've got some colors we can define colored constants
+module MTK
+  module Lang
+    # @private
+    class Tutorial
+      SEPARATOR = "===============================================================================".bold.yellow
+    end
+  end
+end

data/lib/mtk/lang/tutorial_lesson.rb

@@ -0,0 +1,87 @@
+module MTK
+  module Lang
+
+    # @private
+    class TutorialLesson
+
+      # Every TutorialLesson requires the options at construction title:
+      #   title - The short summary displayed in the tutorial's table of contents.
+      #   description - The full description displayed when entering the tutorial step.
+      #   validate(input) - Validate user input entered after the description is displayed.
+      #   success(input) - Perform an action on successful validation
+      #   failure(input) - Instruct the user on failed validation
+      def initialize options
+        @title = options[:title]
+        @description = options[:description].split("\n").map{|line| line.strip }.join("\n") # trim extra whitespace
+        @validation = options[:validation]
+      end
+
+
+      def run(output)
+        puts
+        puts Tutorial::SEPARATOR
+        puts
+        puts "Lesson: #{@title}".bold.yellow
+        puts @description
+        puts
+        print "Try it now: ".blue
+
+        did_it_once = false
+        input = gets.strip
+        until did_it_once and input.empty?
+          until validate(input)
+            failure(input)
+            print "Try again: ".blue
+            input = gets.strip
+          end
+
+          success(input, output)
+          did_it_once = true
+          puts
+          puts "Good! ".bold.green + "Try again, or press enter to exit this lesson:".blue
+          input = gets.strip
+        end
+      end
+
+
+      def validate(input)
+        return false if input.empty?
+
+        case @validation
+          when Symbol
+            MTK::Lang::Parser.parse(input, @validation)
+            true
+          else # Assume Regexp
+            (input =~ @validation) != nil and MTK::Lang::Parser.parse(input)
+        end
+      rescue Citrus::ParseError
+        false
+      end
+
+
+      def success(input, output)
+        sequencer = MTK::Lang::Parser.parse(input)
+        if sequencer
+          output.play sequencer.to_timeline
+        else
+          STDERR.puts "Nothing to play for \"#{input}\""
+        end
+      rescue Citrus::ParseError
+        STDERR.puts $!
+      end
+
+
+      def failure(input)
+        puts
+        puts "Invalid entry \"#{input}\"".bold.red
+      end
+
+
+      def to_s
+        @title
+      end
+
+    end
+
+  end
+end

data/lib/mtk/sequencers/event_builder.rb

@@ -29,15 +29,31 @@ module MTK
         @patterns.each do |pattern|
           pattern_value = pattern.next
 
-          elements = pattern_value.is_a?(Enumerable) ? pattern_value : [pattern_value]
+          elements = if pattern_value.is_a? Enumerable and not pattern_value.is_a? MTK::Groups::PitchCollection then
+            pattern_value
+          else
+            [pattern_value]
+          end
+
           elements.each do |element|
             return nil if element.nil? or element == :skip
 
             case element
-              when ::MTK::Core::Pitch         then pitches << element
-              when ::MTK::Core::PitchClass    then pitches += pitches_for_pitch_classes([element], @previous_pitch)
-              when ::MTK::Groups::PitchClassSet then pitches += pitches_for_pitch_classes(element, @previous_pitch)
-              when ::MTK::Groups::PitchCollection then pitches += element.pitches # this must be after the PitchClassSet case, because that is also a PitchCollection
+              when ::MTK::Core::Pitch
+                pitches << element
+                @previous_pitch = element
+
+              when ::MTK::Core::PitchClass
+                pitches += pitches_for_pitch_classes([element], @previous_pitch)
+                @previous_pitch = pitches.last
+
+              when ::MTK::Groups::PitchClassSet
+                pitches += pitches_for_pitch_classes(element, @previous_pitch)
+                @previous_pitch = pitches.last
+
+              when ::MTK::Groups::PitchCollection
+                pitches += element.pitches # this must be after the PitchClassSet case, because that is also a PitchCollection
+                @previous_pitch = pitches.last
 
               when ::MTK::Core::Duration
                 duration ||= 0
@@ -52,6 +68,7 @@ module MTK
                 else
                   pitches << (@previous_pitch + element)
                 end
+                @previous_pitch = pitches.last
 
               # TODO? String/Symbols for special behaviors like :skip, or :break (something like StopIteration for the current Pattern?)
 
@@ -62,7 +79,7 @@ module MTK
         end
 
         pitches     << @previous_pitch if pitches.empty?
-        duration   ||= @previous_duration
+        duration   ||= @previous_duration.abs
 
         if intensities.empty?
           intensity = @previous_intensity
@@ -80,7 +97,11 @@ module MTK
         @previous_intensity = intensity
         @previous_duration = duration
 
-        pitches.map{|pitch| MTK::Events::Note.new(pitch,duration,intensity,@channel) }
+        if duration.rest?
+          [MTK::Events::Rest.new(duration,@channel)]
+        else
+          pitches.map{|pitch| MTK::Events::Note.new(pitch,duration,intensity,@channel) }
+        end
       end
 
       # Reset the EventBuilder to its initial state
@@ -98,7 +119,7 @@ module MTK
       private
 
       def pitches_for_pitch_classes(pitch_classes, previous_pitch)
-        pitch_classes.map{|pitch_class| previous_pitch.nearest(pitch_class) }
+        pitch_classes.to_a.map{|pitch_class| previous_pitch.nearest(pitch_class) }
       end
 
       def constrain_pitch(pitches)

data/spec/mtk/core/duration_spec.rb

@@ -8,7 +8,7 @@ describe MTK::Core::Duration do
 
   describe 'NAMES' do
     it "is the list of base duration names available" do
-      Duration::NAMES.should =~ %w( w h q i s r x )
+      Duration::NAMES.should =~ %w( w h q e s r x )
     end
 
     it "is immutable" do
@@ -176,6 +176,19 @@ describe MTK::Core::Duration do
   end
 
 
+  describe '#abs' do
+    it 'returns the Duration is the value is positive' do
+      d = MTK.Duration(2)
+      d.abs.should be d
+    end
+
+    it 'returns the negation of the Duration is the value is negative' do
+      d = MTK.Duration(-2)
+      d.abs.should == -d
+    end
+  end
+
+
   describe '#to_f' do
     it "is the value as a floating point number" do
       f = Duration.new(Rational(1,2)).to_f