jmtk 0.0.3.3-java

data/lib/mtk/core/interval.rb

@@ -0,0 +1,157 @@
+module MTK
+  module Core
+
+    # A measure of intensity, using an underlying value in the range 0.0-1.0
+    class Interval
+
+      include Comparable
+
+      # The preferred names of all pre-defined intervals
+      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.
+      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
+        ].freeze
+
+      # A mapping from intervals names to their value
+      VALUES_BY_NAME = Hash[ # a map from a list of name,value pairs
+          NAMES_BY_VALUE.map.with_index do |names,value|
+            names.map{|name| [name,value] }
+          end.flatten(1)
+      ].freeze
+
+      # All valid interval names
+      ALL_NAMES = NAMES_BY_VALUE.flatten.freeze
+
+
+      @flyweight = {}
+
+      # The number of semitones represented by this interval
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+      end
+
+      # Return an {Interval}, only constructing a new instance when not already in the flyweight cache
+      def self.[](value)
+        value = value.to_f unless value.is_a? Fixnum
+        @flyweight[value] ||= new(value)
+      end
+
+      class << self
+        alias :from_f :[]
+        alias :from_i :[]
+      end
+
+      # Lookup an interval duration by name.
+      def self.from_s(s)
+        value = VALUES_BY_NAME[s.to_s]
+        raise ArgumentError.new("Invalid Interval string '#{s}'") unless value
+        self[value]
+      end
+
+      class << self
+        alias :from_name :from_s
+      end
+
+      # The number of semitones as a floating point number
+      def to_f
+        @value.to_f
+      end
+
+      # The numerical value for the nearest whole number of semitones in this interval
+      def to_i
+        @value.round
+      end
+
+      def to_s
+        @value.to_s
+      end
+
+      def inspect
+        "#{self.class}<#{to_s} semitones>"
+      end
+
+      def ==( other )
+        other.is_a? MTK::Core::Interval and other.value == @value
+      end
+
+      def <=> other
+        if other.respond_to? :value
+          @value <=> other.value
+        else
+          @value <=> other
+        end
+      end
+
+      def + interval
+        if interval.is_a? MTK::Core::Interval
+          MTK::Core::Interval[@value + interval.value]
+        else
+          MTK::Core::Interval[@value + interval]
+        end
+      end
+
+      def -interval
+        if interval.is_a? MTK::Core::Interval
+          MTK::Core::Interval[@value - interval.value]
+        else
+          MTK::Core::Interval[@value - interval]
+        end
+      end
+
+      def * interval
+        if interval.is_a? MTK::Core::Interval
+          MTK::Core::Interval[@value * interval.value]
+        else
+          MTK::Core::Interval[@value * interval]
+        end
+      end
+
+      def / interval
+        if interval.is_a? MTK::Core::Interval
+          MTK::Core::Interval[to_f / interval.value]
+        else
+          MTK::Core::Interval[to_f / interval]
+        end
+      end
+
+      def -@
+        MTK::Core::Interval[@value * -1]
+      end
+
+      def coerce(other)
+        return MTK::Core::Interval[other], self
+      end
+
+    end
+  end
+
+  # Construct a {Duration} from any supported type
+  def Interval(*anything)
+    anything = anything.first if anything.length == 1
+    case anything
+      when Numeric then MTK::Core::Interval[anything]
+      when String, Symbol then MTK::Core::Interval.from_s(anything)
+      when Interval then anything
+      else raise "Interval doesn't understand #{anything.class}"
+    end
+  end
+  module_function :Interval
+
+end

data/lib/mtk/core/pitch.rb

