mtk 0.0.1

data/README.md

@@ -0,0 +1,52 @@
+# MTK
+## Music ToolKit for Ruby
+
+Classes for modeling music with a focus on simplicity. Support for reading/writing MIDI files (and soon, realtime MIDI).
+
+
+
+## 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
+
+Pre-alpha, API subject to change. Feedback welcome!
+
+
+
+## Requirements
+### Ruby Version
+
+Ruby 1.8 or 1.9
+
+### Gem Dependencies
+
+* rake (tests & docs)
+* 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)
+
+
+
+## Documentation
+
+    rake yard
+
+then open doc/frames.html
+
+
+
+## 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:
+
+    rvm 1.8.7,1.9.2,jruby-1.5.6,jruby-1.6.1 rake spec:fast
+

data/Rakefile

@@ -0,0 +1,31 @@
+require 'rspec/core/rake_task'
+require 'rake/clean'
+require 'yard'
+
+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| 
+  spec.rspec_opts = ["--color", "--format", "nested"]
+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
+end
+
+YARD::Rake::YardocTask.new do |yard|
+  yard.files   = ['lib/**/*.rb', 'spec/**/*.rb']
+  yard.options = []
+  if File.exist? '../yard-spec-plugin/lib/yard-rspec.rb'
+    # prefer my local patched copy which can handle my rspec conventions better...
+    yard.options.concat ['-e' '../yard-spec-plugin/lib/yard-rspec.rb']
+  else
+    # use the gem
+    yard.options.concat ['-e' 'yard-rspec']
+  end
+end

data/lib/mtk/chord.rb

@@ -0,0 +1,47 @@
+module MTK
+
+  # A multi-pitch, note-like {Event} defined by a {PitchSet}, intensity, and duration
+  class Chord < Event
+
+    # the {PitchSet} of the chord
+    attr_reader :pitch_set
+
+    def initialize(pitches, intensity, duration)
+      @pitch_set = if pitches.is_a? PitchSet
+        pitches
+      else
+        PitchSet.new(pitches)
+      end
+      super(intensity, duration)
+    end
+
+    def self.from_hash(hash)
+      new hash[:pitch_set], hash[:intensity], hash[:duration]
+    end
+
+    def to_hash
+      super.merge({ :pitch_set => @pitch_set })
+    end
+
+    def pitches
+      @pitch_set.pitches
+    end
+
+    def transpose(interval)
+      self.class.new(@pitch_set + interval, @intensity, @duration)
+    end
+
+    def == other
+      super and other.respond_to? :pitch_set and @pitch_set == other.pitch_set
+    end
+
+    def to_s
+      "Chord(#{pitch_set}, #{super})"
+    end
+
+    def inspect
+      "Chord(#{pitch_set}, #{super})"
+    end
+  end
+
+end

data/lib/mtk/constants/dynamics.rb

@@ -0,0 +1,56 @@
+module MTK
+
+  # Defines values for 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 throught the module (MTK::Dynamics::f) or via mixin (include MTK::Dynamics;  f)
+  #
+  # These values are intensities in the range 0.0 - 1.0, so they can be easily scaled (unlike MIDI velocities).
+  #
+  # @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 Dynamics
+    extend MTK::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] dynamics.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
+
+    def self.[](name)
+      send name
+    rescue
+      nil
+    end
+
+  end
+end

data/lib/mtk/constants/intervals.rb

