tuning-core 1.0.1 → 1.0.2

package/dist/classes/Harmonic.d.ts

@@ -0,0 +1,92 @@
+import Fraction, { type FractionInput } from 'fraction.js';
+import { type HarmonicData } from '../lib';
+/**
+ * Represents a single partial in an arbitrary spectrum.
+ * The name Harmonic does not imply a harmonic series but chosen over
+ * Partial to avoid coflict with the TypeScript's Partial type.
+ * Mutable for better real-time performance.
+ * Frequencies are stored as rational numbers for exact tuning mathematics.
+ *
+ * The constructor accepts either a HarmonicData object or individual parameters.
+ *
+ * @example
+ * // Using HarmonicData object
+ * const harmonic1 = new Harmonic({
+ *   frequency: 440,
+ *   amplitude: 0.5,
+ *   phase: Math.PI
+ * });
+ *
+ * @example
+ * // Using individual parameters
+ * const harmonic2 = new Harmonic(440, 0.5, Math.PI);
+ * const harmonic3 = new Harmonic("440"); // amplitude defaults to 1, phase defaults to 0
+ * const harmonic4 = new Harmonic("440 1/3"); // frequency as a string with whole and fractional part
+ * const harmonic4 = new Harmonic([107, 100]); // frequency as a fraction of two integers 107/100
+ * // Note that frequency is treated as a rational number from Fraction.js lib
+ * // so it accepts FractionInput type
+ */
+export declare class Harmonic {
+    private _frequency;
+    private _amplitude;
+    private _phase;
+    /**
+     * Get frequency as a Fraction
+     */
+    get frequency(): Fraction;
+    /**
+     * Get frequency as a float number
+     */
+    get frequencyNum(): number;
+    /**
+     * Get frequency as a simplified fraction string (e.g., "3/2")
+     */
+    get frequencyStr(): string;
+    /**
+     * Get amplitude (0-1 normalized)
+     */
+    get amplitude(): number;
+    /**
+     * Get phase (0-2π radians)
+     */
+    get phase(): number;
+    constructor(data: HarmonicData);
+    constructor(frequency: FractionInput, amplitude?: number, phase?: number);
+    private validate;
+    /**
+     * Sets frequency to the provided value
+     */
+    setFrequency(frequency: FractionInput): this;
+    /**
+     * Sets amplitude (0-1)
+     */
+    setAmplitude(amplitude: number): this;
+    /**
+     * Sets phase (0-2π)
+     */
+    setPhase(phase: number): this;
+    /**
+     * Multiply frequency by a ratio (for transposition)
+     */
+    transpose(ratio: FractionInput): this;
+    /**
+   * Multiply frequency by a ratio (for transposition)
+   */
+    toTransposed(ratio: FractionInput): Harmonic;
+    /**
+     * Scale amplitude by a factor
+     */
+    scale(factor: number): this;
+    /**
+     * Create a copy of this harmonic
+     */
+    clone(): Harmonic;
+    /**
+     * Compare frequencies (for sorting)
+     */
+    compareFrequency(other: Harmonic): number;
+    /**
+     * Serializes the harmonic to a HarmonicData object
+     */
+    toJSON(): HarmonicData;
+}

package/dist/classes/Harmonic.js

