@tspro/web-music-score 3.2.0 → 4.0.0

package/README.md

@@ -1,6 +1,6 @@
 # WebMusicScore
 
-Typedoc API Reference, Examples and Demos can be found [here](https://pahkasoft.github.io). The API Reference is not commented but is mostly self explanatory and gives idea of full API.
+The API Reference, Examples and Demos can be found [here](https://pahkasoft.github.io). The API Reference is very little commented but gives idea of the full API.
 
 ## About
 
@@ -9,30 +9,11 @@ This library allows you to view and play music scores (notation) in the browser.
 I'm not a professional musician. I began learning classical guitar on my own, 
 later taking lessons in classical guitar. I've also studied music theory independently.
 
-This is a work in progress project. Expect changes, bugs, or unexpected behavior.
+This is a work in progress project. Lately there has been improvements that required major
+version update. As the project matures there might be less major updates, and more minor
+updates and patches.
 
-## Version 2 Update
-
-**Breaking:** Version 2 is major update and brought many changes.
-
-* Introduced subpath modules instead of one big main module. There is no main export.
-* Theory module had big refactor that affected whole library. Renamed all musical terms that
-  were wrong (e.g. pitch => diatonicId, noteId => chromaticId).
-* Score module stayed mostly same. Some changes (e.g. enum StaffKind => StaffPreset) but nothing major.
-* Classical guitar audio was put into separate module (audio-cg) because it bundles over 1MB of audio
-  samples. Also improved default synthesizer audio.
-* Numerous small changes/improvements.
-
-Enough changes until next major update!
-
-## Version 3 Update
-
-**Breaking:** Version 3 is another major update and brought some important changes.
-
-* Support score configuration with multiple notation lines (combination of staves and tabs).
-* Introduced DocumentBuilder to create scores, removed old way.
-* DocumentOptions functionality is replaced using functions addScoreConfiguration() and setMeasuresPerRow() in DocumentBuilder.
-* Add ties, slurs and slides using addConnective() in DocumentBuilder. Tie and span options removed from NoteOptions.
+This version (4.0.0) added support for string arguments in addition to typescript enums (e.g. NoteLength.Quarter => "4n", just to name one).
 
 ## Installation
 
@@ -63,25 +44,24 @@ import * as ScoreUI from "@tspro/web-music-score/react-ui";
 import * as Pieces from "@tspro/web-music-score/pieces";
 
 // You can also use require
-const Core = require("@tspro/web-music-score/core");
-
-// etc.
+const Score = require("@tspro/web-music-score/score");
 ```
 
 ## Browser Script
 
-This is an experimental 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 (excluding `react-ui` and `audio-cg`).
+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).
 
 ```html
-<script src="https://unpkg.com/@tspro/web-music-score@3"></script>
-<script src="https://unpkg.com/@tspro/web-music-score@3.0.0"></script>
-<script src="https://unpkg.com/@tspro/web-music-score@3.0.0/dist/iife/index.global.js"></script>
+<script src="https://unpkg.com/@tspro/web-music-score@4"></script>
+<script src="https://unpkg.com/@tspro/web-music-score@4.0.0"></script>
+<script src="https://unpkg.com/@tspro/web-music-score@4.0.0/dist/iife/index.global.js"></script>
 
 <!--
-    Use one of above. It is recommended to use version number (e.g. @3.0.0 or at least @3).
-    This way if there is breaking change between versions your code does not stop working.
+    Use one of above. It is recommended to use version number (e.g. @4.0.0 or at least @4).
+    This way if something breaks between versions then your web site does not stop working.
 -->
 
 <script>
@@ -92,406 +72,284 @@ and `Pieces` as corresponding subpath modules (excluding `react-ui` and `audio-c
 
 ## API
 
-Following is the main interface explained.
+Following is introduction to the main interface with the help of simple examples.
 
-### Create DocumentBuilder
+### Using `DocumentBuilder`
 
-Documents are created using `DocumentBuilder`.
+```js
+let doc = new Score.DocumentBuilder()
+    .addScoreConfiguration({ type: "staff", clef: "G", isOctavewDown: true })
+    .setMeasuresPerRow(4)
+    .addMeasure()
+    .addNote(1, "C3", "4n")
+    .addChord(1, ["C3", "E3", "G3"], "4n").addLabel("chord", "C")
+    .addRest(1, "4n")
+    // etc.
+    .getDEocument();
+```
 
+**Hint:**
 ```js
-let builder = new Score.DocumentBuilder();
+    // In following examples this:
+    .addNote(...)
 
-// Here build document, e.g.
-builder
-    .addMEasure()
-    .addNote(0, "C3", Theory.NoteLength.Quarter)
-    // etc.
+    // means call to the DocumentBuilder object:
+    documentBuilder.addNote(...)
 
-// When ready, get document:
-let doc = builder.getDocument();
+    // It is just shortened for simplicity.
 ```
 
 ### Set Score Configuration
-Setting score configuration takes place in first measure of next row.
+New score configuration takes place in the first measure of next row.
 
 #### Using preset values
-```js
-builder.setScoreConfiguration(staffPreset: Score.StaffPreset);
-```
 
-`staffPreset` can be:
-* `Score.StaffPreset.Treble`: Staff with treble (G-) clef.
-* `Score.StaffPreset.Bass`: Staff with bass (F-) clef.
-* `Score.StaffPreset.Grand`: Both treble and bas staves.
-* `Score.StaffPreset.GuitarTreble`: Same as `Treble` but one octave down.
-* `Score.StaffPreset.GuitarTab`: Guitar tab only.
-* `Score.StaffPreset.GuitarCombined`: Treble and tab for guitar.
+For staff presets you can use `Score.StaffPreset` enum values (e.g. `Score.StaffPreset.Treble`)
+or corresponding string values (e.g. `"treble"`).
 
 ```js
-// Example
-builder.setScoreConfiguration(Score.StaffPreset.GuitarCombined);
+.setScoreConfiguration("treble")         // Staff with treble G-clef.
+.setScoreConfiguration("bass")           // Staff with bass F-clef.
+.setScoreConfiguration("grand")          // Both treble and bas staves.
+.setScoreConfiguration("guitarTreble")   // Same as `Treble` but one octave down.
+.setScoreConfiguration("guitarTab")      // Guitar tab only.
+.setScoreConfiguration("guitarCombined") // Treble and tab for guitar.
 ```
 
 #### Using configuration objects
 ```js
-builder.setScoreConfiguration(config: Score.StaffConfig | Score.TabConfig);
-builder.setScoreConfiguration(config: (Score.StaffConfig | Score.TabConfig)[]);
-```
-
-`config` is `StaffConfig`, `TabConfig` or array of combination.
-
-`StaffConfig` contains following properties:
-* `type`: "staff"
-* `clef`: Clef can be `Score.Clef.G` or `Score.Clef.F`.
-* `isOctaveDown`: boolean (optional)
-* `name`: staff name.
-* `minNote`: string (optional), minimum note allowed in staff.
-* `maxNote`: string (optional), maximum note allowed in staff.
-* `voiceIds`: number[] (optional), array of voice ids are visible on this staff.
-* `isGrand`: boolean (optional), use this to create grand staff.
-
-`TabConfig` contains following properties:
-* `type`: "tab"
-* `name`: tab name.
-* `tuning`: string | string[] (optional), tuning name or array of 6 note names for tuning.
-* `voiceIds`: number[] (optional), array of voice ids are visible on this tab.
-
-```js
-// Example: Staff and tab for guitar
-builder.setScoreConfiguration([
-    { type: "staff", clef: Score.Clef.G, isOctaveDown: true },
+.setScoreConfiguration({ type: "staff", clef: "G"}) // Staff with treble G-clef.
+.setScoreConfiguration({ type: "staff", clef: "F"}) // Staff with bass F-clef.
+.setScoreConfiguration({
+    type: "staff",
+    clef: "G",           // G-clef
+    isOctaveDown: false, // (optional) octave down
+    name: "staff1",      // (optional) staff name
+    minNote: "C2",       // (optional) min allowed note
+    maxNote: "C6",       // (optional) max allowed note
+    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 }
+]) // Grand staff
+.setScoreConfiguration([
+    { type: "staff", clef: "G", isOctaveDown: true },
     { type: "tab", tuning: "Drop D" }
-]);
-
-// Example: Grand staff
-builder.setScoreConfiguration([
-    { type: "staff", clef: Score.Clef.G, isGrand: true },
-    { type: "staff", clef: Score.Clef.F, isGrand: true }
-]);
+]) // Staff and tab for guitar, tab with Drop D tuning.
+.setScoreConfiguration(
+{
+    type: "tab",
+    name: "tab1",
+    tuning: ["E2", "A2", "D3", "G3", "B3", "E4"],
+    voiceIds: 4
+}) // Tab with guitar tuning, present only voiceId 4 in this tab.
 ```
 
 ### Set Automatic Measures Per Row
 ```ts
-builder.setMesuresPerRow(measuresPerRow: number)
+.setMesuresPerRow(4)        // Set 4 measures per row
+.setMesuresPerRow(Infinity) // Turn off auto row change (default)
 ```
 
-`measuresPerRow` can be integer >= 1, or Infinity (default).
-
 ### Set Header
 ```js
-builder.setHeader(title?: string, composer?: string, arranger?: string);
-
-// Example
-builder.setHeader("Demo Song");
+.setHeader("Title", "Composer", "Arranger") // Set title, composer and arranger
+.setHeader("Title")                         // Set title only
 ```
 
 ### Add Measure
 ```js
-builder.addMeasure();
+.addMeasure() // Add new measure
 ```
 
 ### End Row
 ```js
-builder.endRow();
+.endRow() // Manually induce row change. Next measure that is added will begin new row.
 ```
 
-Manually induce row change. Next measure that is added will begin new row.
-
 ### Set Key Signature
+For scale type you can use `Theory.ScaleType` enum values (e.g. `Theory.ScaleType.Major`)
+or corresponding string values (e.g. `"Major"`).
 
 ```js
-builder.setKeySignature(tonic: string, scaleType: Theory.ScaleType);
-
-// Example: Am
-builder.setKeySignature("A", Theory.ScaleType.Aeolian);
-```
-
-`tonic` is scale tonic/root note, e.g. "C" (in "C Major").
-
- `scaleType` can be
- - `Theory.ScaleType.Major`
- - `Theory.ScaleType.NaturalMinor`
- - `Theory.ScaleType.HarmonicMinor`
- - `Theory.ScaleType.Ionian`
- - `Theory.ScaleType.Dorian`
- - `Theory.ScaleType.Phrygian`
- - `Theory.ScaleType.Lydian`
- - `Theory.ScaleType.Mixolydian`
- - `Theory.ScaleType.Aeolian`
- - `Theory.ScaleType.Locrian`
- - `Theory.ScaleType.MajorPentatonic`
- - `Theory.ScaleType.MinorPentatonic`
- - `Theory.ScaleType.MajorHexatonicBlues`
- - `Theory.ScaleType.MinorHexatonicBlues`
- - `Theory.ScaleType.HeptatonicBlues`
+.setKeySignature("C Major")            // Create C Major scale.
+.setKeySignature("D", "Major")         // Create D Major scale.
+.setKeySignature("A", "Natural Minor") // Create A natural minor scale.
+```
 
 ### Set Time Signature
 ```js
-builder.setTimeSignature(timeSignature: string);
-
-// Example
-builder.setTimeSignature("3/4");
+.setTimeSignature("2/4") // Set time signature of 2/4
+.setTimeSignature("3/4") // Set time signature of 3/4
+.setTimeSignature("4/4") // Set time signature of 4/4
+.setTimeSignature("6/8") // Set time signature of 6/8
+.setTimeSignature("9/8") // Set time signature of 9/8
 ```
 
-timeSignature can be:
-- `"2/4"`
-- `"3/4"`
-- `"4/4"`
-- `"6/8"`
-- `"9/8"`
-
 ### Set Tempo
 ```js
-builder.setTempo(beatsPerMinute: number, beatLength?: Theory.NoteLength, dotted?: boolean);
-
-// Example
-builder.setTempo(100, Theory.NoteLength.Quarter);
+.setTempo(100, "4n") // 100 beats per minute, beat length is quarter note.
+.setTempo(80, "4..") // 100 beats per minute, beat length is double dotted quarter note.
 ```
 
-`beatsPerMinute` is self explanatory.
-
-`beatLength` tells  the length of each beat, e.g. Theory.NoteLength.Quarter.
-
-`dotted` tells if `beatLength` is dotted.
-
-### Add Note Or Chord
-
+### Add Note
 ```js
-builder.addNote(voiceId: number, note: string, noteLength: Theory.NoteLength, noteOptions?: Score.NoteOptions);
-builder.addChord(voiceId: number, notes: string[], noteLength: Theory.NoteLength, noteOptions?: Score.NoteOptions);
-
-// Examples
-builder.addNote(0, "C4", Theory.NoteLength.Half, { dotted: true });
-builder.addChord(1, ["C3", "E3", "G3"], Theory.NoteLength.Whole, { arpeggio: Score.Arpeggio.Down });
+.addNote(0, "C4", "1n")                     // Create whole note "C4"
+.addNote(0, "Bb4", "2..")                   // Create double dotted half note "Bb4"
+.addNote(0, "C4", "4n", { stem: "up" })     // Stem direction Up (could be also Down)
+.addNote(0, "C4", "4n", { staccate: true }) // Show staccato dot and play in short
+.addNote(0, "C4", "4n", { diamond: true })  // Show diamond shaped note head
 ```
 
-`voiceId` can be `0`, `1`, `2` or `3`.
-
-`note` is note name, e.g. `"G#3"`, `"Db3"`.
-
-`notes`: array of notes `string[]` (e.g. `["C3", "E3"]`)
-
-`noteLength` can be:
-* `Theory.NoteLength.Whole`
-* `Theory.NoteLength.Half`
-* `Theory.NoteLength.Quarter`
-* `Theory.NoteLength.Eighth`
-* `Theory.NoteLength.Sixteenth`
-* `Theory.NoteLength.ThirtySecond`
-* `Theory.NoteLength.SixtyFourth`
-
-`noteOptions` is optional object of note options (e.g. `{ dotted: true }`):
-
-| Note option | Type                      |                     |
-|-------------|---------------------------|---------------------|
-| dotted      | `boolean`                 | Create dotted note. |
-| stem        | `Score.Stem.Auto/Up/Down` | Set stem direction. |
-| arpeggio    | `Score.Arpeggio.Up/Down` \| `boolean`  | Play column in arpeggio. |
-| staccato    | `boolean`               | Play column in staccato. |
-| diamond     | `boolean`               | Diamond shaped note head. |
-| triplet     | `boolean`               | Set this note part of triplet. |
-| string      | `number` \| `number[]`  | String number for guitar tab. Array of string numbers for chord. |
+### Add Chord
+```js
+.addChord(1, ["C3", "E3", "G3"], "1n", { arpeggio: "down" }) // Create whole note chord of three notes, played in arpeggio.
+```
 
 ### Add Rest
 
 ```js    
-builder.addRest(voideId: number, restLength: Theory.NoteLength, restOptions?: Score.RestOptions);
-
-// Example
-builder.addRest(0, Theory.NoteLength.Sixteenth);
+.addRest(0, "16n")                    // Add sixteenth rest
+.addRest(0, "4.")                     // Add dotted quarter rest
+.addRest(0, "4n", { staffPos: "D3" }) // Draw this quarter rest at level of "D3" note.
+.addRest(0, "4n", { hide: true })     // Invisible rest affects playing
 ```
 
- `voiceId` can be `0`, `1`, `2` or `3`.
-
-`restLength` is length of rest, similar as noteLength above.
-
-`restOptions` is optional object of rest options (e.g. `{ hide: true }`):
-
-| Rest option | Type         |                     |
-|-------------|--------------|---------------------|
-| dotted      | `boolean`    | Create dotted rest. |
-| staffPos    | `string`     | Staff positions (e.g. `"C3"`). |
-| hide        | `boolean`    | Add invisible rest. |
-| triplet     | `boolean`    | Set this rest part of triplet. |
-
-### Add Fermata
-
+### Add Tuplet
+This works for any tuplet:
 ```js
-builder.addFermata(fermata?: Score.Fermata);
-
-// Example
-builder.addFermata(Score.Fermata.AtMeasureEnd);
+// Example: add triplet
+.addTuplet(0, { parts: 3, inTimeOf: 2 }, notes => {
+    notes.addNote("G3", "8n")
+    notes.addNote("B3", "8n")
+    notes.addNote("D4", "8n")
+})
 ```
 
-`fermata` is typeof `Score.Fermata` and can be:
-- `Score.Fermata.AtNote`: Adds fermata anchored to previously added note, chord or rest.
-- `Score.Fermata.AtMeasureEnd`: Adds fermata at the end of measure.
+Triplets can also be created using note length (e.g. NoteLength.EighthTriplet or "8t").
+```js
+// Example: add triplet using triplet note length.
+.addNote(0, "G3", "8t")
+.addNote(0, "B3", "8t")
+.addNote(0, "D4", "8t")
+```
 
-### Add Navigation
+### Add Fermata
 
-Add navigational element to measure.
+For fermata you can use `Score.Fermata` enum values (e.g. `Scoore.Fermata.AtNote`)
+or corresponding string values (e.g. `"atNote"`).
 
 ```js
-builder.addNavigation(navigation: Score.Navigation, ...args?);
-
-// Examples
-builder.addNavigation(Score.Navigation.StartRepeat);
-builder.addNavigation(Score.Navigation.EndRepeat, 3);
-builder.addNavigation(Score.Navigation.Ending, 1, 2);
+.addNote(0, "C3", "2n").addFermata("atNote") // Add fermata at note.
+.addFermata("atMeasureEnd")                  // Add fermata at measure end.
 ```
 
-`navigation` can be:
-* `Score.Navigation.DC_al_Fine`
-* `Score.Navigation.DC_al_Coda`
-* `Score.Navigation.DS_al_Fine`
-* `Score.Navigation.DS_al_Coda`
-* `Score.Navigation.Coda`
-* `Score.Navigation.toCoda`
-* `Score.Navigation.Segno`
-* `Score.Navigation.Fine`
-* `Score.Navigation.StartRepeat`
-* `Score.Navigation.EndRepeat`
-* `Score.Navigation.Ending`
-
-`Score.Navigation.EndRepeat` takes optional second arg which is number of times to repeat (once if omitted).
-
-`Score.Navigation.Ending` takes variable number of number args, each is a passage number.
+### Add Navigation
 
-### Add Label
+Add navigation element to measure.
 
-Add text label anchored to previously added note, chord or rest.
+For navigation you can use `Score.Navigation` enum values (e.g. `Score.Navigation.DC_al_Fine`)
+or corresponding string values (e.g. `"D.C. al Fine"`).
 
 ```js
-builder.addLabel(label: Score.Label, text: string);
-
-// Example
-builder.addLabel(Score.Label.Chord, "Am);
+.addNavigation("D.C. al Fine") // Add "D.C. al Fine"
+.addNavigation("D.C. al Coda") // Add "D.C. al Coda"
+.addNavigation("D.S. al Fine") // Add "D.S. al Fine"
+.addNavigation("D.S. al Coda") // Add "D.S. al Coda"
+.addNavigation("Coda")         // Add "Coda"
+.addNavigation("toCoda")       // Ass "toCoda"
+.addNavigation("Segno")        // Add "Segno" symbol
+.addNavigation("Fine")         // Add "Fine"
+.addNavigation("startRepeat")  // Add repeat sections start position
+.addNavigation("endRepeat", 3) // Add repeat sections end position, repeat sectionplayed 3 times
+.addNavigation("ending", 1, 2) // Add ending, played on 1st and 2nd run
 ```
 
-`label` can be:
-* `Score.Label.Note`: Used to label notes and is positioned below note.
-* `Score.Label.Chord`: Used to label chords and is positioned on top.
-
 ### Add Annotation
 
 Add annotation text anchored to previously added note, chord or rest.
 
-```js
-builder.addAnnotation(annotation: Score.Annotation, text: string);
+For annotation you can use `Score.Annotation` enum values (e.g. `Score.Annotation.Tempo`)
+or corresponding string values (e.g. `"tempo"`).
 
-// Example
-builder.addAnnotation(Score.Annotation.Tempo, "accel.");
+```js
+.addAnnotation("dynamics", "ff")  // Add dynamics annotation text.
+.addAnnotation("tempo", "accel.") // Add tempo annotation text.
+.addAnnotation("ppp")             // Add annotation text, detect annotation type automatically (incomplete list of annotations supported).
 ```
 
-`annotation` can be:
-* `Score.Annotation.Dynamics`: `text` could be for example `"fff"`, `"cresc."`, `"dim."`, etc.
-* `Score.Annotation.Tempo`: `text` could be for example `"accel."`, `"rit."`, `"a tempo"`, etc.
-
-### Add Elements To Certain Staff Or Tab
-
-There are alternatives to these functions:
-- `addFermata` => `addFermataTo`
-- `addNavigation` => `addNavigationTo`
-- `addAnnotation` => `addAnnotationTo`
-- `addLabel` => `addLabelTo`.
-
-First argument of these alterate functions is:
+### Add Label
 
- `staffTabOrGroups: Score.StaffTabOrGroups`.
+Add text label anchored to previously added note, chord or rest.
 
-`StaffTabOrGroups` can be:
-- `number`: staff/tab index, 0=top staff/tab, etc.
-- `string`: staff/tab name.
-- `string`: staff group name.
-- `(number | string)[]`: an array of staff/tab indices, names or group names.
+For label you can use `Score.Label` enum values (e.g. `Score.Label.Chord`)
+or corresponding string values (e.g. `"chord"`).
 
 ```js
-// Example: add label to top staff/tab.
-builder.addLabelTo(0, Score.Label.Chord, "Am");
+.addLabel("chord", "Am") // Add chord label, positioned above staff by default.
+.addLabel("note", "C#5") // Add note label, positioned below staff by default.
 ```
 
-#### Staff Group
-```js
-builder.addStaffGroup(groupName: string, staffsTabsAndGroups: number | string | (number | string)[], verticalPosition: Score.VerticalPosition);
-```
+### Positioning Elements
 
-Arguments are:
-- `groupName`: Name of new staff group.
-- `staffsTabsAndGroups`: single value or an array of staves, tabs and groups (index or name).
-- `verticalPosition` (optional): Can be `Score.VerticalPosition.Above`/`Below`/`Both`/`Auto` (default).
+`addFermata`, `addNavigation`, `addAnnotation` and `addLabel` functions have alternate versions 
+`addFermataTo`, `addNavigationTo`, `addAnnotationTo` and `addLabelTo` that contain extra first argument.
 
 ```js
-// Example: create staff group to add elements below top staff/tab.
-// Add staff group
-builder.addStaffGroup("grp1", [0], Score.VertocalPosition.Below);
-// Use group
-builder.addLabelTo("grp1", Score.Label.Note, "C");
+.addLabelTo(0, "chord", "Am")        // Add label to top (id 0) staff/tab.
+.addLabelTo([0, 1], "chord", "Am")   // Add label to top two (id 0 and 1) staves/tabs.
+.addLabelTo("staff1", "chord", "Am") // Add label to staff/tab/group named "staff1".
+.addLabelTo("grp1", "chord", "Am")   // Add label to staff/tab/group named "grp1".
+
+// Create staff groups
+.addStaffGroup("grp1", 0, "above")                 // This staff group layouts elements above top staff/tab.
+.addStaffGroup("grp2", [1], "below")               // This staff group layouts elements below second staff/tab from top.
+.addStaffGroup("grp3", "tab1", "both")             // This staff group layouts elements above and below tab named "tab1".
+.addStaffGroup("grp4", ["staff1", "tab1"], "auto") // This staff group layouts elements to their default locations in "staff1" and "tab1".
 ```
 
 ### Add Extension
 
-Adds extension line to element, for example to previously added annotation.
+Adds extension line to previously added label or annotation.
 
 ```js
-builder.addExtension(extensionLength: number, visible?: boolean);
-
-// Example
-builder.addAnnotation(Score.Annotation.Tempo, "accel.").addExtension(Theory.NoteLength.Whole * 2, true);
+.addExtension(ext => ext.notes("1n", 2))    // Add extension line, length is 2 whole notes
+.addExtension(ext => ext.measures(3).hide())      // Add extension line, length is 3 measures, hidden
+.addExtension(ext => ext.measures(1).notes("8n")) // Add extension line, length is 1 measure + 1 eigth note
+.addExtension(ext => ext.infinity())              // Add extension line, length is as long as possible
+.addExtension()                                   // Add extension line, length is as long as possible
 ```
 
-`extensionLength` is `number` but `Theory.NoteLength` values can be used as number and multiplied to set desired extension length.
-
-`visible` sets visibility of extension line, visible by default (if omitted).
-
 ### Add Connective (tie, slur, slide)
 
-```js
-// Add tie
-builder.addConnective(connective: Score.Connetive.Tie, span?: Score.ConnectiveSpan, noteAnchor?: Score.NoteAnchor);
-
-// Add slur
-builder.addConnective(connective: Score.Connetive.Slur, span?: Score.ConnectiveSpan, noteAnchor?: Score.NoteAnchor);
-
-// Add slide
-builder.addConnective(connective: Score.Connetive.Slide, noteAnchor?: Score.NoteAnchor);
-```
-
-- `span` describes how many notes the connective is across.
-  It is integer >= 2 (for tie it can be also `Score.TieType.Stub|ToMeasureEnd`).
-  Default value is 2.
-- `noteAnchor` describes the attach point of connective to note.
-  It can be `Score.NoteAnchor.Auto|Above|Center|Below|StemTip`.
-  Default value is `Score.NoteAnchor.Auto`.
-
-### Guitar Tab
+For connective you can use `Score.Connective` enum values (e.g. `Score.Connective.Tie`)
+or corresponding string values (e.g. `"tie"`).
 
-This library has preliminary guitar tabs rendering. 
-Create document with `Score.StaffPreset.GuitarTab` or `Score.StaffPreset.GuitarCombined`, or set score configuration with TabConfig.
+For note anchor you can use `Score.NoteAnchor` enum values (e.g. `Score.NoteAnchor.Above`)
+or corresponding string values (e.g. `"above"`).
 
-Add notes with `{ string: number | number[] }` to specify which string the fret number is rendered in guitar tab.
 
 ```js
-// Single note
-builder.addNote(0, "G3", Theory.NoteLength.Eighth, { string: 3 });
-
-// Multi note
-builder.addChord(0, ["E4", "C3"], Theory.NoteLength.Eighth, { string: [1, 5] });
+.addConnective("tie")    // Add tie
+.addConnective("slur")   // Add slur
+.addConnective("slide")  // Add slide
+.addConnective("tie", 3) // Add tie with span value (describes how many notes the connective is across).
+.addConnective("slur", 2, "above")   // Add slur connected above note.
+.addConnective("slur", 2, "below")   // Add slur connected below note.
+.addConnective("slur", 2, "center")  // Add slur connected next to note.
+.addConnective("slur", 2, "stemTip") // Add slur connected at stem tip.
 ```
 
-### Queueing
+### Guitar Tab
+
+This library has simple guitar tab rendering. 
 
-`DocumentBuilder` operations can be queued.
+Add notes with `string` property to specify at what string the fret number is rendered in the tab.
 
 ```js
-let doc = new Score.DocumentBuilder()
-    .addScoreConfiguration({ type: "staff", clef: Score.Clef.G, isOctavewDown: true })
-    .setMeasuresPerRow(4)
-    .addMeasure()
-    .addNote(1, "C3", Theory.NoteLength.Quarter)
-    .addChord(1, ["C3", "E3", "G3"], Theory.NoteLength.Quarter).addLabel(Score.Label.Chord, "C")
-    .addRest(1, Theory.NoteLength.Quarter)
-    // etc.
-    .getDEocument();
+.addNote(0, "G3", "8n", { string: 3 })
+.addChord(0, ["E4", "C3"], "8n", { string: [1, 5] })
 ```
 
 ### Beams
@@ -503,12 +361,12 @@ Beams are detected and added automatically.
 Default instrument is `Synthesizer`.
 
 `Classical Guitar` is available via `audio-cg` module.
-It was included as separate module because it contains over 1MB of audio samples bundled in it.
+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";
 
-registerClassicalGuitar();
+registerClassicalGuitar(); // This registers classical guitar audio, and takes it into use.
 ```
 
 ### Play Document
@@ -518,13 +376,13 @@ registerClassicalGuitar();
 doc.play();
 
 // More playback options:
-let player = new MPlayer(doc);
+let player = new Score.MPlayer(doc);
 
 player.play();
 player.pause();
 player.stop();
 
-MPlayer.stopAll();
+Score.MPlayer.stopAll();
 ```
 
 ### Viewing Using React JSX/TSX