chordscript 0.1.0

Add your description here

ChordScript

ChordScript is a plain-text markup language and parser for authoring and rendering musical chord charts. Designed for musicians, bandleaders, and music engravers, ChordScript allows you to write chord sheets in clean, human-readable plain text and automatically render them into beautiful, print-ready vector graphics (SVG).

---

Key Features

• Plain-Text Authoring: Simple, version-control-friendly syntax that anyone can read and write.
• Stunning SVG Output: Compiles plain text into high-quality, professional vector graphics using standard or custom music notation fonts (such as MuseJazz Text).
• Flexible Styling: Customize your chart layouts, column counts, colors, alignments, and fonts using simple JSON style definitions.
• Rich Musical Syntax:
  • Detailed metadata tracking (song title, artist, key, tempo, tuning, and custom fields).
  • Explicit rhythm patterns (e.g., {q q h}) and chord holds/diamonds (e.g., <Cmaj7>).
  • Performance articulations like pushes (<C), pulls (>C), chokes (!C), and ties (~).
  • Structural commands like inline repeats (|: and :|), voltas/alternate endings (| 1.), and measure repeats (%).
  • Multi-line lyrics blocks wrapped in quotes ("...").

---

Getting Started

Prerequisites

• Python: >= 3.13
• uv (recommended package installer) or pip

Installation

Clone the repository and install the project along with its dependencies:

# Clone the repository
git clone https://github.com/your-username/chordscript.git
cd chordscript

# Install dependencies and project using uv (recommended)
uv pip install .

# Or install using standard pip
pip install .

---

Command Line Interface (CLI)

ChordScript provides a user-friendly CLI to process your files.

1. Process Chord Files

Compile .chords files into vector graphics (SVG):

# Process a single file to SVG (default format)
uv run chordscript process songs/Wonderwall.chords -o output/

# Process files with a specific style (e.g., jazz)
uv run chordscript process songs/*.chords -s jazz -o output/

2. List Styles

View the available styles defined in your directory:

uv run chordscript styles

3. List Fonts

Display the font families, weights, and styles detected on your system:

uv run chordscript fonts

4. Sync Files

Synchronize files between two folders (e.g., local work folder and external backup/cloud folder):

uv run chordscript sync <input_dir> <output_dir>

---

Syntax Guide

A ChordScript file is divided into metadata, section headers, chords, and lyrics.

1. Metadata

Declared at the top of the file using @key: value:

@title: Wonderwall
@artist: Oasis
@key: F#m
@meter: 4/4
@tempo: 120 (Moderate)
@tuning: Standard

2. Sections

Sections define parts of the song (e.g., Verse, Chorus) and start with $:

$ Intro * 2
$ Verse 1
$ Chorus

3. Chords & Measures

• Basic Chords: Standard roots (A to G) with accidentals (# / b) and extensions: C, F#m7, G/B, C9, C7(b9).
• Measure Separation: Chords separated by spaces/tabs belong to separate measures.
• Split Measures: Group multiple chords inside a single measure using parentheses: (C G) (Am F).
• Rests: Use _ for a blank measure or rest.

4. Rhythms & Articulations

• Explicit Rhythms: Curly braces {} preceding a measure define note lengths: {q q h} C G Am (Quarter, Quarter, Half).
• Holds (Diamonds): Hold a chord for its full duration using < >: <Cmaj7>.
• Pushes & Pulls: Accentuate entry using < (push) or > (pull): <C or >C.
• Chokes: Staccato cut-offs are prefixed with !: !C.
• Ties: Standalone tildes ~ tie measures across bars: C | ~ | D.

5. Repeats & Alternating Endings

• Inline Repeats: Enclose repeated structures with |: and :|.
• Voltas (Alternate Endings): Define endings using | 1. or | 2.:

  |: C F | 1. G :| 2. C ||
  

• Measure Repeats: Repeat the preceding measure using %.
• Block Multipliers: Repeat entire groups: 4 * [ Bb5 ].

6. Lyrics

Lyrics are enclosed in double quotes " and can span multiple lines:

$ Verse 1
C                G
"Today is gonna be the day"
             D                 A
"That they're gonna throw it back to you"

---

Example ChordScript Sheet

Below is a complete, minimal example of a ChordScript (.chords) file:

@title: Example Song
@artist: Jane Doe
@key: G Major
@meter: 4/4
@tempo: 120

$ Intro
G C D G

$ Verse 1
G                C
"This is the first line of lyrics"
                 D                G
"And here is the second line of text"

$ Chorus
|: G D | 1. C G :| 2. C D ||
"This is the chorus that repeats
With some different endings"

---

Styling your Charts

ChordScript supports customization through JSON-based style sheets located in the styles/ folder (such as styles/jazz.json or styles/nns.json). These style configurations allow you to control:

• Font families for headers, sections, chords, comments, and lyrics.
• Column structures (e.g., single or double-column layouts).
• Custom abbreviation maps for section headers.
• Background and foreground colors, sizing, and margins.

---

Contributing

Contributions are welcome! Please ensure any new features or syntax enhancements include accompanying tests under the relevant directories, and respect the codebase's separation of concerns (keeping parser AST and rendering writers decoupled).

License

This project is open-source. For licensing details, please refer to the project repository.