Music notation (MusiXTeX/LilyPond)

The MusiXTeX manual opens by insisting on one thing: music is not a line of symbols the way prose is, it is a two-dimensional matrix. That single fact is why LaTeX, which sets mathematics so beautifully, cannot set sheet music without help. The horizontal position of a note is not fixed until you know how many bars fit on the line, and how many bars fit is not known until the notes have widths — a chicken-and-egg loop. This page follows MusiXTeX, which breaks that loop with a three-pass run; LilyPond, which answered the same problem by leaving TeX behind; and the compact ABC notation — including the blunt question of what your TeX Live actually ships and what it does not.

Why LaTeX alone cannot set music

The answer is that notes run down the page as well as across it. TeX's model is to line boxes up horizontally into a row, then stack rows into a page; that is enough for prose and for mathematics. A score, though, has several staves advancing at once, and the spacing between notes stretches or shrinks depending on how many bars you decide to put on a system. The MusiXTeX manual describes this as accumulating vertical combs horizontally, and its input works exactly that way: everything from \notes to \en is one comb, and inside it & separates the staves, counting up from the bottom instrument. LaTeX has no such machinery, which is why music always needs an extra layer.

That extra layer comes in two broad shapes. One is to stay inside TeX: add fonts and macros and let TeX itself engrave the music — this is MusiXTeX. The other is to step outside TeX: let a dedicated program engrave the score and pull the result back in as a picture with \includegraphics — this is what LilyPond and the ABC tools do. What makes the pair interesting is that they are historically connected: LilyPond began when two people who had set out to build a preprocessor for MusiXTeX abandoned that plan.

The three passes of MusiXTeX, and why musixflx sits in the middle

The standard route is three passes — etex → musixflx → etex — and the musixflx in the middle is not TeX at all but a separate program that does nothing but break lines. Step by step: on the first TeX pass, \startmuflex opens jobname.mx1 and writes out, bar by bar, how much hard space and how much stretchable space each bar contains. musixflx then reads that .mx1, decides how many bars go on each system, and writes the per-system stretch factors into jobname.mx2. On the third pass TeX reads both files, and only then is the final spacing fixed. The chicken-and-egg loop from the top of this page is broken by going out to a file and back.

You do not have to drive those three runs by hand. TeX Live ships a wrapper script called musixtex: type musixtex score.tex and it performs the three passes in order, then calls dvips and ps2pdf if needed. Adding -p takes the short route and produces PDF directly with pdfetex; adding -i keeps the intermediate .mx1 and .mx2 instead of deleting them — and if you open the .mx2, you will find lines like \lineset{1}{2}{...}, which is literally the decision "two bars on system one" written down. Note that musixflx in TeX Live is itself a texlua script, so this "separate program" runs on the Lua interpreter built into the TeX binary.

musixtex score.tex      # 3 passes: etex -> musixflx -> etex, then dvips + ps2pdf
musixtex -p score.tex   # same 3 passes, straight to PDF via pdfetex
musixtex -i score.tex   # keep score.mx1 and score.mx2 so you can read them
musixtex -1 score.tex   # single pass: fast draft, spacing NOT final

One trap: a PDF made with -1 (a single pass) has not had its systems laid out. It is fast and fine for checking work in progress, but never produce the version you hand in with -1. A second point: the engine MusiXTeX needs is not plain tex but e-TeX. That change was made in version 1.15 (April 2011) to escape a shortage of registers, and it is why the musixtex script invokes etex by default.

Why three passes? The answer is in MusiXTeX's own history. The chapter "A very brief history" in the bundled manual traces the idea of typesetting music with TeX back to around 1987 and a master's thesis at the University of Bonn by Andrea Steinbach and Angelika Schofer, Automatisierter Notensatz mit TeX. Their package, MuTeX, handled only a single staff, but it left two ideas behind: building beams and slurs out of a large number of font characters, and using TeX's glue to control horizontal spacing and justification. Around 1991 Daniel Taupin extended that to multiple staves as MusicTeX — at a price. Flexibility in horizontal spacing was lost, and avoiding excessive or insufficient gaps around bar lines became a matter of trial and error, because MusicTeX was single-pass. The only cure was to go multi-pass, and around 1997 Taupin, with Ross Mitchell and Andreas Egler, wrote the first MusiXTeX on exactly that conclusion. The musixflx sitting in the middle of your build is that decision, still standing.

