![]() |
GNU LilyPondUser Manual |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
This document is also available in gzipped PostScript and PDF. This file documents GNU LilyPond. Copyright 1999-2002 by the authors Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections. A copy of the license is included in the section entitled "GNU Free Documentation License". GNU LilyPond -- The music typesetterThis is the user manual for GNU LilyPond 1.6.0. A further source of information is the website, which can be found at http://www.lilypond.org/. The website contains on-line copies of this and other documentation. We would like to dedicate this program to all the friends that we met through music. Table of Contents
PrefaceIt must have been during a rehearsal of the EJE (Eindhoven Youth Orchestra), somewhere in 1995 that Jan, one of the cranked violists told Han-Wen, one of the distorted French horn players, about the grand new project he was working on. It was an automated system for printing music (to be precise, it was MPP, a preprocessor for MusiXTeX). As it happened, Han-Wen accidentally wanted to print out some parts from a score, so he started looking at the software, and he quickly got hooked. It was decided that MPP was a dead end. After lots of philosophizing and heated e-mail exchanges Han-Wen started LilyPond in 1996. This time, Jan got sucked into Han-Wen's new project. In some ways, developing a computer program is like learning to play an instrument. In the beginning, discovering how it works is fun, and the things you can't do are challenging. After the initial excitement, you have to practice and practice. Scales and studies can be dull, and if you aren't motivated by others--teachers, conductors or audience--it is very tempting to give up. You continue, and gradually playing becomes a part of your life. Some days it comes naturally, and it's wonderful, and on some days it just doesn't work, but you keep playing, day after day. Like making music, working on LilyPond is can be dull work, and on some days it feels like plodding through a morass of bugs. Nevertheless, it has become a part of our life, and we keep doing it. Probably the most important motivation is that our program actually does something useful for people. When we browse around the net we find many people that use LilyPond, and use it to produce impressive pieces of sheet music. Seeing that still feels unreal, but in a very pleasant way. Our users not only give us good vibes by using our program, many of them also help us by giving suggestions and sending bugreports. So first and foremost, we would like to thank all users that sent us bugreports, gave suggestions or contributed in any other way to LilyPond. We would also like to thank the following people: Mats Bengtsson for the incountable number of questions he answered on the mailing list, and Rune Zedeler for his energy in finding and fixing bugs. Nicola Bernardini for inviting us to his workshop on music publishing, which was truly a masterclass, and Heinz Stolba and James Ingram for teaching us there. Playing and printing music is more than nice analogy: programming together is a lot of fun, and helping people is deeply satisfying, but ultimately, working on LilyPond is a way to express our deep love for music. May it help you create lots of beautiful music! Han-Wen and Jan Utrecht/Eindhoven, The Netherlands, July 2002. IntroductionLilyPond is a program to print sheet music. If you have used notation programs before, then the way to use this program might be surprising at first sight. To print music with lilypond, you have to enter musical codes in a file. Then you run LilyPond on the file, and the music is produced without any further intervention. For example, something like this: \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4 produces this Encoding music using letters and digits may appear strange, intimidating or even clumsy at first. Nevertheless, when you take the effort to learn the codes and the program you will find that it is easier than it seems. Entering music can be done quickly, and you never have to remember how you made the program do something complicated: it's all in the input code, and you only have to read the file to see how it works. Moreover, when you use LilyPond, you are rewarded with very nicely looking output. In this chapter, we will explain the reasoning behind this unusual design, and how this approach affects you as a user. Batch processingWhen we started developing LilyPond, we were still studying at the university. We were interested in music notation, not as publishers or musicians, but as students and scientists. We wanted to figure to what extent formatting sheet music could be automated. Back then GUIs were not as ubiquitous as they are today, and we were immersed in the UNIX operating system, where it is very common to use compilers to achieve computing tasks, so our computerized music engraving experiment took on the form of a compiler. You can freely use, modify and redistribute LilyPond. This choice was also motivated by our academic background. In the scientific community it has always been a tradition to share knowledge, also if that knowledge was packaged as software. One of the most visible groups that stimulated this philosophy, was the Free Software Foundation, whose popular GNU project aimed to replace closed and proprietary computing solutions with free (as in "Libre") variants. We jumped on that bandwagon, and released LilyPond as free software. That is the reason that you can get LilyPond at no cost and without any strings attached. Music engravingMaking sheet music may seem trivial at first ("you print 5 lines, and then put in the notes at different heights"), music engraving, i.e. professional music typography, is in another ballpark. The term `music engraving' derives from the traditional process of music printing. Only a few decades ago, sheet music was made by cutting and stamping the music into zinc or pewter plates, mirrored. The plate would be inked, and the depressions caused by the cutting and stamping would hold ink. A positive image was formed by pressing paper to the plate. Stamping and cutting was completely done by hand. Making corrections was cumbersome, so engraving had to be done correctly in one go. As you can imagine this was a highly specialized skill, much more so than the traditional process of printing books. The following fact illustrates that. In the traditional German craftsmanship six years of full-time training, more than any other craft, were required before a student could call himself a master of the art. After that many more years of practical experience were needed to become an established music engraver. Even today, with the use of high-speed computers and advanced software, music requires lots of manual fine tuning before it acceptable to be published. When we wanted to write a computer program to do create music typography, we encountered the first problem: there were no sets of musical symbols available: either they were not available freely, or they didn't look well to our taste. Not let down, we decided to try font design ourselves. We created a font of musical symbols, relying on nice printouts of hand-engraved music. It was a good decision to design our own font. The experience helped develop a typographical taste, and it made us appreciate subtle design details. Without that experience, we would not have realized how ugly the fonts were that we admired at first. The figure above shows a few notable glyphs. For example, the half-notehead is not elliptic but slightly diamond shaped. The vertical stem of a flat symbol should be slightly brushed, i.e. becoming wider at the top. Fine endings, such as the one on the bottom of the quarter rest, should not end in sharp points, but rather in rounded shapes. Taken together, the blackness of the font must be carefully tuned together with the thickness of lines, beams and slurs to give a strong yet balanced overall impression. Producing a strong and balanced look is the real challenge of music engraving. It is a recurring theme with many variations. In spacing, the balance is in a distribution that reflects the character of the music. The spacing should not lead to unnatural clusters of black and big gaps with white space. The distances between notes should reflect the durations between notes, but adhering with mathematical precision to the duration will lead to a poor result. Shown here is an example of a motive, printed twice. It is printed using both exact, mathematical spacing, and with some corrections. Can you spot which is which? The fragment that was printed uses only quarter notes: notes that are played in a constant rhythm. The spacing should reflect that. Unfortunately, the eye deceives us a little: the eye not only notices the distance between note heads, but also between consecutive stems. The notes of a up-stem/down-stem combination should be put farther apart, and the notes of a down-up combination should be put closer together, all depending on the combined vertical positions of the notes. The first two measures are printed with this correction, the last two measures without. The notes in the last two measures form downstem/upstems clumps of notes. We hope that these examples show that music typography is a subtle business, and that it requires skill and knowledge to produce good engraving. It was our challenge to see if we could put such knowledge into a computer program. Music representationOne of the big questions when making programs, is what kind of input the program should expect. Many music notation programs offer a graphical interface that shows notation, and allow you to enter the music by placing notes on a staff. Although this is a obvious way to design a program, from our point of view, it is cheating. After all, the core message of a piece of music notation simply is the music itself. If you start by offering notation to the user, you have already skipped one conversion, even if it is implicit. If we want to generate music notation from something else, then the obvious candidate for the source is the music itself. On paper this theory sounds very good. In practice, it opens a can of worms. What really is music? Many philosophical treatises must have been written on the subject. Even if you are more practically inclined, you will notice that there exist an enormous number of ways to represent music in a computer, and they are much more incompatible than the formats for word processors and spreadsheets. Anyone who has tried to exchange data files from between different notation programs can attest to this. This problem is caused by the two-dimensional nature of music: in polyphonic music, notes have time and pitch as their two coordinates, and they often are related in both directions. Computer files on the other hand are essentially one-dimensional: they are a long stream of characters. When you represent music in a file, then you have to flatten this two-dimensional information breaking either timing or pitch relations, and there is no universal agreement on how to do this. Fortunately, we have a concrete application, so we don't run the risk of loosing ourselves in philosophical arguments over the essence of music. We want to produce a printed score from a music representation, so this gives us a nice guide for designing a format: we need a format containing mainly musical elements, such as pitch and duration, but also enough information to print a score. Our users have to key in the music into the file directly, so the input format should have a friendly syntax. Finally, we as programmers and scientists want a clean formal definition. After all, producing music notation is a difficult problem, and in the scientific world, problems can only be solved if they are well-specified. Moreover, formally defined formats are easier to write programs for. These ideas shaped our music representation: it is a compact format that can easily be typed by hand. It complex musical constructs from simple entities like notes and rests, in much the same way that one builds complex formulas from simple expressions such as numbers and mathematical operators. The strict separation between musical information and typesetting also gives a blueprint of the program: first it reads the music representation, then it interprets the music--reading it `left-to-right', and translating the musical information to a layout specification. When the layout is computed, the resulting symbols are written to an output file. About this manualAs you will notice in the coming pages the program makes good decisions in a lot of cases: what comes out of LilyPond generally looks good. The default layout of lilypond even is suitable for publication for some specific files. However, some aspects of the formatting are not yet very good. For us programmers, this gives inspiration for improving the program. However, most users are more interested in improving their printouts, and then they have to make manual adjustments to the output. Another aspect of our system of encoding through ASCII then shows: it can be complicated to fine tune the layout of a piece. There is no graphical user interface, where you can simply click and drag a symbol. On the other hand, if you have written the code for tuning one specific aspect of the layout, then you can simply store the file on disk, retrieve it when you need it: there is no need to remember how you did it, since it is all in the input file. Lilypond also comes with a huge collection of snippets that show all kinds of tricks. This collection is much needed, because of the way LilyPond is structured. It is a large program, but almost all of the internal functionality is exported: that is, the variables that are internally used for formatting the sheet music are available directly to the user. These are variables to control thicknesses, distances, and other formatting options. There are a huge number of them, and it would be impossible to describe them all in a hand-written manual. There is no need to despair, there is an `automatic' manual, that lists all of the variables that are available. It is directly generated from the definitions that LilyPond itself uses, so it is always up to date. If you are reading this from a screen: it is available from the web, and is included with most binary distributions. If you're reading this from paper, then we advise you to use the digital version anyway: the hyperlinks make finding topics in the lilypond-internals manual much easier. For those who really want to get their hands dirty: it is even possible to add your own functionality, by extending LilyPond in the built-in scripting language, a dialect of the powerful programming language Scheme. There is no real distinction between what a user can do and what a programmer is allowed to do. In summary, this manual does not pretend to be exhaustive, but it is merely a guide that tries to explain the most important principles, and shows popular input idioms. The rest of the manual is structured as follows: it starts with a tutorial that explains how to use lilypond. In the tutorial, a number of fragments of increasing complexity are shown and explained. Then comes the reference manual, which gives more detailed information on all features. If you're new to lilypond, then you should start reading the tutorial, and experiment for yourself. If you already have some experience, then you can simply use the manual as reference: there is an extensive index1, but the document is also available in One Big Page, which is is available for text search using your browser's search facility. TutorialOperating lilypond is done through text files: To print a piece of
music, you enter the music in a file. When you run lilypond (normally
using the program This tutorial starts with a small introduction to the LilyPond music language. After this first contact, we will show you how to run LilyPond to produce printed output; you should then be able to create your first sheets of music. The tutorial continues with more and more complex examples. First stepsWe start off by showing how very simple music is entered in LilyPond:
you get a note simply by typing its note name, from c d e f g a b then the result looks like this: We will continue with this format: First we show a snippet of input, then the resulting output. The length of a note is specified by adding a number, a1 a2 a4 a16 a32 If you don't specify a duration, the previous one is used: a4 a a2 a A sharp (#) is made by adding cis1 ees fisis aeses Add a dot a2. a4 a8. a16 The meter (or time signature) can be set with the
\time 3/4 \time 6/8 \time 4/4 The clef can be set using the \clef treble \clef bass \clef alto \clef tenor When you enter these commands in a file, you must to enclose them in
\notes { \time 3/4 \clef bass c2 e4 g2. f4 e d c2. } Now the piece of music is almost ready to be printed. The final step is to combine the music with a printing command. The printing command is the so-called \score { \notes { \time 3/4 \clef bass c2 e4 g2. f4 e d c2. } \paper { } } Running LilyPondIn the last section we explained what kind of things you could enter in a lilypond file. In this section we explain how to run LilyPond and how to view or print the output. If you have not used LilyPond before, want to test your setup of LilyPond, or want to run an example file yourself, read this section. The instructions that follow are for running LilyPond on Unix-like systems. Some additional instructions for running LilyPond on Windows are given at the end of this section. Begin by opening a terminal window and starting a text editor.
For example, you could open an xterm and execute \score { \notes { c'4 e' g' } } LilyPond is the program that computes the sheet music. All other
things, such as adding titles, page breaking and other page layout,
are done by a small wrapper program called
ly2dvi -P test.ly You will see the following on your screen: GNU LilyPond 1.6.0 Now processing: `/home/fred/ly/test.ly' Parsing... Interpreting music...[1] ... more interesting stuff ... PS output to `test.ps'... DVI output to `test.dvi'... The results of the ly2dvi run are two files, If the music on your screen looks good, you can print it by clicking File/Print inside ghostview.gv test.ps ghostview test.ps ggv test.ps kghostview test.ps The DVI file ( If your DVI viewer does not have a "Print" button, you can print the
file by executing If your system does not support printing PostScript files, then you can install Ghostscript, a PostScript emulator. Refer to Ghostscript's website at http://www.ghostscript.com. A final option is to use the popular PDF format. You can get a PDF
file by running If you are familiar with TeX, be warned: do not use other
DVI drivers like Windows usersWindows users can start the terminal by clicking on the LilyPond or
Cygwin icon. You can use any text editor (such as NotePad, Emacs or
Vim) to edit the LilyPond file. If you install the Cygwin's
You can also print from the command line by executing:
SUMMARY To run LilyPond, input a text file, then run the command
More basicsWe continue with the introduction of the remaining musical constructs.
Normal rests are entered just like notes with the name " r2 r4 r8 r16 To raise a note by an octave, add a high quote c'4 c'' c''' \clef bass c c, A tie is created by adding a tilde " g'4-~ g' a'2-~ a'4 A tie is different from a slur. A tie simply makes the first note sound longer, and can only be used on pairs of notes with the same pitch. Slurs indicate the articulations of notes, and can be used on larger groups of notes. Slurs and ties are also nested in practice: The key signature is set with the command " \key d \major g'1 \key c \minor g' This example shows notes, ties, octave marks, and rests in action. \score { \notes { \time 4/4 \key d \minor \clef violin r4 r8 d''8 cis''4 e'' d''8 a'4.-~ a' b'8 cis''4 cis''8 cis'' bis'4 d''8 cis''-~ cis''2 r2 } \paper { } } There are some interesting points to note in this example. Accidentals (sharps and flats) don't have to be marked explicitly: you just enter the note name, and LilyPond determines whether or not to print an accidental. Bar lines and beams are drawn automatically. LilyPond calculates line breaks for you; it doesn't matter where you make new lines in the source file. Finally, the order of time, key and clef changes is not relevant: lilypond will use standard notation conventions for ordering these items. The example also indicates that a piece of music written in a high register needs lots of quotes. This makes the input less readable, and is also a potential source of errors. The solution is to use "relative octave" mode. In practice, this is
the most convenient way to copy existing music. To use relative mode,
add \relative c'' { c f c g c } You can make larger intervals by adding octavation quotes. Note that
quotes or commas do not determine the absolute height of a note;
the height of a note is relative to the previous one.
For example: \relative c'' { c f, f c' c g' c, } Here's an example of the difference between relative mode and "normal" (non-relative) mode: \relative a { \clef bass a d a e d c' d' } \clef bass a d a e d c' d' SUMMARY The following table summarizes the syntax learned so far in this section.
A slur is drawn across many notes, and indicates bound articulation
(legato). The starting note and ending note are marked with a
" d4-( c16-)-( cis d e c cis d e-)-( d4-) If you need two slurs at the same time (one for articulation, one for
phrasing), you can also make a phrasing slur with a8-(-\( ais b c-) cis2 b'2 a4 cis, c-\) Beams are drawn automatically, but if you don't like the choices, you
can enter beams by hand. Mark the first note to be beamed with
a8-[ ais-] d-[ es r d-] To print more than one staff, each piece of music that makes up a staff
is marked by adding < \context Staff = staffA { \clef violin c'' } \context Staff = staffB { \clef bass c } > In this example, We can now typeset a melody with two staves: \score { \notes < \context Staff = staffA { \time 3/4 \clef violin \relative c'' { e2-( d4 c2 b4 a8-[ a-] b-[ b-] g-[ g-] a2.-) } } \context Staff = staffB { \clef bass c2 e4 g2. f4 e d c2. } > \paper {} } Notice that the time signature is specified in one melody staff only (the top staff), but is printed on both. LilyPond knows that the time signature should be the same for all staves. Common accents can be added to a note using c-. c-- c-> Dynamic signs are made by adding the markings to the note: c-\ff c-\mf Crescendi and decrescendi are started with the commands c2-\< c2-\!-\ff c2-\> c2-\! Chords can be made by surrounding notes with r4 <<c e g>>4 <<c f a>>8 You can combine beams and ties with chords. Beam and tie markings must be placed outside the chord markers: r4 <<c e g>>8-[ <<c f a>>-]-~ <<c f a>> r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-\) SUMMARY
Now you know the basic ingredients of a music file, so this is the right moment to try your at hand at doing it yourself: try typing some simple examples, and experiment a little. When you're comfortable with the basics, you might want to read the rest of this chapter. It continues in tutorial-style, but it is much more in-depth, dealing with more advanced topics such as lyrics, chords, orchestral scores and parts, fine tuning of output, polyphonic music, and integrating text and music. Printing lyricsIn this section we shall explain how to typeset the following fragment of The Free Software Song: To print lyrics, you must enter them and then instruct lilypond to
print the lyrics.
You can enter lyrics in a special input mode of LilyPond. This mode is
called Lyrics mode, and it is introduced by the keyword Syllables are entered like notes, but with pitches replaced by text. For
example, Spaces can be introduced into a lyric either by using quotes:
These are the lyrics for the free software song: \lyrics { Join us now __ and share the soft -- ware; } As you can see, extender lines are entered as You can use ordinary hyphens at the end of a syllable, i.e. soft- warebut then the hyphen will be attached to the end of the first syllable. If you want them centered between syllables you can use the special
` Normally the notes that you enter are transformed into note heads. Note heads alone make no sense, so they need surrounding information: a key signature, a clef, staff lines, etc. They need context. In LilyPond, these symbols are created by objects called `interpretation contexts'. Interpretation contexts exist for generating notation (`notation context') and for generating sound (`performance context'). These objects only exist while LilyPond is executing. When LilyPond interprets music, it will create a Staff context. We don't want that default here, because we want lyric. The command \context Lyricsexplicitly creates an interpretation context of Lyrics type to interpret the song text that we entered.
The melody of the song doesn't offer anything new: \notes \relative c' { \time 7/4 d'2 c4 b16-( a g a b a b c-) a2 b2 c4 b8-( a16 g a4-) g2 } Both can be combined with the \addlyrics \notes \relative c' ... \context Lyrics \lyrics ... The lyrics are also music expressions, similar to notes. Each syllable of the lyrics is put under a note of the melody. The complete file is listed here: \score { \notes { \addlyrics \notes \relative c' { \time 7/4 d'2 c4 b16 ( a g a b a b ) c a2 b2 c4 b8 ( a16 g ) a4 g2 } \context Lyrics \lyrics { Join us now __ and share the soft -- ware; } } \paper { linewidth = -1. } } A melody with chordsIn this section we show how to typeset a melody with chord
accompaniment. This file is included as \include "paper16.ly" melody = \notes \relative c' { \partial 8 \key c \minor g8 | c4 c8 d es-[ -( d-]-) c4 | f4 f8 g es-[-( d-)-] c g | c4 c8 d es-[ -( d-]-) c4 | d4 es8 d c4. \bar "|." } accompaniment =\chords { r8 c2:3- f:3-.7 d:min es4 c8:min r8 c2:min f:min7 g:7^3.5 c:min } \score { \simultaneous { %\accompaniment \context ChordNames \accompaniment \context Staff = mel { \melody } } \midi { \tempo 4=72 } \paper { linewidth = 10.0\cm } } The result would look this. We will dissect this file line by line. \include "paper16.ly"Smaller size (suitable for inclusion in a book). melody = \notes \relative c' {The structure of the file will be the same as the previous one: a \score block with music in it. To keep things readable, we will
give different names to the different parts of music, and use the names
to construct the music within the score block.
\partial 8 The piece starts with an anacrusis (or "pickup") of one eighth. c4 c8 d [es () d] c4 | f4 f8 g [es() d] c g | c4 c8 d [es () d] c4 | d4 es8 d c4. \bar "|." We use explicit beaming. Since this is a song, we turn automatic beams off and use explicit beaming where needed. }This ends the definition of melody .
text = \lyrics {This defines the lyrics, similar to what we have seen before. accompaniment =\chords {We'll put chords over the music. To enter them, we use a special mode analogous to \lyrics and \notes mode, where you can give
the names of the chords you want instead of listing the notes
comprising the chord.
r8There is no accompaniment during the anacrusis. c2:3- This is a c minor chord, lasting for a half note. Chords are entered using
the tonic. Notes can be changed to create different chords. In this case,
a lowered third is used (making a C major chord into a C minor chord).
The code for this is f:3-.7Similarly, 7 modifies (adds) a seventh, which is small by
default to create the f a c es chord. Multiple modifiers must be
separated by dots.
d:min es4 c8:min r8Some modifiers have predefined names, e.g. min is the same as
3- , so d-min is a minor d chord.
c2:min f:min7 g:7^3.5 c:min } A named modifier \score { \simultaneous {We assemble the music in the \score block. Melody, lyrics and
accompaniment have to sound at the same time, so they should be
\simultaneous .
%\accompanimentChord mode generates notes grouped in \simultaneous music. If
you remove the comment sign, you can see the chords in normal
notation: they will be printed as note heads on a separate
staff. To print them as chords names, they have to be interpreted as
being chords, not notes. This is done with the following command:
\context ChordNames \accompaniment Normally the notes that you enter are transformed into note heads. Note heads alone make no sense, so they need surrounding information: a key signature, a clef, staff lines, etc. They need context. In LilyPond, these symbols are created by objects called `interpretation contexts'. Interpretation contexts exist for generating notation (`notation context') and for generating sound (`performance context'). These objects only exist while LilyPond is executing. When LilyPond interprets music, it will create a Staff context. If
the We don't want that default here, because we want chord names. The
command above explicitly creates an interpretation context of
\context Staff = mel { We place the melody on a staff called \property Staff.autoBeaming = ##fAn interpretation context has variables, called properties, that tune its behavior. One of the variables is autoBeaming . Setting
this Staff 's property to ##f , which is the boolean value
false, turns the automatic beaming mechanism off for the current
staff.
\melody }Finally, we put the melody on the current staff. Note that the \property directives and \melody are grouped in sequential
music, so the property settings are done before the melody is
processed.
\midi { \tempo 4=72}MIDI (Musical Instrument Digital Interface) is a standard for connecting and recording digital instruments. So a MIDI file is like a tape recording of an instrument. The \midi block makes the
music go to a MIDI file, so you can listen to the music you entered. It
is great for checking the music. Whenever you hear something weird, you
probably hear a typing error.
Syntactically, \paper { linewidth = 10.0\cm }We also want notation output. The linewidth is short so that the piece will be set in two lines. More stanzasIf you have multiple stanzas printed underneath each other, the vertical groups of syllables should be aligned around punctuation. LilyPond can do this if you tell it which lyric lines belong to which melody. We show how you can do this by showing how you could print a frivolous fragment of a fictional Sesame Street duet. \score { \addlyrics \notes \relative c'' \context Voice = duet { \time 3/4 g2 e4 a2 f4 g2. } \lyrics \context Lyrics < \context LyricsVoice = "duet-1" { \property LyricsVoice . stanza = "Bert" Hi, my name is bert. } \context LyricsVoice = "duet-2" { \property LyricsVoice . stanza = "Ernie" Ooooo, ch\'e -- ri, je t'aime. } > } To this end, give the Voice context an identity, and set the
LyricsVoice to a name starting with that identity followed by a dash.
In the following example, the Voice identity is \context Voice = duet { \time 3/4 g2 e4 a2 f4 g2. }and the identities of the LyricsVoices are duet-1 and duet-2 .
\context LyricsVoice = "duet-1" { Hi, my name is bert. } \context LyricsVoice = "duet-2" { Ooooo, ch\'e -- ri, je t'aime. } We add the names of the singers. This can be done by setting
\property LyricsVoice . stanza = "Bert" ... \property LyricsVoice . stanza = "Ernie" The convention for naming More movementsThe program Two miniatures
Opus 1.
Up
Opus 2.
Down
For example, consider the following file ( \version "1.5.72" \header { title = "Two miniatures" composer = "F. Bar Baz" tagline = "small is beautiful" } \paper { linewidth = -1.0 } %{ Mental note: discuss Schenkerian analysis of these key pieces. %} \score { \notes { c'4 d'4 } \header { opus = "Opus 1." piece = "Up" } } \score { \notes { d'4 c'4 } \header { opus = "Opus 2." piece = "Down" } } The information for the global titling is in a so-called header block.
The information in this block is not used by LilyPond, but it is
passed into \header { title = "Two miniatures" composer = "F. Bar Baz" tagline = "small is beautiful" } When you process a file with ly2dvi, a signature line is printed at
the bottom of the last page. This signature is produced from the
Many people find the default tagline ("Lily was here") too droll.
If that is the case, you can change \paper { linewidth = -1.0 } A paper block at top level (i.e. not in a The variable %{ Mental note: discuss Schenkerian analysis of these key pieces. %} Mental notes to yourself can be put into comments. There are two types
of comments. Line comments are introduced by \score { \notes { c'4 d'4 } In previous examples, most notes were specified in relative octaves
(i.e. each note was put in the octave that is closest to its
predecessor). Besides relative, there is also absolute octave
specification, which you get when you don't include When you're copying music from existing sheet music, relative octaves are probably the easiest to use: you have to do less typing, and errors are easily spotted. However, if you write LilyPond input directly, either by hand (i.e. composing) or by computer, absolute octaves may be easier to use. \header { The opus = "Opus 1." piece = "Up" }For example, the Opus number is put at the right, and the "piece" string will be at the left. \version "1.5.72" \header { title = "Two miniatures" composer = "F. Bar Baz" tagline = "small is beautiful" } \paper { linewidth = -1.0 } \score { \notes { c'4 d'4 } \header { opus = "Opus 1." piece = "Up" } } \score { \notes { d'4 c'4 } \header { opus = "Opus 2." piece = "Down" } } TODO: scoreA = \score { \deelA } scoreB = \score { \deelA } % \score { \scoreA } \score { \scoreB } \version "1.5.72"Lilypond and its language are still under development, and occasionally details of the syntax are changed. The version
fragment indicates which version of lilypond the input file was written
for. When you compile this file, the version number will be checked
and you will get a warning when the file is too old. This version
number is also used by the convert-ly program (See
Invoking convert-ly), which can used to update the file to the
latest lily version.
A piano excerptOur eighth subject is a piece of piano music. The fragment in the
input file is a piano reduction of the G major Sinfonia by Giovanni
Battista Sammartini, composed around 1740. It's in the source
package under the name \version "1.7.6" \include "paper16.ly" viola = \notes \relative c' \context Voice = viola { <<c g' c>>4-\arpeggio \voiceTwo g'8. b,16 s1 s2. r4 g } oboes = \notes \relative c'' \context Voice = oboes { \voiceOne s4 g8. b,16 c8 r <<e' g>>8. <<f a>>16 \grace <<e g>>8-( <<d f>>4-) <<c e>>2 \times 2/3 { <<d f>>8 <<e g>> <<f a>> } < { \times 2/3 { a8 g c } c2 } \\ { f,8 e e2 } > \grace <<c, e>>8-( <<b d>>8.-)-\trill <<c e>>16 | [<<d f>>-( <<f a>>8.-)] <<b, d>>8 r [<<d f>>16-( <<f a>>8.-)] <<b, d>>8 r | [<<c e>>16-( <<e g>>8.-)] <<c e,>>8 } hoomPah = \repeat unfold 8 \notes \transpose c c { \translator Staff = down \stemUp c8 \translator Staff = up \stemDown c'8 } bassvoices = \notes \relative c' { c4 g8. b,16 \context Voice \hoomPah \translator Staff = down \stemBoth [c8 c'8] r4 <<g d'>> r4 < { r2 <<e c'>>4 <<c g'>>8 } \\ { g2-~ | g4 c8 } > } \score { \context PianoStaff \notes < \context Staff = up < \oboes \viola > \context Staff = down < \time 2/2 \clef bass \bassvoices > > \midi { } \paper { indent = 0.0 linewidth = 15.0 \cm } } %% new-chords-done %%
As you can see, this example features multiple voices on one staff. To make room for those voices, their notes should be stemmed in opposite directions. LilyPond includes the identifiers viola = \notes \relative c' \context Voice = viola {In this example you can see multiple parts on a staff. Each part is associated with one notation context. This notation context handles stems and dynamics (among other things). The type name of this context is Voice . For each part we have to make sure that there is
precisely one Voice context, so we give it a unique name
(`viola ').
<<c g' c>>4-\arpeggioThe delimiters << and >> enclose the pitches of a chord.
\arpeggio typesets an arpeggio sign (a wavy vertical line)
before the chord.
\voiceTwo We want the viola to have stems down, and have all the other
characteristics of a second voice. This is enforced using the
g'8. b,16Relative octaves work a little differently with chords. The starting point for the note following a chord is the first note of the chord. So the g gets an octave up quote: it is a fifth above the starting
note of the previous chord (the central C).
s1 s2. r4 s is a spacer rest. It does not print anything, but it does have
the duration of a rest. It is useful for filling up voices that
temporarily don't play. In this case, the viola doesn't come until one
and a half measure later.
oboes = \notes \relative c'' \context Voice = oboe {Now comes a part for two oboes. They play homophonically, so we print the notes as one voice that makes chords. Again, we insure that these notes are indeed processed by precisely one context with \context .
\voiceOne s4 g8. b,16 c8 r <<e' g>>8. <<f a>>16 The oboes should have stems up to keep them from interfering with
the staff-jumping bass figure. To do that, we use \grace <<e g>>-( <<d f>>4-) <<c e>>2 \grace introduces grace notes. It takes one argument, in this
case a chord. A slur is introduced starting from the \grace
ending on the following chord.
\times 2/3Tuplets are made with the \times keyword. It takes two
arguments: a fraction and a piece of music. The duration of the piece
of music is multiplied by the fraction. Triplets make notes occupy 2/3
of their notated duration, so in this case the fraction is 2/3.
{ <<d f>>8 <<e g>> <<f a>> }The piece of music to be `tripletted' is sequential music containing three chords. <At this point, the homophonic music splits into two rhythmically different parts. We can't use a sequence of chords to enter this, so we make a "chord of sequences" to do it. We start with the upper voice, which continues with upward stems: { \times 2/3 { a8 g c } c2 } \\The easiest way to enter multiple voices is demonstrated here. Separate the components of the voice (single notes or entire sequences) with \\ in a simultaneous music expression. The
\\ separators split first voice, second voice, third voice, and
so on.
As far as relative mode is concerned, the previous note is the
f,8 e e2 } >This ends the two-part section. \stemBoth \grace <<c, e>>8-( <<b d>>8.-\trill <<c e>>16 |
The bass has a little hoom-pah melody to demonstrate parts switching between staves. Since it is repetitive, we use repeats: hoomPah = \repeat unfold 8The unfolded repeat prints the notes in its argument as if they were written out in full eight times. \notes \transpose c' { Transposing can be done with The purpose of this no-op is to protect it from being interpreted as
relative notes. Relative mode can not be used together with
transposition, so \translator Staff = down \stemUp c8 \translator Staff = up \stemDown c'8 }Voices can switch between staves. Here you see two staff switching commands. The first one moves to the lower staff, the second one to the lower one. If you set the stem directions explicitly (using the identifiers \stemUp and \stemDown , the notes
can be beamed together (despite jumping between staffs).
bassvoices = \notes \relative c' { c4 g8. b,16 \autochange Staff \hoomPah \context Voice \translator Staff = downWe want the remaining part of this melody on the lower staff, so we do a manual staff switch here. \context Voice = reallyLow {\stemDown g2-~ | g4 c8 } >After skipping some lines, we see ~ . This mark makes ties. Note
that ties and slurs are different things. A tie can only connect two
note heads of the same pitch, whereas a slur can connect many notes
with one curve.
\context PianoStaffA special context is needed to get cross staff beaming right. This context is called PianoStaff .
\context Staff = bottom < \time 2/2 \clef bassThe bottom staff must have a different clef. indent = 0.0To make some more room on the line, the first (in this case the only) line is not indented. The line still looks very cramped, but that is due to the page layout of this document. Fine tuning a pieceIn this section we show some ways to fine tune the final output of a
piece. We do so using a single measure of a moderately complex piano
piece: a Brahms intermezzo (opus 119, no. 1). Both fragments (the
tuned and the untuned versions) are in The code for the untuned example shows us some new things. \version "1.7.6" \score { \notes\context PianoStaff < \context Staff = up \relative c'' < { \key d\major fis4-3_\p-(-~ fis16 a-)-5 } \\ { fis16-(-\> d b-\! \translator Staff = down \clef treble g-~ <<g e>>8-) } \\ { s16 d' ~ <<d b>>4 } > \context Staff = down { \key d \major \time 3/8 \clef bass s4. } > \paper { linewidth = -1. } } %% new-chords-done %% Hairpin dynamics can be easily added to Lilypond scores. Beginning a
crescendo is indicated with Fingering indications are entered with Now that we have the basic piece of music entered, we want to fine tune it so that we get something that resembles the original printed edition by Schott/Universal Edition: Fine tuning involves overriding the defaults of the printing system.
We do this by setting variables which control how Lilypond prints
symbols. Printed symbols are called graphical objects (often
abbreviated to grob). Each object is described by a bunch of
settings. Every setting is a variable: it has a name and a value
which you can change. These values determine the fonts, offsets,
sub-routines to be called on the object, etc. The initial values of
these settings are set in the Scheme file
We start with the slur in the upper part, running from F sharp to A. In the printed edition, this slur runs from stem to stem; in our version, the slur begins at the note head of the F sharp. The following property setting forces all slurs to run from stem to stem (not from or to note heads!). \property Voice.Slur \set #'attachment = #'(stem . stem) More precisely, this command modifies the definition of the Although this fixes the slur, it isn't very helpful for fine tuning in
general: the lilypond back-end supports approximately 240 variables
like The interesting information is how you can figure out which properties to tune for your own scores. To discover this, you must have a copy of the internals document. This is a set of HTML pages which should be included if you installed a binary distribution2. These HTML pages are also available on the web: go to the lilypond website, click "Documentation: Index" on the side bar, look in the "Information for uses" section, and click on "Documentation of internals". You might want to bookmark either the HTML files on your disk, or the one on the web (the HTML on your hard drive will load much faster than the ones on the web!). One word of caution: the internals documentation is generated from the definitions that lily uses. For that reason, it is strongly tied to the version of LilyPond that you use. Before you proceed, please make sure that you are using the documentation that corresponds to the version of LilyPond that you are using. Suppose that you wanted to tune the behavior of the slur. The first step is to get some general information on slurs in lilypond. Turn to the index, and look up "slur". The section on slurs says The grob for this object is Slur , generally in Voice context. So the graphical object for this object is called Now you get a list of all the properties that the slur object
supports, along with their default values. Among the properties we
find the \property Voice.Slur \set #'attachment = #'(stem . stem) If you ran the previous example, you have unknowingly already used
this kind of command. The stemUp = \property Voice.Stem \set #'direction = #1 Next we want to move the fingering `3'. In the printed edition it is
not above the stem, but a little lower and slightly left of the stem.
From the user manual we find that the associated graphical object is
called Fingering grobs are created by: Fingering_engraver Clicking Fingering_engraver is part of contexts: Voice and TabVoiceso tuning the settings for Fingering should be done using either \property Voice.Fingering \set ...or \property TabVoice.Fingering \set ... Since the For shifting the fingering, we use the property \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8)The extra-offset is a low-level feature: it moves around
objects in the printout; the formatting engine is completely oblivious
to these offsets. The unit of these offsets are staff-spaces. The
first number controls left-right movement; a positive number will move
the object to the right. The second number controls up-down movement;
a positive number will move it higher.
We only want to offset a single object, so after the F-sharp we must undo the setting. The technical term is to revert the property. \property Voice.Fingering \revert #'extra-offset There are three different types of variables in LilyPond, something
which can be confusing at first (and for some people it stays confusing
:). Variables such as The second fingering instruction should be moved up a little to avoid
a collision with the slur. This could be achieved with
a-)^" "^\markup { \finger "5" } A fingering instruction, which would be entered as Normally one would specify all dynamics in the same voice, so that dynamics (such as f and p) will be aligned with hairpins. But in this case, we don't want the decrescendo to be aligned with the piano sign. We achieve this by putting the dynamic markings in different voices. The crescendo should be above the upper staff. This can be forced by using the precooked command \dynamicsUp However, if you do that the decrescendo will be too close to the
upper voice and collide with the stems. Looking at the manual for
dynamics, we notice that "Vertical positioning of these symbols is
handled by the DynamicLineSpanner
grob.". If we turn
to the documentation of For the moment we are interested in side positioning: side-position-interfaceBetween the object and its support (in this case the notes in the voice going down), there should be more space. This space is controlled by padding , so we increase it.
\property Voice.DynamicLineSpanner \override #'padding = #5.0 This command is almost like the command for setting slur attachments,
but subtly different in its details. Grob properties can be
manipulated with two commands: Brahms uses music notation is a slightly unorthodox way. Ties usually happen only within one voice. In this piece, the composer gladly produces ties that jump voices. We deal with this by faking these ties: whenever we need such a tie, we insert a notehead in a different voice, and blank the stem. This is done in the following snippet of code. \property Voice.Stem \set #'transparent = ##t d'Blanking the stem should be done for only one object. One of the ways to achieve that, is by setting the property before a note. Reverting it afterwards is tedious, so for setting a property only once, we have the syntax \once : it reverts the property directly before
proceeding to the next step in time.
The Finally, the last tie is forced up using Here's the complete "fine tuned" version, which includes all the modifications we discussed in this section: \version "1.7.6" \score { \notes\context PianoStaff < \context Staff = up \relative c'' < { \key d\major \property Voice.Slur \set #'attachment = #'(stem . stem) \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8) fis4-3_\p-(-~ \property Voice.Fingering \revert #'extra-offset fis16 a-)^" "^\markup { \finger "5" } } \\ { \dynamicUp \property Voice.DynamicLineSpanner \override #'padding = #5.0 \tieUp fis16-(-\> d b-\! \translator Staff = down \stemUp \clef treble g-~ <<g e>>8-) } \\ { s16 \property Voice.Stem \set #'transparent = ##t d' \property Voice.Stem \revert #'transparent ~ <<d b>>4 } > \context Staff = down { \key d \major \time 3/8 \clef bass s4. } > \paper { linewidth = -1. } } %% new-chords-done %% An orchestral scoreOur next two examples demonstrate one way to create an orchestral score in LilyPond. When typesetting a piece for several instruments, you'll want to create a full score (for the conductor) along with several individual parts (for the players). LilyPond is well suited for this task. We will declare the music for
each instrument individually, giving the music of each instrument its
own name. These pieces of music are then combined in different
This orchestral score example consists of three input files. In the
first file, % os-music.ly \header { title = "Zo, goed lieverd?" subtitle = "How's, this babe?" composer = "JCN" opus = "1" piece = "Laid back" } global = { \time 2/4 \skip 2*4 \bar "|." } Key = \notes \key as \major flautoI = \notes\relative c'' { f8 g f g f g f g bes as bes as bes as bes as } flautoII = \notes\relative c'' { as8 bes as bes R1 d4 ~ d } tromboI = \notes\relative c'' { c4. c8 c8 c4. es4 r as, r } tromboII = \notes\relative c'' { as4. as8 as8 as4. R1*1/2 as4 es' } timpani = \notes\relative c, { \times 2/3 { f4 f f } \times 4/5 { as8 as as as as } R1 } corno = \notes\relative c' { bes4 d f, bes d f, bes d } We will not examine this example line by line, since you already know most of it. We'll examine a few lines which contain new elements. global = { \time 2/4 \skip 2*4 \bar "|." } Declare setting to be used globally. The Key = \notes \key as \majorDeclare the key signature of the piece and assign it to the identifier Key. Later on we'll use \Key for all staves except those
for transposing instruments.
The full scoreThe second file, \version "1.7.6" \include "os-music.ly" \include "paper13.ly" #(ly:set-point-and-click 'line-column) textFlat = \markup {\smaller \musicglyph #"accidentals--1"} \score { < \global \property Score.BarNumber \override #'padding = #3 \context StaffGroup = woodwind < \context Staff = flauti < \property Staff.midiInstrument = #"flute" \property Staff.instrument = "2 Flauti" \property Staff.instr = "Fl." \Key \context Voice=one { \voiceOne \flautoI } \context Voice=two { \voiceTwo \flautoII } > > \context StaffGroup = timpani < \context Staff = timpani < \property Staff.midiInstrument = #"timpani" \property Staff.instrument = \markup { \column << "Timpani" "(C-G)" >> } \property Staff.instr = #"Timp." \clef bass \Key \timpani > > \context StaffGroup = brass < \context Staff = trombe < \property Staff.midiInstrument = #"trumpet" \property Staff.instrument = \markup { \column << "2 Trombe" "(C)" >> } \property Staff.instr = \markup{ \column << "Tbe." "(C)">> } \Key \context Voice=one \partcombine Voice \context Thread=one \tromboI \context Thread=two \tromboII > \context Staff = corni < \property Staff.midiInstrument = #"french horn" \property Staff.instrument = \markup { \column << "Corno" { "(E" \textFlat ")" } >> } \property Staff.instr = \markup { \column << "Cor." { "(E" \textFlat ")" } >> } \property Staff.transposing = #3 \notes \key bes \major \context Voice=one \corno > > > \paper { indent = 15 * \staffspace linewidth = 60 * \staffspace textheight = 90 * \staffspace \translator{ \VoiceContext \consists "Multi_measure_rest_engraver" } \translator{ \HaraKiriStaffContext \remove "Multi_measure_rest_engraver" } } \midi { \tempo 4 = 75 } } Zo, goed lieverd?
How's, this babe?
Opus 1.
LAID BACK
\include "os-music.ly"First we need to include the music definitions we made in os-music.ly .
#(ly:set-point-and-click 'line-column) This piece of Scheme code executes the function
#(define text-flat '((font-relative-size . -2) (music "accidentals--1"))) To name the transposition of the french horn, we will need a piece of
text with a flat sign. LilyPond has a mechanism for font selection and
kerning called Scheme markup text (See Text markup). The flat
sign is taken from the music font, and its name is < \globalAll staves are simultaneous and use the same global settings. \property Score.BarNumber \override #'padding = #3LilyPond prints bar numbers at the start of each line, but unfortunately they end up a bit too close to the staff in this example. In LilyPond, a bar number is called BarNumber. BarNumber objects can be manipulated through their side-position-interface. One of the properties of a side-position-interface that can be tweaked is padding: the amount of extra space that is put between this and other objects. We set the padding to three staff spaces. You can find information on all these kind of properties in LilyPond's automatically generated documentation in LilyPond Internals or in Fine tuning a piece. \context StaffGroup = woodwind < \context Staff = flauti <A new notation context: the StaffGroup . StaffGroup can
hold one or more Staff 's, and will print a big bracket at the
left of the score. This starts a new staff group for the woodwind
section (just the flutes in this case). Immediately after that, we
start the staff for the two flutes, who also play simultaneously.
\property Staff.midiInstrument = #"flute"Specify the instrument for MIDI output (see MIDI instrument names). \property Staff.instrument = "2 Flauti" \property Staff.instr = "Fl."This defines the instrument names to be printed in the margin. instrument specifies the name for the first line
of the score, instr is used for the rest of the score.
\KeyThe flutes play in the default key. \context Voice=one { \voiceOne \flautoI } \context Voice=two { \voiceTwo \flautoII }Last come the actual flute parts. Remember that we're still in simultaneous mode. We name both voices differently, so that LilyPond will create two Voice contexts. The flute parts are simple, so we specify manually which voice is which: \voiceOne forces the
direction of stems, beams, slurs and ties up, \voiceTwo sets
directions down.
> >Close the flutes staff and woodwind staff group. \property Staff.instrument = #'(lines "Timpani" "(C-G)")The timpani staff demonstrates a new piece of scheme markup, it sets two lines of text. \context Voice=one \partcombine Voice \context Thread=one \tromboI \context Thread=two \tromboIIYou have seen the notation contexts Staff and Voice, but here's a new one: Thread. One or more Threads can be part of a Voice. Thread takes care of note heads and rests; Voice combine note heads onto a stem. For the trumpets we use the automatic part combiner (see Automatic part combining) to combine the two simultaneous trumpet parts onto the
trumpet staff. Each trumpet gets its own Thread context, which must be
named \property Staff.instrument = #`(lines "Corno" (columns "(E" ,text-flat ")"))The french horn ("Corno") has the most complex scheme markup name, made up of two lines of text. The second line has three elements (columns) - the (E , the flat sign text-flat that we defined previously,
and a final ")" . Note that we use a backquote instead of an
ordinary quote at the beginning of the Scheme expression to be able to
access the text-flat identifier, `unquoting' it with a ", ".
\property Staff.transposing = #3The french horn is to be tuned in E-flat, so we tell the MIDI back-end to transpose this staff by three steps. Note how we can choose different tunings for the text input, sheet music
output and, and MIDI output, using \notes \key bes \majorSince the horn is transposing, it's in a different key. indent = 15 * \staffspace linewidth = 55 * \staffspaceWe specify a big indent for the first line and a small linewidth for this tutorial. Usually LilyPond's default setup of notation contexts (Thread, Voice, Staff, Staffgroup, Score) is just fine. But in this case we want a different type of Staff context. \translator{ \HaraKiriStaffContext } In orchestral scores it often happens that one instrument only has
rests during one line of the score. Extracting an individual partThe third file, \include "os-music.ly" \include "paper16.ly" \score { \context Staff < \property Score.skipBars = ##t \property Staff.midiInstrument = #"flute" \global \Key \flautoII > \header { instrument = "Flauto II" } \paper { linewidth = 80 * \staffspace textheight = 200 * \staffspace } \midi { \tempo 4 = 75 } } Zo, goed lieverd?
How's, this babe?
Flauto II
Opus 1.
LAID BACK
Because we separated the music definitions from the \flautoIIIn this individual part the second flute has a whole staff for itself, so we don't want to force stem or tie directions. \header { instrument = "Flauto II" }The \header definitions were also read from os-music.ly ,
but we need to set the instrument for this particular score.
\property Score.skipBars = ##tIn the conductor's full score, all bars with rests are printed, but for the individual parts, we want to print one multimeasure rest instead of many consecutive empty bars. LilyPond will do this if Score.skipBars is set to true (##t ).
Integrating text and musicSometimes you might want to use music examples in a text that you are writing (for example a musicological treatise, a songbook, or (like us) the LilyPond manual). You can make such texts by hand, simply by importing a PostScript figure into your word processor. However, there is an automated procedure to reduce the amount of work. If you use HTML, LaTeX, or texinfo, you can mix text and LilyPond
code. A script called \documentclass[a4paper]{article} \begin{document} In a lilypond-book document, you can freely mix music and text. For example: \begin{lilypond} \score { \notes \relative c' { c2 g'2 \times 2/3 { f8 e d } c'2 g4 } } \end{lilypond} Notice that the music line length matches the margin settings of the document. If you have no \verb+\score+ block in the fragment, \texttt{lilypond-book} will supply one: \begin{lilypond} c'4 \end{lilypond} In the example you see here, two things happened: a \verb+\score+ block was added, and the line width was set to natural length. You can specify many more options using \LaTeX style options in brackets: \begin[verbatim,11pt,singleline, fragment,relative,intertext="hi there!"]{lilypond} c'4 f bes es \end{lilypond} \texttt{verbatim} prints the LilyPond code in addition to the graphical score, \texttt{11pt} selects the default music size, \texttt{fragment} adds a score block, \texttt{relative} uses relative mode for the fragment, and \texttt{intertext} specifies what to print between the \texttt{verbatim} code and the music. If you want to include large examples into the text, it may be more convenient to put the example in a separate file: \lilypondfile[printfilename]{sammartini.ly} The \texttt{printfilename} option adds the file name to the output. \end{document} Under Unix, you can view the results as follows. $ cd input/tutorial $ mkdir -p out/ $ lilypond-book --outdir=out/ lilbook.tex lilypond-book (GNU LilyPond) 1.6.1 Reading `input/tutorial/lilbook.tex' Reading `input/tutorial/sammartini.ly' lots of stuff deleted Writing `out/lilbook.latex' $ cd out $ latex lilbook.latex lots of stuff deleted $ xdvi lilbook Notice the The result looks more or less like this: In a lilypond-book document, you can freely mix music and text. For example: Notice that the music line length matches the margin settings of the document. If you have no In the example you see here, a number of things happened: a
c'4 f bes es hi there!
If you include large examples into the text, it may be more convenient
to put the example in a separate file:
The End of tutorialThis is the end of the tutorial. If you read everything until this point (and understood everything!) then you're now an accomplished lilypond hacker. From here you should try fiddling with input files or making your own input files. Come back to the reference manual for more information if you get stuck! Don't forget to check out the templates, examples and feature tests. If you want to see real action LilyPond, head over to http://www.mutopiaproject.org, which has many examples of classical music typeset with LilyPond. Reference ManualThis document describes GNU LilyPond and its input format. The last revision of this document was made for LilyPond 1.7.10. It assumes that you already know a little bit about LilyPond input (how to make an input file, how to create sheet music from that input file, etc). New users are encouraged to study the tutorial before reading this manual. Note entryNotes constitute the most basic elements of LilyPond input, but they do
not form valid input on their own without a NotesA note is printed by specifying its pitch and then its duration. cis'4 d'8 e'16 c'16 PitchesThe verbose syntax for pitch specification is \pitch scmpitch where scmpitch is a pitch scheme object. In Note and Chord mode, pitches may be designated by names. The default
names are the Dutch note names. The notes are specified by the letters
\clef bass a,4 b, c d e f g a b c' d' e' \clef treble f' g' a' b' c'' In Dutch, a sharp is formed by adding LilyPond has predefined sets of note names for various other languages.
To use them, simply include the language specific init file. For
example: Note Names sharp flat nederlands.ly c d e f g a bes b -is -es english.ly c d e f g a bf b -s/-sharp -f/-flat deutsch.ly c d e f g a b h -is -es norsk.ly c d e f g a b h -iss/-is -ess/-es svenska.ly c d e f g a b h -iss -ess italiano.ly do re mi fa sol la sib si -d -b catalan.ly do re mi fa sol la sib si -d/-s -b espanol.ly do re mi fa sol la sib si -s -b The optional octave specification takes the form of a series of
single quote (` c' c'' es' g' as' gisis' ais' Chromatic alterationsNormally accidentals are printed automatically, but you may also
print them manually. A reminder accidental
can be forced by adding an exclamation mark cis' cis' cis'! cis'? The automatic production of accidentals can be tuned in many ways. For more information, refer to Accidentals. RestsRests are entered like notes, with a "note name" of ` r1 r2 r4 r8 Whole bar rests, centered in middle of the bar, are specified using
For some music, you may wish to explicitly specify the rest's vertical
position. This can be achieved by entering a note with the a'4\rest d'4\rest SkipsAn invisible rest (also called a `skip') can be entered like a note
with note name ` a2 s4 a4 \skip 1 a4 In Lyrics mode, you can make invisible syllables by entering ` < \context Lyrics \lyrics { lah2 di4 " " dah2 _4 di } \notes\relative c'' { a2 a4 a a2 a4 a } > In this case, syllables containing a space will be printed. In the case that you really need an invisible space (i.e. something taking up time, but not space), you should use \skip .
Note that the \score { \context Staff < { \time 4/8 \skip 2 \time 4/4 } \notes\relative c'' { a2 a1 } > } The skip command is merely an empty musical placeholder. It doesn't produce any output, not even transparent output. DurationsIn Note, Chord, and Lyrics mode, durations are designated by numbers
and dots: durations are entered as their reciprocal values. For example,
a quarter note is entered using a c'\breve c'1 c'2 c'4 c'8 c'16 c'32 c'64 c'64 r\longa r\breve r1 r2 r4 r8 r16 r32 r64 r64
If the duration is omitted then it is set to the previously entered
duration. At the start of parsing, a quarter note is assumed. The
duration can be followed by dots (` a' b' c''8 b' a'4 a'4. b'4.. c'8. You can alter the length of duration by a fraction N/M
appending ` a'2*2 b'4*2 a'8*4 a'4*3/2 gis'4*3/2 a'4*3/2 a'4 Durations can also be produced through GUILE extension mechanism. c'\duration #(ly:make-duration 2 1) BUGS Dot placement for chords is not perfect. In some cases, dots overlap: TiesA tie connects two adjacent note heads of the same pitch. The tie in
effect extends the length of a note. Ties should not be confused with
slurs, which indicate articulation, or phrasing slurs, which indicate
musical phrasing. A tie is entered using the tilde symbol ` e' ~ e' <<c' e' g'>> ~ <<c' e' g'>> When a tie is applied to a chord, all note heads (whose pitches match) are connected. If you try to tie together chords that have no common pitches, no ties will be created. If you want less ties created for a chord, you can set
\property Voice.sparseTies = ##t <<c' e' g'>> ~ <<c' e' g'>> In its meaning a tie is just a way of extending a note duration, similar to the augmentation dot: the following example are two ways of notating exactly the same concept. If you need to tie notes over bars, it may be easier to use Automatic note splitting. See also Tie . BUGS At present, the tie is represented as a separate event, temporally located in between the notes. Tying only a subset of the note heads of a chord is not supported in a simple way. It can be achieved by moving the tie-engraver into the Thread context and turning on and off ties per Thread. Switching staves when a tie is active will not work. Automatic note splittingLilyPond can automatically converting long notes to tied notes. This
is done by replacing the \score{ \notes\relative c'{ \time 2/4 c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2 } \paper{ \translator{ \ThreadContext \remove "Note_heads_engraver" \consists "Completion_heads_engraver" } } }
This engraver splits all running notes at the bar line, and inserts ties. One of its uses is to debug complex scores: if the measures are not entirely filled, then the ties exactly show how much each measure is off. BUGS Not all durations (especially those containing tuplets) can be represented exactly; the engraver will not insert tuplets. TupletsTuplets are made out of a music expression by multiplying all durations with a fraction. \times fraction musicexpr The duration of musicexpr will be multiplied by the fraction. In the sheet music, the fraction's denominator will be printed over the notes, optionally with a bracket. The most common tuplet is the triplet in which 3 notes have the length of 2, so the notes are 2/3 of their written length: g'4 \times 2/3 {c'4 c' c'} d'4 d'4 The property \property Voice.tupletSpannerDuration = #(ly:make-moment 1 4) \times 2/3 { c'8 c c c c c } The format of the number is determined by the property
See also TupletBracket . BUGS Nested tuplets are not formatted automatically. In this case, outer tuplet brackets should be moved automatically. Easy Notation note headsA entirely different type of note head is the "easyplay" note head: a note head that includes a note name. It is used in some publications by Hal-Leonard Inc. music publishers. \score { \notes { c'2 e'4 f' | g'1 } \paper { \translator { \EasyNotation } } } Note that If you view the result with Xdvi, then staff lines will show through the letters. Printing the PostScript file obtained with ly2dvi does produce the correct result. Easier music entryWhen entering music with LilyPond, it is easy to introduce errors. This section deals with tricks and features that help you enter music, and find and correct mistakes. Graphical interfacesOne way to avoid entering notes using the keyboard is to use a graphical user interface. The following programs are known to have a lilypond export option:
Another option is to enter the music using your favorite
sequencer/notation editor, and then export it as MIDI or MusicXML.
You can then import it in lilypond by using either midi2ly or
xml2ly. midi2ly is described in Invoking midi2ly. Relative octavesOctaves are specified by adding \relative startpitch musicexpr The octave of notes that appear in musicexpr are calculated as
follows: If no octave changing marks are used, the basic interval
between this and the last note is always taken to be a fourth or less
(This distance is determined without regarding alterations; a
The octave changing marks Entering music that changes octave frequently is easy in relative mode. \relative c'' { b c d c b c bes a } And octave changing marks are used for intervals greater than a fourth. \relative c'' { c g c f, c' a, e'' } If the preceding item is a chord, the first note of the chord is used to determine the first note of the next chord. However, other notes within the second chord are determined by looking at the immediately preceding note. \relative c' { c <<c e g>> <<c' e g>> <<c, e' g>> } The pitch after the The relative conversion will not affect Bar checkWhenever a bar check is encountered during interpretation, a warning
message is issued if it doesn't fall at a measure boundary. This can
help you find errors in the input. Depending on the value of
A bar check is entered using the bar symbol, \time 3/4 c2 e4 | g2. Failed bar checks are most often caused by entering incorrect
durations. Incorrect durations often completely garble up the score,
especially if it is polyphonic, so you should start correcting the score
by scanning for failed bar checks and incorrect durations. To speed up
this process, you can use Point and clickPoint and click lets you find notes in the input by clicking on them in the Xdvi window. This makes it very easy to find input that causes some error in the sheet music. To use it, you need the following software
Xdvi must be configured to find the TeX fonts and music fonts. Refer to the Xdvi documentation for more information. To use point-and-click, add one of these lines to the top of your .ly file. #(ly:set-point-and-click 'line) When viewing, Control-Mousebutton 1 will take you to the originating
spot in the If you correct large files with point-and-click, be sure to start correcting at the end of the file. When you start at the top, and insert one line, all following locations will be off by a line. For using point-and-click with emacs, add the following
In your emacs startup file (usually (server-start) Make sure that the environment variable XEDITOR is set to emacsclient --no-wait +%l %fIf you use xemacs instead of emacs, you use (gnuserve-start) in
your .emacs , and set XEDITOR to gnuclient -q +%l %f
For using Vim, set For using NEdit, set If can also make your editor jump to the exact location of the note
you clicked. This is only supported on Emacs and VIM. Users of Emacs version
20 must apply the patch #(ly:set-point-and-click 'line-column)and set XEDITOR to emacsclient --no-wait +%l:%c %f . Vim
users can set XEDITOR to gvim --remote +:%l:norm%c| %f .
BUGS When you convert the TeX file to PostScript using Skipping corrected musicThe property \relative c'' { c8 d \property Score.skipTypesetting = ##t e f g a g c, f e d \property Score.skipTypesetting = ##f c d b bes a g c2 } Staff notationThis section deals with music notation that occurs on staff level, such as keys, clefs and time signatures. Staff symbolThe lines of the staff symbol are formed by the
StaffSymbol
object. This object is created at the moment
that their context is created. You can not change the appearance of
the staff symbol by using BUGS If you end a staff half way a piece, the staff symbol may not end exactly on the barline. Key signatureSetting or changing the key signature is done with the
Here, type should be This command sets the context property The printed signature is a KeySignature object, typically created in Staff context. ClefThe clef can be set or changed with the \key f\major c''2 \clef alto g'2 Supported clef-names include
By adding \clef "G_8" The object for this symbol is Clef . This command is equivalent to setting Time signatureThe time signature is set or changed by the \time 2/4 c'2 \time 3/4 c'2. The actual symbol that's printed can be customized with the The object for this symbol is TimeSignature
. There are
many more options for its layout. They are selected through the
This command sets the property More options are available through the Scheme function
\score { \notes \relative c'' { #(set-time-signature 9 8 '(2 2 2 3)) g8 g d d g g a8-[-( bes g-]-) | #(set-time-signature 5 8 '(3 2)) a4. g4 } \paper { linewidth = -1.0 \translator { \StaffContext \consists "Measure_grouping_engraver" }}} PartialPartial measures, for example in upbeats, are entered using the
\partial 4* 5/16 c'16 c4 f16 a'2. ~ a'8. a'16 | g'1 The syntax for this command is \partial durationThis is internally translated into \property Timing.measurePosition = -length of durationThe property measurePosition contains a rational number
indicating how much of the measure has passed at this point.
Unmetered musicBar lines and bar numbers are calculated automatically. For unmetered
music (e.g. cadenzas), this is not desirable. The commands
c'2. \cadenzaOn c2 \cadenzaOff c4 c4 c4 The property Bar linesBar lines are inserted automatically, but if you need a special type
of barline, you can force one using the c4 \bar "|:" c4 The following bar types are available c4 \bar "|" c \bar "" c \bar "|:" c \bar "||" c \bar ":|" c \bar ".|" c \bar ".|." c \bar "|." You are encouraged to use In scores with many staves, the barlines are automatically placed at top level, and they are connected between different staves of a StaffGroup : < \context StaffGroup < \context Staff = up { e'4 d' \bar "||" f' e' } \context Staff = down { \clef bass c4 g e g } > \context Staff = pedal { \clef bass c2 c2 } > The objects that are created at Staff level. The name is BarLine . The command
PolyphonyThe easiest way to enter such fragments with more than one voice on a
staff is to split chords using the separator \context Voice = VA \relative c'' { c4 < { f d e } \\ { b c2 } > c4 < g' \\ b, \\ f \\ d > } The separator causes Voice
contexts to be instantiated,
bearing the names Sometimes, it is necessary to instantiate these contexts by hand: For
Instantiate a separate Voice context for each part, and use
\relative c'' \context Staff < \context Voice = VA { \voiceOne cis2 b } \context Voice = VB { \voiceThree b4 ais ~ ais4 gis4 } \context Voice = VC { \voiceTwo fis4~ fis4 f ~ f } > The identifiers If you want more than four voices, you can also manually set horizontal shifts and stem directions, as is shown in the following example: \context Staff \notes\relative c''< \context Voice=one { \shiftOff \stemUp e4 } \context Voice=two { \shiftOn \stemUp cis } \context Voice=three { \shiftOnn \stemUp ais } \context Voice=four { \shiftOnnn \stemUp fis } > Normally, note heads with a different number of dots are not merged, but
if you set the object property \context Voice < { g'8 g'8 \property Staff.NoteCollision \override #'merge-differently-dotted = ##t g'8 g'8 } \\ { [g'8. f16] [g'8. f'16] } > Similarly, you can merge half note heads with eighth notes, by setting
\context Voice < { c8 c4. \property Staff.NoteCollision \override #'merge-differently-headed = ##t c8 c4. } \\ { c2 c2 } > LilyPond also vertically shifts rests that are opposite of a stem. \context Voice < c''4 \\ r4 > See also NoteCollision and RestCollision BUGS Resolving collisions is a very intricate subject, and LilyPond only
handles a few situations. When it can not cope, you are advised to use
BeamingBeams are used to group short notes into chunks that are aligned with the metrum. They are inserted automatically in most cases. \time 2/4 c8 c c c \time 6/8 c c c c8. c16 c8 If you're not satisfied with the automatic beaming, you can enter the beams explicitly. If you have beaming patterns that differ from the defaults, you can also set the patterns for automatic beamer. See also Beam . Manual beamsIn some cases it may be necessary to override LilyPond's automatic
beaming algorithm. For example, the auto beamer will not beam over
rests or bar lines, If you want that, specify the begin and end point
manually using a \context Staff { r4 r8-[ g' a r8-] r8 g-[ | a-] r8 } Normally, beaming patterns within a beam are determined automatically.
When this mechanism fouls up, the properties
\context Staff { f8-[ r16 f g a-] f8-[ r16 \property Voice.stemLeftBeamCount = #1 f g a-] } The property c16-[ c c c c c c c-] \property Voice.subdivideBeams = ##t c16-[ c c c c c c c-] c32-[ c c c c c c c c c c c c c c c-] \property Score.beatLength = #(ly:make-moment 1 8) c32-[ c c c c c c c c c c c c c c c-]
Kneed beams are inserted automatically, when a large gap between two
adjacent beamed notes is detected. This behavior can be tuned through
the object property BUGS Auto knee beams can not be used together with hara kiri staves. [TODO from bugs] The Automatic beamer does not put unfinished beams on the last notes of a score. Formatting of ties is a difficult subject. LilyPond often does not give optimal results. Setting automatic beam behaviorIn normal time signatures, automatic beams can start on any note but can
only end in a few positions within the measure: beams can end on a beat,
or at durations specified by the properties in
The value of \property Voice.autoBeamSettings \override #'(BE P Q N M) = dur \property Voice.autoBeamSettings \revert #'(BE P Q N M)Here, BE is the symbol begin or end . It determines
whether the rule applies to begin or end-points. The quantity
P/Q refers to the length of the beamed notes (and `*
* ' designates notes of any length), N/M refers to a time
signature (wildcards, `* * ' may be entered to designate all time
signatures).
For example, if you want automatic beams to end on every quarter note, you can use the following: \property Voice.autoBeamSettings \override #'(end * * * *) = #(ly:make-moment 1 4)Since the duration of a quarter note is 1/4 of a whole note, it is entered as (ly:make-moment 1 4) .
The same syntax can be used to specify beam starting points. In this example, automatic beams can only end on a dotted quarter note. \property Voice.autoBeamSettings \override #'(end * * * *) = #(ly:make-moment 3 8)In 4/4 time signature, this means that automatic beams could end only on 3/8 and on the fourth beat of the measure (after 3/4, that is 2 times 3/8 has passed within the measure). You can also restrict rules to specific time signatures. A rule that should only be applied in N/M time signature is formed by replacing the second asterisks by N and M. For example, a rule for 6/8 time exclusively looks like \property Voice.autoBeamSettings \override #'(begin * * 6 8) = ... If you want a rule to apply to certain types of beams, you can use the
first pair of asterisks. Beams are classified according to the shortest
note they contain. For a beam ending rule that only applies to beams
with 32nd notes (and no shorter notes), you would use If a score ends while an automatic beam has not been ended and is still accepting notes, this last beam will not be typeset at all. For melodies that have lyrics, you may want to switch off
automatic beaming. This is done by setting BUGS It is not possible to specify beaming parameters for beams with mixed durations, that differ from the beaming parameters of all separate durations, i.e., you'll have to specify manual beams to get: It is not possible to specify beaming parameters that act differently in different parts of a measure. This means that it is not possible to use automatic beaming in irregular meters such as 5/8 .
AccidentalsThis section describes how to change the way that LilyPond automatically inserts accidentals before the running notes. Using the predefined accidental macrosThe constructs for describing the accidental typesetting rules are
quite hairy, so non-experts should stick to the macros defined in
The macros operate on the "Current" context (see Context properties). This
means that the macros shuold normally be invoked right after the
creation of the context in which the accidental typesetting described
by the macro is to take effect. I.e. if you want to use
piano-accidentals in a pianostaff then you issue
\score { \notes \relative c'' < \context Staff = sa { cis4 d e2 } \context GrandStaff < \pianoAccidentals \context Staff = sb { cis4 d e2 } \context Staff = sc { es2 c } > \context Staff = sd { es2 c } > } The macros are:
Defining your own accidental typesettingsThis section must be considered gurus-only, and hence it must be sufficient with a short description of the system and a reference to the internal documentation. The idea of the algorithm is to try several different rules and then use the rule that gives the highest number of accidentals. Each rule cosists of
As described in the internal documentation of
Accidental_engraver
, the properties BUGS Currently the simultaneous notes are considered to be entered in sequential mode. This means that in a chord the accidentals are typeset as if the notes in the chord happened one at a time - in the order in which they appear in the input file. Of course this is only a problem when you have simultainous notes which accidentals should depend on each other. Notice that the problem only occurs when using non-default accidentals - as the default accidentals only depend on other accidentals on the same staff and same pitch and hence cannot depend on other simultainous notes. This example shows two examples of the same music giving different accidentals depending on the order in which the notes occur in the input file: \property Staff.autoAccidentals = #'( Staff (any-octave . 0) ) cis'4 <<c'' c'>> r2 | cis'4 <<c' c''>> r2 | <<cis' c''>> r | <<c'' cis'>> r | The only solution is to manually insert the problematic
accidentals using Expressive marksSlursA slur indicates that notes are to be played bound or legato. They are entered using parentheses: f'-( g'-)-( a'-) [a'8 b'-(-] a'4 g'2 f'4-) <<c' e'>>2-( <<b d'>>2-) See also Slur . Slurs avoid crossing stems, and are generally attached to note heads.
However, in some situations with beams, slurs may be attached to stem
ends. If you want to override this layout you can do this through the
object property \slurUp \property Voice.Stem \set #'length = #5.5 g'8-(g g4-) \property Voice.Slur \set #'attachment = #'(stem . stem) g8-( g g4-) If a slur would strike through a stem or beam, the slur will be moved away upward or downward. If this happens, attaching the slur to the stems might look better: \stemUp \slurUp d32-( d'4 d8..-) \property Voice.Slur \set #'attachment = #'(stem . stem) d,32-( d'4 d8..-) BUGS Producing nice slurs is a difficult problem, and LilyPond currently uses a simple, empiric method to produce slurs. In some cases, the results of this method are ugly. Phrasing slursA phrasing slur (or phrasing mark) connects chords and is used to
indicate a musical sentence. It is started using \time 6/4 c' \( d ( e-) f ( e-) d-\) Typographically, the phrasing slur behaves almost exactly like a normal
slur. See also PhrasingSlur
. But although they behave
similarily to normal slurs, phrasing slurs count as different objects.
A Note that the commands
Breath marksBreath marks are entered using TempoMetronome settings can be entered as follows: \tempo duration = perminute For example, BUGS The tempo setting is not printed, but is only used in the MIDI output. You can trick lily into producing a metronome mark, though. Details are in Text markup. Text spannersSome textual indications, e.g. rallentando or accelerando, often extend over many measures. This is indicated by following the text with a dotted line. You can create such texts using text spanners. The syntax is as follows: \startTextSpan \stopTextSpanLilyPond will respond by creating a TextSpanner object (typically in Voice context). The string to be printed, as well as the style is set through object properties. An application--or rather, a hack--is to fake octavation indications. \relative c' { a''' b c a \property Voice.TextSpanner \set #'type = #'dotted-line \property Voice.TextSpanner \set #'edge-height = #'(0 . 1.5) \property Voice.TextSpanner \set #'edge-text = #'("8va " . "") \property Staff.centralCPosition = #-13 a\startTextSpan b c a \stopTextSpan } Analysis bracketsBrackets are used in musical analysis to indicate structure in musical
pieces. LilyPond supports a simple form of nested horizontal brackets.
To use this, add the Horizontal_bracket_engraver
to
Staff
context. A bracket is started with
\score { \notes \relative c'' { c4-\groupOpen-\groupOpen c4-\groupClose c4-\groupOpen c4-\groupClose-\groupClose } \paper { \translator { \StaffContext \consists "Horizontal_bracket_engraver" }}} OrnamentsArticulationsA variety of symbols can appear above and below notes to indicate different characteristics of the performance. They are added to a note by adding a dash and the the character signifying the articulation. They are demonstrated here. The script is automatically placed, but if you need to force
directions, you can use c''4^^ c''4_^ Other symbols can be added using the syntax
note Fingering instructions can also be entered in this shorthand. For finger changes, use markup texts: c'4-1 c'4-2 c'4-3 c'4-4 c^\markup { \fontsize #-3 \number "2-3" } See also Script and Fingering . BUGS All of these note ornaments appear in the printed output but have no effect on the MIDI rendering of the music. Unfortunately, there is no support for adding fingering instructions or
ornaments to individual note heads. Some hacks exist, though. See
Text scriptsIn addition, it is possible to place arbitrary strings of text or markup
text (see Text markup) above or below notes by using a string:
By default, these indications do not influence the note spacing, but
by using the command \relative c' { c4^"longtext" \fatText c4_"longlongtext" c4 } It is possible to use TeX commands in the strings, but this should be avoided because it makes it impossible for LilyPond to compute the exact length of the string, which may lead to collisions. Also, TeX commands won't work with direct PostScript output. Text scripts are created in form of TextScript objects, in Voice context. Text markup describes how to change the font or access special symbols in text scripts. Grace notesGrace notes are ornaments that are written out c4 \grace c16 c4 \grace { [c16 d16] } c4 In normal notation, grace notes are supposed to take up no logical time in a measure. Such an idea is practical for normal notation, but is not strict enough to put it into a program. The model that LilyPond uses for grace notes internally is that all timing is done in two steps: Every point in musical time consists of two rational numbers: one denotes the logical time, one denotes the grace timing. The above example is shown here with timing tuples. The advantage of this approach is that you can use almost any lilypond construction together with grace notes, for example slurs and clef changes may appear halfway in between grace notes: c4 \grace { [ c16 c, \clef bass c, b(] } )c4 The placement of these grace notes is synchronized between different staves, using this grace timing. < \context Staff = SA { e4 \grace { c16 d e f } e4 } \context Staff = SB { c4 \grace { g8 b } c4 } > Unbeamed eighth notes and shorter by default have a slash through the
stem. This can be controlled with object property [TODO discuss Scheme functionality.] Notice how the \relative c'' \context Voice { \grace c8 c4 \grace { [c16 c16] } c4 \grace { \property Voice.Stem \override #'stroke-style = #'() c16 \property Voice.Stem \revert #'stroke-style } c4 } If you want to end a note with a grace note, then the standard trick is to put the grace notes before a phantom "space note", e.g. \context Voice { < { d1^\trill ( } { s2 \grace { [c16 d] } } > )c4 } A \relative c'' \context Voice { \slurUp \grace { a4 ( } ) a4 a4 () a2 \slurBoth \grace { \slurUp a4 ( } ) a4 a4 () a2 \slurBoth } BUGS Grace notes can not be used in the smallest size ( Grace note synchronization can also lead to surprises. Staff notation, such as key signatures, barlines, etc. are also synchronized. Take care when you mix staves with grace notes and staves without. < \context Staff = SA { e4 \bar "|:" \grace c16 d4 } \context Staff = SB { c4 \bar "|:" d4 } > Grace sections should only be used within sequential music expressions. Nesting, juxtaposing, or ending sequential music with a grace section is not supported, and might produce crashes or other errors. GlissandoA glissando line can be requested by attaching a c'-\glissando c' BUGS Printing of an additional text (such as gliss.) must be done manually. See also Glissando . DynamicsAbsolute dynamic marks are specified using an identifier after a
note: c'\ppp c\pp c \p c\mp c\mf c\f c\ff c\fff c2\sf c\rfz A crescendo mark is started with c'' \< \! c'' d'' \decr e'' \rced < f''1 { s4 s4 \< \! s4 \> \! s4 } > This may give rise to very short hairpins. Use minimum-length
in Voice.HairPin to lengthen these, e.g.
\property Staff.Hairpin \override #'minimum-length = #5 You can also use a text saying cresc. instead of hairpins. Here is an example how to do it: c4 \cresc c4 \endcresc c4 You can also supply your own texts: \context Voice { \property Voice.crescendoText = "cresc. poco" \property Voice.crescendoSpanner = #'dashed-line a'2\mf\< a a \!a } Dynamics are objects of DynamicText and Hairpin . Vertical positioning of these symbols is handled by the DynamicLineSpanner object. If you want to adjust padding or vertical direction of the dynamics, you must set properties for the DynamicLineSpanner object. Predefined identifiers to set the vertical direction are \dynamicUp and \dynamicDown. RepeatsTo specify repeats, use the
Repeat syntaxThe syntax for repeats is \repeat variant repeatcount repeatbody If you have alternative endings, you may add \alternativewhere each alternative is a music expression. Normal notation repeats are used like this: c'1 \repeat volta 2 { c'4 d' e' f' } \repeat volta 2 { f' e' d' c' } With alternative endings: c'1 \repeat volta 2 {c'4 d' e' f'} \alternative { {d'2 d'} {f' f} } Folded repeats look like this: c'1 \repeat fold 2 {c'4 d' e' f'} \alternative { {d'2 d'} {f' f} } If you don't give enough alternatives for all of the repeats, then the first alternative is assumed to be repeated often enough to equal the specified number of repeats. \context Staff { \relative c' { \partial 4 \repeat volta 4 { e | c2 d2 | e2 f2 | } \alternative { { g4 g g } { a | a a a a | b2. } } } } Repeats and MIDIFor instructions on how to unfoldi repeats for MIDI output, see
the example file BUGS Notice that timing information is not remembered at the start of an
alternative, so you have to reset timing information after a repeat,
e.g. using a bar-check (See Bar check), setting
It is possible to nest Folded repeats offer little more over simultaneous music. Manual repeat commandsThe property
c''4 \property Score.repeatCommands = #'((volta "93") end-repeat) c''4 c''4 \property Score.repeatCommands = #'((volta #f)) c''4 c''4 Repeats brackets are VoltaBracket objects. Tremolo repeatsTo place tremolo marks between notes, use \score { \context Voice \notes\relative c' { \repeat "tremolo" 8 { c16 d16 } \repeat "tremolo" 4 { c16 d16 } \repeat "tremolo" 2 { c16 d16 } \repeat "tremolo" 4 c16 } } Tremolo beams are Beam
objects. Single stem tremolos are
StemTremolo
. The single stem tremolo must be
entered without BUGS Only powers of two and undotted notes are supported repeat counts. Tremolo subdivisionsTremolo marks can be printed on a single note by adding
` c'2:8 c':32 | c': c': | BUGS Tremolos in this style do not carry over into the MIDI output. Measure repeatsIn the \context Voice { \repeat "percent" 4 { c'4 } \repeat "percent" 2 { c'2 es'2 f'4 fis'4 g'4 c''4 } } The signs are represented by these objects: RepeatSlash and PercentRepeat and DoublePercentRepeat . BUGS You can not nest percent repeats, e.g. by filling in the first measure with slashes, and repeating that measure with percents. Rhythmic musicSometimes you might want to show only the rhythm of a melody. This can be done with the rhythmic staff. All pitches of notes on such a staff are squashed, and the staff itself looks has a single staff line: \context RhythmicStaff { \time 4/4 c4 e8 f g2 | r4 g r2 | g1:32 | r1 | } Percussion stavesTo typeset more than one piece of percussion to be played by the same musician one typically uses a multiline staff where each staff position refers to a specific piece of percussion. LilyPond is shipped with a bunch of scheme functions which allows you to do this fairly easily. The system is based on the general midi drum-pitches.
In order to use the drum pitches you include
To typeset the music on a staff you apply the scheme function
\include "drumpitch-init.ly" up = \notes { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat } down = \notes { bassdrum4 snare8 bd r bd sn4 } \score { \apply #(drums->paper 'drums) \context Staff < \clef percussion \context Voice = up { \voiceOne \up } \context Voice = down { \voiceTwo \down } > } In the above example the music was transformed using the list 'drums .
Currently the following lists are defined in scm/drums.scm :
If you don't like any of the predefined lists you can define your own list at the top of your file: #(define mydrums `( (bassdrum default #f ,(ly:make-pitch -1 2 0)) (snare default #f ,(ly:make-pitch 0 1 0)) (hihat cross #f ,(ly:make-pitch 0 5 0)) (pedalhihat xcircle "stopped" ,(ly:make-pitch 0 5 0)) (lowtom diamond #f ,(ly:make-pitch -1 6 0)) )) \include "drumpitch-init.ly" up = \notes { hh8 hh hh hh hhp4 hhp } down = \notes { bd4 sn bd toml8 toml } \score { \apply #(drums->paper 'mydrums) \context Staff < \clef percussion \context Voice = up { \voiceOne \up } \context Voice = down { \voiceTwo \down } > } To use a modified existing list instead of building your own from scratch you can append your modifications to the start of the existing list: #(define mydrums (append `( (bassdrum default #f ,(ly:make-pitch -1 2 0)) (lowtom diamond #f ,(ly:make-pitch -1 6 0)) ) drums )) Percussion staves with normal stavesWhen you include \include "drumpitch-init.ly" up = \notes { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat } down = \notes { bassdrum4 snare8 bd r bd sn4 } \include "nederlands.ly" bass = \notes \transpose c c,, { a4. e8 r e g e } \score { < \apply #(drums->paper 'drums) \context Staff = drums < \clef percussion \context Voice = up { \voiceOne \up } \context Voice = down { \voiceTwo \down } > \context Staff = bass { \clef "F_8" \bass } > } Percussion midi outputIn order to produce correct midi output you need to produce two score
blocks - one for the paper and one for the midi.
To use the percussion channel you set the property \score { \apply #(drums->paper 'mydrums) \context Staff < \clef percussion \context Voice = up { \voiceOne \up } \context Voice = down { \voiceTwo \down } > \paper{} } \score { \context Staff < \property Staff.instrument = #'drums \up \down > \midi{} } BUGS This scheme is to be considered a temporary implementation. Even though the scheme will probably keep on working then the future might bring some other way of typesetting drums, and probably there will be made no great efforts in keeping things downwards compatible. Piano musicPiano music is an odd type of notation. Piano staves are two normal staves coupled with a brace. The staves are largely independent, but sometimes voices can cross between the two staves. The PianoStaff is especially built to handle this cross-staffing behavior. In this section we discuss the PianoStaff and some other pianistic peculiarities. BUGS There is no support for putting chords across staves. You can get
this result by increasing the length of the stem in the lower stave so
it reaches the stem in the upper stave, or vice versa. An example is
included with the distribution as Automatic staff changesVoices can switch automatically between the top and the bottom staff. The syntax for this is \autochange Staff \context Voice { ...music... }The autochanger switches on basis of pitch (central C is the turning point), and it looks ahead skipping over rests to switch rests in advance. Here is a practical example: \score { \notes \context PianoStaff < \context Staff = "up" { \autochange Staff \context Voice = VA < \relative c' { g4 a b c d r4 a g } > } \context Staff = "down" { \clef bass s1*2 } > } Spacer rests are used to prevent the bottom staff from terminating too soon. Manual staff switchesVoices can be switched between staves manually, using the following command: \translator Staff = staffname musicThe string staffname is the name of the staff. It switches the current voice from its current staff to the Staff called staffname. Typically staffname is "up" or
"down" .
PedalsPiano pedal instruction can be expressed using
The symbols that are printed can be modified by setting
Pedals can also be indicated by a sequence of brackets, by setting the
\property Staff.SustainPedal \override #'pedal-type = #'bracket c''4 \sustainDown d''4 e''4 a'4 \sustainUp \sustainDown f'4 g'4 a'4 \sustainUp A third style of pedal notation is a mixture of text and brackets,
obtained by setting \property Staff.SustainPedal \override #'pedal-type = #'mixed c''4 \sustainDown d''4 e''4 c'4 \sustainUp \sustainDown f'4 g'4 a'4 \sustainUp The default '*Ped' style for sustain and damper pedals corresponds to
c''4 \sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4 \sostenutoUp For fine-tuning of the appearance of a pedal bracket, the properties
\property Staff.PianoPedalBracket \override #'shorten-pair = #'(0 . -1.0) c''4 \sostenutoDown d''4 e''4 c'4 f'4 g'4 a'4 \sostenutoUp ArpeggioYou can specify an arpeggio sign on a chord by attaching an
<<c e g c>>-\arpeggio When an arpeggio crosses staves in piano music, you attach an arpeggio
to the chords in both staves, and set
\context PianoStaff < \property PianoStaff.connectArpeggios = ##t \context Voice = one { <<c' e g c>>-\arpeggio } \context Voice = other { \clef bass <<c,, e g>>-\arpeggio} > This command creates Arpeggio
objects. Cross staff arpeggios
are To add an arrow head to explicitly specify the direction of the
arpeggio, you should set the arpeggio object property
\context Voice { \property Voice.Arpeggio \set #'arpeggio-direction = #1 <<c e g c>>-\arpeggio \property Voice.Arpeggio \set #'arpeggio-direction = #-1 <<c e g c>>-\arpeggio } A square bracket on the left indicates that the player should not
arpeggiate the chord. To draw these brackets, set the
\context PianoStaff < \property PianoStaff.connectArpeggios = ##t \property PianoStaff.Arpeggio \override #'molecule-callback = \arpeggioBracket \context Voice = one { <<c' e g c>>-\arpeggio } \context Voice = other { \clef bass <<c,, e g>>-\arpeggio } > BUGS It is not possible to mix connected arpeggios and unconnected arpeggios in one PianoStaff at the same time. Voice follower linesWhenever a voice switches to another staff a line connecting the notes
can be printed automatically. This is enabled if the property
\context PianoStaff < \property PianoStaff.followVoice = ##t \context Staff \context Voice { c1 \translator Staff=two b2 a } \context Staff=two {\clef bass \skip 1*2 } > The associated object is VoiceFollower . Vocal musicFor a discussion of how to put lyrics into a score, see section
[TODO: Move lyrics section from tutorial to here?] See also the sections on Slurs and Breath marks. [TODO: Move slurs / breath marks section to here?] [TODO: Write subsection upon usage of ChoirStaff.] For entering quotes in Lyrics mode, use the following "\"God\"" is "`King'" AmbitusThe term ambitus denotes a range of pitches for a given voice in a part of music. It also may denote the pitch range that a musical instrument is capable of playing. Most musical instruments have their ambitus standardized (or at least there is agreement upon the minimal ambitus of a particular type of instrument), such that a composer or arranger of a piece of music can easily meet the ambitus constraints of the targeted instrument. However, the ambitus of the human voice depends on individual physiological state, including education and training of the voice. Therefore, a singer potentially has to check for each piece of music if the ambitus of that piece meets his individual capabilities. This is why the ambitus of a piece may be of particular value to vocal performers. The ambitus is typically notated on a per-voice basis at the very beginning of a piece, e.g. nearby the initial clef or time signature of each staff. The range is graphically specified by two noteheads, that represent the minimum and maximum pitch. Some publishers use a textual notation: they put the range in words in front of the corresponding staff. Lilypond currently only supports the graphical ambitus notation. To apply, simply add the Ambitus_engraver to the Voice context, as shown in the below example: upper = \notes \relative c { \clef "treble" \key c \minor as'' c e2 bes f cis d4 e f2 g } lower = \notes \relative c { \clef "treble" \key e \major e'4 b g a c es fis a cis b a g f e d2 } \score { \context ChoirStaff { < \context Staff = one { \upper } \context Staff = three { \lower } > } \paper { \translator { \VoiceContext \consists Ambitus_engraver } } } The shape of the note heads to use can be changed via the
\translator { \VoiceContext \consists Ambitus_engraver Ambitus \set #'note-head-style = #'noteheads-2mensural Ambitus \set #'join-heads = ##f } By default, the ambitus grob is put before the clef. You can control
this behaviour through the \translator { \ScoreContext breakAlignOrder = #'( instrument-name left-edge span-bar breathing-sign clef ambitus key-signature staff-bar time-signature custos ) } TablaturesTablature notation is used for notating music for plucked string instruments. It notates pitches not by using note heads, but by indicating on which string and fret a note must be played. LilyPond offers limited support for tablature. Tablatures basicTablature can be typeset with Lilypond by using the TabStaff and TabVoice contexts. As tablature is a recent feature in Lilypond, most of the guitar special effects such as bend are not yet supported. With the TabStaff
, the string number associated to a note
is given as a backslash followed by the string number, e.g. \context TabStaff < \notes { a,4\5 c'\2 a\3 e'\1 e\4 c'\2 a\3 e'\1 } > If you do not specify a string number then lilypond automatically selects one.
The selection is controlled by the translator property Notice that LilyPond does not handle chords in any special way, and hence the automatic string selector may easily select the same string to two notes in a chord. e8 fis gis a b cis' dis' e' \property TabStaff.minimumFret = #8 e8 fis gis a b cis' dis' e' Non-guitar tablaturesThere are many ways to customize Lilypond tablatures. First you can change the number of strings, by setting the number of
lines in the TabStaff
(the (The numbers specified for stringTuning are the numbers of semitons to subtract -- or add -- starting the specified pitch by default middle C, in string order: thus the notes are e, a, d & g) \context TabStaff < \outputproperty #(make-type-checker 'staff-symbol-interface) #'line-count = #4 \property TabStaff.stringTunings = #'(-5 -10 -15 -20) \notes { a,4 c' a e' e c' a e' } > Finally, it is possible to change the Scheme function to format the tablature note text. The default is fret-number-tablature-format, which uses the fret number, but for some instruments that may not use this notation, just create your own tablature-format function. This function takes three argument: the string number, the string tuning and the note pitch. Tablature in addition to normal staffIt is possible to typeset both tablature and a "normal" staff, as commonly done in many parts. A common trick for that is to put the notes in a variables, and to hide the fingering information (which correspond to the string number) for the standard staff. part = \notes { a,4-2 c'-5 a-4 e'-6 e-3 c'-5 a-4 e'-6 } \score { \context StaffGroup < \context Staff < % Hide fingering number \property Staff.Fingering \override #'transparent = ##t \part > \context TabStaff < \property Staff.Stem \override #'direction = #1 \part > > } ChordsLilyPond has support for both entering and printing chords. twoWays = \notes \transpose c c' { \chords { c1 f:sus4 bes/f } <<c e g>> <<f bes c'>> <<f bes d'>> } \score { < \context ChordNames \twoWays \context Voice \twoWays > } This example also shows that the chord printing routines do not try to
be intelligent. If you enter As you can see chords really are a set of pitches. They are internally stored as simultaneous music expressions. This means you can enter chords by name and print them as notes, enter them as notes and print them as chord names, or (the most common case) enter them by name, and print them as name. Chords modeChord mode is a mode where you can input sets of pitches using common
names. It is introduced by the keyword es4. d8 c2 is the notation for an E-flat major chord. Other chords may be entered by suffixing a colon, and introducing a modifier, and optionally, a number, for example \chords { e1:m e1:7 e1:m7 } The first number following the root is taken to be the `type' of the chord, thirds are added to the root until it reaches the specified number, for example. \chords { c:3 c:5 c:6 c:7 c:8 c:9 c:10 c:11 } More complex chords may also be constructed adding separate steps to a chord. Additions are added after the number following the colon, and are separated by dots. For example \chords { c:5.6 c:3.7.8 c:3.6.13 } Chord steps can be altered by suffixing a - or + sign
to the number, for example:
\chords { c:7+ c:5+.3- c:3-.5-.7- } Removals are specified similarly, and are introduced by a caret. They must come after the additions. \chords { c^3 c:7^5 c:9^3.5 } Modifiers can be used to change pitches. The following modifiers are supported
\chords { c:sus4 c:7sus4 c:dim7 c:m6 } Since the unaltered 11 does sound well when combined with the unaltered 3, the 11 is removed in this case, unless it is added explicitly). For example, \chords { c:13 c:13.11 c:m13 } An inversion (putting one pitch of the chord on the bottom), as well
as bass notes, can be specified by appending
\chords { c1 c/g c/f } If you do not want to remove the bass note from the chord, but rather
add the note, then you can use \chords { c1 c/+g c/+f } BUGS Each step can only be present in a chord once. The following
simply produces the augmented chord, since \chords { c:5.5-.5+ } In chord mode, dashes and carets are used to indicate chord additions and subtractions, so articulation scripts can not be entered. Printing named chordsFor displaying printed chord names, use the ChordNames context. The chords may be entered either using the notation described above, or directly using simultaneous music. scheme = \notes { \chords {a1 b c} <<d f g>> <<e g b>> } \score { \notes< \context ChordNames \scheme \context Staff \transpose c c' \scheme > } You can make the chord changes stand out by setting
scheme = \chords { c1:m c:m \break c:m c:m d } \score { \notes < \context ChordNames { \property ChordNames.chordChanges = ##t \scheme } \context Staff \transpose c c' \scheme > \paper{linewidth= 9.\cm} } LilyPond examines chords specified as lists of notes to determine a name to give the chord. LilyPond will not try to identify chord inversions or an added bass note, which may result in strange chord names when chords are entered as a list of pitches: scheme = \notes { <<c' e' g'>>1 <<e' g' c''>> <<e e' g' c''>> } \score { < \context ChordNames \scheme \context Staff \scheme > } The default chord name layout is a system for Jazz music, proposed by Klaus Ignatzek (See Literature). [TODO: add description for banter other jazz.] The Ignatzek chord name formatting can be tuned in a number of ways through the following properties:
Writing partsOrchestral music involves some special notation, both in the full score, as in the individual parts. This section explains how to tackle common problems in orchestral music. Rehearsal marksTo print a rehearsal mark, use the \relative c'' { c1 \mark "A" c1 \mark \default c1 \mark \default c1 \mark "12" c1 \mark \default c1 } As you can see, the mark is incremented automatically if you use
The c1 \mark \markup { \musicglyph #"scripts-ufermata" } c1 The problem is that marks that occur at a line break are typeset only at the beginning of the next line, opposite to what you want for the fermata. This can be corrected by the following property setting \property Score.RehearsalMark \override #'break-visibility = #begin-of-line-invisible Bar numbersBar numbers are printed by default at the start of the line. The
number itself is a property that can be set by modifying the
\property Score.currentBarNumber = #217 To typeset Bar Numbers at regular intervals instead of at the beginning of each line,
you need to change the grob property \property Score.BarNumber \override #'break-visibility = #end-of-line-invisible \property Score.barNumberVisibility = #(every-nth-bar-number-visible 5) \property Score.BarNumber \override #'molecule-callback = #(make-molecule-boxer 0.1 0.25 0.25 Text_item::brew_molecule) \property Score.BarNumber \override #'font-relative-size = #0
If you would like the bar numbers to appear at regular intervals, but
not starting from measure zero, you can use the context function,
resetBarnum = \context Score \applycontext #(set-bar-number-visibility 4) ... \property Score.BarNumber \override #'break-visibility = #end-of-line-invisible \mark "A" \resetBarnum \repeat unfold 10 c1 \mark \default \resetBarnum \repeat unfold 8 c
See also BarNumber . BUGS Barnumbers can collide with the StaffGroup, if there is one at the top. To solve this, You have to twiddle with the padding property of BarNumber if your score starts with a StaffGroup . Instrument namesIn scores, the instrument name is printed before the staff. This can
be done by setting \property Staff.instrument = "ploink " { c''4 } You can also use markup texts to construct more complicated instrument names: \score { \notes \context Staff = treble { \property Staff.instrument = \markup { \column << "Clarinetti" { "in B" \smaller \musicglyph #"accidentals--1" } >> } { c''1 } } \paper { linewidth= 8.0\cm } } BUGS When you put a name on a grand staff or piano staff the width of the brace is not taken into account. You must add extra spaces to the end of the name to avoid a collision. TransposeA music expression can be transposed with \transpose from to musicexpr This means that musicexpr is transposed to by the interval between from is to.
mus =\notes { \key d \major cis d fis g } \score { \notes \context Staff { \clef "F" \mus \clef "G" \transpose c g' \mus \transpose c f' \mus }} If you want to use both Multi measure restsMulti measure rests are entered using ` \time 4/4 r1 | R1 | R1*2 \property Score.skipBars = ##t R1*17 R1*4 The \property Score.skipBars = ##t \time 3/4 R2. | R2.*2 \time 13/8 R1*13/8 R1*13/8*12 Notice that a R spanning a single measure is printed as a whole
rest centered in the measure, regardless of the time signature.
[ add note about breves.] Texts can be added to multi-measure rests by using the
note- \time 3/4 R2._\markup { \roman "Ad lib" } R2.^\fermataMarkup By default, the multi-measure rest uses the number font, which does not contain any letters. This is the reason for the explicit \roman in the above example.
The object for this object is MultiMeasureRest , and MultiMeasureRestNumber . BUGS Only one text can be put on a multi-measure rest with
note-text syntax, since this is internally converted to
setting Currently, there is no way to automatically condense multiple rests into a single multimeasure rest. Multi measure rests do not take part in rest collisions. Automatic part combiningAutomatic part combining is used to merge two parts of music onto a staff in an intelligent way. It is aimed primarily at typesetting orchestral scores. When the two parts are identical for a period of time, only one is shown. In places where the two parts differ, they are typeset as separate voices, and stem directions are set automatically. Also, solo and a due parts can be identified and marked. The syntax for part combining is \partcombine context musicexpr1 musicexpr2where the pieces of music musicexpr1 and musicexpr2 will be combined into one context of type context. The music expressions must be interpreted by contexts whose names should start with one
and two .
The most useful function of the part combiner is to combine parts into one voice, as common for wind parts in orchestral scores: \context Staff < \context Voice=one \partcombine Voice \context Thread=one \relative c'' { g a () b r } \context Thread=two \relative c'' { g r4 r f } > Notice that the first If you just want the merging parts, and not the textual markings, you may set the property soloADue to false. \context Staff < \property Staff.soloADue = ##f \context Voice=one \partcombine Voice \context Thread=one \relative c'' { b4 a c g } \context Thread=two \relative c'' { d,2 a4 g' } > There are a number of other properties that you can use to tweak the
behavior of part combining, refer to the automatically generated
documentation of Thread_devnull_engraver
and
Voice_devnull_engraver
. Look at the documentation of the
responsible engravers, BUGS In Hara kiri stavesIn orchestral scores, staff lines that only have rests are usually removed. This saves some space. LilyPond also supports this through the hara kiri3 staff. This staff commits suicide when it finds itself to be empty after the line-breaking process. It will not disappear when it contains normal rests, you must use multi measure rests. The hara kiri staff is specialized version of the Staff context. It is available as the context identifier
\score { \notes \relative c' < \context Staff = SA { e4 f g a \break c1 } \context Staff = SB { c4 d e f \break R1 } > \paper { linewidth = 6.\cm \translator { \HaraKiriStaffContext } } } Sound output for transposing instrumentsWhen you want to make a MIDI file from a score containing transposed
and untransposed instruments, you have to instruct LilyPond the pitch
offset (in semitones) for the transposed instruments. This is done
using the \property Staff.instrument = #"Cl. in B-flat" \property Staff.transposing = #-2 Ancient notationAncient note headsTo get a longa note head, you have to use mensural note heads. This
is accomplished by setting the \property Voice.NoteHead \set #'style = #'mensural a'\longa Ancient clefsLilyPond supports a variety of clefs, many of them ancient. For modern clefs, see section Clef. For the percussion clef, see
section Percussion staves. For the The following table shows all ancient clefs that are supported via the
Modern style means "as is typeset in current editions of transcribed mensural music". Petrucci style means "inspired by printings published by the famous engraver Petrucci (1466-1539)". Historic style means "as was typeset or written in contemporary historic editions (other than those of Petrucci)". Editio XXX style means "as is/was printed in Editio XXX". Petrucci used C clefs with differently balanced left-side vertical beams, depending on which staffline it was printed. CustodesA custos (plural: custodes; latin word for `guard') is a staff context symbol that appears at the end of a staff line. It anticipates the pitch of the first note(s) of the following line and thus helps the player or singer to manage line breaks during performance, thus enhancing readability of a score. \score { \notes { c'1 \break \property Staff.Custos \set #'style = #'mensural d' } \paper { \translator { \StaffContext \consists Custos_engraver } } }
Custodes were frequently used in music notation until the 17th century. There were different appearances for different notation styles. Nowadays, they have survived only in special forms of musical notation such as via the editio vaticana dating back to the beginning of the 20th century. For typesetting custodes, just put a \paper { \translator { \StaffContext \consists Custos_engraver Custos \override #'style = #'mensural } } The property can also be set locally, for example in a \notes { \property Staff.Custos \override #'style = #'vaticana c'1 d' e' d' \break c' d' e' d' } LigaturesIn musical terminology, a ligature is a coherent graphical symbol that represents at least two different notes. Ligatures originally appeared in the manuscripts of Gregorian chant notation roughly since the 9th century as an allusion to the accent symbols of greek lyric poetry to denote ascending or descending sequences of notes. Both, the shape and the exact meaning of ligatures changed tremendously during the following centuries: In early notation, ligatures where used for monophonic tunes (Gregorian chant) and very soon denoted also the way of performance in the sense of articulation. With upcoming multiphony, the need for a metric system arised, since multiple voices of a piece have to be synchronized some way. New notation systems were invented, that used the manifold shapes of ligatures to now denote rhythmical patterns (e.g. black mensural notation, mannered notation, ars nova). With the invention of the metric system of the white mensural notation, the need for ligatures to denote such patterns disappeared. Nevertheless, ligatures were still in use in the mensural system for a couple of decades until they finally disappeared during the late 16th / early 17th century. Still, ligatures have survived in contemporary editions of Gregorian chant such as the Editio Vaticana from 1905/08. Syntactically, ligatures are simply enclosed by \score { \notes \transpose c c' { \[ g c a f d' \] a g f \[ e f a g \] } } To select a specific style of ligatures, a proper ligature engraver has to be added to the Voice context, as explained in the following subsections. Currently, Lilypond only supports white mensural ligatures with certain limitations. Support for Editio Vaticana will be added in the future. White mensural ligaturesLilypond has limited support for white mensural ligatures. The implementation is still experimental; it currently may output strange warnings or even crash in some cases or produce weird results on more complex ligatures. To engrave white mensural ligatures, in the paper block the MensuralLigature engraver has to be put into the Voice context (and you probably want to remove the LigatureBracket engraver). There is no additional input language to describe the shape of a white mensural ligature. The shape is rather determined solely from the pitch and duration of the enclosed notes. While this approach may take a new user quite a while to get accustomed, it has a great advantage: this way, lily has full musical information about the ligature. This is not only required for correct MIDI output, but also allows for automatic transcription of the ligatures. Example: \score { \notes \transpose c c' { \property Score.timing = ##f \property Score.defaultBarType = "empty" \property Voice.NoteHead \set #'style = #'neo_mensural \property Staff.TimeSignature \set #'style = #'neo_mensural \clef "petrucci_g" \[ g\longa c\breve a\breve f\breve d'\longa \] s4 \[ e1 f1 a\breve g\longa \] } \paper { \translator { \VoiceContext \remove Ligature_bracket_engraver \consists Mensural_ligature_engraver } } } Without replacing \score { \notes \transpose c c' { \property Score.timing = ##f \property Score.defaultBarType = "empty" \property Voice.NoteHead \set #'style = #'neo_mensural \property Staff.TimeSignature \set #'style = #'neo_mensural \clef "petrucci_g" \[ g\longa c\breve a\breve f\breve d'\longa \] s4 \[ e1 f1 a\breve g\longa \] } } Figured bassLilyPond has limited support for figured bass: < \context FiguredBass \figures { <_! 3+ 5- >4 < [4 6] 8 > } \context Voice { c4 g8 } > The support for figured bass consists of two parts: there is an input
mode, introduced by that takes care of making BassFigure objects. In figures input mode, a group of bass figures is delimited by
<4 6> Accidentals are added to the numbers if you alterate them by
appending <4- 6+ 7!> Spaces or dashes may be inserted by using < [4 6] 8 [_ 12]> Although the support for figured bass may superficially resemble chord support, it works much simpler: in figured bass simply stores the numbers, and then prints the numbers you entered. There is no conversion to pitches, and no realizations of the bass are played in the MIDI file. Contemporary notationClustersIn musical terminology, a cluster denotes a range of simultaneously sounding pitches that may change over time. The set of available pitches to apply usually depends on the accoustic source. Thus, in piano music, a cluster typically consists of a continous range of the semitones as provided by the piano's fixed set of a chromatic scale. In choral music, each singer of the choir typically may sing an arbitrary pitch within the cluster's range that is not bound to any diatonic, chromatic or other scale. In electronic music, a cluster (theoretically) may even cover a continuous range of pitches, thus resulting in coloured noise, such as pink noise. Clusters can be notated in the context of ordinary staff notation by engraving simple geometrical shapes that replace ordinary notation of notes. Ordinary notes as musical events specify starting time and duration of pitches; however, the duration of a note is expressed by the shape of the note head rather than by the horizontal graphical extent of the note symbol. In contrast, the shape of a cluster geometrically describes the development of a range of pitches (vertical extent) over time (horizontal extent). Still, the geometrical shape of a cluster covers the area in wich any single pitch contained in the cluster would be notated as an ordinary note. From this point of view, it is reasonable to specify a cluster as the envelope of a set of notes. This is exactly how to construct a cluster with lilypond. \score { \context PianoStaff < \context Voice = voiceI { % same as voiceII, but with ordinary notes \notes \relative c' { c4 f4 a4 <e4 d'4> | \break < g8 a8 > < e8 a8 > a4 c1 < d4 b4 > e4 | c4 a4 f4 g4 a4 } } \context Voice = voiceII { % same as voiceI, but with cluster notation \notes \relative c' { % hide notes, accidentals, etc. \property Thread.NoteHead \set #'transparent = ##t \property Voice.Stem \set #'transparent = ##t \property Voice.Beam \set #'transparent = ##t \property Staff.Accidental \set #'transparent = ##t \property Voice.Cluster \set #'padding = #0.01 \property Voice.Cluster \set #'shape = #'ramp c4 f4 \startCluster a4 <e4 d'4> | \break < g8 a8 > < e8 a8 > a4 c1 < d4 b4 > e4 | c4 \stopCluster a4 f4 g4 a4 } } > } Note that the second voice differs from the first one only by the
additional keywords Also note that a music expression like By default, cluster engraver is in the voice context. This allows putting ordinary notes and clusters together in the same staff, even simultaneously. However, in such a case no attempt is made to automatically avoid collisions between ordinary notes and clusters. The geometrical shape can be further controlled with grob properties
Tuning outputLilyPond tries to take as much formatting as possible out of your hands. Nevertheless, there are situations where it needs some help, or where you want to override its decisions. In this section we discuss ways to do just that. Formatting is internally done by manipulating so called objects (graphic objects). Each object carries with it a set of properties (object properties) specific to that object. For example, a stem object has properties that specify its direction, length and thickness. The most direct way of tuning the output is by altering the values of these properties. There are two ways of doing that: first, you can temporarily change the definition of a certain type of object, thus affecting a whole set of objects. Second, you can select one specific object, and set a object property in that object. Tuning groups of objectsA object definition is a Scheme association list, that is stored in a
context property. By assigning to that property (using plain
c'4 \property Voice.NoteHead = #'() c'4 This mechanism is fairly crude, since you can only set, but not modify, the definition of an object. Also, it will thoroughly confuse LilyPond. The definition of an object is actually a list of default object
properties. For example, the definition of the Stem object (available
in (thickness . 0.8) (beamed-lengths . (0.0 2.5 2.0 1.5)) (Y-extent-callback . ,Stem::height) ... You can add a property on top of the existing definition, or remove a property, thus overriding the system defaults: c'4 \property Voice.Stem \override #'thickness = #4.0 c'4 \property Voice.Stem \revert #'thickness c'4 You should balance \override and \revert . If that's too
much work, you can use the \set shorthand. It performs a revert
followed by an override. The following example gives exactly the same
result as the previous one.
c'4 \property Voice.Stem \set #'thickness = #4.0 c'4 \property Voice.Stem \set #'thickness = #0.8 c'4 If you use \set , you must explicitly restore the default.
Formally the syntax for these constructions is \property context.grobname \override symbol = value \property context.grobname \set symbol = value \property context.grobname \revert symbolHere symbol is a Scheme expression of symbol type, context and grobname are strings and value is a Scheme expression. If you revert a setting which was not set in the first place, then it
has no effect. However, if the setting was set as a system default, it
may remove the default value, and this may give surprising results,
including crashes. In other words, These are examples of correct nesting of A clumsy but correct form: \override \revert \override \revert \override \revert Shorter version of the same: \override \set \set \revert A short form, using only \set \set \set \set to default value If there is no default (i.e. by default, the object property is unset), then you can use \set \set \set \revert For the digirati, the object description is an Scheme association
list. Since a Scheme list is a singly linked list, we can treat it as a
stack, and BUGS LilyPond will hang or crash if value contains cyclic references.
The backend is not very strict in type-checking object properties. If you
Tuning per objectTuning a single object is most often done with \once \property ...applies a setting only during one moment in the score: notice how the original setting for stem thickness is restored automatically in the following example c4 \once \property Voice.Stem \set #'thickness = #4 c4 c4 A second way of tuning objects is the more arcane \outputproperty predicate symbol = valueHere predicate is a Scheme function taking a object argument, and
returning a boolean. This statement is processed by the
Output_property_engraver . It instructs the engraver to feed all
objects that it sees to predicate. Whenever the predicate returns
true, the object property symbol will be set to value.
This command is only single shot, in contrast to You will need to combine this statement with In the following example, all note heads occurring at current staff
level, are shifted up and right by setting their \relative c'' { c4 \context Staff \outputproperty #(make-type-checker 'note-head-interface) #'extra-offset = #'(0.5 . 0.75) <<c e g>>8 } In this example, the predicate checks the #(define (make-text-checker text) (lambda (grob) (equal? text (ly:get-grob-property grob 'text)))) \score { \notes\relative c''' { \property Voice.Stem \set #'direction = #1 \outputproperty #(make-text-checker "m.d.") #'extra-offset = #'(-3.5 . -4.5) a^2^"m.d." } } BUGS If possible, avoid this feature: the semantics are not very clean, and the syntax and semantics are up for rewrite. Font selectionThe most common thing to change about the appearance of fonts is
their size. The font size of a Voice
,
Staff
or Thread
context, can be easily
changed by setting the This command will not change the size of variable symbols, such as beams or slurs. You can use this command to get smaller symbol for cue notes, but that involves some more subtleties. An elaborate example of those is in input/test/cue-notes.ly .
The font used for printing a object can be selected by setting
\property Staff.TimeSignature \set #'font-name = #"cmr17"You may use any font which is available to TeX, such as foreign fonts or fonts that do not belong to the Computer Modern font family. Font selection for the standard fonts, TeX's Computer Modern fonts, can also be adjusted with a more fine-grained mechanism. By setting the object properties described below, you can select a different font. All three mechanisms work for every object that supports font-interface .
For any of these properties, the value \property Lyrics.LyricText \override #'font-series = #'bold \property Lyrics.LyricText \override #'font-family = #'typewriter \property Lyrics.LyricText \override #'font-shape = #'* There are also pre-cooked font selection qualifiers. These are
selected through the object property The size of the font may be scaled with the object property
BUGS Relative size is not linked to any real size. There is no style sheet provided for other fonts besides the TeX family, and the style sheet can not be modified easily. Text markupLilyPond has an internal mechanism to typeset texts. You can access it
with the keyword c1^\markup { hello } c1_\markup { hi there } c1^\markup { hi \bold there, is \italic anyone home? } The line of the example demonstrates font switching commands. Notice that the command only apply to the first following word; enclose a set of texts with braces to apply a command to more words. \markup { \bold { hi there } }For clarity, you can also do this for single arguments, e.g. \markup { is \italic { anyone } home } The following size commands set abolute sizes
You can also make letter larger or smaller relative to their neighbors,
with the commands The following font change commands are defined:
Raising and lowering texts can be done with c1^\markup { E "=" mc \super "2" } If you want to give an explicit amount for lowering or raising, use
c1^\markup { C \small \raise #1.0 { "9/7+" }} The argument to \raise is the vertical displacement amount,
measured in (global) staff spaces.
Other commands taking single arguments include
In markup mode you can compose expressions, similar to mathematical
expressions, XML documents and music expressions. The braces group
notes into horizontal lines. Other types of lists also exist: you can
stack expressions grouped with c1^\markup { \column << a bbbb c >> } c1^\markup { \center << a bbbb c >> } c1^\markup { \line << a b c >> } The markup mechanism is very flexible and extensible. Refer to
One practical application of complicated markup is to fake a metronome marking: eighthStem = \markup \combine \musicglyph #"flags-stem" \translate #'(0.0 . 3.5) \musicglyph #"flags-u3" eighthNote = \markup \override #'(word-space . 0.0) { \musicglyph #"noteheads-2" \translate #'(-0.05 . 0.1) \eighthStem } \score { \notes\relative c'' { a1^\markup { \magnify #0.9 \eighthNote " = 64" } } } BUGS LilyPond does not account for kerning in its text formatting, so it spaces texts slightly too wide. Syntax errors for markup mode are confusing. Global layoutThe global layout determined by three factors: the page layout, the line breaks and the spacing. These all influence each other: The choice of spacing determines how densely each system of music is set, where line breaks breaks are chosen, and thus ultimately how many pages a piece of music takes. In this section we will explain how the lilypond spacing engine works, and how you can tune its results. Globally spoken, this procedure happens in three steps: first, flexible distances ("springs") are chosen, based on durations. All possible line breaking combination are tried, and the one with the best results--a layout that has uniform density and requires as little stretching or cramping as possible--is chosen. When the score is processed by TeX, page are filled with systems, and page breaks are chosen whenever the page gets full. Vertical spacingThe height of each system is determined automatically by lilypond, to keep systems from bumping into each other, some minimum distances are set. By changing these, you can put staves closer together, and thus put more systems onto one page. Normally staves are stacked vertically. To make
staves maintain a distance, their vertical size is padded. This is
done with the property \property Staff.minimumVerticalExtent = #'(-4 . 4)This sets the vertical size of the current staff to 4 staff-space on either side of the center staff line. The argument of minimumVerticalExtent is interpreted as an interval, where the
center line is the 0, so the first number is generally negative. you
could also make the staff larger at the bottom by setting it to
(-6 . 4) . The default value is (-6 . 6) .
Vertical aligment of staves is handled by the VerticalAlignment object, which lives at Score level. The piano staves are handled a little differently: to make cross-staff beaming work correctly, it necessary that the distance between staves is fixed. This is also done with a VerticalAlignment object, created in PianoStaff
, but a forced distance is
set. This is done with the object property #'forced-distance. If you
want to override this, use a \translator { \PianoStaffContext VerticalAlignment \override #'forced-distance = #9 }This would bring the staves together at a distance of 9 staff spaces, and again this is measured from the center line of each staff. Horizontal SpacingThe spacing engine translates differences in durations into stretchable distances ("springs") of differing lengths. Longer durations get more space, shorter durations get less. The basis for assigning spaces to durations, is that the shortest durations get a fixed amount of space, and the longer durations get more: doubling a duration adds a fixed amount of space to the note. For example, the following piece contains lots of half, quarter and 8th notes, the eighth note is followed by 1 note head width. The The quarter note is followed by 2 NHW, the half by 3 NHW, etc. c2 c4. c8 c4. c8 c4. c8 c8 c8 c4 c4 c4 These two amounts of space are If one would follow the above procedure exactly, then adding a single 32th note to a score that uses 8th and 16th notes, would widen up the entire score a lot. The shortest note is no longer a 16th, but a 64th, thus adding 2 noteheads of space to every note. To prevent this, the shortest duration for spacing is not the shortest note in the score, but the most commonly found shortest note. Notes that are even shorter this are followed by a space that is proportonial to their duration relative to the common shortest note. So if we were to add only a few 16th notes to the example above, they would be followed by half a NHW: c2 c4. c8 c4. [c16 c] c4. c8 c8 c8 c4 c4 c4 The most common shortest duration is determined as follows: in every
measure, the shortest duration is determined. The most common short
duration, is taken as the basis for the spacing, with the stipulation
that this shortest duration should always be equal to or shorter than
1/8th note. The shortest duration is printed when you run lilypond
with In the introduction it was explained that stem directions influence
spacing. This is controlled with BUGS Spacing is determined on a score wide basis. If you have a score that changes its character (measured in durations) half way during the score, the part containing the longer durations will be spaced too widely. Generating optically pleasing spacing is black magic. LilyPond tries to deal with a number of frequent cases. Here is an example that is not handled correctly, due to the combination of chord collisions and kneed stems. Font sizeThe Feta font provides musical symbols at seven different sizes. These fonts are 11 point, 13 point, 16 point, 19 pt, 20 point, 23 point, and 26 point. The point size of a font is the height of the five lines in a staff when displayed in the font. Definitions for these sizes are the files \include "paper26.ly" \score { ... } The font definitions are generated using a Scheme function. For more
details, see the file Line breakingLine breaks are normally computed automatically. They are chosen such that it looks neither cramped nor loose, and that consecutive lines have similar density. Occasionally you might want to override the automatic breaks; you can
do this by specifying If you want linebreaks at regular intervals, you can use the following: < \repeat 7 unfold { s1 * 4 \break } real music >This makes the following 28 measures (assuming 4/4 time) be broken every 4 measures. Page layoutThe most basic settings influencing the spacing are The page layout process happens outside lilypond. Ly2dvi sets page
layout instructions. Ly2dvi responds to the following variables in the
If the variable Page breaks are normally computed by TeX, so they are not under
direct control of LilyPond. However, you can insert a commands into
the To change the paper size, you must first set the
\paper{ papersize = "a4" } \include "paper16.ly" The file SoundLilyPond can produce MIDI output. The performance lacks lots of interesting effects, such as swing, articulation, slurring, etc., but it is good enough for proof-hearing the music you have entered. Ties, dynamics and tempo changes are interpreted. Dynamic marks, crescendi and decrescendi translate into MIDI volume
levels. Dynamic marks translate to a fixed fraction of the available
MIDI volume range, crescendi and decrescendi make the the volume vary
linearly between their two extremities. The fractions be adjusted by
overriding the For each type of musical instrument (that MIDI supports), a volume range
can be defined. This gives you basic equalizer control, which can
enhance the quality of the MIDI output remarkably. You can add
instruments and ranges or change the default settings by overriding the
Both loudness controls are combined to produce the final MIDI volume. MIDI blockThe MIDI block is analogous to the paper block, but it is somewhat
simpler. The
Assignments in the Context definitions follow precisely the same syntax as within the
\paper block. Translation modules for sound are called performers.
The contexts for MIDI output are defined in MIDI instrument namesThe MIDI instrument name is set by the BUGS If the selected string does not exactly match, then LilyPond uses the default (Grand Piano). It is not possible to select an instrument by number. Advanced TopicsWhen translating the input to notation, there are number of distinct phases. We list them here: The purpose of LilyPond is explained informally by the term `music typesetter'. This is not a fully correct name: Not only does the program print musical symbols, it also makes aesthetic decisions. Symbols and their placements are generated from a high-level musical description. In other words, LilyPond would be best described to be a `music compiler' or `music to notation compiler'. LilyPond is linked to GUILE, GNU's Scheme library for extension programming. The Scheme library provides the glue that holds together the low-level routines and separate modules which are written in C++. When lilypond is run to typeset sheet music, the following happens:
During these stages different types of data play the the main role: During parsing, Music objects are created. During the interpretation, contexts are constructed, and with these contexts a network of graphical objects (`grobs') is created. These grobs contain unknown variables, and the network forms a set of equations. After solving the equations and filling in these variables, the printed output is written to an output file. These threemanship of tasks (parsing, translating, typesetting) and data-structures (music, context, graphical objects) permeates the entire design of the program.
The data types that are mentioned here are all discussed in this section. Interpretation contextInterpretation contexts are objects that only exist during a run of
LilyPond. During the interpretation phase of LilyPond (when it prints
During this interpretation, the interpretation context holds the state for the current point within the music. It contains information like
Contexts are grouped hierarchically: A Voice context is contained in a Staff context (because a staff can contain multiple voices at any point), a Staff context is contained in Score , StaffGroup , or ChoirStaff context. Contexts associated with sheet music output are called notation
contexts, those for sound output are called performance
contexts. The default definitions of the standard notation and
performance contexts can be found in Creating contextsContexts for a music expression can be selected manually, using the following music expression. \context contexttype [= contextname] musicexpr This instructs lilypond to interpret musicexpr within the context of type contexttype and with name contextname. If this context does not exist, it will be created. \score { \notes \relative c'' { c4 <d4 \context Staff = "another" e4> f } } In this example, the Default contextsMost music expressions don't need an explicit \score { \notes \context Voice = goUp { c'4 d' e' } } There are some quirks that you must keep in mind when dealing with defaults: First, every top level music is interpreted by the Score context; in other
words, you may think of \score { \context Score music } Second, contexts are created automatically to be able to interpret the music expressions. Consider the following example. \score { \context Score \notes { c'4-( d' e'-) } } The sequential music is interpreted by the Score context initially
(notice that the Context evaluationScheme code can be used to modify contexts. The syntax for this is \applycontext function function should be a Scheme function taking a single argument, being the context to apply it with. The following code will print the current bar number on the standard output during the compile. \applycontext #(lambda (tr) (format #t "\nWe were called in barnumber ~a.\n" (ly:get-context-property tr 'currentBarNumber))) Context propertiesNotation contexts have properties. These properties are from
the \property contextname.propname = value Sets the propname property of the context contextname to the specified Scheme expression value. All propname and contextname are strings, which are typically unquoted. Properties that are set in one context are inherited by all of the contained contexts. This means that a property valid for the Voice context can be set in the Score context (for example) and thus take effect in all Voice contexts. If you don't wish to specify the name of the context in the
context, but you can force another context with the
\property contextname.propname = value and \context contextname \property Current.propname = value do the same thing. The main use for this is in macros - allowing the specification of a property-setting without restriction to a specific context. Properties can be unset using the following expression: \property contextname.propname \unset This removes the definition of propname in contextname. If propname was not defined in contextname (but was inherited from a higher context), then this has no effect. BUGS The syntax of Engravers and performers[TODO] Basic building blocks of translation are called engravers; they are special C++ classes. Changing context definitionsThe most common way to define a context is by extending an existing context. You can change an existing context from the paper block by first initializing a translator with an existing context identifier: \paper { \translator { context-identifier } } Then you can add and remove engravers using the following syntax: \remove engravername \consists engravername Here engravername is a string, the name of an engraver in the system. \score { \notes { c'4 c'4 } \paper { \translator { \StaffContext \remove Clef_engraver } } } You can also set properties in a translator definition. The syntax is as follows: propname = value propname \set grob-propname = pvalue propname \override grob-propname = pvalue propname \revert grob-propname propname is a string, grob-propname a symbol, value
and To simplify editing translators, all standard contexts have standard
identifiers called name Defining new contextsIf you want to build a context from scratch, you must also supply the following extra information:
This is an example: \translator
The argument of
Other modifiers are
In the \paper { foo = \translator { ... } } \score { \notes { ... } \paper { \translator { \foo ... } } } Syntactic detailsThis section describes details that were too boring to be put elsewhere. IdentifiersAll of the information in a LilyPond input file is internally represented as a Scheme value. In addition to normal Scheme data types (such as pair, number, boolean, etc.), LilyPond has a number of specialized data types,
LilyPond also includes some transient object types. Objects of these types are built during a LilyPond run, and do not `exist' per se within your input file. These objects are created as a result of your input file, so you can include commands in the input to manipulate them, during a LilyPond run.
Music expressionsMusic in LilyPond is entered as a music expression. Notes, rests, lyric
syllables are music expressions, and you can combine music expressions
to form new ones, for example by enclosing a list of expressions in
\sequential { c4 d4 } The two basic compound music expressions are simultaneous and sequential music. \sequential For both, there is a shorthand:
for sequential and
for simultaneous music. In principle, the way in which you nest sequential and simultaneous to produce music is not relevant. In the following example, three chords are expressed in two different ways: \notes \context Voice { <a c'> <b d'> <c' e'> < { a b c' } { c' d' e' } > } However, using < and > for chords turns up various
syntactical peculiarities. For this reason, a special syntax for
chords was introduced in version 1.7: << >> .
Other compound music expressions include \repeat expr \transpose from to expr \apply func expr \context type = id expr \times fraction expr Manipulating music expressionsThe \apply #func music This means that func is applied to music. The function func should return a music expression. This example replaces the text string of a script. It also shows a dump of the music it processes, which is useful if you want to know more about how music is stored. #(define (testfunc x) (if (equal? (ly:get-mus-property x 'text) "foo") (ly:set-mus-property! x 'text "bar")) ;; recurse (ly:set-mus-property! x 'elements (map testfunc (ly:get-mus-property x 'elements))) (display x) x) \score { \notes \apply #testfunc { c'4_"foo" } } For more information on what is possible, see the automatically generated documentation. Directly accessing internal representations is dangerous: The implementation is subject to changes, so you should avoid this feature if possible. A final example is a function that reverses a piece of music in time: #(define (reverse-music music) (let* ((elements (ly:get-mus-property music 'elements)) (reversed (reverse elements)) (span-dir (ly:get-mus-property music 'span-direction))) (ly:set-mus-property! music 'elements reversed) (if (ly:dir? span-dir) (ly:set-mus-property! music 'span-direction (- span-dir))) (map reverse-music reversed) music)) music = \notes { c'4 d'4( e'4 f'4 } \score { \context Voice { \music \apply #reverse-music \music } } More examples are given in the distributed example files in
AssignmentsIdentifiers allow objects to be assigned to names during the parse
stage. To assign an identifier, use name An identifier can be created with any string for its name, but you will only be able to refer to identifiers whose names begin with a letter, being entirely alphabetical. It is impossible to refer to an identifier whose name is the same as the name of a keyword. The right hand side of an identifier assignment is parsed completely before the assignment is done, so it is allowed to redefine an identifier in terms of its old value, e.g. foo = \foo * 2.0 When an identifier is referenced, the information it points to is copied. For this reason, an identifier reference must always be the first item in a block. \paper { foo = 1.0 \paperIdent % wrong and invalid } \paper { \paperIdent % correct foo = 1.0 } Lexical modesTo simplify entering notes, lyrics, and chords, LilyPond has three
special input modes in addition to the default mode: note, lyrics, and
chords mode. These input modes change the way that normal, unquoted
words are interpreted: For example, the word A mode switch is entered as a compound music expression
In each of these cases, these expressions do not add anything to the meaning of their arguments. They just instruct the parser in what mode to parse their arguments. Different input modes may be nested. AmbiguitiesThe grammar contains a number of ambiguities. We hope to resolve them at some time.
Lexical detailsEven more boring details, now on the lexical side of the input parser. Direct SchemeLilyPond internally uses GUILE, a Scheme-interpreter. Scheme is a
language from the LISP family. You can learn more about Scheme at
http://www.scheme.org. It is used to represent data throughout
the whole program. The hash-sign ( LilyPond contains a Scheme interpreter (the GUILE library) for internal use. In some places, Scheme expressions also form valid syntax: Wherever it is allowed, #scheme evaluates the specified Scheme code. Example: \property Staff.TestObject \override #'foobar = #(+ 1 2)
In-line Scheme may be used at the top level. In this case the result is discarded. Scheme is a full-blown programming language, and a full discussion is outside the scope of this document. Interested readers are referred to the website http://www.schemers.org/ for more information on Scheme. RealsFormed from an optional minus sign and a sequence of digits followed
by a required decimal point and an optional exponent such as
A real constant can be followed by one of the dimension keywords:
StringsBegins and ends with the Output detailsLilyPond's default output format is TeX. Using the option At the beginning of the output file, various global parameters are defined.
It also contains a large Then the file Now the music is output system by system (a `system' consists of all
staves belonging together). From TeX's point of view, a system is an
After the last system LilyPond emits a stronger variant of
\def\lilypondpaperlastpagefill{1} or by setting the variable It is possible to fine-tune the vertical offset further by defining the
macro \def\lilypondscoreshift{0.25\baselineskip}
The code produced by LilyPond can be used by both TeX and LaTeX. Here an example how to embed a small LilyPond file \documentclass{article} \def\lilypondpaperlastpagefill{} \lineskip 5pt \def\lilypondscoreshift{0.25\baselineskip} \begin{document} This is running text which includes an example music file \input{foo.tex} right here. \end{document} The file lilypond foo.ly It is important to set the The call to Invoking LilyPondUsage: lilypond [option]... file... When invoked with a filename that has no extension, LilyPond will try
to add When LilyPond processes Command line optionsThe following options are supported:
Environment variablesFor processing both the TeX and the PostScript output, you must have appropriate environment variables set. The following scripts do this:
They should normally be sourced as part of your login process. If these scripts are not run from the system wide login process, then you must run it yourself. If you use sh, bash, or a similar shell, then add the following to
your . lilypond-profile If you use csh, tcsh or a similar shell, then add the following to
your source lilypond-login These scripts set the following variables
The LilyPond binary itself recognizes the following environment variables
Reporting bugsSince there is no finder's fee which doubles every year, there is no need to wait for the prize money to grow. So send a bug report today! LilyPond development moves quickly, so if you have a problem, it is wise to check if it has been fixed in a newer release. If you think you found a bug, please send in a bugreport. When you send us a bugreport, we have to diagnose the problem and if possible, duplicate it. To make this possible, it is important that you include the following information in your report:
You can send the report to bug-lilypond@gnu.org. This is a mailinglist, but you don't have to be subscribed to it to post. WebsiteIf you are reading this manual in print, it is possible that the website contains updates to the manual. You can find the lilypond website at http://www.lilypond.org/. Invoking ly2dviNicely titled output is created through a separate program:
ly2dvi [option]... file... To have ly2dvi read from stdin, use a dash Ly2dvi supports the following options:
Titling layoutLy2dvi extracts the following header fields from the LY files to
generate titling. An example demonstrating all these fields is in
Additional parametersLy2dvi responds to several parameters specified in a
Environment variables
Integrating text and music with lilypond-bookIf you want to add pictures of music to a document, you can simply do
it the way you would do with other types of pictures. You write
LilyPond code, process it separately to embedded PostScript or
It can work on LaTeX, TODO: explain how to use lilypond fonts in text. Integrating Texinfo and musicYou specify the LilyPond code like this: @lilypond[options, go, here] YOUR LILYPOND CODE @end lilypond @lilypond[options, go, here]{ YOUR LILYPOND CODE } @lilypondfile[options, go, here]{filename} Then you run lilypond-book on it, and the result is a file you can process with texinfo. We show two simple examples here. First a complete block: @lilypond[26pt] c' d' e' f' g'2 g' @end lilypond produces this music: Then the short version: @lilypond[11pt]{<<c' e' g'>>} and its music:
When producing texinfo, lilypond-book also generates bitmaps of the music, so you can make a HTML document with embedded music. Integrating LaTeX and musicYou specify LilyPond code like this: \begin[options, go, here]{lilypond} YOUR LILYPOND CODE \end{lilypond} \lilypondfile[options, go,here]{filename} or \lilypond{ YOUR LILYPOND CODE } Then you run lilypond-book on it, and the result is a file you can process with LaTeX. We show some examples here. \begin[26pt]{lilypond} c' d' e' f' g'2 g'2 \end{lilypond} produces this music: Then the short version: \lilypond[11pt]{<<c' e' g'>>} and its music: You can use whatever commands you like in the document preamble,
the part of the document before After The music will be surrounded by Integrating HTML and musicYou specify LilyPond code like this: <lilypond relative1 verbatim> \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4 </lilypond> Then you run lilypond-book on it, and the result is a file you can process with LaTeX. The final result look like <lilypond relative1 verbatim> \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4 </lilypond> For inline pictures, use Some music in <lilypond a b c/> a line of text. A special feature not (yet) available in other output formats, is the
<ly2dvifile>trip.ly</ly2dvifile>This runs trip.ly through ly2dvi (See also Invoking ly2dvi), and substitutes a preview image in the output. The image
links to a separate HTML file, so clicking it will take the viewer to
a menu, with links to images, midi and printouts.
Music fragment optionsThe commands for lilypond-book have room to specify options. These are all of the options:
Invoking lilypond-bookWhen you run
For LaTeX input, the file to give to LaTeX has extension If you use If you want to add titling from the \input titledefs.tex \def\preLilypondExample{\def\mustmakelilypondtitle{}}
BugsThe LaTeX The Texinfo command Almost all LaTeX commands that change margins and line widths are ignored. There is no way to automatically apply
Converting from other formatsInvoking convert-lyConvert-ly sequentially applies different conversions to upgrade a
Lilypond input file. It uses convert-ly -e --to=1.3.150 `find . -name '*.ly' -print` The program is invoked as follows: convert-ly [option]... file... The following options can be given:
BUGS Not all language changes are handled. Only one output options can be specified. Invoking midi2lyMidi2ly translates a MIDI input file to a LilyPond source file. MIDI (Music Instrument Digital Interface) is a standard for digital instruments: it specifies cabling, a serial protocol and a file format. The MIDI file format is a de facto standard format for exporting music from other programs, so this capability may come in useful when you want to import files from a program that has no converter for its native format. It is possible to record a MIDI file using a digital keyboard, and then
convert it to Hackers who know about signal processing are invited to write a more robust midi2ly. midi2ly is written in Python, using a module written in C to parse the MIDI files. It is invoked as follows: midi2ly [option]... midi-file The following options are supported by midi2ly:
Invoking etf2lyETF (Enigma Transport Format) is a format used by Coda Music Technology's Finale product. etf2ly will convert part of an ETF file to a ready-to-use LilyPond file. It is invoked as follows: etf2ly [option]... etf-file The following options are supported by etf2ly.
BUGS The list of articulation scripts is incomplete. Empty measures confuse etf2ly. Invoking abc2lyABC is a fairly simple ASCII based format. It is described at the abc site: http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txtabc2ly translates from ABC to LilyPond. It is invoked as follows: abc2ly [option]... abc-file The following options are supported by abc2ly:
There is a rudimentary facility for adding lilypond code to the ABC source file. If you say: %%LY voices \property Voice.autoBeaming=##f This will cause the text following the keyword "voices" to be inserted into the current voice of the lilypond output file. Similarly: %%LY slyrics more words will cause the text following the "slyrics" keyword to be inserted into the current line of lyrics. BUGS The ABC standard is not very "standard". For extended features (eg. polyphonic music) different conventions exist. Multiple tunes in one file cannot be converted. ABC synchronizes words and notes at the beginning of a line; abc2ly does not. abc2ly ignores the ABC beaming. Invoking pmx2lyPMX is a MusiXTeX preprocessor written by Don Simons. More information on PMX is available from the following site: http://icking-music-archive.sunsite.dk/Misc/Music/musixtex/software/pmx/. pmx2ly converts from PMX to LilyPond input. The program is invoked as follows: pmx2ly [option]... pmx-file The following options are supported by pmx2ly:
BUGS This script was updated last in September 2000, and then successfully
converted the Invoking musedata2lyMusedata (http://www.musedata.org/) is an electronic library of
classical music scores, currently comprising about 800 composition
dating from 1700 to 1825. The music is encoded in so-called Musedata
format. musedata2ly converts a set of musedata files to one .ly file,
and will include a musedata2ly [option]... musedata-files The following options are supported by musedata2ly:
BUGS musedata2ly converts only a small subset musedata. Invoking mup2lyMUP (Music Publisher) is a shareware music notation program by Arkkra Enterprises. It is also the name of the input format. Mup2ly will convert part of a Mup file to a ready-to-use LilyPond file. Mup2ly is invoked as follows: mup2ly [option]... mup-file The following options are supported by mup2ly:
BUGS Currently, only plain notes (pitches, durations), voices and staves are converted. LiteratureIf you need to know more about music notation, here are some
interesting titles to read. The source archive includes a more
elaborate BibTeX bibliography of over 100 entries in
Index
Refman appendixLyrics mode definitionThe definition of lyrics mode is ludicrous, and this will remain so until the authors of LilyPond acquire a deeper understanding of character encoding, or someone else steps up to fix this. A word in Lyrics mode begins with: an alphabetic character, Subsequent characters of a word can be any character that is not a digit
and not white space. One important consequence of this is that a word
can end with ` American ChordsJazz chordsMIDI instruments"acoustic grand" "contrabass" "lead 7 (fifths)" "bright acoustic" "tremolo strings" "lead 8 (bass+lead)" "electric grand" "pizzicato strings" "pad 1 (new age)" "honky-tonk" "orchestral strings" "pad 2 (warm)" "electric piano 1" "timpani" "pad 3 (polysynth)" "electric piano 2" "string ensemble 1" "pad 4 (choir)" "harpsichord" "string ensemble 2" "pad 5 (bowed)" "clav" "synthstrings 1" "pad 6 (metallic)" "celesta" "synthstrings 2" "pad 7 (halo)" "glockenspiel" "choir aahs" "pad 8 (sweep)" "music box" "voice oohs" "fx 1 (rain)" "vibraphone" "synth voice" "fx 2 (soundtrack)" "marimba" "orchestra hit" "fx 3 (crystal)" "xylophone" "trumpet" "fx 4 (atmosphere)" "tubular bells" "trombone" "fx 5 (brightness)" "dulcimer" "tuba" "fx 6 (goblins)" "drawbar organ" "muted trumpet" "fx 7 (echoes)" "percussive organ" "french horn" "fx 8 (sci-fi)" "rock organ" "brass section" "sitar" "church organ" "synthbrass 1" "banjo" "reed organ" "synthbrass 2" "shamisen" "accordion" "soprano sax" "koto" "harmonica" "alto sax" "kalimba" "concertina" "tenor sax" "bagpipe" "acoustic guitar (nylon)" "baritone sax" "fiddle" "acoustic guitar (steel)" "oboe" "shanai" "electric guitar (jazz)" "english horn" "tinkle bell" "electric guitar (clean)" "bassoon" "agogo" "electric guitar (muted)" "clarinet" "steel drums" "overdriven guitar" "piccolo" "woodblock" "distorted guitar" "flute" "taiko drum" "guitar harmonics" "recorder" "melodic tom" "acoustic bass" "pan flute" "synth drum" "electric bass (finger)" "blown bottle" "reverse cymbal" "electric bass (pick)" "skakuhachi" "guitar fret noise" "fretless bass" "whistle" "breath noise" "slap bass 1" "ocarina" "seashore" "slap bass 2" "lead 1 (square)" "bird tweet" "synth bass 1" "lead 2 (sawtooth)" "telephone ring" "synth bass 2" "lead 3 (calliope)" "helicopter" "violin" "lead 4 (chiff)" "applause" "viola" "lead 5 (charang)" "gunshot" "cello" "lead 6 (voice)" The Feta fontThe following symbols are available in the Feta font and may be
accessed directly using text markup such as
GNU Free Documentation LicenseVersion 1.1, March 2000
Copyright © 2000 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
ADDENDUM: How to use this License for your documentsTo use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: Copyright (C) year your name. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being list their titles, with the Front-Cover Texts being list, and with the Back-Cover Texts being list. A copy of the license is included in the section entitled ``GNU Free Documentation License''. If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being list"; likewise for Back-Cover Texts. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software. Footnotes
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Go back to index of LilyPond.
Please send GNU LilyPond questions and comments to lilypond-user@gnu.org. Please send comments on these web pages to (address unknown) Copyright (c) 1997--2002 Han-Wen Nienhuys and Jan Nieuwenhuizen. Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved. |
This page was built from LilyPond-1.7.14 (development-branch) by