mtk 0.0.1 → 0.0.2

data/.yardopts

@@ -0,0 +1,9 @@
+--readme README.md
+--title 'MTK (Music ToolKit for Ruby)'
+--charset utf-8
+--protected
+lib/**/*.rb
+- *.md
+- examples/*
+- lib/**/*.citrus
+

data/INTRO.md

@@ -0,0 +1,73 @@
+(Work in progress)
+
+Core Concepts
+-------------
+
+### Core data types
+
+These model the basic properties of musical events:
+* pitch_class (MTK class)
+* pitch (MTK class)
+* intensity (Numeric)
+* duration (Numeric)
+
+Like Numeric types, PitchClass and Pitch are 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
+
+For efficiency and convenience, intensity and duration are modeled using Ruby's Numeric types (Fixnum, Float, etc).
+
+Intensity is 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
+
+
+

data/LICENSE.txt

@@ -0,0 +1,27 @@
+Copyright (c) 2011, 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

@@ -1,52 +1,127 @@
-# MTK
-## Music ToolKit for Ruby
+MTK
+===
 
-Classes for modeling music with a focus on simplicity. Support for reading/writing MIDI files (and soon, realtime MIDI).
+Music ToolKit for Ruby
+----------------------
 
+Classes for modeling music with a focus on simplicity. Support for reading/writing MIDI files and realtime MIDI.
 
 
-## Goals
+
+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
+Status
+------
 
-Pre-alpha, API subject to change. Feedback welcome!
+Alpha phase, API subject to change. Feedback welcome!
 
 
 
-## Requirements
+Requirements
+------------
+
 ### Ruby Version
 
-Ruby 1.8 or 1.9
+Ruby 1.8+ or JRuby 1.5+
+
+
+### Dependencies
+
+MTK's core features should not depend on anything outside of the Ruby standard library.
 
-### Gem Dependencies
+MTK's optional features typically require gems. Currently the following gems are required:
 
-* rake (tests & docs)
+* midilib: required by MTK::MIDI::File for file I/O
+
+* jsound and gamelan: required by MTK::MIDI::JSoundInput/Output (also requires JRuby)
+
+Development requires all the gems for optional features, plus the following development tools:
+
+* rake
 * rspec (tests)
 * yard (docs)
 * yard-rspec (docs)
 * rdiscount (docs)
-* midilib (MIDI file I/O -- not strictly required by core lib, but currently needed for tests)
 