Taupin was a physicist by profession. He died in a climbing accident in 2003 — the README and the manual's front matter shipped in TeX Live 2024 both say so. Maintenance has since passed to Don Simons, Hiroaki Morimoto and Bob Tennent. As for the musixflx in the middle, it began as a program Ross Mitchell wrote between 1992 and 1997; Nikhil Helferty rewrote it in Lua in 2011, and that rewrite is the musixflx.lua in use today.

A minimal MusiXTeX document, and why \begin{music} says "Undefined control sequence"

MusiXTeX has two input styles, a plain TeX one and a LaTeX one, and mixing them breaks. The plain TeX form, loaded with \input musixtex, has no \begin{music}: write it and you get ! Undefined control sequence. and, to add insult, the word "music" typeset as body text. The music environment is defined on the other side, in musixblx.tex — that is, in the LaTeX form loaded with \usepackage{musixtex}. The plain TeX skeleton looks like this: the music sits between \startpiece and \endpiece, that pair is wrapped in \startmuflex … \endmuflex, and the file ends with \bye.

% plain TeX form: run it with  musixtex -p score.tex
\input musixtex
\instrumentnumber{1}
\setclef1\treble
\generalmeter\meterC
\startmuflex
\startpiece
  \NOtes\qa{cdef}\en\bar
  \NOTes\ha{g}\en
\endpiece
\endmuflex
\bye

% LaTeX form: the music environment exists only here.
% Run it with  musixtex -p -l score-latex.tex
\documentclass{article}
\usepackage{musixtex}
\begin{document}
\begin{music}
  \instrumentnumber{1}
  \setclef1\treble
  \generalmeter\meterC
  \startpiece
    \NOtes\qa{cdef}\en\bar
    \NOTes\ha{g}\en
  \endpiece
\end{music}
\end{document}

A little vocabulary makes the rest readable. \NOtes … \en is one "comb", and the growing capitals — \notes, \Notes, \NOtes, \NOTes, \NOTEs — select the basic spacing that goes with a note value, widening as you go from sixteenth to whole. \qa{cdef} means "stemless quarter notes on c d e f", \ha{g} a stemless half note on g, and \bar is a barline. \instrumentnumber sets how many instruments there are, \setclef1\treble puts the first one in treble clef, and \generalmeter\meterC sets common time. Because the raw macros read like this, the preprocessors described next have become the input everyone actually writes.

pmx, M-Tx and autosp: not writing MusiXTeX by hand

The MusiXTeX manual itself says most tasks can be done entirely through a preprocessor, with no need to learn MusiXTeX's own commands or syntax. PMX for instrumental music and M-Tx for vocal music with lyrics are the two standards, and since the second feeds the first the chain is M-Tx → PMX → MusiXTeX. TeX Live 2024 ships the executables, though the names are a little perverse: the PMX program is pmxab and the M-Tx program is prepmx (with m-tx as an alias).

Helpfully, the musixtex script picks its entry point from the file extension. Hand it a .mtx and it starts at prepmx, a .pmx and it starts at pmxab, an .aspc and it starts at autosp — then runs through all three passes without further prompting. autosp is the preprocessor that automates choosing \notes / \Notes / \NOtes according to note values, so you never write those capitals by hand. And with xml2pmx you can enter from MusicXML, which is the route for material coming out of other notation software.

musixtex piece.pmx   # pmxab -> etex -> musixflx -> etex
musixtex song.mtx    # prepmx -> pmxab -> etex -> musixflx -> etex
musixtex draft.aspc  # autosp -> etex -> musixflx -> etex
musixtex score.xml   # xml2pmx -> pmxab -> etex -> musixflx -> etex
musixtex -m song.mtx # stop after producing the .pmx, to inspect or hand-edit

One more thing: the fonts are a separate package. MusiXTeX's note fonts are split out as musixtex-fonts, so installing only the macros will not compile. A normal TeX Live installation has both, but a minimal one will trip on this. Extensions ship alongside too — musixlyr.tex (Rainer Dunker) for lyrics, musixcrd (Robert Hennig) for chord symbols.

LilyPond with lilypond-book or lyluatex: calling an engraver outside TeX

LilyPond is a program entirely separate from TeX, with its own input language and the strongest reputation for engraving quality. Its starting point was MusiXTeX, which reads a little ironically today: Han-Wen Nienhuys and Jan Nieuwenhuizen began collaborating in 1995 on MPP (MusiXTeX PreProcessor), abandoned it, and started LilyPond in 1996. Version 1.0, in 1998, completed the separation from MusiXTeX, and LilyPond now writes PDF (via PostScript), SVG and PNG on its own. The two presented "LilyPond, a system for automated music engraving" at the 2003 Colloquium on Musical Informatics (CIM).

