music-transcription 0.3.0

data/lib/music-transcription/link.rb

@@ -0,0 +1,115 @@
+module Music
+module Transcription
+
+# Defines a relationship (tie, slur, legato, etc.) to a note with a certain pitch.
+#
+# @author James Tunnell
+#
+# @!attribute [rw] target_pitch
+#   @return [Pitch] The pitch of the note which is being connected to.
+#
+# @!attribute [rw] relationship
+#   @return [Symbol] The relationship between the current note and a consecutive
+#                    note. Valid values are RELATIONSHIP_NONE, RELATIONSHIP_TIE,
+#                    RELATIONSHIP_SLUR, RELATIONSHIP_LEGATO, RELATIONSHIP_GLISSANDO, 
+#                    and RELATIONSHIP_PORTAMENTO.
+#
+class Link
+  include Hashmake::HashMakeable
+  
+  # no relationship with the following note
+  RELATIONSHIP_NONE = :none
+  # tie to the following note
+  RELATIONSHIP_TIE = :tie
+  # play notes continuously and don't rearticulate
+  RELATIONSHIP_SLUR = :slur
+  # play notes continuously and do rearticulate
+  RELATIONSHIP_LEGATO = :legato
+  # play an uninterrupted slide through a series of consecutive tones to the next note.
+  RELATIONSHIP_GLISSANDO = :glissando
+  # play an uninterrupted glide to the next note.
+  RELATIONSHIP_PORTAMENTO = :portamento
+  
+  # a list of valid note relationships
+  RELATIONSHIPS = [
+    RELATIONSHIP_NONE,
+    RELATIONSHIP_TIE,
+    RELATIONSHIP_SLUR,
+    RELATIONSHIP_LEGATO,
+    RELATIONSHIP_GLISSANDO,
+    RELATIONSHIP_PORTAMENTO
+  ]
+
+  # hashed-arg specs (for hash-makeable idiom)
+  ARG_SPECS = {
+    :target_pitch => arg_spec(:reqd => false, :type => Pitch, :default => ->(){ Pitch.new }),
+    :relationship => arg_spec(:reqd => false, :type => Symbol, :default => RELATIONSHIP_NONE, :validator => ->(a){ RELATIONSHIPS.include?(a)}),
+  }
+
+  attr_reader :target_pitch, :relationship
+  
+  # A new instance of Link.
+  # @param [Hash] args Hashed arguments. See ARG_SPECS for details about valid keys.
+  def initialize args={}
+    hash_make args
+  end
+  
+  # Produce an identical Link object.
+  def clone
+    Link.new(:target_pitch => @target_pitch.clone, :relationship => @relationship)
+  end
+  
+  # Compare equality of two Link objects.
+  def ==(other)
+    return (@target_pitch == other.target_pitch) && (@relationship == other.relationship)
+  end
+
+  # Set the pitch of the note being connected to.
+  # @param [Pitch] target_pitch The pitch of the note being connected to.
+  # @raise [ArgumentError] if target_pitch is not a Pitch.
+  def target_pitch= target_pitch
+    ARG_SPECS[:target_pitch].validate_value target_pitch
+    @target_pitch = target_pitch
+  end
+
+  # Set the note relationship.
+  # @param [Symbol] relationship The relationship of the note to the following 
+  #                  note (if applicable). Valid relationship are given by the 
+  #                  RELATIONSHIPS constant.
+  # @raise [ArgumentError] if relationship is not a valid relationship.
+  def relationship= relationship
+    ARG_SPECS[:relationship].validate_value relationship
+    @relationship = relationship
+  end
+  
+end
+
+module_function
+
+# helper method to create a Link object with GLISSANDO relationship.
+def glissando pitch
+  Link.new(:target_pitch => pitch, :relationship => Link::RELATIONSHIP_GLISSANDO)
+end
+
+# helper method to create a Link object with LEGATO relationship.
+def legato pitch
+  Link.new(:target_pitch => pitch, :relationship => Link::RELATIONSHIP_LEGATO)
+end
+
+# helper method to create a Link object with PORTAMENTO relationship.
+def portamento pitch
+  Link.new(:target_pitch => pitch, :relationship => Link::RELATIONSHIP_PORTAMENTO)
+end
+
+# helper method to create a Link object with SLUR relationship.
+def slur pitch
+  Link.new(:target_pitch => pitch, :relationship => Link::RELATIONSHIP_SLUR)
+end
+
+# helper method to create a Link object with TIE relationship.
+def tie pitch
+  Link.new(:target_pitch => pitch, :relationship => Link::RELATIONSHIP_TIE)
+end
+
+end
+end

