@tspro/web-music-score 4.2.0 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [5.0.0] - 2025-10-05
+Major update required to enable independent browser iife instrument modules.
+
+### **Breiking Changes**
+- Converted audio instrument modules (currently only audio-cg) independant of main lib.
+- Instead of using registerClassicalGuitar() => use import { ClassicalGuitar } and Audio.addInstrument(ClassicalGuitar).
+- Renamed Audio.registerInstrument() => Audio.addInstrument().
+- Renamed Audio.setInstrument() => Audio.useInstrument().
+
+## [4.2.1] - 2025-10-04
+## Fixed
+- Error was thrown with dotted rests.
+
 ## [4.2.0] - 2025-10-03
 ## Added
 - Add support for lyrics/syllables with alignment and hyphen/extender.

package/README.md

@@ -13,6 +13,19 @@ This is a work in progress project. Lately there has been improvements that requ
 version update. As the project matures there might be less major updates, and more minor
 updates and patches.
 
+## Version 5 Update
+
+Version 5.0.0 updated audio interface, instrument bundles are no longer dependant of the main lib and can be loaded in browser environment as independent modules.
+
+- How to add and use instrument, see sections [Instruments](#instruments)
+- How to add and use instrument browser version, see sections [Browser Modules](#browser-modules)
+
+## Help Wanted
+
+If someone has piano or keyboard and can record samples for me I'd be happy to add a new instrument.
+About ten mp3 samples between C2 to C6 would be fine (named "E2.mp3", etc).
+My email can be found on [GitHub](https://github.com/pahkasoft) (visible for signed in users).
+
 ## Installation
 
 ```sh
@@ -45,29 +58,35 @@ import * as Pieces from "@tspro/web-music-score/pieces";
 const Score = require("@tspro/web-music-score/score");
 ```
 
-## Browser Script
+## Browser Modules
+
+This lib can be used in browser via unpkg CDN using iife bundle. It declares
+global name `WebMusicScore` that contains `Core`, `Audio`, `Theory`, `Score`,
+and `Pieces` as corresponding subpath modules.
 
-This module that can be used in html page via unpkg CDN. It declares global variable 
-`WebMusicScore` that contains `Core`, `Audio`, `Theory`, `Score`, and `Pieces` as 
-corresponding subpath modules (`react-ui` and `audio-cg` are not included in this 
-browser module).
+React module `react-ui` is not included available for browser usage.
 
 ```html
 <!--
-    It is recommended to use exact version number so that if something
-    breaks between versions then your web site does not stop working.
+    It is recommended to use exact version number and direct link to the bundle so
+    that if something breaks between versions then your web site does not stop working.
 -->
-<script src="https://unpkg.com/@tspro/web-music-score@4.2.0"></script>
+<script src="https://unpkg.com/@tspro/web-music-score@5.0.0/dist/iife/index.global.js"></script>
 
 <!--
-    Or you can use direct link to the js bundle.
+    Classical guitar now also available for browser module.
 -->
-<script src="https://unpkg.com/@tspro/web-music-score@4.2.0/dist/iife/index.global.js"></script>
-
+<script src="https://unpkg.com/@tspro/web-music-score@5.0.0/dist/iife/audio-cg.global.js"></script>
 
 <script>
+    // The lib is available via global name WebMusicScore.
     const { Core, Audio, Theory, Score, Pieces } = window.WebMusicScore;
-    // ...
+
+    // Classical guitar audio is available via global name Audio_ClassicalGuitar.
+    const { ClassicalGuitar } = window.Audio_ClassicalGuitar;
+
+    // Add and use classical guitar instrument.
+    Audio.addInstrument(ClassicalGuitar);
 </script>
 ```
 
@@ -400,17 +419,32 @@ These are the beam groupings for each time signature.
 How to set beam grouping for `5/8` and `7/8` time signatures,
 see [Set Time Signature](#set-time-signature) section above.
 
-### Classical Guitar Audio Module
+### Instruments
 
-Default instrument is `Synthesizer`.
+Default instrument `Synthesizer` is available out of the box.
+Other instruments need to be registered manually.
 
 `Classical Guitar` is available via `audio-cg` module.
-It is included as separate module because it contains over 1MB of guitar audio samples bundled in it.
 
 ```js
-import { registerClassicalGuitar } from "@tspro/web-music-score/audio-cg";
+// Import classical guitar instrument.
+import { ClassicalGuitar } from "@tspro/web-music-score/audio-cg";
+
+// Add and use classical guitar instrument.
+Audio.addInstrument(ClassicalGuitar);
+```
+
+You can easily create and register your own instrument.
+```js
+class MyCoolInstrument implements Audio.Instrument {
+    constructor() { }
+    getName() { return "My Cool Instrument"; }
+    playNote(note: string, duration: number, linearVolume: number) { }
+    stop() { }
+}
 
-registerClassicalGuitar(); // This registers classical guitar audio, and takes it into use.
+// Add and use my cool instrument.
+Audio.addInstrument(new MyCoolInstrument());
 ```
 
 ### Play Document

package/dist/audio/index.d.mts

@@ -1,24 +1,7 @@
 import { N as Note } from '../note-eA2xPPiG.mjs';
+import { I as Instrument } from '../instrument-DYboobMW.mjs';
+export { l as linearToDecibels } from '../instrument-DYboobMW.mjs';
 
-/** Instrument interface. */
-interface Instrument {
-    /**
-     * Get instrument name.
-     * @return - Instrument name.
-     */
-    getName(): string;
-    /**
-     * Play a note.
-     * @param note - Note to play (e.g. "C4").
-     * @param duration - Play duration in seconds.
-     * @param volume - Linear volume in range [0, 1].
-     */
-    playNote(note: string, duration?: number, volume?: number): void;
-    /**
-     * Stop playback.
-     */
-    stop(): void;
-}
 /**
  * Get instrument name list.
  * @returns - Array of available instrument names.
@@ -30,15 +13,15 @@ declare function getInstrumentList(): ReadonlyArray<string>;
  */
 declare function getCurrentInstrument(): string;
 /**
- * Register new instrument.
- * @param instr - Instrument object implementing Instrument interface.
+ * Add and use instrument.
+ * @param instrument - Object that implements Instrument interface. Can be single instrument or array of instruments.
  */
-declare function registerInstrument(instr: Instrument): void;
+declare function addInstrument(instrument: Instrument | Instrument[]): void;
 /**
- * Set current instrument to use in playback.
- * @param instrName - Instrument name.
+ * Set instrument to use in playback.
+ * @param instrumentName - Instrument name.
  */
-declare function setInstrument(instrName: string): void;
+declare function useInstrument(instrumentName: string): void;
 /**
  * Play a note using current instrument.
  * @param note - Note instance of Note object, note name (e.g. "C4"), or midiNumber.
@@ -51,4 +34,4 @@ declare function playNote(note: Note | string | number, duration?: number, linea
  */
 declare function stop(): void;
 
-export { type Instrument, getCurrentInstrument, getInstrumentList, playNote, registerInstrument, setInstrument, stop };
+export { Instrument, addInstrument, getCurrentInstrument, getInstrumentList, playNote, stop, useInstrument };

package/dist/audio/index.d.ts

@@ -1,24 +1,7 @@
 import { N as Note } from '../note-eA2xPPiG.js';
+import { I as Instrument } from '../instrument-DYboobMW.js';
+export { l as linearToDecibels } from '../instrument-DYboobMW.js';
 
-/** Instrument interface. */
-interface Instrument {
-    /**
-     * Get instrument name.
-     * @return - Instrument name.
-     */
-    getName(): string;
-    /**
-     * Play a note.
-     * @param note - Note to play (e.g. "C4").
-     * @param duration - Play duration in seconds.
-     * @param volume - Linear volume in range [0, 1].
-     */
-    playNote(note: string, duration?: number, volume?: number): void;
-    /**
-     * Stop playback.
-     */
-    stop(): void;
-}
 /**
  * Get instrument name list.
  * @returns - Array of available instrument names.
@@ -30,15 +13,15 @@ declare function getInstrumentList(): ReadonlyArray<string>;
  */
 declare function getCurrentInstrument(): string;
 /**
- * Register new instrument.
- * @param instr - Instrument object implementing Instrument interface.
+ * Add and use instrument.
+ * @param instrument - Object that implements Instrument interface. Can be single instrument or array of instruments.
  */
-declare function registerInstrument(instr: Instrument): void;
+declare function addInstrument(instrument: Instrument | Instrument[]): void;
 /**
- * Set current instrument to use in playback.
- * @param instrName - Instrument name.
+ * Set instrument to use in playback.
+ * @param instrumentName - Instrument name.
  */
-declare function setInstrument(instrName: string): void;
+declare function useInstrument(instrumentName: string): void;
 /**
  * Play a note using current instrument.
  * @param note - Note instance of Note object, note name (e.g. "C4"), or midiNumber.
@@ -51,4 +34,4 @@ declare function playNote(note: Note | string | number, duration?: number, linea
  */
 declare function stop(): void;
 
-export { type Instrument, getCurrentInstrument, getInstrumentList, playNote, registerInstrument, setInstrument, stop };
+export { Instrument, addInstrument, getCurrentInstrument, getInstrumentList, playNote, stop, useInstrument };

package/dist/audio/index.js

@@ -1,4 +1,4 @@
-/* WebMusicScore v4.2.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
+/* WebMusicScore v5.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -33,20 +33,27 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 // src/audio/index.ts
 var audio_exports = {};
 __export(audio_exports, {
+  addInstrument: () => addInstrument,
   getCurrentInstrument: () => getCurrentInstrument,
   getInstrumentList: () => getInstrumentList,
+  linearToDecibels: () => linearToDecibels,
   playNote: () => playNote,
-  registerInstrument: () => registerInstrument,
-  setInstrument: () => setInstrument,
-  stop: () => stop
+  stop: () => stop,
+  useInstrument: () => useInstrument
 });
 module.exports = __toCommonJS(audio_exports);
 var import_theory = require("@tspro/web-music-score/theory");
 
-// src/audio/synth.ts
+// src/audio/audio-synth.ts
 var Tone = __toESM(require("tone"));
-var import_ts_utils_lib = require("@tspro/ts-utils-lib");
-var Synth2 = class {
+
+// src/audio/instrument.ts
+function linearToDecibels(linearVolume) {
+  return !isFinite(linearVolume) || linearVolume <= 0 ? -Infinity : 20 * Math.log10(linearVolume);
+}
+
+// src/audio/audio-synth.ts
+var SynthesizerInstr = class {
   constructor() {
     __publicField(this, "audioSource");
     try {
@@ -74,10 +81,8 @@ var Synth2 = class {
   playNote(note, duration, linearVolume) {
     try {
       if (this.audioSource) {
-        if (linearVolume !== void 0) {
-          this.audioSource.volume.value = import_ts_utils_lib.Utils.Math.linearToDecibels(linearVolume);
-        }
-        this.audioSource.triggerAttackRelease(note, duration != null ? duration : "2n");
+        this.audioSource.volume.value = linearToDecibels(linearVolume);
+        this.audioSource.triggerAttackRelease(note, duration);
       }
     } catch (err) {
     }
@@ -91,10 +96,11 @@ var Synth2 = class {
     }
   }
 };
-var Synthesizer = new Synth2();
+var Synthesizer = new SynthesizerInstr();
 
 // src/audio/index.ts
 var import_core = require("@tspro/web-music-score/core");
+var import_ts_utils_lib = require("@tspro/ts-utils-lib");
 (0, import_core.init)();
 function getNoteName(note) {
   if (typeof note === "string") {
@@ -112,36 +118,49 @@ function getInstrumentList() {
 function getCurrentInstrument() {
   return CurrentInstrument.getName();
 }
-function registerInstrument(instr) {
-  if (InstrumentList.some((instr2) => instr2.getName() === instr.getName())) {
-    return;
-  }
-  InstrumentList.push(instr);
-  setInstrument(instr.getName());
+function addInstrument(instrument) {
+  (import_ts_utils_lib.Utils.Is.isArray(instrument) ? instrument : [instrument]).forEach((instr) => {
+    if (!import_ts_utils_lib.Utils.Obj.hasProperties(instr, ["getName", "playNote", "stop"]) || !import_ts_utils_lib.Utils.Is.isFunction(instr.getName) || !import_ts_utils_lib.Utils.Is.isFunction(instr.playNote) || !import_ts_utils_lib.Utils.Is.isFunction(instr.stop)) {
+      throw new import_core.MusicError(import_core.MusicErrorType.Audio, "Invalid instrument object: " + instr);
+    }
+    if (InstrumentList.some((instr2) => instr2.getName() === instr.getName())) {
+      console.warn(`Instrument "${instr.getName()}" already registered!`);
+    } else {
+      InstrumentList.push(instr);
+    }
+    useInstrument(instr.getName());
+  });
 }
-function setInstrument(instrName) {
-  if (instrName === CurrentInstrument.getName()) {
+function useInstrument(instrumentName) {
+  if (instrumentName === CurrentInstrument.getName()) {
     return;
   }
   CurrentInstrument.stop();
-  let instr = InstrumentList.find((instr2) => instr2.getName() === instrName);
+  let instr = InstrumentList.find((instr2) => instr2.getName() === instrumentName);
   if (instr) {
     CurrentInstrument = instr;
   }
 }
+var DefaultDuration = (function calcDuration(noteSize, beatsPerMinute, timeTisgnature) {
+  var _a;
+  let beatSize = parseInt((_a = timeTisgnature.split("/")[1]) != null ? _a : "4");
+  return 60 * (1 / noteSize) / (beatsPerMinute * (1 / beatSize));
+})(2, 80, "4/4");
+var DefaultVolume = 1;
 function playNote(note, duration, linearVolume) {
-  CurrentInstrument.playNote(getNoteName(note), duration, linearVolume);
+  CurrentInstrument.playNote(getNoteName(note), duration != null ? duration : DefaultDuration, linearVolume != null ? linearVolume : DefaultVolume);
 }
 function stop() {
   CurrentInstrument.stop();
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  addInstrument,
   getCurrentInstrument,
   getInstrumentList,
+  linearToDecibels,
   playNote,
-  registerInstrument,
-  setInstrument,
-  stop
+  stop,
+  useInstrument
 });
 //# sourceMappingURL=index.js.map

package/dist/audio/index.mjs

@@ -1,15 +1,17 @@
-/* WebMusicScore v4.2.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
+/* WebMusicScore v5.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
+import {
+  linearToDecibels
+} from "../chunk-AAL3CMRO.mjs";
 import {
   __publicField
-} from "../chunk-5NWLGWHS.mjs";
+} from "../chunk-J3KU3U4W.mjs";
 
 // src/audio/index.ts
 import { Note, PitchNotation, SymbolSet } from "@tspro/web-music-score/theory";
 
-// src/audio/synth.ts
+// src/audio/audio-synth.ts
 import * as Tone from "tone";
-import { Utils } from "@tspro/ts-utils-lib";
-var Synth2 = class {
+var SynthesizerInstr = class {
   constructor() {
     __publicField(this, "audioSource");
     try {
@@ -37,10 +39,8 @@ var Synth2 = class {
   playNote(note, duration, linearVolume) {
     try {
       if (this.audioSource) {
-        if (linearVolume !== void 0) {
-          this.audioSource.volume.value = Utils.Math.linearToDecibels(linearVolume);
-        }
-        this.audioSource.triggerAttackRelease(note, duration != null ? duration : "2n");
+        this.audioSource.volume.value = linearToDecibels(linearVolume);
+        this.audioSource.triggerAttackRelease(note, duration);
       }
     } catch (err) {
     }
@@ -54,10 +54,11 @@ var Synth2 = class {
     }
   }
 };
-var Synthesizer = new Synth2();
+var Synthesizer = new SynthesizerInstr();
 
 // src/audio/index.ts
-import { init as initCore } from "@tspro/web-music-score/core";
+import { init as initCore, MusicError, MusicErrorType } from "@tspro/web-music-score/core";
+import { Utils } from "@tspro/ts-utils-lib";
 initCore();
 function getNoteName(note) {
   if (typeof note === "string") {
@@ -75,35 +76,48 @@ function getInstrumentList() {
 function getCurrentInstrument() {
   return CurrentInstrument.getName();
 }
-function registerInstrument(instr) {
-  if (InstrumentList.some((instr2) => instr2.getName() === instr.getName())) {
-    return;
-  }
-  InstrumentList.push(instr);
-  setInstrument(instr.getName());
+function addInstrument(instrument) {
+  (Utils.Is.isArray(instrument) ? instrument : [instrument]).forEach((instr) => {
+    if (!Utils.Obj.hasProperties(instr, ["getName", "playNote", "stop"]) || !Utils.Is.isFunction(instr.getName) || !Utils.Is.isFunction(instr.playNote) || !Utils.Is.isFunction(instr.stop)) {
+      throw new MusicError(MusicErrorType.Audio, "Invalid instrument object: " + instr);
+    }
+    if (InstrumentList.some((instr2) => instr2.getName() === instr.getName())) {
+      console.warn(`Instrument "${instr.getName()}" already registered!`);
+    } else {
+      InstrumentList.push(instr);
+    }
+    useInstrument(instr.getName());
+  });
 }
-function setInstrument(instrName) {
-  if (instrName === CurrentInstrument.getName()) {
+function useInstrument(instrumentName) {
+  if (instrumentName === CurrentInstrument.getName()) {
     return;
   }
   CurrentInstrument.stop();
-  let instr = InstrumentList.find((instr2) => instr2.getName() === instrName);
+  let instr = InstrumentList.find((instr2) => instr2.getName() === instrumentName);
   if (instr) {
     CurrentInstrument = instr;
   }
 }
+var DefaultDuration = (function calcDuration(noteSize, beatsPerMinute, timeTisgnature) {
+  var _a;
+  let beatSize = parseInt((_a = timeTisgnature.split("/")[1]) != null ? _a : "4");
+  return 60 * (1 / noteSize) / (beatsPerMinute * (1 / beatSize));
+})(2, 80, "4/4");
+var DefaultVolume = 1;
 function playNote(note, duration, linearVolume) {
-  CurrentInstrument.playNote(getNoteName(note), duration, linearVolume);
+  CurrentInstrument.playNote(getNoteName(note), duration != null ? duration : DefaultDuration, linearVolume != null ? linearVolume : DefaultVolume);
 }
 function stop() {
   CurrentInstrument.stop();
 }
 export {
+  addInstrument,
   getCurrentInstrument,
   getInstrumentList,
+  linearToDecibels,
   playNote,
-  registerInstrument,
-  setInstrument,
-  stop
+  stop,
+  useInstrument
 };
 //# sourceMappingURL=index.mjs.map

package/dist/audio-cg/index.d.mts

@@ -1,6 +1,16 @@
+import { I as Instrument } from '../instrument-DYboobMW.mjs';
+
 /**
- * Register classical guitar audio instrument, and set is as current instrument.
+ * Default export is the classical guitar instrument object.
+ *
+ * ```ts
+ *   // Usage
+ *   import * as Audio from "@tspro/web-music-score/audio";
+ *   import { ClassicalGuitar } from "@tspro/web-music-score/audio-cg";
+ *
+ *   Audio.addInstrument(ClassicalGuitar);
+ * ```
  */
-declare function registerClassicalGuitar(): void;
+declare const ClassicalGuitar: Instrument;
 
-export { registerClassicalGuitar };
+export { ClassicalGuitar };

package/dist/audio-cg/index.d.ts

@@ -1,6 +1,16 @@
+import { I as Instrument } from '../instrument-DYboobMW.js';
+
 /**
- * Register classical guitar audio instrument, and set is as current instrument.
+ * Default export is the classical guitar instrument object.
+ *
+ * ```ts
+ *   // Usage
+ *   import * as Audio from "@tspro/web-music-score/audio";
+ *   import { ClassicalGuitar } from "@tspro/web-music-score/audio-cg";
+ *
+ *   Audio.addInstrument(ClassicalGuitar);
+ * ```
  */
-declare function registerClassicalGuitar(): void;
+declare const ClassicalGuitar: Instrument;
 
-export { registerClassicalGuitar };
+export { ClassicalGuitar };