tuning-core 1.0.1 → 1.0.2

package/dist/classes/IntervalSet.js

@@ -0,0 +1,304 @@
+import Fraction, {} 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 class IntervalSet {
+    ratios;
+    constructor(ratios) {
+        this.ratios = new Map();
+        if (!ratios)
+            return;
+        for (const r of ratios) {
+            this.add(r);
+        }
+    }
+    /**
+     * Add a ratio to the set.
+     * If ratio already exists, it replaces the existing one.
+     */
+    add(ratio) {
+        const f = new Fraction(ratio);
+        this.ratios.set(f.toFraction(), f);
+        return this;
+    }
+    /**
+     * Check if the set contains this ratio
+     */
+    has(ratio) {
+        const key = new Fraction(ratio).toFraction();
+        return this.ratios.has(key);
+    }
+    /**
+     * Remove a ratio from the set
+     * @returns true if ratio was removed, false if it didn't exist
+     */
+    delete(ratio) {
+        const key = new Fraction(ratio).toFraction();
+        this.ratios.delete(key);
+        return this;
+    }
+    /**
+     * Get a ratio from the set
+     * @returns Fraction object or undefined if not found
+     */
+    get(ratio) {
+        const key = new Fraction(ratio).toFraction();
+        return this.ratios.get(key);
+    }
+    /**
+     * Number of ratios in the set
+     */
+    get size() {
+        return this.ratios.size;
+    }
+    /**
+     * Check if the set is empty
+     */
+    isEmpty() {
+        return this.ratios.size === 0;
+    }
+    /**
+     * Get all ratios as an array
+     */
+    getRatios() {
+        return Array.from(this.ratios.values()).sort((a, b) => a.compare(b));
+    }
+    /**
+     * Get the smallest ratio in the set
+     */
+    min() {
+        return this.getRatios().at(0);
+    }
+    /**
+     * Get the largest ratio in the set
+     */
+    max() {
+        return this.getRatios().at(-1);
+    }
+    /**
+     * Clear all ratios from the set
+     */
+    clear() {
+        this.ratios.clear();
+        return this;
+    }
+    /**
+     * Create a copy of this interval set
+     */
+    clone() {
+        return new IntervalSet(Array.from(this.ratios.values()));
+    }
+    /**
+     * Iterate over all ratios
+     */
+    forEach(callback) {
+        this.ratios.forEach(callback);
+    }
+    /**
+     * Convert to Spectrum with equal amplitudes
+     * @param fundamentalHz - Optional fundamental frequency in Hz
+     * @param amplitude - Amplitude for all harmonics (default 1)
+     */
+    toSpectrum(amp) {
+        const spectrum = new Spectrum();
+        this.getRatios().forEach((ratio, index) => {
+            spectrum.add(ratio, amp(ratio, index));
+        });
+        return spectrum;
+    }
+    /**
+     * Get ratios as array of strings
+     */
+    toStrings() {
+        return this.getRatios().map(r => r.toFraction());
+    }
+    /**
+     * Get ratios as array of decimal numbers
+     */
+    toNumbers() {
+        return this.getRatios().map(r => r.valueOf());
+    }
+    /**
+     * Check if this set equals another set
+     */
+    equals(other) {
+        if (this.size !== other.size)
+            return false;
+        for (const ratio of this.getRatios()) {
+            if (!other.has(ratio))
+                return false;
+        }
+        return true;
+    }
+    /**
+     * Calculate GCD of all ratios
+     */
+    getGCD() {
+        const ratios = this.getRatios();
+        if (ratios.length === 0)
+            return undefined;
+        let gcd = ratios[0];
+        for (let i = 1; i < ratios.length; i++) {
+            gcd = gcd.gcd(ratios[i]);
+        }
+        return gcd;
+    }
+    /**
+   * 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() {
+        const ratios = this.getRatios();
+        const intervals = [];
+        if (ratios.length === 0)
+            return intervals;
+        intervals.push(new Fraction(1));
+        for (let i = 1; i < ratios.length; i++) {
+            intervals.push(ratios[i].div(ratios[i - 1]));
+        }
+        return intervals;
+    }
+    minMax(min, max) {
+        const minFraction = new Fraction(min);
+        const maxFraction = new Fraction(max);
+        if (minFraction.compare(maxFraction) > 0) {
+            throw new Error('min must be less than or equal to max');
+        }
+        for (const ratio of this.ratios.values()) {
+            if (ratio.compare(minFraction) < 0 || ratio.compare(maxFraction) > 0) {
+                this.ratios.delete(ratio.toFraction());
+            }
+        }
+        return 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, max, maxDenominator) {
+        if (maxDenominator < 1) {
+            throw new Error('maxDenominator must be at least 1');
+        }
+        const minFraction = new Fraction(min);
+        const maxFraction = new Fraction(max);
+        if (minFraction.compare(maxFraction) > 0) {
+            throw new Error('min must be less than or equal to max');
+        }
+        const intervalSet = new IntervalSet();
+        for (let denominator = 1; denominator <= maxDenominator; denominator++) {
+            const minNumerator = Math.max(1, Math.ceil(minFraction.valueOf() * denominator));
+            const maxNumerator = Math.floor(maxFraction.valueOf() * denominator);
+            for (let numerator = minNumerator; numerator <= maxNumerator; numerator++) {
+                const fraction = new Fraction(numerator, denominator);
+                if (fraction.compare(minFraction) >= 0 && fraction.compare(maxFraction) <= 0) {
+                    intervalSet.add(fraction);
+                }
+            }
+        }
+        return 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, complement) {
+        const intervalSet = new IntervalSet();
+        const harmonics1 = context.getHarmonics();
+        const harmonics2 = complement.getHarmonics();
+        // Calculate ratio between every pair of harmonics
+        for (const h1 of harmonics1) {
+            for (const h2 of harmonics2) {
+                const ratio = h2.frequency.div(h1.frequency);
+                intervalSet.add(ratio);
+            }
+        }
+        return 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) {
+        if (maxGapCents <= 0) {
+            throw new Error('maxGapCents must be positive');
+        }
+        // Convert cents to ratio (1 cent = 2^(1/1200))
+        const maxGapRatio = Math.pow(2, maxGapCents / 1200);
+        // Keep adding intervals until all gaps are small enough
+        let needsMorePoints = true;
+        while (needsMorePoints) {
+            const sorted = this.getRatios();
+            needsMorePoints = false;
+            // Check each adjacent pair
+            for (let i = 0; i < sorted.length - 1; i++) {
+                const left = sorted[i];
+                const right = sorted[i + 1];
+                // Calculate logarithmic gap (ratio of ratios)
+                const gapRatio = right.div(left).valueOf();
+                // If gap is too large, add the geometric mean
+                if (gapRatio > maxGapRatio) {
+                    // Geometric mean: sqrt(a * b) - the logarithmic midpoint
+                    const geometricMean = Math.sqrt(left.valueOf() * right.valueOf());
+                    this.add(geometricMean);
+                    needsMorePoints = true;
+                }
+            }
+        }
+        return this;
+    }
+}

package/dist/classes/Spectrum.d.ts

@@ -0,0 +1,127 @@
+import Fraction, { type FractionInput } from 'fraction.js';
+import { Harmonic } from './Harmonic';
+import { type HarmonicData, type SpectrumData } from '../lib';
+/**
+ * Represents a spectrum as a collection of harmonics.
+ * Uses Map to ensure no duplicate frequencies.
+ * Key is the frequency as a string (e.g., "3/2") for exact matching.
+ *
+ * @example
+ * // Empty spectrum
+ * const s1 = new Spectrum();
+ *
+ * // Add harmonics using various representations
+ * s1.add(new Harmonic(3, 0.5, 0));
+ * s1.add(2, 0.3, Math.PI);
+ * s1.add({ frequency: '440', amplitude: 0.2, phase: Math.PI / 2 });
+ *
+ * @example
+ * // From SpectrumData
+ * const s2 = new Spectrum([
+ *   { frequency: '110', amplitude: 0.5, phase: 0 },
+ *   { frequency: '220', amplitude: 0.3, phase: Math.PI }
+ * ]);
+ */
+export declare class Spectrum {
+    private harmonics;
+    constructor(data?: SpectrumData);
+    /**
+    * Number of harmonics in spectrum
+    */
+    get size(): number;
+    /**
+     * Add a harmonic to the spectrum.
+     * If harmonic with same frequency exists, replaces it.
+     */
+    private addHarmonic;
+    /**
+     * Convenience method to add harmonic from various input types
+     */
+    add(harmonic: Harmonic): this;
+    add(data: HarmonicData): this;
+    add(frequency: FractionInput, amplitude?: number, phase?: number): this;
+    /**
+     * Get harmonic by frequency (FractionInput) or Harmonic class
+     */
+    get(harmonicOrFrequency: Harmonic | FractionInput): Harmonic | undefined;
+    /**
+     * Check if spectrum contains a harmonic with by frequency (FractionInput) or Harmonic class
+     */
+    has(harmonicOrFrequency: Harmonic | FractionInput): boolean;
+    /**
+     * Remove harmonic by frequency (FractionInput) or Harmonic class
+     */
+    remove(harmonicOrFrequency: Harmonic | FractionInput): this;
+    /**
+     * Get harmonics sorted by frequency (ascending)
+     */
+    getHarmonics(): Harmonic[];
+    /**
+     * Get all frequencies as an array
+     */
+    getFrequenciesAsNumbers(): number[];
+    /**
+     * TODO: UNTESTED
+     * Get all keys (frequency strings) as an unsorted array.
+     * Useful for iterating over harmonics.
+     */
+    getKeys(): string[];
+    /**
+     * Check if spectrum is empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Clear all harmonics
+     */
+    clear(): this;
+    /**
+     * Method to transpose a single harmonic in place
+     * Removes the old harmonic and adds the transposed one
+     */
+    transposeHarmonic(harmonicOrFrequency: Harmonic | FractionInput, ratio: FractionInput): this;
+    /**
+     * Transpose entire spectrum by a ratio in place
+     */
+    transpose(ratio: FractionInput): this;
+    toTransposed(ratio: FractionInput): Spectrum;
+    /**
+     * Scale all amplitudes by a factor
+     */
+    scaleAmplitudes(factor: number): this;
+    /**
+     * Get the lowest frequency harmonic
+     */
+    getLowestHarmonic(): Harmonic | undefined;
+    /**
+     * Get the highest frequency harmonic
+     */
+    getHighestHarmonic(): Harmonic | undefined;
+    /**
+     * Calculate GCD of all frequency ratios
+     */
+    private getGCD;
+    /**
+    * Calculate period of the resulting wave
+    */
+    getPeriod(): Fraction | undefined;
+    /**
+     * Create a copy of this spectrum
+     */
+    clone(): Spectrum;
+    /**
+     * Iterate over harmonics
+     */
+    forEach(callback: (harmonic: Harmonic, key: string) => void): void;
+    /**
+     * Serialize spectrum to JSON
+     */
+    toJSON(): SpectrumData;
+    /**
+     * Create harmonic spectrum (110 Hz, 220 Hz, 330 Hz, 440 Hz, ...)
+     */
+    static harmonic(count: number, fundamentalHz: FractionInput): Spectrum;
+    /**
+     * Create spectrum from arrays of arbitrary frequencies, amplitudes and phases
+     */
+    static fromFrequencies(frequencies: FractionInput[], amplitudes?: number[], phases?: number[]): Spectrum;
+}

package/dist/classes/Spectrum.js

@@ -0,0 +1,279 @@
+import Fraction, {} from 'fraction.js';
+import { Harmonic } from './Harmonic';
+import { isHarmonicData } from '../lib';
+/**
+ * Represents a spectrum as a collection of harmonics.
+ * Uses Map to ensure no duplicate frequencies.
+ * Key is the frequency as a string (e.g., "3/2") for exact matching.
+ *
+ * @example
+ * // Empty spectrum
+ * const s1 = new Spectrum();
+ *
+ * // Add harmonics using various representations
+ * s1.add(new Harmonic(3, 0.5, 0));
+ * s1.add(2, 0.3, Math.PI);
+ * s1.add({ frequency: '440', amplitude: 0.2, phase: Math.PI / 2 });
+ *
+ * @example
+ * // From SpectrumData
+ * const s2 = new Spectrum([
+ *   { frequency: '110', amplitude: 0.5, phase: 0 },
+ *   { frequency: '220', amplitude: 0.3, phase: Math.PI }
+ * ]);
+ */
+export class Spectrum {
+    harmonics;
+    constructor(data) {
+        this.harmonics = new Map();
+        if (data) {
+            for (const harmonicData of data) {
+                const harmonic = new Harmonic(harmonicData);
+                this.addHarmonic(harmonic);
+            }
+        }
+    }
+    /**
+    * Number of harmonics in spectrum
+    */
+    get size() {
+        return this.harmonics.size;
+    }
+    /**
+     * Add a harmonic to the spectrum.
+     * If harmonic with same frequency exists, replaces it.
+     */
+    addHarmonic(harmonic) {
+        const key = harmonic.frequencyStr;
+        this.harmonics.set(key, harmonic);
+        return this;
+    }
+    add(harmonicOrDataOrFreq, amplitude, phase) {
+        if (harmonicOrDataOrFreq instanceof Harmonic) {
+            // Harmonic case
+            this.addHarmonic(harmonicOrDataOrFreq);
+        }
+        else if (isHarmonicData(harmonicOrDataOrFreq)) {
+            // HarmonicData case
+            const harmonic = new Harmonic(harmonicOrDataOrFreq);
+            this.addHarmonic(harmonic);
+        }
+        else {
+            // FractionInput case: frequency, amplitude, phase
+            const harmonic = new Harmonic(harmonicOrDataOrFreq, amplitude ?? 1, phase ?? 0);
+            this.addHarmonic(harmonic);
+        }
+        return this;
+    }
+    /**
+     * Get harmonic by frequency (FractionInput) or Harmonic class
+     */
+    get(harmonicOrFrequency) {
+        if (harmonicOrFrequency instanceof Harmonic) {
+            const key = harmonicOrFrequency.frequencyStr;
+            return this.harmonics.get(key);
+        }
+        else {
+            const key = new Fraction(harmonicOrFrequency).toFraction();
+            return this.harmonics.get(key);
+        }
+    }
+    /**
+     * Check if spectrum contains a harmonic with by frequency (FractionInput) or Harmonic class
+     */
+    has(harmonicOrFrequency) {
+        if (harmonicOrFrequency instanceof Harmonic) {
+            const key = harmonicOrFrequency.frequencyStr;
+            return this.harmonics.has(key);
+        }
+        else {
+            const key = new Fraction(harmonicOrFrequency).toFraction();
+            return this.harmonics.has(key);
+        }
+    }
+    /**
+     * Remove harmonic by frequency (FractionInput) or Harmonic class
+     */
+    remove(harmonicOrFrequency) {
+        if (harmonicOrFrequency instanceof Harmonic) {
+            const key = harmonicOrFrequency.frequencyStr;
+            this.harmonics.delete(key);
+        }
+        else {
+            const key = new Fraction(harmonicOrFrequency).toFraction();
+            this.harmonics.delete(key);
+        }
+        return this;
+    }
+    /**
+     * Get harmonics sorted by frequency (ascending)
+     */
+    getHarmonics() {
+        return Array.from(this.harmonics.values()).sort((a, b) => a.compareFrequency(b));
+    }
+    /**
+     * Get all frequencies as an array
+     */
+    getFrequenciesAsNumbers() {
+        return this.getHarmonics().map(h => h.frequencyNum);
+    }
+    /**
+     * TODO: UNTESTED
+     * Get all keys (frequency strings) as an unsorted array.
+     * Useful for iterating over harmonics.
+     */
+    getKeys() {
+        return Array.from(this.harmonics.keys());
+    }
+    /**
+     * Check if spectrum is empty
+     */
+    isEmpty() {
+        return this.size === 0;
+    }
+    /**
+     * Clear all harmonics
+     */
+    clear() {
+        this.harmonics.clear();
+        return this;
+    }
+    /**
+     * Method to transpose a single harmonic in place
+     * Removes the old harmonic and adds the transposed one
+     */
+    transposeHarmonic(harmonicOrFrequency, ratio) {
+        const oldHarmonic = this.get(harmonicOrFrequency);
+        if (!oldHarmonic)
+            return this;
+        const oldKey = oldHarmonic.frequencyStr;
+        const newHarmonic = oldHarmonic.toTransposed(ratio);
+        const newKey = newHarmonic.frequencyStr;
+        if (oldKey === newKey)
+            return this;
+        this.harmonics.delete(oldKey);
+        this.harmonics.set(newKey, newHarmonic);
+        return this;
+    }
+    /**
+     * Transpose entire spectrum by a ratio in place
+     */
+    transpose(ratio) {
+        const r = new Fraction(ratio);
+        const ratioValue = r.valueOf();
+        if (ratioValue === 1)
+            return this;
+        if (ratioValue <= 0)
+            throw new Error('Ratio must be greater than 0');
+        const allHarmonics = this.getHarmonics();
+        // If transposing up, start from highest frequency and go down
+        if (ratioValue > 1) {
+            for (let i = allHarmonics.length - 1; i >= 0; i--) {
+                this.transposeHarmonic(allHarmonics[i], r);
+            }
+            return this;
+        }
+        for (let i = 0; i < allHarmonics.length; i++) {
+            this.transposeHarmonic(allHarmonics[i], r);
+        }
+        return this;
+    }
+    toTransposed(ratio) {
+        return this.clone().transpose(ratio);
+    }
+    /**
+     * Scale all amplitudes by a factor
+     */
+    scaleAmplitudes(factor) {
+        for (const harmonic of this.harmonics.values()) {
+            harmonic.scale(factor);
+        }
+        return this;
+    }
+    /**
+     * Get the lowest frequency harmonic
+     */
+    getLowestHarmonic() {
+        const sorted = this.getHarmonics();
+        return sorted[0];
+    }
+    /**
+     * Get the highest frequency harmonic
+     */
+    getHighestHarmonic() {
+        const sorted = this.getHarmonics();
+        return sorted[sorted.length - 1];
+    }
+    /**
+     * Calculate GCD of all frequency ratios
+     */
+    getGCD() {
+        const frequencies = this.getHarmonics().map(h => h.frequency);
+        if (frequencies.length === 0)
+            return undefined;
+        let gcd = frequencies[0];
+        for (let i = 1; i < frequencies.length; i++) {
+            const freq = frequencies[i];
+            if (freq)
+                gcd = gcd.gcd(freq);
+        }
+        return gcd;
+    }
+    /**
+    * Calculate period of the resulting wave
+    */
+    getPeriod() {
+        const gcd = this.getGCD();
+        if (!gcd)
+            return undefined;
+        return gcd.inverse();
+    }
+    /**
+     * Create a copy of this spectrum
+     */
+    clone() {
+        const copy = new Spectrum();
+        for (const harmonic of this.harmonics.values()) {
+            copy.addHarmonic(harmonic.clone());
+        }
+        return copy;
+    }
+    /**
+     * Iterate over harmonics
+     */
+    forEach(callback) {
+        this.harmonics.forEach(callback);
+    }
+    /**
+     * Serialize spectrum to JSON
+     */
+    toJSON() {
+        const data = [];
+        for (const harmonic of this.harmonics.values()) {
+            data.push(harmonic.toJSON());
+        }
+        return data;
+    }
+    /**
+     * Create harmonic spectrum (110 Hz, 220 Hz, 330 Hz, 440 Hz, ...)
+     */
+    static harmonic(count, fundamentalHz) {
+        const spectrum = new Spectrum();
+        for (let i = 1; i <= count; i++) {
+            spectrum.add(new Fraction(fundamentalHz).mul(i), 1 / i);
+        }
+        return spectrum;
+    }
+    /**
+     * Create spectrum from arrays of arbitrary frequencies, amplitudes and phases
+     */
+    static fromFrequencies(frequencies, amplitudes, phases) {
+        const spectrum = new Spectrum();
+        frequencies.forEach((frequency, i) => {
+            const amp = amplitudes?.[i] ?? 1;
+            const phase = phases?.[i] ?? 0;
+            spectrum.add(frequency, amp, phase);
+        });
+        return spectrum;
+    }
+}

package/dist/classes/index.js

@@ -0,0 +1,3 @@
+export * from './Harmonic';
+export * from './Spectrum';
+export * from './IntervalSet';