@tspro/web-music-score 4.0.0 → 4.1.0

package/dist/theory/index.mjs

@@ -1,7 +1,7 @@
-/* WebMusicScore v4.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
+/* WebMusicScore v4.1.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
 import {
   __publicField
-} from "../chunk-D643HZHM.mjs";
+} from "../chunk-MHNTJ6FU.mjs";
 
 // src/theory/chord.ts
 import { Utils as Utils6 } from "@tspro/ts-utils-lib";
@@ -65,8 +65,11 @@ var DiatonicToChromaticMap = [0, 2, 4, 5, 7, 9, 11];
 var NoteNameRegex = /^([A-G])((?:bb|𝄫|♭|b|#|♯|x|𝄪)?)?(-?\d+)?$/;
 var _Note = class _Note {
   constructor(arg, accidental, octave) {
+    /** Diatonic class */
     __publicField(this, "diatonicClass");
+    /** Accidental. */
     __publicField(this, "accidental");
+    /** Octave. */
     __publicField(this, "octave");
     if (typeof arg === "number" && typeof accidental === "number" && octave === void 0) {
       _Note.validateDiatonicId(arg);
@@ -85,21 +88,32 @@ var _Note = class _Note {
       throw new MusicError2(MusicErrorType2.Note, `Invalid args: ${arg}, ${accidental}, ${octave}`);
     }
   }
+  /** Diatonic id getter. */
   get diatonicId() {
     return _Note.getDiatonicIdInOctave(this.diatonicClass, this.octave);
   }
+  /** Chromatic id getter. */
   get chromaticId() {
     return _Note.getChromaticIdInOctave(DiatonicToChromaticMap[this.diatonicClass] + this.accidental, this.octave);
   }
+  /** Midi number getter (implemented same as chromatic id). */
   get midiNumber() {
     return this.chromaticId;
   }
+  /** Chromatic class getter. */
   get chromaticClass() {
     return _Note.getChromaticClass(DiatonicToChromaticMap[this.diatonicClass] + this.accidental);
   }
+  /** Note letter getter. */
   get noteLetter() {
     return NoteLetters[this.diatonicClass];
   }
+  /**
+   * Format note to string presentation.
+   * @param pitchNotation - Pitchy notation.
+   * @param symbolSet - Symbol set.
+   * @returns - String presentation of note.
+   */
   format(pitchNotation, symbolSet) {
     let { noteLetter, octave } = this;
     let accidentalSymbol = _Note.getAccidentalSymbol(this.accidental, symbolSet);
@@ -113,11 +127,21 @@ var _Note = class _Note {
       return noteLetter + accidentalSymbol + octave;
     }
   }
+  /**
+   * Format note to string presentation without octave number.
+   * @param symbolSet - Symbol set.
+   * @returns - String presentation of note without octave number.
+   */
   formatOmitOctave(symbolSet) {
     let noteLetter = NoteLetters[this.diatonicClass];
     let accidental = _Note.getAccidentalSymbol(this.accidental, symbolSet);
     return noteLetter + accidental;
   }
+  /**
+   * Get note.
+   * @param noteName - Note name (e.g. "C4").
+   * @returns - Note.
+   */
   static getNote(noteName) {
     let note = this.noteByNameCache.get(noteName);
     if (note === void 0) {
@@ -133,6 +157,11 @@ var _Note = class _Note {
     }
     return note;
   }
+  /**
+   * Get chromatic note. There are number of alternatives, this function uses simple logic to choose one.
+   * @param chromaticId - Chromatic id.
+   * @returns - Note.
+   */
   static getChromaticNote(chromaticId) {
     let note = this.chromaticNoteCache.get(chromaticId);
     if (note === void 0) {
@@ -159,21 +188,54 @@ var _Note = class _Note {
       throw new MusicError2(MusicErrorType2.Note, `Invalid arg: ${arg}`);
     }
   }
+  /**
+   * Get octave from diatonic id.
+   * @param diatonicId - Diatonic id.
+   * @returns - Octave.
+   */
   static getOctaveFromDiatonicId(diatonicId) {
     return Math.floor((diatonicId - C0_diatonicId) / 7);
   }
+  /**
+   * Get diatonic id in given octave (transposes diatonic id to given octave).
+   * @param diatonicId - Original diatonic id.
+   * @param octave - Octave.
+   * @returns - Transposed diatonic id.
+   */
   static getDiatonicIdInOctave(diatonicId, octave) {
     return _Note.getDiatonicClass(diatonicId) + octave * 7 + C0_diatonicId;
   }
+  /**
+   * Get chromatic class from chromatic id.
+   * @param chromaticId - Chromatic id.
+   * @returns - Chromatic class.
+   */
   static getChromaticClass(chromaticId) {
     return mod(chromaticId, 12);
   }
+  /**
+   * Get octave from chromatic id.
+   * @param chromaticId - Chromatic id.
+   * @returns - Octave.
+   */
   static getOctaveFromChromaticId(chromaticId) {
     return Math.floor((chromaticId - C0_chromaticId) / 12);
   }
+  /**
+   * Get chromatic id in given octave (transposes chromatic id to given octave).
+   * @param chromaticId - Original chromatic id.
+   * @param octave - Octave.
+   * @returns - Transpose chromatic id.
+   */
   static getChromaticIdInOctave(chromaticId, octave) {
     return _Note.getChromaticClass(chromaticId) + octave * 12 + C0_chromaticId;
   }
+  /**
+   * Test if given two notes are equal.
+   * @param a - Note a.
+   * @param b - Note b.
+   * @returns - True/false.
+   */
   static equals(a, b) {
     if (a == null && b == null) {
       return true;
@@ -183,6 +245,12 @@ var _Note = class _Note {
       return a === b || a.diatonicId === b.diatonicId && a.accidental === b.accidental;
     }
   }
+  /**
+   * Replace accidental symbols in given string to givn symbol set (ascii/unicode).
+   * @param str - String to replace.
+   * @param symbolSet - Symbol set.
+   * @returns - String with updated accidental symbols.
+   */
   static replaceAccidentalSymbols(str, symbolSet) {
     if (symbolSet === 1 /* Unicode */) {
       return str.replace("bb", "\u{1D12B}").replace("b", "\u266D").replace("#", "\u266F").replace("x", "\u{1D12A}");
@@ -190,9 +258,19 @@ var _Note = class _Note {
       return str.replace("\u{1D12B}", "bb").replace("\u266D", "b").replace("\u266F", "#").replace("\u{1D12A}", "x");
     }
   }
+  /**
+   * Test if given string is valid note name.
+   * @param noteName - Note name to validate.
+   * @returns - True/false.
+   */
   static isValidNoteName(noteName) {
     return NoteNameRegex.test(noteName);
   }
+  /**
+   * Parse note name string to note props.
+   * @param noteName - Note name to parse.
+   * @returns - Parsed note props or undefined if parsing error.
+   */
   static parseNote(noteName) {
     var _a;
     let m = NoteNameRegex.exec(noteName);
@@ -206,6 +284,12 @@ var _Note = class _Note {
     let octave = octaveStr ? _Note.validateOctave(+octaveStr) : void 0;
     return { noteLetter, accidental, octave };
   }
+  /**
+   * Get scientific note name from given note name.
+   * @param noteName - Note name.
+   * @param symbolSet - Symbol set (ascii/unicode) for scientific note name.
+   * @returns - Scientific note name.
+   */
   static getScientificNoteName(noteName, symbolSet) {
     let p = _Note.parseNote(noteName);
     if (!p) {
@@ -214,9 +298,20 @@ var _Note = class _Note {
     let { noteLetter, accidental, octave } = p;
     return noteLetter + _Note.getAccidentalSymbol(accidental, symbolSet) + (octave != null ? octave : "");
   }
+  /**
+   * Get symbol of given accidental in given symbol set (ascii/unicide).
+   * @param accidental - Accidental.
+   * @param symbolsSet - Symbol set.
+   * @returns - Accidental symbol or undefined (invalid accidental).
+   */
   static getAccidentalSymbol(accidental, symbolsSet) {
     return symbolsSet === 1 /* Unicode */ ? AccidentalUnicodeSymbolMap.get(accidental) : AccidentalAsciiSymbolMap.get(accidental);
   }
+  /**
+   * Get accidental value from given accidental symbol.
+   * @param accidentalSymbol - Accidental symbol (e.g. "#").
+   * @returns - Accidental vlaue.
+   */
   static getAccidental(accidentalSymbol) {
     let accidental = AccidentalMap.get(accidentalSymbol);
     if (accidental === void 0) {
@@ -224,15 +319,32 @@ var _Note = class _Note {
     }
     return accidental;
   }
+  /**
+   * Get note letter from given diatonic id.
+   * @param diatonicId - Diatonic id.
+   * @returns - Note letter.
+   */
   static getNoteLetter(diatonicId) {
     return NoteLetters[_Note.getDiatonicClass(diatonicId)];
   }
+  /**
+   * Find next lowest possible diatonic id that is above given bottom level.
+   * @param diatonicId - Diatonic id to begin with.
+   * @param bottomDiatonicId - Bottom diatonic id.
+   * @param addOctaveIfEqual - If true then add one octave if diatonic id would equal to bottom diatonic id.
+   * @returns - Diatonic id.
+   */
   static findNextDiatonicIdAbove(diatonicId, bottomDiatonicId, addOctaveIfEqual) {
     let diatonicClass = _Note.getDiatonicClass(diatonicId);
     let bottomDiatonicClass = _Note.getDiatonicClass(bottomDiatonicId);
     let addOctave = addOctaveIfEqual ? diatonicClass <= bottomDiatonicClass ? 1 : 0 : diatonicClass < bottomDiatonicClass ? 1 : 0;
     return _Note.getDiatonicIdInOctave(diatonicClass, _Note.getOctaveFromDiatonicId(bottomDiatonicId) + addOctave);
   }
+  /**
+   * Validate if given argument is diatonic id.
+   * @param diatonicId - Diatonic id to validate.
+   * @returns - Valid diatonic id or throws.
+   */
   static validateDiatonicId(diatonicId) {
     if (Utils2.Is.isInteger(diatonicId)) {
       return diatonicId;
@@ -240,13 +352,23 @@ var _Note = class _Note {
       throw new MusicError2(MusicErrorType2.Note, `Invalid diatonicId: ${diatonicId}`);
     }
   }
+  /**
+   * Validate if given argument is diatonic class.
+   * @param diatonicClass - Diatonic class to validate.
+   * @returns - Valid diatonic class or throws.
+   */
   static validateDiatonicClass(diatonicClass) {
-    if (Utils2.Is.isInteger(diatonicClass) && diatonicClass >= 0 && diatonicClass < 7) {
+    if (Utils2.Is.isIntegerBetween(diatonicClass, 0, 6)) {
       return diatonicClass;
     } else {
       throw new MusicError2(MusicErrorType2.Note, `Invalid diatonicClass: ${diatonicClass}`);
     }
   }
+  /**
+   * Validate if given argument is chromatic id.
+   * @param chromaticId - Chromatic id to validate.
+   * @returns - Valid chromatic id, or throws.
+   */
   static validateChromaticId(chromaticId) {
     if (Utils2.Is.isInteger(chromaticId)) {
       return chromaticId;
@@ -254,20 +376,35 @@ var _Note = class _Note {
       throw new MusicError2(MusicErrorType2.Note, `Invalid chromaticId: ${chromaticId}`);
     }
   }
+  /**
+   * Validate if given argument is chromatic class.
+   * @param chromaticClass - Chromatic class to validate.
+   * @returns - Valid chromatic class, or throws.
+   */
   static validatechromaticClass(chromaticClass) {
-    if (Utils2.Is.isInteger(chromaticClass) && chromaticClass >= 0 && chromaticClass < 12) {
+    if (Utils2.Is.isIntegerBetween(chromaticClass, 0, 11)) {
       return chromaticClass;
     } else {
       throw new MusicError2(MusicErrorType2.Note, `Invalid chromaticClass: ${chromaticClass}`);
     }
   }
-  static validateNoteLetter(note) {
-    if (NoteLetters.some((n) => n === note)) {
-      return note;
+  /**
+   * Validate if given argument if note letter.
+   * @param noteLetter - Note letter to validate.
+   * @returns - Valid note letter or throws.
+   */
+  static validateNoteLetter(noteLetter) {
+    if (NoteLetters.some((n) => n === noteLetter)) {
+      return noteLetter;
     } else {
-      throw new MusicError2(MusicErrorType2.Note, `Invalid note: ${note}`);
+      throw new MusicError2(MusicErrorType2.Note, `Invalid note: ${noteLetter}`);
     }
   }
+  /**
+   * Validate if given argument is octave.
+   * @param octave - Octave to validate.
+   * @returns - Valid octave or throws.
+   */
   static validateOctave(octave) {
     if (Utils2.Is.isInteger(octave)) {
       return octave;
@@ -275,8 +412,13 @@ var _Note = class _Note {
       throw new MusicError2(MusicErrorType2.Note, `Invalid octave: ${octave}`);
     }
   }
+  /**
+   * Validate if given argument is valid accidental.
+   * @param acc - Accidental to validate.
+   * @returns - Valid accidental or thorws.
+   */
   static validateAccidental(acc) {
-    if (Utils2.Is.isInteger(acc) && acc >= -2 && acc <= 2) {
+    if (Utils2.Is.isIntegerBetween(acc, -2, 2)) {
       return acc;
     } else {
       throw new MusicError2(MusicErrorType2.Note, `Invalid accidental: ${acc}`);
@@ -304,6 +446,12 @@ var _Note = class _Note {
     });
     return uniqueSet;
   }
+  /**
+   * Function to compare two notes using diatonic id and accidental properties of notes.
+   * @param a - Note a.
+   * @param b - Note b.
+   * @returns - -1, 0 or 1.
+   */
   static compareFunc(a, b) {
     if (a.diatonicId < b.diatonicId) {
       return -1;
@@ -425,6 +573,10 @@ var _KeySignature = class _KeySignature {
     }
     this.orderedAccidentedNotes = flats.length > 0 ? flats : sharps;
   }
+  /**
+   * Get accidental type sharps, flats, or natural (without accidentals).
+   * @returns - Accidental type.
+   */
   getAccidentalType() {
     if (this.orderedAccidentedNotes.length === 0) {
       return 0 /* Natural */;
@@ -434,23 +586,40 @@ var _KeySignature = class _KeySignature {
       return 2 /* Sharps */;
     }
   }
+  /**
+   * Get natural scale notes of this key signature, natural scale has 7 steps (e.g. Major scale: W, W, H, W, W, W, H).
+   * @returns - Array of notes.
+   */
   getNaturalScaleNotes() {
     return this.naturalScaleNotes;
   }
+  /**
+   * Get accidental for given diatonic id.
+   * @param diatonicId - Diatonic id.
+   * @returns - Accidental -2, -1, 0, 1 or 2.
+   */
   getAccidental(diatonicId) {
     var _a;
     return (_a = this.accidentalByDiatonicClass[Note.getDiatonicClass(diatonicId)]) != null ? _a : 0;
   }
+  /**
+   * Get number of accidentals this key signature has.
+   * @returns - Number of accidentals.
+   */
   getNumAccidentals() {
     return this.orderedAccidentedNotes.length;
   }
+  /**
+   * Get accidental notes in correct order.
+   * @returns - Array of accidental notes.
+   */
   getOrderedAccidentalNotes() {
     return this.orderedAccidentedNotes;
   }
   /**
-   * 
-   * @param degree - number 1..7 or string e.g "b5" or "#4"
-   * @returns 
+   * Get note of key signature by degree value.
+   * @param degree - Degree number in range [1, 7] or string e.g "b5" or "#4".
+   * @returns - Note.
    */
   getNoteByDegree(degree) {
     let { deg, acc } = parseDegree(degree);
@@ -461,6 +630,12 @@ var _KeySignature = class _KeySignature {
       return new Note(note.diatonicId, note.accidental + acc);
     }
   }
+  /**
+   * Test equality of given key signatures.
+   * @param a - Key signature a.
+   * @param b - Key signature b.
+   * @returns - True/false.
+   */
   static equals(a, b) {
     if (a == null && b == null) {
       return true;
@@ -598,9 +773,13 @@ var Interval = class _Interval {
   constructor(note1, note2) {
     this.note1 = note1;
     this.note2 = note2;
+    /** Interval direction. */
     __publicField(this, "direction");
+    /** Number of semitones. */
     __publicField(this, "semitones");
+    /** Interval quantity. */
     __publicField(this, "quantity");
+    /** Interval quality. */
     __publicField(this, "quality");
     if (note2.diatonicId >= note1.diatonicId) {
       this.direction = note2.diatonicId === note1.diatonicId ? "Unison" : "Ascending";
@@ -618,6 +797,12 @@ var Interval = class _Interval {
       throw new InvalidIntervalException("Unknown interval quality");
     }
   }
+  /**
+   * Get interval between given two notes.
+   * @param note1 - First note.
+   * @param note2 - Second note.
+   * @returns - Interval if valid, or undefined.
+   */
   static get(note1, note2) {
     try {
       return new _Interval(note1, note2);
@@ -629,12 +814,20 @@ var Interval = class _Interval {
       }
     }
   }
+  /**
+   * Get string presentation of interval (e.g. "Descending Major 2").
+   * @returns - Interval string.
+   */
   toString() {
     let direction = this.direction === "Unison" ? "" : this.direction + " ";
     let quality = this.quality + " ";
     let quantity = this.direction === "Unison" ? "Unison" : formatQuantity(this.quantity);
     return direction + quality + quantity;
   }
+  /**
+   * Get abbrevated string presentation of interval (e.g. "↓M2").
+   * @returns - Interval abbrevated string.
+   */
   toAbbrString() {
     var _a;
     let direction = this.direction === "Descending" ? "\u2193" : "";
@@ -729,12 +922,20 @@ function getMode(scaleType) {
   }
 }
 var Scale = class extends KeySignature {
+  /**
+   * Create nev scale object instance.
+   * @param tonic - Tonic (e.g. "C" in "C Major").
+   * @param scaleType - Scale typo ("e.g. "Major" in "C Major").
+   */
   constructor(tonic, scaleType) {
     super(tonic, getMode(scaleType));
     this.tonic = tonic;
     this.scaleType = scaleType;
+    /** Degrees of scale notes. */
     __publicField(this, "scaleDegrees");
+    /** Scale notes. */
     __publicField(this, "scaleNotes");
+    /** Degrees (or undefined) of chromatic classes. */
     __publicField(this, "chromaticClassDegree");
     __publicField(this, "preferredChromaticNoteCache", /* @__PURE__ */ new Map());
     switch (scaleType) {
@@ -766,6 +967,12 @@ var Scale = class extends KeySignature {
       return id >= 0 ? this.scaleDegrees[id] : void 0;
     });
   }
+  /**
+   * Compare if two scales equals.
+   * @param a - Scale a.
+   * @param b - Scale b.
+   * @returns - Boolean equality of given scales.
+   */
   static equals(a, b) {
     if (a == null && b == null) {
       return true;
@@ -775,6 +982,11 @@ var Scale = class extends KeySignature {
       return a === b || a.getScaleName() === b.getScaleName();
     }
   }
+  /**
+   * Get scale name.
+   * @param symbolSet - Symbol set to format scale name in ascii or unicode.
+   * @returns - Scale name string.
+   */
   getScaleName(symbolSet) {
     switch (symbolSet) {
       case 1 /* Unicode */:
@@ -783,6 +995,12 @@ var Scale = class extends KeySignature {
         return this.tonic + " " + this.scaleType;
     }
   }
+  /**
+   * Get scale notes.
+   * @param bottomNote - Computed scale notes begin no lower than this note.
+   * @param numOctaves - How many octaves?
+   * @returns - Array of scale notes.
+   */
   getScaleNotes(bottomNote, numOctaves) {
     if (!Utils5.Is.isIntegerGte(numOctaves, 1)) {
       throw new MusicError5(MusicErrorType5.Scale, `Invalid numOctaves: ${numOctaves}`);
@@ -798,9 +1016,17 @@ var Scale = class extends KeySignature {
       return new Note(diatonicId, note.accidental);
     });
   }
+  /**
+   * Get scale overview (e.g. "C - D - E - F - G - A - B" for "C Major" scale).
+   * @returns - Scale overview string.
+   */
   getScaleOverview() {
     return this.getScaleNotes("C4", 1).map((note) => note.formatOmitOctave(1 /* Unicode */)).join(" - ");
   }
+  /**
+   * Get scale steps, array of 1 (half step) and 2 (whole step), (e.g. [2, 2, 1, 2, 2, 2, 1] for Major scale).
+   * @returns - Array of scale steps.
+   */
   getScaleSteps() {
     let chromaticIds = this.getScaleNotes("C4", 1).map((note) => note.chromaticId);
     let steps = [];
@@ -809,15 +1035,34 @@ var Scale = class extends KeySignature {
     }
     return steps;
   }
+  /**
+   * Get scale steps string presentation, array of "H" (half step) and "W" (whole step), (e.g. ["W", "W", "H", "W", "W", "W", "H"] for Major scale).
+   * @returns - Array of scale steps string presentation.
+   */
   getScaleStringSteps() {
     return this.getScaleSteps().map((step) => step === 1 ? "H" : step === 2 ? "W" : step.toString() + "H");
   }
+  /**
+   * Test if given note is scale note.
+   * @param note - Note to test.
+   * @returns - True/false.
+   */
   isScaleNote(note) {
     return this.chromaticClassDegree[note.chromaticClass] !== void 0;
   }
+  /**
+   * Test if given note is scale root note.
+   * @param note - Note to test.
+   * @returns - True/false.
+   */
   isScaleRootNote(note) {
     return String(this.chromaticClassDegree[note.chromaticClass]) === "1";
   }
+  /**
+   * Get interval value between scale root note and given note.
+   * @param note - Note.
+   * @returns - Interval.
+   */
   getIntervalFromRootNote(note) {
     let rootNote = this.getScaleNotes("C0", 1)[0];
     while (note.chromaticId >= rootNote.chromaticId + 12) {
@@ -833,6 +1078,11 @@ var Scale = class extends KeySignature {
       return interval;
     }
   }
+  /**
+   * Get preferred chromatic note from given chromatic id.
+   * @param chromaticId - Chromatic id.
+   * @returns - Note.
+   */
   getPreferredChromaticNote(chromaticId) {
     Note.validateChromaticId(chromaticId);
     let note = this.preferredChromaticNoteCache.get(chromaticId);
@@ -875,6 +1125,10 @@ var Scale = class extends KeySignature {
   }
 };
 var ScaleFactory = class {
+  /**
+   * Create new scale factory object instance.
+   * @param type - Scale type.
+   */
   constructor(type) {
     this.type = type;
     __publicField(this, "tonicList", []);
@@ -920,15 +1174,32 @@ var ScaleFactory = class {
       ...flatScales.sort(SortByAccidentalCountFunc).map((scale) => scale.tonic)
     ];
   }
+  /**
+   * Get list of tonics (e.g. "C", "C#", ... for Major scale type).
+   * @returns - Array of tonics.
+   */
   getTonicList() {
     return this.tonicList;
   }
+  /**
+   * Get default tonic.
+   * @returns - Default tonic.
+   */
   getDefaultTonic() {
     return this.tonicList[0];
   }
+  /**
+   * Get scale type.
+   * @returns - SCale type.
+   */
   getType() {
     return this.type;
   }
+  /**
+   * Get scale by given tonic.
+   * @param tonic - Tonic (e.g. "C").
+   * @returns - Scale.
+   */
   getScale(tonic) {
     let scale = this.scaleMap.get(tonic);
     if (!scale) {
@@ -937,6 +1208,11 @@ var ScaleFactory = class {
       return scale;
     }
   }
+  /**
+   * Test if this scale factory has scale for given tonic value.
+   * @param tonic - Tonic.
+   * @returns - True/false.
+   */
   hasScale(tonic) {
     return this.scaleMap.get(tonic) !== void 0;
   }
@@ -1101,9 +1377,13 @@ var Chord = class _Chord {
   constructor(chordInfo, chordNotes, rootNote, bassNote) {
     this.chordInfo = chordInfo;
     this.rootNote = rootNote;
+    /** Chord name. */
     __publicField(this, "name");
+    /** Notes of this chord. */
     __publicField(this, "notes");
+    /** Notes that are omitted in this chord (partial chord). */
     __publicField(this, "omitNotes");
+    /** Bass note if not chord root note (e.g. "B" in "C/B"). */
     __publicField(this, "slashBassNote");
     this.name = chordInfo.name;
     let notesLeft = chordNotes.slice();
@@ -1142,6 +1422,11 @@ var Chord = class _Chord {
       throw new InvalidChordException("Power chord no bass note allowed!");
     }
   }
+  /**
+   * Get all chords that can be made up with given notes.
+   * @param notes - Array of notes.
+   * @returns - Array of chords.
+   */
   static getChords(notes) {
     let chords = [];
     let chordNotes = Note.sort(notes);
@@ -1181,7 +1466,8 @@ var Chord = class _Chord {
     return true;
   }
   /**
-   * @returns Chord name e.g. "C/B"
+   * Get chord string presentation.
+   * @returns Chord string presentation (e.g. "C/B").
    */
   toString() {
     let symbolSet = 1 /* Unicode */;
@@ -1190,7 +1476,8 @@ var Chord = class _Chord {
     return rootNoteStr + this.name + slashBassStr;
   }
   /**
-   * @returns Degree notation string, e.g. "E - 1(C) - 3(E) - 5(G)"
+   * Get degree notation string (e.g. "E - 1(C) - 3(E) - 5(G)").
+   * @returns Degree notation string.
    */
   getDegreeNotationString() {
     let symbolSet = 1 /* Unicode */;
@@ -1201,7 +1488,8 @@ var Chord = class _Chord {
     return bassNoteStr + degreeNoteStr;
   }
   /**
-   * @returns Omitted degrees string e.g. "Omits 5(G), 9(D)"
+   * Get string presentation of omitted degrees (e.g. "Omits 5(G), 9(D)").
+   * @returns - String presentation of omitted degrees.
    */
   getOmittedDegreesString() {
     let omittedStrList = this.omitNotes.map((omit, i) => {
@@ -1210,15 +1498,17 @@ var Chord = class _Chord {
     return omittedStrList.length > 0 ? "Omits " + omittedStrList.join(", ") : "";
   }
   /**
-   * @param i - Degree index
-   * @returns Degree string for given degree index, e.g. "3"
+   * Degree index for given degree index (e.g. "3").
+   * @param i - Chord degree index (e.g. 0 is first note degree of chord).
+   * @returns Degree string.
    */
   getDegreeStr(i) {
     return Note.replaceAccidentalSymbols("" + this.chordInfo.degrees[i], 1 /* Unicode */);
   }
   /**
-   * @param i - Degree index
-   * @returns Note string for given degree index, e.g. "E"
+   * Get note name for given degree index (e.g. "E").
+   * @param i - Chord degree index (e.g. 0 is first note degree of chord).
+   * @returns - Note name string.
    */
   getNoteStr(i) {
     return this.notes[i].formatOmitOctave(1 /* Unicode */);
@@ -1530,6 +1820,7 @@ var NoteLength = /* @__PURE__ */ ((NoteLength3) => {
   NoteLength3["Whole"] = "1n";
   NoteLength3["WholeTriplet"] = "1t";
   NoteLength3["WholeDot"] = "1.";
+  NoteLength3["Whole2Dots"] = "1..";
   NoteLength3["Whole12Dots"] = "1..";
   NoteLength3["Whole3Dots"] = "1...";
   NoteLength3["Whole4Dots"] = "1....";
@@ -1572,17 +1863,24 @@ function validateNoteLength(noteLength) {
   }
 }
 var _NoteLengthProps = class _NoteLengthProps {
-  // Is solid (black) note head?
   constructor(noteLength) {
+    /** Note length. */
     __publicField(this, "noteLength");
+    /** Note size (whole=1, half=2, quarter=4, ...). */
     __publicField(this, "noteSize");
+    /** Number of ticks (not altered by isTriplet). */
     __publicField(this, "ticks");
-    // Not altered by isTriplet!
+    /** Flag count. */
     __publicField(this, "flagCount");
+    /** Dot count. */
     __publicField(this, "dotCount");
+    /** Max dot count. */
     __publicField(this, "maxDotCount");
+    /** Is triplet? */
     __publicField(this, "isTriplet");
+    /** Has note stem. */
     __publicField(this, "hasStem");
+    /** Is note head solid (black)? */
     __publicField(this, "isSolid");
     this.noteLength = validateNoteLength(noteLength);
     this.noteSize = parseInt(noteLength);
@@ -1599,6 +1897,11 @@ var _NoteLengthProps = class _NoteLengthProps {
       throw new MusicError8(MusicErrorType8.Note, `noteLength "${this.noteLength}" is both triplet and dotted!`);
     }
   }
+  /**
+   * Get note length props.
+   * @param noteLength - Note length.
+   * @returns - Note length props.
+   */
   static get(noteLength) {
     let p = this.cache.get(noteLength);
     if (!p) {
@@ -1606,6 +1909,12 @@ var _NoteLengthProps = class _NoteLengthProps {
     }
     return p;
   }
+  /**
+   * Create note length props.
+   * @param noteLength - Note length or note size.
+   * @param dotCount - Dot count.
+   * @returns - Note length props.
+   */
   static create(noteLength, dotCount = 0) {
     let noteSize = typeof noteLength === "number" ? noteLength : this.get(noteLength).noteSize;
     return this.get(noteSize + (Utils8.Is.isIntegerGte(dotCount, 1) ? ".".repeat(dotCount) : "n"));
@@ -1635,7 +1944,9 @@ var _NoteLengthProps = class _NoteLengthProps {
     return aNoteSize === bNoteSize;
   }
 };
+/** Longest note size (e.g. 1 = whole note). */
 __publicField(_NoteLengthProps, "LongestNoteSize", Math.min(...Utils8.Enum.getEnumValues(NoteLength).map((noteLength) => parseInt(noteLength))));
+/** Shortest note size (e.g. 64 = sixtyfourth note). */
 __publicField(_NoteLengthProps, "ShortestNoteSize", Math.max(...Utils8.Enum.getEnumValues(NoteLength).map((noteLength) => parseInt(noteLength))));
 __publicField(_NoteLengthProps, "cache", /* @__PURE__ */ new Map());
 var NoteLengthProps = _NoteLengthProps;
@@ -1647,23 +1958,30 @@ function validateTupletRatio(tupletRatio) {
   }
 }
 var Tuplet = {
-  /** 2 in the time of 3 */
+  /** Duplet: 2 in the time of 3 */
   Duplet: { parts: 2, inTimeOf: 3 },
-  /** 3 in the time of 2 */
+  /** Triplet: 3 in the time of 2 */
   Triplet: { parts: 3, inTimeOf: 2 },
-  /** 4 in the time of 3 */
+  /** Quadruplet: 4 in the time of 3 */
   Quadruplet: { parts: 4, inTimeOf: 3 }
 };
 var _RhythmProps = class _RhythmProps {
   constructor(noteLength, dotCount, tupletRatio) {
+    /** Note length. */
     __publicField(this, "noteLength");
+    /** Note size (whole=1, half=2, quarter=4, ...). */
     __publicField(this, "noteSize");
-    // whole=1, half=2, quarter=4, etc.
+    /** Dot count. */
     __publicField(this, "dotCount");
+    /** Tuplet ratio. */
     __publicField(this, "tupletRatio");
+    /** Number of ticks. */
     __publicField(this, "ticks");
+    /** Flag count. */
     __publicField(this, "flagCount");
+    /** Has note stem. */
     __publicField(this, "hasStem");
+    /** Is note head solid (black)? */
     __publicField(this, "isSolidNoteHead");
     this.noteLength = validateNoteLength(noteLength);
     let p = NoteLengthProps.get(noteLength);
@@ -1692,11 +2010,22 @@ var _RhythmProps = class _RhythmProps {
       this.ticks *= this.tupletRatio.inTimeOf / this.tupletRatio.parts;
     }
   }
+  /**
+   * Get string presentation of rhythm props.
+   * @returns - String presentation.
+   */
   toString() {
     let sym = _RhythmProps.NoteSymbolMap.get(this.noteSize);
     let dots = ".".repeat(this.dotCount);
     return sym ? sym + dots : "" + this.noteSize + (dots.length > 0 ? dots : "n");
   }
+  /**
+   * Get rhythm props with given arguments.
+   * @param noteLength - Note length.
+   * @param dotCount - Dot count.
+   * @param tupletRatio - Tuplet ratio.
+   * @returns - Rhythm props.
+   */
   static get(noteLength, dotCount, tupletRatio) {
     if (dotCount !== void 0 || tupletRatio !== void 0) {
       return new _RhythmProps(noteLength, dotCount, tupletRatio);
@@ -1733,22 +2062,50 @@ var RhythmProps = _RhythmProps;
 
 // src/theory/time-signature.ts
 import { MusicError as MusicError9, MusicErrorType as MusicErrorType9 } from "@tspro/web-music-score/core";
+var TimeSignatures = /* @__PURE__ */ ((TimeSignatures2) => {
+  TimeSignatures2["_2_4"] = "2/4";
+  TimeSignatures2["_3_4"] = "3/4";
+  TimeSignatures2["_4_4"] = "4/4";
+  TimeSignatures2["_5_8"] = "5/8";
+  TimeSignatures2["_6_8"] = "6/8";
+  TimeSignatures2["_7_8"] = "7/8";
+  TimeSignatures2["_9_8"] = "9/8";
+  TimeSignatures2["_12_8"] = "12/8";
+  return TimeSignatures2;
+})(TimeSignatures || {});
+var BeamGrouping = /* @__PURE__ */ ((BeamGrouping2) => {
+  BeamGrouping2["_2_3"] = "2-3";
+  BeamGrouping2["_3_2"] = "3-2";
+  BeamGrouping2["_2_2_3"] = "2-2-3";
+  BeamGrouping2["_3_2_2"] = "3-2-2";
+  return BeamGrouping2;
+})(BeamGrouping || {});
 var TimeSignature = class {
   constructor(...args) {
+    /** Number of beats in measure, upper value (e.g. "3" in "3/4"). */
     __publicField(this, "beatCount");
+    /** Beat size of time signature, lower value (e.g. "4" in "3/4"). */
     __publicField(this, "beatSize");
-    /** Lengths in ticks */
+    /** Beat length. */
     __publicField(this, "beatLength");
+    /** Number of ticks in measure. */
     __publicField(this, "measureTicks");
-    __publicField(this, "beamGroupCount");
-    __publicField(this, "beamGroupLength");
-    if (args.length === 1 && typeof args[0] === "string") {
+    /** Beam groups (e.g. [[2], [2]] or [[2, 2], [2, 2]] (first try as [[4], [4]])). */
+    __publicField(this, "beamGroupSizes", []);
+    let beamGrouping;
+    if (Utils9.Is.isEnumValue(args[0], TimeSignatures)) {
       let parts = args[0].split("/");
       this.beatCount = +parts[0];
       this.beatSize = +parts[1];
-    } else if (args.length === 2 && typeof args[0] === "number" && typeof args[1] === "number") {
+      if (Utils9.Is.isEnumValue(args[1], BeamGrouping)) {
+        beamGrouping = args[1];
+      }
+    } else if (Utils9.Is.isIntegerGte(args[0], 2) && Utils9.Is.isIntegerGte(args[1], 2)) {
       this.beatCount = args[0];
       this.beatSize = args[1];
+      if (Utils9.Is.isEnumValue(args[2], BeamGrouping)) {
+        beamGrouping = args[2];
+      }
     } else {
       throw new MusicError9(MusicErrorType9.Timesignature, `Invalid args: ${args}`);
     }
@@ -1757,25 +2114,55 @@ var TimeSignature = class {
     } else if (!Utils9.Is.isIntegerGte(this.beatSize, 1)) {
       throw new MusicError9(MusicErrorType9.Timesignature, `Invalid beatSize: ${this.beatSize}`);
     }
-    let props = NoteLengthProps.create(this.beatSize);
-    this.beatLength = props.noteLength;
-    this.measureTicks = this.beatCount * props.ticks;
-    if (this.is(2, 4) || this.is(3, 4) || this.is(4, 4)) {
-      this.beamGroupCount = this.beatCount;
-    } else if (this.is(6, 8) || this.is(9, 8)) {
-      this.beamGroupCount = this.beatCount / 3;
-    } else {
-      console.warn("Not necessarily an error, but unsupported time signature: " + this.toString());
-      this.beamGroupCount = 1;
+    let { noteLength, ticks } = NoteLengthProps.create(this.beatSize);
+    this.beatLength = noteLength;
+    this.measureTicks = this.beatCount * ticks;
+    if (this.is(2, 4)) {
+      this.beamGroupSizes = [[2], [2]];
+    } else if (this.is(3, 4)) {
+      this.beamGroupSizes = [[2], [2], [2]];
+    } else if (this.is(4, 4)) {
+      this.beamGroupSizes = [[2, 2], [2, 2]];
+    } else if (this.is(5, 8)) {
+      if (!Utils9.Is.isUndefined(beamGrouping) && beamGrouping !== "2-3" /* _2_3 */ && beamGrouping !== "3-2" /* _3_2 */) {
+        throw new MusicError9(MusicErrorType9.Timesignature, `Invalid beam grouping "${beamGrouping}" for time signature "${this.toString()}".`);
+      } else {
+        this.beamGroupSizes = beamGrouping === "3-2" /* _3_2 */ ? [[3], [2]] : [[2], [3]];
+        beamGrouping = void 0;
+      }
+    } else if (this.is(6, 8)) {
+      this.beamGroupSizes = [[3], [3]];
+    } else if (this.is(7, 8)) {
+      if (!Utils9.Is.isUndefined(beamGrouping) && beamGrouping !== "2-2-3" /* _2_2_3 */ && beamGrouping !== "3-2-2" /* _3_2_2 */) {
+        throw new MusicError9(MusicErrorType9.Timesignature, `Invalid beam grouping "${beamGrouping}" for time signature "${this.toString()}".`);
+      } else {
+        this.beamGroupSizes = beamGrouping === "3-2-2" /* _3_2_2 */ ? [[3], [2], [2]] : [[2], [2], [3]];
+        beamGrouping = void 0;
+      }
+    } else if (this.is(9, 8)) {
+      this.beamGroupSizes = [[3], [3], [3]];
+    } else if (this.is(12, 8)) {
+      this.beamGroupSizes = [[3], [3], [3], [3]];
     }
-    this.beamGroupLength = this.measureTicks / this.beamGroupCount;
-    if (!Utils9.Is.isIntegerGte(this.beamGroupLength, 1)) {
-      throw new MusicError9(MusicErrorType9.Timesignature, `Invalid beamGroupLength: ${this.beamGroupLength}`);
+    if (this.beamGroupSizes.length === 0) {
+      throw new MusicError9(MusicErrorType9.Timesignature, `Unimplemented time signature "${this.toString()}".`);
+    } else if (beamGrouping !== void 0) {
+      throw new MusicError9(MusicErrorType9.Timesignature, `Invalid beam grouping "${beamGrouping}" for time signature "${this.toString()}".`);
     }
   }
+  /**
+   * Test whether this time signature has given beat count and size.
+   * @param beatCount - Beat count.
+   * @param beatSize - Beat size.
+   * @returns - Boolean whether this time signature match given beat count and size.
+   */
   is(beatCount, beatSize) {
     return this.beatCount === beatCount && this.beatSize === beatSize;
   }
+  /**
+   * Get string representation of this time signature (e.g. "3/4").
+   * @returns - String representation.
+   */
   toString() {
     return this.beatCount + "/" + this.beatSize;
   }
@@ -1811,6 +2198,7 @@ import { init as initCore } from "@tspro/web-music-score/core";
 initCore();
 export {
   AccidentalType,
+  BeamGrouping,
   Chord,
   DefaultGuitarNoteLabel,
   DefaultHandedness,
@@ -1833,6 +2221,7 @@ export {
   ScaleType,
   SymbolSet,
   TimeSignature,
+  TimeSignatures,
   TuningNameList,
   Tuplet,
   alterTempoSpeed,