shimi

import { IPitchContainer, FitPitchOptions } from './IPitchContainer'; import Scale from './Scale'; /** * The Chord class holds a collection of pitches that represent a chord. * * Examples: * ``` * const chord = new Chord().setRoot(36).addPitches([40, 43]); * chord.contains(40) //Returns true * chord.contains(41) //Returns false * chord.fitPitch(44) //Returns 43 * chord.getPitch(1) //Returns 40 * ``` * * @category Chords & Scales */ export default class Chord implements IPitchContainer { /** Returns the name of this type. This can be used rather than instanceof which is sometimes unreliable. */ get typeName(): string; /** * Contains the pitches that make up the chord. * * Intended for read use only. To modify the chord, use addPitch, addPitches & removePitches methods. * * Pitches should always be held in ascending order. */ get pitches(): number[]; private _pitches; /** * The root note of the chord. * * Setting this property is the same as calling the setRoot method. */ get root(): number; set root(pitch: number); private _root; /** * The bass note of the chord. */ get bass(): number; /** * Holds the name of the chord. * * Each time a pitch on the chord gets changed, the name property gets wiped out. So long as the static nameGenerator property has been set, then the next time an attempt is made to get the name, it will be automatically recalculated. */ get name(): string; set name(value: string); private _name; /** * Holds a function which will be used for any chord that needs to recalculate what its name is. * * Example: * ``` * const scale = shimi.ScaleTemplate.major.create(shimi.pitch('Eb')); * const finder = new shimi.ChordFinder().withDefaultChordLookups(); * shimi.Chord.nameGenerator = (chord) => { * const result = finder.findChord(chord.pitches, chord.root, null, scale); * if (result == null) * return null; * return result.name * .replace('{r}', scale.getPitchName(result.root)) * .replace('{r}', scale.getPitchName(result.bass)); * }; * ``` */ static nameGenerator: (Chord: any) => string; constructor(); /** * Adds a new pitch to the chord. This method ensures that pitches are stored in ascending order. * * @param pitch The pitch to add to the chord. This is only added if the chord doesn't already contain the pitch. Can also take pitch names, see the [pitch](../functions/pitch.html) method for more information. * @returns Returns the chord instance, so that method calls can be chained together. */ addPitch(pitch: number | string): Chord; /** * Adds multiple new pitches to the chord. This method ensures that pitches are stored in ascending order. * * @param pitches The pitches to add to the chord. Each one will only be added if the chord doesn't already contain the pitch. Can also take pitch names, see the [pitch](../functions/pitch.html) method for more information. * @returns Returns the chord instance, so that method calls can be chained together. */ addPitches(pitches: Array<number | string>): Chord; /** * Removes pitches from the chord that match the passed in condition. * * @param condition The condition to determine how to remove pitches, for example: `pitch => pitch % 2 == 0` would remove all even numbered pitches from the chord. * @returns Returns the chord instance, so that method calls can be chained together. */ removePitches(condition: (pitch: number) => boolean): Chord; /** * Sets the root pitch of the chord, also adds the root pitch to the list of pitches if the chord doesn't already contain it. * * @param pitch The pitch to be set as the new chord root. Can also take pitch names, see the [pitch](../functions/pitch.html) method for more information. * @returns Returns the chord instance, so that method calls can be chained together. */ setRoot(pitch: number | string): Chord; /** * Returns a pitch from the chord based on its index. Allows indices below zero or above pitches.length to fetch pitches from additional registers. * * Example: * ``` * new shimi.Chord().addPitches([36, 40, 43]).getPitchByIndex(2) => 43 * new shimi.Chord().addPitches([36, 40, 43]).getPitchByIndex(3) => 48 * new shimi.Chord().addPitches([36, 40, 43]).getPitchByIndex(-1) => 31 * ``` * * @param index The index of the pitch to fetch within the chord * @returns Returns a number representing the pitch at the specified index */ getPitchByIndex(index: number): number; /** * Returns a pitch from the chord based on its degree. To use this, you must have set the chord root. * * Example: * ``` * new shimi.Chord().setRoot(36).addPitches([40, 43]).getPitchByDegree(5) => 43 * new shimi.Chord().setRoot(36).addPitches([40, 43]).getPitchByDegree(8) => 48 * new shimi.Chord().setRoot(36).addPitches([40, 43]).getPitchByDegree(9) => 50 * ``` * @param degree The degree of the chord to fetch * @param scale Used to find which pitch to use when the chord doesn't contain the requested degree. * @returns Returns a number representing the pitch at the specified degree. */ getPitchByDegree(degree: number, scale?: Scale): number; /** * Returns true if the chord contains the passed in pitch. The method doesn't care if the pitches are in different octaves. * * @param pitch The pitch to check if contained by the chord. Can also take pitch names, see the [pitch](../functions/pitch.html) method for more information. */ contains(pitch: number | string): boolean; /** Modifies the chord in place, transposing the pitches within the chord up/down by the specified number of semitones. */ transpose(semitones: number): void; /** Creates a copy of the chord. */ duplicate(): Chord; /** * Adds one or more pitches to a chord, based on chord degrees. For example, addDegrees([3,5]) would add a 3rd & 5th to the chord. The degrees added will always default to the major/perfect variety, though if the scale parameter is used, then the minor/diminished/augmented versions can be used if they would be deemed to be a better fit within the scale. If you want to force the use of the minor/diminished version of the degree, then the degree can be provided as a negative, for example: addDegrees([-3,5]) * @param degrees The degrees of the chord to be added. * @param scale Optional, used to allow for better fitting pitch selection. * @returns Returns the chord instance, so that method calls can be chained together. */ addDegrees(degrees: Array<number>, scale?: Scale): Chord; /** * Modifies the pitches within a chord up/down octaves so that they are nearer to the desired pitch * @param pitch The pitch which the chord should be moved closer to * @param allowInversions Defaults to false, meaning the entire chord must be moved up/down as one. If true, then single pitches within the chord can be moved, allowing for inversions. * @returns Returns the chord instance which the method was called on. */ near(pitch: number | string, allowInversions?: boolean): Chord; /** * Returns a pitch near to the passed in pitch, but which should fit better with the notes within the chord. * * @param pitch The pitch which we want to fit to the chord. Can also take pitch names, see the [pitch](../functions/pitch.html) method for more information. * @param options The options allow us to configure how we want the pitch to be fitted to the chord * @returns Returns a new pitch number */ fitPitch(pitch: number | string, options?: Partial<FitPitchOptions>, fallbackOptions?: Partial<FitPitchOptions>): number; /** The pitch is part of the chord, returns 1 if in chord, 0 if not */ private _isTightFit; /** * Same as strict, but also allows pitches which belong to the scale * if they're at least 2 steps away from all of the chord pitches * Returns 1 if in chord, 0.5 if in scale and at least 2 steps from chord, 0 if neither */ private _isMediumFit; /** * The pitch belongs to either the chord, or the scale * Returns 1 if in chord, 0.5 if in scale, 0 if in neither * @param pitch * @param options * @returns */ private _isLooseFit; }