Overview

Relevant source files

Purpose and Scope

This document provides a high-level introduction to the sheetmusic repository, a multi-format sheet music conversion system. It covers the system's architecture, core components, file organization, and processing workflow. For detailed information about specific subsystems:

For the conversion pipeline implementation, see Conversion Pipeline
For dependency installation and version requirements, see Dependencies and Setup
For helper script internals, see Helper Scripts
For input/output format specifications, see Input Formats and Output Formats

Sources: README.md1-13 ly-to-all.sh1-63

System Purpose

The sheetmusic repository transforms LilyPond musical notation source files (.ly) into six distribution formats optimized for different consumption scenarios: web display, printing, audio playback, and video embedding. The system executes a deterministic conversion pipeline via the ly-to-all.sh script, producing vector graphics, raster images, MIDI data, and multiple audio/video encodings from a single source file.

The repository includes three complete example songs (row, twinkle, happy) demonstrating the full asset generation workflow. All output files are versioned in git (except intermediate .wav files) and accessible via CDN (jsDelivr), enabling direct browser access to rendered sheet music and audio.

Sources: README.md1-6 ly-to-all.sh1-63

High-Level Architecture

System Architecture Diagram

The system follows a single-pass batch processing model where ly-to-all.sh orchestrates all external tools in a fixed sequence. The pipeline splits into two parallel tracks after initial LilyPond compilation: visual processing (SVG → WebP) and audio processing (MIDI → WAV → Opus → WebM).

Sources: ly-to-all.sh1-63

Core Components

Component Interaction Map

Sources: ly-to-all.sh20-62 package.json

Component Responsibilities

Component	Type	Primary Function	Key Operations
`ly-to-all.sh`	Bash script	Pipeline orchestration	File iteration, tool invocation, intermediate file management
`midi-len.js`	Node.js script	Duration calculation	MIDI parsing, tick-to-second conversion
`svg-bg.js`	Node.js script	SVG modification	XML DOM manipulation, white background injection
`lilypond`	External binary	Music engraving	`.ly` → `.svg` + `.mid` compilation
`fluidsynth`	External binary	Audio synthesis	MIDI + soundfont → WAV rendering
`ffmpeg`	External binary	Audio/video encoding	WAV trimming, Opus encoding, WebM muxing
`rsvg-convert`	External binary	Rasterization	SVG → WebP at 2160px width
`FluidR3_GM.sf2`	Data file	Instrument samples	GM-compatible soundfont for synthesis

Sources: ly-to-all.sh1-63

Repository Structure

File Organization

sheetmusic/
├── ly-to-all.sh          # Main conversion pipeline
├── midi-len.js           # MIDI duration extractor
├── svg-bg.js             # SVG background setter
├── package.json          # Node.js dependencies
├── README.md             # Repository documentation
├── LICENSE-CC0-1.0       # Public domain license
├── LICENSE-0BSD          # Zero-clause BSD license
├── .gitignore            # Excludes *.wav and FluidR3_GM.sf2
│
├── row/                  # "Row, Row, Row Your Boat"
│   ├── row.ly            # LilyPond source
│   ├── row.musicxml      # MusicXML export
│   ├── row.svg           # Vector graphics output
│   ├── row.webp          # Raster image output
│   ├── row.mid           # MIDI output
│   ├── row.opus          # Opus audio output
│   └── row.webm          # WebM video output
│
├── twinkle/              # "Twinkle, Twinkle, Little Star"
│   ├── twinkle.ly
│   ├── twinkle.musicxml
│   ├── twinkle.svg
│   ├── twinkle.webp
│   ├── twinkle.mid
│   ├── twinkle.opus
│   └── twinkle.webm
│
└── happy/                # "Happy Birthday to You"
    ├── happy.ly
    ├── happy.musicxml
    ├── happy.svg
    ├── happy.webp
    ├── happy.mid
    ├── happy.opus
    └── happy.webm

Each song directory contains a complete asset set: one source file (.ly), one optional interchange format (.musicxml), and six generated outputs. The directory structure enables self-contained distribution and CDN hosting via jsDelivr, as indicated by the badge in README.md.

Sources: ly-to-all.sh22-24 README.md3

Processing Workflow

Sequential Pipeline Stages

The ly-to-all.sh script processes each .ly file through ten sequential stages:

Sources: ly-to-all.sh22-62

Stage Details

Stage	Tool/Script	Input	Output	Purpose
1	`lilypond`	`file.ly`	`file.svg`, `file.mid`	Compile musical notation to graphics and MIDI
2	`npx svgo`	`file.svg`	`file.svg` (optimized)	Remove unnecessary SVG elements
3	`rsvg-convert`	`file.svg`	`file.webp`	Rasterize at 2160px with white background
4	`svg-bg.js`	`file.svg`	`file.svg` (modified)	Insert white background rectangle
5	`xmllint`	`file.svg`	`file.svg` (formatted)	Format XML with UTF-8 encoding
6	`fluidsynth`	`file.mid`, `FluidR3_GM.sf2`	`file.wav`	Synthesize audio from MIDI
7	`midi-len.js`	`file.mid`	duration value	Calculate exact playback duration
8	`ffmpeg`	`file.wav`, duration	`file.tmp.wav` → `file.wav`	Trim to exact duration
9	`ffmpeg`	`file.wav`	`file.opus`	Encode to Opus codec
10	`ffmpeg`	`file.opus`, duration	`file.webm`	Mux with 256×144 black video

Sources: ly-to-all.sh27-61

Version Requirements

The system requires specific versions of external tools, as documented in ly-to-all.sh5-13:

Tool	Required Version	Purpose
`lilypond`	2.24.4	Music notation compiler
`librsvg` (rsvg-convert)	2.61.3	SVG to raster converter
`libxml2` (xmllint)	2.15.1	XML formatter
`fluidsynth`	2.5.2	MIDI synthesizer
`ffmpeg`	8.0.1	Audio/video encoder
`node`	25.5.0	JavaScript runtime

These version constraints suggest the pipeline was developed for a controlled environment. Version mismatches may cause compilation errors or output format incompatibilities. For detailed installation instructions, see Dependencies and Setup.

Sources: ly-to-all.sh5-13

Output Format Summary

The pipeline generates six output formats from each .ly source file:

Format	File Extension	Use Case	Generation Method
SVG	`.svg`	Print, web display (scalable)	LilyPond → svgo → svg-bg.js → xmllint
WebP	`.webp`	Web display (optimized raster)	SVG → rsvg-convert at 2160px
MIDI	`.mid`	Musical data, playback control	LilyPond direct output
WAV	`.wav`	Intermediate audio (not in git)	MIDI → fluidsynth → ffmpeg trim
Opus	`.opus`	Audio streaming	WAV → ffmpeg libopus
WebM	`.webm`	Video platforms, browser embed	Opus + synthetic black video

The WebM format (256×144 resolution, black screen) serves as a video container for Opus audio, enabling compatibility with platforms that handle video better than standalone audio files. For detailed format specifications, see Output Formats.