jmtk 0.0.3.3-java

data/.yardopts

@@ -0,0 +1,10 @@
+--readme README.md
+--title 'MTK (Music Tool Kit for Ruby)'
+--charset utf-8
+--protected
+--no-private
+lib/**/*.rb
+- INTRO.md
+- lib/**/*.citrus
+- LICENSE.txt
+- examples/**/*.rb

data/DEVELOPMENT_NOTES.md

@@ -0,0 +1,115 @@
+MTK
+===
+
+[![Build Status](https://secure.travis-ci.org/adamjmurray/mtk.png)](http://travis-ci.org/adamjmurray/mtk)
+
+Music Tool Kit for Ruby
+-----------------------
+
+Classes for modeling music with a focus on simplicity. Support for reading/writing MIDI files and realtime MIDI.
+
+
+
+Getting Started
+---------------
+
+    gem install mtk
+
+or download the source from here and add mtk/lib to your $LOAD_PATH. Then...
+
+    require 'mtk'
+
+Some examples are available in the examples folder (more coming soon).
+The specs provide a lot of details of usage...
+
+
+
+Goals
+-----
+
+* Build musical generators to assist with composing music
+* Re-implement Cosy (http://compusition.com/web/software/cosy) using these models as the "backend"
+
+
+
+Status
+------
+
+Alpha phase, API subject to change. Feedback welcome!
+
+
+
+Requirements
+------------
+
+### Ruby Version
+
+Ruby 1.9+ or JRuby 1.6+
+
+
+### Dependencies
+
+MTK's core features should not depend on anything outside of the Ruby standard library.
+
+
+MTK's optional features typically require gems. Currently the following gems are required:
+
+* MIDI file I/O requires the __midilib__ gem
+
+* realtime MIDI I/O with (MRI/YARV) Ruby requires the __unimidi__ and __gamelan__ gems
+
+* realtime MIDI I/O with JRuby require the __jsound__ and __gamelan__ gems
+
+* The custom MTK syntax (work in progress) requires the __citrus__ gem
+
+
+Development requires the gems for optional features, plus the following:
+
+* rake
+* rspec (tests)
+* yard (docs)
+
+You shouldn't need to worry about the dependencies too much. A Gemfile is provided to sort this out for you:
+
+    gem install bundler
+    bundle install
+
+[rvm](https://rvm.beginrescueend.com/) is required for cross version testing (see Development Notes below)
+
+
+
+Documentation
+-------------
+
+Generate with:
+
+     bundle exec rake doc
+
+Or view online @ http://rubydoc.info/github/adamjmurray/mtk/master/frames
+
+
+Development Notes
+-----------------
+
+### Run Tests ###
+
+Test with current version of Ruby:
+
+     bundle exec rake test
+
+Test with all supported versions of Ruby (requires [rvm](https://rvm.beginrescueend.com/), YARV 1.9.3, and JRuby 1.6.7):
+
+     bundle exec rake test:all
+
+The test:all test must pass for a pull request to be accepted or for a release of the mtk gem.
+
+
+### Generate Docs ###
+
+     bundle exec rake doc
+     open doc/frames.html
+
+or, to automatically refresh the documentation as you work:
+
+     bundle exec yard server -r
+     open http://localhost:8808

data/INTRO.md

@@ -0,0 +1,129 @@
+(Work in progress)
+
+Core Concepts
+-------------
+
+### Core data types
+
+These model the basic properties of musical events:
+* PitchClass
+* Pitch
+* Duration
+* Intensity
+
+These types are all immutable. This helps avoid confusing bugs.
+Mostly you don't need to worry about this. Just remember when you call methods that change the value, like #invert,
+it does not change the value in-place. For example:
+
+     p = PitchClass[G]
+     p = p.invert(E)  # because p.invert(E) does not change p
+
+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
+indicate a rest that lasts for the absolute value duration.
+
+
+<br/>
+### Events
+
+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
+
+
+<br/>
+### Core collections
+
+A collection of timed events, such as a melody, a riff, or one track of an entire song.
+
+* timeline
+
+
+<br/>
+### Patterns
+
+Structured collections of core data types and other patterns. Used to generate musical material.
+
+* cycle
+* palindrome
+* choice (randomly select from weghted distribution)
+* line (linear interpolation between 2 points)
+* function (dynamically generate elements with a lambda)
+
+Future?
+* curve (exponential/curved interpolation between points)
+* permutation (cycle that permutes itself each cycle period)
+* markov chain
+* graph
+* petri net (special type of graph??)
+* custom (just implement enumerator pattern?)
+
+
+<br/>
+### Sequencers
+
+Convert patterns into timelines
+
+
+<br/>
+### Syntax
+
+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
+
+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**
+
+**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#**
+
+Double-sharps (c##) and double-flats (dbb) are also allowed. You may prefer Bb to bb, etc
+
+**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.
+
+**Duration: w h q i 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.
+
+For intensity, we'll try to use standard music notation, but 'f' conflicts, so we handle this the same way we did with durations:
+
+**Intensity: ppp pp p mp mf o ff fff**
+
+(You may find it helpful to think "loud" for "o")
+
+
+TODO: keep documenting this...
+
+
+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
+
+h -> half note duration
+i -> eighth note duration
+
+o -> forte intensity
+p -> piano intensity
+q -> quarter note duration
+r -> thirty-second note duration
+s -> sixteenth note duration
+t -> triplet modifier on durations
+
+w -> whole note duration
+x -> sixty-fourth note duration
+```

data/LICENSE.txt

@@ -0,0 +1,27 @@
+Copyright (c) 2011-2013, Adam Murray (adam@compusition.com).
+
+All rights reserved.
+
+Redistribution and use of the "MTK" Ruby library, in source and binary forms,
+with or without modification, are permitted provided that the following
+conditions are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in
+   the documentation and/or other materials provided with the
+   distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
+OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,50 @@
+MTK: a Music Tool Kit for Ruby
+===
+
+MTK is a Ruby library and custom [domain-specific language](https://en.wikipedia.org/wiki/Domain-specific_language) (DSL) for generating musical material.
+
+MTK is flexible: You may use the custom music-generating language without writing any Ruby code, or you may avoid the custom language
+ and only program in Ruby, or anywhere in between.
+
+
+Features
+--------
+* A minimalist syntax (DSL) for generating musical patterns
+* Read and write MIDI files
+* Record and output realtime MIDI signals
+* Sequence MIDI-compatible event streams
+* Manipulate musical objects like pitch, duration, and intensity
+* Generate deterministic and non-deterministic music via flexible patterns such as looping sequences and random choices
+
+Getting Started
+---------------
+
+MTK works with Ruby 1.9, Ruby 2.0, and JRuby
+
+0. Install
+
+        gem install mtk
+
+    or if using JRuby:
+
+        jgem install mtk
+
+0. Learn the command-line interface:
+
+        mtk --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
+
+0. Read the [MTK Ruby library documentation](http://rubydoc.info/github/adamjmurray/mtk/master/frames)
+
+
+About this project
+------------------
+This project is developed by [Adam Murray (github.com/adamjmurray)](http://github.com/adamjmurray).
+
+It is a free and open source project licensed under [a permissive BSD-style license](https://raw.github.com/adamjmurray/mtk/master/LICENSE.txt).
+I simply ask for credit by including my copyright in derivative works.
+
+You can learn more about the development of this project at the [development notes page](https://github.com/adamjmurray/mtk/blob/master/DEVELOPMENT_NOTES.md).

data/Rakefile

@@ -0,0 +1,102 @@
+require 'rspec/core/rake_task'
+require 'rake/clean'
+
+GEM_VERSION = '0.0.3.3'
+
+SUPPORTED_RUBIES = %w[ 1.9.3  2.0  jruby-1.7.4 ]
+ENV['JRUBY_OPTS'] = '--1.9'
+
+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|
+  spec.rspec_opts = ["--color", "--format", "nested"]
+  if ARGV[1]
+    # only run specs with filenames starting with the command line argument
+    spec.pattern = "spec/**/#{ARGV[1]}*"
+  end
+end
+
+task :spec => :test
+
+
+namespace :gem do
+  desc "Install gems for supported versions of Ruby: #{SUPPORTED_RUBIES.join ', '}"
+  task :install_dependencies do
+    fail unless system("rvm #{SUPPORTED_RUBIES.join ','} do bundle install")
+  end
+
+  desc "Build the CRuby and JRuby gems for distribution"
+  task :build do
+    gem_version = GEM_VERSION
+
+    gem_name = 'mtk'
+    platform_specific_depedencies = {unimidi:'~> 0.3'}
+    additional_gem_specifications = {}
+    generate_gemspec(binding)
+
+    gem_name = 'jmtk'
+    platform_specific_depedencies = {jsound:'~> 0.1'}
+    additional_gem_specifications = {platform:'java'}
+    generate_gemspec(binding)
+  end
+
+  def generate_gemspec(erb_bindings)
+    gem_name = erb_bindings.eval('gem_name')
+
+    erb = ERB.new(IO.read 'mtk.gemspec.erb')
+    gemspec = erb.result(erb_bindings)
+
+    gemspec_filename = "#{gem_name}.gemspec"
+    puts "Generating #{gemspec_filename}"
+    IO.write(gemspec_filename, gemspec)
+
+    if gem_name == 'jmtk'
+      `cp bin/mtk bin/jmtk` # jmtk gem uses this as the binary
+    end
+    puts "Building gem"
+    puts `gem build #{gemspec_filename}`
+  ensure
+    `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

@@ -0,0 +1,250 @@
+#!/usr/bin/env ruby
+
+require 'mtk'
+require 'optparse'
+
+options = {}
+
+
+#######################################################################
+
+option_parser = OptionParser.new do |opts|
+
+  opts.banner = "Usage: #{$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',
+          '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.separator ''
+
+  opts.on('-f FILE', '--file FILE', 'Write the 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.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 }
+
+  opts.separator ''
+
+  opts.on('-l', '--list', 'List available MIDI devices for --input and --output') { options[:list] = true }
+
+  opts.separator ''
+
+  opts.on('-m', '--monitor', 'Monitor MIDI input while recording') { options[:monitor] = true }
+
+  opts.separator ''
+
+  opts.on('-o OUTPUT', '--output OUTPUT', 'Set MIDI output for playing') {|output| options[:output] = output }
+
+  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.separator ''
+
+  #opts.on('-t', '--tutorial', 'Start an interactive tutorial for the MTK syntax') { options[:tutorial] = true }
+  #
+  #opts.separator ''
+
+  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 }
+
+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.
+WARMUP = MTK::Events::Timeline.from_h( {0 => MTK.Note(60,-1)} )
+
+#######################################################################
+
+begin
+  option_parser.parse!
+rescue OptionParser::MissingArgument, OptionParser::InvalidOption
+  puts "Invalid command, #{$!}"
+  puts "For command line help: #{$0} --help"
+  puts "For command line help: #{$0} --help"
+  exit ERROR_INVALID_COMMAND
+end
+
+
+def setup_io
+  require 'mtk/io/midi_input'
+  require 'mtk/io/midi_output'
+end
+
+
+def convert(mtk_syntax)
+  sequencer = MTK::Lang::Parser.parse(mtk_syntax)
+  if sequencer
+    timeline = sequencer.to_timeline
+    output(timeline)
+  end
+rescue Citrus::ParseError
+  STDERR.puts $!
+end
+
+
+def output(timelines, print_header='Timeline')
+  timelines = [timelines] unless timelines.is_a? Array
+  if @output
+    @output.play WARMUP
+    @output.play timelines.first # TODO: support multiple timelines
+  elsif @file
+    require 'mtk/io/midi_file'
+    MTK.MIDIFile(@file).write timelines
+  else
+    puts print_header, timelines
+    puts
+  end
+end
+
+
+def record
+  if @input
+    print "Press Enter to begin recording MIDI input..."
+    gets
+    puts "Recording input. Press control-C to stop."
+    @input.record monitor:@monitor
+    Signal.trap("INT") do # SIGINT = control-C
+      @input.stop
+      output @input.to_timeline, "\nRecorded MIDI data"
+      exit
+    end
+    loop{ sleep 0.01 }
+  end
+end
+
+
+def watch_file_updated?
+  mtime = File.stat(@watch_file).mtime
+  updated = @watch_file_mtime.nil? || @watch_file_mtime < mtime
+  @watch_file_mtime = mtime
+  updated
+end
+
+
+#######################################################################
+
+if options[:list]
+  setup_io
+  input_names  = MTK::IO::MIDIInput.devices_by_name.keys
+  output_names = MTK::IO::MIDIOutput.devices_by_name.keys
+  puts
+  puts (['INPUTS:'] + input_names).join("\n * ")
+  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
+  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}/
+  if @input
+    puts "Using input '#{@input.name}'"
+  else
+    STDERR.puts "Input '#{input_name}' not found."
+    exit ERROR_INPUT_NOT_FOUND
+  end
+end
+
+if options[:output]
+  setup_io
+  output_name = options[:output]
+  @output = MTK::IO::MIDIOutput.find_by_name /#{output_name}/
+  if @output
+    puts "Using output '#{@output.name}'"
+  else
+    STDERR.puts "Output '#{output_name}' not found."
+    exit ERROR_OUTPUT_NOT_FOUND
+  end
+end
+
+file = options[:file]
+@file = file if file
+
+if options[:play]
+  filename = options[:play]
+  require 'mtk/io/midi_file'
+  timelines = MTK.MIDIFile(filename).to_timelines
+  output(timelines, "Timeline for #{filename}")
+end
+
+if options.has_key? :eval
+  mtk_syntax = options[:eval]
+  if mtk_syntax.nil?
+    puts "Starting the interactive interpreter."
+    begin
+      loop do
+        puts "Enter MTK syntax. Press Ctrl+C to exit."
+        convert(gets)
+      end
+    rescue SystemExit,Interrupt
+      Kernel.exit
+    end
+  else
+    convert(mtk_syntax)
+  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."
+  watch_file_updated? # prime the watcher
+  begin
+    loop do
+      mtk_syntax = IO.read(@watch_file)
+      convert(mtk_syntax)
+      Kernel.sleep(0.5) until watch_file_updated?
+      puts "#{Time.new}: #{@watch_file} updated"
+    end
+  rescue SystemExit,Interrupt
+    Kernel.exit
+  end
+end
+
+#if options.has_key? :tutorial
+#  puts "TODO: tutorial"
+#end
+
+record if @input