The standard way into a LaTeX document is lilypond-book. In a file with the extension .lytex you mix LaTeX prose with LilyPond fragments — short ones in \lilypond{…}, longer ones in a lilypond environment, external files via \lilypondfile{…} — and running lilypond-book over it renders each fragment with LilyPond and writes out an ordinary .tex file in which the fragments have become \includegraphics calls. You then compile that as usual. The line width of the music is matched automatically, read out of your preamble.

\documentclass{article}
\begin{document}
A short phrase:
\begin{lilypond}[quote,fragment,staffsize=26]
  c'4 d' e' f' g'2 g'
\end{lilypond}
\end{document}

lilypond-book --pdf score.lytex   # renders the fragments, writes score.tex
pdflatex score.tex                # compile the generated document

The newer option is lyluatex. Built for LuaLaTeX, it drops the preprocessing stage and calls LilyPond directly during the compile. Its native form is the ly environment (or \lily for a short fragment), and you simply start lualatex with --shell-escape. It also provides \lilypond and \lilypondfile for migrating away from lilypond-book, so an existing .lytex source carries over almost unchanged. With only one file to manage, drafts that go through many revisions get easier. TeX Live 2024 carries v1.1.5 (2023/04/18), under the MIT licence.

% compile with:  lualatex --shell-escape document.tex
\documentclass{article}
\usepackage{lyluatex}
\begin{document}
\begin{ly}
  \relative c' { c4 d e f g2 g }
\end{ly}
\end{document}

Here is the pitfall you must know about. The .sty for lyluatex is in TeX Live, but LilyPond itself (the lilypond command) and lilypond-book are not. Check the binary directory of a TeX Live 2024 installation and neither lilypond nor lilypond-book is there. So loading lyluatex on its own will not work: LilyPond has to be installed separately and put on your PATH. Having the package is a different thing from having the external program.

The abc package: folk tunes and single-line melodies, fast

ABC notation is a text music format designed above all to be readable and writable by a human, and it is widely used for folk tunes and lead sheets (single melodic lines) from Ireland, England, Scotland and beyond. One-letter headers — X:, T:, M:, L:, K: — carry the title, metre and key, and then you simply write out the notes, CDEF|GABc|. As notation it is plain, but it is light enough to paste into an email. The LaTeX side of it is the abc package (Enrico Gregorio; v2.0b in TeX Live 2024).

% compile with:  pdflatex -shell-escape tune.tex
\documentclass{article}
\usepackage{abc}
\begin{document}
\begin{abc}
X:1
T:Simple Tune
M:4/4
L:1/8
K:C
CDEF|GABc|
\end{abc}
\end{document}

Mechanically it works like lilypond-book: an external conversion. The package writes the body of the abc environment to a temporary file, hands it via \write18 (shell execution) to abcm2ps, which produces PostScript, then tidies that into EPS with ps2eps before including it. So -shell-escape is mandatory — and the same problem as LilyPond appears here too: abcm2ps is not in TeX Live. It is easy to end up with abc.sty present but no converter, so install abcm2ps before you rely on it (the mup option calls Mup instead). The classic abc2mtex, which converts ASCII ABC into MusicTeX/MusiXTeX input, likewise has to be obtained separately.

What TeX Live ships, what it does not, and which to choose

There is one rule of thumb. The tools that engrave inside TeX are all in TeX Live; the tools that engrave outside it are not. The MusiXTeX set (musixtex, musixflx, pmxab, prepmx, autosp, xml2pmx) and the LaTeX-side entry points (lyluatex.sty, abc.sty) are bundled. The external engines that actually draw the music — lilypond, lilypond-book, abcm2ps — are not. The table below records what a TeX Live 2024 installation actually contains.

From all of which, the practical decision. If you want no extra installation at all, or you know the machines that will build your document only have TeX Live, use MusiXTeX — but enter through pmxab / prepmx rather than writing raw macros. If engraving quality comes first, use LilyPond: lyluatex if you are already on LuaLaTeX, lilypond-book otherwise. For a few single-line tunes in a hurry, use abc. One lesson applies to all three: any setup that calls an external program (lyluatex, abc) needs -shell-escape, so check that it is permitted before you commit to it on a shared build machine or in CI. If what you want is the score as a standalone image to hand to another application, the TeX2img page covers that.