sethares-dissonance 3.0.0 → 5.0.0-beta.0

package/dist/classes/DissonanceCurve.d.ts

@@ -38,6 +38,9 @@ export type DissonanceCurveOptions = DissonanceParams & {
  *
  * // Get plot data with cents
  * const plotDataCents = curve.plotCents();
+ *
+ * // Normalize dissonance to 0–1 range (destructive, mutates in place)
+ * curve.normalize();
  * ```
  */
 export declare class DissonanceCurve {
@@ -70,6 +73,21 @@ export declare class DissonanceCurve {
      * @returns The DissonanceCurvePoint for the given ratio, or undefined if not found
      */
     get(ratio: FractionInput): DissonanceCurvePoint | undefined;
+    /**
+     * Normalize dissonance values in place to a target range.
+     *
+     * **Destructive:** This method mutates the curve permanently. All dissonance values
+     * are scaled from [0, maxDissonance] to [min, max], and the original raw values
+     * cannot be recovered. Use {@link recalculate} to rebuild the curve with raw values.
+     *
+     * After normalization, `points`, `get`, `plot`, `plotCents`, `toJSON`, and
+     * `toString` will all return normalized dissonance values in the [min, max] range.
+     *
+     * @param min - Target minimum value (default: 0)
+     * @param max - Target maximum value (default: 1)
+     * @returns `this` for method chaining
+     */
+    normalize(min?: number, max?: number): this;
     /**
      * Get plot points with intervals as ratio values (decimal numbers).
      * @returns Array of [ratio, dissonance] tuples suitable for plotting

package/dist/classes/DissonanceCurve.js

@@ -1,6 +1,7 @@
 import { Fraction } from "fraction.js";
 import { ratioToCents, Spectrum, IntervalSet } from "tuning-core";
 import { getSetharesDissonance, getIntrinsicDissonance } from "../lib";
+import { DEFAULT_PHANTOM_HARMONICS_NUMBER } from "../lib/const";
 import { SpectrumWithLoudness } from "./private/SpectrumWithLoudness";
 const DEFAULT_COLUMN_DELIMITER = ",";
 const DEFAULT_ROW_DELIMITER = "\n";
@@ -33,6 +34,9 @@ const DEFAULT_ROW_DELIMITER = "\n";
  *
  * // Get plot data with cents
  * const plotDataCents = curve.plotCents();
+ *
+ * // Normalize dissonance to 0–1 range (destructive, mutates in place)
+ * curve.normalize();
  * ```
  */
 export class DissonanceCurve {
@@ -45,7 +49,8 @@ export class DissonanceCurve {
     maxDissonance = 0;
     constructor(opts) {
         const { context, complement, start, end, maxGapCents = 20, ...dissonanceParams } = opts;
-        const phantomHarmonics = SpectrumWithLoudness.harmonic(dissonanceParams.phantomHarmonicsNumber + 1, 1, true);
+        const phantomCount = (dissonanceParams.phantomHarmonicsNumber ?? DEFAULT_PHANTOM_HARMONICS_NUMBER) + 1;
+        const phantomHarmonics = SpectrumWithLoudness.harmonic(phantomCount, 1, true);
         this.context = new SpectrumWithLoudness(context).mul(phantomHarmonics);
         this.complement = new SpectrumWithLoudness(complement).mul(phantomHarmonics);
         this.start = new Fraction(start ?? 1);
@@ -61,7 +66,8 @@ export class DissonanceCurve {
      */
     recalculate(opts) {
         const { context, complement, start, end, maxGapCents = 20, ...dissonanceParams } = opts;
-        const phantomHarmonics = SpectrumWithLoudness.harmonic(dissonanceParams.phantomHarmonicsNumber + 1, 1, true);
+        const phantomCount = (dissonanceParams.phantomHarmonicsNumber ?? DEFAULT_PHANTOM_HARMONICS_NUMBER) + 1;
+        const phantomHarmonics = SpectrumWithLoudness.harmonic(phantomCount, 1, true);
         this.context = new SpectrumWithLoudness(context).mul(phantomHarmonics);
         this.complement = new SpectrumWithLoudness(complement).mul(phantomHarmonics);
         this.start = new Fraction(start ?? 1);
@@ -111,6 +117,35 @@ export class DissonanceCurve {
     get(ratio) {
         return this._data.get(new Fraction(ratio).toFraction());
     }
+    /**
+     * Normalize dissonance values in place to a target range.
+     *
+     * **Destructive:** This method mutates the curve permanently. All dissonance values
+     * are scaled from [0, maxDissonance] to [min, max], and the original raw values
+     * cannot be recovered. Use {@link recalculate} to rebuild the curve with raw values.
+     *
+     * After normalization, `points`, `get`, `plot`, `plotCents`, `toJSON`, and
+     * `toString` will all return normalized dissonance values in the [min, max] range.
+     *
+     * @param min - Target minimum value (default: 0)
+     * @param max - Target maximum value (default: 1)
+     * @returns `this` for method chaining
+     */
+    normalize(min = 0, max = 1) {
+        if (max <= min)
+            throw new Error('max must be greater than min');
+        if (this.maxDissonance === 0)
+            return this;
+        const range = max - min;
+        for (const [key, point] of this._data) {
+            this._data.set(key, {
+                interval: point.interval,
+                dissonance: (point.dissonance / this.maxDissonance) * range + min,
+            });
+        }
+        this.maxDissonance = max;
+        return this;
+    }
     /**
      * Get plot points with intervals as ratio values (decimal numbers).
      * @returns Array of [ratio, dissonance] tuples suitable for plotting

package/dist/lib/const.d.ts

@@ -1,9 +1,40 @@
 export declare const NORMALISATION_PRESSURE_UNIT = 2.8284271247461903;
 /** 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;
+    readonly s1: 0.021;
+    readonly s2: 19;
+    readonly b1: 3.5;
+    readonly b2: 5.75;
+    readonly x_star: 0.24;
+    readonly magnitude: 1;
+    /** At 0: no decay (constant magnitude). Higher values = faster decay with minFrequency. */
+    readonly magnitudeFrequencyDecay: 0;
 };
+export declare const DEFAULT_FIRST_ORDER_DISSONANCE_PARAMS: {
+    s1: 0.021;
+    s2: 19;
+    b1: 3.5;
+    b2: 5.75;
+    x_star: 0.24;
+    magnitude: 1;
+    magnitudeFrequencyDecay: 0;
+};
+export declare const DEFAULT_SECOND_ORDER_DISSONANCE_PARAMS: {
+    magnitude: number;
+    s1: 0.021;
+    s2: 19;
+    b1: 3.5;
+    b2: 5.75;
+    x_star: 0.24;
+    magnitudeFrequencyDecay: 0;
+};
+export declare const DEFAULT_THIRD_ORDER_DISSONANCE_PARAMS: {
+    magnitude: number;
+    s1: 0.021;
+    s2: 19;
+    b1: 3.5;
+    b2: 5.75;
+    x_star: 0.24;
+    magnitudeFrequencyDecay: 0;
+};
+export declare const DEFAULT_PHANTOM_HARMONICS_NUMBER = 0;

package/dist/lib/const.js

@@ -6,4 +6,11 @@ export const SETHARES_DISSONANCE_PARAMS = {
     b1: 3.5,
     b2: 5.75,
     x_star: 0.24,
+    magnitude: 1,
+    /** At 0: no decay (constant magnitude). Higher values = faster decay with minFrequency. */
+    magnitudeFrequencyDecay: 0,
 };
+export const DEFAULT_FIRST_ORDER_DISSONANCE_PARAMS = { ...SETHARES_DISSONANCE_PARAMS };
+export const DEFAULT_SECOND_ORDER_DISSONANCE_PARAMS = { ...SETHARES_DISSONANCE_PARAMS, magnitude: 0.25 };
+export const DEFAULT_THIRD_ORDER_DISSONANCE_PARAMS = { ...SETHARES_DISSONANCE_PARAMS, magnitude: 0.1 };
+export const DEFAULT_PHANTOM_HARMONICS_NUMBER = 0;

package/dist/lib/types.d.ts

@@ -1,11 +1,14 @@
 import type Fraction from "fraction.js";
 import type { SETHARES_DISSONANCE_PARAMS } from "./const";
-export type SetharesDissonanceParams = Partial<typeof SETHARES_DISSONANCE_PARAMS>;
-export type DissonanceParams = SetharesDissonanceParams & {
-    firstOrderContribution: number;
-    secondOrderContribution: number;
-    thirdOrderContribution: number;
-    phantomHarmonicsNumber: number;
+/** Params for Plomp-Levelt formula; all numeric to allow overrides */
+export type SetharesDissonanceParams = Partial<{
+    [K in keyof typeof SETHARES_DISSONANCE_PARAMS]: number;
+}>;
+export type DissonanceParams = {
+    firstOrderDissonance?: SetharesDissonanceParams;
+    secondOrderDissonance?: SetharesDissonanceParams;
+    thirdOrderDissonance?: SetharesDissonanceParams;
+    phantomHarmonicsNumber?: number;
 };
 export type DissonanceCurvePoint = {
     interval: Fraction;

package/dist/lib/utils.d.ts

@@ -4,14 +4,12 @@ import type { HarmonicWithLoudness } from "../classes/private/HarmonicWithLoudne
 import { SpectrumWithLoudness } from "../classes/private/SpectrumWithLoudness";
 export { getLoudness } from "./loudness";
 /** The formula to calculate sensory dissoannce proposed by Sethares in the appendix "How to Draw Dissonance Curves" */
-export declare function getPlompLeveltDissonance(h1: Harmonic, h2: Harmonic, params?: SetharesDissonanceParams & {
-    contribution?: number;
-}): number;
+export declare function getPlompLeveltDissonance(h1: Harmonic, h2: Harmonic, params: SetharesDissonanceParams): number;
 /**
  * Find dissonance between two harmonics based on phantom status.
- * - Both non-phantom: firstOrderDissonance
- * - One phantom, one non-phantom: secondOrderDissonance
- * - Both phantom: thirdOrderDissonance
+ * - Both non-phantom: first order
+ * - One phantom, one non-phantom: second order
+ * - Both phantom: third order
  */
 export declare function getSensoryDissonance(h1: HarmonicWithLoudness, h2: HarmonicWithLoudness, params?: DissonanceParams): number;
 /**

package/dist/lib/utils.js

@@ -1,17 +1,18 @@
-import { SETHARES_DISSONANCE_PARAMS } from "./const";
+import { DEFAULT_FIRST_ORDER_DISSONANCE_PARAMS, DEFAULT_SECOND_ORDER_DISSONANCE_PARAMS, DEFAULT_THIRD_ORDER_DISSONANCE_PARAMS, SETHARES_DISSONANCE_PARAMS, } from "./const";
 import { getLoudness } from "./loudness";
 import { SpectrumWithLoudness } from "../classes/private/SpectrumWithLoudness";
 export { getLoudness } from "./loudness";
 /** The formula to calculate sensory dissoannce proposed by Sethares in the appendix "How to Draw Dissonance Curves" */
 export function getPlompLeveltDissonance(h1, h2, params) {
-    const contribution = params?.contribution ?? 1;
-    if (contribution <= 0)
+    const magnitude = params?.magnitude ?? SETHARES_DISSONANCE_PARAMS.magnitude;
+    if (magnitude <= 0)
         return 0;
     const x_star = params?.x_star ?? SETHARES_DISSONANCE_PARAMS.x_star;
     const s1 = params?.s1 ?? SETHARES_DISSONANCE_PARAMS.s1;
     const s2 = params?.s2 ?? SETHARES_DISSONANCE_PARAMS.s2;
     const b1 = params?.b1 ?? SETHARES_DISSONANCE_PARAMS.b1;
     const b2 = params?.b2 ?? SETHARES_DISSONANCE_PARAMS.b2;
+    const magnitudeFrequencyDecay = params?.magnitudeFrequencyDecay ?? SETHARES_DISSONANCE_PARAMS.magnitudeFrequencyDecay;
     if (h1.frequency.equals(h2.frequency))
         return 0;
     const minLoudness = Math.min("loudness" in h1 ? h1.loudness : getLoudness(h1.amplitude), "loudness" in h2 ? h2.loudness : getLoudness(h2.amplitude));
@@ -20,39 +21,38 @@ export function getPlompLeveltDissonance(h1, h2, params) {
     const minFrequency = Math.min(h1.frequencyNum, h2.frequencyNum);
     if (minFrequency <= 0)
         return 0;
+    const magnitudeDecayFactor = Math.exp(-magnitudeFrequencyDecay * (minFrequency / 1000));
     const frequencyDifference = Math.abs(h1.frequencyNum - h2.frequencyNum);
     const s = x_star / (s1 * minFrequency + s2);
-    return (contribution *
+    return (magnitude *
+        magnitudeDecayFactor *
         minLoudness *
         (Math.exp(-1 * b1 * s * frequencyDifference) -
             Math.exp(-1 * b2 * s * frequencyDifference)));
 }
-/** For now identical to getPlompLeveltDissonance */
-function firstOrderDissonance(h1, h2, params) {
-    return getPlompLeveltDissonance(h1, h2, { ...params, contribution: params?.firstOrderContribution });
-}
-/** For now identical to getPlompLeveltDissonance */
-function secondOrderDissonance(h1, h2, params) {
-    return getPlompLeveltDissonance(h1, h2, { ...params, contribution: params?.secondOrderContribution });
-}
-/** For now identical to getPlompLeveltDissonance */
-function thirdOrderDissonance(h1, h2, params) {
-    return getPlompLeveltDissonance(h1, h2, { ...params, contribution: params?.thirdOrderContribution });
-}
 /**
  * Find dissonance between two harmonics based on phantom status.
- * - Both non-phantom: firstOrderDissonance
- * - One phantom, one non-phantom: secondOrderDissonance
- * - Both phantom: thirdOrderDissonance
+ * - Both non-phantom: first order
+ * - One phantom, one non-phantom: second order
+ * - Both phantom: third order
  */
 export function getSensoryDissonance(h1, h2, params) {
     if (!h1.phantom && !h2.phantom) {
-        return firstOrderDissonance(h1, h2, params);
+        return getPlompLeveltDissonance(h1, h2, {
+            ...DEFAULT_FIRST_ORDER_DISSONANCE_PARAMS,
+            ...params?.firstOrderDissonance,
+        });
     }
     if (h1.phantom !== h2.phantom) {
-        return secondOrderDissonance(h1, h2, params);
+        return getPlompLeveltDissonance(h1, h2, {
+            ...DEFAULT_SECOND_ORDER_DISSONANCE_PARAMS,
+            ...params?.secondOrderDissonance,
+        });
     }
-    return thirdOrderDissonance(h1, h2, params);
+    return getPlompLeveltDissonance(h1, h2, {
+        ...DEFAULT_THIRD_ORDER_DISSONANCE_PARAMS,
+        ...params?.thirdOrderDissonance,
+    });
 }
 /**
  * Calculate the intrinsic dissonance of a spectrum.

package/dist/manual-testing/index.js

@@ -1,16 +1,16 @@
 import { Spectrum } from "tuning-core";
 import { DissonanceCurve } from "../classes";
-const context = Spectrum.harmonic(6, 440);
-const complement = Spectrum.harmonic(6, 440);
+const context = Spectrum.harmonic(1, 440);
+const complement = Spectrum.harmonic(1, 440);
 const curve = new DissonanceCurve({
     context,
     complement,
     start: 1,
     end: 2,
-    firstOrderContribution: 1,
-    secondOrderContribution: 0.3,
-    thirdOrderContribution: 0.1,
+    firstOrderDissonance: { magnitude: 1 },
+    secondOrderDissonance: { magnitude: 0.3 },
+    thirdOrderDissonance: { magnitude: 0.1 },
     phantomHarmonicsNumber: 2,
     maxGapCents: 20,
 });
-Bun.write("./manual-testing/curve.csv", curve.toCsvFileBuffer());
+Bun.write("./manual-testing/curve.csv", curve.normalize().toCsvFileBuffer());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sethares-dissonance",
-  "version": "3.0.0",
+  "version": "5.0.0-beta.0",
   "type": "module",
   "devDependencies": {
     "@types/bun": "latest"