@@ -0,0 +1,76 @@
+module MTK
+
+  # Defines a constant for intervals up to an octave using diatonic naming conventions (see http://en.wikipedia.org/wiki/Interval_(music)#Main_intervals)
+  #
+  # Naming conventions
+  #   P#: perfect interval
+  #   M#: major interval
+  #   m#: minor interval
+  #   TT: tritone (AKA augmented 4th or diminshed 5th)
+  #
+  # These can be thought of like constants, but in order to succintly distinguish 'm2' (minor) from 'M2' (major),
+  # 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
+
+    # NOTE: the yard doc macros here only fill in [$2] with the actual value when generating docs under Ruby 1.9+
+
+    # perfect unison
+    # @macro [attach] interval.define_constant
+    #   @attribute [r]
+    #   @return [$2] number of semitones in the interval $1    
+    define_constant 'P1', 0
+
+    # minor second
+    # @macro [attach] interval.define_constant
+    #   @attribute [r]
+    #   @return [$2] number of semitones in the interval $1
+    define_constant 'm2', 1
+
+    # major second
+    define_constant 'M2', 2
+
+    # minor third
+    define_constant 'm3', 3
+
+    # major third
+    define_constant 'M3', 4
+
+    # pefect fourth
+    define_constant 'P4', 5
+
+    # tritone (AKA augmented fourth or diminished fifth)
+    define_constant 'TT', 6
+
+    # perfect fifth
+    define_constant 'P5', 7
+
+    # minor sixth
+    define_constant 'm6', 8
+
+    # major sixth
+    define_constant 'M6', 9
+
+    # minor seventh
+    define_constant 'm7', 10
+
+    # major seventh
+    define_constant 'M7', 11
+
+    # pefect octave
+    define_constant 'P8', 12
+
+    def self.[](name)
+      send name
+    rescue
+      begin
+        const_get name
+      rescue
+        nil
+      end
+    end
+
+  end
+  
+end

data/lib/mtk/constants/pitch_classes.rb

@@ -0,0 +1,18 @@
+module MTK
+
+  # Defines a constant for each {PitchClass} in the Western chromatic scale.
+
+  module PitchClasses
+
+    # An array of all pitch class constants defined in this module
+    PITCH_CLASSES = []
+
+    for name in PitchClass::NAMES
+      pc = PitchClass.from_name name
+      PITCH_CLASSES << pc
+      const_set name, pc
+    end
+
+  end
+
+end

data/lib/mtk/constants/pitches.rb

@@ -0,0 +1,24 @@
+module MTK
+
+  # Defines a constants for each {Pitch} in the standard MIDI range using scientific pitch notation.
+  #
+  # See http://en.wikipedia.org/wiki/Scientific_pitch_notation
+  #
+  # Note that because the character '#' cannot be used in the name of a constant,
+  # The "black key" pitches are all named as flats with 'b' (for example, Gb3 or Cb4)
+
+  module Pitches
+
+    # An array of all the pitch constants defined in this module
+    PITCHES = []
+
+    128.times do |note_number|
+      pitch = Pitch.from_i( note_number )
+      PITCHES << pitch
+      octave_str = pitch.octave.to_s.sub(/-/,'_') # '_1' for -1
+      const_set "#{pitch.pitch_class}#{octave_str}", pitch
+    end
+
+  end
+
+end

data/lib/mtk/constants/pseudo_constants.rb

@@ -0,0 +1,25 @@
+module MTK
+  
+  # Extension for modules that want to define pseudo-constants (constant-like values with lower-case names)
+  module PseudoConstants
+  
+    # Define a "constant" as a module method and module function (available both through the module namespace and as a mixin method),
+    # in order to facility defining constant-like values with lower-case names.
+    #
+    # @param name [Symbol] the name of the pseudo-constant
+    # @param value [Object] the value of the pseudo-constant
+    # @return [nil]
+    def define_constant name, value
+      if name[0..0] =~ /[A-Z]/
+        const_set name, value # it's just a normal constant
+      else
+        # the pseudo-constant definition is the combination of a method and module_function:
+        define_method(name) { value }
+        module_function name
+      end
+      nil
+    end
+
+  end
+  
+end

data/lib/mtk/event.rb

@@ -0,0 +1,61 @@
+module MTK
+
+  # An abstract musical event that has an intensity and a duration
+  # @abstract
+  class Event
+
+    # intensity of the note as a value in the range 0.0 - 1.0
+    attr_reader :intensity
+
+    # duration of the note in beats (e.g. 1.0 is a quarter note in 4/4 time signatures)
+    attr_reader :duration
+
+    def initialize(intensity, duration)
+      @intensity, @duration = intensity, duration
+    end
+
+    def self.from_hash(hash)
+      new hash[:intensity], hash[:duration]
+    end
+
+    def to_hash
+      { :intensity => @intensity, :duration => @duration }
+    end
+
+    def clone_with(hash)
+      self.class.from_hash(to_hash.merge hash)
+    end
+
+    def scale_intensity(scaling_factor)
+      clone_with :intensity => @intensity * scaling_factor.to_f
+    end
+
+    def scale_duration(scaling_factor)
+      clone_with :duration => @duration * scaling_factor.to_f
+    end
+
+    # intensity scaled to the MIDI range 0-127
+    def velocity
+      (127 * @intensity).round
+    end
+
+    def duration_in_pulses(pulses_per_beat)
+      (@duration * pulses_per_beat).round
+    end
+
+    def == other
+      other.respond_to? :intensity and @intensity == other.intensity and
+      other.respond_to? :duration and @duration == other.duration
+    end
+
+    def to_s
+      "#{sprintf '%.2f',@intensity}, #{sprintf '%.2f',@duration}"
+    end
+
+    def inspect
+      "#@intensity, #@duration"
+    end
+
+  end
+
+end

