sethares-dissonance 0.2.0 → 2.0.0

package/dist/classes/DissonanceCurve.d.ts

@@ -1,23 +1,87 @@
-import { SETHARES_DISSONANCE_PARAMS, type SpectrumPartial } from "../lib";
-export type DissonanceCurveOptions = Partial<typeof SETHARES_DISSONANCE_PARAMS> & {
-    context: SpectrumPartial[];
-    complement: SpectrumPartial[];
-    step?: number;
-    rangeMin?: number;
-    rangeMax?: number;
+import { Fraction, type FractionInput } from "fraction.js";
+import { type DissonanceParams, type DissonanceCurvePoint, type DissonanceCurveData } from "../lib";
+import { Spectrum } from "tuning-core";
+export type DissonanceCurveOptions = DissonanceParams & {
+    context: Spectrum;
+    complement: Spectrum;
+    maxDenominator?: number;
+    start?: FractionInput;
+    end?: FractionInput;
 };
+/**
+ * Represents a dissonance curve calculated using Sethares' sensory dissonance model.
+ *
+ * A dissonance curve shows how sensory dissonance varies across a range of intervals.
+ * The curve is generated by:
+ * 1. Creating a set of intervals between start and end ratios using IntervalSet.range()
+ * 2. For each interval calculates dissonance between the context spectrum and complement spectrum transposed by that interval
+ *
+ * @example
+ * ```ts
+ * const context = Spectrum.harmonicSeries(10, 440);
+ * const complement = Spectrum.harmonicSeries(10, 440);
+ *
+ * const curve = new DissonanceCurve({
+ *   context,
+ *   complement,
+ *   start: 1,
+ *   end: 2,
+ *   maxDenominator: 60
+ * });
+ *
+ * // Get points sorted by interval
+ * const points = curve.points;
+ *
+ * // Get plot data with ratios
+ * const plotData = curve.plot();
+ *
+ * // Get plot data with cents
+ * const plotDataCents = curve.plotCents();
+ * ```
+ */
 export declare class DissonanceCurve {
     private _data;
-    readonly rangeMin: NonNullable<DissonanceCurveOptions["rangeMin"]>;
-    readonly rangeMax: NonNullable<DissonanceCurveOptions["rangeMax"]>;
-    readonly step: NonNullable<DissonanceCurveOptions["step"]>;
-    readonly context: DissonanceCurveOptions["context"];
-    readonly complement: DissonanceCurveOptions["complement"];
+    readonly start: Fraction;
+    readonly end: Fraction;
+    readonly context: Spectrum;
+    readonly complement: Spectrum;
     readonly maxDissonance: number;
-    readonly change: number;
     constructor(opts: DissonanceCurveOptions);
-    get points(): [number, number][];
-    get(cent: number): number | undefined;
+    /**
+     * Get all dissonance curve points sorted by interval ratio.
+     * @returns Array of DissonanceCurvePoint objects sorted in ascending order by interval
+     */
+    get points(): DissonanceCurvePoint[];
+    /**
+     * Get a dissonance curve point for a specific ratio.
+     * @param ratio - The interval ratio as FractionInput (number, string, array, object, or Fraction)
+     * @returns The DissonanceCurvePoint for the given ratio, or undefined if not found
+     */
+    get(ratio: FractionInput): DissonanceCurvePoint | undefined;
+    /**
+     * Get plot points with intervals as ratio values (decimal numbers).
+     * @returns Array of [ratio, dissonance] tuples suitable for plotting
+     */
+    plot(): [number, number][];
+    /**
+     * Get plot points with intervals as cents values.
+     * @returns Array of [cents, dissonance] tuples suitable for plotting
+     */
+    plotCents(): [number, number][];
+    /**
+     * Serialize the dissonance curve to a JSON object.
+     * @returns DissonanceCurveData object
+     */
+    toJSON(): DissonanceCurveData;
     private getRowString;
-    toFileString(): string;
+    toString(columnDelimiter?: string, rowDelimiter?: string): string;
+    toCsvFileBuffer(columnDelimiter?: string, rowDelimiter?: string): Buffer<ArrayBuffer>;
+    /**
+     * Find the nearest calculated point for a given ratio.
+     * Uses binary search to find the first point where given ratio <= current ratio.
+     * If given ratio is greater than all calculated ratios, returns the last point.
+     * @param ratio - The ratio to find
+     * @returns The nearest DissonanceCurvePoint, or undefined if curve has no points
+     */
+    findNearestPoint(ratio: FractionInput): DissonanceCurvePoint | undefined;
 }

package/dist/classes/DissonanceCurve.js

@@ -1,57 +1,168 @@
-import { getSetharesDissonance, SETHARES_DISSONANCE_PARAMS, transpose } from "../lib";
+import { Fraction } from "fraction.js";
+import { getSetharesDissonance, } from "../lib";
+import { ratioToCents, Spectrum, IntervalSet } from "tuning-core";
+const DEFAULT_COLUMN_DELIMITER = ",";
+const DEFAULT_ROW_DELIMITER = "\n";
+/**
+ * Represents a dissonance curve calculated using Sethares' sensory dissonance model.
+ *
+ * A dissonance curve shows how sensory dissonance varies across a range of intervals.
+ * The curve is generated by:
+ * 1. Creating a set of intervals between start and end ratios using IntervalSet.range()
+ * 2. For each interval calculates dissonance between the context spectrum and complement spectrum transposed by that interval
+ *
+ * @example
+ * ```ts
+ * const context = Spectrum.harmonicSeries(10, 440);
+ * const complement = Spectrum.harmonicSeries(10, 440);
+ *
+ * const curve = new DissonanceCurve({
+ *   context,
+ *   complement,
+ *   start: 1,
+ *   end: 2,
+ *   maxDenominator: 60
+ * });
+ *
+ * // Get points sorted by interval
+ * const points = curve.points;
+ *
+ * // Get plot data with ratios
+ * const plotData = curve.plot();
+ *
+ * // Get plot data with cents
+ * const plotDataCents = curve.plotCents();
+ * ```
+ */
 export class DissonanceCurve {
     _data = new Map();
-    rangeMin;
-    rangeMax;
-    step;
+    start;
+    end;
     context;
     complement;
     maxDissonance = 0;
-    change = 0;
     constructor(opts) {
-        const { context, complement, rangeMin, rangeMax, step, ...dissonanceParams } = opts;
+        const { context, complement, start, end, maxDenominator, ...dissonanceParams } = opts;
         this.context = context;
         this.complement = complement;
-        this.rangeMin = rangeMin ?? 0;
-        this.rangeMax = rangeMax ?? 1200;
-        this.step = step ?? 1;
-        if (this.rangeMin > this.rangeMax)
-            throw Error("rangeMin should be less or equal to rangeMax");
-        if (this.step <= 0)
-            throw Error("precision should be greater than zero");
-        for (let cent = this.rangeMin; cent <= this.rangeMax; cent += this.step) {
-            const dissonance = getSetharesDissonance(this.context, transpose(this.complement, cent), dissonanceParams);
+        this.start = new Fraction(start ?? 1);
+        this.end = new Fraction(end ?? 2);
+        if (this.start.compare(this.end) > 0)
+            throw Error("startCents should be less or equal to endCents");
+        const intervals = IntervalSet.affinitive(this.context, this.complement).densify(20);
+        const ratios = intervals.getRatios();
+        for (let i = 0; i < ratios.length; i++) {
+            const interval = ratios[i];
+            const dissonance = getSetharesDissonance(this.context, this.complement.toTransposed(interval), dissonanceParams);
             if (dissonance > this.maxDissonance)
                 this.maxDissonance = dissonance;
-            this._data.set(cent, dissonance);
+            this._data.set(interval.toFraction(), { interval, dissonance });
         }
     }
+    /**
+     * Get all dissonance curve points sorted by interval ratio.
+     * @returns Array of DissonanceCurvePoint objects sorted in ascending order by interval
+     */
     get points() {
-        return Array.from(this._data.entries()).sort((a, b) => a[0] - b[0]);
+        return Array.from(this._data.values()).sort((a, b) => a.interval.compare(b.interval));
     }
-    get(cent) {
-        return this._data.get(cent);
+    /**
+     * Get a dissonance curve point for a specific ratio.
+     * @param ratio - The interval ratio as FractionInput (number, string, array, object, or Fraction)
+     * @returns The DissonanceCurvePoint for the given ratio, or undefined if not found
+     */
+    get(ratio) {
+        return this._data.get(new Fraction(ratio).toFraction());
     }
-    getRowString(row) {
+    /**
+     * Get plot points with intervals as ratio values (decimal numbers).
+     * @returns Array of [ratio, dissonance] tuples suitable for plotting
+     */
+    plot() {
+        return this.points.map(({ interval, dissonance }) => [
+            interval.valueOf(),
+            dissonance,
+        ]);
+    }
+    /**
+     * Get plot points with intervals as cents values.
+     * @returns Array of [cents, dissonance] tuples suitable for plotting
+     */
+    plotCents() {
+        return this.points.map(({ interval, dissonance }) => [
+            ratioToCents(interval).valueOf(),
+            dissonance,
+        ]);
+    }
+    /**
+     * Serialize the dissonance curve to a JSON object.
+     * @returns DissonanceCurveData object
+     */
+    toJSON() {
+        return this.points.map(({ interval, dissonance }) => ({
+            interval: {
+                n: Number(interval.n),
+                d: Number(interval.d),
+            },
+            dissonance,
+        }));
+    }
+    getRowString(row, delimiter = DEFAULT_COLUMN_DELIMITER) {
         if (row.length === 0)
             return "";
         let result = `${row[0]}`;
         for (let i = 1; i < row.length; i += 1) {
-            result += `\t${row[i]}`;
+            result += `${delimiter}${row[i]}`;
         }
         return result;
     }
-    toFileString() {
+    toString(columnDelimiter = DEFAULT_COLUMN_DELIMITER, rowDelimiter = DEFAULT_ROW_DELIMITER) {
         if (this._data.size === 0)
             return "";
-        const headerRow = this.getRowString([
-            "Interval (cents)",
-            "Sensory dissonance",
-        ]);
-        let result = headerRow + "\n";
+        const headerRow = this.getRowString(["Ratio", "Interval", "Interval (cents)", "Sensory dissonance"], columnDelimiter);
+        let result = headerRow + rowDelimiter;
         for (const point of this.points) {
-            result += this.getRowString(point);
+            result += this.getRowString([
+                point.interval.toFraction(),
+                point.interval.valueOf(),
+                ratioToCents(point.interval).valueOf(),
+                point.dissonance,
+            ], columnDelimiter) + rowDelimiter;
         }
         return result;
     }
+    toCsvFileBuffer(columnDelimiter = DEFAULT_COLUMN_DELIMITER, rowDelimiter = DEFAULT_ROW_DELIMITER) {
+        const content = this.toString(columnDelimiter, rowDelimiter);
+        // Return UTF-8 BOM + content as Buffer for Node.js writeFileSync
+        return Buffer.concat([
+            Buffer.from([0xef, 0xbb, 0xbf]),
+            Buffer.from(content, "utf-8"),
+        ]);
+    }
+    /**
+     * Find the nearest calculated point for a given ratio.
+     * Uses binary search to find the first point where given ratio <= current ratio.
+     * If given ratio is greater than all calculated ratios, returns the last point.
+     * @param ratio - The ratio to find
+     * @returns The nearest DissonanceCurvePoint, or undefined if curve has no points
+     */
+    findNearestPoint(ratio) {
+        const points = this.points;
+        if (points.length === 0)
+            return undefined;
+        const given = new Fraction(ratio);
+        let left = 0;
+        let right = points.length;
+        while (left < right) {
+            const mid = (left + right) >>> 1;
+            const point = points[mid];
+            if (given.compare(point.interval) <= 0) {
+                right = mid;
+            }
+            else {
+                left = mid + 1;
+            }
+        }
+        return points[left] ?? points[points.length - 1];
+    }
 }

package/dist/lib/const.d.ts

@@ -0,0 +1,29 @@
+import type { SecondOrderBeatingTerm } from "./types";
+export declare const NORMALISATION_PRESSURE_UNIT = 2.8284271247461903;
+export declare const SECOND_ORDER_BEATING_PARAMS: {
+    terms: SecondOrderBeatingTerm[];
+    widthMagnitudeRelationship: number;
+    totalContribution: number;
+};
+/** Fitting parameters proposed by Sethares in the appendix "How to Draw Dissonance Curves" */
+export declare const SETHARES_DISSONANCE_PARAMS: {
+    s1: number;
+    s2: number;
+    b1: number;
+    b2: number;
+    x_star: number;
+    totalContribution: number;
+};
+export declare const DEFAULT_DISSONANCE_PARAMS: {
+    secondOrderBeating: {
+        terms: SecondOrderBeatingTerm[];
+        widthMagnitudeRelationship: number;
+        totalContribution: number;
+    };
+    s1: number;
+    s2: number;
+    b1: number;
+    b2: number;
+    x_star: number;
+    totalContribution: number;
+};

package/dist/lib/const.js

@@ -0,0 +1,19 @@
+export const NORMALISATION_PRESSURE_UNIT = 2.8284271247461905;
+export const SECOND_ORDER_BEATING_PARAMS = {
+    terms: [],
+    widthMagnitudeRelationship: 0,
+    totalContribution: 1,
+};
+/** Fitting parameters proposed by Sethares in the appendix "How to Draw Dissonance Curves" */
+export const SETHARES_DISSONANCE_PARAMS = {
+    s1: 0.021,
+    s2: 19,
+    b1: 3.5,
+    b2: 5.75,
+    x_star: 0.24,
+    totalContribution: 1,
+};
+export const DEFAULT_DISSONANCE_PARAMS = {
+    ...SETHARES_DISSONANCE_PARAMS,
+    secondOrderBeating: SECOND_ORDER_BEATING_PARAMS,
+};

package/dist/lib/index.d.ts

@@ -1 +1,3 @@
 export * from "./utils";
+export * from "./const";
+export * from "./types";

package/dist/lib/index.js

@@ -1 +1,3 @@
 export * from "./utils";
+export * from "./const";
+export * from "./types";

package/dist/lib/types.d.ts

@@ -0,0 +1,22 @@
+import type Fraction from "fraction.js";
+import type { SECOND_ORDER_BEATING_PARAMS, SETHARES_DISSONANCE_PARAMS } from "./const";
+export type SecondOrderBeatingTerm = {
+    ratio: number;
+    magnitude: number;
+};
+export type SetharesDissonanceParams = Partial<typeof SETHARES_DISSONANCE_PARAMS>;
+export type SecondOrderBeatingParams = Partial<typeof SECOND_ORDER_BEATING_PARAMS>;
+export type DissonanceParams = SetharesDissonanceParams & {
+    secondOrderBeating?: SecondOrderBeatingParams;
+};
+export type DissonanceCurvePoint = {
+    interval: Fraction;
+    dissonance: number;
+};
+export type DissonanceCurveData = {
+    interval: {
+        n: number;
+        d: number;
+    };
+    dissonance: number;
+}[];

package/dist/lib/utils.d.ts

@@ -1,32 +1,26 @@
-export type SpectrumPartial = {
-    rate: number;
-    amplitude: number;
-    phase?: number;
-};
+import type { Harmonic, Spectrum } from "tuning-core";
+import type { DissonanceParams } from "./types";
 /**
  * The formula to calculate loudness from amplitude. The converstion to SPL (phons) is done according to Sethares in the appendix "How to Draw Dissonance Curves". The converstion to loudness is done according to https://sengpielaudio.com/calculatorSonephon.htm
  * @param {number} amplitude - the normalized peak value where 0.001 corresponds to SPL of 40 db or 1 sone and 1 to SPL of 100db and 64 sones. Normalisation is done for the simplicity of providing harmonic spectrum with amplitudes 1, 1/2, 1/3, ...
  */
 export declare function getLoudness(amplitude: number): number;
-/** Fitting parameters proposed by Sethares in the appendix "How to Draw Dissonance Curves" */
-export declare const SETHARES_DISSONANCE_PARAMS: {
-    s1: number;
-    s2: number;
-    b1: number;
-    b2: number;
-    x_star: number;
-};
-export type SetharesDissonanceParams = Partial<typeof SETHARES_DISSONANCE_PARAMS>;
 /** The formula to calculate sensory dissoannce proposed by Sethares in the appendix "How to Draw Dissonance Curves" */
-export declare function getPlompLeveltDissonance(partial1: SpectrumPartial, partial2: SpectrumPartial, params?: {
-    s1: number;
-    s2: number;
-    b1: number;
-    b2: number;
-    x_star: number;
-}): number;
-export declare function getIntrinsicDissonance(spectrum: SpectrumPartial[], params?: SetharesDissonanceParams): number;
-export declare function getSetharesDissonance(spectrum1: SpectrumPartial[], spectrum2: SpectrumPartial[], params?: SetharesDissonanceParams): number;
-export declare function ratioToCents(ratio: number): number;
-export declare function centsToRatio(cents: number): number;
-export declare function transpose(partials: SpectrumPartial[], cents: number): SpectrumPartial[];
+export declare function getPlompLeveltDissonance(h1: Harmonic, h2: Harmonic, params?: DissonanceParams): number;
+/**
+ * Calculate the intrinsic dissonance of a spectrum.
+ */
+export declare function getIntrinsicDissonance(spectrum: Spectrum, params?: DissonanceParams): number;
+/**
+ * Calculate the dissonance between two spectra.
+ * This is the sum of the intrinsic dissonance of each spectrum
+ * plus the dissonance between the harmonics of the two spectra.
+ *
+ * Note: If not proviing secondOrderBeating params is yield the same result as Sethares' TTSS formula.
+ * However secondOrderBeating params can be used to finetune the dissoannce perception and account for harmonicity.
+ */
+export declare function getSetharesDissonance(spectrum1: Spectrum, spectrum2: Spectrum, params?: DissonanceParams): number;
+/**
+ * Helper function to calculate the second order beating dissonance between two harmonics.
+ */
+export declare function getSecondOrderBeatingDissonance(h1: Harmonic, h2: Harmonic, params?: DissonanceParams): number;

package/dist/lib/utils.js

@@ -1,4 +1,4 @@
-const NORMALISATION_PRESSURE_UNIT = 2.8284271247461905;
+import { DEFAULT_DISSONANCE_PARAMS, NORMALISATION_PRESSURE_UNIT } from "./const";
 /**
  * The formula to calculate loudness from amplitude. The converstion to SPL (phons) is done according to Sethares in the appendix "How to Draw Dissonance Curves". The converstion to loudness is done according to https://sengpielaudio.com/calculatorSonephon.htm
  * @param {number} amplitude - the normalized peak value where 0.001 corresponds to SPL of 40 db or 1 sone and 1 to SPL of 100db and 64 sones. Normalisation is done for the simplicity of providing harmonic spectrum with amplitudes 1, 1/2, 1/3, ...
@@ -14,72 +14,122 @@ export function getLoudness(amplitude) {
         return Math.pow(phons / 40, 2.86) - 0.005;
     return Math.pow(2, (phons - 40) / 10);
 }
-/** Fitting parameters proposed by Sethares in the appendix "How to Draw Dissonance Curves" */
-export const SETHARES_DISSONANCE_PARAMS = {
-    s1: 0.021,
-    s2: 19,
-    b1: 3.5,
-    b2: 5.75,
-    x_star: 0.24,
-};
 /** The formula to calculate sensory dissoannce proposed by Sethares in the appendix "How to Draw Dissonance Curves" */
-export function getPlompLeveltDissonance(partial1, partial2, params = SETHARES_DISSONANCE_PARAMS) {
-    if (partial1.rate === partial2.rate)
+export function getPlompLeveltDissonance(h1, h2, params) {
+    const x_star = params?.x_star ?? DEFAULT_DISSONANCE_PARAMS.x_star;
+    const s1 = params?.s1 ?? DEFAULT_DISSONANCE_PARAMS.s1;
+    const s2 = params?.s2 ?? DEFAULT_DISSONANCE_PARAMS.s2;
+    const b1 = params?.b1 ?? DEFAULT_DISSONANCE_PARAMS.b1;
+    const b2 = params?.b2 ?? DEFAULT_DISSONANCE_PARAMS.b2;
+    if (h1.frequency.equals(h2.frequency))
         return 0;
-    const minLoudness = Math.min(getLoudness(partial1.amplitude), getLoudness(partial2.amplitude));
+    const minLoudness = Math.min(getLoudness(h1.amplitude), getLoudness(h2.amplitude));
     if (minLoudness <= 0)
         return 0;
-    const minFrequency = Math.min(partial1.rate, partial2.rate);
-    const frequencyDifference = Math.abs(partial1.rate - partial2.rate);
+    const minFrequency = Math.min(h1.frequencyNum, h2.frequencyNum);
     if (minFrequency <= 0)
         return 0;
-    const s = params.x_star / (params.s1 * minFrequency + params.s2);
+    const frequencyDifference = Math.abs(h1.frequencyNum - h2.frequencyNum);
+    const s = x_star / (s1 * minFrequency + s2);
     return (minLoudness *
-        (Math.exp(-1 * params.b1 * s * frequencyDifference) -
-            Math.exp(-1 * params.b2 * s * frequencyDifference)));
+        (Math.exp(-1 * b1 * s * frequencyDifference) -
+            Math.exp(-1 * b2 * s * frequencyDifference)));
 }
+/**
+ * Calculate the intrinsic dissonance of a spectrum.
+ */
 export function getIntrinsicDissonance(spectrum, params) {
+    const totalContribution = params?.totalContribution ??
+        DEFAULT_DISSONANCE_PARAMS.totalContribution;
+    const secondOrderBeatingContribution = params?.secondOrderBeating?.totalContribution ??
+        DEFAULT_DISSONANCE_PARAMS.secondOrderBeating?.totalContribution;
     let dissonance = 0;
-    for (let i = 0; i < spectrum.length; i++) {
-        for (let j = i + 1; j < spectrum.length; j++) {
-            const partial1 = spectrum[i];
-            const partial2 = spectrum[j];
-            dissonance += getPlompLeveltDissonance(partial1, partial2, {
-                ...SETHARES_DISSONANCE_PARAMS,
-                ...params,
-            });
+    const frequencies = spectrum.getKeys();
+    // loop over all pairs of harmonics within the spectrum (not including reversed pairs)
+    for (let i = 0; i < frequencies.length; i++) {
+        for (let j = i + 1; j < frequencies.length; j++) {
+            const h1 = spectrum.get(frequencies[i]);
+            const h2 = spectrum.get(frequencies[j]);
+            if (totalContribution) {
+                dissonance +=
+                    totalContribution *
+                        getPlompLeveltDissonance(h1, h2, params);
+            }
+            if (secondOrderBeatingContribution) {
+                dissonance +=
+                    secondOrderBeatingContribution *
+                        getSecondOrderBeatingDissonance(h1, h2, params);
+            }
         }
     }
     return dissonance;
 }
+/**
+ * Calculate the dissonance between two spectra.
+ * This is the sum of the intrinsic dissonance of each spectrum
+ * plus the dissonance between the harmonics of the two spectra.
+ *
+ * Note: If not proviing secondOrderBeating params is yield the same result as Sethares' TTSS formula.
+ * However secondOrderBeating params can be used to finetune the dissoannce perception and account for harmonicity.
+ */
 export function getSetharesDissonance(spectrum1, spectrum2, params) {
+    const totalContribution = params?.totalContribution ??
+        DEFAULT_DISSONANCE_PARAMS.totalContribution;
+    const secondOrderBeatingContribution = params?.secondOrderBeating?.totalContribution ??
+        DEFAULT_DISSONANCE_PARAMS.secondOrderBeating?.totalContribution;
     let dissonance = getIntrinsicDissonance(spectrum1, params) +
         getIntrinsicDissonance(spectrum2, params);
-    for (let i = 0; i < spectrum1.length; i++) {
-        for (let j = 0; j < spectrum2.length; j++) {
-            const partial1 = spectrum1[i];
-            const partial2 = spectrum2[j];
-            dissonance += getPlompLeveltDissonance(partial1, partial2, {
-                ...SETHARES_DISSONANCE_PARAMS,
-                ...params,
-            });
+    const frequencies1 = spectrum1.getKeys();
+    const frequencies2 = spectrum2.getKeys();
+    // loop over all pairs of harmonics between the two spectra (not including reversed pairs)
+    for (let i = 0; i < frequencies1.length; i++) {
+        for (let j = 0; j < frequencies2.length; j++) {
+            const h1 = spectrum1.get(frequencies1[i]);
+            const h2 = spectrum2.get(frequencies2[j]);
+            if (totalContribution) {
+                dissonance +=
+                    totalContribution *
+                        getPlompLeveltDissonance(h1, h2, params);
+            }
+            if (secondOrderBeatingContribution) {
+                dissonance +=
+                    secondOrderBeatingContribution *
+                        getSecondOrderBeatingDissonance(h1, h2, params);
+            }
         }
     }
     return dissonance;
 }
-export function ratioToCents(ratio) {
-    return ratio > 0 ? 1200 * Math.log2(ratio) : 0;
-}
-export function centsToRatio(cents) {
-    return Math.pow(2, cents / 1200);
-}
-export function transpose(partials, cents) {
-    const result = [];
-    for (const partial of partials) {
-        result.push({
-            rate: partial.rate * centsToRatio(cents),
-            amplitude: partial.amplitude,
-        });
+/**
+ * Helper function to calculate the second order beating dissonance between two harmonics.
+ */
+export function getSecondOrderBeatingDissonance(h1, h2, params) {
+    const x_star = params?.x_star ?? DEFAULT_DISSONANCE_PARAMS.x_star;
+    const s1 = params?.s1 ?? DEFAULT_DISSONANCE_PARAMS.s1;
+    const s2 = params?.s2 ?? DEFAULT_DISSONANCE_PARAMS.s2;
+    const b1 = params?.b1 ?? DEFAULT_DISSONANCE_PARAMS.b1;
+    const b2 = params?.b2 ?? DEFAULT_DISSONANCE_PARAMS.b2;
+    const widthMagnitudeRelationship = params?.secondOrderBeating?.widthMagnitudeRelationship ??
+        DEFAULT_DISSONANCE_PARAMS.secondOrderBeating.widthMagnitudeRelationship;
+    const terms = params?.secondOrderBeating?.terms ??
+        DEFAULT_DISSONANCE_PARAMS.secondOrderBeating.terms;
+    let dissonance = 0;
+    const minLoudness = Math.min(getLoudness(h1.amplitude), getLoudness(h2.amplitude));
+    const minFrequency = Math.min(h1.frequencyNum, h2.frequencyNum);
+    if (minFrequency <= 0)
+        return 0;
+    const maxFrequency = Math.max(h1.frequencyNum, h2.frequencyNum);
+    for (const term of terms) {
+        if (term.ratio === 1 || term.ratio <= 0)
+            continue;
+        const difference = Math.abs(minFrequency * term.ratio - maxFrequency);
+        const s = x_star / (s1 * minFrequency + s2);
+        const widthModifier = 1 - widthMagnitudeRelationship * term.magnitude;
+        dissonance +=
+            term.magnitude *
+                minLoudness *
+                (Math.exp((-1 * b1 * s * difference) / widthModifier) -
+                    Math.exp((-1 * b2 * s * difference) / widthModifier));
     }
-    return result;
+    return dissonance;
 }

package/dist/tests/DissonanceCurve.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/DissonanceCurve.test.js

@@ -0,0 +1,127 @@
+import { describe, test, expect } from "bun:test";
+import Fraction from "fraction.js";
+import { DissonanceCurve } from "../classes";
+import { Spectrum } from "tuning-core";
+function createTestCurve() {
+    const context = Spectrum.harmonic(6, 440);
+    const complement = Spectrum.harmonic(6, 440);
+    return new DissonanceCurve({
+        context,
+        complement,
+        start: 1,
+        end: 2,
+        maxDenominator: 60,
+    });
+}
+describe("DissonanceCurve", () => {
+    describe("findNearestPoint", () => {
+        describe("ratios that exist in the curve", () => {
+            test("returns exact point when ratio is in curve (number)", () => {
+                const curve = createTestCurve();
+                const points = curve.points;
+                const firstPoint = points[0];
+                const result = curve.findNearestPoint(firstPoint.interval.valueOf());
+                expect(result).toBeDefined();
+                expect(result?.interval.compare(firstPoint.interval)).toBe(0);
+                expect(result?.dissonance).toBe(firstPoint.dissonance);
+            });
+            test("returns exact point when ratio is in curve (string)", () => {
+                const curve = createTestCurve();
+                const points = curve.points;
+                const midPoint = points[Math.floor(points.length / 2)];
+                const result = curve.findNearestPoint(midPoint.interval.toFraction());
+                expect(result).toBeDefined();
+                expect(result?.interval.compare(midPoint.interval)).toBe(0);
+            });
+            test("returns exact point when ratio is in curve (Fraction)", () => {
+                const curve = createTestCurve();
+                const points = curve.points;
+                const lastPoint = points[points.length - 1];
+                const result = curve.findNearestPoint(new Fraction(lastPoint.interval));
+                expect(result).toBeDefined();
+                expect(result?.interval.compare(lastPoint.interval)).toBe(0);
+            });
+            test("returns exact point for ratio 1 (unison)", () => {
+                const curve = createTestCurve();
+                const result = curve.findNearestPoint(1);
+                expect(result).toBeDefined();
+                expect(result?.interval.compare(1)).toBe(0);
+            });
+            test("returns exact point for ratio 2 (octave)", () => {
+                const curve = createTestCurve();
+                const result = curve.findNearestPoint(2);
+                expect(result).toBeDefined();
+                expect(result?.interval.compare(2)).toBe(0);
+            });
+        });
+        describe("ratios that do not exist in the curve", () => {
+            test("returns ceiling point when ratio is between two calculated points", () => {
+                const curve = createTestCurve();
+                const points = curve.points;
+                if (points.length < 2)
+                    return;
+                const left = points[0];
+                const right = points[1];
+                const between = Math.sqrt(left.interval.valueOf() * right.interval.valueOf());
+                const result = curve.findNearestPoint(between);
+                expect(result).toBeDefined();
+                expect(result?.interval.compare(right.interval)).toBe(0);
+            });
+            test("returns first point when ratio is below curve range", () => {
+                const curve = createTestCurve();
+                const points = curve.points;
+                const minRatio = points[0].interval.valueOf();
+                const result = curve.findNearestPoint(minRatio * 0.5);
+                expect(result).toBeDefined();
+                expect(result?.interval.compare(points[0].interval)).toBe(0);
+            });
+            test("returns last point when ratio is above curve range", () => {
+                const curve = createTestCurve();
+                const points = curve.points;
+                const lastPoint = points[points.length - 1];
+                const result = curve.findNearestPoint(lastPoint.interval.valueOf() * 2);
+                expect(result).toBeDefined();
+                expect(result?.interval.compare(lastPoint.interval)).toBe(0);
+            });
+            test("returns correct point for ratio just below an existing point", () => {
+                const curve = createTestCurve();
+                const points = curve.points;
+                if (points.length < 2)
+                    return;
+                const target = points[1];
+                const justBelow = target.interval.valueOf() - 0.001;
+                const result = curve.findNearestPoint(justBelow);
+                expect(result).toBeDefined();
+                expect(result?.interval.compare(target.interval)).toBe(0);
+            });
+            test("returns ceiling point when ratio is just above an existing point", () => {
+                const curve = createTestCurve();
+                const points = curve.points;
+                if (points.length < 2)
+                    return;
+                const current = points[1];
+                const justAboveCurrent = current.interval.valueOf() + 0.001;
+                const result = curve.findNearestPoint(justAboveCurrent);
+                expect(result).toBeDefined();
+                expect(result.interval.compare(justAboveCurrent)).toBeGreaterThanOrEqual(0);
+            });
+        });
+        describe("FractionInput types", () => {
+            test("accepts number input", () => {
+                const curve = createTestCurve();
+                const result = curve.findNearestPoint(1.5);
+                expect(result).toBeDefined();
+            });
+            test("accepts string fraction input", () => {
+                const curve = createTestCurve();
+                const result = curve.findNearestPoint("3/2");
+                expect(result).toBeDefined();
+            });
+            test("accepts Fraction object input", () => {
+                const curve = createTestCurve();
+                const result = curve.findNearestPoint(new Fraction(5, 4));
+                expect(result).toBeDefined();
+            });
+        });
+    });
+});

package/dist/tests/utils.test.js

@@ -1,6 +1,5 @@
 import { expect, test, describe } from "bun:test";
 import * as Utils from "../lib/utils";
-import { DissonanceCurve } from "../classes";
 describe("lib/utils", () => {
     test("Should calculate loudness", () => {
         const amplitudes = [1, 0.001, 0.000025];
@@ -8,9 +7,3 @@ describe("lib/utils", () => {
         expect(amplitudes.map(Utils.getLoudness)).toEqual(expectedOutcome);
     });
 });
-describe("classes/DissoannceCurve", () => {
-    test("Should construct Dissoancne curve", () => {
-        const curve = new DissonanceCurve({ context: [], complement: [] });
-        expect(curve).toBeInstanceOf(DissonanceCurve);
-    });
-});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sethares-dissonance",
-  "version": "0.2.0",
+  "version": "2.0.0",
   "module": "index.ts",
   "type": "module",
   "devDependencies": {
@@ -11,8 +11,15 @@
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["./dist"],
+  "files": [
+    "./dist"
+  ],
   "scripts": {
-    "build": "npx tsc"
+    "build": "npx tsc",
+    "publish": "npx tsc && bun publish --access public"
+  },
+  "dependencies": {
+    "fraction.js": "^5.3.4",
+    "tuning-core": "^1.0.0"
   }
 }