data/lib/music-transcription/note.rb

@@ -0,0 +1,156 @@
+module Music
+module Transcription
+
+# Abstraction of a musical note. The note can contain multiple intervals
+# (at different pitches). Each interval can also contain a link to an interval
+# in a following note. Contains values for attack, sustain, and separation,
+# which will be used to form the envelope profile for the note.
+#
+# @author James Tunnell
+# 
+# @!attribute [rw] duration
+#   @return [Numeric] The duration (in, say note length or time), greater than 0.0.
+#
+# @!attribute [rw] intervals
+#   @return [Numeric] The intervals that define which pitches are part of the
+#                     note and can link to intervals in a following note.
+# 
+# @!attribute [rw] attack
+#   @return [Numeric] The amount of attack, from 0.0 (less) to 1.0 (more).
+#                     Attack controls how quickly a note's loudness increases
+#                     at the start.
+#
+# @!attribute [rw] sustain
+#   @return [Numeric] The amount of sustain, from 0.0 (less) to 1.0 (more).
+#                     Sustain controls how much the note's loudness is 
+#                     sustained after the attack.
+#
+# @!attribute [rw] separation
+#   @return [Numeric] Shift the note release towards or away the beginning
+#                   of the note. From 0.0 (towards end of the note) to 
+#                   1.0 (towards beginning of the note).
+#
+class Note
+  include Hashmake::HashMakeable
+  attr_reader :duration, :intervals, :sustain, :attack, :separation
+
+  # hashed-arg specs (for hash-makeable idiom)
+  ARG_SPECS = {
+    :duration => arg_spec(:type => Numeric, :reqd => true, :validator => ->(a){ a > 0 } ),
+    :intervals => arg_spec_array(:type => Interval, :reqd => false),
+    :sustain => arg_spec(:type => Numeric, :reqd => false, :validator => ->(a){ a.between?(0.0,1.0)}, :default => 0.5),
+    :attack => arg_spec(:type => Numeric, :reqd => false, :validator => ->(a){ a.between?(0.0,1.0)}, :default => 0.5),
+    :separation => arg_spec(:type => Numeric, :reqd => false, :validator => ->(a){ a.between?(0.0,1.0)}, :default => 0.5),
+  }
+  
+  # A new instance of Note.
+  # @param [Hash] args Hashed arguments. See Note::ARG_SPECS for details.
+  def initialize args={}
+    hash_make args
+  end
+  
+  # Compare the equality of another Note object.
+  def == other
+    return (@duration == other.duration) &&
+    (@intervals == other.intervals) &&
+    (@sustain == other.sustain) &&
+    (@attack == other.attack) &&
+    (@separation == other.separation)
+  end
+
+  # Set the note duration.
+  # @param [Numeric] duration The duration to use.
+  # @raise [ArgumentError] if duration is not greater than 0.
+  def duration= duration
+    ARG_SPECS[:duration].validate_value duration
+    @duration = duration
+  end  
+  
+  # Set the note sustain.
+  # @param [Numeric] sustain The sustain of the note.
+  # @raise [ArgumentError] if sustain is not a Numeric.
+  # @raise [RangeError] if sustain is outside the range 0.0..1.0.
+  def sustain= sustain
+    ARG_SPECS[:sustain].validate_value sustain
+    @sustain = sustain
+  end
+
+  # Set the note attack.
+  # @param [Numeric] attack The attack of the note.
+  # @raise [ArgumentError] if attack is not a Numeric.
+  # @raise [RangeError] if attack is outside the range 0.0..1.0.
+  def attack= attack
+    ARG_SPECS[:attack].validate_value attack
+    @attack = attack
+  end
+
+  # Set the note separation.
+  # @param [Numeric] separation The separation of the note.
+  # @raise [ArgumentError] if separation is not a Numeric.
+  # @raise [RangeError] if separation is outside the range 0.0..1.0.
+  def separation= separation
+    ARG_SPECS[:separation].validate_value separation
+    @separation = separation
+  end
+  
+  # Produce an identical Note object.
+  def clone
+    Marshal.load(Marshal.dump(self))
+  end
+ 
+  # Remove any duplicate intervals (occuring on the same pitch), removing
+  # all but the last occurance. Remove any duplicate links (links to the
+  # same interval), removing all but the last occurance.
+  def remove_duplicates
+    # in case of duplicate notes
+    intervals_to_remove = Set.new
+    for i in (0...@intervals.count).entries.reverse
+      @intervals.each_index do |j|
+        if j < i
+          if @intervals[i].pitch == @intervals[j].pitch
+            intervals_to_remove.add @intervals[j]
+          end
+        end
+      end
+    end
+    @intervals.delete_if { |interval| intervals_to_remove.include? interval}
+    
+    # in case of duplicate links
+    for i in (0...@intervals.count).entries.reverse
+      @intervals.each_index do |j|
+        if j < i
+          if @intervals[i].linked? && @intervals[j].linked? && @intervals[i].link.target_pitch == @intervals[j].link.target_pitch
+            @intervals[j].link = Link.new
+          end
+        end
+      end
+    end
+  end
+
+  def transpose pitch_diff
+    self.clone.transpose! pitch_diff
+  end
+
+  def transpose! pitch_diff
+    @intervals.each do |interval|
+      interval.pitch += pitch_diff
+      interval.link.target_pitch += pitch_diff
+    end
+    return self
+  end
+  
+  def to_s
+    "#{duration}:#{intervals.map{|i| i.pitch}.inspect}"
+  end
+end
+
+module_function
+
+def note duration, intervals = [], other_args = {}
+  Note.new(
+    { :duration => duration, :intervals => intervals }.merge other_args
+  )
+end
+
+end
+end

