Menees.Chords 1.2.2

Chords

This repo contains a .NET library and applications (e.g., an online Blazor WebAssembly app) for parsing, transforming, and reformatting chord sheets. It can parse files in human-friendly "chords over text" format (e.g., from Ultimate Guitar), machine-friendly ChordPro format, or a mix of both. For example, given this "chords over text" input:

[Verse 2]
D          G      C          G
 Bring him peace,  bring him joy,
C      Bm     Am      C      D
 He is young,   he is only a boy.

Running .\Menees.Chords.Cli.exe convert with that input produces this output in ChordPro format:

{start_of_verse: Verse 2}
[D] Bring him [G]peace, [C] bring him [G]joy,
[C] He is [Bm]young, [Am]  he is [C]only a [D]boy.
{end_of_verse}

Library

The Menees.Chords.dll .NET library is the main focus of this repo, and it contains all of the parsing, transforming, and formatting objects. It can be reused in any application targeting .NET Framework 4.8, .NET 8.0, or .NET Standard 2.0.

Code Example

// Parsing
Document inputDocument = Document.Load(inputFileName);

// Transforming
ChordProTransformer transformer = new ChordProTransformer(inputDocument);
Document outputDocument = transformer.Transform().Document;

// Formatting
ContainerFormatter formatter = new TextFormatter(outputDocument);
string outputText = formatter.ToString();

// Saving
File.WriteAllText(outputFileName, outputText);

Parsing

The Document class provides methods to Load chord sheet files and to Parse chord sheet text into an in-memory DOM. Document is similar to .NET's XDocument class except instead of XML nodes, Document represents a parsed chord sheet as a tree of Entry objects in IEntryContainers (e.g., Sections). The Entry-derived class hierarchy is:

• Entry - The abtract base for each item in Document.Entries.
  • ChordDefinitions - One or more chord definitions on a line (e.g., G 320033, G7 320001).
  • ChordLyricPair - Groups a ChordLine and a LyricLine together in a "chords over text" file.
  • ChordProDirectiveLine - A ChordPro directive (e.g., {title: Grey Street})
  • Section - An IEntryContainer of related entries (e.g., all lines in a chorus, or a ChordPro environment)
  • SegmentedEntry - The abstract base for an entry composed of multiple text segments (e.g., ChordPro lines with bracketed chords and unbracketed lyrics).
    • ChordLine - A line from a "chords over text" document that just contains chords (and maybe a few annotations).
    • ChordProLyricLine - A line from a ChordPro document that contains interlaced chords and lyrics.
  • TextEntry - The abstract base for a text entry that has a recognizable structure.
    • BlankLine - A line that's blank or was all whitespace and was trimmed to be blank.
    • ChordProGridLine - A line in a ChordPro grid environment.
    • ChordProRemarkLine - A #-prefixed ChordPro remark line (i.e., a comment for maintainers that's not displayed in rendered content).
    • Comment - A comment line that should be displayed in the rendered content.
    • HeaderLine - A bracketed header line that begins a section in "chords over text" format (e.g., [Verse 1]).
    • LyricLine - A line of lyrics (or anything that the parser couldn't match to another entry type).
    • TablatureLine - A tablature line, typically inside a ChordPro tab environment.

Chord sheets are parsed line-by-line. Parsing can be customized using the DocumentParser class with an ordered collection of specialized line parsers and groupers.

Transforming

Documents (and Entrys) are immutable after construction. The DocumentTransformer class provides a way to build a new in-memory Document by transforming an existing one. The primary transformer-derived types are:

• ChordProTransformer - Transforms "chords over text" (e.g., Ultimate Guitar) syntax into standard ChordPro syntax.
• MobileSheetsTransformer - A ChordProTransformer-derived type that restricts the output to a subset of ChordPro syntax compatible with the MobileSheets application.
• ChordOverLyricTransformer - Transforms standard ChordPro syntax into "chords over text" (e.g., Ultimate Guitar) syntax.

Formatting

In-memory Documents can be formatted as text using one of the ContainerFormatter-derived types:

• TextFormatter
• XmlFormatter

These are useful when saving chord sheets back into text files after transforming them to a new syntax.

Helpers

The library also contains some helper classes for specialized parsing situtations:

• Chord
• ChordDefinition
• Lexer

Applications

Web

The Menees Chord Sheet Converter web application converts Ultimate Guitar-style chords-over-text sheets into ChordPro format or MobileSheets format. The converter is a Blazor WebAssembly app, so it needs to be run in a modern, up-to-date web browser.

Because this is a WebAssembly app, it runs completely in your browser. It never sends any data to an external server. None of the information you enter into it leaves your brower, so it's safe to use it to convert private transcriptions.

Console

The .\Menees.Chords.Cli.exe .NET console application is a wrapper over the Menees.Chords.dll library. Run .\Menees.Chords.Cli.exe --help to see its available commands and options. This is also available as the menees-chords dotnet tool.

DotNet Local Tool

It can be installed as a local tool with:

dotnet tool install Menees.Chords.Cli --local

To run it as a local tool and see the convert command's help:

dotnet menees-chords convert --help

DotNet Global Tool

It can be installed as a global tool with:

dotnet tool install Menees.Chords.Cli --global

To run it as a global tool and see the convert command's help:

menees-chords convert --help

Note: The dotnet prefix isn't required (or supported) when running it as a global tool.

Others

Here are some links to similar software that might be of interest:

• ChordPro - The ChordPro format specification and reference app
• Ultimate Guitar Tablature Guide - Chords formatting rules
• Ultimate Guitar to ChordPro Converter - Web site for converting chord sheets
• ChordSheetJS - JavaScript chord sheet parser
• Konves.ChordPro - Older C# chord sheet parser
• Songpress - Windows and Linux app for chord sheet conversion and printing
• LaTeX Songs - Specification for rendering chord sheets via LaTeX type setting