+[rvm](https://rvm.beginrescueend.com/) is recommended for cross version testing (see Development Notes below)
+
+
+
+Documentation
+-------------
+
+Gem: http://rdoc.info/gems/mtk/0.0.2/frames
+
+Latest for source: http://rubydoc.info/github/adamjmurray/mtk/master/frames
+
+
+
+Development Notes
+-----------------
+
+### Run Tests ###
+
+Test with current version of Ruby:
+
+     rake spec
+
+Test with all supported versions of Ruby (requires [rvm](https://rvm.beginrescueend.com/), MRI 1.8.7, YARV 1.9.2, JRuby 1.5.6, and JRuby 1.6.2):
+
+     rake spec:xversion
+
+The spec:xversion test must pass for a pull request to be accepted or for a release of the mtk gem.
+
+
+### Generate Docs ###
 
+     yard
+     open doc/frames.html
 
-## Documentation
+or, to automatically refresh the documentation as you work:
 
-    rake yard
+      yard server -r
+      open http://localhost:8808
 
-then open doc/frames.html
 
+### Project Roadmap ###
 
+https://www.pivotaltracker.com/projects/295419
 
-## Tests
 
-    rake spec
 
-I test with MRI 1.8.7, MRI 1.9.2, JRuby 1.5.6, and JRuby 1.6.1 on OS X via rvm:
+Changelog
+---------
 
-    rvm 1.8.7,1.9.2,jruby-1.5.6,jruby-1.6.1 rake spec:fast
+* July 8, 2011: version 0.0.2
+    - Added a Sequencer module to build Timelines out of Patterns
+    - Overhauled Pattern module: removed type-specific patterns, and added the Palindrome, Lines, and Function patterns
+    - Patterns can now be nested (they can contain other Patterns)
+    - Patterns can now be typed, to distinguish Numeric Patterns as :pitch (i.e. intervals), :intensity, :duration, or :rhythm patterns
+    - Removed auto-sorting behavior from PitchClassSet to support 12-tone rows and atonal composition techniques
+    - Added #quantize and #shift features to Timeline
+    - Got rid of Chord class, model Chords with PitchSets or Arrays of Notes instead
+    - Added support for realtime MIDI I/O with JSound (JRuby only)
+    - various cleanup and reorganization
 
+* June 8, 2011: version 0.0.1
+    - First gem release.

data/Rakefile

@@ -7,17 +7,29 @@ task :default => :spec
 CLEAN.include('html','doc') # clean and clobber do the same thing for now
 
 desc "Run RSpec tests with full output"
-RSpec::Core::RakeTask.new do |spec| 
+RSpec::Core::RakeTask.new 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
 
 namespace :spec do
+
   desc "Run RSpecs tests with summary output and fast failure"
   RSpec::Core::RakeTask.new(:fast) do |spec|
     spec.rspec_opts = ["--color", "--fail-fast"]
   end
+
+  desc "Run RSpecs tests on mutiple versions of Ruby: 1.8.7, 1.9.2, JRuby 1.5.6, and JRuby 1.6.2"
+  task :xversion do
+    fail unless system("rvm 1.8.7,1.9.2,jruby-1.5.6,jruby-1.6.2 rake -f #{__FILE__} spec:fast")
+  end
+
 end
 
+
 YARD::Rake::YardocTask.new do |yard|
   yard.files   = ['lib/**/*.rb', 'spec/**/*.rb']
   yard.options = []

data/examples/crescendo.rb

@@ -0,0 +1,20 @@
+# Generate a MIDI file of the C-major scale with a crescendo (it increases in intensity)
+#
+# NOTE: this blindly overwrites any existing MTK-crescendo.mid file, unless an argument is provided
+
+require 'mtk'
+require 'mtk/midi/file'
+include MTK
+include Pitches
+include Intensities
+
+file = ARGV[0] || 'MTK-crescendo.mid'
+
+scale = Pattern::PitchSequence C4,D4,E4,F4,G4,A4,B4,C5
+crescendo = Pattern::IntensityLines pp, [fff, scale.length-1] # step from pp to fff over the length of the scale
+
+sequencer = Sequencer::StepSequencer.new [scale, crescendo]
+timeline = sequencer.to_timeline
+
+MIDI_File(file).write timeline
+

data/examples/dynamic_pattern.rb

@@ -0,0 +1,39 @@
+# Generate a MIDI file using a lambda to dynamically generate the pitches
+#
+# NOTE: this blindly overwrites any existing MTK-dynamic_pattern.mid file, unless an argument is provided
+
+require 'mtk'
+require 'mtk/midi/file'
+include MTK
+include Pitches
+include Intensities
+include Intervals
+
+file = ARGV[0] || "MTK-#{File.basename(__FILE__,'.rb')}.mid"
+
+interval_generator = lambda do
+  # Randomly return intervals
+  r = rand
+  case
+    when r < 0.1 then m2
+    when r < 0.4 then M2
+    when r < 0.5 then m3
+    when r < 0.6 then M3
+    when r < 0.7 then P4
+    when r < 0.8 then -M3
+    when r < 0.95 then -P5
+    else -P8
+  end
+end
+
+pitches = Pattern::Function.new interval_generator, :type => :pitch, :max_elements => 24
+
+# we'll also use a weighted choice to generate the intensities
+intensities = Pattern::Choice.new [mp, mf, f, ff, fff], :type => :intensity, :weights => [1,2,3,2,1]
+
+
+sequencer = Sequencer::StepSequencer.new [pitches, intensities], :step_size => 0.5
+timeline = sequencer.to_timeline
+
+MIDI_File(file).write timeline
+

data/examples/play_midi.rb

@@ -0,0 +1,19 @@
+# Play a given MIDI file with the given MIDI output
+#
+# NOTE: this example only runs under JRuby with the jsound and gamelan gems installed
+
+file, output = ARGV[0], ARGV[1]
+unless file and output
+  puts "Usage: ruby #$0 midi_file output_device"
+  exit 1
+end
+
+require 'mtk'
+require 'mtk/midi/file'
+require 'mtk/midi/jsound_output'
+include MTK
+
+timeline = MIDI_File(file).to_timelines.first # for now this example just plays the first track (JSoundOutput needs to be enhanced to support multiple timelines)
+player = MTK::MIDI::JSoundOutput.new output
+
+player.play timeline

data/examples/print_midi.rb

@@ -0,0 +1,13 @@
+# Print the notes in a MIDI file
+
+file = ARGV[0]
+unless file
+  puts "Usage: ruby #$0 midi_file"
+  exit 1
+end
+
+require 'mtk'
+require 'mtk/midi/file'
+include MTK
+
+puts MIDI_File(file).to_timelines

data/examples/random_tone_row.rb

@@ -0,0 +1,18 @@
+# Generate a MIDI file of a random 12-tone row
+#
+# NOTE: this blindly overwrites any existing MTK-random_tone_row.mid file, unless an argument is provided
+
+require 'mtk'
+require 'mtk/midi/file'
+include MTK
+
+file = ARGV[0] || 'MTK-random_tone_row.mid'
+
+row = PitchClassSet.random_row
+sequence = Pattern::PitchSequence *row.to_a
+
+sequencer = Sequencer::StepSequencer.new [sequence]
+timeline = sequencer.to_timeline
+
+MIDI_File(file).write timeline
+

data/examples/tone_row_melody.rb

@@ -0,0 +1,21 @@
+# Generate a MIDI file using a tone row, repeated 3 times using random rhythms
+#
+# NOTE: this blindly overwrites any existing MTK-tone_row_melody.mid file, unless an argument is provided
+
+require 'mtk'
+require 'mtk/midi/file'
+include MTK
+include PitchClasses
+include Durations
+
+file = ARGV[0] || 'MTK-tone_row_melody.mid'
+
+row = PitchClassSet(Db, G, Ab, F, Eb, E, D, C, B, Gb, A, Bb)
+pitch_pattern = Pattern.PitchCycle *row
+rhythm_pattern = Pattern.RhythmCycle(Pattern.Choice s, e, e+s, q) # choose between sixteenth, eighth, dotted eighth, and quarter
+
+sequencer = Sequencer::RhythmicSequencer.new [pitch_pattern, rhythm_pattern], :max_steps => 36
+timeline = sequencer.to_timeline
+
+MIDI_File(file).write timeline
+

data/lib/mtk/_constants/durations.rb

@@ -0,0 +1,80 @@
+require 'rational'
+
+module MTK
+
+  # Defines duration constants using abbreviations for standard rhythm values ('w' for whole note, 'h' for half note, etc).
+  #
+  # These can be thought of like constants, but in order to distinguish 'e' (eighth note) from the {PitchClass} 'E'
+  # it was necessary to use lower-case names and therefore define them as "pseudo constant" methods.
+  # The methods are available either through the module (MTK::Durations::e) or via mixin (include MTK::Durations; e)
+  #
+  # These values assume the quarter note is one beat (1.0), so they work best with 4/4 and other */4 time signatures.
+  #
+  # @note Including this module defines a bunch of single-character variables, which may shadow existing variable names.
+  #       Just be mindful of what is defined in this module when including it.
+  #
+  # @see Note
+  module Durations
+    extend Helper::PseudoConstants
+
+    # NOTE: the yard doc macros here only fill in [$2] with the actual value when generating docs under Ruby 1.9+
+
+    # whole note
+    # @macro [attach] durations.define_constant
+    #   @attribute [r]
+    #   @return [$2] number of beats for $1
+    define_constant 'w', 4
+
+    # half note
+    define_constant 'h', 2
+
+    # quarter note
+    define_constant 'q', 1
+
+    # eight note
+    define_constant 'e', Rational(1,2)
+
+    # sixteenth note
+    define_constant 's', Rational(1,4)
+
+    # thirty-second note
+    define_constant 'r', Rational(1,8)
+
+    # sixty-fourth note
+    define_constant 'x', Rational(1,16)
+
+    # The values of all "psuedo constants" defined in this module
+    DURATIONS = [w, h, q, e, s, r, x].freeze
+
+    # The names of all "psuedo constants" defined in this module
+    DURATION_NAMES = %w[w h q e s r x].freeze
+
+    # Lookup the value of an duration constant by name.
+    # This method supports appending any combination of '.' and 't' for more fine-grained values.
+    # each '.' multiplies by 3/2, and each 't' multiplies by 2/3.
+    # @example lookup value of 'e.' (eight note), which is 0.75 (0.5 * 1.5)
+    #         MTK::Durations['e.']
+    def self.[](name)
+      begin
+        modifier = nil
+        if name =~ /(\w)((.|t)*)/
+          name = $1
+          modifier = $2
+        end
+
+        value = send name
+        modifier.each_char do |mod|
+          case mod
+            when '.' then value *= Rational(3,2)
+            when 't' then value *= Rational(2,3)
+          end
+        end
+        value
+
+      rescue
+        nil
+      end
+    end
+
+  end
+end

data/lib/mtk/_constants/intensities.rb

@@ -0,0 +1,81 @@
+module MTK
+
+  # Defines intensity constants using standard dynamic symbols.
+  #
+  # These can be thought of like constants, but in order to distinguish 'f' (forte) from the {PitchClass} 'F'
+  # it was necessary to use lower-case names and therefore define them as "pseudo constant" methods.
+  # The methods are available either through the module (MTK::Intensities::f) or via mixin (include MTK::Intensities;  f)
+  #
+  # These values are intensities in the range 0.125 - 1.0 (in increments of 1/8), so they can be easily scaled (unlike MIDI velocities).
+  #
+  # It is also possible to retrieve values in increments of 1/24 by using the '+' and '-' suffix when looking
+  # up values via the {.[]} method.
+  #
+  # @note Including this module shadows Ruby's built-in p() method. 
+  #   If you include this module, you can access the built-in p() method via Kernel.p()
+  #
+  # @see Note
+  module Intensities
+    extend Helper::PseudoConstants
+    
+    # NOTE: the yard doc macros here only fill in [$2] with the actual value when generating docs under Ruby 1.9+
+    
+    # pianississimo 
+    # @macro [attach] intensities.define_constant
+    #   @attribute [r]
+    #   @return [$2] intensity value for $1   
+    define_constant 'ppp', 0.125
+
+    # pianissimo      
+    define_constant 'pp', 0.25
+
+    # piano
+    # @note Including this module shadows Ruby's built-in p() method. 
+    #   If you include this module, you can access the built-in p() method via Kernel.p()
+    define_constant 'p', 0.375
+
+    # mezzo-piano
+    define_constant 'mp', 0.5
+
+    # mezzo-forte
+    define_constant 'mf', 0.625
+
+    # forte
+    define_constant 'f', 0.75
+    
+    # fortissimo
+    define_constant 'ff', 0.875
+
+    # fortississimo
+    define_constant 'fff', 1.0
+
+    # The values of all "psuedo constants" defined in this module
+    INTENSITIES = [ppp, pp, p, mp, mf, f, ff, fff].freeze
+
+    # The names of all "psuedo constants" defined in this module
+    INTENSITY_NAMES = %w[ppp pp p mp mf f ff fff].freeze
+
+    # Lookup the value of an intensity constant by name.
+    # This method supports appending '+' or '-' for more fine-grained values.
+    # '+' and '-' add and subtract 1/24, respectively (enforcing the upper bound of 1.0 for 'fff+').
+    # @example lookup value of 'mp+', which is 0.5416666666666666  (0.5 + 1/24.0)
+    #         MTK::Intensities['mp+']
+    def self.[](name)
+      return 1.0 if name == "fff+" # special case because "fff" is already the maximum
+
+      modifier = nil
+      if name =~ /(\w+)([+-])/
+        name = $1
+        modifier = $2
+      end
+
+      value = send name
+      value += 1.0/24 if modifier == '+'
+      value -= 1.0/24 if modifier == '-'
+      value
+    rescue
+      nil
+    end
+
+  end
+end

data/lib/mtk/{constants → _constants}/intervals.rb

@@ -12,7 +12,7 @@ module MTK
   # it was necessary to use lower-case names for some of the values and therefore define them as "pseudo constant" methods.
   # The methods are available either through the module (MTK::Intervals::m2) or via mixin (include MTK::Intervals; m2) 
   module Intervals
-    extend PseudoConstants
+    extend Helper::PseudoConstants
 
     # NOTE: the yard doc macros here only fill in [$2] with the actual value when generating docs under Ruby 1.9+
 
@@ -61,6 +61,15 @@ module MTK
     # pefect octave
     define_constant 'P8', 12
 
+    # The values of all "psuedo constants" defined in this module
+    INTERVALS = [P1, m2, M2, m3, M3, P4, TT, P5, m6, M6, m7, M7, P8].freeze
+
+    # The names of all "psuedo constants" defined in this module
+    INTERVAL_NAMES = %w[P1 m2 M2 m3 M3 P4 TT P5 m6 M6 m7 M7 P8].freeze
+
+    # Lookup the value of an interval constant by name.
+    # @example lookup value of 'M3', which is 4
+    #         MTK::Intervals['M3']
     def self.[](name)
       send name
     rescue

data/lib/mtk/_constants/pitch_classes.rb

@@ -0,0 +1,35 @@
+module MTK
+
+  # Defines a constant for each {PitchClass} in the Western chromatic scale.
+
+  module PitchClasses
+
+    # The values of all "psuedo constants" defined in this module
+    PITCH_CLASSES = []
+
+    # The names of all "psuedo constants" defined in this module
+    PITCH_CLASS_NAMES = PitchClass::NAMES
+
+    for name in PITCH_CLASS_NAMES
+      pc = PitchClass[name]
+      PITCH_CLASSES << pc
+      const_set name, pc
+    end
+
+    PITCH_CLASSES.freeze
+
+    # Lookup the value of an pitch class constant by name.
+    # @example lookup value of 'C'
+    #         MTK::PitchClasses['C']
+    # @see PitchClass.[]
+    def self.[](name)
+      begin
+        const_get name
+      rescue
+        nil
+      end
+    end
+
+  end
+
+end