data/lib/mtk/midi/file.rb

@@ -0,0 +1,179 @@
+require 'rubygems'
+require 'midilib'
+
+module MTK
+  module MIDI
+
+    class File
+      def initialize file
+        if file.respond_to? :path
+          @file = file.path
+        else
+          @file = file.to_s
+        end
+      end
+
+      # Read a MIDI file into an Array of {Timeline}s
+      #
+      # @param filepath [String, #path] path of the file to be written
+      # @return [Timeline]
+      #
+      def to_timelines
+        timelines = []
+
+        ::File.open(@file, 'rb') do |f|
+          sequence = ::MIDI::Sequence.new
+          sequence.read(f)
+          pulses_per_beat = sequence.ppqn.to_f
+          track_idx = -1
+
+          for track in sequence
+            track_idx += 1
+            timeline = Timeline.new
+            note_ons = {}
+            #puts "TRACK #{track_idx}"
+
+            for event in track
+              #puts "#{event.class}: #{event}   @#{event.time_from_start}"
+              case event
+                when ::MIDI::NoteOn
+                  note_ons[event.note] = event
+
+                when ::MIDI::NoteOff
+                  if on_event = note_ons.delete(event.note)
+                    time = (on_event.time_from_start)/pulses_per_beat
+                    duration = (event.time_from_start - on_event.time_from_start)/pulses_per_beat
+                    note = Note.from_midi event.note, on_event.velocity, duration
+                    timeline.add time, note
+                  end
+              end
+            end
+            timelines << timeline
+          end
+        end
+        timelines
+      end
+
+      def write(anything)
+        case anything
+          when Timeline then
+            write_timeline(anything)
+          when Array then
+            write_timelines(anything)
+          else
+            raise "#{self.class}#write doesn't understand #{anything.class}"
+        end
+      end
+
+      def write_timelines(timelines, parent_sequence=nil)
+        sequence = parent_sequence || ::MIDI::Sequence.new
+        for timeline in timelines
+          write_timeline(timeline, sequence)
+        end
+        write_to_disk sequence unless parent_sequence
+      end
+
+      # Write the Timeline as a MIDI file
+      #
+      # @param [Timeline]
+      def write_timeline(timeline, parent_sequence=nil)
+        sequence = parent_sequence || ::MIDI::Sequence.new
+        clock_rate = sequence.ppqn
+        track = add_track sequence
+        channel = 1
+
+        for time, event in timeline
+          time *= clock_rate
+          case event
+            when Note
+              pitch, velocity = event.pitch, event.velocity
+              add_event track, time => note_on(channel, pitch, velocity)
+              duration = event.duration_in_pulses(clock_rate)
+              add_event track, time+duration => note_off(channel, pitch, velocity)
+
+            when Chord
+              velocity = event.velocity
+              duration = event.duration_in_pulses(clock_rate)
+              for pitch in event.pitches
+                pitch = pitch.to_i
+                add_event track, time => note_on(channel, pitch, velocity)
+                add_event track, time+duration => note_off(channel, pitch, velocity)
+              end
+
+          end
+        end
+        track.recalc_delta_from_times
+
+        write_to_disk sequence unless parent_sequence
+      end
+
+
+      ########################
+      private
+
+      def write_to_disk(sequence)
+        ::File.open(@file, 'wb') { |f| sequence.write f }
+      end
+
+      def print_midi sequence
+        for track in sequence
+          puts "\n*** track \"#{track.name}\""
+          puts "#{track.events.length} events"
+          for event in track
+            puts "#{event.to_s} (#{event.time_from_start})"
+          end
+        end
+      end
+
+      # Set tempo in terms of Quarter Notes per Minute (aka BPM)
+      def tempo(bpm)
+        ms_per_quarter_note = ::MIDI::Tempo.bpm_to_mpq(bpm)
+        ::MIDI::Tempo.new(ms_per_quarter_note)
+      end
+
+      def program(program_number)
+        ::MIDI::ProgramChange.new(channel, program_number)
+      end
+
+      def note_on(channel, pitch, velocity)
+        ::MIDI::NoteOn.new(channel, pitch.to_i, velocity)
+      end
+
+      def note_off(channel, pitch, velocity)
+        ::MIDI::NoteOff.new(channel, pitch.to_i, velocity)
+      end
+
+      def cc(channel, controller, value)
+        ::MIDI::Controller.new(channel, controller.to_i, value.to_i)
+      end
+
+      def pitch_bend(channel, value)
+        ::MIDI::PitchBend.new(channel, value)
+      end
+
+      def add_track sequence, opts={}
+        track = ::MIDI::Track.new(sequence)
+        track.name = opts.fetch :name, ''
+        sequence.tracks << track
+        track
+      end
+
+      def add_event track, event_hash
+        for time, event in event_hash
+          event.time_from_start = time
+          track.events << event
+          event
+        end
+      end
+
+    end
+
+  end
+
+  def MIDI_File(f)
+    MIDI::File.new(f)
+  end
+  module_function :MIDI_File
+
+end
+

