Sheet Music Builder

Render MusicXML files into printable sheet music.

Quick Start

uv sync                          # first-time setup
uv run python app.py build "inputs/It Could Happen To You.musicxml"

This writes outputs/It Could Happen To You.html and opens it automatically in your browser.

---

Input Format

The app accepts MusicXML files (.musicxml or .xml). These can be exported from:

• iReal Pro (lead sheets with chord symbols)
• MuseScore
• Sibelius / Finale
• Flat.io (free, browser-based)

MusicXML preserves all notation features: chord symbols, rehearsal marks, barline styles, clefs, key signatures, articulations, etc.

---

Output Formats

All output lands in the outputs/ folder by default.

Format	Flag	Description	How to open
HTML	--format html (default)	Self-contained page rendered with OpenSheetMusicDisplay	Opens automatically in your browser; or double-click the .html file
MusicXML	--format xml	Universal notation interchange format	MuseScore · Sibelius · Finale · Flat.io (free, browser-based)
MIDI	--format midi	Playback / DAW import	Windows Media Player · VLC · Any DAW (Reaper, Ableton, Logic, GarageBand)
PDF	--format pdf	Print-ready score	Any PDF viewer — requires MuseScore installed and configured

Viewing the HTML output

The HTML file is fully self-contained — no internet connection required after first load (OSMD is bundled via CDN on first open). To open manually:

# Windows
start outputs\my_song.html

# macOS
open outputs/my_song.html

# Linux
xdg-open outputs/my_song.html

Viewing MusicXML in the browser (free)

1. Go to flat.io → Import → upload the .musicxml file.
2. Or use MuseScore.com for online rendering.

---

CLI Reference

Usage: app.py build [OPTIONS] INPUT_FILE

Options:
  -o, --output PATH           Output file path (without extension)
  -f, --format [html|xml|midi|pdf]
                              Output format  [default: html]
  --open / --no-open          Auto-open HTML in browser  [default: open]
  -t, --tempo INTEGER         Override tempo (BPM)
  -k, --key TEXT              Override key, e.g. "Eb major"
  -ts, --time-sig TEXT        Override time signature, e.g. "3/4"
  --help                      Show this message and exit.

Examples

# Open as HTML in browser (default)
uv run python app.py build "inputs/It Could Happen To You.musicxml"

# Export MusicXML only
uv run python app.py build inputs/my_song.musicxml --format xml

# Export MIDI
uv run python app.py build inputs/my_song.musicxml --format midi

# Custom output path
uv run python app.py build inputs/my_song.musicxml --output exports/my_song

# Override metadata at the CLI
uv run python app.py build inputs/my_song.musicxml --tempo 90 --key "G major" --time-sig "3/4"

# Suppress auto-open
uv run python app.py build inputs/my_song.musicxml --no-open

---

Project Structure

.
├── app.py                  # CLI entry point
├── modules/
│   ├── parser.py           # MusicXML → MusicData (lightweight parse)
│   ├── converter.py        # MusicXML → music21 Score (full fidelity)
│   └── renderer.py         # Score → HTML / MusicXML / MIDI / PDF
├── inputs/                 # MusicXML source files
├── outputs/                # Generated sheet music (auto-created)
└── pyproject.toml