mtk 0.0.3.3 → 0.4

data/examples/notation.rb

@@ -1,3 +1,7 @@
+# NOTE: experimental example!
+# This requires Lilypond to be installed, see http://lilypond.org/
+# The lilypond command must be on your PATH or specificed via the LILYPOND_PATH environment variable.
+
 require 'mtk'
 require 'mtk/io/notation'
 include MTK
@@ -13,7 +17,7 @@ arg_error "MTK syntax string not provided" unless syntax
 
 
 file = ARGV[1]
-arg_error "The output_file must end in '.png', '.pdf', or '.ps'" unless file
+arg_error "The output_file must end in '.png', '.pdf', or '.ps'" unless file =~ /\.(png|pdf|ps)$/
 
 
 sequencer = MTK::Lang::Parser.parse(syntax)

data/examples/tone_row_melody.rb

@@ -12,7 +12,7 @@ file = ARGV[0] || 'MTK-tone_row_melody.mid'
 
 row = PitchClassSet Db, G, Ab, F, Eb, E, D, C, B, Gb, A, Bb
 pitch_pattern = Patterns.Cycle *row
-rhythm_pattern = Patterns.Choice s, i, i+s, q # choose between sixteenth, eighth, dotted eighth, and quarter
+rhythm_pattern = Patterns.Choice s, e, e+s, q # choose between sixteenth, eighth, dotted eighth, and quarter
 
 chain = Patterns.Chain pitch_pattern, rhythm_pattern, min_elements: 36, max_elements: 36
 

data/lib/mtk.rb

@@ -56,6 +56,7 @@ require 'mtk/groups/chord'
 
 require 'mtk/events/event'
 require 'mtk/events/note'
+require 'mtk/events/rest'
 require 'mtk/events/parameter'
 require 'mtk/events/timeline'
 

data/lib/mtk/core/duration.rb

@@ -3,18 +3,20 @@ module MTK
 
     # A measure of time in musical beats.
     # May be negative to indicate a rest, which uses the absolute value for the effective duration.
+    #
+    # @see Lang::Durations
     class Duration
 
       include Comparable
 
       # The names of the base durations. See {MTK::Lang::Durations} for more info.