@@ -0,0 +1,154 @@
+module MTK
+  module Core
+
+    # A frequency represented by a {PitchClass}, an integer octave, and an offset in semitones.
+    class Pitch
+
+      include Comparable
+
+      attr_reader :pitch_class, :octave, :offset
+
+      def initialize( pitch_class, octave, offset=0 )
+        @pitch_class, @octave, @offset = pitch_class, octave, offset
+        @value = @pitch_class.to_i + 12*(@octave+1) + @offset
+      end
+
+      @flyweight = {}
+
+      # Return a pitch with no offset, only constructing a new instance when not already in the flyweight cache
+      def self.[](pitch_class, octave)
+        pitch_class = MTK.PitchClass(pitch_class)
+        @flyweight[[pitch_class,octave]] ||= new(pitch_class, octave)
+      end
+
+      # Lookup a pitch by name, which consists of any {PitchClass::VALID_NAMES} and an octave number.
+      # The name may also be optionally suffixed by +/-###cents (where ### is any number).
+      # @example get the Pitch for middle C :
+      #         Pitch.from_s('C4')
+      # @example get the Pitch for middle C + 50 cents:
+      #         Pitch.from_s('C4+50cents')
+      def self.from_s( name )
+        s = name.to_s
+        s = s[0..0].upcase + s[1..-1].downcase # normalize name
+        if s =~ /^([A-G](#|##|b|bb)?)(-?\d+)(\+(\d+(\.\d+)?)cents)?$/
+          pitch_class = PitchClass.from_s($1)
+          if pitch_class
+            octave = $3.to_i
+            offset_in_cents = $5.to_f
+            if offset_in_cents.nil? or offset_in_cents.zero?
+              return self[pitch_class, octave]
+            else
+              return new( pitch_class, octave, offset_in_cents/100.0 )
+            end
+          end
+        end
+        raise ArgumentError.new("Invalid pitch name: #{name.inspect}")
+      end
+
+      class << self
+        alias :from_name :from_s
+      end
+
+      # Convert a Numeric semitones value into a Pitch
+      def self.from_f( f )
+        i, offset = f.floor, f%1  # split into int and fractional part
+        pitch_class = PitchClass.from_i(i)
+        octave = i/12 - 1
+        if offset == 0
+          self[pitch_class, octave]
+        else
+          new( pitch_class, octave, offset )
+        end
+      end
+
+      def self.from_h(hash)
+        new hash[:pitch_class], hash[:octave], hash.fetch(:offset,0)
+      end
+
+      # Convert a Numeric semitones value into a Pitch
+      def self.from_i( i )
+        from_f( i )
+      end
+
+      # The numerical value of this pitch
+      def to_f
+        @value
+      end
+
+      # The numerical value for the nearest semitone
+      def to_i
+        @value.round
+      end
+
+      def offset_in_cents
+        @offset * 100
+      end
+
+      def to_h
+        {:pitch_class => @pitch_class, :octave => @octave, :offset => @offset}
+      end
+
+      def to_s
+        "#{@pitch_class}#{@octave}" + (@offset.zero? ? '' : "+#{offset_in_cents.round}cents")
+      end
+
+      def inspect
+        "#<#{self.class}:#{object_id} @value=#{@value}>"
+      end
+
+      def ==( other )
+        other.respond_to? :pitch_class and other.respond_to? :octave and other.respond_to? :offset and
+        other.pitch_class == @pitch_class and other.octave == @octave and other.offset == @offset
+      end
+
+      def <=> other
+        @value <=> other.to_f
+      end
+
+      def + interval_in_semitones
+       self.class.from_f( @value + interval_in_semitones.to_f )
+      end
+      alias transpose +
+
+      def - interval_in_semitones
+        self.class.from_f( @value - interval_in_semitones.to_f )
+      end
+
+      def invert(center_pitch)
+        self + 2*(center_pitch.to_f - to_f)
+      end
+
+      def nearest(pitch_class)
+        self + self.pitch_class.distance_to(pitch_class)
+      end
+
+      def coerce(other)
+        return self.class.from_f(other.to_f), self
+      end
+
+      def clone_with(hash)
+        self.class.from_h(to_h.merge hash)
+      end
+
+    end
+  end
+
+  # Construct a {Pitch} from any supported type
+  def Pitch(*anything)
+    anything = anything.first if anything.length == 1
+    case anything
+      when Numeric then MTK::Core::Pitch.from_f(anything)
+      when String, Symbol then MTK::Core::Pitch.from_s(anything)
+      when MTK::Core::Pitch then anything
+      when Array
+        if anything.length == 2
+          MTK::Core::Pitch[*anything]
+        else
+          MTK::Core::Pitch.new(*anything)
+        end
+      else raise ArgumentError.new("Pitch doesn't understand #{anything.class}")
+    end
+  end
+  module_function :Pitch
+
+end

data/lib/mtk/core/pitch_class.rb

@@ -0,0 +1,194 @@
+module MTK
+  module Core
+
+    # 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
+    #
+    class PitchClass
+
+      # The normalized 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
+
+      # All enharmonic names of the 12 pitch classes, including sharps, flats, double-sharps, and double-flats,
+      # 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
+        %w( B#  C  Dbb ), #   0   #   C
+        %w( B## C# Db  ), #   1   #   Db
+        %w( C## D  Ebb ), #   2   #   D
+        %w( D#  Eb Fbb ), #   3   #   Eb
+        %w( D## E  Fb  ), #   4   #   E
+        %w( E#  F  Gbb ), #   5   #   F
+        %w( E## F# Gb  ), #   6   #   Gb
+        %w( F## G  Abb ), #   7   #   G
+        %w( G#     Ab  ), #   8   #   Ab
+        %w( G## A  Bbb ), #   9   #   A
+        %w( A#  Bb Cbb ), #  10   #   Bb
+        %w( A## B  Cb  )  #  11   #   B
+      ].freeze
+
+      # All valid enharmonic pitch class names in a flat list.
+      # @see VALID_NAMES_BY_VALUE
+      VALID_NAMES = VALID_NAMES_BY_VALUE.flatten.freeze
+
+      # A mapping from valid names to the value of the pitch class with that name
+      VALUES_BY_NAME = Hash[ # a map from a list of name,value pairs
+        VALID_NAMES_BY_VALUE.map.with_index do |valid_names,value|
+          valid_names.map{|name| [name,value] }
+        end.flatten(1)
+      ].freeze
+
+
+      # The name of this pitch class.
+      # One of the {NAMES} defined by this class.
+      attr_reader :name
+
+      # The value of this pitch class.
+      # An integer from 0..11 that indexes this pitch class in {PITCH_CLASSES} and the {#name} in {NAMES}.
+      attr_reader :value
+
+
+      private  ######
+      # Even though new is a private_class_method, YARD gets confused so we temporarily go private
+
+      def initialize(name, value)
+        @name, @value = name, value
+      end
+      private_class_method :new
+
+      @flyweight = {}
+
+      public   ######
+
+
+      # Lookup a PitchClass by name or value.
+      # @param name_or_value [String,Symbol,Numeric] one of {VALID_NAMES} or 0..12
+      # @return the PitchClass representing the argument
+      # @raise ArgumentError for arguments that cannot be converted to a PitchClass
+      def self.[] name_or_value
+        @flyweight[name_or_value] ||= case name_or_value
+          when String,Symbol then from_name(name_or_value)
+          when Numeric       then from_value(name_or_value.round)
+          else raise ArgumentError.new("PitchClass.[] doesn't understand #{name_or_value.class}")
+        end
+      end
+
+      # Lookup a PitchClass by name.
+      # @param name [String,#to_s] one of {VALID_NAMES} (case-insensitive)
+      def self.from_name(name)
+        @flyweight[name] ||= (
+          valid_name = name.to_s.capitalize
+          value = VALUES_BY_NAME[valid_name] or raise ArgumentError.new("Invalid PitchClass name: #{name}")
+          new(valid_name,value)
+        )
+      end
+
+      class << self
+        alias from_s from_name
+      end
+
+      # All 12 pitch classes in the chromatic scale.
+      # The index of each pitch class is the pitch class's numeric {#value}.
+      PITCH_CLASSES = NAMES.map{|name| from_name name }.freeze
+
+      # return the pitch class with the given integer value mod 12
+      # @param value [Integer,#to_i]
+      def self.from_value(value)
+        PITCH_CLASSES[value.to_i % 12]
+      end
+
+      class << self
+        alias from_i from_value
+      end
+
+      # return the pitch class with the given float rounded to the nearest integer, mod 12
+      # @param value [Float,#to_f]
+      def self.from_f(value)
+        from_i value.to_f.round
+      end
+
+      # Compare 2 pitch classes for equal values.
+      # @param other [PitchClass]
+      # @return true if this pitch class's value is equal to the other pitch class's value
+      def == other
+        other.is_a? PitchClass and other.value == @value
+      end
+
+      # Compare a pitch class with another pitch class or integer value
+      # @param other [PitchClass,#to_i]
+      # @return -1, 0, or +1 depending on whether this pitch class's value is less than, equal to, or greater than the other object's integer value
+      # @see http://ruby-doc.org/core-1.9.3/Comparable.html
+      def <=> other
+        @value <=> other.to_i
+      end
+
+      # This pitch class's normalized {#name}.
+      # @see NAMES
+      def to_s
+        @name.to_s
+      end
+
+      # This pitch class's integer {#value}
+      def to_i
+        @value.to_i
+      end
+
+      # This pitch class's {#value} as a floating point number
+      def to_f
+        @value.to_f
+      end
+
+      # Transpose this pitch class by adding it's value to the value given (mod 12)
+      # @param interval [PitchClass,Float,#to_f]
+      def + interval
+        new_value = (value + interval.to_f).round
+        self.class.from_value new_value
+      end
+      alias transpose +
+
+      # Transpose this pitch class by subtracing the given value from this value (mod 12)
+      # @param interval [PitchClass,Float,#to_f]
+      def - interval
+        new_value = (value - interval.to_f).round
+        self.class.from_value new_value
+      end
+
+      # Inverts (mirrors) the pitch class around the given center
+      # @param center [PitchClass,Pitch,Float,#to_f] the value to "mirror" this pitch class around
+      def invert(center)
+        delta = (2*(center.to_f - value)).round
+        self + delta
+      end
+
+      # the smallest interval in semitones that needs to be added to this PitchClass to reach the given PitchClass
+      # @param pitch_class [PitchClass,#value]
+      def distance_to(pitch_class)
+        delta = (pitch_class.value - value) % 12
+        if delta > 6
+          delta -= 12
+        elsif delta == 6 and to_i >= 6
+          # this is a special edge case to prevent endlessly ascending pitch sequences when alternating between two pitch classes a tritone apart
+          delta = -6
+        end
+        delta
+      end
+
+    end
+  end
+
+  # Construct a {PitchClass} from any supported type
+  # @param anything [PitchClass,String,Symbol,Numeric]
+  def PitchClass(anything)
+    case anything
+      when Numeric then MTK::Core::PitchClass.from_f(anything)
+      when String, Symbol then MTK::Core::PitchClass.from_s(anything)
+      when MTK::Core::PitchClass then anything
+      else raise ArgumentError.new("PitchClass doesn't understand #{anything.class}")
+    end
+  end
+  module_function :PitchClass
+
+end