@tspro/web-music-score 4.2.1 → 5.1.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [5.1.0] - 2025-10-08
+## Added
+- Audio functions: mute(), unmute() and isMuted().
+- Added audio-synth as an own module.
+- Added PlaybackButtons properties singlePlayStop, playStop and playPauseStop (deprecated buttonLayout).
+- Added grandId property to staff config, deprecated isGrand property.
+- Added tab signature (show tempo, measure number and time siganture).
+- Draw rhythms above tab.
+
+## Fixed
+- Documentation errors.
+- Correctly apply NoteOptions.string for each note when using addNote with arrya of notes.
+- Incorrect detection upbeat beams.
+- Increase beam separation by angle.
+- Better tempo position above staff.
+- Distance between staff and tab.
+
+## [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.

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.1.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.1.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>
 ```
 
@@ -131,8 +150,8 @@ or corresponding string values (e.g. `"treble"`).
     voiceIds: [0, 1]     // (optional) only present voices 0 and 1 in this staff
 })
 .setScoreConfiguration([
-    { type: "staff", clef: "G", isGrand: true },
-    { type: "staff", clef: "F", isGrand: true }
+    { type: "staff", clef: "G", grandId: "grand1" },
+    { type: "staff", clef: "F", grandId: "grand1" }
 ]) // Grand staff
 .setScoreConfiguration([
     { type: "staff", clef: "G", isOctaveDown: true },
@@ -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";
 
-registerClassicalGuitar(); // This registers classical guitar audio, and takes it into use.
+// 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() { }
+}
+
+// Add and use my cool instrument.
+Audio.addInstrument(new MyCoolInstrument());
 ```
 
 ### Play Document
@@ -435,13 +469,16 @@ Score.MPlayer.stopAll();
 // Draw document
 <ScoreUI.MusicScoreView doc={doc} />
 
-// Add playback buttons
-<ScoreUI.PlaybackButtons doc={doc} buttonLayout={ScoreUI.PlaybackButtonsLayout.PlayStopSingle}/> // Single Play/Stopo button
-<ScoreUI.PlaybackButtons doc={doc} buttonLayout={ScoreUI.PlaybackButtonsLayout.PlayStop}/>       // Play and Stop buttons
-<ScoreUI.PlaybackButtons doc={doc} buttonLayout={ScoreUI.PlaybackButtonsLayout.PlayPauseStop}/>  // Play, Pause and Stop buttons
+// Show playback buttons
+<ScoreUI.PlaybackButtons doc={doc} singlePlayStop /> // Single play/stop button.
+<ScoreUI.PlaybackButtons doc={doc} playStop />       // Play and stop buttons.
+<ScoreUI.PlaybackButtons doc={doc} playPauseStop />  // Play, pause and Stop buttons.
+<ScoreUI.PlaybackButtons doc={doc} />                // Default is play, pause and Stop buttons.
 ```
 
-Bootstrap is used for better visual appearance, but it needs to be installed and loaded.
+Hint! Bootstrap is used for better visual appearance.
+- Install bootstrap: `npm install bootstrap`
+- Import in app entry: `import "bootstrap/dist/css/bootstrap.min.css";`
 
 ### Viewing Using Plain JS/TS
 
@@ -474,10 +511,10 @@ let p = new Score.MPlaybackButtons().
     setDocument(doc);
 
 // You can also set combined play/stop button.
-p.setPlayStopButton("playStopButtonId")
+p.setPlayStopButton("playStopButtonId");
 
 // You can also pass HTMLButtonElement instead of element id.
-p.setPlayButton(playButtonElement)
+p.setPlayButton(playButtonElement);
 ```
 
 ### MusicError

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.
@@ -47,8 +30,21 @@ declare function setInstrument(instrName: string): void;
  */
 declare function playNote(note: Note | string | number, duration?: number, linearVolume?: number): void;
 /**
- * Stop playing on current instrument.
+ * Stop playback on current instrument.
  */
 declare function stop(): void;
+/**
+ * Mute playback on current instrument.
+ */
+declare function mute(): void;
+/**
+ * Unmute playback on current instrument.
+ */
+declare function unmute(): void;
+/**
+ * Is playback muted?
+ * @returns True/false.
+ */
+declare function isMuted(): boolean;
 
