From 732eac123e2f7d20f8ba2eb92b698ed3ca57480c Mon Sep 17 00:00:00 2001 From: infojunkie Date: Mon, 21 Oct 2024 13:22:17 -0700 Subject: [PATCH] Update documentation --- README.md | 2 +- doc/irealpro.md | 193 ++++++++++++++++++++++++++++++------------------ 2 files changed, 122 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index 9b0ab47..0bd1d89 100644 --- a/README.md +++ b/README.md @@ -52,7 +52,7 @@ $ ireal-musicxml test/data/jazz.txt --songs=Blues --validate ``` # 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 [iReal Pro format](doc/irealpro.md) does not feature melody lines, only chords and backing styles. The conversion tries to produce a high-fidelity replica of the source sheet by recreating the following aspects of the iReal Pro format: +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): ## 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). diff --git a/doc/irealpro.md b/doc/irealpro.md index 3b613ae..f813f5d 100644 --- a/doc/irealpro.md +++ b/doc/irealpro.md @@ -4,10 +4,9 @@ - [iReal Pro File Format](https://www.irealpro.com/ireal-pro-file-format) - [`ireal-renderer`](https://github.com/daumling/ireal-renderer) -## Application model and playback algorithm - +## Application model - iReal Pro sheets are made of rows of cells -- Each cell can contain a chord and other music annotations such as barlines, time signature, repeats, etc. +- Each cell can be empty or can contain a chord and other music annotations such as barlines, time signature, repeats, etc. - A row contains exactly 16 cells and barlines can be placed on any cell - one cell does NOT correspond to one beat! - The iReal Pro sequencer generates a playback sequence and detects illegal input (e.g. too many chords in a bar) @@ -95,56 +94,53 @@ - Virtual Funk ## Key signatures -- C, Db, D, Eb, E, F, Gb, G, Ab, A, Bb, B -- A-, Bb-, B-, C-, C#-, D-, Eb-, E-, F-, F#-, G-, G#- +- Major: C, Db, D, Eb, E, F, Gb, G, Ab, A, Bb, B +- Minor: A-, Bb-, B-, C-, C#-, D-, Eb-, E-, F-, F#-, G-, G#- ## Cells - -- T44 - time signature 44 -- (N1|N2|N3)chord - first and second house (represents ONE BAR ONLY, see _I Got Rhythm_, _Like Someone in Love_, _On the Sunny Side of the Street_, _Misty_) -- XyQ - blank space for row alignment -- x - repeat previous bar (see _Butterfly_) -- Kcl or XyQKcl - also repeat previous bar (see _Besame Mucho_, _Butterfly_, _Solar_) -- r - repeat previous 2 bars (see _Mas Que Nada_) -- () - alternative chord written in small (above actual chord) -- " - represents a chord separator -- , - equivalent to space, especially for whole notes in 44 -- - Comments and repeat directives (can start with *yy to denote a vertical offset of yy units, see _La Fiesta_) -- *A - section A (could be *B, *C, *i, *v, etc.) -- S - segno (see _Butterfly_) -- Q - coda (see _Butterfly_) -- Y - vertical spacer (see _Nearness of You_, _Night in Tunisia_) -- U - end (see _Mas Que Nada_, _Scrapple from the Apple_, _Triste_, _Wave_) -- s - small chord (e.g. sC^7) -- l - large chord (e.g. lC^7) -- f - fermata (see _Butterfly_, _Summer Serenade_) +- `T44` - time signature 4/4 +- `(N1|N2|N3)chord` - first and second house (represents ONE BAR ONLY, see _I Got Rhythm_, _Like Someone in Love_, _On the Sunny Side of the Street_, _Misty_) +- `XyQ` - blank space for row alignment +- `x` - repeat previous bar (see _Butterfly_) +- `Kcl` or `XyQKcl` - also repeat previous bar (see _Besame Mucho_, _Butterfly_, _Solar_) +- `r` - repeat previous 2 bars (see _Mas Que Nada_) +- `()` - alternative chord written in small (above actual chord) +- `"` - represents a chord separator +- `,` - equivalent to space, especially for whole notes in 44 +- `` - Comments and repeat directives (can start with `*yy` to denote a vertical offset of yy units, see _La Fiesta_) +- `*A` - section A (could be `*B`, `*C`, `*i`, `*v`, etc.) +- `S` - segno (see _Butterfly_) +- `Q` - coda (see _Butterfly_) +- `Y` - vertical spacer (see _Nearness of You_, _Night in Tunisia_) +- `U` - end (see _Mas Que Nada_, _Scrapple from the Apple_, _Triste_, _Wave_) +- `s` - small chord (e.g. `sC^7`) +- `l` - large chord (e.g. `lC^7`) +- `f` - fermata (see _Butterfly_, _Summer Serenade_) ## Time signatures - -- 24 (2/4) -- 34 (3/4) -- 44 (4/4) -- 54 (5/4) -- 64 (6/4) -- 74 (7/4) -- 38 (3/8) -- 58 (5/8) -- 68 (6/8) -- 78 (7/8) -- 98 (9/8) -- 12 (12/8) -- 22 (2/2) -- 32 (3/2) +- `24` (2/4) +- `34` (3/4) +- `44` (4/4) +- `54` (5/4) +- `64` (6/4) +- `74` (7/4) +- `38` (3/8) +- `58` (5/8) +- `68` (6/8) +- `78` (7/8) +- `98` (9/8) +- `12` (12/8) +- `22` (2/2) +- `32` (3/2) ## Barlines - -- [ - start double barline -- ] - end double barline -- { - start repeat -- } - end repeat -- LZ - normal barline -- | - also normal barline (see _Au Privave_, _Stormy Weather_) -- Z - end double barline (that has a bolded second line) +- `[` - start double barline +- `]` - end double barline +- `{` - start repeat +- `}` - end repeat +- `LZ` - normal barline +- `|` - also normal barline (see _Au Privave_, _Stormy Weather_) +- `Z` - end double barline (that has a bolded second line) ## Comments and repeat directives - D.C. al Coda @@ -165,32 +161,85 @@ - 7x - 8x -## Chords -### Roots +## Chord roots Cb, C, C#, Db, D, D#, Eb, E, F, F#, Gb, G, G#, Ab, A, A#, Bb, B -### Inversions (aka bass notes) +## Chord inversions (aka bass notes) /Cb, /C, /C#, /Db, /D, /D#, /Eb, /E, /F, /F#, /Gb, /G, /G#, /Ab, /A, /A#, /Bb, /B -### Qualities - -- ^7, -7, 7, 7sus -- ^, -, 7alt, sus -- 6, -6, o7, ø7 -- ^9, -9, 9, 9sus -- ^13, -11, 13, 13sus -- 6/9, -6/9, -^7, -^9 -- ^7#11, ^9#11, -b6, -#5 -- ^7#5, add9, -7b5, ø9 -- 2, 5, +, o, ø -- 7b9, 7#9, 7b5, 7#5 -- 7b13, 7#11, 9#11, 13#11 -- 11, 7b9sus, 7b13sus, 7add3sus -- 9b5, 9#5, 13b9, 13#9 -- 7b9b13, 7b9#5, 7b9b5, 7b9#9 -- 7#9#5, 7#9b5, 7#9#11, 7b9#11 - -### Other possible chord values -- W - invisible chord (typically used to add a bass note, see _Butterfly_ ppsW/C) -- n - N.C. (see _Butterfly_) -- p - slash (repeat previous chord) +## Chord qualities indicators +- `^` - major +- `-` - minor +- `o` - diminished +- `ø` - hald-diminished +- `+` - augmented +- `b` - flat +- `#` - sharp + +## Chord qualities full list +- `^7` +- `-7` +- `7` +- `7sus` +- `^` +- `-` +- `7alt` +- `sus` +- `6` +- `-6` +- `o7` +- `ø7` +- `^9` +- `-9` +- `-9` +- `9sus` +- `^13` +- `-11` +- `13` +- `13sus` +- `6/9` +- `-6/9` +- `-^7` +- `-^9` +- `^7#11` +- `^9#11` +- `-b6` +- `-#5` +- `^7#5` +- `add9` +- `-7b5` +- `ø9` +- `2` +- `5` +- `+` +- `o` +- `ø` +- `7b9` +- `7#9` +- `7b5` +- `7#5` +- `7b13` +- `7#11` +- `9#11` +- `13#11` +- `11` +- `7b9sus` +- `7b13sus` +- `7add3sus` +- `9b5` +- `9#5` +- `13b9` +- `13#9` +- `7b9b13` +- `7b9#5` +- `7b9b5` +- `7b9#9` +- `7#9#5` +- `7#9b5` +- `7#9#11` +- `7b9#11` + +## Other chord values +- `W` - invisible chord (typically used to add a bass note, see _Butterfly_) +- `n` - N.C. (see _Butterfly_) +- `p` - slash (repeat previous chord)