tonal-tools 8.3.2 → 8.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edaeefa4c9e85628de77bdc793e7bf185c66b7f77449201180972798bc8c03e4
-  data.tar.gz: c084919a42c7d53a030b208dfcadb3b6b3435a2da23393736ca7aa8a697a0866
+  metadata.gz: bdb178eb44ac2841a878052e7ec184d97dbe4b992596c4fc849ba7cbd8c08538
+  data.tar.gz: 59043afa410a203fb83c361e8f580a60e2c81903d4b95153ed5f8a8e3285a68e
 SHA512:
-  metadata.gz: 391772bbd5096b18ced768e099f093b5d477a022cd6540a858129abddd5479d00a36e717c81a72af5c5251f71ff5de8ebe7bd6265e168993c58e00f44038562c
-  data.tar.gz: 1d90f075280b353130e0df41f21b8993b614fa82c22dd9513ba135641895b86efc570face1f389427837ee5bfb6ffcbfa0619bcfe819b731b59a6f66e1e3f67b
+  metadata.gz: cbc32bccbf514a8abce43f1627b1795d8517091a452be252325317958075c1c9a13a407f389b12c93426c6786feedfb00c1bb777368e0c625440de605d734cfe
+  data.tar.gz: 86d55133cdd853c597d07fdd1017d674aa8cc1898dbe560a31c556877ae2c1567b262bcfd43b68eab9e67f0fe44267d0f02f9c770f5032ca66d4e53a922abab4

data/lib/tonal/attributions.rb

@@ -1,4 +1,4 @@
 module Tonal
   TOOLS_PRODUCER = "mTonal"
-  TOOLS_VERSION = "8.3.2"
+  TOOLS_VERSION = "8.3.4"
 end

data/lib/tonal/cents.rb

@@ -3,6 +3,7 @@ class Tonal::Cents
   include Comparable
 
   def_delegators :@log, :logarithm, :logarithmand, :base
+  def_delegators :@ratio, :numerator, :denominator, :to_reduced_ratio, :to_ratio
 
   HUNDREDTHS_ROUNDOFF = -2
   FLOAT_PRECISION = 100
@@ -40,6 +41,8 @@ class Tonal::Cents
     end
   end
 
+  alias :reduced_ratio :to_reduced_ratio
+
   # @return [Tonal::Cents] the default cents tolerance
   # @example
   #   Tonal::Cents.default_tolerance => 5
@@ -149,8 +152,8 @@ class Tonal::Cents
   end
 
   def derive_ratio(log: nil, ratio: nil)
-    return Tonal::ReducedRatio.new(log.logarithmand) if log
-    Tonal::ReducedRatio.new(ratio.numerator, ratio.denominator)
+    return Tonal::Ratio.new(log.logarithmand) if log
+    Tonal::Ratio.new(ratio.numerator, ratio.denominator)
   end
 
   def derive_cents(cents: nil, log: nil)

data/lib/tonal/extensions.rb

@@ -145,10 +145,13 @@ class Numeric
   # @return [Float] the cents difference between self and its step in the given modulo
   # @example
   #   (3/2r).efficiency(12) => -1.96
-  # @param modulo
-  # @param reduced
+  # @example
+  #   (3/2r).efficiency(12, is_step_efficiency: true) => 1.96
+  # @param modulo against which the difference of self is compared
+  # @param reduced if true, self is reduced to the octave before calculating efficiency
+  # @param is_step_efficiency if true, calculates the efficiency of the step instead of the ratio (self). If the step efficiency is X cents, then the ratio efficiency is -X cents.
   #
-  def efficiency(modulo, reduced: false) = ratio(reduced:).efficiency(modulo)
+  def efficiency(modulo, reduced: false, is_step_efficiency: false) = ratio(reduced:).efficiency(modulo, is_step_efficiency:)
 
   # @return [Tonal::Interval] beween self (upper) and ratio (lower)
   # @example

data/lib/tonal/hertz.rb

@@ -15,9 +15,9 @@ class Tonal::Hertz
 
   # @return [Tonal::Hertz] 440 Hz
   # @example
-  #   Tonal::Hertz.a440 => 440.0 Hz
+  #   Tonal::Hertz.reference => 440.0 Hz
   #
-  def self.a440
+  def self.reference
     self.new(440.0)
   end
 
@@ -29,7 +29,6 @@ class Tonal::Hertz
     Rational(value)
   end
 
-
   # @return [Rational] self as a float
   # @example
   #   Tonal::Hertz.new(440).to_f => 440.0
@@ -38,6 +37,15 @@ class Tonal::Hertz
     value.to_f
   end
 
+  # @return [Tonal::Cents] the cents difference between self and a reference frequency
+  # @example
+  #   Tonal::Hertz.new(880).to_cents => 1200.0
+  # @param reference [Tonal::Hertz, Numeric] the reference frequency to compare to
+  #
+  def to_cents(reference: self.class.reference)
+    Tonal::Cents.new(ratio: to_r / reference.to_r)
+  end
+
   # @return [String] the string representation of Tonal::Hertz
   # @example
   #   Tonal::Hertz(1000.0).inspect => "1000.0 Hz"

data/lib/tonal/ratio.rb

@@ -5,6 +5,7 @@ class Tonal::Ratio
   def_delegators :@approximation, :neighborhood
 
   PRECISION = 2
