@tspro/web-music-score 1.1.0 → 3.0.0

package/README.md

@@ -2,336 +2,478 @@
 
 This library allows you to view and play music scores (notation) in the browser.
 
-Note: I'm not a professional musician. I began learning classical guitar on my own, 
+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 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.
+This is a work in progress project. Expect changes, bugs, or unexpected behavior.
+
+## 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.
 
 ## Installation
 
 ```sh
 npm i @tspro/web-music-score
-
-# React is required, it is peer dependency
-npm i react
 ```
 
-## Usage And API Documentation
-
-### Usage
+## Import
 
-#### Import (ESM)
 ```js
-// Import named exports
-import * as Score from "@tspro/web-music-score";
+// Import core module, it does not contain much.
+import * as Core from "@tspro/web-music-score/core";
 
-// Import default export
-import Score from "@tspro/web-music-score";
-```
+// Import audio module, it can play notes.
+import * as Audio from "@tspro/web-music-score/audio";
 
-#### Require (CommonJS)
-```js
-// Use require
-const Score = require("@tspro/web-music-score");
+// Import theory module, it contains all music theory stuff.
+import * as Theory from "@tspro/web-music-score/theory";
+
+// Import score module, it contains music score stuff.
+import * as Score from "@tspro/web-music-score/score";
+
+// Import react-ui module, it contains all react components.
+// React is peer dependency "^18.0.0 || ^19.0.0".
+import * as ScoreUI from "@tspro/web-music-score/react-ui";
+
+// Import pieces module, it contains demo songs.
+import * as Pieces from "@tspro/web-music-score/pieces";
+
+// You can also use require
+const Core = require("@tspro/web-music-score/core");
+
+// etc.
 ```
 
-#### Browser Script
-Use in browser via unpkg CDN.
-Browser version comes without React-components.
+## 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`).
 
 ```html
-<script src="https://unpkg.com/@tspro/web-music-score@1"></script>
+<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>
 
-<canvas id="scoreCanvas"></canvas><br />
-<button id="playButton"></button>
+<!--
+    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.
+-->
 
 <script>
-    const Score = window.WebMusicScore;
+    const { Core, Audio, Theory, Score, Pieces } = window.WebMusicScore;
     // ...
 </script>
 ```
 
