mtk 0.0.3.3 → 0.4

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZWM0YWVjOGJiYzM4ZjIxOWUxNWVkOWU3MDYyYWU5MDY1ZmUxMmJhOQ==
+  data.tar.gz: !binary |-
+    ZDYwNTg1ZGMyMjMyMzBiMzljZDUyM2RkNDI4MTczMjVmY2FkNTJkMA==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    ZTRlNGRmYmEyZDBjMGRkMDYxM2U0ZGQ3YjQ5NThmZDk3MGRhNTBmYjY3MDBm
+    NzdiMmM0NWE2NDY0YzFkNTM1YTc4MTNhZmY1MGM5MjFiMWY3NWNjYWM0N2Nh
+    ZGYyMThhODA4MGJlOGNiZDIyM2EzYTFhOGY2YjgwOTNlZDNlM2U=
+  data.tar.gz: !binary |-
+    MGNiZGVmOTAyZDM4MmVjOThmOWY0ZjE3NjgwZjRkN2M2NzY0MTRkMzZmNTk1
+    ZjgyMzJkMTNiODAwNzE3Y2M4MDE4MjI3YWY5MWQ1NDc2ZGY0MDlhMzg1MDMz
+    MjJiMjQzNzc4NjgyOTRjNDY0MzRmMjY4YzEyYjcyNTY2M2Q4MWY=

data/INTRO.md

@@ -20,9 +20,12 @@ it does not change the value in-place. For example:
 
 Intensity values are intended to range from 0.0 (minimum intensity) to 1.0 (maximum intensity).
 
-A Duration of 1 is one beat (usually a quarter note, depending on the meter). By convention, negative durations
+A Duration of 1 is one beat (usually a quarter note, depending on the meter, but note the quarter note value in this
+library is 1 beat, so adjust accordingly for non-standard meters). By convention, negative durations
 indicate a rest that lasts for the absolute value duration.
 
+Additionally there is a core type Interval to model intervals between pitches and pitch classes.
+
 
 <br/>
 ### Events
@@ -30,16 +33,23 @@ indicate a rest that lasts for the absolute value duration.
 Events group together the core data types together to represent a musical event, like a single Note.
 Events can be converted to and from MIDI.
 
-* event
-* note
+* Event
+* Note
+* Parameter
 
+Paramter represents any non-note event like a MIDI CC, pitch bend, aftertouch (pressure), etc.
 
-<br/>
-### Core collections
+Events with a negative duration are considered a rest. There is also a dedicated rest class so you
+don't have to specifiy unnecessary properties like pitch for a rest.
+
+Events are organized in time via the Timeline
 
-A collection of timed events, such as a melody, a riff, or one track of an entire song.
 
-* timeline
+<br/>
+### Collections
+
+The collection classes need some work... The interface is likely to change so it's best to not rely on them too much
+right now.
 
 
 <br/>
@@ -53,7 +63,7 @@ Structured collections of core data types and other patterns. Used to generate m
 * line (linear interpolation between 2 points)
 * function (dynamically generate elements with a lambda)
 
-Future?
+To be added in the Future?
 * curve (exponential/curved interpolation between points)
 * permutation (cycle that permutes itself each cycle period)
 * markov chain
@@ -65,7 +75,23 @@ Future?
 <br/>
 ### Sequencers
 
-Convert patterns into timelines
+Convert patterns into event Timelines
+
+The sequencer classes differ in terms of how they determine how much time should occur between one event and the next.
+So far the options are:
+* LegatoSequencer - the end of each event is the start of the next event
+* RhythmSequencer - requires a special rhythm-type patter to determine the inter-event time intervals
+* StepSequencer - uses a constant amount of time between all events. In other words, works like a drum sequencer/
+
+
+<br/>
+### Creating object conveniently
+
+The Core types as well as Patterns and Note events have "convenience constructors" under the top-level MTK module.
+
+You can construct objects from almost any arguments by using the methods such as MTK.Pitch() and MTK.Note().
+These methods do their best to guess what you want from the arguments and even handle out-of-order arguments
+in most cases. See the unit tests for ideas...
 
 
 <br/>
