Update branch

.gitattributes

@@ -0,0 +1,2 @@
+# ignore test data
+test/data/** linguist-documentation

.github/workflows/test.yml

@@ -9,7 +9,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [12, 14, 16]
+        node-version: [18, 20, 22]
 
     steps:
     - name: Install dependencies
@@ -20,6 +20,6 @@ jobs:
       with:
         node-version: ${{ matrix.node-version }}
     - run: npm install
-    - run: npm test && npm run test:typescript
+    - run: npm test
       env:
         CI: true

README.md

@@ -1,21 +1,28 @@
 # ireal-musicxml
-
-iReal Pro to MusicXML converter
+iReal Pro to MusicXML converter.
 
 [![npm version](https://badge.fury.io/js/ireal-musicxml.svg)](https://badge.fury.io/js/ireal-musicxml)
 ![GitHub Build Status](https://github.com/infojunkie/ireal-musicxml/workflows/Test/badge.svg)
 
 # Demo
+[Check out the demo!](https://blog.karimratib.me/demos/chirp/) You can upload one of the [iReal Pro main playlists](https://www.irealpro.com/main-playlists/) as a test.
 
-[Check out the demo!](https://blog.karimratib.me/demos/musicxml/) You can upload one of the [iReal Pro main playlists](https://www.irealpro.com/main-playlists/) as a test.
+# Installation
+- Install `xmllint` (included in [libxml2](http://www.xmlsoft.org/) on most platforms) - only needed for validation
+- `npm install && npm run build`
+- `npm test`
 
 # Usage
-
 ```javascript
-import * as iReal2MusicXML from 'ireal-musicxml'
+import {
+  convertSync,
+  convert,
+  Playlist,
+  Converter
+} from 'ireal-musicxml'
 const ireal = // Content of HTML file generated by iReal Pro or irealb:// URI
-const playlistSync = iReal2MusicXML.convertSync(ireal)
-const playlistAsync = await iReal2MusicXML.convert(ireal)
+const playlistSync = convertSync(ireal)
+const playlistAsync = await convert(ireal)
 // => {
 //   name:              // Playlist name
 //   songs: [{
@@ -33,23 +40,41 @@ const playlistAsync = await iReal2MusicXML.convert(ireal)
 //   }]
 // }
 
-const playlistManual = new iReal2MusicXML.Playlist(ireal)
-// => Same as above minus `musicXml` attribute
-const musicXml = iReal2MusicXML.MusicXML.convert(playlistManual.songs[0])
-// => MusicXML output
+const playlistManual = new Playlist(ireal)
+// => Same as above minus `musicXml` attribute.
+
+const musicXml = Converter.convert(playlistManual.songs[0])
+// => MusicXML output of the first song in the above playlist.
 ```
 
-# Development
+```bash
+$ ireal-musicxml test/data/jazz1460.txt --songs=Blues --validate
+```
 
-`xmllint` is required to run tests (but NOT at runtime). Tests are used to ensure that the generated MusicXML is valid.
+# Theory of operation
+This module parses an iReal Pro URI or playlist file, and transforms each song it finds to a MusicXML lead sheet. The conversion process tries to produce a high-fidelity replica of the source sheet by recreating the following aspects of the [iReal Pro format](doc/irealpro.md):
 
-```
-npm install
-npm run test
-```
+## Harmonic information
+The chords found in the iReal Pro song are translated to their MusicXML representation. Because the chords supported by iReal Pro are a subset of the [harmonic expressivity of MusicXML](https://www.w3.org/2021/06/musicxml40/musicxml-reference/elements/harmony/), this translation is exact. [More information can be found in this blog post](https://blog.karimratib.me/2020/11/30/ireal-musicxml.html#emitting-correct-chord-information).
+
+An additional detail is the handling of "alternate chords" that can be specified in iReal Pro - these also [will be handled in this converter eventually](https://github.com/infojunkie/ireal-musicxml/issues/2).
+
+## Rhythmic information
+Because iReal Pro uses a fixed grid for each bar, timing assumptions need to be made about chord onsets, [both in the iReal Pro app itself](https://www.irealb.com/forums/showthread.php?25161-Using-empty-cells-to-control-chord-duration) and in this converter. The [timing algorithm is described in this blog post](https://blog.karimratib.me/2020/11/30/ireal-musicxml.html#emulating-the-ireal-pro-playback-model), and some [follow-up works remains to be done](https://github.com/infojunkie/ireal-musicxml/issues/54).
+
+## Layout and styling information
+iReal Pro has a distinctive visual sheet style that aims to enhance readability. This converter attempts to recreate this visual style:
+- Using rhythmic notation or slash notation to display the chords
+- Increasing the size of noteheads and chord names
+- Removing uneeded elements from the score, such as clef and staff lines
+- Respecting the original positioning of measures to best reflect the structure of the song
+- Fitting the score on one page where at all possible
+
+MusicXML support for layout and style is expressive enough to represent all these customizations. Unfortunately, existing engraving software do not support the full set of MusicXML directives, thus recreating the intended style only partially. The (heavy-handed) solution is to go one additional step and [convert the MusicXML output from this present converter to the native format of the desired engraving software](https://github.com/infojunkie/ireal-musicxml/issues/16).
+
+## Backing track information
+The backing track patterns of the iReal Pro styles are not documented. Therefore, a mapping is done to support playing back the converted MusicXML scores that replicates or approximates the original iReal Pro playback. This is achieved in 2 phases:
 
-Check out the demos for example usage under `demo/`.
+  - First, the MusicXML `sound/play/other-play[@type = 'groove']` element is used to capture the playback style as specified in the iReal Pro song. Because MusicXML does not currently feature a dedicated element to specify the performance style, the generic `other-play` element was [selected to capture this information](https://github.com/w3c/musicxml/discussions/449).
 
-# Documentation
-- More information [about the iReal Pro format](doc/irealpro.md).
-- More information [about the MusicXML format](https://w3c.github.io/musicxml/).
+  - Next, the downstream playback component interprets the above MusicXML element to generate a backing track for the score. This is done in [`musicxml-midi`](https://github.com/infojunkie/musicxml-midi) which utilizes an extensive library of "grooves" to map the incoming iReal Pro style to MIDI accompaniment tracks.

lib/ireal-musicxml.d.ts → build/ireal-musicxml.d.ts

@@ -23,7 +23,7 @@ export class Playlist {
 export class Song {
   /**
    * Song parser. Parsing occurs in this constructor.
-   * Refer to https://github.com/infojunkie/ireal-musicxml/blob/main/doc/ireal.md for structure details.
+   * Refer to https://github.com/infojunkie/ireal-musicxml/blob/main/doc/irealpro.md for structure details.
    * @param ireal iReal Pro encoding for a single song
    * @param oldFormat Flag to indicate that the encoding above corresponds to the older irealbook:// format.
    */