data/lib/music-transcription/part.rb

@@ -0,0 +1,128 @@
+require 'yaml'
+
+module Music
+module Transcription
+
+# Abstraction of a musical part. Contains start offset, notes, and loudness_profile settings.
+#
+# @author James Tunnell
+#
+# @!attribute [rw] offset
+#   @return [Numeric] The offset where the part begins.
+#
+# @!attribute [rw] notes
+#   @return [Array] The notes to be played.
+#
+# @!attribute [rw] loudness_profile
+#   @return [Profile] The parts loudness_profile profile.
+#
+class Part
+  include Hashmake::HashMakeable
+  attr_reader :offset, :loudness_profile, :notes
+  
+  # hashed-arg specs (for hash-makeable idiom)
+  ARG_SPECS = {
+    :offset => arg_spec(:reqd => false, :type => Numeric, :default => 0),
+    :loudness_profile => arg_spec(:reqd => false, :type => Profile, :validator => ->(a){ a.values_between?(0.0,1.0) }, :default => ->(){ Profile.new(:start_value => 0.5) }),
+    :notes => arg_spec_array(:reqd => false, :type => Note),
+  }
+  
+  # A new instance of Part.
+  # @param [Hash] args Hashed arguments. Valid optional keys are :loudness_profile, 
+  #                    :notes, and :offset.
+  def initialize args = {}
+    hash_make args, Part::ARG_SPECS
+  end
+  
+  # Produce an exact copy of the current object
+  def clone
+    Marshal.load(Marshal.dump(self))
+  end
+  
+  # Compare the equality of another Part object.
+  def ==(other)
+    return (@offset == other.offset) &&
+    (@loudness_profile == other.loudness_profile) &&
+    (@notes == other.notes)
+  end
+
+  # Set the start offset of the part.
+  # @param [Numeric] offset The start offset of the part.
+  # @raise [ArgumentError] unless offset is a Numeric.
+  def offset= offset
+    ARG_SPECS[:offset].validate_value offset
+    @offset = offset
+  end
+
+  # Set the loudness_profile Profile.
+  # @param [Tempo] loudness_profile The Profile for part loudness_profile.
+  # @raise [ArgumentError] if loudness_profile is not a Profile.
+  def loudness_profile= loudness_profile
+    ARG_SPECS[:loudness_profile].validate_value loudness_profile
+    @loudness_profile = loudness_profile
+  end
+
+  # Duration of part notes.
+  def duration
+    total_duration = @notes.inject(0) { |sum, note| sum + note.duration }
+    return @offset + total_duration
+  end
+  
+  # offset where part begins
+  def start
+    return @offset
+  end
+
+  # offset where part ends
+  def end
+    return @offset + duration
+  end
+  
+  def transpose pitch_diff
+    self.clone.transpose! pitch_diff
+  end
+
+  def transpose! pitch_diff
+    @notes.each do |note|
+      note.transpose! pitch_diff
+    end
+    return self
+  end 
+end
+
+class PartFile < Part
+  include Hashmake::HashMakeable
+  attr_reader :file_path
+  
+  # hashed-arg specs (for hash-makeable idiom)
+  ARG_SPECS = {
+    :file_path => arg_spec(:reqd => true, :type => String, :validator => ->(a){ File.exist? a })
+  }
+  
+  # A new instance of Part.
+  # @param [Hash] args Hashed arguments. Only valid keys is :file_path.
+  def initialize args
+    hash_make args, PartFile::ARG_SPECS
+    
+    unless @file_path.nil?
+      obj = YAML.load_file @file_path
+      
+      if obj.is_a?(Part)
+        super(:offset => obj.offset, :notes => obj.notes, :loudness_profile => obj.loudness_profile)
+      elsif obj.is_a?(Hash)
+        super(obj)
+      else
+        raise ArgumentError, "Expected a Hash or Part object"
+      end
+    end
+  end
+
+  # Produce an exact copy of the current object
+  def clone
+    Marshal.load(Marshal.dump(self))
+  end
+
+end
+
+end
+end

