@tspro/web-music-score 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [1.1.0] - 2025-07-03
+### Added
+- Preliminary support for rendering guitar tabs.
+
+### Fixed
+- Ties/slurs were created multiple times.
+- Beams in first measure (upbeat) were not created correctly.
+- Quite much refactoring for better code.
+
 ## [1.0.0] - 2025-07-03
 ### Added
 - First release.

package/README.md

@@ -8,7 +8,7 @@ later taking lessons in classical guitar. I've also studied music theory indepen
 This project has been a slow and steady effort over several years. It's now ready for
 public release — though please note that there may still be bugs or unexpected behavior.
 
-## Install
+## Installation
 
 ```sh
 npm i @tspro/web-music-score
@@ -17,53 +17,30 @@ npm i @tspro/web-music-score
 npm i react
 ```
 
-## Library Bundle
-
-This library is bundled to ESM, CJS and UMD formats.
-
-* CJS and UMD bundles are transpiled with Babel for ES5/IE11 compatibility.
-* ESM bundle targets modern environments (ES6+).
-* Uses ES6 features like Map, etc.
-* No polyfills are included.
-
-While designed for compatibility in mind, the library has not been explicitly tested against specific Node.js or browser versions.
-
-## Report a Bug
-
-Found a bug or unexpected behavior?
-
-[Please open a new issue.](https://github.com/pahkasoft/issues/issues/new)
-
-You can also suggest a feature or impovement.
-
-Thanks for helping improve the project!
-
-## License
-
-This project is licensed under the [MIT License](https://mit-license.org/).
-
-It also bundles the [Tone.js](https://github.com/Tonejs/Tone.js) library,
-which is licensed under the [MIT License](https://opensource.org/license/mit).
-
 ## Usage And API Documentation
 
-### Import Methods
+### Usage
+
+#### Import (ESM)
 ```js
 // Import named exports
 import * as Score from "@tspro/web-music-score";
 
-// Or import default export
+// Import default export
 import Score from "@tspro/web-music-score";
+```
 
-// Or use require
+#### Require (CommonJS)
+```js
+// Use require
 const Score = require("@tspro/web-music-score");
 ```
 
+#### Browser Script
+Use in browser via unpkg CDN.
+Browser version comes without React-components.
+
 ```html
-<!--
-    Or use in browser via unpkg CDN.
-    Browser version comes without React-components.
--->
 <script src="https://unpkg.com/@tspro/web-music-score@1"></script>
 
 <canvas id="scoreCanvas"></canvas><br />
@@ -78,21 +55,32 @@ const Score = require("@tspro/web-music-score");
 ### Create Document
 
 ```js
-let doc = new Score.MDocument(Score.StaffKind.Treble, 4);
+let doc = new Score.MDocument(Score.StaffKind.Treble, { measuresPerRow: 4 });
 ```
 
-First argument can be Treble, TrebleForGuitar, Bass or Grand. TrebleForGuitar is same as Treble but one octave lower.
+First argument is `StaffKind`:
+* `Treble`: Staff with treble (G-) clef.
+* `Bass`: Staff with bass (F-) clef.
+* `Grand`: Both treble and bas staves.
+* `GuitarTreble`: `Treble` but one octave lower.
+* `GuitarTab`: Guitar tab only.
+* `GuitarTrebleAndTab`: Treble and tab for guitar.
 
-Second argument is number of measures per row, and can be omitted.
+Second argument is optional `DocumentOptions`:
+```ts
+DocumentOptions = { measuresPerRow?: number, tuning?: string }
+```
+
+Default tuning is `"Standard"`. `TuningNameList` is array of available tuning names.
 
-## Set Header
+### Set Header
 
 ```js
 doc.setHeader("Title", "Composer", "Arranger");
 doc.setHeader("Title");
 ```
 
-Any of title, composer and arranger can be omitted/set undefined.
+Any of `title`, `composer` and `arranger` can be omitted/set undefined.
 
 ### Add Measure
 
@@ -116,14 +104,14 @@ m.setKeySignature("C", Score.ScaleType.Major);
 
 Firat argument is scale key note.
 
-Second argument is scale type, which can be Major, NaturalMinor, HarmonicMinor, Ionian, Dorian, Phrygian, Lydian, Mixolydian, 
-Aeolian, Locrian, MajorPentatonic, MinorPentatonic, MajorHexatonicBlues, MinorHexatonicBlues or HeptatonicBlues.
+Second argument is `ScaleType`, which can be `Major`, `NaturalMinor`, `HarmonicMinor`, `Ionian`, `Dorian`, `Phrygian`, `Lydian`, `Mixolydian`, 
+`Aeolian`, `Locrian`, `MajorPentatonic`, `MinorPentatonic`, `MajorHexatonicBlues`, `MinorHexatonicBlues` or `HeptatonicBlues`.
 
 ```js
 m.setTimeSignature("4/4");
 ```
 
-Time signature can be "2/4", "3/4", "4/4", "6/8" or "9/8".
+Time signature can be `"2/4"`, `"3/4"`, `"4/4"`, `"6/8"` or `"9/8"`.
 
 ```js
 m.setTempo(80, Score.NoteLength.Quarter, false);
@@ -134,118 +122,77 @@ First argument is beats per minute.
 
 Second argument is beat length. Third argument tells if beat length is dotted. Second and third arguments can be omitted.
 
-### Adding Notes and chords
-
-```js
-m.addNote(0, "C3", Score.NoteLength.Quarter);
-m.addChord(1, ["C3", "E3", "G3", "C4"], Score.NoteLength.Whole);
-```
-
-First argument is voice track id and can be 0, 1, 2 or 3.
-
-Second argument is note or list of notes for chord.
-
-Third argument is note length. Note length can be Whole, Half, Quarter, Eighth, Sixteenth, ThirdySecond or SixtyFourth.
-
-### Add Rest
-
-```js    
-m.addRest(0, Score.NoteLength.Quarter);
-```
-
-First argument is voice track id and can be 0, 1, 2 or 3.
-
-Second argument is rest length. Rest length can be Whole, Half, Quarter, Eighth, Sixteenth, ThirdySecond or SixtyFourth.
-
-### Note And Rest Options
-
-#### Doted Note And Rest
+### Add Note Or Chord
 
 ```js
-m.addNote(0, "C3", Score.NoteLength.Quarter, { dotted: true });
-m.addRest(0, Score.NoteLength.Quarter, { dotted: true });
+m.addNote(voiceId, note, noteLength, noteOptions?);
+m.addChord(voiceId, notes, noteLength, noteOptions);
 ```
 
-#### Stem Direction
+* `voiceId`: Voice track id `0`, `1`, `2` or `3`
+* `note`: note `string | Note` (e.g. `"C3"`)
+* `notes`: array of notes `(string | Note)[]` (e.g. `["C3", "E3"]`)
+* `noteLength`: Note length (e.g. `NoteLength.Half`), see below
+* `noteOptions`: Optional note otions, see below
 
+Examples:
 ```js
-m.addNote(0, "C3", Score.NoteLength.Quarter, { stem: Stem.Up });
-```
-
-Stem  direction can be Auto, Up or Down
-
-#### Arpeggio
-
-```js
-m.addNote(0, "C3", Score.NoteLength.Quarter, { arpeggio: Arpeggio.Down });
-```
-
-Play this column of notes in arpeggio. Arpeggio can be Up or Down.
-
-#### Staccato
-
-```js
-m.addNote(0, "C3", Score.NoteLength.Quarter, { staccato: true });
-```
-
-#### Diamond Note Head
-
-```js
-m.addNote(0, "C3", Score.NoteLength.Quarter, { diamond: true });
-```
-
-#### Add Ties And Slurs
-
-```js
-m.addNote(0, "C3", Score.NoteLength.Half, { tieSpan: 2, tiePos: Score.ArcPos.Below })
 m.addNote(0, "C3", Score.NoteLength.Quarter);
+m.addChord(1, ["C3", "E3", "G3", "C4"], Score.NoteLength.Half, { dotted: true });
 ```
-    
-Adds a tie.
 
-```js
-m.addNote(0, "C3", Score.NoteLength.Eight, { slurSpan: 2, slurPos: Score.ArcPos.Below })
-m.addNote(0, "D3", Score.NoteLength.Eight);
-```
+#### NoteLength
 
-Adds a slur.
+* `NoteLength.Whole`
+* `NoteLength.Half`
+* `NoteLength.Quarter`
+* `NoteLength.Eighth`
+* `NoteLength.Sixteenth`
+* `NoteLength.ThirtySecond`
+* `NoteLength.SixtyFourth`
 
-ArcPos can be Auto, Above (above note head), Middle (next to note head), Below (below note head), StemTip.
+#### NoteOptions
 
-#### Add Triplet
+Optional object of note options (e.g. `{ stem: Stem.Up }`):
 
-```js
-doc.addMeasure()
-    .addNote(0, "C3", Score.NoteLength.Eight, { triplet: true })
-    .addNote(0, "D3", Score.NoteLength.Eight, { triplet: true })
-    .addNote(0, "E3", Score.NoteLength.Eight, { triplet: true });
-```
+| Note option | Type                    |                    |
+|-------------|-------------------------|--------------------|
+| dotted      | `boolean`               | Create dotted note. |
+| stem        | `Stem`                  | Set stem direction (`Stem.Auto`/`Up`/`Down`) |
+| arpeggio    | `Arpeggio`              | Play column in arpeggio `Arpeggio.Up`/`Down` |
+| staccato    | `boolean`               | Play column in staccato. |
+| diamond     | `boolean`               | Diamond shaped note head. |
+| tieSpan     | `number` \| `TieLength` | How many notes tied, or `TieLength.Short`/`ToMeasureEnd` |
+| tiePos      | `ArcPos`                | Tie attach point: `Arc.Auto`/`Above`/`Middle`/`Below`/`StemTip` |
+| slurSpan    | `number`                | How many notes slurred. |
+| slurPos     | `ArcPos`                | Slur attach point: `Arc.Auto`/`Above`/`Middle`/`Below`/`StemTip` |
+| triplet     | `boolean`               | Make this note part of triplet. |
+| string      | `number` \| `number[]`  | What string does the note fret number belong to in guitar tab. Array of strings for chord. |
 
-Adds triplet between three notes or rest of equal length.
+### Add Rest
 
-```js
-doc.addMeasure()
-    .addNote(0, "C3", Score.NoteLength.Eight, { triplet: true })
-    .addRest(0, Score.NoteLength.Quarter, { triplet: true });
+```js    
+m.addRest(voideId, restLength, restOptions?);
 ```
 
-Triplet can also be added between two notes or rest. Other note or rest is double length of the other.
-
-#### Rest Pitch
+* `voiceId`: Voice track id `0`, `1`, `2` or `3`.
+* `restLength`: Rest length using `NoteLength` (e.g. `NoteLength.Half`), see above.
+* `restOptions`: Optional rest otions, see below.
 
+Example:
 ```js
-m.addRest(0, Score.NoteLength.Quarter, { pitch: "C3" });
+m.addRest(0, Score.NoteLength.Quarter);
 ```
 
-Positions rest at the pitch level of note "C3".
-
-#### Hide Rest
+#### RestOptions
 
-```js
-m.addRest(0, Score.NoteLength.Quarter, { hide: true });
-```
-
-Creates invisible rest.
+Optional object of rest options (e.g. `{ hide: true }`):
+| Rest option | Type                   |                    |
+|-------------|------------------------|--------------------|
+| dotted      | `boolean`              | Create dotted rest |
+| pitch       | `string` \| `Note`     | Positions rest at level of note (e.g. `"C3"`) |
+| hide        | `boolean`              | Add invisible rest |
+| triplet     | `boolean`              | Make this rest part of triplet |
 
 ### Add Fermata
 
@@ -272,25 +219,25 @@ Adds navigational element to measure.
 
 Available navigations are:
 
-* Navigation.DC\_al\_Fine
-* Navigation.DC\_al\_Coda
-* Navigation.DS\_al\_Fine
-* Navigation.DS\_al\_Coda
-* Navigation.Coda
-* Navigation.toCoda
-* Navigation.Segno
-* Navigation.Fine
-* Navigation.StartRepeat
-* Navigation.EndRepeat
-* Navigation.Ending
+* `Navigation.DC_al_Fine`
+* `Navigation.DC_al_Coda`
+* `Navigation.DS_al_Fine`
+* `Navigation.DS_al_Coda`
+* `Navigation.Coda`
+* `Navigation.toCoda`
+* `Navigation.Segno`
+* `Navigation.Fine`
+* `Navigation.StartRepeat`
+* `Navigation.EndRepeat`
+* `Navigation.Ending`
 
-Navigation.EndRepeat takes optional second argument which is number of repeats. Defaults to 1 if omitted.
+`Navigation.EndRepeat` Takes optional second argument which is number of repeats. Defaults to 1 if omitted.
 
 ```js
 m.addNavigation(Score.Navigation.EndRepeat, 2);
 ```
 
-Navigation.Ending takes variable number of arguments, each is a passage number.
+`Navigation.Ending` takes variable number of arguments, each is a passage number.
 
 ```js
 m.addNavigation(Score.Navigation.Ending, 1, 2);
@@ -305,8 +252,8 @@ m.addChord(0, ["D3", "F3", "A3"], Score.NoteLength.Quarter).addLabel(Score.Label
 
 Available Label types are:
 
-* Label.Note is used to label notes and is positioned below note.
-* Label.Chord is used to label chords and is positioned on top.
+* `Label.Note` is used to label notes and is positioned below note.
+* `Label.Chord` is used to label chords and is positioned on top.
 
 ### Add Annotation
 
@@ -314,12 +261,12 @@ Available Label types are:
 m.addNote(0, "C3", Score.NoteLength.Quarter).addAnnotation(Score.Annotation.Dynamics, "fff");
 ```
 
-First argument is Annotation, second argument is the annotation text.
+First argument is `Annotation`, second argument is the annotation text.
 
 Available annotations are:
 
-* Annotation.Dynamics could be for example "fff", "cresc.", "dim.", etc.
-* Annotation.Tempo could be for example "accel.", "rit.", "a tempo", etc.
+* `Annotation.Dynamics` could be for example `"fff"`, `"cresc."`, `"dim."`, etc.
+* `Annotation.Tempo` could be for example `"accel."`, `"rit."`, `"a tempo"`, etc.
 
 ### Add Extension
 
@@ -331,9 +278,29 @@ m.addNote(0, "C3", Score.NoteLength.Quarter).
 
 Adds extension line to element, annotation in this case.
 
-First argument is extension length, of type number. NoteLength values can be used as number, and NoteLength values can be multiplied to set desired extension length.
+First argument is extension length, of type number. `NoteLength` values can be used as number, and `NoteLength` values can be multiplied to set desired extension length.
+
+Second argument is `true`/`false` whether extension line is visible. This argument cvan be omitted, extension line is visible by default.
+
+### Guitar Tab
+
+Has preliminary support for rendering guitar tabs. 
+Create document with `StaffKind.GuitarTab` or `StaffKind.GuitarTrebleAndTab`, and specify tuning (optional, defaults to Standard tuning):
+
+```js
+let doc = new Score.MDocument(Score.StaffKind.GuitarTrebleAndTab, { tuning: "Standard" });
+```
+
+Add notes with `string` option to specify which string the fret number is rendered in tab view.
+
+```js
+// Single note
+m.addNote(0, "G3", Score.NoteLength.Eighth, { string: 3 });
+
+// Multi note
+m.addChord(0, ["E4", "C3"], Score.NoteLength.Eighth, { string: [1, 5] });
+```
 
-Second argument is true/false whether extension line is visible. This argument cvan be omitted, extension line is visible by default.
 
 ### Queueing
 
@@ -441,3 +408,31 @@ catch(e) {
     }
 }
 ```
+
+## Compatibility
+
+This library is bundled to ESM, CJS and UMD formats.
+
+* CJS and UMD bundles are transpiled with Babel for ES5/IE11 compatibility.
+* ESM bundle targets modern environments (ES6+).
+* Uses ES6 features like Map, etc.
+* No polyfills are included.
+
+While designed for compatibility in mind, the library has not been explicitly tested against specific Node.js or browser versions.
+
+## Report a Bug
+
+Found a bug or unexpected behavior?
+
+[Please open a new issue.](https://github.com/pahkasoft/issues/issues/new)
+
+You can also suggest a feature or impovement.
+
+Thanks for helping improve the project!
+
+## License
+
+This project is licensed under the [MIT License](https://mit-license.org/).
+
+It also bundles the [Tone.js](https://github.com/Tonejs/Tone.js) library,
+which is licensed under the [MIT License](https://opensource.org/license/mit).