@@ -162,15 +162,47 @@ export class ConversionOptions {
    */
   notehead?: string;
   /**
-   * Log level (default: Warn).
+   * Size of note head to use for the chord note (default: large).
+   * https://www.w3.org/2021/06/musicxml40/musicxml-reference/data-types/font-size/
+   */
+  noteheadSize?: string;
+  /**
+   * Whether to output encoding date (default: yes).
+   * https://www.w3.org/2021/06/musicxml40/musicxml-reference/elements/encoding-date/
+   */
+  date?: boolean;
+  /**
+   * Whether to display the clef (i.e. set its @print-object attribute) (default: no).
+   * https://www.w3.org/2021/06/musicxml40/musicxml-reference/elements/clef/
+   */
+  clef?: boolean;
+  /**
+   * Whether to display the key signature (i.e. set its @print-object attribute) (default: no).
+   * https://www.w3.org/2021/06/musicxml40/musicxml-reference/elements/key/
+   */
+  keySignature?: boolean;
+  /**
+   * Page width in millimeters (default: A4 = 210mm).
+   */
+  pageWidth?: number;
+  /**
+   * Page height in millimeters (default: A4 = 297mm).
+   */
+  pageHeight?: number;
+  /**
+   * Page margin in millimeters (default: 15mm).
+   */
+  pageMargin?: number;
+  /**
+   * Log level (default: LogLevel.Warn).
    */
   logLevel?: LogLevel;
 }
 
 /**
  * MusicXML converter.
  */
-export class MusicXML {
+export class Converter {
   /**
    * Default conversion options.
    */
@@ -195,6 +227,28 @@ export class MusicXML {
   convert(): string;
 }
 
+/**
+ * Package information.
+ */
+export class Version {
+  /**
+   * Package name.
+   */
+  static name: string;
+  /**
+   * Package version.
+   */
+  static version: string;
+  /**
+   * Package author.
+   */
+  static author: string;
+  /**
+   * Package description.
+   */
+  static description: string;
+}
+
 /**
  * Convert an iReal Pro playlist synchronously.
  * @param ireal iReal Pro playlist as HTML file contents or URI encoding