+  DEFAULT_EQUAVE = 2/1r
 
   attr_reader :antecedent, :consequent, :equave, :reduced_antecedent, :reduced_consequent
 
@@ -16,7 +17,7 @@ class Tonal::Ratio
   # @param antecedent [Numeric, Tonal::Ratio]
   # @param consequent [Numeric, Tonal::Ratio]
   #
-  def initialize(antecedent, consequent=nil, label: nil, equave: 2/1r)
+  def initialize(antecedent, consequent=nil, label: nil, equave: DEFAULT_EQUAVE)
     raise ArgumentError, "Antecedent must be Numeric" unless antecedent.kind_of?(Numeric)
     raise ArgumentError, "Consequent must be Numeric or nil" unless (consequent.kind_of?(Numeric) || consequent.nil?)
 
@@ -79,8 +80,8 @@ class Tonal::Ratio
   # @param step the step number in the equal division of the equave
   # @param equave the interval of equivalence, default 2/1
   #
-  def self.ed(step, modulo, equave: 2/1r)
-    self.new(2**(step.to_f/modulo), equave: equave)
+  def self.ed(step, modulo, equave: DEFAULT_EQUAVE)
+    self.new(2**(step.to_f/modulo), equave:)
   end
 
   # @return [Boolean] if pair of ratios are within the given cents limit
@@ -213,7 +214,7 @@ class Tonal::Ratio
   #   Tonal::Ratio.new(48,14).equave_reduce(3) => 8/7
   # @param equave Numeric
   #
-  def equave_reduce(equave=2/1r)
+  def equave_reduce(equave=DEFAULT_EQUAVE)
     self.class.new(*_equave_reduce(equave))
   end
   alias :reduce :equave_reduce
@@ -224,7 +225,7 @@ class Tonal::Ratio
   #   Tonal::Ratio.new(48,14).equave_reduce!(3) => 8/7
   # @param equave Numeric
   #
-  def equave_reduce!(equave=2/1r)
+  def equave_reduce!(equave=DEFAULT_EQUAVE)
     @antecedent, @consequent = _equave_reduce(equave)
     self
   end
@@ -430,10 +431,10 @@ class Tonal::Ratio
   #   Tonal::ReducedRatio.new(3,2).efficiency(12) => -1.96
   # @param modulo against which the difference of self is compared
   #
-  def efficiency(modulo)
-    # We want the efficiency from the ratio (self).
+  def efficiency(modulo, is_step_efficiency: false)
+    # For single ratios, we normally want the efficiency from the ratio (self).
     # If the step efficiency is X cents, then the ratio efficiency is -X cents.
-    step(modulo).efficiency * -1.0
+    step(modulo).efficiency * (is_step_efficiency ? 1.0 : -1.0)
   end
 
   # @return [Array] the results of ratio dividing and multiplying self
@@ -459,12 +460,13 @@ class Tonal::Ratio
 
   # @return [Tonal::Cents] cent difference between self and other ratio
   # @example
-  #   Tonal::ReducedRatio.new(3,2).cent_diff(4/3r) => 203.92
+  #   Tonal::ReducedRatio.new(3,2).cents_difference_with(4/3r) => 203.92
   # @param other_ratio [Tonal::ReducedRatio, Numeric] from which self's cents is measured
   #
-  def cent_diff(other_ratio)
-    cents - other_ratio.ratio.cents
+  def cents_difference_with(other_ratio)
+    to_cents - other_ratio.ratio.to_cents
   end
+  alias :cent_diff :cents_difference_with
 
   # @return [Integer] the least common multiple with self's denominator and the given number's denominator
   # @example
@@ -649,7 +651,7 @@ class Tonal::Ratio
   end
 
   private
-  def _initialize(antecedent, consequent=nil, label: nil, equave: 2/1r)
+  def _initialize(antecedent, consequent=nil, label: nil, equave: DEFAULT_EQUAVE)
     if consequent
       @antecedent = antecedent.abs
       @consequent = consequent.abs
@@ -668,7 +670,7 @@ class Tonal::Ratio
     raise ArgumentError, "Arguments must be greater than zero" if args.any?{|i| i < 0 }
   end
 
-  def _equave_reduce(equave=2/1r)
+  def _equave_reduce(equave=DEFAULT_EQUAVE)
     case to_r
     when Float::INFINITY
       ante, cons = antecedent, 0

data/lib/tonal/step.rb

@@ -85,6 +85,7 @@ class Tonal::Scale
       # We want the efficiency from the step (self).
       ratio_to_cents - step_to_cents
     end
+    alias :cents_difference :efficiency
 
     def +(rhs)
       self.class.new(step: (rhs % modulo), modulo: modulo)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: tonal-tools
 version: !ruby/object:Gem::Version
-  version: 8.3.2
+  version: 8.3.4
 platform: ruby
 authors:
 - Jose Hales-Garcia
 bindir: bin
 cert_chain: []
-date: 2026-02-15 00:00:00.000000000 Z
+date: 2026-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yaml
@@ -192,7 +192,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '3.1'
 requirements: []
-rubygems_version: 4.0.4
+rubygems_version: 4.0.7
 specification_version: 4
 summary: Tonal tools
 test_files: []