jmtk 0.0.3.3-java → 0.4-java

data/bin/mtk

@@ -10,38 +10,38 @@ options = {}
 
 option_parser = OptionParser.new do |opts|
 
-  opts.banner = "Usage: #{$0} [options]"
+  opts.banner = "\nMTK: Music Tool Kit for Ruby\n\nUsage: #{$0} [options]"
   opts.separator ''
   opts.separator 'Options:'
 
-   opts.on('-c FILE', '--convert FILE', 'Convert a file containing MTK syntax to MIDI',
-          'if a --file is given, write the MIDI to a file',
-          'if an --output is given, play the MIDI',
+  opts.on('-c FILE', '--convert FILE', 'Convert file containing MTK syntax to MIDI',
+          'if --file is given, write the MIDI to file',
+          'if --output is given, play the MIDI',
           'otherwise print the MIDI') {|file| options[:convert] = file }
 
   opts.separator ''
 
-  opts.on('-e [syntax]', '--eval [syntax]', 'Convert the given MTK syntax String to MIDI',
-          'or start an interactive interpreter when [syntax] is omitted',
-          'Behaves like --convert when a --file or --output is given') {|syntax| options[:eval] = syntax }
+  opts.on('-e [syntax]', '--eval [syntax]', 'Convert the given MTK syntax to MIDI or',
+          'interactive interpreter when no [syntax]',
+          'Behaves like --convert for --file/--output') {|syntax| options[:eval] = syntax }
 
   opts.separator ''
 
-  opts.on('-f FILE', '--file FILE', 'Write the output of --convert, --eval, --input, or --watch to a file'
-         ) {|file| options[:file] = file }
+  opts.on('-f FILE', '--file FILE', 'Write output of --convert, --eval, --input',
+          'or --watch to a file') {|file| options[:file] = file }
 
   opts.separator ''
 
-  opts.on('-h', '--help', 'Show this message') { puts opts; exit }
+  opts.on('-h', '--help', 'Show these usage instructions') { puts opts; exit }
 
   opts.separator ''
 
   opts.on('-i INPUT', '--input INPUT', 'Set MIDI input for recording',
-          'if no --file is specified, prints the recorded MIDI') {|input| options[:input] = input }
+          'if no --file given, prints recorded MIDI') {|input| options[:input] = input }
 
   opts.separator ''
 
-  opts.on('-l', '--list', 'List available MIDI devices for --input and --output') { options[:list] = true }
+  opts.on('-l', '--list', 'List MIDI devices for --input and --output') { options[:list] = true }
 
   opts.separator ''
 
@@ -53,17 +53,19 @@ option_parser = OptionParser.new do |opts|
 
   opts.separator ''
 
-  opts.on('-p FILE', '--play FILE', 'Play or print the contents of a MIDI file',
-          'if no --output is specified, print the MIDI file') {|file| options[:play] = file }
+  opts.on('-p FILE', '--play FILE', 'Play or print a MIDI file',
+          'if no --output given, print the MIDI') {|file| options[:play] = file }
 
   opts.separator ''
 
-  #opts.on('-t', '--tutorial', 'Start an interactive tutorial for the MTK syntax') { options[:tutorial] = true }
-  #
-  #opts.separator ''
+  opts.on('-t [color]', '--tutorial [color]', 'Interactive tutorial for MTK syntax',
+          'Text color can be set on/off') {|color| options[:tutorial] = true; options[:color] = color }
 
-  opts.on('-w FILE', '--watch FILE', 'Watch an MTK syntax file for changes and automatically convert to MIDI',
-          'Behaves like --convert when a --file or --output is given') {|file| options[:watch] = file }
+  opts.separator ''
+
+  opts.on('-w FILE', '--watch FILE', 'Watch an MTK syntax file for changes and',
+          'automatically convert to MIDI',
+          'Behaves like --convert for --file/--output') {|file| options[:watch] = file }
 
 end
 
@@ -71,18 +73,16 @@ end
 #######################################################################
 
 puts option_parser and exit if ARGV.length == 0
