Skip to content
leouofaPublic

About

The PDF songbook generator for the masses.

Resources

Stars

4 stars

Watchers

1 watching

Forks

Latest commit

 

History

44 Commits

Folders and files

Repository files navigation

EvoX Logo

EvoX

Gem Version Ruby Prawn PDF Amazon KDP MCP Server License: MIT

EvoX is a rugged, elegant PDF songbook generator designed for musicians, jam sessions, and publishers. It transforms plain-text chord and lyric sheets into beautifully formatted, print-ready PDF songbooks that are fully Amazon KDP (Kindle Direct Publishing) compatible and ready for physical print. Complete with cover art, multi-column layouts, and an automated table of contents, your songbook is ready for print-on-demand right out of the box.


📖 Published in Print: Universal Songs

EvoX is battle-tested in physical print publishing!

The songbook Universal Songs by Leonid Eduardovich Medovyy was compiled, typeset, and published directly using EvoX.

Books generated by EvoX conform to Amazon KDP print specifications, allowing you to upload your compiled PDF directly to Amazon KDP for paperback distribution with zero manual reformatting.

"Music makes the world go round, and there's nothing better than a good jam session with friends. EvoX simplifies the publishing pipeline so you can focus on the music."


🤖 AI & Agent Integration: Model Context Protocol (MCP)

Supercharge your songbook workflow with AI. EvoX features an official Model Context Protocol (MCP) server:

👉 evox-mcp on GitHub

With evox-mcp, assistants like Claude Desktop, Cursor, and Antigravity can interactively:

  • Initialize and inspect songbook workspaces.
  • Parse, draft, and modify .evox song chord sheets with natural language.
  • Update cover layout metadata, headers, footers, and dimensions in config.yml.
  • Build the final book.pdf directly through agent tool calls.

✨ Features

  • Amazon KDP Compatible & Print-Ready: Generates high-resolution, print-compliant PDFs adhering to Amazon Kindle Direct Publishing (KDP) specifications with proper margins, gutters, and trim layouts.
  • Print-Ready PDF Generation: Built on top of Prawn with A4 layout and clean margins.
  • Customizable Cover Pages: Configurable title, subtitle, custom logo image, and attribution footer.
  • Multi-Column Layouts: Intelligently splits verses and choruses across balanced columns with custom gutter widths.
  • OpenSong-Inspired Syntax: Minimalist markup separating chords from lyrics for fast writing and easy sharing.
  • Automated Table of Contents: Generates an alphabetical index and dynamic page numbers (<page> of <total>).
  • Per-Song Typography Tuning: Custom font sizes and column dimensions on a per-song basis.

🚀 Quickstart

1. Installation

Install the gem via RubyGems:

gem install evox

2. Initialize a Songbook

Create a new directory and initialize the songbook scaffold:

mkdir my-songbook
cd my-songbook
evox init

This creates the project layout:

my-songbook/
├── book/                  # Destination for compiled PDFs
├── cover/
│   ├── config.yml         # Cover typography & logo settings
│   └── logo.png           # Cover artwork
└── songs/
    ├── free_falling.evox  # Song files (.evox)
    ├── i_dont_love.evox
    └── over_the_rainbow.evox

3. Generate the PDF

Compile your songbook:

evox generate

Your compiled book will be ready at book/book.pdf.


🛠️ CLI Reference

Command Description
evox init Initializes folder structure (book/, cover/, songs/) and copies starter templates
evox generate Builds book/book.pdf including cover, song pages, and table of contents
evox generate --skip-cover Generates the songbook with an empty page instead of the cover
evox howto Displays quick command-line instructions

🎼 The .evox Song Format

Songs are stored as .evox files in the songs/ folder and are printed alphabetically.

Metadata Header

Enclosed in double equals ==, YAML attributes define formatting per song:

==
name: Free Falling
author: Tom Petty
font: 9.0
column_width: 610
gutter: 5
==

Lyrics and Chords Syntax

Columns are wrapped in double dashes --.

  • Chords begin with a period (.): rendered in blue (#008AFF).
  • Lyrics begin with a space ( ): rendered in monospace courier.
  • Line breaks add comfortable vertical spacing.
--
.        C    F     F     C     G
 She's a good girl, loves her mama
.     C    F     F     C    G
 Loves Jesus and America too
.        C    F     F        C   G
 She's a good girl, crazy 'bout Elvis
.      C    F         F    C    G
 Loves horses and her boyfriend too
--

--
.       C    F        F     C   G
 It's a long day of livin' in Reseda
.          C    F    F       C          G
 There's a freeway runnin' through the yard
.          C    F             F     C     G
 And I'm a bad boy, 'cause I don't even miss her
.      C   F         F    C        G
 I'm a bad boy for breakin' her heart
--

🎨 Cover Configuration

Customize cover/config.yml to style your front page:

header:
  top_padding: 20
  title: 'The Great Book of Songs'
  title_size: 35
  subtitle: 'Version 0.5'
  subtitle_size: 15
  bottom_padding: 50
logo:
  image: logo.png
  width: 393.5
  height: 457
footer:
  title: 'Compiled by Leonid Medovyy'
  title_size: 25

🤝 Contributing

Bug reports, feature suggestions, and pull requests are welcome on GitHub at github.com/leouofa/evox.


📄 License

The gem is open source under the terms of the MIT License.

About

The PDF songbook generator for the masses.

Resources

Stars

4 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages