@tspro/web-music-score 4.0.0 → 4.1.0

package/dist/score/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/score/pub/div-rect.ts
 import { Utils } from "@tspro/ts-utils-lib";
@@ -38,11 +38,11 @@ var DivRect = class _DivRect {
   /**
    * Create rect from basic left, top, width and height arguments.
    * 
-   * @param left -
-   * @param top -
-   * @param width -
-   * @param height -
-   * @returns 
+   * @param left - Left coordinate.
+   * @param top - Top coordinate.
+   * @param width - With.
+   * @param height - Height.
+   * @returns - DivRect.
    */
   static create(left, top, width, height) {
     return new _DivRect(left, left + width, top, top + height);
@@ -52,9 +52,9 @@ var DivRect = class _DivRect {
    * 
    * @param centerX - Center x-coordinate.
    * @param centerY - Center y-coordinate.
-   * @param width -
-   * @param height -
-   * @returns 
+   * @param width - Width.
+   * @param height - Height.
+   * @returns - DivRect.
    */
   static createCentered(centerX, centerY, width, height) {
     return new _DivRect(centerX - width / 2, centerX + width / 2, centerY - height / 2, centerY + height / 2);
@@ -66,43 +66,43 @@ var DivRect = class _DivRect {
    * @param rightw - Right section width.
    * @param toph - Top section height.
    * @param bottomh - Bottomsection height.
-   * @returns 
+   * @returns - DivRect.
    */
   static createSections(leftw, rightw, toph, bottomh) {
     return new _DivRect(-leftw, 0, rightw, -toph, 0, bottomh);
   }
   /**
-   * Width.
+   * Width getter.
    */
   get width() {
     return this.right - this.left;
   }
   /**
-   * Height.
+   * Height getter.
    */
   get height() {
     return this.bottom - this.top;
   }
   /**
-   * Left section width.
+   * Left section width getter.
    */
   get leftw() {
     return this.centerX - this.left;
   }
   /**
-   * Right section width.
+   * Right section width getter.
    */
   get rightw() {
     return this.right - this.centerX;
   }
   /**
-   * Top section height.
+   * Top section height getter.
    */
   get toph() {
     return this.centerY - this.top;
   }
   /**
-   * Bottom section height.
+   * Bottom section height getter.
    */
   get bottomh() {
     return this.bottom - this.centerY;
@@ -110,9 +110,9 @@ var DivRect = class _DivRect {
   /**
    * Does this Rect contain given (x, y)-point?
    * 
-   * @param x -
-   * @param y -
-   * @returns 
+   * @param x - X-coordinate.
+   * @param y - Y-coordinate.
+   * @returns - True/false.
    */
   contains(x, y) {
     return x >= this.left && x <= this.right && y >= this.top && y <= this.bottom;
@@ -120,9 +120,9 @@ var DivRect = class _DivRect {
   /**
    * Do a and b rects overlap?
    * 
-   * @param a -
-   * @param b -
-   * @returns 
+   * @param a - DivRect a.
+   * @param b - DivRect b.
+   * @returns - True/false.
    */
   static overlap(a, b) {
     return a.right > b.left && a.left < b.right && a.bottom > b.top && a.top < b.bottom;
@@ -130,17 +130,18 @@ var DivRect = class _DivRect {
   /**
    * Do horizontal measures of a and b rects overlap?
    * 
-   * @param a -
-   * @param b -
-   * @returns 
+   * @param a - DivRect a.
+   * @param b - DivRect b.
+   * @returns - True/false.
    */
   static overlapX(a, b) {
     return a.right > b.left && a.left < b.right;
   }
   /**
    * Check if this Rect equals with given Rect.
-   * @param b -
-   * @returns 
+   * @param a - DivRect a.
+   * @param b - DivRect b.
+   * @returns - True/false.
    */
   static equals(a, b) {
     if (a == null && b == null) {
@@ -152,10 +153,11 @@ var DivRect = class _DivRect {
     }
   }
   /**
-   * Check if frame (ignoring centerX/Y) of this Rect equals with given Rect, ignoring centerX and centerY.
+   * Check if frame of this Rect equals with given Rect, ignoring center x- and center y-coordinates.
    * 
-   * @param b -
-   * @returns 
+   * @param a - DivRect a.
+   * @param b - DivRect b.
+   * @returns - True/false.
    */
   static equalsFrame(a, b) {
     if (a == null && b == null) {
@@ -169,7 +171,7 @@ var DivRect = class _DivRect {
   /**
    * Created duplicate of this Rect.
    * 
-   * @returns 
+   * @returns - Duplicate.
    */
   copy() {
     return new _DivRect(this.left, this.centerX, this.right, this.top, this.centerY, this.bottom);
@@ -177,9 +179,9 @@ var DivRect = class _DivRect {
   /**
    * Move this rect by (dx, dy). Modifies this Rect.
    * 
-   * @param dx -
-   * @param dy -
-   * @returns 
+   * @param dx - Offset amount in x-direction.
+   * @param dy - Offset amount in y-direction.
+   * @returns - This DivRect instance.
    */
   offsetInPlace(dx, dy) {
     this.left += dx;
@@ -193,9 +195,9 @@ var DivRect = class _DivRect {
   /**
    * Move this rect by (dx, dy). Immutable, returns modified copy.
    * 
-   * @param dx -
-   * @param dy -
-   * @returns 
+   * @param dx - Offset amount in x-direction.
+   * @param dy - Offset amount in y-direction.
+   * @returns - DivRect copy with applied offset.
    */
   offsetCopy(dx, dy) {
     return this.copy().offsetInPlace(dx, dy);
@@ -203,8 +205,8 @@ var DivRect = class _DivRect {
   /**
    * Expand this Rect by given Rect. Modifies this Rect.
    * 
-   * @param rect - 
-   * @returns 
+   * @param rect - DivRect to expand this instance with.
+   * @returns - This DivRect instance.
    */
   expandInPlace(rect) {
     this.left = Math.min(this.left, rect.left);
@@ -216,8 +218,8 @@ var DivRect = class _DivRect {
   /**
    * Expand this Rect by given Rect. Immutable, returns modified copy.
    * 
-   * @param rect -
-   * @returns 
+   * @param rect - DivRect to expand this instance with.
+   * @returns - Expanded copy of this DivRect.
    */
   expandCopy(rect) {
     return this.copy().expandInPlace(rect);
@@ -225,8 +227,8 @@ var DivRect = class _DivRect {
   /**
    * Clip this Rect by given Rect. Mmodifies this Rect.
    * 
-   * @param clipRect -
-   * @returns 
+   * @param clipRect - DivRect to clip this instance with.
+   * @returns - This DivRect instance.
    */
   clipInPlace(clipRect) {
     this.left = Math.max(this.left, clipRect.left);
@@ -240,8 +242,8 @@ var DivRect = class _DivRect {
   /**
    * Clip this Rect by given Rect. Immutable, return modified copy.
    * 
-   * @param clipRect -
-   * @returns 
+   * @param clipRect - DivRecto to clip this instance with.
+   * @returns - Clipped DivRect copy.
    */
   clipCopy(clipRect) {
     return this.copy().clipInPlace(clipRect);
@@ -249,9 +251,9 @@ var DivRect = class _DivRect {
   /**
    * Scale Rect. Anchor pos is (centerX, centerY). Modifies this Rect.
    * 
-   * @param scaleX -
-   * @param scaleY -
-   * @returns Copy of scaled Rect.
+   * @param scaleX - Scale x-amount.
+   * @param scaleY - Scale y-amount. If undefined then scale x-amount is used.
+   * @returns This DivRect instance.
    */
   scaleInPlace(scaleX, scaleY) {
     scaleY = scaleY != null ? scaleY : scaleX;
@@ -264,13 +266,17 @@ var DivRect = class _DivRect {
   /**
    * Scale Rect. Anchor pos is (centerX, centerY). Immutable, returns modified copy.
    * 
-   * @param scaleX -
-   * @param scaleY -
-   * @returns Copy of scaled Rect.
+   * @param scaleX - Scale x-amount.
+   * @param scaleY - Scale y-amount. If undefined then scale x-amount is used.
+   * @returns Scaled copy of this DivRect.
    */
   scaleCopy(scaleX, scaleY) {
     return this.copy().scaleInPlace(scaleX, scaleY);
   }
+  /**
+   * Get this DivRect instance.
+   * @returns - This DivRect instance.
+   */
   getRect() {
     return this;
   }
@@ -361,6 +367,27 @@ var Annotation = /* @__PURE__ */ ((Annotation2) => {
   Annotation2["Tempo"] = "tempo";
   return Annotation2;
 })(Annotation || {});
+var DynamicsAnnotation = /* @__PURE__ */ ((DynamicsAnnotation2) => {
+  DynamicsAnnotation2["cresc"] = "cresc.";
+  DynamicsAnnotation2["decresc"] = "decresc.";
+  DynamicsAnnotation2["dim"] = "dim.";
+  DynamicsAnnotation2["ppp"] = "ppp";
+  DynamicsAnnotation2["pp"] = "pp";
+  DynamicsAnnotation2["p"] = "p";
+  DynamicsAnnotation2["mp"] = "mp";
+  DynamicsAnnotation2["m"] = "m";
+  DynamicsAnnotation2["mf"] = "mf";
+  DynamicsAnnotation2["f"] = "f";
+  DynamicsAnnotation2["ff"] = "ff";
+  DynamicsAnnotation2["fff"] = "fff";
+  return DynamicsAnnotation2;
+})(DynamicsAnnotation || {});
+var TempoAnnotation = /* @__PURE__ */ ((TempoAnnotation2) => {
+  TempoAnnotation2["accel"] = "accel.";
+  TempoAnnotation2["rit"] = "rit.";
+  TempoAnnotation2["a_tempo"] = "a tempo";
+  return TempoAnnotation2;
+})(TempoAnnotation || {});
 var Label = /* @__PURE__ */ ((Label2) => {
   Label2["Note"] = "note";
   Label2["Chord"] = "chord";
@@ -875,7 +902,7 @@ import { Utils as Utils11 } from "@tspro/ts-utils-lib";
 // src/score/engine/obj-measure.ts
 import { Utils as Utils10 } from "@tspro/ts-utils-lib";
 import { getScale, Scale, validateScaleType, Note as Note7, RhythmProps as RhythmProps4, KeySignature as KeySignature2, getDefaultKeySignature, PitchNotation, SymbolSet, validateNoteLength, NoteLengthProps as NoteLengthProps4 } from "@tspro/web-music-score/theory";
-import { getDefaultTempo, TimeSignature, getDefaultTimeSignature } from "@tspro/web-music-score/theory";
+import { getDefaultTempo, getDefaultTimeSignature } from "@tspro/web-music-score/theory";
 
 // src/score/engine/acc-state.ts
 import { Note } from "@tspro/web-music-score/theory";
@@ -1258,9 +1285,9 @@ var ObjSignature = class extends MusicObject {
     if (showTimeSignature) {
       let timeSignature = this.measure.getTimeSignature();
       let beatCount = timeSignature.beatCount.toString();
-      this.beatCountText = new ObjText(this, { text: beatCount, scale: 1.4 }, 0, 0.5);
+      this.beatCountText = new ObjText(this, { text: beatCount, scale: 1.4 }, 0.5, 0.5);
       let beatSize = timeSignature.beatSize.toString();
-      this.beatSizeText = new ObjText(this, { text: beatSize, scale: 1.4 }, 0, 0.5);
+      this.beatSizeText = new ObjText(this, { text: beatSize, scale: 1.4 }, 0.5, 0.5);
     } else {
       this.beatCountText = this.beatSizeText = void 0;
     }
@@ -1350,6 +1377,7 @@ var ObjSignature = class extends MusicObject {
     return [this];
   }
   layout(renderer) {
+    var _a, _b, _c, _d, _e, _f;
     let { unitSize } = renderer;
     let { staff } = this;
     let paddingX = unitSize;
@@ -1394,15 +1422,16 @@ var ObjSignature = class extends MusicObject {
       });
     }
     let right = x;
+    (_a = this.beatCountText) == null ? void 0 : _a.layout(renderer);
+    (_b = this.beatSizeText) == null ? void 0 : _b.layout(renderer);
+    let tsWidth = Math.max((_d = (_c = this.beatCountText) == null ? void 0 : _c.getRect().width) != null ? _d : 0, (_f = (_e = this.beatSizeText) == null ? void 0 : _e.getRect().width) != null ? _f : 0);
     if (this.beatCountText) {
-      this.beatCountText.layout(renderer);
-      this.beatCountText.offset(x + paddingX, staff.getDiatonicIdY(staff.middleLineDiatonicId + 2));
+      this.beatCountText.offset(x + tsWidth / 2 + paddingX, staff.getDiatonicIdY(staff.middleLineDiatonicId + 2));
       this.rect.expandInPlace(this.beatCountText.getRect());
       right = Math.max(right, this.rect.right);
     }
     if (this.beatSizeText) {
-      this.beatSizeText.layout(renderer);
-      this.beatSizeText.offset(x + paddingX, staff.getDiatonicIdY(staff.bottomLineDiatonicId + 2));
+      this.beatSizeText.offset(x + tsWidth / 2 + paddingX, staff.getDiatonicIdY(staff.bottomLineDiatonicId + 2));
       this.rect.expandInPlace(this.beatSizeText.getRect());
       right = Math.max(right, this.rect.right);
     }
@@ -2791,11 +2820,10 @@ var ObjNoteGroup = class _ObjNoteGroup extends MusicObject {
   }
   setStemTipY(staff, stemTipY) {
     let obj = this.staffObjects.find((obj2) => obj2.staff === staff);
-    if (!(obj == null ? void 0 : obj.stemTip) || stemTipY === obj.stemTip.centerY) {
-      return;
+    if (this.hasBeamCount() && (obj == null ? void 0 : obj.stemTip) && stemTipY !== obj.stemTip.centerY) {
+      obj.stemTip.top = obj.stemTip.centerY = obj.stemTip.bottom = stemTipY;
+      this.requestRectUpdate();
     }
-    obj.stemTip.top = obj.stemTip.centerY = obj.stemTip.bottom = stemTipY;
-    this.requestRectUpdate();
   }
   offset(dx, dy) {
     this.staffObjects.forEach((obj) => obj.offset(dx, 0));
@@ -3324,6 +3352,9 @@ var ObjRhythmColumn = class extends MusicObject {
   }
 };
 
+// src/score/engine/extension.ts
+import { MusicError as MusicError9, MusicErrorType as MusicErrorType9 } from "@tspro/web-music-score/core";
+
 // src/score/engine/element-data.ts
 import { Utils as Utils5 } from "@tspro/ts-utils-lib";
 
@@ -3446,29 +3477,8 @@ function getNavigationString(navigation) {
       return navigation[0].toUpperCase() + navigation.substring(1);
   }
 }
-var DynamicsAnnotations = /* @__PURE__ */ ((DynamicsAnnotations2) => {
-  DynamicsAnnotations2["cresc"] = "cresc.";
-  DynamicsAnnotations2["decresc"] = "decresc.";
-  DynamicsAnnotations2["dim"] = "dim.";
-  DynamicsAnnotations2["ppp"] = "ppp";
-  DynamicsAnnotations2["pp"] = "pp";
-  DynamicsAnnotations2["p"] = "p";
-  DynamicsAnnotations2["mp"] = "mp";
-  DynamicsAnnotations2["m"] = "m";
-  DynamicsAnnotations2["mf"] = "mf";
-  DynamicsAnnotations2["f"] = "f";
-  DynamicsAnnotations2["ff"] = "ff";
-  DynamicsAnnotations2["fff"] = "fff";
-  return DynamicsAnnotations2;
-})(DynamicsAnnotations || {});
-var TempoAnnotations = /* @__PURE__ */ ((TempoAnnotations2) => {
-  TempoAnnotations2["accel"] = "accel.";
-  TempoAnnotations2["rit"] = "rit.";
-  TempoAnnotations2["a_tempo"] = "a tempo";
-  return TempoAnnotations2;
-})(TempoAnnotations || {});
 function isDynamicsText(text) {
-  return Utils5.Is.isEnumValue(text, DynamicsAnnotations);
+  return Utils5.Is.isEnumValue(text, DynamicsAnnotation);
 }
 function getDynamicsVolume(text) {
   if (/^(p+|f+|m|mp|mf)$/.test(text)) {
@@ -3479,12 +3489,12 @@ function getDynamicsVolume(text) {
   }
 }
 function isTempoText(text) {
-  return Utils5.Is.isEnumValue(text, TempoAnnotations);
+  return Utils5.Is.isEnumValue(text, TempoAnnotation);
 }
 function getAnnotation(text) {
-  if (Utils5.Is.isEnumValue(text, DynamicsAnnotations)) {
+  if (Utils5.Is.isEnumValue(text, DynamicsAnnotation)) {
     return "dynamics" /* Dynamics */;
-  } else if (Utils5.Is.isEnumValue(text, TempoAnnotations)) {
+  } else if (Utils5.Is.isEnumValue(text, TempoAnnotation)) {
     return "tempo" /* Tempo */;
   } else {
     return void 0;
@@ -3492,7 +3502,6 @@ function getAnnotation(text) {
 }
 
 // src/score/engine/extension.ts
-import { MusicError as MusicError9, MusicErrorType as MusicErrorType9 } from "@tspro/web-music-score/core";
 function getTextAnchorY(linePos) {
   switch (linePos) {
     case "bottom":
@@ -5023,7 +5032,7 @@ var _ObjMeasure = class _ObjMeasure extends MusicObject {
   setTimeSignature(timeSignature) {
     var _a;
     (_a = this.getPrevMeasure()) == null ? void 0 : _a.endSection();
-    this.alterTimeSignature = timeSignature instanceof TimeSignature ? timeSignature : new TimeSignature(timeSignature);
+    this.alterTimeSignature = timeSignature;
     this.updateTimeSignature();
   }
   updateTimeSignature() {
@@ -5553,52 +5562,77 @@ var _ObjMeasure = class _ObjMeasure extends MusicObject {
         return false;
       }
     });
+    let ts = this.getTimeSignature();
+    if (!this.needBeamsUpdate || ts.beamGroupSizes.length === 0) {
+      return;
+    }
     getVoiceIds().forEach((voiceId) => {
-      let symbols = this.getVoiceSymbols(voiceId);
-      if (symbols.length <= 2) {
-        return;
-      }
-      if (!DebugSettings.DisableBeams) {
-        let groupSymbols = [];
+      let symbols = this.getVoiceSymbols(voiceId).slice();
+      if (symbols.length >= 2) {
+        let symbolsStartTicks = this.isUpBeat() ? Math.max(0, this.getMeasureTicks() - this.getConsumedTicks()) : 0;
         let groupStartTicks = 0;
-        let groupEndTicks = 0;
-        if (this.isUpBeat()) {
-          let startTicks = Math.max(0, this.getMeasureTicks() - this.getConsumedTicks());
-          groupStartTicks = groupEndTicks = startTicks;
-        }
-        let ts = this.getTimeSignature();
-        symbols.forEach((symbol) => {
-          groupSymbols.push(symbol);
-          groupEndTicks += symbol.rhythmProps.ticks;
-          if (groupStartTicks === 0 && groupEndTicks === ts.beamGroupLength) {
-            _ObjMeasure.setupBeamGroup(groupSymbols);
-          }
-          while (groupEndTicks >= ts.beamGroupLength) {
-            groupSymbols = [];
-            groupStartTicks = groupEndTicks = groupEndTicks - ts.beamGroupLength;
+        for (let groupId = 0; groupId < ts.beamGroupSizes.length; groupId++) {
+          let beamGroupSize = ts.beamGroupSizes[groupId];
+          let groupSizeSum = 0;
+          beamGroupSize.forEach((s) => groupSizeSum += s);
+          let groupLength = groupSizeSum * NoteLengthProps4.get("8n").ticks;
+          let groupSymbols = [];
+          let groupSymbolsLength = 0;
+          while (symbols.length > 0 && groupSymbolsLength < groupLength) {
+            let symbol = symbols[0];
+            if (symbol.col.positionTicks >= groupStartTicks) {
+              groupSymbols.push(symbol);
+              groupSymbolsLength += symbol.rhythmProps.ticks;
+              symbols.shift();
+            } else {
+              break;
+            }
           }
-        });
+          _ObjMeasure.setupBeamGroup(groupSymbols, beamGroupSize);
+          symbolsStartTicks += groupSymbolsLength;
+          groupStartTicks += groupLength;
+        }
       }
     });
     this.needBeamsUpdate = false;
     this.requestLayout();
   }
-  static setupBeamGroup(groupSymbols) {
+  static setupBeamGroup(groupSymbols, mainBeamGroupSizeArr) {
+    if (mainBeamGroupSizeArr.length === 0) {
+      return false;
+    }
     let groupNotes = groupSymbols.map((s) => {
       var _a;
       return s instanceof ObjNoteGroup && ((_a = s.getBeamGroup()) == null ? void 0 : _a.isTuplet()) !== true ? s : void 0;
     });
     ObjNoteGroup.setBeamCounts(groupNotes);
-    let beamNotes = [];
-    groupNotes.forEach((noteGroup) => {
-      if (noteGroup && noteGroup.hasBeamCount()) {
-        beamNotes.push(noteGroup);
-      } else {
-        ObjBeamGroup.createBeam(beamNotes);
-        beamNotes = [];
-      }
-    });
-    ObjBeamGroup.createBeam(beamNotes);
+    let beamGroupSizeArrList = [mainBeamGroupSizeArr];
+    if (mainBeamGroupSizeArr.length > 1) {
+      let sum = 0;
+      mainBeamGroupSizeArr.forEach((s) => sum += s);
+      beamGroupSizeArrList.unshift([sum]);
+    }
+    let beamsCreated = false;
+    while (beamGroupSizeArrList.length > 0 && !beamsCreated) {
+      let beamGroupSizeArr = beamGroupSizeArrList.shift();
+      let groupSymbolsCopy = groupSymbols.slice();
+      beamGroupSizeArr.forEach((beamGroupSize) => {
+        var _a;
+        let beamGroupLength = beamGroupSize * NoteLengthProps4.get("8n").ticks;
+        let beamNotesLength = 0;
+        let beamNotes = [];
+        while (beamNotesLength < beamGroupLength && groupSymbolsCopy.length > 0) {
+          let symbol = groupSymbolsCopy.shift();
+          beamNotesLength += symbol.rhythmProps.ticks;
+          beamNotes.push(symbol instanceof ObjNoteGroup && ((_a = symbol.getBeamGroup()) == null ? void 0 : _a.isTuplet()) !== true ? symbol : void 0);
+        }
+        if (beamNotesLength === beamGroupLength && beamNotes.every((n) => n !== void 0) && (beamNotes.every((n) => n.rhythmProps.flagCount === 1) || beamGroupSizeArrList.length === 0)) {
+          ObjBeamGroup.createBeam(beamNotes);
+          beamsCreated = true;
+        }
+      });
+    }
+    return beamsCreated;
   }
   getBarLineLeft() {
     return this.barLineLeft;
@@ -6947,7 +6981,7 @@ var ObjDocument = class extends MusicObject {
 };
 
 // src/score/pub/document-builder.ts
-import { KeySignature as KeySignature3, Note as Note10, NoteLength as NoteLength7, RhythmProps as RhythmProps5, Scale as Scale2, ScaleType, SymbolSet as SymbolSet2, TimeSignature as TimeSignature2, TuningNameList, validateNoteLength as validateNoteLength2, validateTupletRatio } from "@tspro/web-music-score/theory";
+import { BeamGrouping, KeySignature as KeySignature3, Note as Note10, NoteLength as NoteLength7, RhythmProps as RhythmProps5, Scale as Scale2, ScaleType, SymbolSet as SymbolSet2, TimeSignature as TimeSignature2, TimeSignatures, TuningNameList, validateNoteLength as validateNoteLength2, validateTupletRatio } from "@tspro/web-music-score/theory";
 import { MusicError as MusicError17, MusicErrorType as MusicErrorType17 } from "@tspro/web-music-score/core";
 function assertArg(condition, argName, argValue) {
   if (!condition) {
@@ -7035,6 +7069,9 @@ function isTupletRatio(tupletRatio) {
   }
 }
 var DocumentBuilder = class {
+  /**
+   * Create new document builder instance.
+   */
   constructor() {
     __publicField(this, "doc");
     this.doc = new ObjDocument();
@@ -7068,9 +7105,20 @@ var DocumentBuilder = class {
     var _a;
     return (_a = this.doc.getLastMeasure()) != null ? _a : this.doc.addMeasure();
   }
+  /**
+   * Get music document after finished building.
+   * @returns - Music document.
+   */
   getDocument() {
     return this.doc.getMusicInterface();
   }
+  /**
+   * Set header texts.
+   * @param title - Title of this docmument/musical piece.
+   * @param composer - Composer of this document/musical piece.
+   * @param arranger - Arranger of this document/musical piece.
+   * @returns - This document builder instance.
+   */
   setHeader(title, composer, arranger) {
     assertArg(Utils13.Is.isStringOrUndefined(title), "title", title);
     assertArg(Utils13.Is.isStringOrUndefined(composer), "composer", composer);
@@ -7078,11 +7126,20 @@ var DocumentBuilder = class {
     this.doc.setHeader(title, composer, arranger);
     return this;
   }
+  /**
+   * Automatically limit number of measures per score row.
+   * @param measuresPerRow - Number of measures per row. Must be integer >=1 or Infinity.
+   * @returns - This document builder instance.
+   */
   setMeasuresPerRow(measuresPerRow) {
     assertArg(Utils13.Is.isIntegerGte(measuresPerRow, 1) || Utils13.Is.isPosInfinity(measuresPerRow), "measuresPerRow", measuresPerRow);
     this.doc.setMeasuresPerRow(measuresPerRow);
     return this;
   }
+  /**
+   * Add new measure.
+   * @returns - This document builder instance.
+   */
   addMeasure() {
     this.doc.addMeasure();
     return this;
@@ -7092,9 +7149,16 @@ var DocumentBuilder = class {
     this.getMeasure().setKeySignature(...args);
     return this;
   }
-  setTimeSignature(timeSignature) {
-    assertArg(timeSignature instanceof TimeSignature2 || Utils13.Is.isNonEmptyString(timeSignature), "timeSignature", timeSignature);
-    this.getMeasure().setTimeSignature(timeSignature);
+  setTimeSignature(...args) {
+    if (args[0] instanceof TimeSignature2) {
+      this.getMeasure().setTimeSignature(args[0]);
+    } else if (Utils13.Is.isEnumValue(args[0], TimeSignatures) && Utils13.Is.isEnumValueOrUndefined(args[1], BeamGrouping)) {
+      this.getMeasure().setTimeSignature(new TimeSignature2(args[0], args[1]));
+    } else if (Utils13.Is.isIntegerGte(args[0], 1) && Utils13.Is.isIntegerGte(args[1], 1) && Utils13.Is.isEnumValueOrUndefined(args[2], BeamGrouping)) {
+      this.getMeasure().setTimeSignature(new TimeSignature2(args[0], args[1], args[2]));
+    } else {
+      assertArg(false, "timeSignature args", args);
+    }
     return this;
   }
   setTempo(beatsPerMinute, beatLength, dotted) {
@@ -7108,6 +7172,14 @@ var DocumentBuilder = class {
     this.getMeasure().setTempo(beatsPerMinute, beatLength, dotted);
     return this;
   }
+  /**
+   * Add note o current measure.
+   * @param voiceId - Voice id to add note to.
+   * @param note - Note instance of Note or string (e.g. "D4").
+   * @param noteLength - Note length (e.g. "4n").
+   * @param options - Note options.
+   * @returns - This document builder instance.
+   */
   addNote(voiceId, note, noteLength, options) {
     assertArg(isVoiceId(voiceId), "voiceId", voiceId);
     assertArg(note instanceof Note10 || Utils13.Is.isNonEmptyString(note), "note", note);
@@ -7118,6 +7190,13 @@ var DocumentBuilder = class {
     this.getMeasure().addNoteGroup(voiceId, [note], noteLength, options);
     return this;
   }
+  /**
+   * @param voiceId - Voice id to add chord to.
+   * @param notes - Array of notes, each instance of Note or string (e.g. "D4"). 
+   * @param noteLength - Note length (e.g. "4n"). 
+   * @param options - Note options. 
+   * @returns - This document builder instance.
+   */
   addChord(voiceId, notes, noteLength, options) {
     assertArg(isVoiceId(voiceId), "voiceId", voiceId);
     assertArg(Utils13.Is.isNonEmptyArray(notes) && notes.every((note) => note instanceof Note10 || Utils13.Is.isNonEmptyString(note)), "notes", notes);
@@ -7128,6 +7207,13 @@ var DocumentBuilder = class {
     this.getMeasure().addNoteGroup(voiceId, notes, noteLength, options);
     return this;
   }
+  /**
+   * 
+   * @param voiceId - Voice id to add rest to.
+   * @param restLength - Rest length (e.g. "4n").  
+   * @param options - Rest options.
+   * @returns - This document builder instance.
+   */
   addRest(voiceId, restLength, options) {
     assertArg(isVoiceId(voiceId), "voiceId", voiceId);
     assertArg(Utils13.Is.isEnumValue(restLength, NoteLength7) || isNoteLength(restLength), "restLength", restLength);
@@ -7147,10 +7233,10 @@ var DocumentBuilder = class {
    * });
    * </pre>
    * 
-   * @param voiceId 
+   * @param voiceId - Voice id to add tuplet to.
    * @param tupletRatio - You can also use Theory.Tuplet presets (e.g. Theory.Tuplet.Triplet).
-   * @param tupletBuilder 
-   * @returns 
+   * @param tupletBuilder - Tuplet builder function to build tuplet.
+   * @returns - This document builder instance.
    */
   addTuplet(voiceId, tupletRatio, tupletBuilder) {
     assertArg(isVoiceId(voiceId), "voiceId", voiceId);
@@ -7201,10 +7287,20 @@ var DocumentBuilder = class {
     this.getMeasure().addFermata(staffTabOrGroups, fermata);
     return this;
   }
+  /**
+   * Add fermata to current measure.
+   * @param fermata - Fermata type (e.g. "atNote" or Fermata.AtrNote).
+   * @returns - This document builder instance.
+   */
   addFermata(fermata = "atNote" /* AtNote */) {
     return this.addFermataInternal(void 0, fermata);
   }
-  /** @param staffTabOrGroups  - staff/tab index (0=top), staff/tab name, or staff group name. */
+  /**
+   * Add Fermata to current measure to given staff/tab/group.
+   * @param staffTabOrGroups - staff/tab index (0=top), staff/tab name, or staff group name.
+   * @param fermata - Fermata type (e.g. "atNote" or Fermata.AtrNote).
+   * @returns - This document builder instance.
+   */
   addFermataTo(staffTabOrGroups, fermata = "atNote" /* AtNote */) {
     return this.addFermataInternal(staffTabOrGroups, fermata);
   }
@@ -7257,10 +7353,22 @@ var DocumentBuilder = class {
     this.getMeasure().addLabel(staffTabOrGroups, label, text);
     return this;
   }
+  /**
+   * Add label text to column of last added note/chord/rest in current measure.
+   * @param label - Label type (e.g. "chord" or Label.Chord).
+   * @param text - label text (e.g. "Am").
+   * @returns - This document builder instance.
+   */
   addLabel(label, text) {
     return this.addLabelInternal(void 0, label, text);
   }
-  /** @param staffTabOrGroups  - staff/tab index (0=top), staff/tab name, or staff group name. */
+  /**
+   * Add label text to column of last added note/chord/rest in current measure to given staff/tab/group.
+   * @param staffTabOrGroups - staff/tab index (0=top), staff/tab name, or staff group name.
+   * @param label - Label type (e.g. "chord" or Label.Chord).
+   * @param text - label text (e.g. "Am").
+   * @returns - This document builder instance.
+   */
   addLabelTo(staffTabOrGroups, label, text) {
     return this.addLabelInternal(staffTabOrGroups, label, text);
   }
@@ -7286,16 +7394,16 @@ var DocumentBuilder = class {
     return this;
   }
   /**
-   * Extension length example:
+   * Add extension line to previously added annotation or label element.
    * <pre>
+   *     // Example
    *     addExtension(ext => ext.notes("1n", 2))          // length is 2 whole notes
    *     addExtension(ext => ext.measures(3).hide())      // length is 3 measures, hidden
    *     addExtension(ext => ext.measures(1).notes("8n")) // length is 1 measure + 1 eigth note
    *     addExtension(ext => ext.infinity())              // length is as long as possible
    * </pre>
-   * @param extensionLength
-   * @param extensionVisible
-   * @returns 
+   * @param extensionBuilder - Extension builder function used to build exstension.
+   * @returns - This document builder instance.
    */
   addExtension(extensionBuilder) {
     assertArg(Utils13.Is.isFunctionOrUndefined(extensionBuilder), "addExtension() has new usage, for e.g. addExtension(ext => ext.measures(2)). Please refer to README or API Reference.", extensionBuilder);
@@ -7331,11 +7439,11 @@ var DocumentBuilder = class {
     return this;
   }
   /**
-   * 
+   * Add staff group.
    * @param groupName - Name of staff group.
    * @param staffsTabsAndGroups - staff/tab index (0=top), staff/tab name, or staff group name. Single value or array.
    * @param verticalPosition - Vertical position, are elements added above, below or both.
-   * @returns 
+   * @returns - This document builder instance.
    */
   addStaffGroup(groupName, staffsTabsAndGroups, verticalPosition = "auto" /* Auto */) {
     assertArg(Utils13.Is.isNonEmptyString(groupName), "groupName", groupName);
@@ -7348,24 +7456,48 @@ var DocumentBuilder = class {
     this.doc.addStaffGroup(groupName, staffsTabsAndGroups, verticalPosition);
     return this;
   }
+  /**
+   * Add song end. Adds certain bar line at the end of measure.
+   * @returns - This document builder instance.
+   */
   endSong() {
     this.getMeasure().endSong();
     return this;
   }
+  /**
+   * Add section end. Adds certain bar line at the end of measure.
+   * @returns - This document builder instance.
+   */
   endSection() {
     this.getMeasure().endSection();
     return this;
   }
+  /**
+   * End current score row. Next measure will start new row.
+   * @returns - This document builder instance.
+   */
   endRow() {
     var _a;
     (_a = this.doc.getLastMeasure()) == null ? void 0 : _a.endRow();
     return this;
   }
+  /**
+   * Add rests to fill current measure.
+   * @param voiceId - Voice id to add rests to. Single value, array or all if omitted.
+   * @returns - This document builder instance.
+   */
   completeRests(voiceId) {
     assertArg(Utils13.Is.isUndefined(voiceId) || isVoiceId(voiceId) || Utils13.Is.isArray(voiceId) && voiceId.every((id) => isVoiceId(id)), "voiceId", voiceId);
     this.getMeasure().completeRests(voiceId);
     return this;
   }
+  /**
+   * Add notes of given scale in ascending order.
+   * @param scale - Scale.
+   * @param bottomNote - Scale starts from note >= bottom note.
+   * @param numOctaves - Number of octaves to add.
+   * @returns - This document builder instance.
+   */
   addScaleArpeggio(scale, bottomNote, numOctaves) {
     assertArg(Utils13.Is.isNonEmptyString(bottomNote), "bottomNote", bottomNote);
     assertArg(Utils13.Is.isIntegerGte(numOctaves, 1), "numOctaves", numOctaves);
@@ -7386,11 +7518,22 @@ var DocumentBuilder = class {
 // src/score/pub/event.ts
 import { MusicError as MusicError18, MusicErrorType as MusicErrorType18 } from "@tspro/web-music-score/core";
 var ScoreEvent = class {
+  /**
+   * Create new score event instance.
+   * @param type - Score event type.
+   */
   constructor(type) {
     this.type = type;
   }
 };
 var ScoreStaffPosEvent = class extends ScoreEvent {
+  /**
+   * Create new score staff position event.
+   * @param type - Score event type.
+   * @param renderer - Renderer.
+   * @param scoreRow - Score row.
+   * @param diatonicId - Diatonic id that was clicked/entered/left.
+   */
   constructor(type, renderer, scoreRow, diatonicId) {
     super(type);
     this.renderer = renderer;
@@ -7399,6 +7542,12 @@ var ScoreStaffPosEvent = class extends ScoreEvent {
   }
 };
 var ScoreObjectEvent = class extends ScoreEvent {
+  /**
+   * Create new score object event.
+   * @param type - Score event type.
+   * @param renderer - Renderer.
+   * @param objects - Array of objects, last object in this array is the top object that was clicked/entered/left, previous objects are it's parent objects.
+   */
   constructor(type, renderer, objects) {
     super(type);
     this.renderer = renderer;
@@ -7407,16 +7556,25 @@ var ScoreObjectEvent = class extends ScoreEvent {
       throw new MusicError18(MusicErrorType18.Score, "Empty array in score object event!");
     }
   }
+  /** Top object getter. */
   get topObject() {
     return this.objects[this.objects.length - 1];
   }
+  /**
+   * Find object.
+   * @param fn - Compare function.
+   * @returns - First object that matched compare function, or undefined if no match.
+   */
   findObject(fn) {
     return this.objects.find((obj) => fn(obj));
   }
 };
 
-// src/score/pub/interface.ts
+// src/score/pub/music-interface.ts
 import * as Audio2 from "@tspro/web-music-score/audio";
+import { Utils as Utils15 } from "@tspro/ts-utils-lib";
+
+// src/score/pub/music-objects.ts
 import { Utils as Utils14 } from "@tspro/ts-utils-lib";
 import { MusicError as MusicError19, MusicErrorType as MusicErrorType19 } from "@tspro/web-music-score/core";
 function assertArg2(condition, argName, argValue) {
@@ -7424,13 +7582,6 @@ function assertArg2(condition, argName, argValue) {
     throw new MusicError19(MusicErrorType19.Score, `Invalid arg: ${argName} = ${argValue}`);
   }
 }
-function require_t(t, message) {
-  if (t === void 0 || t === null) {
-    throw new TypeError(message);
-  } else {
-    return t;
-  }
-}
 function isVoiceId2(value) {
   return Utils14.Is.isNumber(value) && getVoiceIds().indexOf(value) >= 0;
 }
@@ -7442,9 +7593,17 @@ function getNotationLine(line) {
   }
 }
 var MusicInterface6 = class {
+  /**
+   * Create new music interface object.
+   * @param name - OBject name.
+   */
   constructor(name) {
     this.name = name;
   }
+  /**
+   * Get parent object.
+   * @returns - Parent object or undefined.
+   */
   getParent() {
     var _a;
     return (_a = this.getMusicObject().getParent()) == null ? void 0 : _a.getMusicInterface();
@@ -7460,10 +7619,15 @@ var _MAccidental = class _MAccidental extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get accidental.
+   * @returns - Accidental (e.g. 1 = #).
+   */
   getAccidental() {
     return this.obj.accidental;
   }
 };
+/** Object name. */
 __publicField(_MAccidental, "Name", "Accidental");
 var MAccidental = _MAccidental;
 var _MConnective = class _MConnective extends MusicInterface6 {
@@ -7477,6 +7641,7 @@ var _MConnective = class _MConnective extends MusicInterface6 {
     return this.obj;
   }
 };
+/** Object name. */
 __publicField(_MConnective, "Name", "Connective");
 var MConnective = _MConnective;
 var _MArpeggio = class _MArpeggio extends MusicInterface6 {
@@ -7489,13 +7654,22 @@ var _MArpeggio = class _MArpeggio extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get rhythm column this arpeggio is in.
+   * @returns - Rhythm column.
+   */
   getRhythmColumn() {
     return this.obj.col.getMusicInterface();
   }
+  /**
+   * Get notation line this arpeggio is in.
+   * @returns - Staff or tab object.
+   */
   getNotationLine() {
     return getNotationLine(this.obj.line);
   }
 };
+/** Object name. */
 __publicField(_MArpeggio, "Name", "Arpeggio");
 var MArpeggio = _MArpeggio;
 var _MBeamGroup = class _MBeamGroup extends MusicInterface6 {
@@ -7509,6 +7683,7 @@ var _MBeamGroup = class _MBeamGroup extends MusicInterface6 {
     return this.obj;
   }
 };
+/** OBject name. */
 __publicField(_MBeamGroup, "Name", "BeamGroup");
 var MBeamGroup = _MBeamGroup;
 var _MStaffBeamGroup = class _MStaffBeamGroup extends MusicInterface6 {
@@ -7521,10 +7696,15 @@ var _MStaffBeamGroup = class _MStaffBeamGroup extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get staff this beam group is in.
+   * @returns - Staff object.
+   */
   getStaff() {
     return this.obj.staff.getMusicInterface();
   }
 };
+/** Object name. */
 __publicField(_MStaffBeamGroup, "Name", "StaffBeamGroup");
 var MStaffBeamGroup = _MStaffBeamGroup;
 var _MDocument = class _MDocument extends MusicInterface6 {
@@ -7537,27 +7717,53 @@ var _MDocument = class _MDocument extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get title.
+   * @returns - Title string or undefined.
+   */
   getTitle() {
     return this.obj.getTitle();
   }
+  /**
+   * Get composer.
+   * @returns - Composer string or undefined.
+   */
   getComposer() {
     return this.obj.getComposer();
     3;
   }
+  /**
+   * Get arranger.
+   * @returns - Arranger string or undefined.
+   */
   getArranger() {
     return this.obj.getArranger();
   }
+  /**
+   * Get score rows.
+   * @returns - Array or score rows.
+   */
   getRows() {
     return this.obj.getRows().map((r) => r.getMusicInterface());
   }
+  /**
+   * Get measures.
+   * @returns - Array of measures.
+   */
   getMeasures() {
     return this.obj.getMeasures().map((m) => m.getMusicInterface());
   }
-  play(fn) {
-    assertArg2(Utils14.Is.isFunctionOrUndefined(fn), "playStateChangeListener", fn);
-    return new MPlayer(this, fn).play();
+  /**
+   * Play this document.
+   * @param playStateChangeListener - Play state change listener function or undefined.
+   * @returns - Player instance.
+   */
+  play(playStateChangeListener) {
+    assertArg2(Utils14.Is.isFunctionOrUndefined(playStateChangeListener), "playStateChangeListener", playStateChangeListener);
+    return new MPlayer(this, playStateChangeListener).play();
   }
 };
+/** Object name. */
 __publicField(_MDocument, "Name", "Document");
 var MDocument2 = _MDocument;
 var _MEnding = class _MEnding extends MusicInterface6 {
@@ -7570,14 +7776,24 @@ var _MEnding = class _MEnding extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get passages.
+   * @returns - Array of passage numbers, e.g. passage number 1 means that this ending is played on first pass.
+   */
   getPassages() {
     return this.obj.passages;
   }
+  /**
+   * Has passage number?
+   * @param passage - Passage number to find out.
+   * @returns - Boolean whether this ending has asked passage number.
+   */
   hasPassage(passage) {
     assertArg2(Utils14.Is.isIntegerGte(passage, 1), "passage", passage);
     return this.obj.hasPassage(passage);
   }
 };
+/** Object name. */
 __publicField(_MEnding, "Name", "Ending");
 var MEnding = _MEnding;
 var _MFermata = class _MFermata extends MusicInterface6 {
@@ -7591,6 +7807,7 @@ var _MFermata = class _MFermata extends MusicInterface6 {
     return this.obj;
   }
 };
+/** OBject name. */
 __publicField(_MFermata, "Name", "Fermata");
 var MFermata = _MFermata;
 var _MHeader = class _MHeader extends MusicInterface6 {
@@ -7603,16 +7820,29 @@ var _MHeader = class _MHeader extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get title.
+   * @returns - Title string or undefined.
+   */
   getTitle() {
     return this.obj.title;
   }
+  /**
+   * Get composer.
+   * @returns - Composer string or undefined.
+   */
   getComposer() {
     return this.obj.composer;
   }
+  /**
+   * Get arranger.
+   * @returns - Arranger string or undefined.
+   */
   getArranger() {
     return this.obj.arranger;
   }
 };
+/** OBject name. */
 __publicField(_MHeader, "Name", "Header");
 var MHeader = _MHeader;
 var _MImage = class _MImage extends MusicInterface6 {
@@ -7626,6 +7856,7 @@ var _MImage = class _MImage extends MusicInterface6 {
     return this.obj;
   }
 };
+/** Object name. */
 __publicField(_MImage, "Name", "Image");
 var MImage = _MImage;
 var _MMeasure = class _MMeasure extends MusicInterface6 {
@@ -7638,16 +7869,29 @@ var _MMeasure = class _MMeasure extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get measure number.
+   * @returns - Measure number starting from 1, or 0 if upbeat.
+   */
   getMeasureNumber() {
     return this.obj.getMeasureNumber();
   }
+  /**
+   * Get rhythm columns.
+   * @returns - Array of rhythm columns.
+   */
   getRhythmColumns() {
     return this.obj.getColumns().map((col) => col.getMusicInterface());
   }
+  /**
+   * Get score row that this measure is in.
+   * @returns - Score row.
+   */
   getRow() {
     return this.obj.row.getMusicInterface();
   }
 };
+/** OBject name. */
 __publicField(_MMeasure, "Name", "Measure");
 var MMeasure = _MMeasure;
 var _MBarLineRight = class _MBarLineRight extends MusicInterface6 {
@@ -7661,6 +7905,7 @@ var _MBarLineRight = class _MBarLineRight extends MusicInterface6 {
     return this.obj;
   }
 };
+/** OBject name. */
 __publicField(_MBarLineRight, "Name", "BarLineRight");
 var MBarLineRight = _MBarLineRight;
 var _MBarLineLeft = class _MBarLineLeft extends MusicInterface6 {
@@ -7674,6 +7919,7 @@ var _MBarLineLeft = class _MBarLineLeft extends MusicInterface6 {
     return this.obj;
   }
 };
+/** Object name. */
 __publicField(_MBarLineLeft, "Name", "BarLineLeft");
 var MBarLineLeft = _MBarLineLeft;
 var _MStaffTabBarLine = class _MStaffTabBarLine extends MusicInterface6 {
@@ -7686,6 +7932,10 @@ var _MStaffTabBarLine = class _MStaffTabBarLine extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get parent bar line object.
+   * @returns - Parent bar line object.
+   */
   getBarLine() {
     let barLine = this.obj.barLine;
     if (barLine instanceof ObjBarLineLeft || barLine instanceof ObjBarLineRight) {
@@ -7694,10 +7944,15 @@ var _MStaffTabBarLine = class _MStaffTabBarLine extends MusicInterface6 {
       throw new MusicError19(MusicErrorType19.Score, `Bar line not let nor right.`);
     }
   }
+  /**
+   * Get staff or tab this bar lien object is in.
+   * @returns - Staff or tab.
+   */
   getNotationLine() {
     return getNotationLine(this.obj.line);
   }
 };
+/** Object name. */
 __publicField(_MStaffTabBarLine, "Name", "StaffTabBarLine");
 var MStaffTabBarLine = _MStaffTabBarLine;
 var _MNoteGroup = class _MNoteGroup extends MusicInterface6 {
@@ -7710,19 +7965,36 @@ var _MNoteGroup = class _MNoteGroup extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get notes of this note group.
+   * @returns - Array of Note instances.
+   */
   getNotes() {
     return this.obj.notes;
   }
+  /**
+   * Get rhythm props of this note group.
+   * @returns - Rhythm props.
+   */
   getRhythmProps() {
     return this.obj.rhythmProps;
   }
+  /**
+   * Get rhythm column this note group is in.
+   * @returns - Rhythm column.
+   */
   getRhythmColumn() {
     return this.obj.col.getMusicInterface();
   }
+  /**
+   * Get the measure this note group is in.
+   * @returns - Measure.
+   */
   getMeasure() {
     return this.obj.measure.getMusicInterface();
   }
 };
+/** Object name. */
 __publicField(_MNoteGroup, "Name", "NoteGroup");
 var MNoteGroup = _MNoteGroup;
 var _MStaffNoteGroup = class _MStaffNoteGroup extends MusicInterface6 {
@@ -7735,19 +8007,36 @@ var _MStaffNoteGroup = class _MStaffNoteGroup extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get parent note group.
+   * @returns - Parent note group.
+   */
   getNoteGroup() {
     return this.obj.noteGroup.getMusicInterface();
   }
+  /**
+   * Get rhythm column this note group is in.
+   * @returns - Rhythm column.
+   */
   getRhythmColumn() {
     return this.getNoteGroup().getRhythmColumn();
   }
+  /**
+   * Get the measure this note group is in.
+   * @returns - Measure.
+   */
   getMeasure() {
     return this.getNoteGroup().getMeasure();
   }
+  /**
+   * Get staff notation line this note group is in.
+   * @returns - Staff object.
+   */
   getStaff() {
     return this.obj.staff.getMusicInterface();
   }
 };
+/** Object name. */
 __publicField(_MStaffNoteGroup, "Name", "StaffNoteGroup");
 var MStaffNoteGroup = _MStaffNoteGroup;
 var _MTabNoteGroup = class _MTabNoteGroup extends MusicInterface6 {
@@ -7760,19 +8049,36 @@ var _MTabNoteGroup = class _MTabNoteGroup extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get parent note group.
+   * @returns - Parent note group.
+   */
   getNoteGroup() {
     return this.obj.noteGroup.getMusicInterface();
   }
+  /**
+   * Get rhythm column this note group is in.
+   * @returns - Rhythm column.
+   */
   getRhythmColumn() {
     return this.getNoteGroup().getRhythmColumn();
   }
+  /**
+   * Get the measure this note group is in.
+   * @returns - Measure.
+   */
   getMeasure() {
     return this.getNoteGroup().getMeasure();
   }
+  /**
+   * Get guitar tab this note group is in.
+   * @returns - Tab object.
+   */
   getTab() {
     return this.obj.tab.getMusicInterface();
   }
 };
+/** OBject name. */
 __publicField(_MTabNoteGroup, "Name", "TabNoteGroup");
 var MTabNoteGroup = _MTabNoteGroup;
 var _MRest = class _MRest extends MusicInterface6 {
@@ -7785,16 +8091,29 @@ var _MRest = class _MRest extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get rhythm props of this rest.
+   * @returns - Rhythm props.
+   */
   getRhythmProps() {
     return this.obj.rhythmProps;
   }
+  /**
+   * Get rhythm column this rest is in.
+   * @returns - Rhythm column.
+   */
   getRhythmColumn() {
     return this.obj.col.getMusicInterface();
   }
+  /**
+   * Get the measure this rest is in.
+   * @returns - Measure.
+   */
   getMeasure() {
     return this.obj.measure.getMusicInterface();
   }
 };
+/** OBject name. */
 __publicField(_MRest, "Name", "Rest");
 var MRest = _MRest;
 var _MStaffRest = class _MStaffRest extends MusicInterface6 {
@@ -7807,19 +8126,36 @@ var _MStaffRest = class _MStaffRest extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get parent rest object.
+   * @returns - Parent rest object.
+   */
   getRest() {
     return this.obj.rest.getMusicInterface();
   }
+  /**
+   * Get rhythm column this rest is in.
+   * @returns - Rhythm column.
+   */
   getRhythmColumn() {
     return this.getRest().getRhythmColumn();
   }
+  /**
+   * Get the measure this rest is in.
+   * @returns - Measure.
+   */
   getMeasure() {
     return this.getRest().getMeasure();
   }
+  /**
+   * Get staff notation line this rest is in.
+   * @returns - Staff object.
+   */
   getStaff() {
     return this.obj.staff.getMusicInterface();
   }
 };
+/** Object name. */
 __publicField(_MStaffRest, "Name", "StaffRest");
 var MStaffRest = _MStaffRest;
 var _MRhythmColumn = class _MRhythmColumn extends MusicInterface6 {
@@ -7832,19 +8168,36 @@ var _MRhythmColumn = class _MRhythmColumn extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get symbol (note group or rest) of this column for given voice id.
+   * @param voiceId - Voice id.
+   * @returns - Note group, rest or undefined.
+   */
   getRhythmSymbol(voiceId) {
     var _a;
     assertArg2(isVoiceId2(voiceId), "voiceId", voiceId);
     return (_a = this.obj.getVoiceSymbol(voiceId)) == null ? void 0 : _a.getMusicInterface();
   }
+  /**
+   * Get symbol (note group or rest) of this column for given voice id.
+   * @deprecated - Use getRhythmSymbol(voiceId) instead.
+   * @param voiceId - Voice id.
+   * @returns - Note group, rest or undefined.
+   */
+  getVoiceSymbol(voiceId) {
+    var _a;
+    assertArg2(isVoiceId2(voiceId), "voiceId", voiceId);
+    return (_a = this.obj.getVoiceSymbol(voiceId)) == null ? void 0 : _a.getMusicInterface();
+  }
+  /**
+   * Get the measure this rhythm column is in.
+   * @returns - Measure.
+   */
   getMeasure() {
     return this.obj.measure.getMusicInterface();
   }
-  getVoiceSymbol(voiceId) {
-    let s = this.obj.getVoiceSymbol(voiceId);
-    return s instanceof ObjNoteGroup || s instanceof ObjRest ? s.getMusicInterface() : void 0;
-  }
 };
+/** OBject name. */
 __publicField(_MRhythmColumn, "Name", "RhythmColumn");
 var MRhythmColumn = _MRhythmColumn;
 var _MScoreRow = class _MScoreRow extends MusicInterface6 {
@@ -7857,16 +8210,29 @@ var _MScoreRow = class _MScoreRow extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Parent music document.
+   * @returns - Parent music document.
+   */
   getDocument() {
     return this.obj.doc.getMusicInterface();
   }
+  /**
+   * Get measures of this score row.
+   * @returns - Array of measures.
+   */
   getMeasures() {
     return this.obj.getMeasures().map((m) => m.getMusicInterface());
   }
+  /**
+   * Get notation lines (staves and tabs) of this score row.
+   * @returns - Array of staves and tabs.
+   */
   getNotationLines() {
     return this.obj.getNotationLines().map((line) => getNotationLine(line));
   }
 };
+/** Object name. */
 __publicField(_MScoreRow, "Name", "ScoreRow");
 var MScoreRow = _MScoreRow;
 var _MStaff = class _MStaff extends MusicInterface6 {
@@ -7879,16 +8245,29 @@ var _MStaff = class _MStaff extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get index of this staff in score row.
+   * @returns - Index (0=top notation line).
+   */
   getId() {
     return this.obj.id;
   }
+  /**
+   * Get name of this staff.
+   * @returns - Staff name.
+   */
   getName() {
     return this.obj.name.length > 0 ? this.obj.name : void 0;
   }
+  /**
+   * Get the score row this staff is in.
+   * @returns - Score row.
+   */
   getRow() {
     return this.obj.row.getMusicInterface();
   }
 };
+/** Object name. */
 __publicField(_MStaff, "Name", "Staff");
 var MStaff = _MStaff;
 var _MTab = class _MTab extends MusicInterface6 {
@@ -7901,16 +8280,29 @@ var _MTab = class _MTab extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get index of this guitar tab in score row.
+   * @returns - Index (0=top notation line).
+   */
   getId() {
     return this.obj.id;
   }
+  /**
+   * Get name of this guitar tab.
+   * @returns - Staff name.
+   */
   getName() {
     return this.obj.name.length > 0 ? this.obj.name : void 0;
   }
+  /**
+   * Get the score row this guitar tab is in.
+   * @returns - Score row.
+   */
   getRow() {
     return this.obj.row.getMusicInterface();
   }
 };
+/** Object name. */
 __publicField(_MTab, "Name", "Tab");
 var MTab = _MTab;
 var _MSignature = class _MSignature extends MusicInterface6 {
@@ -7923,10 +8315,15 @@ var _MSignature = class _MSignature extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get staff notation line this signature is in.
+   * @returns - Staff object.
+   */
   getStaff() {
     return this.obj.staff.getMusicInterface();
   }
 };
+/** Object name. */
 __publicField(_MSignature, "Name", "Signature");
 var MSignature = _MSignature;
 var _MSpecialText = class _MSpecialText extends MusicInterface6 {
@@ -7939,10 +8336,15 @@ var _MSpecialText = class _MSpecialText extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get text content.
+   * @returns - Text content.
+   */
   getText() {
     return this.obj.getText();
   }
 };
+/** Object name. */
 __publicField(_MSpecialText, "Name", "SpecialText");
 var MSpecialText = _MSpecialText;
 var _MText = class _MText extends MusicInterface6 {
@@ -7955,10 +8357,15 @@ var _MText = class _MText extends MusicInterface6 {
   getMusicObject() {
     return this.obj;
   }
+  /**
+   * Get text content.
+   * @returns - Text content.
+   */
   getText() {
     return this.obj.getText();
   }
 };
+/** Object name. */
 __publicField(_MText, "Name", "Text");
 var MText = _MText;
 var _MExtensionLine = class _MExtensionLine extends MusicInterface6 {
@@ -7972,33 +8379,69 @@ var _MExtensionLine = class _MExtensionLine extends MusicInterface6 {
     return this.obj;
   }
 };
+/** OBject name. */
 __publicField(_MExtensionLine, "Name", "ExtensionLine");
 var MExtensionLine = _MExtensionLine;
+
+// src/score/pub/music-interface.ts
+import { MusicError as MusicError20, MusicErrorType as MusicErrorType20 } from "@tspro/web-music-score/core";
+function assertArg3(condition, argName, argValue) {
+  if (!condition) {
+    throw new MusicError20(MusicErrorType20.Score, `Invalid arg: ${argName} = ${argValue}`);
+  }
+}
+function require_t(t, message) {
+  if (t === void 0 || t === null) {
+    throw new TypeError(message);
+  } else {
+    return t;
+  }
+}
 var _MPlayer = class _MPlayer {
-  constructor(doc, fn) {
+  /**
+   * Create new music player.
+   * @param doc - Music document to play.
+   * @param playStateChangeListener - Play state change listener.
+   */
+  constructor(doc, playStateChangeListener) {
     __publicField(this, "player");
-    assertArg2(doc instanceof MDocument2, "doc", doc);
-    assertArg2(Utils14.Is.isFunctionOrUndefined(fn), "playStateChangeListener", fn);
+    assertArg3(doc instanceof MDocument2, "doc", doc);
+    assertArg3(Utils15.Is.isFunctionOrUndefined(playStateChangeListener), "playStateChangeListener", playStateChangeListener);
     this.player = new Player();
     this.player.setDocument(doc.getMusicObject());
     this.player.setCursorPositionChangeListener((cursorRect) => doc.getMusicObject().updateCursorRect(cursorRect));
-    if (fn) {
-      this.player.setPlayStateChnageListener(fn);
+    if (playStateChangeListener) {
+      this.player.setPlayStateChnageListener(playStateChangeListener);
     }
   }
+  /**
+   * Stop all playing.
+   */
   static stopAll() {
     this.currentlyPlaying.forEach((p) => p.stop());
     Audio2.stop();
   }
+  /**
+   * Playe attached document.
+   * @returns - This player instance.
+   */
   play() {
     _MPlayer.currentlyPlaying.add(this);
     this.player.play();
     return this;
   }
+  /**
+   * Pause playback of attached document.
+   * @returns - This player instance.
+   */
   pause() {
     this.player.pause();
     return this;
   }
+  /**
+   * Stop playback of attached document.
+   * @returns - This player instance.
+   */
   stop() {
     this.player.stop();
     _MPlayer.currentlyPlaying.delete(this);
@@ -8008,33 +8451,61 @@ var _MPlayer = class _MPlayer {
 __publicField(_MPlayer, "currentlyPlaying", /* @__PURE__ */ new Set());
 var MPlayer = _MPlayer;
 var MRenderer2 = class {
+  /**
+   * Create new renderer instance.
+   */
   constructor() {
     __publicField(this, "renderer");
     this.renderer = new Renderer(this);
   }
+  /**
+   * Attach music document to this renderer.
+   * @param doc - Music document.
+   * @returns - This renderer instance.
+   */
   setDocument(doc) {
-    assertArg2(Utils14.Is.isUndefined(doc) || doc instanceof MDocument2, "doc", doc);
+    assertArg3(Utils15.Is.isUndefined(doc) || doc instanceof MDocument2, "doc", doc);
     this.renderer.setDocument(doc);
     return this;
   }
+  /**
+   * Set target canvas html element for this renderer.
+   * @param canvas - HTML canvas element or element id.
+   * @returns - This renderer instance.
+   */
   setCanvas(canvas) {
-    canvas = require_t(Utils14.Dom.getCanvas(canvas), typeof canvas === "string" ? "Cannot set renderer canvas because invalid canvas id: " + canvas : "Cannot set renderer canvas because given canvas is undefined.");
+    canvas = require_t(Utils15.Dom.getCanvas(canvas), typeof canvas === "string" ? "Cannot set renderer canvas because invalid canvas id: " + canvas : "Cannot set renderer canvas because given canvas is undefined.");
     this.renderer.setCanvas(canvas);
     return this;
   }
-  setScoreEventListener(fn) {
-    assertArg2(Utils14.Is.isFunctionOrUndefined(fn), "scoreEventListener", fn);
-    this.renderer.setScoreEventListener(fn);
+  /**
+   * Set score event listener.
+   * @param scoreEventListener - Score event listener.
+   */
+  setScoreEventListener(scoreEventListener) {
+    assertArg3(Utils15.Is.isFunctionOrUndefined(scoreEventListener), "scoreEventListener", scoreEventListener);
+    this.renderer.setScoreEventListener(scoreEventListener);
   }
+  /**
+   * Draw given music object hilighted.
+   * @param obj - Music object or undefined to remove hilighting.
+   */
   hilightObject(obj) {
     this.renderer.hilightObject(obj == null ? void 0 : obj.getMusicObject());
   }
+  /**
+   * Draw given staff position hilighted.
+   * @param staffPos - Staff position (score row and diatonic id) or undefined to remove hilighting.
+   */
   hilightStaffPos(staffPos) {
     this.renderer.hilightStaffPos(staffPos ? {
       scoreRow: staffPos.scoreRow.getMusicObject(),
       diatonicId: staffPos.diatonicId
     } : void 0);
   }
+  /**
+   * Draw contents of attached music document to attached canvas.
+   */
   draw() {
     try {
       this.renderer.draw();
@@ -8045,6 +8516,9 @@ var MRenderer2 = class {
   }
 };
 var _MPlaybackButtons = class _MPlaybackButtons {
+  /**
+   * Create new playback buttons helper class instance.
+   */
   constructor() {
     __publicField(this, "playButton");
     __publicField(this, "stopButton");
@@ -8077,8 +8551,13 @@ var _MPlaybackButtons = class _MPlaybackButtons {
     };
     this.updateButtons();
   }
+  /**
+   * Attach music document whose playcak will be controlled by this playback buttons helper class instance.
+   * @param doc - Music document.
+   * @returns 
+   */
   setDocument(doc) {
-    assertArg2(Utils14.Is.isUndefined(doc) || doc instanceof MDocument2, "doc", doc);
+    assertArg3(Utils15.Is.isUndefined(doc) || doc instanceof MDocument2, "doc", doc);
     this.onStop();
     if (doc) {
       this.player = new MPlayer(doc, (playState) => {
@@ -8091,6 +8570,9 @@ var _MPlaybackButtons = class _MPlaybackButtons {
     this.updateButtons();
     return this;
   }
+  /**
+   * Detach attached music document.
+   */
   detachDocument() {
     this.setDocument(void 0);
   }
@@ -8112,31 +8594,50 @@ var _MPlaybackButtons = class _MPlaybackButtons {
       this.pauseButton.innerText = this.pauseLabel;
     }
   }
+  /**
+   * Set play button.
+   * @param btn - HTML button element or element id.
+   * @param btnLabel - Custom button label (e.g. "Play").
+   * @returns - This playback buttons class instance.
+   */
   setPlayButton(btn, btnLabel) {
-    assertArg2(Utils14.Is.isStringOrUndefined(btnLabel), "btnLabel", btnLabel);
+    assertArg3(Utils15.Is.isStringOrUndefined(btnLabel), "btnLabel", btnLabel);
     _MPlaybackButtons.removeOnClickListeners(this.playButton, this.onPlay);
-    this.playButton = require_t(Utils14.Dom.getButton(btn), "Play button required!");
+    this.playButton = require_t(Utils15.Dom.getButton(btn), "Play button required!");
     this.playLabel = btnLabel != null ? btnLabel : "Play";
     _MPlaybackButtons.removeOnClickListeners(this.playButton, "all");
     _MPlaybackButtons.addOnClickListener(this.playButton, this.onPlay);
     this.updateButtons();
     return this;
   }
+  /**
+   * Set stop button.
+   * @param btn - HTML button element or element id.
+   * @param btnLabel - Custom button label (e.g. "Stop").
+   * @returns - This playback buttons class instance.
+   */
   setStopButton(btn, btnLabel) {
-    assertArg2(Utils14.Is.isStringOrUndefined(btnLabel), "btnLabel", btnLabel);
+    assertArg3(Utils15.Is.isStringOrUndefined(btnLabel), "btnLabel", btnLabel);
     _MPlaybackButtons.removeOnClickListeners(this.stopButton, this.onStop);
-    this.stopButton = require_t(Utils14.Dom.getButton(btn), "Stop button required!");
+    this.stopButton = require_t(Utils15.Dom.getButton(btn), "Stop button required!");
     this.stopLabel = btnLabel != null ? btnLabel : "Stop";
     _MPlaybackButtons.removeOnClickListeners(this.stopButton, "all");
     _MPlaybackButtons.addOnClickListener(this.stopButton, this.onStop);
     this.updateButtons();
     return this;
   }
+  /**
+   * Set play/stop button.
+   * @param btn - HTML button element or element id.
+   * @param playLabel - Custom button label for play action (e.g. "Play").
+   * @param stopLabel - Custom button label for stop action (e.g. "Stop").
+   * @returns - This playback buttons class instance.
+   */
   setPlayStopButton(btn, playLabel, stopLabel) {
-    assertArg2(Utils14.Is.isStringOrUndefined(playLabel), "playLabel", playLabel);
-    assertArg2(Utils14.Is.isStringOrUndefined(stopLabel), "stopLabel", stopLabel);
+    assertArg3(Utils15.Is.isStringOrUndefined(playLabel), "playLabel", playLabel);
+    assertArg3(Utils15.Is.isStringOrUndefined(stopLabel), "stopLabel", stopLabel);
     _MPlaybackButtons.removeOnClickListeners(this.playStopButton, this.onPlayStop);
-    this.playStopButton = require_t(Utils14.Dom.getButton(btn), "Play/stop button required!");
+    this.playStopButton = require_t(Utils15.Dom.getButton(btn), "Play/stop button required!");
     this.playLabel = playLabel != null ? playLabel : "Play";
     this.stopLabel = stopLabel != null ? stopLabel : "Stop";
     _MPlaybackButtons.removeOnClickListeners(this.playStopButton, "all");
@@ -8144,10 +8645,16 @@ var _MPlaybackButtons = class _MPlaybackButtons {
     this.updateButtons();
     return this;
   }
+  /**
+   * Set pause button.
+   * @param btn - HTML button element or element id.
+   * @param btnLabel - Custom button label (e.g. "Pause").
+   * @returns - This playback buttons class instance.
+   */
   setPauseButton(btn, btnLabel) {
-    assertArg2(Utils14.Is.isStringOrUndefined(btnLabel), "btnLabel", btnLabel);
+    assertArg3(Utils15.Is.isStringOrUndefined(btnLabel), "btnLabel", btnLabel);
     _MPlaybackButtons.removeOnClickListeners(this.pauseButton, this.onPause);
-    this.pauseButton = require_t(Utils14.Dom.getButton(btn), "Pause button required!");
+    this.pauseButton = require_t(Utils15.Dom.getButton(btn), "Pause button required!");
     this.pauseLabel = btnLabel != null ? btnLabel : "Pause";
     _MPlaybackButtons.removeOnClickListeners(this.pauseButton, "all");
     _MPlaybackButtons.addOnClickListener(this.pauseButton, this.onPause);
@@ -8169,7 +8676,7 @@ var _MPlaybackButtons = class _MPlaybackButtons {
     }
   }
   static addOnClickListener(btn, onClick) {
-    assertArg2(Utils14.Is.isFunction(onClick), "onClick", onClick);
+    assertArg3(Utils15.Is.isFunction(onClick), "onClick", onClick);
     btn.addEventListener("click", onClick);
     let clickListeners = this.savedOnClickListeners.get(btn) || [];
     this.savedOnClickListeners.set(btn, [...clickListeners, onClick]);
@@ -8188,6 +8695,7 @@ export {
   Connective,
   DivRect,
   DocumentBuilder,
+  DynamicsAnnotation,
   Fermata,
   Label,
   MAccidental,
@@ -8229,6 +8737,7 @@ export {
   ScoreStaffPosEvent,
   StaffPreset,
   Stem,
+  TempoAnnotation,
   TieType,
   VerticalPosition,
   getStringNumbers,