-#p ARGV
-#p options
 
 ERROR_INVALID_COMMAND  = 1
 ERROR_FILE_NOT_FOUND   = 2
 ERROR_OUTPUT_NOT_FOUND = 3
 ERROR_INPUT_NOT_FOUND  = 4
 
-# Immediately trying to play output while Ruby is still "warming up" can cause timing issues with
-# the first couple notes. So we play this "empty" Timeline containing a rest to address that issue.
+# Empty timeline used to prime the realtime output
 WARMUP = MTK::Events::Timeline.from_h( {0 => MTK.Note(60,-1)} )
 
+
 #######################################################################
 
 begin
@@ -115,6 +115,9 @@ end
 def output(timelines, print_header='Timeline')
   timelines = [timelines] unless timelines.is_a? Array
   if @output
+    # Immediately trying to play output while Ruby is still "warming up" can cause timing issues with
+    # the first couple notes. So we play this "empty" Timeline containing a rest to address that issue.
+    # TODO? move this into the output class and do it automatically when playing for the first time? (warmup code is also in output_selector))
     @output.play WARMUP
     @output.play timelines.first # TODO: support multiple timelines
   elsif @file
@@ -151,6 +154,33 @@ def watch_file_updated?
 end
 
 
+def set_tutorial_color(color_option)
+  if color_option
+    case color_option.strip.downcase
+      when /^(on|yes|true|y|t|color)$/ then $tutorial_color = true
+      when /^(off|no|false|n|f)$/ then $tutorial_color = false
+      else
+        STDERR.puts "Invalid tutorial color setting '#{color}'. Try 'on' or 'off'."
+        exit ERROR_INVALID_COMMAND
+    end
+  else
+    require 'rbconfig'
+    os = RbConfig::CONFIG['host_os'].downcase
+    if os =~ /win/ and os !~ /darwin/
+      puts
+      puts "Windows command line text color is off by default."
+      puts "If you want color, use ANSI terminal software like Cygwin or Ansicon and "
+      puts "run #{$0} with the color option \"--tutorial on\""
+      $tutorial_color = false
+    else
+      $tutorial_color = true
+    end
+  end
+  puts "Tutorial color is #{if $tutorial_color then 'enabled' else 'disabled' end}."
+  puts
+end
+
+
 #######################################################################
 
 if options[:list]
@@ -162,18 +192,21 @@ if options[:list]
   puts
   puts (['OUTPUTS:']+output_names).join("\n * ")
   puts
-  puts 'When specifying --input INPUT or --output OUTPUT, the first substring match will be used.'
-  puts "For example: --output IAC will use 'Apple Inc. IAC Driver' if it's the first OUTPUT containing 'IAC'"
+  puts 'When specifying --input INPUT or --output OUTPUT, the first substring match'
+  puts '(case-insensitive) will be used. For example: "--output iac" will use'
+  puts '"Apple Inc. IAC Driver" if it\'s the first OUTPUT containing "IAC".'
   puts
   exit
 end
 
+
 @monitor = true if options[:monitor]
 
+
 if options[:input]
   setup_io
   input_name = options[:input]
-  @input = MTK::IO::MIDIInput.find_by_name /#{input_name}/
+  @input = MTK::IO::MIDIInput.find_by_name /#{input_name}/i
   if @input
     puts "Using input '#{@input.name}'"
   else
@@ -182,10 +215,11 @@ if options[:input]
   end
 end
 
+
 if options[:output]
   setup_io
   output_name = options[:output]
-  @output = MTK::IO::MIDIOutput.find_by_name /#{output_name}/
+  @output = MTK::IO::MIDIOutput.find_by_name /#{output_name}/i
   if @output
     puts "Using output '#{@output.name}'"
   else
@@ -194,8 +228,9 @@ if options[:output]
   end
 end
 
-file = options[:file]
-@file = file if file
+
+@file = options[:file]
+
 
 if options[:play]
   filename = options[:play]
@@ -204,6 +239,7 @@ if options[:play]
   output(timelines, "Timeline for #{filename}")
 end
 
+
 if options.has_key? :eval
   mtk_syntax = options[:eval]
   if mtk_syntax.nil?
