Microtonality in Lilypond

Lilypond is a piece of free software that produces printable notation and MIDI files from text input. There are graphical editors that work with it. It can be extended on the fly using Scheme code, and it has a flexible tuning model, so it can be adapted to work with different microtonal notations. It's the best tool currently available for notation-centric microtonal composition. (The ABC tool chain has similar capabilities and limitations.)

How to Use It

There are different ways that microtonal notation requires special support. The pitch names can refer to different pitches, and you may define new pitch names that lie outside conventional notation. You may need more or different accidentals, and they'll apply to new pitch shifts. The notation may not be based on the traditional 7 note scale. You may want to use different notation systems for different purposes. Lilypond can help in all these areas.

Quick Start

Download regular.ly. Place it somewhere Lilypond can find it (probably the same folder as the files you're compiling). Add this near the top of your file (after any language setting):

tuning = #31
\include "regular.ly
With a recent version of Lilypond, this will give you a MIDI file tuned to 31 note equal temperament with pitch bends. (The visual appearance of the score should be unchanged.)

This script is good enough for any tuning based on a single chain of fifths. Primarily, that means Meantone but also Schismatic and Mavila. In fact, because of Lilypond's support for quartertones, it covers chains of neutral thirds, like Mohajira.

MIDI Output

Lilypond will tune your microtonal music using pitch bends. They work, but require each independent melodic line to be on a separate MIDI channel (usually a separate Staff and don't work with chords. Lilypond's implementation also resets the pitch bend at the end of a note, while its decay is still sounding.

To get around these problems, I wrote a Python script to convert the pitch bends to real time MIDI Tuning Standard (MTS) messages. You can download the script for Python 3 or a suitably recent Python 2. To run it, open your favorite command prompt in the folder your MIDI file lives in and run either

python3 addmts.py3 masterpiece.midi masterpiece-mts.midi
python addmts.py masterpiece.midi masterpiece-mts.midi
You may even find that drag-and-drop works in a graphical file manager.

The script uses a dumb search and replace method based on regular expressions. It works because the Lilypond developers were smart enough to implement pitch bends in a sufficiently dumb way that it's easy to reverse engineer them. Of course, we all know that regular expressions are no substitute for a true parser. Parsing the MIDI file wouldn't be that difficult, but it's still harder than using regular expressions, so I didn't bother. So there. Because of the syntax of MIDI files, it's very unlikely that one will contain something that looks like a note-on message but isn't. It's even less likely that Lilypond would produce such a file but I haven't proved it impossible. If you ever find one, this script won't work with it.

The Pitch Model

Pitches in Lilypond are a combination of the position on the staff, and the alteration relative to the nominal at that position, as a rational fraction of a 200 cent whole tone. Pitch names repeat every 1200 cent octave. You can create a pitch with ly:make-pitch and find out about an existing pitch with ly:pitch-octave, ly:pitch-notename, and ly:pitch-alteration. There's also ly:pitch-steps, which is a combination of ly:pitch-octave and ly:pitch-notename, and ly:pitch-semitones which can be risky in a microtonal context.

Each pitch name corresponds to an object in this format. You can define your own names to correspond to whatever pitches you like. (There are restrictions on what names are valid. I stick with the English alphabet.) You set the new names with ly:parser-set-note-names. Any music you write afterward that will use these names.

The old language files were good examples of how to define pitch names. They've all been consolidated in /usr/share/lilypond/current/scm/define-note-names.scm but you can still see the Scheme lists you need in that file.


When it needs to print an accidental, Lilypond looks in an associative list to find a glyph to represent it. This list (like a dictionary) produces a glyph given the alteration. Whether or not you want new accidentals, you need a new associative array for microtonal tunings. (Lilypond supports quartertones out of the box.)

As an example, the standard accidental glyphs are defined in ... and look something like this:

    ;; ordered for optimal performance.
    (0 . "accidentals.natural")
    (-1/2 . "accidentals.flat")
    (1/2 . "accidentals.sharp")

    (1 . "accidentals.doublesharp")
    (-1 . "accidentals.flatflat")

    (3/4 . "accidentals.sharp.slashslash.stemstemstem")
    (1/4 . "accidentals.sharp.slashslash.stem")
    (-1/4 . "accidentals.mirroredflat")
    (-3/4 . "accidentals.mirroredflat.flat"))

Once you've defined your new set of accidentals, you apply them with code like this:

\layout {
  \context {
    \override Accidental #'glyph-name-alist = \newglyphs
    \override KeySignature #'glyph-name-alist = \newglyphs
    \override AccidentalCautionary #'glyph-name-alist = \newglyphs
    \override TrillPitchAccidental #'glyph-name-alist = \newglyphs
    \override AmbitusAccidental #'glyph-name-alist = \newglyphs

The glyph names refer to the standard Lilypond fonts. It is possible to use third party fonts, like Sagittal but that involves Scheme code. For an example, see Tripod Notation.

The Default Scale

The tuning of the nominals, the pitches you get with no alterations, is determined by the default scale. You set it, reasonably enough, with ly:set-default-scale. The scale you pass in is produced by ly:make-scale. That takes a vector of pitches specified as a fraction of a 200 cent whole tone. (The same units you use for alterations.)

The pitches of the default scale apply to the MIDI tuning. The default scale is also important because it determines the number of scale degrees to an octave. Because of this, you have to set the correct default scale before you define note names based on it. You also have to have the right default scale active for a given staff (that is, Staff). It is possible to have more than one default scale active in different parts of a scale, so that you can write music in one pitch system and write a Scheme function to convert it to a completely different system.

Lilypond also has a staffLineLayoutFunction for defining chromatic scores. You can use this to define a notation with other than 7 degrees to the octave, instead of changing the default scale, but it doesn't work properly with accidentals. (Chromatic scores don't have accidentals.)


You might use a standard MIDI keyboard to play music in an alternative tuning. The score for such an instrument can be in standard notation, where the pitches tell you which key to press and lose there usual association with the sound that comes out. This is related to scordatura, and treats staff notation as a keyboard tablature. Hence I call it scordablature.

Scordablature is also useful in MIDI output. It means you can play the files using a synthesizer that supports tuning tables. You can edit such a file in a sequencer and not have to worry about the pitch bends or MTS messages getting out of synch with the notes they apply to. You may have a MIDI file you recorded with a retuned keyboard and want Lilypond to turn it into a presentable score in a microtonal notation.

Lilypond can work with scordablature, but you have to lie to it. You have to tell it you're using standard notation with 12 note equal notation, and hope it doesn't notice that what you've written makes no sense. You can define your own pitch names but, in the likely event that you want more than 12 distinct pitches to the octave, you need to run a Scheme function to convert them to the deceitful mapping you want to sneak past Lilypond.

For an example of this, see scordablature.ly. It's designed to replace regular.ly so that you can change from one to the other to change from retuned output to scordablature. (Don't try to include both of them in the same file. That won't work.) Use the \retune function to convert a voice to scordablature. You need to tell it the equal temperament to tune to and the MIDI pitch number you want middle C to map to. For example \retune #19 #60 \somemusic will retune to 19 note equal temperament with middle C held constant, and \retune #12 #60 \somemusic will do nothing at all useful.

You may want to remap the MIDI output, but leave the printed score untouched. You can do that like this, using a content variable with the music to retune and tuning set like you would for regular.ly:

\score {
  \new Staff \content
\score {
  \new Staff \retune #tuning #60 \content

Just Intonation

Sagittal EDA Notations

You can write music in just intonation and display it using Sagittal Athenian or Promethean notation based on equal divisions of the apotome (EDA) and, in the Promethean case, a few exceptions. You can get the source code you need, including an example of just intervals and a musical example in this zip file.

At the top of the file, add either

\include "athenian.ly"
or (for higher precision)
\include "promethean.ly"
and write pitch names using the language you already set. The default tuning is Pythagorean. To raise a pitch by a syntonic comma, write
\raise #81/80
and to lower it, write
\lower #81/80
before the note name. To set b to a harmonic seventh above c, write
\tonic c \tune #7/4 b

There are \pure and \mixed commands to choose the accidental types. You can add cents indications with \centsUp or \centsDown. They aren't properly ordered in the example but they should be fine with a single line per staff.

Sagittal Trojan Notations

Two equal divisions of the equally tempered semitone are currently supported for just intonation input. Use

\include "trojan72.ly"


\include "trojan72.ly"

and otherwise follow the instructions above for EDAs.

Tripod Notation

Tripod Notation is a crazy idea of mine that's so strange it works as a good demonstration of Lilypond's microtonal functionality. I don't have time to explain it all here. You may wish to study the source code.


Here are some examples taken from Mutopia. I cleaned them up to run with recent versions of Lilypond (2.12.3 with the key signatures patch and hopefully 2.14.1) as well. I added articulate.ly support along with the tuning.

Mike Battaglia has some audio for startlingly similar pieces in Mavila.

As exact realizations of meantone temperaments, they're important to different people. For scholars, they show what a literal meantone performance would sound like, without the constraints of 12 note keyboards. They show what does and doesn't work in meantone and indicate how tuning influenced the rules of harmony and spelling. For composers, comparing different tunings gives an idea of the moods each tuning gives, and how the same material can be interesting when presented in different tunings. For casual listeners, they can be enjoyable to listen to, with the novel tunings making up for the obvious shortcomings of the performances.

Where there's a single movement with a single Lilypond file, I link to that. If there's more than one movement, you get a zip archive with some MIDI files as well, in case you don't want to run Lilypond to produce them yourself. You'll still need a General MIDI file player with MTS support. (Probably Timidity.)


I think Schubert's a good demo for extended meantone because he was skillful and adventurous with his harmony, but kept within a tonal framework. I know some people have produced good results by applying adaptive temperament algorithms (even up to the 7-limit) and there's a sense to that, because he was well into the era of circulating temperaments. It's still interesting to hear tunings based on the written notes, though.

All these pieces are rendered well in MIDI (by one Ph. Raynaud), including dynamics. The Lilypond files are also a true example of the EEC harmony I was indoctrinated in as a child. The note names are Italian, the comments are in French, the title's in German, and the Lilypond commands are in English.

Impromptus D935
I used the first one of these as a test for a range of different temperaments. It's also marked up for scordablature. You get all the MIDI files in the zip. It's a good example because it covers a reasonable chromatic range, and gives xenharmonic effects even in mainstream meantones. All the spellings look correct, in that there's a logic behind them, and no enharmonics seem to be used to simplify the notation.
Impromptus D899
More of the same.
Quartet movement D703
String quartets should work with pitch bend tuning, but I don't have good enough soundfonts to really do them justice.


Although he's famous for advocating circular temperaments, most of Bach's music works fine in quarter comma meantone provided you have enough notes.

Ricercare 6 (the famous one) from the Musical Offering.
Should be a good test for extended meantone, and I can't spot any wrong notes. Maintained by Arnaud Gossart.
Invention 1 BWV 772
Two part piece, would work with pitch bends. Maintained by Jeff Covey.
Invention 13 BWV 784
Two parts again. Entered by Allen Garvin.


Rondo Alla Turca (K331 movement 3)
Fast enough to make up for the mechanical performance. Maintained by Rune Zedeler and Chris Sawer.


Moonlight Sonata (Sonata No. 14, Op. 27, No. 2)
Maintained by Stewart Holmes.