data/lib/mtk/note.rb

@@ -0,0 +1,44 @@
+module MTK
+
+  # A musical #{Event} defined by a {Pitch}, intensity, and duration
+  class Note < Event
+
+    # frequency of the note as a Pitch
+    attr_reader :pitch
+
+    def initialize(pitch, intensity, duration)
+      @pitch = pitch
+      super(intensity, duration)
+    end
+
+    def self.from_hash(hash)
+      new hash[:pitch], hash[:intensity], hash[:duration]
+    end
+
+    def self.from_midi(pitch, velocity, beats)
+      new Pitches::PITCHES[pitch], velocity/127.0, beats
+    end
+
+    def to_hash
+      super.merge({ :pitch => @pitch })
+    end
+
+    def transpose(interval)
+      self.class.new(@pitch+interval, @intensity, @duration)
+    end
+
+    def == other
+      super and other.respond_to? :pitch and @pitch == other.pitch
+    end
+
+    def to_s
+      "Note(#{pitch}, #{super})"
+    end
+
+    def inspect
+      "Note(#{pitch}, #{super})"
+    end
+
+  end
+
+end

data/lib/mtk/numeric_extensions.rb

@@ -0,0 +1,61 @@
+class Numeric
+
+  def semitones
+    self
+  end
+
+  def cents
+    self/100.0
+  end
+
+  def minor_seconds
+    self
+  end
+
+  def major_seconds
+    self * 2
+  end
+
+  def minor_thirds
+    self * 3
+  end
+
+  def major_thirds
+    self * 4
+  end
+
+  def perfect_fourths
+    self * 5
+  end
+
+  def tritones
+    self * 6
+  end
+  alias augmented_fourths tritones
+  alias diminshed_fifths tritones
+
+  def perfect_fifths
+    self * 7
+  end
+
+  def minor_sixths
+    self * 8
+  end
+
+  def major_sixths
+    self * 9
+  end
+
+  def minor_sevenths
+    self * 10
+  end
+
+  def major_sevenths
+    self * 11
+  end
+
+  def octaves
+    self * 12
+  end
+
+end

data/lib/mtk/pattern/choice.rb

@@ -0,0 +1,21 @@
+module MTK
+  module Pattern
+
+    # An element enumerator that randomly choices from a list of elements
+    class Choice
+
+      # The element choices
+      attr_reader :elements
+
+      def initialize(elements)
+        @elements = elements
+      end
+
+      def next
+        @elements[rand(@elements.length)] if @elements and not @elements.empty?
+      end
+
+    end
+
+  end
+end