-export { type Instrument, getCurrentInstrument, getInstrumentList, playNote, registerInstrument, setInstrument, stop };
+export { Instrument, addInstrument, getCurrentInstrument, getInstrumentList, isMuted, mute, playNote, stop, unmute, 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.
@@ -47,8 +30,21 @@ declare function setInstrument(instrName: string): void;
  */
 declare function playNote(note: Note | string | number, duration?: number, linearVolume?: number): void;
 /**
- * Stop playing on current instrument.
+ * Stop playback on current instrument.
  */
 declare function stop(): void;
+/**
+ * Mute playback on current instrument.
+ */
+declare function mute(): void;
+/**
+ * Unmute playback on current instrument.
+ */
+declare function unmute(): void;
+/**
+ * Is playback muted?
+ * @returns True/false.
+ */
+declare function isMuted(): boolean;
 
-export { type Instrument, getCurrentInstrument, getInstrumentList, playNote, registerInstrument, setInstrument, stop };
+export { Instrument, addInstrument, getCurrentInstrument, getInstrumentList, isMuted, mute, playNote, stop, unmute, useInstrument };

package/dist/audio/index.js

@@ -1,12 +1,9 @@
-/* WebMusicScore v4.2.1 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
+/* WebMusicScore v5.1.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
 "use strict";
-var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -19,82 +16,34 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
 // src/audio/index.ts
 var audio_exports = {};
 __export(audio_exports, {
+  addInstrument: () => addInstrument,
   getCurrentInstrument: () => getCurrentInstrument,
   getInstrumentList: () => getInstrumentList,
+  isMuted: () => isMuted,
+  linearToDecibels: () => linearToDecibels,
+  mute: () => mute,
   playNote: () => playNote,
-  registerInstrument: () => registerInstrument,
-  setInstrument: () => setInstrument,
-  stop: () => stop
+  stop: () => stop,
+  unmute: () => unmute,
+  useInstrument: () => useInstrument
 });
 module.exports = __toCommonJS(audio_exports);
 var import_theory = require("@tspro/web-music-score/theory");
+var import_core = require("@tspro/web-music-score/core");
+var import_audio_synth = require("@tspro/web-music-score/audio-synth");
 
-// src/audio/synth.ts
-var Tone = __toESM(require("tone"));
-var import_ts_utils_lib = require("@tspro/ts-utils-lib");
-var Synth2 = class {
-  constructor() {
-    __publicField(this, "audioSource");
-    try {
-      const reverb = new Tone.Reverb({ decay: 3, wet: 0.4 }).toDestination();
-      const filter = new Tone.Filter(800, "lowpass").connect(reverb);
-      this.audioSource = new Tone.PolySynth(Tone.Synth, {
-        oscillator: {
-          type: "triangle"
-        },
-        envelope: {
-          attack: 1e-3,
-          decay: 2,
-          sustain: 0.1,
-          release: 1.2
-        }
-      }).connect(filter);
-    } catch (err) {
-      this.audioSource = void 0;
-      console.error(err);
-    }
-  }
-  getName() {
-    return "Synthesizer";
-  }
-  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");
-      }
-    } catch (err) {
-    }
-  }
-  stop() {
-    try {
-      if (this.audioSource) {
-        this.audioSource.releaseAll();
-      }
-    } catch (err) {
-    }
-  }
-};
-var Synthesizer = new Synth2();
+// src/audio/instrument.ts
+function linearToDecibels(linearVolume) {
+  return !isFinite(linearVolume) || linearVolume <= 0 ? -Infinity : 20 * Math.log10(linearVolume);
+}
 
 // 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") {
@@ -104,44 +53,73 @@ function getNoteName(note) {
   }
   return note.format(import_theory.PitchNotation.Scientific, import_theory.SymbolSet.Ascii);
 }
-var InstrumentList = [Synthesizer];
-var CurrentInstrument = Synthesizer;
+var InstrumentList = [import_audio_synth.Synthesizer];
+var currentInstrument = import_audio_synth.Synthesizer;
+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;
+var mutePlayback = false;
 function getInstrumentList() {
   return InstrumentList.map((instr) => instr.getName());
 }
 function getCurrentInstrument() {
-  return CurrentInstrument.getName();
+  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);
+  currentInstrument.stop();
+  let instr = InstrumentList.find((instr2) => instr2.getName() === instrumentName);
   if (instr) {
-    CurrentInstrument = instr;
+    currentInstrument = instr;
   }
 }
 function playNote(note, duration, linearVolume) {
-  CurrentInstrument.playNote(getNoteName(note), duration, linearVolume);
+  if (!mutePlayback) {
+    currentInstrument.playNote(getNoteName(note), duration != null ? duration : DefaultDuration, linearVolume != null ? linearVolume : DefaultVolume);
+  }
 }
 function stop() {
-  CurrentInstrument.stop();
+  currentInstrument.stop();
+}
+function mute() {
+  stop();
+  mutePlayback = true;
+}
+function unmute() {
+  mutePlayback = false;
+}
+function isMuted() {
+  return mutePlayback;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  addInstrument,
   getCurrentInstrument,
   getInstrumentList,
+  isMuted,
+  linearToDecibels,
+  mute,
   playNote,
-  registerInstrument,
-  setInstrument,
-  stop
+  stop,
+  unmute,
+  useInstrument
 });
 //# sourceMappingURL=index.js.map