data/lib/music-transcription/pitch.rb

@@ -0,0 +1,297 @@
+module Music
+module Transcription
+
+# Abstraction of a musical pitch. Contains values for octave, semitone, 
+# and cent. These values are useful because they allow simple mapping to
+# both the abstract (musical scales) and concrete (audio data).
+#
+# Fundamentally, pitch can be considered a ratio to some base number. 
+# For music, this is a base frequency. The pitch frequency can be 
+# determined by multiplying the base frequency by the pitch ratio. For 
+# the standard musical scale, the base frequency of C0 is 16.35 Hz.
+# 
+# Octaves represent the largest means of differing two pitches. Each 
+# octave added will double the ratio. At zero octaves, the ratio is 
+# 1.0. At one octave, the ratio will be 2.0. Each semitone and cent 
+# is an increment of less-than-power-of-two.
+#
+# Semitones are the primary steps between octaves. By default, the 
+# number of semitones per octave is 12, corresponding to the twelve-tone equal 
+# temperment tuning system. The number of semitones per octave can be 
+# modified at runtime by overriding the Pitch::SEMITONES_PER_OCTAVE 
+# constant.
+#
+# Cents are the smallest means of differing two pitches. By default, the 
+# number of cents per semitone is 100 (hence the name cent, as in per-
+# cent). This number can be modified at runtime by overriding the 
+# Pitch::CENTS_PER_SEMITONE constant.
+#
+# @author James Tunnell
+# 
+# @!attribute [r] octave
+#   @return [Fixnum] The pitch octave.
+# @!attribute [r] semitone
+#   @return [Fixnum] The pitch semitone.
+# @!attribute [r] cent
+#   @return [Fixnum] The pitch cent.
+# @!attribute [r] cents_per_octave
+#   @return [Fixnum] The number of cents per octave. Default is 1200 
+#    				 (12 x 100). If a different scale is required, 
+#                    modify CENTS_PER_SEMITONE (default 12) and/or 
+#                    SEMITONES_PER_OCTAVE (default 100).
+# @!attribute [r] base_freq
+#   @return [Numeric] Multiplied with pitch ratio to determine the final frequency
+#                   of the pitch. Defaults to DEFAULT_BASE_FREQ, but can be set 
+#                   during initialization to something else using the :base_freq key.
+#
+class Pitch
+  include Comparable
+  include Hashmake::HashMakeable
+  attr_reader :cents_per_octave, :base_freq, :octave, :semitone, :cent
+
+  #The default number of semitones per octave is 12, corresponding to 
+  # the twelve-tone equal temperment tuning system.
+  SEMITONES_PER_OCTAVE = 12
+
+  #The default number of cents per semitone is 100 (hence the name cent,
+  # as in percent).
+  CENTS_PER_SEMITONE = 100
+  
+  # The default base ferquency is C0
+  DEFAULT_BASE_FREQ = 16.351597831287414
+
+  # hashed-arg specs (for hash-makeable idiom)
+  ARG_SPECS = {
+    :octave => arg_spec(:reqd => false, :type => Fixnum, :default => 0),
+    :semitone => arg_spec(:reqd => false, :type => Fixnum, :default => 0), 
+    :cent => arg_spec(:reqd => false, :type => Fixnum, :default => 0), 
+    :base_freq => arg_spec(:reqd => false, :type => Numeric, :validator => ->(a){ a > 0.0 }, :default => DEFAULT_BASE_FREQ)
+  }
+  
+  # A new instance of Pitch.
+  # @param [Hash] args Hashed args. See ARG_SPECS for details.
+  # @raise [ArgumentError] if any of :octave, :semitone, or :cent is
+  #                        not a Fixnum.
+  def initialize args={}
+    @cents_per_octave = CENTS_PER_SEMITONE * SEMITONES_PER_OCTAVE
+    hash_make args
+    normalize!
+  end
+
+  # Set @base_freq, which is used with the pitch ratio to produce the
+  # pitch frequency.
+  def base_freq= base_freq
+    ARG_SPECS[:base_freq].validate_value base_freq
+    @base_freq = base_freq
+  end
+  
+  # Set @octave.
+  def octave= octave
+    ARG_SPECS[:octave].validate_value octave
+    @octave = octave
+  end
+  
+  # Set semitone.
+  def semitone= semitone
+    ARG_SPECS[:semitone].validate_value semitone
+    @semitone = semitone
+  end
+  
+  # Set @cent.
+  def cent= cent
+    ARG_SPECS[:cent].validate_value cent
+    @cent = cent
+  end
+
+  # Return the pitch's frequency, which is determined by multiplying the base 
+  # frequency and the pitch ratio. Base frequency defaults to DEFAULT_BASE_FREQ,
+  # but can be set during initialization to something else by specifying the 
+  # :base_freq key.
+  def freq
+    return self.ratio() * @base_freq
+  end
+  
+  # Set the pitch according to the given frequency. Uses the current base_freq 
+  # to determine what the pitch ratio should be, and sets it accordingly.
+  def freq= freq
+    self.ratio = freq / @base_freq
+  end
+
+  # Calculate the total cent count. Converts octave and semitone count
+  # to cent count before adding to existing cent count.
+  # @return [Fixnum] total cent count
+  def total_cent
+    return (@octave * @cents_per_octave) +
+            (@semitone * CENTS_PER_SEMITONE) + @cent
+  end
+  
+  # Set the Pitch ratio according to a total number of cents.
+  # @param [Fixnum] cent The total number of cents to use.
+  # @raise [ArgumentError] if cent is not a Fixnum
+  def total_cent= cent
+    raise ArgumentError, "cent is not a Fixnum" if !cent.is_a?(Fixnum)
+    @octave, @semitone, @cent = 0, 0, cent
+    normalize!
+  end
+
+  # Calculate the pitch ratio. Raises 2 to the power of the total cent 
+  # count divided by cents-per-octave.
+  # @return [Float] ratio
+  def ratio
+    2.0**(self.total_cent.to_f / @cents_per_octave)
+  end
+
+  # Represent the Pitch ratio according to a ratio.
+  # @param [Numeric] ratio The ratio to represent.
+  # @raise [RangeError] if ratio is less than or equal to 0.0
+  def ratio= ratio
+    raise RangeError, "ratio #{ratio} is less than or equal to 0.0" if ratio <= 0.0
+    
+    x = Math.log2 ratio
+    self.total_cent = (x * @cents_per_octave).round
+  end
+
+  # Round to the nearest semitone.
+  def round
+    self.clone.round!
+  end
+
+  # Round to the nearest semitone.
+  def round!
+    if @cent >= (CENTS_PER_SEMITONE / 2)
+      @semitone += 1
+    end
+    @cent = 0
+    normalize!
+    return self
+  end
+  
+  # Calculates the number of semitones which would represent the pitch's
+  # octave and semitone count. Excludes cents.
+  def total_semitone
+    return (@octave * SEMITONES_PER_OCTAVE) + @semitone
+  end
+  
+  # Override default hash method.
+  def hash
+    return self.total_cent
+  end
+  
+  # Compare pitch equality using total cent
+  def ==(other)
+    self.total_cent == other.total_cent
+  end
+  
+  # Compare pitches. A higher ratio or total cent is considered larger.
+  # @param [Pitch] other The pitch object to compare.
+  def <=> (other)
+    self.total_cent <=> other.total_cent
+  end
+
+  # Add pitches by adding the total cent count of each.
+  # @param [Pitch] other The pitch object to add. 
+  def + (other)
+    self.class.new :octave => (@octave + other.octave), :semitone => (@semitone + other.semitone), :cent => (@cent + other.cent)
+  end
+
+  # Add pitches by subtracting the total cent count.
+  # @param [Pitch] other The pitch object to subtract.
+  def - (other)
+    self.class.new :octave => (@octave - other.octave), :semitone => (@semitone - other.semitone), :cent => (@cent - other.cent)
+  end
+  
+  # Produce an identical Pitch object.
+  def clone
+    Marshal.load(Marshal.dump(self))
+  end
+  
+  # Balance out the octave, semitone, and cent count. 
+  def normalize!
+    centTotal = (@octave * @cents_per_octave) + (@semitone * CENTS_PER_SEMITONE) + @cent
+    
+    @octave = centTotal / @cents_per_octave
+    centTotal -= @octave * @cents_per_octave
+    
+    @semitone = centTotal / CENTS_PER_SEMITONE
+    centTotal -= @semitone * CENTS_PER_SEMITONE
+    
+    @cent = centTotal
+    return self
+  end
+
+  # Produce a string representation of a pitch (e.g. "C2")
+  def to_s
+    if @cents_per_octave != 1200
+      raise "Don't know how to produce a string representation since cents_per_octave is not 1200."
+    end
+    
+    semitone_str = case @semitone
+    when 0 then "C"
+    when 1 then "Db"
+    when 2 then "D"
+    when 3 then "Eb"
+    when 4 then "E"
+    when 5 then "F"
+    when 6 then "Gb"
+    when 7 then "G"
+    when 8 then "Ab"
+    when 9 then "A"
+    when 10 then "Bb"
+    when 11 then "B"
+    end
+    
+    return semitone_str + @octave.to_s
+  end
+  
+  def self.make_from_freq(freq, base_freq = DEFAULT_BASE_FREQ)
+    pitch = Pitch.new()
+    pitch.ratio = freq / base_freq
+    return pitch
+  end
+end
+
+end
+end
+
+class String
+  # Create a Pitch object from a string (e.g. "C2"). String can contain a letter (A-G),
+  # to indicate the semitone, followed by an optional sharp/flat (#/b) and then the
+  # octave number (non-negative integer).
+  def to_pitch
+    string = self
+    if string =~ /[AaBbCcDdEeFfGg][#b][\d]+/
+      semitone = letter_to_semitone string[0]
+      semitone = case string[1]
+      when "#" then semitone + 1
+      when "b" then semitone - 1
+      else raise ArgumentError, "unexpected symbol found"
+      end
+      octave = string[2..-1].to_i
+      return Music::Transcription::Pitch.new(:octave => octave, :semitone => semitone)
+    elsif string =~ /[AaBbCcDdEeFfGg][\d]+/
+      semitone = letter_to_semitone string[0]
+      octave = string[1..-1].to_i
+      return Music::Transcription::Pitch.new(:octave => octave, :semitone => semitone)
+    else
+      raise ArgumentError, "string #{string} cannot be converted to a pitch"
+    end    
+  end
+
+  private
+  
+  def letter_to_semitone letter
+    semitone = case letter
+    when /[Cc]/ then 0
+    when /[Dd]/ then 2
+    when /[Ee]/ then 4
+    when /[Ff]/ then 5
+    when /[Gg]/ then 7
+    when /[Aa]/ then 9
+    when /[Bb]/ then 11
+    else raise ArgumentError, "invalid letter \"#{letter}\" given"
+    end
+    
+    return semitone
+  end
+
+end