-### Create Document
+## API
+
+Typedoc API reference is available [here](https://pahkasoft.github.io).
+It is not commented but is mostly self explanatory and gives idea of full API.
+
+Following is the main interface explained.
+
+### Create DocumentBuilder
+
+Documents are created using `DocumentBuilder`.
 
 ```js
-let doc = new Score.MDocument(Score.StaffKind.Treble, { measuresPerRow: 4 });
+let builder = new Score.DocumentBuilder();
+
+// Here build document, e.g.
+builder
+    .addMEasure()
+    .addNote(0, "C3", Theory.NoteLength.Quarter)
+    // etc.
+
+// When ready, get document:
+let doc = builder.getDocument();
 ```
 
-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.
+### Set Score Configuration
+Setting score configuration takes place in first measure of next row.
 
-Second argument is optional `DocumentOptions`:
-```ts
-DocumentOptions = { measuresPerRow?: number, tuning?: string }
+#### Using preset values
+```js
+builder.setScoreConfiguration(staffPreset: Score.StaffPreset);
 ```
 
-Default tuning is `"Standard"`. `TuningNameList` is array of available tuning names.
+`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.
 
-### Set Header
+```js
+// Example
+builder.setScoreConfiguration(Score.StaffPreset.GuitarCombined);
+```
 
+#### Using configuration objects
 ```js
-doc.setHeader("Title", "Composer", "Arranger");
-doc.setHeader("Title");
+builder.setScoreConfiguration(config: Score.StaffConfig | Score.TabConfig);
+builder.setScoreConfiguration(config: (Score.StaffConfig | Score.TabConfig)[]);
 ```
 
-Any of `title`, `composer` and `arranger` can be omitted/set undefined.
+`config` is `StaffConfig`, `TabConfig` or array of combination.
 
-### Add Measure
+`StaffConfig` contains following properties:
+* `type`: "staff"
+* `clef`: Clef can be `Score.Clef.G` or `Score.Clef.F`.
+* `isOctaveDown`: boolean (optional)
+* `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"
+* `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
-let m = doc.addMeasure();
+// Example: Staff and tab for guitar
+builder.setScoreConfiguration([
+    { type: "staff", clef: Score.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 }
+]);
 ```
 
-### End Row
+### Set Automatic Measures Per Row
+```ts
+builder.setMesuresPerRow(measuresPerRow: number)
+```
+
+`measuresPerRow` can be integer >= 1, or Infinity (default).
 
+### Set Header
 ```js
-m.endRow();
-```
+builder.setHeader(title?: string, composer?: string, arranger?: string);
 
-Manually induce row change. Next measure will be added to new row.
+// Example
+builder.setHeader("Demo Song");
+```
 
-### Set Signature
+### Add Measure
+```js
+builder.addMeasure();
+```
 
+### End Row
 ```js
-m.setKeySignature("C", Score.ScaleType.Major);
+builder.endRow();
 ```
 
-Firat argument is scale key note.
+Manually induce row change. Next measure that is added will begin new row.
 
-Second argument is `ScaleType`, which can be `Major`, `NaturalMinor`, `HarmonicMinor`, `Ionian`, `Dorian`, `Phrygian`, `Lydian`, `Mixolydian`, 
-`Aeolian`, `Locrian`, `MajorPentatonic`, `MinorPentatonic`, `MajorHexatonicBlues`, `MinorHexatonicBlues` or `HeptatonicBlues`.
+### Set Key Signature
 
 ```js
-m.setTimeSignature("4/4");
+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`
+
+### Set Time Signature
+```js
+builder.setTimeSignature(timeSignature: string);
+
+// Example
+builder.setTimeSignature("3/4");
 ```
 
-Time signature can be `"2/4"`, `"3/4"`, `"4/4"`, `"6/8"` or `"9/8"`.
+timeSignature can be:
+- `"2/4"`
+- `"3/4"`
+- `"4/4"`
+- `"6/8"`
+- `"9/8"`
 
+### Set Tempo
 ```js
-m.setTempo(80, Score.NoteLength.Quarter, false);
-m.setTempo(80);
+builder.setTempo(beatsPerMinute: number, beatLength?: Theory.NoteLength, dotted?: boolean);
+
+// Example
+builder.setTempo(100, Theory.NoteLength.Quarter);
 ```
 
-First argument is beats per minute.
+`beatsPerMinute` is self explanatory.
+
+`beatLength` tells  the length of each beat, e.g. Theory.NoteLength.Quarter.
 
-Second argument is beat length. Third argument tells if beat length is dotted. Second and third arguments can be omitted.
+`dotted` tells if `beatLength` is dotted.
 
 ### Add Note Or Chord
 
 ```js
-m.addNote(voiceId, note, noteLength, noteOptions?);
-m.addChord(voiceId, notes, noteLength, noteOptions);
-```
-
-* `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
+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:
-```js
-m.addNote(0, "C3", Score.NoteLength.Quarter);
-m.addChord(1, ["C3", "E3", "G3", "C4"], Score.NoteLength.Half, { dotted: true });
+// Examples
+builder.addNote(0, "C4", Theory.NoteLength.Half, { dotted: true });
+builder.addChord(1, ["C3", "E3", "G3"], Theory.NoteLength.Whole, { arpeggio: Score.Arpeggio.Down });
 ```
 
-#### NoteLength
+`voiceId` can be `0`, `1`, `2` or `3`.
 
-* `NoteLength.Whole`
-* `NoteLength.Half`
-* `NoteLength.Quarter`
-* `NoteLength.Eighth`
-* `NoteLength.Sixteenth`
-* `NoteLength.ThirtySecond`
-* `NoteLength.SixtyFourth`
+`note` is note name, e.g. `"G#3"`, `"Db3"`.
 
-#### NoteOptions
+`notes`: array of notes `string[]` (e.g. `["C3", "E3"]`)
 
-Optional object of note options (e.g. `{ stem: Stem.Up }`):
+`noteLength` can be:
+* `Theory.NoteLength.Whole`
+* `Theory.NoteLength.Half`
+* `Theory.NoteLength.Quarter`
+* `Theory.NoteLength.Eighth`
+* `Theory.NoteLength.Sixteenth`
+* `Theory.NoteLength.ThirtySecond`
+* `Theory.NoteLength.SixtyFourth`
 
-| 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` |
+`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. |
-| 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. |
+| triplet     | `boolean`               | Set this note part of triplet. |
+| string      | `number` \| `number[]`  | String number for guitar tab. Array of string numbers for chord. |
 
 ### Add Rest
 
 ```js    
-m.addRest(voideId, restLength, restOptions?);
+builder.addRest(voideId: number, restLength: Theory.NoteLength, restOptions?: Score.RestOptions);
+
+// Example
+builder.addRest(0, Theory.NoteLength.Sixteenth);
 ```
 
-* `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.
+ `voiceId` can be `0`, `1`, `2` or `3`.
 
-Example:
-```js
-m.addRest(0, Score.NoteLength.Quarter);
-```
+`restLength` is length of rest, similar as noteLength above.
 
-#### RestOptions
+`restOptions` is optional object of rest options (e.g. `{ hide: true }`):
 
-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 |
+| 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
 
 ```js
-m.addNote(0, "C3", Score.NoteLength.Quarter).addFermata(Score.Fermata.AtNote);
-m.addRest(0, Score.NoteLength.Quarter).addFermata();
-```
-
-Adds fermata anchored to previously added note or rest.
+builder.addFermata(fermata?: Score.Fermata);
 
-```js
-m.addFermata(Score.Fermata.AtMeasureEnd);
+// Example
+builder.addFermata(Score.Fermata.AtMeasureEnd);
 ```
 
-Adds fermata at measure end.
+`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.
 
-### Add Navigation
+### Add Connective (tie, slur)
 
 ```js
-m.addNavigation(Score.Navigation.DC_al_Fine);
-```
+// Add tie
+builder.addConnective(connective: Score.Connetive.Tie, span?: Score.ConnectiveSpan, noteAnchor?: Score.NoteAnchor);
 
-Adds navigational element to measure.
+// Add slur
+builder.addConnective(connective: Score.Connetive.Slur, span?: Score.ConnectiveSpan, noteAnchor?: Score.NoteAnchor);
 
-Available navigations are:
+// 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`.
 
-* `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`
+### Add Navigation
 
-`Navigation.EndRepeat` Takes optional second argument which is number of repeats. Defaults to 1 if omitted.
+Add navigational element to measure.
 
 ```js
-m.addNavigation(Score.Navigation.EndRepeat, 2);
+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);
 ```
 
-`Navigation.Ending` takes variable number of arguments, each is a passage number.
+`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`
 
-```js
-m.addNavigation(Score.Navigation.Ending, 1, 2);
-m.addNavigation(Score.Navigation.Ending, 3);
-```
+`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 Label
 
+Add text label anchored to previously added note, chord or rest.
+
 ```js
-m.addChord(0, ["D3", "F3", "A3"], Score.NoteLength.Quarter).addLabel(Score.Label.Chord, "Dm");
-```
+builder.addLabel(label: Score.Label, text: string);
 
-Available Label types are:
+// Example
+builder.addLabel(Score.Label.Chord, "Am);
+```
 
-* `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` 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
 
-```js
-m.addNote(0, "C3", Score.NoteLength.Quarter).addAnnotation(Score.Annotation.Dynamics, "fff");
-```
+Add annotation text anchored to previously added note, chord or rest.
 
-First argument is `Annotation`, second argument is the annotation text.
+```js
+builder.addAnnotation(annotation: Score.Annotation, text: string);
 
-Available annotations are:
+// Example
+builder.addAnnotation(Score.Annotation.Tempo, "accel.");
+```
 
-* `Annotation.Dynamics` could be for example `"fff"`, `"cresc."`, `"dim."`, etc.
-* `Annotation.Tempo` could be for example `"accel."`, `"rit."`, `"a tempo"`, etc.
+`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 Extension
 
+Adds extension line to element, for example to previously added annotation.
+
 ```js
-m.addNote(0, "C3", Score.NoteLength.Quarter).
-    addAnnotation(Score.Annotation.Tempo, "accel.").
-    addExtension(Score.NoteLength.Whole * 2, true);
-```
+builder.addExtension(extensionLength: number, visible?: boolean);
 
-Adds extension line to element, annotation in this case.
+// Example
+builder.addAnnotation(Score.Annotation.Tempo, "accel.").addExtension(Theory.NoteLength.Whole * 2, true);
+```
 
-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.
+`extensionLength` is `number` but `Theory.NoteLength` values can be used as number and 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.
+`visible` sets visibility of extension line, visible by default (if omitted).
 
 ### 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):
+This library has preliminary guitar tabs rendering. 
+Create document with `Score.StaffPreset.GuitarTab` or `Score.StaffPreset.GuitarCombined`, or set score configuration with TabConfig.
 
-```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.
+Add notes with `{ string: number | number[] }` to specify which string the fret number is rendered in guitar tab.
 
 ```js
 // Single note
-m.addNote(0, "G3", Score.NoteLength.Eighth, { string: 3 });
+builder.addNote(0, "G3", Theory.NoteLength.Eighth, { string: 3 });
 
 // Multi note
-m.addChord(0, ["E4", "C3"], Score.NoteLength.Eighth, { string: [1, 5] });
+builder.addChord(0, ["E4", "C3"], Theory.NoteLength.Eighth, { string: [1, 5] });
 ```
 
-
 ### Queueing
 
-Adding stuff to measures can be queued like this:
+`DocumentBuilder` operations can be queued.
 
 ```js
-doc.addMeasure()
-    .addNote(1, "C3", Score.NoteLength.Quarter)
-    .addChord(1, ["C3", "E3", "G3"], Score.NoteLength.Quarter).addLabel(Score.Label.Chord, "C")
-    .addRest(1, Score.NoteLength.Quarter);
+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();
 ```
 
 ### Beams
 
 Beams are detected and added automatically.
 
-### Play Document
+### Classical Guitar Audio Module
 
-```js
-Score.Audio.setInstrument(Score.Audio.Instrument.ClassicalGuitar);
-```
+Default instrument is `Synthesizer`.
 
-Sets instrument. Instrument can be ClassicalGuitar or Synth.
+`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.
 
 ```js
-doc.play();
+import { registerClassicalGuitar } from "@tspro/web-music-score/audio-cg";
+
+registerClassicalGuitar();
 ```
 
-Plays the document.
+### Play Document
 
 ```js
+// Simple play
+doc.play();
+
+// More playback options:
 let player = new MPlayer(doc);
 
 player.play();
@@ -341,21 +483,19 @@ player.stop();
 MPlayer.stopAll();
 ```
 
-More playback methods.
-
 ### Viewing Using React JSX/TSX
 
 ```js
 // Draw document
-<Score.MusicScoreView doc={doc} />
+<ScoreUI.MusicScoreView doc={doc} />
 
 // Add playback buttons
-<Score.PlaybackButtons doc={doc} buttonLayout={Score.PlaybackButtonsLayout.PlayStopSingle}/> // Single Play/Stopo button
-<Score.PlaybackButtons doc={doc} buttonLayout={Score.PlaybackButtonsLayout.PlayStop}/> // Play and Stop buttons
-<Score.PlaybackButtons doc={doc} buttonLayout={Score.PlaybackButtonsLayout.PlayPauseStop}/> // Play, Pause and Stop 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
 ```
 
-Bootstrap is used for better visual appearance but you must load it.
+Bootstrap is used for better visual appearance, but it needs to be installed and loaded.
 
 ### Viewing Using Plain JS/TS
 
@@ -394,29 +534,22 @@ p.setPlayStopButton("playStopButtonId")
 p.setPlayButton(playButtonElement)
 ```
 
-### Error Handling
-
+### MusicError
 ```js
 try {
-    // Invalid note "C" without octave.
-    m.addNote(0, "C", Score.NoteLength.Quarter);        
+    // Do your music stuff
 }
-catch(e) {
-    // MusicError is raised on errors.
-    if(e instanceof Score.MusicError) {
-        console.log(e);
+catch (e) {
+    if(e instanceof Core.MusicError) {
+        // There was music error.
     }
 }
 ```
 
 ## 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.
+- This library is bundled to ESM, CJS and IIFE formats.
+- Target is to support ES6/ES2015.
+- No polyfills are included.
 
 While designed for compatibility in mind, the library has not been explicitly tested against specific Node.js or browser versions.