@@ -0,0 +1,164 @@
+import Fraction, {} from 'fraction.js';
+import { isHarmonicData } from '../lib';
+/**
+ * Represents a single partial in an arbitrary spectrum.
+ * The name Harmonic does not imply a harmonic series but chosen over
+ * Partial to avoid coflict with the TypeScript's Partial type.
+ * Mutable for better real-time performance.
+ * Frequencies are stored as rational numbers for exact tuning mathematics.
+ *
+ * The constructor accepts either a HarmonicData object or individual parameters.
+ *
+ * @example
+ * // Using HarmonicData object
+ * const harmonic1 = new Harmonic({
+ *   frequency: 440,
+ *   amplitude: 0.5,
+ *   phase: Math.PI
+ * });
+ *
+ * @example
+ * // Using individual parameters
+ * const harmonic2 = new Harmonic(440, 0.5, Math.PI);
+ * const harmonic3 = new Harmonic("440"); // amplitude defaults to 1, phase defaults to 0
+ * const harmonic4 = new Harmonic("440 1/3"); // frequency as a string with whole and fractional part
+ * const harmonic4 = new Harmonic([107, 100]); // frequency as a fraction of two integers 107/100
+ * // Note that frequency is treated as a rational number from Fraction.js lib
+ * // so it accepts FractionInput type
+ */
+export class Harmonic {
+    _frequency; // Frequency as ratio (e.g., 3/2 for perfect fifth)
+    _amplitude; // 0-1 normalized
+    _phase; // 0-2π radians
+    /**
+     * Get frequency as a Fraction
+     */
+    get frequency() {
+        return this._frequency;
+    }
+    /**
+     * Get frequency as a float number
+     */
+    get frequencyNum() {
+        return this._frequency.valueOf();
+    }
+    /**
+     * Get frequency as a simplified fraction string (e.g., "3/2")
+     */
+    get frequencyStr() {
+        return this._frequency.toFraction();
+    }
+    /**
+     * Get amplitude (0-1 normalized)
+     */
+    get amplitude() {
+        return this._amplitude;
+    }
+    /**
+     * Get phase (0-2π radians)
+     */
+    get phase() {
+        return this._phase;
+    }
+    constructor(frequencyOrData, amplitude = 1, phase = 0) {
+        if (isHarmonicData(frequencyOrData)) {
+            // HarmonicData case
+            this._frequency = new Fraction(frequencyOrData.frequency);
+            this._amplitude = frequencyOrData.amplitude;
+            this._phase = frequencyOrData.phase;
+        }
+        else {
+            // Original case: frequency, amplitude, phase
+            this._frequency = new Fraction(frequencyOrData);
+            this._amplitude = amplitude ?? 1;
+            this._phase = phase ?? 0;
+        }
+        this.validate();
+    }
+    validate() {
+        if (this._frequency.compare(0) <= 0) {
+            throw new Error('Frequency must be positive');
+        }
+        if (this._amplitude < 0 || this._amplitude > 1) {
+            throw new Error('Amplitude must be between 0 and 1');
+        }
+        if (this._phase < 0 || this._phase >= 2 * Math.PI) {
+            throw new Error('Phase must be between 0 and 2π');
+        }
+    }
+    /**
+     * Sets frequency to the provided value
+     */
+    setFrequency(frequency) {
+        this._frequency = new Fraction(frequency);
+        if (this._frequency.compare(0) <= 0) {
+            throw new Error('Frequency must be positive');
+        }
+        return this;
+    }
+    /**
+     * Sets amplitude (0-1)
+     */
+    setAmplitude(amplitude) {
+        if (amplitude < 0 || amplitude > 1) {
+            throw new Error('Amplitude must be between 0 and 1');
+        }
+        this._amplitude = amplitude;
+        return this;
+    }
+    /**
+     * Sets phase (0-2π)
+     */
+    setPhase(phase) {
+        if (phase < 0 || phase >= 2 * Math.PI) {
+            throw new Error('Phase must be between 0 and 2π');
+        }
+        this._phase = phase;
+        return this;
+    }
+    /**
+     * Multiply frequency by a ratio (for transposition)
+     */
+    transpose(ratio) {
+        this._frequency = this._frequency.mul(ratio);
+        return this;
+    }
+    /**
+   * Multiply frequency by a ratio (for transposition)
+   */
+    toTransposed(ratio) {
+        return this.clone().transpose(ratio);
+    }
+    /**
+     * Scale amplitude by a factor
+     */
+    scale(factor) {
+        this._amplitude = Math.max(0, Math.min(1, this._amplitude * factor));
+        return this;
+    }
+    /**
+     * Create a copy of this harmonic
+     */
+    clone() {
+        return new Harmonic(this._frequency, this._amplitude, this._phase);
+    }
+    /**
+     * Compare frequencies (for sorting)
+     */
+    compareFrequency(other) {
+        return this._frequency.compare(other._frequency);
+    }
+    /**
+     * Serializes the harmonic to a HarmonicData object
+     */
+    toJSON() {
+        return {
+            frequency: {
+                n: Number(this._frequency.n),
+                d: Number(this._frequency.d),
+            },
+            amplitude: this._amplitude,
+            phase: this._phase,
+        };
+    }
+}

package/dist/classes/IntervalSet.d.ts