-      NAMES = %w[w h q i s r x].freeze
+      NAMES = %w[w h q e s r x].freeze
 
       VALUES_BY_NAME = {
         'w' => 4,
         'h' => 2,
         'q' => 1,
-        'i' => Rational(1,2),
+        'e' => Rational(1,2),
         's' => Rational(1,4),
         'r' => Rational(1,8),
         'x' => Rational(1,16)
@@ -55,7 +57,7 @@ module MTK
       # @example lookup the value of 3/4w, which three-quarters of a whole note (3 beats):
       #          MTK::Core::Duration.from_s('3/4w')
       def self.from_s(s)
-        if s =~ /^(-)?(\d+([\.\/]\d+)?)?([whqisrx])((\.|t)*)$/i
+        if s =~ /^(-)?(\d+([\.\/]\d+)?)?([whqesrx])((\.|t)*)$/i
           name = $4.downcase
           modifier = $5.downcase
           modifier << $1 if $1 # negation
@@ -95,6 +97,7 @@ module MTK
       # The magnitude (absolute value) of the duration.
       # This is the actual duration for rests.
       # @see #rest?
+      # @see #abs
       def length
         @value < 0 ? -@value : @value
       end
@@ -106,6 +109,18 @@ module MTK
         @value < 0
       end
 
+      # Force resets to be non-rests, otherwise don't change the duration.
+      # @see #-@
+      # @see #length
+      # @see #rest?
+      def abs
+        if @value < 0
+          -self
+        else
+          self
+        end
+      end
+
       # The number of beats as a floating point number
       def to_f
         @value.to_f

data/lib/mtk/core/intensity.rb

@@ -2,12 +2,14 @@ module MTK
   module Core
 
     # A measure of intensity, using an underlying value in the range 0.0-1.0
+    #
+    # @see Lang::Intensities
     class Intensity
 
       include Comparable
 
-      # The names of the base intensities. See {}MTK::Lang::Intensities} for more info.
-      NAMES = %w[ppp pp p mp mf o ff fff].freeze
+      # The names of the base intensities. See {MTK::Lang::Intensities} for more info.
+      NAMES = %w[ppp pp p mp mf f ff fff].freeze
 
       VALUES_BY_NAME = {
         'ppp' => 0.125,
@@ -15,7 +17,7 @@ module MTK
         'p' => 0.375,
         'mp' => 0.5,
         'mf' => 0.625,
-        'o' => 0.75,
+        'f' => 0.75,
         'ff' => 0.875,
         'fff' => 1.0
       }

data/lib/mtk/core/interval.rb

@@ -2,29 +2,35 @@ module MTK
   module Core
 
     # A measure of intensity, using an underlying value in the range 0.0-1.0
+    #
+    # @see Lang::Intervals
     class Interval
 
       include Comparable
 
       # The preferred names of all pre-defined intervals
+      # @see ALL_NAMES
       NAMES = %w[P1 m2 M2 m3 M3 P4 TT P5 m6 M6 m7 M7 P8].freeze
 
       # All valid names of pre-defined intervals, indexed by their value.
+      # @see ALL_NAMES
+      # @see NAMES
+      # @see http://en.wikipedia.org/wiki/Interval_(music)#Main_intervals
       NAMES_BY_VALUE =
-        [ #   names      # value # description
-          %w( P1 p1 ),   #   0   #  unison
-          %w( m2 min2 ), #   1   #  minor second
-          %w( M2 maj2 ), #   2   #  major second
-          %w( m3 min3 ), #   3   #  minor third
-          %w( M3 maj3 ), #   4   #  major third
-          %w( P4 p4 ),   #   5   #  perfect fourth
-          %w( TT tt ),   #   6   #  tritone (AKA augmented fourth, diminished fifth)
-          %w( P5 p5 ),   #   7   #  perfect fifth
-          %w( m6 min6 ), #   8   #  minor sixth
-          %w( M6 maj6 ), #   9   #  major sixth
-          %w( m7 min7 ), #  10   #  minor seventh
-          %w( M7 maj7 ),  #  11   #  major seventh
-          %w( P8 p8 )    #  12   #  octave
+        [ #   names      # value # description     # enharmonic equivalents
+          %w( P1 d2 ),   #   0   #  unison         #  diminished second
+          %w( m2 a1 ),   #   1   #  minor second   #  augmented unison
+          %w( M2 d3 ),   #   2   #  major second   #  diminished third
+          %w( m3 a2 ),   #   3   #  minor third    #  augmented second
+          %w( M3 d4 ),   #   4   #  major third    #  diminished fourth
+          %w( P4 a3 ),   #   5   #  perfect fourth #  augmented third
+          %w( TT a4 d5 ),#   6   #  tritone        #  augmented fourth, diminished fifth
+          %w( P5 d6 ),   #   7   #  perfect fifth  #  diminished sixth
+          %w( m6 a5 ),   #   8   #  minor sixth    #  augmented fifth
+          %w( M6 d7 ),   #   9   #  major sixth    #  diminished seventh
+          %w( m7 a6 ),   #  10   #  minor seventh  #  augmented sixth
+          %w( M7 d8 ),   #  11   #  major seventh  #  diminished octave
+          %w( P8 a7 )    #  12   #  octave         #  augmented seventh
         ].freeze
 
       # A mapping from intervals names to their value
@@ -35,6 +41,7 @@ module MTK
       ].freeze
 
       # All valid interval names
+      # @see NAMES_BY_VALUE
       ALL_NAMES = NAMES_BY_VALUE.flatten.freeze
 
 

data/lib/mtk/core/pitch.rb

@@ -2,6 +2,8 @@ module MTK
   module Core
 
     # A frequency represented by a {PitchClass}, an integer octave, and an offset in semitones.
+    #
+    # @see Lang::Pitches
     class Pitch
 
       include Comparable

data/lib/mtk/core/pitch_class.rb

@@ -4,10 +4,10 @@ module MTK
     # A set of all pitches that are an integer number of octaves apart.
     # A {Pitch} has the same PitchClass as the pitches one or more octaves away.
     # @see https://en.wikipedia.org/wiki/Pitch_class
-    #
+    # @see Lang::PitchClasses
     class PitchClass
 
-      # The normalized names of the 12 pitch classes in the chromatic scale.
+      # The preferred names of the 12 pitch classes in the chromatic scale.
       # The index of each {#name} is the pitch class's numeric {#value}.
       NAMES = %w( C Db D Eb E F Gb G Ab A Bb B ).freeze
 
@@ -15,7 +15,7 @@ module MTK
       # organized such that each index contains the allowed names of the pitch class with a {#value} equal to that index.
       # @see VALID_NAMES
       VALID_NAMES_BY_VALUE =
-      [ # (valid names ), # value # normalized name
+      [ # (valid names ), # value # preferred name
         %w( B#  C  Dbb ), #   0   #   C
         %w( B## C# Db  ), #   1   #   Db
         %w( C## D  Ebb ), #   2   #   D
@@ -48,6 +48,9 @@ module MTK
 
       # The value of this pitch class.
       # An integer from 0..11 that indexes this pitch class in {PITCH_CLASSES} and the {#name} in {NAMES}.
+      #
+      # This value is fairly arbitrary and just used for sorting purposes and mod 12 arithmetic when composing
+      # directly with pitch classes.
       attr_reader :value
 
 

data/lib/mtk/events/event.rb

@@ -51,7 +51,7 @@ module MTK
       end
 
       def to_h
-        hash = {:type => @type}
+        hash = {type: @type}
         hash[:value] = @value unless @value.nil?
         hash[:duration] = @duration unless @duration.nil?
         hash[:number] = @number unless @number.nil?
@@ -82,6 +82,7 @@ module MTK
         @duration.length
       end
 
+      # True if this event represents a rest, false otherwise.
       # By convention, any events with negative durations are a rest
       def rest?
         @duration.rest?

data/lib/mtk/events/note.rb

@@ -2,7 +2,7 @@ module MTK
 
   module Events
 
-    # A musical {Event} defined by a {Pitch}, intensity, and duration
+    # A musical {Event} defined by a {Core::Pitch}, {Core::Intensity}, and {Core::Duration}
     class Note < Event
 
       DEFAULT_DURATION  = MTK::Core::Duration[1]

data/lib/mtk/events/parameter.rb

@@ -2,6 +2,7 @@ module MTK
 
   module Events
 
+    # A non-note event such as pitch bend, pressure (aftertouch), or control change (CC)
     class Parameter < Event
 
       def self.from_midi(status, data1, data2)

data/lib/mtk/events/rest.rb

@@ -0,0 +1,85 @@
+module MTK
+
+  module Events
+
+    # An interval of silence.
+    #
+    # By convention, MTK uses {Core::Duration}s with negative values for rests. This class forces the {#duration}
+    # to always have a negative value.
+    #
+    # @note Because a negative durations indicate rests, other {Event} classes may represent rests too.
+    #       Therefore, you should always determine if an {Event} is a rest via the {#rest?} method, instead
+    #       of seeing if the class is an MTK::Events::Rest
+    class Rest < Event
+
+      def initialize(duration, channel=nil)
+        super :rest, duration:duration, channel:channel
+        self.duration = @duration # force to be a rest
+      end
+
+      def self.from_h(hash)
+        new(hash[:duration], hash[:channel])
+      end
+
+      # Assign the duration, forcing to a negative value to indicate this is a rest.
+      def duration= duration
+        super
+        @duration = -@duration unless @duration.rest? # force to be a rest
+      end
+
+      # Rests don't have a corresponding value in MIDI, so this is nil
+      # @return nil
+      def midi_value
+        nil
+      end
+
+      # Rests don't have a corresponding value in MIDI, so this is a no-op
+      def midi_value= value
+      end
+
+      def to_s
+        "Rest(#{@duration})"
+      end
+
+      def inspect
+        "#<#{self.class}:#{object_id} @duration=#{@duration.inspect}" +
+            if @channel then ", @channel=#{@channel}>" else '>' end
+      end
+
+    end
+  end
+
+
+  # Construct a {Events::Rest} from a list of any supported type for the arguments: pitch, intensity, duration, channel
+  def Rest(*anything)
+    anything = anything.first if anything.size == 1
+    case anything
+      when MTK::Events::Rest then anything
+      when MTK::Events::Event then MTK::Events::Rest.new(anything.duration, anything.channel)
+      when Numeric then MTK::Events::Rest.new(anything)
+      when Duration then MTK::Events::Rest.new(anything)
+
+      when Array
+        duration = nil
+        channel = nil
+        unknowns = []
+        anything.each do |item|
+          case item
+            when MTK::Core::Duration then duration = item
+            else unknowns << item
+          end
+        end
+
+        duration  = MTK.Duration(unknowns.shift)  if duration.nil?  and not unknowns.empty?
+        raise "MTK::Rest() couldn't find a duration in arguments: #{anything.inspect}" if duration.nil?
+        channel = unknowns.shift.to_i if channel.nil? and not unknowns.empty?
+
+        MTK::Events::Rest.new(duration, channel)
+
+      else
+        raise "MTK::Rest() doesn't understand #{anything.class}"
+    end
+  end
+  module_function :Rest
+
+end

data/lib/mtk/events/timeline.rb

@@ -212,8 +212,12 @@ module MTK
       def to_s
         times = self.times
         last = times.last
-        width = sprintf("%d",last).length + 3 # nicely align the '=>' against the longest number
-        times.map{|t| sprintf("%#{width}.2f",t)+" => #{@timeline[t].join ', '}" }.join "\n"
+        if last
+          width = sprintf("%d",last).length + 3 # nicely align the '=>' against the longest number
+          times.map{|t| sprintf("%#{width}.2f",t)+" => #{@timeline[t].join ', '}" }.join "\n"
+        else
+          ''
+        end
       end
 
       def inspect

data/lib/mtk/io/jsound_input.rb

@@ -50,7 +50,7 @@ module MTK
       def to_timeline(options={})
         bpm = options.fetch :bmp, 120
         beats_per_second = bpm.to_f/60
-        timeline = Timeline.new
+        timeline = MTK::Events::Timeline.new
         note_ons = {}
         start = nil
 
@@ -59,7 +59,13 @@ module MTK
           time -= start
           time /= beats_per_second
 
-          case message.type
+          message_type = message.type
+          message_type = :note_off if message_type == :note_on and message.velocity == 0
+          # TODO: this will need to be made more robust when we support off velocities
+
+          next if message_type == :unknown # Ignore garbage messages
+
+          case message_type
             when :note_on
               note_ons[message.pitch] = [message,time]
 
@@ -71,7 +77,7 @@ module MTK
                 timeline.add time,note
               end
 
-            else timeline.add time, MTK::Events::Parameter.from_midi([message.type, message.channel], message.data1, message.data2)
+            else timeline.add time, MTK::Events::Parameter.from_midi([message_type, message.channel], message.data1, message.data2)
           end
         end
 

data/lib/mtk/io/midi_file.rb

@@ -41,6 +41,10 @@ module MTK
               case event
                 when ::MIDI::NoteOn
                   note_ons[event.note] = [time,event]
+                  # TODO: handle note ons with velocity 0 as a note off (use output from Logic Pro as a test case)
+                  # This isn't actually necessary right now as midilibs seqreader#note_on automatically
+                  # converts note ons with velocity 0 to note offs. In the future, for full off velocity support,
+                  # I'll need to monkey patch midilib and update the code here
 
                 when ::MIDI::NoteOff
                   on_time,on_event = note_ons.delete(event.note)
@@ -99,7 +103,11 @@ module MTK
                 pitch, velocity = event.midi_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)
+                # TODO: use note_off events when supporting off velocities
+                # add_event track, time+duration => note_off(channel, pitch, velocity)
+                # NOTE: cannot test the following line of code properly right now, because midilib automatically converts
+                # note ons with velocity 0 to note offs when reading files. See comments in #to_timelines in this file
+                add_event track, time+duration => note_on(channel, pitch, 0) # we use note ons with velocity 0 to indicate no off velocity
 
               when :control
                 add_event track, time => cc(channel, event.number, event.midi_value)
@@ -182,8 +190,10 @@ module MTK
 
       def add_track sequence, opts={}
         track = ::MIDI::Track.new(sequence)
-        track.name = opts.fetch :name, ''
+        track_name = opts[:name]
+        track.name = track_name if track_name
         sequence.tracks << track
+        sequence.format = if sequence.tracks.length > 1 then 1 else 0 end
         track
       end
 
@@ -207,3 +217,29 @@ module MTK
 
 end
 
+
+####################################################################################
+# MONKEY PATCHING to prevent blank instrument name meta events from being generated
+# This can be removed if my pull request https://github.com/jimm/midilib/pull/5
+# is merged into midilib and a new gem is released with these changes.
+
+# @private
+module MIDI
+  module IO
+    class SeqWriter
+      alias original_write_instrument write_instrument
+      def write_instrument(instrument)
+        original_write_instrument(instrument) unless instrument.nil?
+      end
+
+      # Also monkey patching write_header to support alternate MIDI file formats
+      def write_header
+        @io.print 'MThd'
+        write32(6)
+        write16(@seq.format || 1)
+        write16(@seq.tracks.length)
+        write16(@seq.ppqn)
+      end
+    end
+  end
+end