@@ -74,56 +100,62 @@ Convert patterns into timelines
 Basic Tenants
 
 * Minimal syntax: less typing means more music!
-* Be case-insensitive to avoid typos caused by lower vs upper case (there's one notable exception for intervals: m2 vs M2)
-* pitch and duration are the most important properties
-* pitch is more important than rhythm
+* Case-sensitive to allow for more to be expressed in fewer characters.
+* Pitch and duration are the most important properties
 
 Because pitch class and duration are such important properties, and we want to minimize typing, we represent these with 1 letter.
 
-**Diatonic Pitch Class: c d e f g a b**
+**Diatonic Pitch Class: C D E F G A B**
 
-**Chromatic Pitch Class (Sharp/Flat): c c# db d d# eb e e# fb f f# gb g g# ab a a# bb b b#**
+**Chromatic Pitch Class (Sharp/Flat): C/B# C#/Db D D#/Eb E/Fb E#/F F#/Gb G G#/Ab A A#/Bb B/Cb**
 
-Double-sharps (c##) and double-flats (dbb) are also allowed. You may prefer Bb to bb, etc
+Double-sharps (C##) and double-flats (Dbb) are also allowed.
 
-**Pitch (Pitch Class + Octave Number): c4 db5 c-1 g9**
+**Pitch (Pitch Class + Octave Number): C4 Db5 C-1 G9**
 
-c-1 (that's octave number: negative 1) is the lowest note. g9 is the highest.
+C-1 (that's octave number: negative 1) is the lowest note. G9 is the highest.
+Note: The MTK syntax expects C-1 as you'd expect, but the corresponding constant in Ruby is C_1 to ensure valid Ruby syntax.
 
-**Duration: w h q i s r x (that's: whole note, half, quarter, eighth, sixteenth, thirty-second, sixty-fourth)**
+**Duration: w h q e s r x (that's: whole note, half, quarter, eighth, sixteenth, thirty-second, sixty-fourth)**
 
-Why "i", "r", and "x"? We're trying to keep these one letter. 'e', 'r', and 's' were already used,
-so we just move along the letters of the word until we find an unused letter.
+In the MTK syntax, durations can be suffixed with "t" or "." for triplets and dotted-notes
+(mathematically that multiplies the dureation by 2/3 or 1.5).
 
-For intensity, we'll try to use standard music notation, but 'f' conflicts, so we handle this the same way we did with durations:
+Why "r", and "x"? We're trying to keep these one letter.
+"t" is used for triplets, so the thirty-second note became "r".
+"s" is used by sixteenth notes, so the sixty-fourth note became "x".
+Hopefully this abnormal naming won't cause problems since those duration values are fairly uncommon.
 
-**Intensity: ppp pp p mp mf o ff fff**
 
-(You may find it helpful to think "loud" for "o")
+**Intensity: ppp pp p mp mf f ff fff**
 
 
 TODO: keep documenting this...
+TODO: explanation of intervals
 
 
 Summary of single-letter assignments:
 ```
-a -> pitch class a
-b -> pitch class b, flat modifier on pitch class
-c -> pitch class c
-d -> pitch class d
-e -> pitch class e
-f -> pitch class f
+A -> pitch class A
+B -> pitch class B
+b -> flat modifier on pitch class
+D -> pitch class c
+D -> pitch class d
+E -> pitch class e
+e -> eighth note duration
+F -> pitch class f
+f -> forte intensity
 
 h -> half note duration
-i -> eighth note duration
+i -> minor tonic chord (PLANNED, not implemented yet)
 
-o -> forte intensity
 p -> piano intensity
 q -> quarter note duration
 r -> thirty-second note duration
 s -> sixteenth note duration
 t -> triplet modifier on durations
 
+v -> minor dominant chord (PLANNED, not implemented yet)
 w -> whole note duration
 x -> sixty-fourth note duration
 ```

data/Rakefile

@@ -1,7 +1,9 @@
 require 'rspec/core/rake_task'
 require 'rake/clean'
+require 'erb'
 
-GEM_VERSION = '0.0.3.3'
+
+GEM_VERSION = '0.4'
 
 SUPPORTED_RUBIES = %w[ 1.9.3  2.0  jruby-1.7.4 ]
 

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
+