@@ -0,0 +1,157 @@
+import Fraction, { type FractionInput } from 'fraction.js';
+import { Spectrum } from './Spectrum';
+/**
+ * Represents a set of frequency ratios (intervals).
+ * Uses Map to ensure no duplicate ratios.
+ * Useful for building tuning systems, scales, and analyzing interval collections.
+ */
+export declare class IntervalSet {
+    private ratios;
+    constructor(ratios?: FractionInput[]);
+    /**
+     * Add a ratio to the set.
+     * If ratio already exists, it replaces the existing one.
+     */
+    add(ratio: FractionInput): this;
+    /**
+     * Check if the set contains this ratio
+     */
+    has(ratio: FractionInput): boolean;
+    /**
+     * Remove a ratio from the set
+     * @returns true if ratio was removed, false if it didn't exist
+     */
+    delete(ratio: FractionInput): this;
+    /**
+     * Get a ratio from the set
+     * @returns Fraction object or undefined if not found
+     */
+    get(ratio: FractionInput): Fraction | undefined;
+    /**
+     * Number of ratios in the set
+     */
+    get size(): number;
+    /**
+     * Check if the set is empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Get all ratios as an array
+     */
+    getRatios(): Fraction[];
+    /**
+     * Get the smallest ratio in the set
+     */
+    min(): Fraction | undefined;
+    /**
+     * Get the largest ratio in the set
+     */
+    max(): Fraction | undefined;
+    /**
+     * Clear all ratios from the set
+     */
+    clear(): this;
+    /**
+     * Create a copy of this interval set
+     */
+    clone(): IntervalSet;
+    /**
+     * Iterate over all ratios
+     */
+    forEach(callback: (ratio: Fraction, key: string) => void): void;
+    /**
+     * Convert to Spectrum with equal amplitudes
+     * @param fundamentalHz - Optional fundamental frequency in Hz
+     * @param amplitude - Amplitude for all harmonics (default 1)
+     */
+    toSpectrum(amp: (ratio: Fraction, index: number) => number): Spectrum;
+    /**
+     * Get ratios as array of strings
+     */
+    toStrings(): string[];
+    /**
+     * Get ratios as array of decimal numbers
+     */
+    toNumbers(): number[];
+    /**
+     * Check if this set equals another set
+     */
+    equals(other: IntervalSet): boolean;
+    /**
+     * Calculate GCD of all ratios
+     */
+    private getGCD;
+    /**
+   * Convert an array of ratios to an array of intervals (differences between consecutive ratios).
+   * The first interval is always 1, and each subsequent interval is the current ratio divided by the previous ratio.
+   *
+   * @param ratios - Array of Fraction objects representing ratios
+   * @returns Array of Fraction objects representing intervals, starting with 1
+   *
+   * @example
+   * // If ratios are [1, 5/4, 3/2, 2], intervals will be [1, 5/4, 6/5, 4/3]
+   * const ratios = [new Fraction(1), new Fraction(5, 4), new Fraction(3, 2), new Fraction(2)];
+   * const intervals = getSweepIntervals(ratios);
+   */
+    toSweepIntervals(): Fraction[];
+    minMax(min: FractionInput, max: FractionInput): this;
+    /**
+     * Generate all unique ratios between min and max with denominators up to maxDenominator.
+     *
+     * This creates all possible fractions n/d where:
+     * - min <= n/d <= max
+     * - 1 <= d <= maxDenominator
+     * - 1 <= n
+     * - n and d are coprime (simplified fractions only)
+     *
+     * The Map in IntervalSet automatically handles deduplication of equivalent fractions.
+     *
+     * @param min - Minimum ratio (inclusive)
+     * @param max - Maximum ratio (inclusive)
+     * @param maxDenominator - Maximum denominator for generated fractions
+     *
+     * @example
+     * // All simple ratios in one octave
+     * IntervalSetFactory.range(1, 2, 5)
+     * // Returns: 1/1, 6/5, 5/4, 4/3, 3/2, 8/5, 5/3, 2/1
+     *
+     * @example
+     * // Fine divisions for analysis (100 steps per octave)
+     * IntervalSetFactory.range(1, 2, 100)
+     *
+     * @example
+     * // Ratios across 1.5 octaves
+     * IntervalSetFactory.range(1, 3, 12)
+     */
+    static range(min: FractionInput, max: FractionInput, maxDenominator: number): IntervalSet;
+    /**
+   * Generate affinitive tuning intervals that contain all ratios between harmonics of two spectra.
+   * For each pair of harmonics (one from each spectrum), calculates the ratio between them.
+   * Useful for analyzing harmonic relationships and consonance between two sounds.
+   *
+   * @param spectrum1 - First spectrum
+   * @param spectrum2 - Second spectrum
+   * @returns IntervalSet containing all unique ratios between the spectra's harmonics
+   */
+    static affinitive(context: Spectrum, complement: Spectrum): IntervalSet;
+    /**
+   * Add intermediate intervals between existing ratios to create a smooth curve.
+   * Uses logarithmic spacing to ensure perceptually uniform distribution.
+   * A gap of 1→2 gets the same density as 2→4 (both are octaves).
+   *
+   * @param maxGapCents - Maximum allowed gap in cents (e.g., 10 for 10-cent steps)
+   *                      1200 cents = 1 octave, 100 cents ≈ 1 semitone
+   * @returns this (for chaining)
+   *
+   * @example
+   * const intervals = new IntervalSet([1, 2, 4]);
+   * intervals.densify(100); // Max 100-cent (1 semitone) gaps
+   * // Adds same number of points between 1→2 as between 2→4
+   *
+   * @example
+   * // For dissonance curves - logarithmic spacing
+   * const extrema = IntervalSet.affinitive(spectrum1, spectrum2);
+   * extrema.densify(10); // ~10-cent resolution for smooth curve
+   */
+    densify(maxGapCents: number): this;
+}