@@ -221,12 +257,14 @@ if options.has_key? :eval
   end
 end
 
+
 if options[:convert]
   mtk_syntax_file = options[:convert]
   mtk_syntax = IO.read(mtk_syntax_file)
   convert(mtk_syntax)
 end
 
+
 if options[:watch]
   @watch_file = options[:watch]
   puts "Watching #{@watch_file}. Press Ctrl+C to exit."
@@ -243,8 +281,13 @@ if options[:watch]
   end
 end
 
-#if options.has_key? :tutorial
-#  puts "TODO: tutorial"
-#end
+
+if options.has_key? :tutorial
+  set_tutorial_color(options[:color])
+  require 'mtk/lang/tutorial'
+  tutorial = MTK::Lang::Tutorial.new
+  tutorial.run(@output)
+end
+
 
 record if @input

data/examples/drum_pattern.rb

@@ -9,8 +9,8 @@ file = ARGV[0] || "MTK-#{File.basename(__FILE__,'.rb')}.mid"
 _ = nil # defines _ as a rest
 
 pattern = {# 0   1   2   3   4   5   6   7   8   9  10  11  12  13  14  15
-  C2  =>  [fff,  _,  _,  _, mf,  _,  _,  _,  o,  _,  _,  _, mp,  _,  _,  _], # kick
-  Db2 =>  [  _,  _,  o,  _,  _,  _, mp,  _,  _,  _,  o,  _,  _,  _, mf,  _], # rim shot
+  C2  =>  [fff,  _,  _,  _, mf,  _,  _,  _,  f,  _,  _,  _, mp,  _,  _,  _], # kick
+  Db2 =>  [  _,  _,  f,  _,  _,  _, mp,  _,  _,  _,  f,  _,  _,  _, mf,  _], # rim shot
   D2  =>  [  _, mp,  _, mp,  _, mp,  _, mf,  _, mp,  _, mp,  _, pp,  _, mf]  # snare
 }
 

data/examples/dynamic_pattern.rb

@@ -29,7 +29,7 @@ end
 pitches = Patterns.Function( interval_generator, max_elements: 24 )
 
 # we'll also use a weighted choice to generate the intensities
-intensities = Patterns.Choice( mp,mf,o,ff,fff, weights: [1,2,3,2,1], max_cycles: 24 )
+intensities = Patterns.Choice( mp,mf,f,ff,fff, weights: [1,2,3,2,1], max_cycles: 24 )
 
 sequencer = Sequencers.StepSequencer( pitches,intensities, step_size: 0.5, max_interval: 17 )
 

data/examples/helpers/output_selector.rb

