jmtk 0.0.3.3-java → 0.4-java

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MjlmMWRmOTljZjQ0MWViNmQ0YzJmNGQ3N2U2NTljOGY3OGE3MTRmMQ==
+  data.tar.gz: !binary |-
+    NDQwMTQ4ZjA4ZWI0YjI2MDY0YzE2ZTQzNDM5ZjA3ZGU5YzQ2ZWMzMQ==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    OThkZmNiZDcxNTM0OWEzZDU1YzRlZTlhODFlYTc1ZGE5OTMwY2EyMjc4ZGFj
+    M2U2ZTEwYzBiNDk0OWI1ZmY1YmM2ZjdjYzViYTZkMDQ5MDU0MTZjYTEzMTdl
+    ZGM5NTZjNmZkMDU4MjdmY2E3NGNhN2YzMTJhM2RmMjEwYWMyMjM=
+  data.tar.gz: !binary |-
+    YmQxODMzMjUwZThjOGQ3OGQ4OGFkMmYzNTE5NGRmNmZiZDhmZjkxNGVmOGZj
+    ZGUyOGM3MTFiNzA5NTYyMWI5ZjM2MzM1MjA1ZmJlMTAyZDM0OTJmZmI2ZTg5
+    NzkzNmM3MWYzNTAzODI0MTU2MmRiM2I1Zjg0YzU1M2RmZTYwYjQ=

data/DEVELOPMENT_NOTES.md

@@ -113,3 +113,23 @@ or, to automatically refresh the documentation as you work:
 
      bundle exec yard server -r
      open http://localhost:8808
+
+
+### Release the gems ###
+
+To better handle the differing depdencies between CRuby and JRuby, there are two gems, mtk and jmtk.
+You can build both gems with:
+
+     bundle exec gem:build
+
+Do a local sanity check by installing
+
+     # Using CRuby 1.9 or 2.0:
+     gem install mtk-0.x.x.gem
+     ... test mtk command ...
+
+     rvm use jruby
+     jgem install jmtk-0.x.x-java.gem
+     ... test jmtk command ...
+
+And then authorized users can push gems to rubygems.org.

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/README.md

@@ -19,20 +19,26 @@ Features
 Getting Started
 ---------------
 
-MTK works with Ruby 1.9, Ruby 2.0, and JRuby
+MTK works with Ruby 1.9, Ruby 2.0, and JRuby 1.7+.
+
+JRuby is recommended for Windows users.
 
 0. Install
 
         gem install mtk
 
-    or if using JRuby:
+    Or for JRuby:
 
-        jgem install mtk
+        jgem install jmtk
 
 0. Learn the command-line interface:
 
         mtk --help
 
+    Or for JRuby:
+
+        jmtk --help
+
 0. Learn the MTK syntax: TODO... documentation forthcoming. In the meantime, see the unit tests @ https://github.com/adamjmurray/mtk/blob/master/spec/mtk/lang/parser_spec.rb
 
 0. Check out examples: https://github.com/adamjmurray/mtk/tree/master/examples

data/Rakefile

@@ -1,14 +1,16 @@
 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 ]
-ENV['JRUBY_OPTS'] = '--1.9'
+
+CLEAN.include('html','doc','coverage.data','coverage', '*.gemspec', '*.gem') # clean and clobber do the same thing for now
 
 task :default => :test
 
-CLEAN.include('html','doc','coverage.data','coverage', '*.gem') # clean and clobber do the same thing for now
 
 desc "Run RSpec tests with full output"
 RSpec::Core::RakeTask.new('test') do |spec|
@@ -18,8 +20,44 @@ RSpec::Core::RakeTask.new('test') do |spec|
     spec.pattern = "spec/**/#{ARGV[1]}*"
   end
 end
+task :spec => :test  # alias test task as spec task
+
+namespace :test do
+  desc "Run RSpec tests with summary output and fast failure"
+  RSpec::Core::RakeTask.new(:fast) do |spec|
+    spec.rspec_opts = ["--color", "--fail-fast"]
+  end
+
+  desc "Run RSpec tests and generate a coverage report"
+  if RUBY_PLATFORM == "java"
+    task :cov do |t|
+      fail "#{t} task is not compatible with JRuby. Use Ruby 1.9 instead."
+    end
+  else
+    RSpec::Core::RakeTask.new(:cov) do |spec|
+      spec.rspec_opts = ["--color", "-r", "#{File.dirname __FILE__}/spec/spec_coverage.rb"]
+    end
+  end
+
+  desc "Profile RSpec tests and report 10 slowest"
+  RSpec::Core::RakeTask.new(:prof) do |spec|
+    spec.rspec_opts = ["--color", "-p"]
+  end
+
+  desc "Run RSpec tests on all supported versions of Ruby: #{SUPPORTED_RUBIES.join ', '}"
+  task :all do
+    fail unless system("rvm #{SUPPORTED_RUBIES.join ','} do bundle exec rake -f #{__FILE__} test:fast")
+  end
+end
+
 
-task :spec => :test
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new(:doc) do |yard|
+    yard.files   = ['lib/**/*.rb']
+  end
+rescue Exception # yard is optional, so don't cause rake to fail if it's missing
+end
 
 
 namespace :gem do
@@ -62,41 +100,3 @@ namespace :gem do
     `rm bin/jmtk`
   end
 end
-
-
-namespace :test do
-  desc "Run RSpec tests with summary output and fast failure"
-  RSpec::Core::RakeTask.new(:fast) do |spec|
-    spec.rspec_opts = ["--color", "--fail-fast"]
-  end
-
-  desc "Run RSpec tests and generate a coverage report"
-  if RUBY_PLATFORM == "java"
-    task :cov do |t|
-      fail "#{t} task is not compatible with JRuby. Use Ruby 1.9 instead."
-    end
-  else
-    RSpec::Core::RakeTask.new(:cov) do |spec|
-      spec.rspec_opts = ["--color", "-r", "#{File.dirname __FILE__}/spec/spec_coverage.rb"]
-    end
-  end
-
-  desc "Profile RSpec tests and report 10 slowest"
-  RSpec::Core::RakeTask.new(:prof) do |spec|
-    spec.rspec_opts = ["--color", "-p"]
-  end
-
-  desc "Run RSpec tests on all supported versions of Ruby: #{SUPPORTED_RUBIES.join ', '}"
-  task :all do
-    fail unless system("rvm #{SUPPORTED_RUBIES.join ','} do bundle exec rake -f #{__FILE__} test:fast")
-  end
-end
-
-
-begin
-  require 'yard'
-  YARD::Rake::YardocTask.new(:doc) do |yard|
-    yard.files   = ['lib/**/*.rb']
-  end
-rescue Exception # yard is optional, so don't cause rake to fail if it's missing
-end

data/bin/jmtk

@@ -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