Menees.Chords
0.9.5-beta
Prefix Reserved
dotnet add package Menees.Chords --version 0.9.5-beta
NuGet\Install-Package Menees.Chords -Version 0.9.5-beta
<PackageReference Include="Menees.Chords" Version="0.9.5-beta" />
paket add Menees.Chords --version 0.9.5-beta
#r "nuget: Menees.Chords, 0.9.5-beta"
// Install Menees.Chords as a Cake Addin #addin nuget:?package=Menees.Chords&version=0.9.5-beta&prerelease // Install Menees.Chords as a Cake Tool #tool nuget:?package=Menees.Chords&version=0.9.5-beta&prerelease
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 6.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 IEntryContainer
s (e.g., Section
s).
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.
- ChordDefinitions - One or more chord definitions on a line (e.g.,
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
Document
s (and Entry
s) 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 Document
s can be formatted as text using one of the ContainerFormatter
-derived types:
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:
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.
- Console: The
.\Menees.Chords.Cli.exe
.NET console application is a thin wrapper over theMenees.Chords.dll
library. Run.\Menees.Chords.Cli.exe -help
to see its available options.
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
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 is compatible. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETFramework 4.8
- No dependencies.
-
.NETStandard 2.0
- No dependencies.
-
net6.0
- No dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
0.9.5-beta | 54 | 9/26/2024 |
0.9.4-beta | 174 | 3/26/2024 |
0.9.3-beta | 67 | 2/11/2024 |
0.9.2-beta | 54 | 2/11/2024 |
0.9.1-beta | 61 | 2/5/2024 |
0.9.0-beta | 145 | 12/3/2023 |
0.8.7-beta | 106 | 10/27/2023 |
0.8.5-beta | 82 | 10/18/2023 |
0.8.2-beta | 71 | 10/8/2023 |
0.8.1-beta | 82 | 10/1/2023 |
0.8.0-beta | 84 | 9/23/2023 |
0.7.5-beta | 102 | 9/12/2023 |
0.7.0-beta | 93 | 9/3/2023 |