@@ -0,0 +1,71 @@
+require 'mtk/io/midi_output'
+
+# Assists with selecting an output.
+class OutputSelector
+
+  # Empty timeline used to prime the realtime output
+  WARMUP = MTK::Events::Timeline.from_h( {0 => MTK.Note(60,-1)} )
+
+  class << self
+
+    def output
+      MTK::IO::MIDIOutput
+    end
+
+    # Look for an output by name using case insensitive matching,
+    # treating underscore like either an underscore or whitespace
+    def search output_name_pattern
+      output.find_by_name(/#{output_name_pattern.to_s.sub '_','(_|\\s+)'}/i)
+    end
+
+    # Command line interface to list output choices and select an output.
+    def prompt_for_output
+      devices_by_name = output.devices_by_name
+      names_by_number = {}
+
+      puts "Available MIDI outputs:"
+      devices_by_name.keys.each_with_index do |name,index|
+        number = index+1
+        names_by_number[number] = name
+        puts " #{number} => #{name}"
+      end
+
+      print "Enter the number of the output to test: "
+      device = nil
+      loop do
+        begin
+          # NOTE: invalid input will turn into 0, but that's ok because we index from 1 so it will be caught as invalid
+          number = STDIN.gets.to_i
+          name = names_by_number[number]
+          device = devices_by_name[name]
+          return output.open(device) if device
+        rescue
+          if $DEBUG
+            puts $!
+            puts $!.backtrace
+          end
+          # keep looping
+        end
+        print "Invalid input. Enter a number listed above: "
+      end
+    end
+
+
+    def ensure_output name=nil
+      output = nil
+      if name
+        output = search name
+        puts "Output '#{name}' not found." unless output
+      end
+      output ||= prompt_for_output
+
+      # Immediately trying to play output while Ruby is still "warming up" can cause timing issues with
+      # the first couple notes. So we play this "empty" Timeline containing a rest to address that issue.
+      output.play WARMUP
+
+      output
+    end
+
+  end
+end
+

data/examples/notation.rb

@@ -1,3 +1,7 @@
+# NOTE: experimental example!
+# This requires Lilypond to be installed, see http://lilypond.org/
+# The lilypond command must be on your PATH or specificed via the LILYPOND_PATH environment variable.
+
 require 'mtk'
 require 'mtk/io/notation'
 include MTK
@@ -13,7 +17,7 @@ arg_error "MTK syntax string not provided" unless syntax
 
 
 file = ARGV[1]
-arg_error "The output_file must end in '.png', '.pdf', or '.ps'" unless file
+arg_error "The output_file must end in '.png', '.pdf', or '.ps'" unless file =~ /\.(png|pdf|ps)$/
 
 
 sequencer = MTK::Lang::Parser.parse(syntax)

data/examples/tone_row_melody.rb

@@ -12,7 +12,7 @@ file = ARGV[0] || 'MTK-tone_row_melody.mid'
 
 row = PitchClassSet Db, G, Ab, F, Eb, E, D, C, B, Gb, A, Bb
 pitch_pattern = Patterns.Cycle *row
-rhythm_pattern = Patterns.Choice s, i, i+s, q # choose between sixteenth, eighth, dotted eighth, and quarter
+rhythm_pattern = Patterns.Choice s, e, e+s, q # choose between sixteenth, eighth, dotted eighth, and quarter
 
 chain = Patterns.Chain pitch_pattern, rhythm_pattern, min_elements: 36, max_elements: 36
 

data/lib/mtk.rb

@@ -56,6 +56,7 @@ require 'mtk/groups/chord'
 
 require 'mtk/events/event'
 require 'mtk/events/note'
+require 'mtk/events/rest'
 require 'mtk/events/parameter'
 require 'mtk/events/timeline'
 

data/lib/mtk/core/duration.rb

@@ -3,18 +3,20 @@ 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.
+    #
+    # @see Lang::Durations
     class Duration
 
       include Comparable
 
       # The names of the base durations. See {MTK::Lang::Durations} for more info.
-      NAMES = %w[w h q i s r x].freeze
+      NAMES = %w[w h q e s r x].freeze
 
       VALUES_BY_NAME = {
         'w' => 4,
         'h' => 2,
         'q' => 1,
-        'i' => Rational(1,2),
+        'e' => Rational(1,2),
         's' => Rational(1,4),
         'r' => Rational(1,8),
         'x' => Rational(1,16)
@@ -55,7 +57,7 @@ module MTK
       # @example lookup the value of 3/4w, which three-quarters of a whole note (3 beats):
       #          MTK::Core::Duration.from_s('3/4w')
       def self.from_s(s)
-        if s =~ /^(-)?(\d+([\.\/]\d+)?)?([whqisrx])((\.|t)*)$/i
+        if s =~ /^(-)?(\d+([\.\/]\d+)?)?([whqesrx])((\.|t)*)$/i
           name = $4.downcase
           modifier = $5.downcase
           modifier << $1 if $1 # negation
@@ -95,6 +97,7 @@ module MTK
       # The magnitude (absolute value) of the duration.
       # This is the actual duration for rests.
       # @see #rest?
+      # @see #abs
       def length
         @value < 0 ? -@value : @value
       end
@@ -106,6 +109,18 @@ module MTK
         @value < 0
       end
 
+      # Force resets to be non-rests, otherwise don't change the duration.
+      # @see #-@
+      # @see #length
+      # @see #rest?
+      def abs
+        if @value < 0
+          -self
+        else
+          self
+        end
+      end
+
       # The number of beats as a floating point number
       def to_f
         @value.to_f

data/lib/mtk/core/intensity.rb

@@ -2,12 +2,14 @@ module MTK
   module Core
 
     # A measure of intensity, using an underlying value in the range 0.0-1.0
+    #
+    # @see Lang::Intensities
     class Intensity
 
       include Comparable
 
-      # The names of the base intensities. See {}MTK::Lang::Intensities} for more info.
-      NAMES = %w[ppp pp p mp mf o ff fff].freeze
+      # The names of the base intensities. See {MTK::Lang::Intensities} for more info.
+      NAMES = %w[ppp pp p mp mf f ff fff].freeze
 
       VALUES_BY_NAME = {
         'ppp' => 0.125,
@@ -15,7 +17,7 @@ module MTK
         'p' => 0.375,
         'mp' => 0.5,
         'mf' => 0.625,
-        'o' => 0.75,
+        'f' => 0.75,
         'ff' => 0.875,
         'fff' => 1.0
       }

data/lib/mtk/core/interval.rb

@@ -2,29 +2,35 @@ module MTK
   module Core
 
     # A measure of intensity, using an underlying value in the range 0.0-1.0
+    #
+    # @see Lang::Intervals
     class Interval
 
       include Comparable
 
       # The preferred names of all pre-defined intervals
+      # @see ALL_NAMES
       NAMES = %w[P1 m2 M2 m3 M3 P4 TT P5 m6 M6 m7 M7 P8].freeze
 
       # All valid names of pre-defined intervals, indexed by their value.
+      # @see ALL_NAMES
+      # @see NAMES
+      # @see http://en.wikipedia.org/wiki/Interval_(music)#Main_intervals
       NAMES_BY_VALUE =
-        [ #   names      # value # description
-          %w( P1 p1 ),   #   0   #  unison
-          %w( m2 min2 ), #   1   #  minor second
-          %w( M2 maj2 ), #   2   #  major second
-          %w( m3 min3 ), #   3   #  minor third
-          %w( M3 maj3 ), #   4   #  major third
-          %w( P4 p4 ),   #   5   #  perfect fourth
-          %w( TT tt ),   #   6   #  tritone (AKA augmented fourth, diminished fifth)
-          %w( P5 p5 ),   #   7   #  perfect fifth
-          %w( m6 min6 ), #   8   #  minor sixth
-          %w( M6 maj6 ), #   9   #  major sixth
-          %w( m7 min7 ), #  10   #  minor seventh
-          %w( M7 maj7 ),  #  11   #  major seventh
-          %w( P8 p8 )    #  12   #  octave
+        [ #   names      # value # description     # enharmonic equivalents
+          %w( P1 d2 ),   #   0   #  unison         #  diminished second
+          %w( m2 a1 ),   #   1   #  minor second   #  augmented unison
+          %w( M2 d3 ),   #   2   #  major second   #  diminished third
+          %w( m3 a2 ),   #   3   #  minor third    #  augmented second
+          %w( M3 d4 ),   #   4   #  major third    #  diminished fourth
+          %w( P4 a3 ),   #   5   #  perfect fourth #  augmented third
+          %w( TT a4 d5 ),#   6   #  tritone        #  augmented fourth, diminished fifth
+          %w( P5 d6 ),   #   7   #  perfect fifth  #  diminished sixth
+          %w( m6 a5 ),   #   8   #  minor sixth    #  augmented fifth
+          %w( M6 d7 ),   #   9   #  major sixth    #  diminished seventh
+          %w( m7 a6 ),   #  10   #  minor seventh  #  augmented sixth
+          %w( M7 d8 ),   #  11   #  major seventh  #  diminished octave
+          %w( P8 a7 )    #  12   #  octave         #  augmented seventh
         ].freeze
 
       # A mapping from intervals names to their value
@@ -35,6 +41,7 @@ module MTK
       ].freeze
 
       # All valid interval names
+      # @see NAMES_BY_VALUE
       ALL_NAMES = NAMES_BY_VALUE.flatten.freeze