shimi/dist/types/ChordFinder.d.ts

A JS framework for building complex MIDI applications

import Scale from './Scale';
import Chord from './Chord';
/**
 * @category Chords & Scales
 */
export declare class ChordLookupData {
    shapeName: string;
    name: string;
    inverseName: string;
    pitchMap: number;
    preference: number;
    intervals: number[];
    root: number;
    constructor(shapeName: string, intervals: number[], name: string, inverseName: string, preference: number, root: number);
    private _getPitchMap;
}
/**
 * The ChordFinder.findChord method returns a ChordLookupResult whenever it manages to find a chord that fits the lookup requirements.
 *
 * The ChordLookupResult class is a collection of properties that give information about what was found.
 *
 * @category Chords & Scales
 */
export declare class ChordLookupResult {
    /** The name to use when refering to the shape of the returned chord, rather than the root-specific name of the chord.
     *
     * For example, for a minor 7th chord, this would just be 'm7'. */
    shapeName: string;
    /**
     * The name of the chord in expression form, where \{r\} is a placeholder for root and \{b\} for bass
     *
     * The reason for \{r\} and \{b\} instead of using actual pitch names is that the pitch namings can vary a lot depending on scale choice. The intention is to do something like:
     * ```
     *  lookupResult.name
     *      .replace('\{r\}', scale.getPitchName(lookupResult.root))
     *      .replace('\{b\}', scale.getPitchName(lookupResult.bass))
     * ```
     */
    name: string;
    /** The root pitch of the returned chord. */
    root: number;
    /** The bass pitch of the returned chord. */
    bass: number;
    /** The collection of all pitches in the returned chord. */
    pitches: number[];
    /** Which of the pitches in the chord were missing from the lookup request. */
    pitchesAdded: number[];
    /** Which of the pitches in the lookup request were removed in the returned chord. */
    pitchesRemoved: number[];
}
/**
 * @category Chords & Scales
 */
export default class ChordFinder {
    /** Returns the name of this type. This can be used rather than instanceof which is sometimes unreliable. */
    get typeName(): string;
    lookupData: ChordLookupData[];
    /**
     * The addChordLookup method adds a new chord shape which the findChord method is able to search through.
     *
     * @param shapeName The name to use when refering to the shape rather than a specific instance of the chord.
     *
     * For example, for a minor 7th chord, this would just be 'm7'.
     * @param intervals The intervals that make up the chord. Where each interval is defined as the semi-tone distance from the chord root.
     *
     * For example, for a major chord, this would be [0, 4, 7].
     * @param name The name of the chord in expression form, where \{r\} is a placeholder for the chord root. For example, '\{r\}M7' is the expression for a major 7th chord.
     * @param inverseName The name of the chord in expression form when inversed, where \{r\} is a placeholder for the chord root and \{b\} for the chord bass. For example, '\{r\}M7/\{b\}' is the expression for a major 7th chord, when the root is not in the bass.
     * @param preference Where 2 chords are equally well suited, the one with higher preference will be chosen.
     * @returns The ChordFinder instance is returned, to allow for chaining operations.
     */
    addChordLookup(shapeName: string, intervals: number[], name: string, inverseName: string, preference: number): ChordFinder;
    /**
     * The removeChordLookup method finds a lookup that's already been added and removes it, meaning the chord finder can no longer find chords of that type.
     * @param shapeName The shape name of the chord to remove, for example 'M' or 'm7'.
     * @returns The ChordFinder instance is returned, to allow for chaining operations.
     */
    removeChordLookup(shapeName: string): ChordFinder;
    /**
     * The replaceChordLookup method acts the same as if you called removeChordLookup, followed by addChordLookup. This just allows you to more easily redefine existing lookups.
     * @param shapeName The name to use when refering to the shape rather than a specific instance of the chord.
     *
     * For example, for a minor 7th chord, this would just be 'm7'.
     * @param intervals The intervals that make up the chord. Where each interval is defined as the semi-tone distance from the chord root.
     *
     * For example, for a major chord, this would be [0, 4, 7].
     * @param name The name of the chord in expression form, where \{r\} is a placeholder for the chord root. For example, '\{r\}M7' is the expression for a major 7th chord.
     * @param inverseName The name of the chord in expression form when inversed, where \{r\} is a placeholder for the chord root and \{b\} for the chord bass. For example, '\{r\}M7/\{b\}' is the expression for a major 7th chord, when the root is not in the bass.
     * @param preference Where 2 chords are equally well suited, the one with higher preference will be chosen.
     * @returns The ChordFinder instance is returned, to allow for chaining operations.
     */
    replaceChordLookup(shapeName: string, intervals: number[], name: string, inverseName: string, preference: number): ChordFinder;
    /**
     * The withDefaultChordLookups method sets up the ChordFinder with a default collection of chord lookups that should cover most of what you might commonly use.
     * @returns The ChordFinder instance is returned, to allow for chaining operations.
     */
    withDefaultChordLookups(): ChordFinder;
    constructor();
    /**
     * The findChord method gets passed in a collection of pitches and tries to find the best suggestion it can of what chord they make up.
     * @param pitches The currently known pitches in the chord.
     * @param root Optional, the currently known chord root.
     * @param shapeFilter Optional, the names of the chord shapes that it's allowed to return. These must match shape names of already added chord lookups.
     * @param scale Optional, the scale which any notes that need to be added to the suggested chord must belong to.
     * @returns If a matching chord is successfully found, then a ChordLookupResult instance is returned with details of the match. Otherwise the method returns null.
     */
    findChord(pitches: number[], root?: number, shapeFilter?: string[], scale?: Scale): ChordLookupResult;
    private _getAllPotentialChords;
    private _getPitchMap;
    private _getPitchMapDistance;
    /**
     * Just like the findChord method, this method returns a ChordLookupResult object with details about the best chord fit it could find.
     * However, this method performs its lookup by chord name, rather than the individual pitches that are in the chord
     * @param chordName The name of the chord to look for
     * @returns
     */
    findChordByName(chordName: string, scale?: Scale): ChordLookupResult;
    private _tryLookupMatchToChordName;
    private _getRegexStringFromLookupDataName;
    /**
     * Takes a chord name as parameter, and attempts to return a new Chord object which matches the named chord
     * @param chordName The name of the chord that we want to create
     * @returns
     */
    newChord(chordName: string, scale?: Scale): Chord;
}