![]() |
GNU LilyPondWelcome to the home of the GNU Music Typesetter |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
This document is also available as a gzipped postscript file. GNU LilyPond -- The music typesetterLilyPond produces sheet music from input files. This document describes how to use LilyPond. 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 soon 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. The rest is, as they say, history. You're reading the preface of the manual for LilyPond 1.4, which is in all honesty, the first release of LilyPond that combines stability, flexibility and good documentation. We hope you will have as much fun in using LilyPond as we have when hacking it. This manual was written to help you learn LilyPond, but as you might imagine, we ourselves don't have much to learn about it. We can't really judge whether the manual is helpful for users, but maybe you can! Don't hesitate to tell us if you find any part of the manual vague, unclear or outdated. Han-Wen and Jan Utrecht/Amsterdam, The Netherlands, March 2001. TutorialThe music is described in a text file, using a simple music language. LilyPond reads that text file and generates music that you can print or view. Therefore, creating music notation with LilyPond is done in two steps. Using a text editor, you write down the notes to print. Then, you run LilyPond to get your printed output. 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 a slightly more elaborate example of real music. This piece introduces and explains some finer details of LilyPond. Then, a number of more complex examples follow, that will help you to produce most complex music with LilyPond. First stepsThis section shows how easy writing music with LilyPond actually is. If you have not seen LilyPond input source before, this section is for you. The next section has a table (see Simple legend) of all symbols that are introduced here, you may want to keep an eye on that. Writing music with LilyPond is explained below by a number of small examples. Each example has a small piece of text; the LilyPond input that you should type, with the resulting music printed below it. You get a simple note by typing its note name, from c d e f g a b 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 duration is used: a 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 violin \clef bass \clef alto \clef tenor From these commands and notes, a piece of music can be formed. A piece
of music is made by enclosing it in " \notes { \time 3/4 \clef bass c2 e4 g2. f4 e d c2. } At this point, the piece of music is ready to be printed. This is done by combining 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 { } } We continue with the introduction of the remaining musical constructs. 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 entering a tilde " g'4 ~ g' a'2 ~ a'4 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. Don't worry about all the quotes. \score { \notes { \time 4/4 \clef violin \key d \minor 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. Firstly, 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. Secondly, bar lines and beams are drawn automatically. Thirdly, LilyPond calculates line breaks for you; it doesn't matter where you make new lines in the source file. The example also indicates that a piece of music written in a high register needs lots of quotes. This makes the input a bit unreadable, and is therefore also a potential source of errors. The solution is to use "relative octave" mode. In practice, most music is entered using this mode. To use relative mode, add If you type no octaviation quotes, relative mode chooses the note that
is closest to the previous one, which is often just the one you need.
For example: \relative c'' { c f c g c } You can make a large interval by adding octaviation 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, } 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. Surround the notes to be grouped 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 typeset a melody with two staffs now: \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 staffs. 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 are started with the commands c2\< \!c2-\ff \>c2 \!c2 Chords can be made by surrounding notes with r4 <c e g> <c f a> Of course, you can combine beams and ties with chords. Notice that beam and tie markings are placed outside the chord markers: r4 [<c8 e g> <c8 f a>] ~ <c8 f a> When you want to combine chords with slurs and dynamics, an annoying
technical detail crops up: you have type these commands next to the
notes, which means that they have to be inside the r4 <c8 e g \> ( > <c e g> <c e g> < ) \! c8 f a> A nasty technical detail also crops up when you start a score with a chord: \score { \notes <c'1 e'1> } The program can not guess that you want the notes on only one staff. To
force the chord on a staff, add \score { \notes \context Staff <c'1 e'1> } This is the end of the simple tutorial. 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 to type some simple examples, and experiment a little. When you're comfortable with the basics, then you might want to read the rest of this chapter. It also a manual in tutorial-style, but it is much more in-depth. It will also be very intimidating if you're not familiar with the basics. It deals with some of the more advanced features of LilyPond. Topics include lyrics, chords, orchestral scores and parts, fine tuning output, polyphonic music, and integrating text and music. Simple legend
Running LilyPondYou write music with LilyPond as follows: first you edit a text file containing a description of the notes. Then you run LilyPond on the file. This leaves you with an output file, which you can view or print. In this section we explain how to run LilyPond, and view or print the output. If you have not used LilyPond before, want to test your setup of LilyPond, or try to run an example file yourself, then 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. You begin with opening a terminal window, and start up a text editor.
For example, open an xterm and execute \score { \notes { c'4 e' g' } } To run LilyPond, you invoke ly2dvi to compile your LilyPond source file: ly2dvi -P test.ly You will see the following on your screen: GNU LilyPond 1.4.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 you are satisfied with the looks of the music displayed on your screen, you can print the PS file 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 you can't get the examples to print, then you should look into installing and configuring ghostscript. Refer to GhostScript's website at http://www.ghostscript.com. Windows usersWindows users start the terminal by clicking on the LilyPond icon.
Notepad is sufficient for editing the LilyPond file. Viewing the PS file
can be done with The first real tuneThe rest of this tutorial will demonstrate how to use Lilypond by presenting examples of input along with resulting output. We will use English terms for notation. In case you are not familiar with those, you may consult the glossary that is distributed with LilyPond. The examples discussed are included in the distribution, in the
subdirectory To demonstrate what LilyPond input looks like, we start off with a
full-fledged, yet simple example. It is a convoluted version
of the famous minuet in J. S. Bach's Klavierbüchlein. The file
is included in the distribution as % all text after a percent sign is a comment % and is ignored by LilyPond \include "paper16.ly" \score { \notes \relative c'' \sequential { \time 3/4 \key g \major \repeat "volta" 2 { d4 g,8 a b c d4 g, g | e'4 c8 d e fis g4 g, g | c4 d8( )c b a( )b4 c8 b a g | a4 [b8 a] [g fis] g2. | } b'4 g8 a b g a4 d,8 e fis d | g4 e8 fis g d cis4 b8 cis a4 | a8-. b-. cis-. d-. e-. fis-. g4 fis e | fis a, r8 cis8 d2.-\fermata \bar "|." } \paper { % standard settings are too big and wide for a book indent = 1.0 \cm linewidth = 15.0 \cm } }
We will analyse the input, line by line. % all text after a percent sign is a comment % and is ignored by LilyPondPercent signs introduce comments: everything after a percent sign is ignored. You can use this to write down mental notes to yourself. You can also make longer comments by enclosing text in %{ and
%} .
\include "paper16.ly"By default, LilyPond will typeset the music in a size such that each staff is 20 point (0.7 cm, or 0.27 inch) high. We want smaller output (16 point staff height), so we must import the settings for that size, which is done here. \score {Music is printed by combining a piece of music with directions for outputting it. This combination is formed in the \score block.
\notesPrepare LilyPond for accepting notes. \relative c'' Even though a piece of music often spans a range of several octaves, it mostly moves in small intervals. LilyPond has a special entry mode to save typing in this situation. In this "relative" octave mode, octaves of notes without quotes are chosen such that a note is as close as possible (graphically, on the staff) to the preceding note. If you add a high-quote an extra octave is added. A lowered quote (a comma) will subtract an extra octave. Because the first note has no predecessor, you have to give the (absolute) pitch of the note to start with. \sequential {What follows is sequential music, i.e., notes that are to be played and printed after each other. \time 3/4Set (or change) the time signature of the current piece: a 3/4 sign is printed. The time signature setting is also used to generate bar lines at the right spots. \key g \majorSet (or change) the current key signature to G-major. Although in this example, the \key command happened to be entered after the
\time command, in the output the time signature will be printed
after the key signature; LilyPond knows about music typesetting
conventions.
\repeat "volta" 2The following piece of music is played twice. The first argument indicates the type of repeat. In this case, "volta" means that
prima volta/secunda volta brackets are used for the alternative
endings--if there were any.
{The subject of the repeat is again sequential music. Since \sequential is such a common construct, a shorthand is provided:
just leave off \sequential , and the result is the same.
d4 g,8Two notes. The first note is a quarter note with relative pitch d . The relative music was started with a c'' , so the real
pitch of this note is d'' . The duration of a note is designated
by a number; the 4 here represents a quarter note.
The second note is an eight note with relative pitch a bTwo more notes, with pitch a and b . Because their
duration is the same as the g,8 , there is no need to enter the
duration, but you may enter it anyway, i.e., a4 b4
d4 g, g |Three more notes. The | character is a "bar check". LilyPond
will verify that bar checks are found at the start of a measure. This can
help you track down typing errors.
c8 d e fisSo far, no notes were chromatically altered. Here is the first one that is: fis . LilyPond by default uses Dutch2 note names, and "Fis" is the Dutch note name for "F
sharp". However, there is no sharp sign in the output. The program
keeps track of key signatures, and will only print accidentals if they
are needed.
For groups of eighth notes and shorter, LilyPond can determine how the notes should form a beam. In this case, the 4 eights are automatically printed as a beam. c4 d8( )c b a( )b4 c8 b a g |The beginning and ending notes of a slur are marked with parentheses, ( and ) for start and end respectively. The line above
indicates two slurs. These slur markers (parentheses) are entered
between the slurred notes.
a4 [b8 a] [g fis]Automatic beaming can be overridden by inserting beam marks, [
and ] . These beam markers (brackets) are put around the notes
you want beamed.
g2. |A period adds a dot to the note. }The end of the sequential music to be repeated. LilyPond will typeset a repeat bar. cis'4 b8 cis a4 |Accidentals are printed whenever necessary: the first C sharp of the bar will be printed with an accidental, the second one without. a8-. b-. cis-. d-. e-. fis-.You can enter articulation signs either in a verbose form or using a shorthand. Here we demonstrate the shorthand: it is formed by a dash and the character for the articulation to use, e.g. -. for
staccato as shown above.
fis a, r8 cis8 Rests are denoted by the special note name d2.-\fermataAll articulations have a verbose form, like \fermata . The
command \fermata is not part of the core of the language, but it
is a shorthand for a more complicated description of a fermata symbol.
\fermata names that description and is therefore called an
identifier.
\bar "|." }Here the music ends. LilyPond does not automatically typeset an end bar, we must explicitly request one, using "|." .
\paper { % standard settings are too big and wide for a book indent = 1.0\cm linewidth = 15.0\cm }The \paper block specifies how entered music should be converted
to notation output. Most of the details of the conversion (font sizes,
dimensions, etc.) have been taken care of, but to fit the output in this
document, it has to be narrower. We do this by setting the line width
to 14 centimeters (approximately 5.5 inches).
}The last brace ends the \score block.
Lyrics and chordsIn this section we show how to typeset a song. This file is
included as \header { title = "The river is flowing" composer = "Traditional" } \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 "|." } text = \lyrics { The ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the ri -- ver is flo -- wing down to the sea. } 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 \addlyrics \context Staff = mel { \property Staff.noAutoBeaming = ##t \property Staff.automaticMelismata = ##t \melody } \context Lyrics \text } \midi { \tempo 4=72 } \paper { linewidth = 10.0\cm } } The result would look this.3 The river is flowing Traditional
Again, we will dissect the file line by line. \header {Information about the music you are about to typeset goes into a \header block. The information in this block is not used by
LilyPond, but it is passed into the output. ly2dvi uses this
information to print titles above the music.
title = "The river is flowing" composer = "Traditional (?)"the \header block contains assignments. In each assignment, a
variable is set to a value. Lexically, both the variable name and the
assigned value are strings. The values have to be quoted here, because
they contain spaces. The variable names could also be put within quotes
but it is not necessary.
\include "paper16.ly"Smaller size 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 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 of one eighth. \key c \minorThe key is C minor: we have three flats. 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 {Another identifier assignment. This one is for the lyrics. Lyrics are formed by syllables that have duration, and not by notes. To make LilyPond parse words as syllables, switch it into lyrics mode with \lyrics . Again, the brace after \lyrics
is a shorthand for \sequential { .
The4 ri -- ver is flo- __ wing, flo -- wing and gro -- wing, the ri- ver is flo- __ wing down to the sea. }The syllables themselves are separated by spaces. You can get syllable extenders by entering __ , and centered hyphens with
- - . We enter the syllables as if they are all quarter notes
in length (hence the 4 ), and use a feature to align the
syllables to the music, which obviously isn't all quarter notes.
accompaniment =\chords {We'll put chords over the music. To enter them, there is 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- f:3-.7 A chord is started by the tonic of the chord. The
first one lasts a half note. An unadorned note creates a major
triad. Since a minor triad is wanted, d:min es4 c8:min r8 Some modifiers have predefined names, e.g. 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, 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 during a run of LilyPond. By default, LilyPond will create a Staff context for you. If you would
remove the We don't want that default here, because we want chord names. The
command above explicitly creates an interpretation context of
\addlyrics The lyrics should be aligned with the melody. This is done by
combining both with \context Staff = mel { The first argument of \property Staff.noAutoBeaming = ##tAn interpretation context has variables, called properties, that tune its behavior. One of the variables is noAutoBeaming . Setting
this Staff's property to ##t , which is the boolean value true,
turns the automatic beaming mechanism off for the current staff.
LilyPond 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 ( If Scheme scares you, don't worry. You don't need to know Scheme to create beautiful sheet music. \property Staff.automaticMelismata = ##tSimilarly, we don't want to print a syllable when there is a slur. This sets up \addlyrics to not put lyrics under each
separate note while there is a slur.
\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.
\context Lyrics \textThe second argument of \addlyrics is the text. The text also
should not land on a Staff, but on a interpretation context for
syllables, extenders, hyphens etc. This context is called
Lyrics.
\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 the piece will be set in two lines. More movements[FIXME: merge here with, or move this to: Other ways to run LilyPond] You probably ran
For example, consider the following file ( \version "1.4.0" \header { title = "Two miniatures" tagline = "small is beautiful" } #(set! point-and-click line-column-location) \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" } } The titling in this manual was not generated by ly2dvi, so we can't exactly show what it would look like, but the result should resemble this: Two miniatures Opus 1. Up
Opus 2. Down
This file is produced by ly2dvi in a few stages, with the help of text
formatting tools. LilyPond produces two output files,
Next, now we'll look at the example line by line to explain new things. \version "1.4.0"Lilypond and its language are still under development, and occasionally, details of the syntax are changed. This fragment indicates for which version the input file was written. 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 \header { title = "Two miniatures" }This sets the titling information for the entire file. tagline = "small is beautiful"A signature line is printed at the bottom of the last page. This signature is produced from the tagline field of
\header . Many people find the default "Lily was here,
version number" too droll. If that is the case, assign
something else to tagline , as shown above.
#(set! point-and-click line-column-location) This piece of Scheme code sets the Scheme variable
Editing input files can be quite complicated if you're working with large files: if you're digitizing existing music, you have to synchronize the .ly file, the sheet music on your lap and the sheet music on the screen. The point-and-click mechanism makes it easy to find the origin of an error in the LY file: when you view the file with Xdvi and click on a note, your editor will jump to the spot where that note was entered. For more information, see Point and click. \paper { The linewidth = -1.0 } The variable \score { \notes { c'4 d'4 } In previous examples, 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 specify When you're copying music from existing sheet music, relative octaves are probably the easiest to use: it's less typing work 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. A piano excerptOur fourth 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. It was composed around 1740. It's in the source package
under the name \include "paper16.ly" stemDown = \property Voice.Stem \override #'direction = #-1 stemUp = \property Voice.Stem \override #'direction = #1 stemBoth = \property Voice.Stem \revert #'direction viola = \notes \relative c' \context Voice = viola { <c4-\f-\arpeggio g' c> \stemDown g'8. b,16 s1 s2. r4 g } oboes = \notes \relative c'' \context Voice = oboe { \stemUp s4 g8. b,16 c8 r <e'8.^\p g> <f16 a> \grace <e8( g> <d4 )f> <c2 e> \times 2/3 { <d8 \< f> <e g> <f a> } < { \times 2/3 { a8 g c } \! c2 } \context Voice = oboeTwo { \stemDown \grace { \property Grace.Stem \override #'direction = #-1 [f,16 g] } f8 e e2 } > \stemBoth \grace <c,8( e> <)b8. d8.-\trill> <c16 e> | [<d ( f> < )f8. a>] <)b,8 d> r [<d16( f> <f8. )a>] <b,8 d> r | [<c16( e> < )e8. g>] <c8 e,> } hoomPah = \repeat unfold 8 \notes \transpose c' { \stemUp c8 \stemBoth \stemDown c'8 \stemBoth } bassvoices = \notes \relative c' { c4 g8. b,16 \autochange Staff \hoomPah \translator Staff = down \stemDown [c8 c'8] r4 <g d'> r4 < {\stemUp r2 <e4 c'> <c8 g'> } \context Voice = reallyLow {\stemDown g2 ~ | g4 c8 } > } \score { \context PianoStaff \notes < \context Staff = up < \time 2/2 \viola \oboes > \context Staff = down < \time 2/2 \clef bass \bassvoices > > \midi { } \paper { indent = 0.0 linewidth = 15.0 \cm } }
If this looks like incomprehensible gibberish to you, you are right. This example has been doctored to have as many quirks as possible. As you can see, this example features multiple voices on one staff. To make room for those voices, their notes have to be stemmed in opposite directions. Printed symbols are internally represented by so-called Graphical
Objects (more colloquially: Grobs). These statements concern the
grob called `Stem'. Each grob is described by a bunch of settings. These
setting determine the fonts, offsets, sub-routines to be called on the
grob, etc. The initial values of these settings are set in the Scheme
file stemDown = \property Voice.Stem \override #'direction = #-1 Set a property for all Stem grobs in the current Voice:
\property Voice.Stem \revert #'direction Revert the to the previous setting. The effect of precisely one
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 others). 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 ').
<c4-\f-\arpeggio g' c>The delimiters < and > are shorthands for
\simultaneous { and } . The expression enclosed in
< and > is a chord.
\stemDown 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 .
\stemUp s4 g8. b,16 c8 r <e'8.-\p g> <f16 a> \stemUp is a reference to the \property \override command
defined above.
\grace <e8 g> < d4 f> <c2 e>
\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.
{ <d8 \< f> <e g> <f a> }The piece of music to be `tripletted' is sequential music containing three notes. On the first chord, a crescendo is started with \< . To be precise, the crescendo start is syntactically attached
to the preceding note, the d .
<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 crescendo is ended at the half note by the escaped exclamation
mark \context Voice = oboeTwo { \stemDownWe can't share stems with the other voice, so we have to create a new Voice context. We give it the name oboeTwo to distinguish
it from the other context. Stems go down in this voice.
\grace {When a grace section is processed, a Grace context is
created. This context acts like a miniature score of its own. It has
its own time bookkeeping, and you can make notes, beams, slurs
etc. Here we fiddle with a property and make a beam. The argument of
\grace is sequential music.
\property Grace.Stem \override #'direction = #-1 [f,16 g] } Normally, grace notes are always stem up, but in this case, the upper voice interferes, so we set the stems down here. As far as relative mode is concerned, the previous note is the
f8 e e2 } >This ends the two-part section. \stemBoth \grace <c,8( e> <)b8. d8.-\trill> <c16 e> |
The bass has a little hoom-pah melody to demonstrate parts switching between staffs. 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 circumventing relative mode. Relative mode
can not be used together with transposition, so bassvoices = \notes \relative c' { c4 g8. b,16 \autochange Staff \hoomPah Voices can switch between staffs. The easiest way to get this, is to use
\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 chords
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. An orchestral scoreOur last two examples show a way to setup the music for an orchestral score. When typesetting a piece for several instruments, you'll want to create a conductor's full score, alongside several individual parts. 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, If you were to run LilyPond on this file, no printable output would be produced. % 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 go through the input line by line, but only indicate and explain the 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 staffs except those
for transposing instruments.
The full scoreThe second file, % os-score.ly \include "os-music.ly" \include "paper13.ly" #(set! point-and-click line-column-location) #(define text-flat '((font-relative-size . -2) (music "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 = #'(lines "Timpani" "(C-G)") \property Staff.instr = #"Timp." \clef bass \Key \timpani > > \context StaffGroup = brass < \context Staff = trombe < \property Staff.midiInstrument = #"trumpet" \property Staff.instrument = #`(lines "2 Trombe" "(C)") \property Staff.instr = #`(lines "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 = #`(lines "Corno" (columns "(E" ,text-flat ")")) \property Staff.instr = #`(lines "Cor." (columns "(E" ,text-flat ")")) \property Staff.transposing = #3 \notes \key bes \major \context Voice=one \corno > > > \paper { indent = 15 * \staffspace linewidth = 60 * \staffspace textheight = 90 * \staffspace \translator{ \HaraKiriStaffContext } } \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 .
#(set! point-and-click line-column-location)In a large orchestral score like this you're bound to make some small mistakes, so we enable point and click (See Point and click) editing. #(define text-flat '((font-relative-size . -2) (music "accidentals--1"))) When naming the tuning of the french horn, we'll 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 < \globalOf course, all staffs 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. A bar number internally is a Grob called BarNumber. BarNumber Grobs can be manipulated through their side-position-interface. One of the properties of a side-position-interface that can be tweaked is the padding: the amount of extra space that is put between this Grob and other Grobs. 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. \context StaffGroup = woodwind < \context Staff = flauti <A new notation context: the StaffGroup. StaffGroup can hold one or more Staffs, and will print a big bracket at the left of the score. Start 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, that 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."And define the instrument names to be printed in the margin, instrument for the first line of the score, instr 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 actually 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 only shows 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. The Thread takes care of note heads and rests, the 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 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 before 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 backend to transpose this staff by three steps. Note how we can choose different tuning for entering, printing and
playing, using \notes \key bes \majorTherefore, it has a different key. indent = 15 * \staffspace linewidth = 60 * \staffspaceWe specify a big indent for the first line and a small linewidth for this tutorial. Usually, LilyPond's predefined 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 has only
rests during one line of the score. The 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 contract pieces of consecutive empty bars. LilyPond will do this if Score's skipBars property to true. Other ways to run LilyPondUntil now, you have been using Secondly, you can generate PostScript directly. This is useful if you can not or do not want to run TeX on your system. To obtain direct PostScript output, invoke LilyPond as follows: lilypond -f ps test.lyYou have to set some environment variables to view or print this output. More information can be found in Invoking LilyPond. Since the direct Postscript generation has some problems, it is recommended to use ly2dvi .
Thirdly, if you want to do special things with your output, you can run invoke LilyPond directly: lilypond test.lyto produce plain TeX output. Note that LaTeX will not work on the resulting test.tex . You must run plain TeX on it.
Integrating text and musicSometimes, you might want to use music examples in a text that you are writing. For example, if you are writing 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 wordprocessor. However, there is a also an automated procedure: If you use 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, a number of 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} also shows the LilyPond code, \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 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 $ lilypond-book --outdir=out/ lilbook.tex lilypond-book (GNU LilyPond) 1.3.146 Reading `/home/hanwen/usr/src/lilypond-1.3.146/input/tutorial/lilbook.tex' Reading `/home/hanwen/usr/src/lilypond-1.3.146/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 more or less looks like this: In a lilypond-book document, you can freely mix music and text. For example:
If you have no
In the example you see here, a number of things happened: a
c'4 f bes eshi 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 tutorialThat's all folks. From here, you can either try fiddling with input
files, or you can read the reference manual. You can find more example
files in Reference ManualThis document describes GNU LilyPond and its input format. The last revision of this document was made for LilyPond 1.4.1. It supposes a passing familiarity with how LilyPond input works. New users are encouraged to study the tutorial first. The reference manual is ordered according to different tasks. More details on the property setting mechanisms and context handling is provided in Tuning output and Interpretation context. The syntactical details are described at the end of the manual. OverviewThe 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 by `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 (in the form of molecules) 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. Note entryThe most basic forms of music are notes. We discuss how you enter them
here. Notes on their own don't form valid input, but for the sake of
brevity we omit obligatory lint such as NotesA note specification has the form pitch[!][?][duration] The alteration refers to what note is heard, not to whether an
accidental is printed. This is done depending on the key and context.
A reminder accidental
can be forced by adding an exclamation mark cis' d' e' cis' c'? d' e' c'! PitchesThe verbose syntax for pitch specification is \pitch scmpitch scmpitch is a pitch scheme object, see Pitch data type. 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
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 The optional octave specification takes the form of a series of
single quote (` c' c'' es' g' as' gisis' ais' RestsRests are entered like notes, with note name ` Skips\skip duration sduration Skips the amount of time specified by duration. If no other music is played, a gap will be left for the skipped time without any notes printed. The shorthand is only available in Note and Chord mode. DurationsThe syntax for a verbose duration specification is \duration scmdurationHere, scmduration is a Scheme object of type Duration . See
Duration for more information.
In Note, Chord, and Lyrics mode, durations may be designated by numbers and dots: durations are entered as their reciprocal values. For notes longer than a whole you must use identifiers. 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
To 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
If the duration is omitted then it is set to the previous duration
entered. At the start of parsing a quarter note is assumed. The
duration can be followed by dots (` a'4. b'4.. c'8.
You can alter the length of duration by a fraction N/M by
appending ` TiesA tie connects two adjacent note heads of the same pitch. When used
with chords, it connects all the note heads whose pitches match.
Ties are indicated using the tilde symbol ` e' ~ e' <c' e' g'> ~ <c' e' g'>
If you dislike the amount of ties created for a chord, you 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.
The name of the tie grob is BUGS At present, the tie is implemented as a separate thing, temporally located in between the notes. There is also no way to convert between tied notes, dotted notes and plain notes. Tieing 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. TupletsTuplets are made out of a music expression by multiplying all duration with a fraction. \times fraction musicexpr The duration of musicexpr will be multiplied by the fraction. In print, 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 = #(make-moment 1 4) \times 2/3 { c''8 c c c c c }
The format of the number is determined by the property
The typesetting of brackets and numbers is controlled by the properties
\property Voice.TupletBracket \set #'tuplet-bracket-visibility = ##t \times 2/3{c'8 d e} \times 2/3{d4 e8} \property Voice.TupletBracket \set #'tuplet-bracket-visibility = #'if-no-beam \times 2/3{c d e} \times 2/3{d4 e8} \property Voice.TupletBracket \set #'tuplet-bracket-visibility = ##f \times 2/3{c d e} \times 2/3{d4 e8} \property Voice.TupletBracket \set #'tuplet-number-visibility = ##f \times 2/3{c d e} \times 2/3{d4 e8} \property Voice.TupletBracket \set #'tuplet-number-visibility = #'if-no-beam \times 2/3{c d e} \times 2/3{d4 e8}
Tuplet brackets are printed as Defining pitch namesNote names and chord modifiers can be customized for nationalities. The syntax is as follows. \pitchnames scheme-alist \chordmodifiers scheme-alist See 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. \include "paper23.ly" \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 either by using dvips or
the Staff notationKey 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 ClefThe clef can be set or changed with the \clef clefname Shortcut for \property Staff.clefGlyph = glyph associated with clefname \property Staff.clefPosition = clef Y-position for clefname \property Staff.clefOctavation = extra transposition of clefname Any change in these properties creates a clef (a Supported clef-names include
By adding Supported associated glyphs (for
Modern style means "as is typeset in current editions." Historic style means "as was typeset or written in contemporary historic editions". Editio XXX style means "as is/was printed in Editio XXX." Time signatureThe time signature is set or changed by the \time n
Internally, this is a shortcut for doing
\property Score.timeSignatureFraction = #'(n . d) \property Score.beatLength = #(make-moment 1 d) \property Score.measureLength = #(make-moment n d) These properties Changing the value of The actual symbol that's printed can be customized with the style property. \time 3/4 s2 \property Staff.TimeSignature \override #'style = #'C \time 4/4 s2 \property Staff.TimeSignature \override #'style = #'() \time 4/4 s2 \property Staff.TimeSignature \override #'style = #'C \time 2/2 s2
There are many more options for the layout of this grob. They are
selected through the See
PartialPartial measures, for example in upbeats, are entered using the
\partial duration Internally, this is a shortcut for \property Score.measurePosition = -length of duration The property Unmetered musicBar lines and bar numbers are calculated automatically. For unmetered
music (e.g. cadenzas), this is not desirable. The property
c'2. \property Score.timing = ##f c2 \property Score.timing = ##t c4 c4 c4
The identifiers Bar lines\bar bartype This is a shortcut for doing \property Score.whichBar = bartypeThe 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 Whenever
PolyphonyPolyphonic parts, i.e. parts with more than one voice on a staff can be typeset with LilyPond. To use this, instantiate a separate Voice context for each part, and assign a stem direction to each part. \context Staff < \context Voice = VA { \stemUp b'4 a' g' f' e' } \context Voice = VB { \stemDown g'4 g' g' g' g' } >
When there are more than two voices on a staff, you must also indicate
which voice should moved horizontally in case of a collision. This can
be done with the identifiers \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 } >
The most convenient way is to use the identifiers \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 } >
Normally, note heads with a different number of dots are not merged, but
if you set the grob property \context Staff < \context Voice = VA { \voiceOne g'8 g'8 \property Staff.NoteCollision \override #'merge-differently-dotted = ##t g'8 g'8 } \context Voice = VB { \voiceTwo [g'8. f16] [g'8. f'16] } >
LilyPond also vertically shifts rests that are opposite of a stem. \context Staff < \context Voice { \stemUp c''4 } \context Voice =VB { r4 } >
Note head collisions (horizontal shifting of note heads) are handled by
the 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. LilyPond guesses where beams should be inserted. If you're not satisfied with the automatic beaming, you can specify which patterns to beam automatically. In specific cases, you can also enter the beams explicitly. Automatic beamsIn 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 N M P Q) = dur \property Voice.autoBeamSettings \revert #'(BE N M P Q)Here, BE is the symbol begin or end . It determines
whether the rule applies to begin or end-points. The quantity
N/M refers to a time signature (wildcards, `* * ' may
be entered to designate all time signatures), P/Q refers to
the length of the beamed notes (and `* * ' designates notes of any
length).
For example, if you want automatic beams to end on every quarter note, you can use the following: \property Voice.autoBeamSettings \override #'(end * * * *) = #(make-moment 1 4)Since the duration of a quarter note is 1/4 of a whole note, it is entered as (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 * * * *) = #(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 first 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
second 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. Automatic beaming is on by default, but can be switched off 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 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 { [f'8 r16 f g a] [f8 r16 \property Voice.stemLeftBeamCount = #1 f g a] }
The beam symbol (grob Set \property Voice.Beam \set #'direction = #1 \property Voice.Beam \set #'height = #0 [a''8 e' d c]
Here's how you'd specify a weird looking beam that instead of being horizontal, falls two staff spaces: \property Voice.Beam \set #'staff-position = #4 \property Voice.Beam \set #'height = #-4 [c'8 c] 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
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
\property Voice.Slur \set #'direction = #1 \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: \property Voice.Stem \set #'direction = #1 \property Voice.Slur \set #'direction = #1 d'32( d'4 )d8.. \property Voice.Slur \set #'attachment = #'(stem . stem) d,32( d'4 )d8..
Similarly, the curvature of a slur is adjusted to stay clear of note
heads and stems. When that would increase the curvature too much, the
slur is reverted to its default shape. The threshold for this decision
is in \property Voice.Beam \override #'direction = #-1 \property Voice.Slur \override #'direction = #1 c'16( a' f' a a f a, )c, c( a' f' a a f d, )c \property Voice.Slur \override #'beautiful = #5.0 c( a' f' a a f d, )c
BUGS
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. The grob associated with it is Breath marksBreath marks are entered using
BUGS Currently, only tick marks are supported, not comma style breath marks. 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: \spanrequest \start "text" \spanrequest \stop "text"LilyPond will respond by creating a Voice.TextSpanner grob. The
string to be printed, as well as the style is set through grob
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\spanrequest \start "text" b c a \spanrequest \stop "text" } OrnamentsArticulationsA variety of symbols can appear above and below notes to indicate
different characteristics of the performance. These symbols can be
added to a note with `note
To save typing work, some shorthands are available:
Fingering instructions can also be entered in this shorthand. c'4-1 c'4-2 c'4-3 c'4-4
You can add scripts by editing \script alias Usually the Grobs for these objects are 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
if \relative c' { c4^"longtext" \fatText c4_"longlongtext" c4 }
Text scripts are created in form of Grace notesGrace notes are ornaments that are written out, but do not take up any logical time in a measure. LilyPond has limited support for grace notes. The syntax is as follows. \grace musicexpr When grace music is interpreted, a score-within-a-score is set up: musicexpr has its own time bookkeeping, and you could (for example) have a separate time signature within the grace notes. While in this score-within-a-score, you can create notes, beams, slurs, etc. Unbeamed eighth notes and shorter by default have a slash through the stem. \relative c'' { \grace c8 c4 \grace { [c16 c16] } c4 \grace { \property Grace.Stem \override #'flag-style = #'() c16 } c4 }
A grace note expression has duration 0; the next real note is assumed to
be the main note. If you want the note to appear after the main note,
set BUGS At present, slurs or ties from the grace notes to the following notes
are not supported. Also, nesting
Since the meaning of such a construct is unclear, we don't consider this
a loss. Similarly, juxtaposing two \grace sections is
syntactically valid, but makes no sense and may cause runtime errors.
Ending a staff or score with grace notes may also generate a run-time
error, since there will be no main note to attach the grace notes to.
The present implementation of grace notes is not robust and generally kludgey. We expect it to change after LilyPond 1.4. Syntax changes might also be implemented. GlissandoA glissando line (grob c''-\glissando c'
BUGS Printing of an additional text (such as gliss.) must be done manually. 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 } >
You can also use a text saying cresc. instead of hairpins. Here is an example how to do it: \context Voice { \property Voice.crescendoText = "cresc." \property Voice.crescendoSpanner = #'dashed-line a''2\mf\< a a \!a }
For everyday use, we recommend the identifiers Dynamics are grobs of 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. } } } }
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. However, it is to be expected that more functionality - especially for the MIDI backend - will be implemented at some point in the future. Volta repeats are printed over all staffs in a score. You must turn them off explicitly, for example by doing \property Staff.VoltaBracket = \turnOffin all but the top staff. 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 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 BUGS At present, the spacing between tremolo beams is not regular, since the spacing engine does not notice that not all notes are printed. 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 grobs: BUGS You can not nest percent repeats, e.g. by filling in the first measure with slashes, and repeating that measure with percents. Rhythmic musicRhythmic staffsSometimes 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 | } Piano musicPiano music is an odd type of notation. Piano staffs are two normal
staffs coupled with a brace. The staffs are largely independent, but
sometimes voices can cross between the two staffs. The
Automatic staff changesVoices can switch automatically between the top and the bottom staff. The syntax for this is \autochange contexttype musicexpThis will switch the interpretation context of musicexp between a contexttype named up and down . Typically, you use
Staff for contexttype. 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.
\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 } > }
Note how spacer rests are used to prevent the bottom staff from terminating too soon. Manual staff switchesVoices can be switched between staffs 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" .
The formal definition of this construct is obtuse, but for the sake of completeness we give it here. \translator contexttype = nameFormally, this construct is a music expression indicating that the context which is a direct child of the context of type contexttype should be shifted to a context of type contexttype and the specified name. PedalsPiano pedal instruction can be expressed using
These identifiers are shorthands for spanner commands of the types
c''4 \spanrequest \start "Sustain" c''4 c''4 \spanrequest \stop "Sustain"
The symbols that are printed can be modified by setting
BUGS Currently, brackets are not supported, only text markings (i.e. `*Ped' style). ArpeggioYou can specify an arpeggio sign on a chord by attaching an
\context Voice <c'\arpeggio e g c>
When an arpeggio crosses staffs in piano music, you attach an arpeggio
to the chords in both staffs, and set
\context PianoStaff < \property PianoStaff.connectArpeggios = ##t \context Voice = one { <c''\arpeggio e g c> } \context Voice = other { \clef bass <c,,\arpeggio e g>} >
This command creates BUGS It is not possible to mix connected arpeggios and unconnected arpeggios 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 { c'1 \translator Staff=two b2 a } \context Staff=two {\clef bass \skip 1*2 } >
The associated grob is LyricsLyrics modeTo print lyrics, you must first make a music expression from the lyric text. That music expression can be printed by selecting an appropriate context. 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, with pitches replaced by text. For
example, Spaces can be introduced into a lyric either by using quotes:
The precise definition of this mode can be found in Lyrics mode definition. Printing lyricsLyrics are printed by interpreting them in the \addlyrics \notes \relative c' { \time 7/4 \property Staff.automaticMelismata = ##t 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; }
Notes and syllable durations are matched automatically. This is
accomplished using The Lyric syllables are As you can see, extender lines are entered as If you want to have hyphens centered between syllables (rather than
attached to the end of the first syllable) you can use the special
` Automatic syllable durationsIf you have lyrics that are set to a melody, you can copy the rhythm
of that melody into the lyrics using \addlyrics musicexpr1 musicexpr2 Both musicexpr1 and musicexpr2 are interpreted, but every music event ("every syllable") in musicexpr2 is interpreted only when there are events in musicexpr1. If the property \addlyrics \transpose c'' { \property Voice.automaticMelismata = ##t c8 () cis d8. e16 f2 } \context Lyrics \lyrics { do4 re mi fa }
If you want the lyric lines to be above the melody staff, or in some
other, more complex configuration, then build that configuration first
using simultaneous music, and use \notes < \context Lyrics = LA { s1 } \context Staff = SA { s1 } \addlyrics \context Staff = SA \relative c' { c4 e g g } \context Lyrics = LA \lyrics { geen ge -- don -- der } >
For \addlyrics \transpose c'' { c8 () cis d8. e16 f2 } \context Lyrics \lyrics < { do4 re fa sol } { do8 re fa sol } >
It is valid (but probably not very useful) to use notes instead of lyrics for musicexpr2. 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. 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 \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. } > }
You can add stanza numbers by setting ChordsLilyPond has support for both entering and printing chords. Chords are characterized by a set of pitches. They are internally stored as simultaneous music expressions. This means you can enter chords by name and print them as note head, enter them as notes and print them as chord names, or (the most common case) enter them by name, and print them as name. twoWays = \notes \transpose c'' { \chords { c1 f:sus4 bes/f } <c e g> <f bes c'> <f bes d'> } \score { < \context ChordNames \twoWays \context Voice \twoWays > }
Note that this example also shows that the chord printing routines do
not attempt to be intelligent. If you enter Chords modeChord mode is a mode where you can input sets of pitches using common
names. It is introduced by the keyword Dashes and carets are used to indicate chord additions and subtractions, so articulation scripts can not be entered in Chord mode. The syntax for named chords is as follows: tonic[duration][ tonic should be the tonic note of the chord, and duration is
the chord duration in the usual notation. There are two kinds of
modifiers. One type is formed by chord additions. Additions are
obtained by listing intervals separated by dots. An interval is written
by its number with an optional Throughout these examples, chords have been shifted around the staff
using \transpose c'' { \chords { c1 c:3- c:7 c:8 c:9 c:9-.5+.7+ c:3-.5- } }
The second type of modifier that may appear after the \transpose c'' { \chords { c1:m c:min7 c:maj c:aug c:dim c:sus } }
Chord subtractions are used to eliminate notes from a chord. The
notes to be subtracted are listed after a \transpose c'' { \chords { c1^3 c:7^5.3 c:8^7 } }
Chord inversions can be specified by appending ` \transpose c''' { \chords { c1 c/e c/g c:7/e } }
Bass notes can be added by ` \transpose c''' { \chords { c1 c/+c c/+g c:7/+b } }
BUGS Implementation details are quite gory. For example Printing named chordsFor displaying printed chord names, use the scheme = \notes { \chords {a1 b c} <d f g> <e g b> } \score { \notes< \context ChordNames \scheme \context Staff \transpose 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'' \scheme > }
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'1 e' g'> <e' g' c''> <e e' g' c''> } \score { < \context ChordNames \scheme \context Staff \scheme > }
By default, a chord name system proposed by Harald Banter (See
Literature) is used. The system is very regular and predictable.
Typical American style chord names may be selected by setting the
Routines that determine the names to be printed are written in Scheme,
and may be customized by the user. The code can be found in
scheme = \chords { c1 c:5^3 c:4^3 c:5+ c:m7+ c:m5-.7 c:5-.7 c:5+.7 c:9^7 } \score { \notes < \context ChordNames = banter \scheme \context ChordNames = american { \property ChordNames.ChordName \override #'style = #'american \scheme } \context ChordNames = jazz { \property ChordNames.ChordName \override #'style = #'jazz \scheme } \context Staff \transpose c'' \scheme > } 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 marks\mark unsigned \mark string \mark \default This command prints a rehearsal mark above the system. You can provide
a number, a string or a markup text as argument. If you use
\relative c'' { c1 \mark "A2" c1 \mark \default c1 \mark \default c1 \mark "12" c1 \mark #'(music "scripts-segno") c1 }
The grob is Bar numbersBar numbers (grob: BUGS It is not possible to have bar numbers printed at regular intervals only. Instrument namesYou can specify an instrument name for a staff by setting
\property Staff.instrument = "ploink " { c''4 }
You can also use markup texts to construct more complicated instrument names: #(define text-flat '((font-relative-size . -2 ) (music "accidentals--1"))) \score { \notes { \property Staff.instrument = #`((kern . 0.5) (lines "2 Clarinetti" (columns " (B" ,text-flat ")"))) c'' 4 } }
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 pitch musicexpr This means that middle C in musicexpr is transposed to pitch.
\context Staff { \clef "F" { \key e \major c d e f } \clef "G" \transpose des'' { \key e \major c d e f } \transpose cis'' { \key e \major c d e f } }
If you want to use both Sound output 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 Multi measure restsMulti measure rests are entered using ` \time 3/4 r2. | R2. | R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4
Notice that the BUGS Currently, there is no way to automatically condense multiple rests into a single multimeasure rest. 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 staffsIn orchestral scores, staff lines that only have rests are usually removed. This saves some space. LilyPond also supports this through the hara kiri4 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 } } } 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' } 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 grobs (graphic objects). Each grob carries with it a set of properties (grob properties) specific to that object. For example, a stem grob 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 grob, thus affecting a whole set of objects. Second, you can select one specific object, and set a grob property in that object. Tuning groups of grobsA grob definition is a Scheme association list, that is stored in a
context property. By assigning to that property (using plain
c'4 \property Voice.Stem = #'((meta . ((interfaces . ())))) c'4
The \property Voice.Stem = \turnOff This mechanism is fairly crude, since you can only set, but not modify, the definition of a grob. For this reason, there is a more advanced mechanism. The definition of a grob is actually a list of default grob
properties. For example, the definition of the Stem grob (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
c'4 \property Voice.Stem \set #'thickness = #4.0 c'4 \property Voice.Stem \set #'thickness = #0.8 c'4
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 grob property is unset), then you can use \set \set \set \revert For the digirati, the grob 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 grob properties. If you
Some grobs are created at the moment that their context is created. An
example of such a grob is the staff itself (i.e. the horizontal lines).
You can not change the appearance of the staff symbol by manipulating
Tuning per grobA second way of tuning grobs is the more arcane \outputproperty predicate symbol = valueHere predicate is a Scheme function taking a grob argument, and
returning a boolean. This statement is processed by the
Output_property_engraver . It instructs the engraver to feed all
grobs that it sees to predicate. Whenever the predicate returns
true, the grob property symbol will be set to value.
You will need to combine this statement with Here are some random examples. 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) <c8 e g> }
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. What to tune?This all tells you how to tune grobs, but you don't know what variables to set? The question is not answered in this part of the manual (although you may encounter some examples.). Grob properties are tied directly to the implementation of LilyPond, and they are thus a moving target. Documentation of such variables is in the automatically generated documentation. Description of properties are generated from the source code for each version. This documentation is therefore more up to date. It should be available from the same place where you got this manual. To decide how to tune a grob, you need to find the following information
Included with the automatically generated documentation is a master list of grobs. Selecting a grob will take you to an overview of the properties available for that grob. There is also a master list of contexts. Selecting one takes you to an overview of that context which lists which grob types are created there. Font selectionMost graphics in LilyPond are composed of characters of fonts. You can alter the characteristics of the font by setting certain grob properties. The mechanism that is used for this resembles LaTeX's New Font Selection Scheme. Within this scheme, a font is entirely characterized by its font name. For each grob that uses fonts (in other words, each grob that supports
The font is selected by taking the first font that satisfies all
qualifiers specified. You can override any of these fields through
\property Lyrics.LyricText \override #'font-series = #'bold \property Lyrics.LyricText \override #'font-shape = #'* There are also pre-cooked font selection qualifiers. These are selected
through the grob property The style sheets and tables for selecting fonts are located in
BUGS Relative size is not linked to any real size. There is no mechanism to select magnification of particular fonts, meaning that you don't have access to continuously scaled fonts. You can scale the entire output, of course, see Output scaling. There is no style sheet provided for other fonts besides the TeX family. Text markupLilyPond has an internal mechanism to typeset texts. You can form text markup expressions by composing scheme expressions in the following way. \relative c' { \fatText a^#"upright" b_#'(bold "bold") c^#'(italic "italic") d_#'((bold italic) "ff") e^#'(dynamic "ff") f_#'(lines "one" (bold "two")) g^#'(music "noteheads-2" ((raise . 2.4) "flags-u3")) }
Normally, the Scheme markup text is stored in the text: string | (head? text+) head: markup | (markup+) markup-item: property | abbrev property: (key . value) abbrev: The markup is broken down and converted into a list of grob properties, which are prepended to the property list. The key-value pair is a grob property. A list of properties available is included in the generated documentation for Text_interface . The following abbreviations are currently defined:
One practical application of complicated markup is to fake a metronome marking: #(define note '(columns (music "noteheads-2" ((kern . -0.1) "flags-stem")))) #(define eight-note `(columns ,note ((kern . -0.1) (music ((raise . 3.5) "flags-u3"))))) #(define dotted-eight-note `(columns ,eight-note (music "dots-dot"))) \score { \notes\relative c'' { a1^#`((columns (font-relative-size . -1)) ,dotted-eight-note " = 64") } \paper { linewidth = -1. \translator{ \ScoreContext TextScript \override #'font-shape = #'upright } } } Invisible grobsYou can imagine a number of situations where you would want to make certain grobs not show up in the output. There may be aesthetic reasons, to make the output resemble an (old) manuscript as close as possible, or to make lessons or exercises for students. Grobs can be made invisible in a number of ways: Here's an example with blanked-out notes and stems: blanknotes = { \property Voice.NoteHead \override #'transparent = ##t \property Voice.Stem \override #'transparent = ##t } unblanknotes = { \property Voice.NoteHead \revert #'transparent \property Voice.Stem \revert #'transparent } \score { \notes\relative c'' { \time 6/4 a b c b \blanknotes c \unblanknotes d } }
\score { \notes\relative c'' { \key c \minor \time 6/4 as bes c bes c d \break \property Staff.KeySignature \override #'molecule-callback = #'() as bes c bes c d } \paper{linewidth=5.0\cm indent=0} }
A very rigorous way of removing grobs from the whole score is to remove the engraver that creates them. For example, \score {\notes { c'4 d'8 e'8 g2 } \paper { \translator { \VoiceContext \remove Stem_engraver } } } Dirty tricksIt 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 (see PostScript output). a''^"3 $\\times$ \\`a deux"
You can also use raw PostScript commands embedded in text scripts. This offers ultimate flexibility, but requires you to learn PostScript. Currently, embedded PostScript will not work with direct PostScript output. Note that all dimensions that you use are in staff space. \score { \notes \relative c'' { a-#"\\embeddedps{3 4 moveto 5 3 rlineto stroke}" -#"\\embeddedps{ [ 0 1 ] 0 setdash 3 5 moveto 5 -3 rlineto stroke}" b-#"\\embeddedps{3 4 moveto 0 0 1 2 8 4 20 3.5 rcurveto stroke}" s2 a'1 } \paper { linewidth = 70*\staffspace } } Page layoutThe page layout is the combined product of LilyPond formatting notation, and (La)TeX putting the notation on a page, including page breaks. The part of LilyPond is documented here. Paper blockThe most important output definition is the
where each of the items is one of
Paper variablesThe paper block has some variables you may want to use or change:
You may enter these dimension using units ( linewidth = 20.0 * \staffspace indent = 0.5 \cm Font sizeThe Feta font provides musical symbols at six different sizes. These fonts are 11 point, 13 point, 16 point, 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 The font definitions are generated using a Scheme function. For more
details, see the file Paper sizeTo change the paper size, you must first set the
papersize = "a4" \include "paper16.ly" The file Line breakLine breaks are normally computed automatically. They are chosen such that the resulting spacing has low variation, and looks neither cramped nor loose. Occasionally you might want to override the automatic breaks; you can do
this by specifying The \penalty int This encourages or discourages LilyPond to make a line break at this point. BUGS The scaling of the Page breakPage breaks are normally computed by TeX, so they are not under
direct control of LilyPond. However, you can insert a commands into the
\newpage Output scaling[TODO] dvips ... pstops ... BUGS There is no mechanism to select magnification of particular fonts, meaning that you don't have access to continuously scaled fonts. Output formatsLilyPond can output processed music in different output formats. TeX outputLilyPond will use TeX by default. Even if you want to produce
PostScript output for viewing or printing, you should normally have
LilyPond produce TeX first. The .tex output must be processed by
TeX (not LaTeX) to generate a .dvi. Then, BUGS Titling is not generated unless you use PostScript outputLilyPond can produce PostScript directly, without going through TeX. Currently, this is mainly useful if you cannot use TeX, because direct PostScript output has some problems; see Bugs below. $ lilypond -fps foo.ly GNU LilyPond 1.3.144 Now processing: `foo.ly' Parsing... Interpreting music...[3] Preprocessing elements... Calculating column positions... paper output to foo.ps... $ cat /usr/share/lilypond/pfa/feta20.pfa foo.ps | lpr BUGS Text font selection is broken. The .ps file does not contain the .pfa font files. To print a .ps created through direct postscript output, you should prepend the necessary .pfa files to LilyPond's .ps output, or upload them to the printer before printing. The line height calculation is broken, you must set lineheight in the paperblock if you have more than one staff in your score, e.g. ... \paper { % Set line height to 40 staff spaces lineheight = 40 } Scheme outputIn the typesetting stage, LilyPond builds a page description, which is then written to disk in postscript, TeX or ASCII art. Before it is written, the page description is represented as Scheme expressions. You can also dump these Scheme expressions to a file, which may be convenient for debugging output routines. This is done with the Scheme output format $ lilypond -fscm foo.ly GNU LilyPond 1.3.144 Now processing: `foo.ly' Parsing... Interpreting music...[3] Preprocessing elements... Calculating column positions... paper output to foo.scm... $ head -4 foo.scm ;;; Usage: guile -s x.scm > x.tex (primitive-load-path 'standalone.scm) ; (scm-tex-output) (scm-ps-output) $ guile -s foo.scm > foo.tex ASCIIScript outputLilyPond can output ASCII Art. This is a two step process, LilyPond
produces an ASCII description file, dubbed ASCIIScript (extension
To produce ASCII Art, you must include an ASCII Art paper definition file in your .ly, one of: \include "paper-as5.ly" \include "paper-as9.ly" Here's an example use for ASCII Art output (the example file
$ lilypond -fas as-email.ly GNU LilyPond 1.3.144 Now processing: `as-email.ly' Parsing... Interpreting music...[3] Preprocessing elements... Calculating column positions... [2] paper output to as-email.as... $ as2text as-email.as 2>/dev/null |\ |/ |##|##| | | | | | /| | | | | |\ |\ |\ |\ |\ | / |_ 3 | | | | 5 | )| )| )| )| )| | /| \ 8 * * * | 8 * * * * * | \_|_/ | | *_| lily BUGS The ASCII Art fonts are far from complete and not very well designed.
It's easy to change the glyphs, though; if you think you can do better,
have a look at Lots of resizable symbols such as slurs, ties and tuplets are missing. The poor looks of most ASCII Art output and its limited general usefulness gives ASCII Art output a low priority; it may be dropped in future versions. 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. BUGS It is currently not possible to use the percussion channel (generally channel 10 of a MIDI file). 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. 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. RelativeOctaves 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. 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 Installation
Xdvi must be configured to find the TeX fonts and music fonts. Refer to the Xdvi documentation for more information. Using itAdd one of these lines to the top of your .ly file. The first one is for
line location only. The second one is more convenient, but requires
patching #(set! point-and-click line-location) In the emacs startup file (usually (server-start) Make sure that the environment variable emacsclient --no-wait +%l %fThe second one, that also specifies the column, only works if you have patched your emacsclient and server, and have compiled your .ly
file using the line-column-location setting.
When viewing, control-mousebutton 1 will take you to the originating
spot in the Column locationIf you want emacs to jump to the exact spot (and not just the line) on a
click, you must enable column positioning. To do so, you need to patch
emacsclient. Apply (setq load-path (cons "~/usr/share/emacs" load-path)) Set At the top of the #(set! point-and-click line-column-location) BUGS When you convert the TeX file to PostScript using When 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 } Interpretation contextInterpretation contexts are objects that only exist during a run of
LilyPond. During the interpretation phase of LilyPond (when it prints
"interpreting music"), the music expression in a 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 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 This is a convenient mechanism, but do not expect opening chords to work
without \score { \notes <c'4 es'> }
Of course, if the chord is preceded by a normal note in sequential music, the chord will be interpreted by the Thread of the preceding note: \score { \notes { c'4 <c'4 es'> } } 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
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-propnamepropname is a string, grob-propname a symbol, value and pvalue are Scheme expressions. These type of property
assignments happen before interpretation starts, so a \property
command will override any predefined settings.
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. Top levelThis section describes what you may enter at top level. ScoreThe output is generated combining a music expression with an output definition. A score block has the following syntax: \score { musicexpr outputdefs } outputdefs are zero or more output definitions. If none is
supplied, the default Default outputDefault values for the HeaderA header describes bibliographic information of the file's contents. It
can also appear in a The syntax is \header { key1 = val1 key2 = val2 ... } It is customary to put the Default outputA 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. \sequentialFor 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' } > }
Other compound music expressions include \repeat expr \transpose pitch expr \apply func expr \context type = id expr \times fraction expr Manipulating music expressionsThe \apply #func musicThis 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 (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
Span requestsNotational constructs that start and end on different notes can be entered using span requests. The syntax is as follows: \spanrequest startstop type This defines a spanning request. The startstop parameter is either
-1 ( c'4-\spanrequest \start "slur" c'4-\spanrequest \stop "slur"
Among the supported types are AssignmentsIdentifiers allow objects to be assigned to names during the parse
stage. To assign an identifier, you 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. The modes are treated in more detail in Lyrics and Chords. 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 lexical side of the input parser. CommentsA one line comment is introduced by a Direct SchemeLilyPond contains a Scheme interpreter (the GUILE library) for internal use. In some places, Scheme expressions also form valid syntax: wherever it is allowed, #schemeevaluates the specified Scheme code. Example: \property Staff.TestObject \override #'foobar = #(+ 1 2) \override expects two Scheme expressions, so there are two Scheme
expressions. The first one is a symbol (foobar ), the second one
an integer (namely, 3).
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. KeywordsKeywords start with a backslash, followed by a number of lower case alphabetic characters. These are all the keywords. apply arpeggio autochange spanrequest commandspanrequest simultaneous sequential accepts alternative bar breathe char chordmodifiers chords clef cm consists consistsend context denies duration dynamicscript elementdescriptions font grace header in lyrics key mark pitch time times midi mm name pitchnames notes outputproperty override set revert partial paper penalty property pt relative remove repeat addlyrics partcombine score script stylesheet skip textscript tempo translator transpose type IntegersFormed from an optional minus sign followed by digits. Arithmetic operations cannot be done with integers, and integers cannot be mixed with reals. 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 Main inputThe File inclusion\include filename Include filename. The argument filename may be a quoted string (an
unquoted string will not work here!) or a string identifier. The full
filename including the Version information\version string Specify the version of LilyPond that a file was written for. The
argument is a version string in quotes, for example InternalsWhen translating the input to notation, there are number of distinct phases. We list them here:
The data types that are mentioned here are all discussed in this section. Input locationInput location objects point to a location in the input file. This location is used to generate error messages and to enable the point and click output.
MomentMoment is a rational number. Since GUILE doesn't support them natively, so we created our own rational data type.
DurationA duration is a musical duration, i.e. a length of time described by a power of two (whole, half, quarter, etc.) and a number of augmentation dots.
Pitch data type
MusicMusic is the data type that music expressions are stored in. The data type does not yet offer many manipulations.
Music_iteratorMusic_iterator is an object type that traverses the Music structure and reports the events it finds to interpretation contexts. It is not yet user-serviceable.
TranslatorTranslators are the building blocks of contexts. They are not yet user accessible.
GrobsThis section is about Grobs (short for Graphical Objects), which are formatting objects used to create the final output. This material is normally the domain of LilyPond gurus, but occasionally, a normal user also has to deal with grobs. The most simple interaction with Grobs are when you use
\property Voice.Stem \override #'direction = #1 This piece of lily input causes all stem objects to be stem-up
henceforth. In effect, you are telling lilypond to extend the definition
of the `Stem' grob with the setting What is a grob?In music notation, lots of symbols are related in some way. You can think of music notation as a graph where nodes are formed by the symbols, and the arcs by their relations. A grob is a node in that graph. The directed edges in the graph are formed by references to other grobs (i.e. pointers). This big graph of grobs specifies the notation problem. The solution of this problem is a description of the printout in closed form, i.e. a list of values. These values are Molecules. (see Molecules) All grobs have an X and Y-position on the page. These X and Y positions are stored in a relative format, so they can easily be combined by stacking them, hanging one grob to the side of another, and coupling them into a grouping-grob. Each grob has a reference point (a.k.a. parent): the position of a grob is stored relative to that reference point. For example the X-reference point of a staccato dot usually is the note head that it applies to. When the note head is moved, the staccato dot moves along automatically. If you keep following offset reference points, you will always end up at
the root object. This root object is called All grobs carry a set of grob-properties. In the Stem example above,
the property A grob is often associated with a symbol, but some grobs do not print
any symbols. They take care of grouping objects. For example, there is a
separate grob that stacks staffs vertically. The A complete list of grob types is found in the generated documentation. CallbacksOffsets of grobs are relative to a parent reference point. Most positions are not known when an object is created, so these are calculated as needed. This is done by adding a callback for a specific direction. Suppose you have the following code in a .ly file. #(define (my-callback gr axis) (* 2.0 (get-grob-property gr 'direction)) ) .... \property Voice.Stem \override #'Y-offset-callbacks = #(list my-callback) When the Y-offset of a Stem object is needed, LilyPond will
automatically execute all callbacks for that object. In this case, it
will find (note: Offset callbacks can be stacked, i.e. \property .... \override #'Y-offset-callbacks = #(list callback1 callback2 callback3) The callbacks will be executed in the order Similarly, the size of a grob are determined through callbacks, settable
with grob properties Setting grob propertiesGrob properties are stored as GUILE association lists, with symbols as keys. In GUILE you can access these using functions described in Section Grob Scheme functions. From C++, grob properties can be accessed using these functions: SCM get_grob_property (SCM) const; void set_grob_property (const char * , SCM val); void set_immutable_grob_property (const char * , SCM val); void set_immutable_grob_property (SCM key, SCM val); void set_grob_property (SCM , SCM val); void set_grob_pointer (const char*, SCM val); SCM remove_grob_property (const char* nm); All lookup functions identify undefined properties with end-of-list
(i.e. Properties are stored in two ways:
You can change immutable grob properties with the \override syntax: \property Voice.Stem \override #'direction = #1 This will push the entry \property Voice.stem \revert #'direction There is also a shorthand, \property Context.GrobType \set #'prop = #VAL this does a You can change mutable properties with \outputproperty. This construct looks like \context ContextName \outputproperty pred #sym = #val In this case, in every grob that satisfies pred, the grob property sym is set to val. For example \outputproperty #(lambda (gr) (string? (ly-get-grob-property gr 'text))) #'extra-offset = #'(-1.0 . 0.0) This shifts all grobs that have a Grob interfacesGrob properties form a name space where you can set variables per
object. Each object however, may have multiple functions. For example,
consider a dynamic symbol, such To reflect this different functions of a grob, procedures and variables are grouped into so-called interfaces. The dynamic text for example supports the following interfaces:
Items and SpannersGrobs can also be distinguished in their role in the horizontal spacing.
Many grobs define constraints on the spacing by their sizes. For
example, note heads, clefs, stems, and all other symbols with a fixed
shape. These grobs form a subtype called Other grobs have a shape that depends on the horizontal spacing. For
example, slur, beam, tie, etc. These grobs form a subtype called
Some items need special treatment for line breaking. For example, a clef is normally only printed at the start of a line (i.e. after a line break). To model this, `breakable' items (clef, key signature, bar lines, etc.) are copied twice. Then we have three versions of each breakable item: one version if there is no line break, one version that is printed before the line break (at the end of a system), one version that is printed after the line break. Whether these versions are visible and take up space, is determined by
the outcome of the Grob Scheme functionsGrob properties can be manipulated from Scheme. In practice, most manipulations are coded in C++ because of tradition.
MoleculesThe objective of any typesetting system is to put ink on paper in the right places. For LilyPond, this final stage is left to the TeX and the printer subsystem. For lily, the last stage in processing a score is outputting a description of what to put where. This description roughly looks like PUT glyph AT (x,y) PUT glyph AT (x,y) PUT glyph AT (x,y) you merely have to look at the tex output of lily to see this. Internally these instructions are encoded in Molecules.5 A molecule is what-to-print-where information that also contains dimension information (how large is this glyph?). Conceptually, Molecules can be constructed from Scheme code, by translating a Molecule and by combining two molecules. In BNF notation: Molecule :: COMBINE Molecule Molecule | TRANSLATE Offset Molecule | GLYPH-DESCRIPTION ; If you are interested in seeing how this information is stored, you
can run with the All visible, i.e. non-transparent, grobs have a callback to create a
Molecule. The name of the property is
Font metricsThe font object represents the metric information of a font. Every font that is loaded into LilyPond can be accessed via Scheme. LilyPond only needs to know the dimension of glyph to be able to process them. This information is stored in font metric files. LilyPond can read two types of font-metrics: TeX Font Metric files (TFM files) and Adobe Font Metric files (AFM files). LilyPond will always try to load AFM files first since they are more versatile.
Miscellaneous Scheme functions
Invoking LilyPondUsage: lilypond [OPTION... [FILE]... Options
When invoked with a filename that has no extension, LilyPond will try to
add When LilyPond processes Environment variables
Bug reportsLilyPond 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 including the following information:
You can send the report to bug-gnu-music@gnu.org. This is a mailinglist, but you don't have to be subscribed to it. You may also enter the bug in the LilyPond wiki, at http://www.lilypond.org/wiki?LilyPondBugs. ly2dvi
Invoking ly2dvily2dvi [OPTION]... FILE... Options
Titling layoutLy2dvi extracts the following header fields from the LY files to generate titling:
Additional parametersLy2dvi responds to several parameters specified in a
Environment variables
BugsCannot generate TeX or AuthorsHan-Wen Nienhuys.Earlier incarnations of ly2dvi were written by Jeffrey B. Reed (Python version), and Jan Arne Fagertun (Bourne shell version) convert-lyConvert-ly sequentially applies different conversions to upgrade a
Lilypond input file. It uses Invoking convert-lyconvert-ly [OPTION]... [FILE]...
ExampleUpgrade all lilypond files to 1.3.150: convert-ly -e --to=1.3.150 `find -name '*.ly'` BugsNot all language changes are handled. Multiple output options won't work. Authors
lilypond-book
More precisely, if a LaTeX file contains \begin{lilypond} CONTENTS \end{lilypond}or \lilypond{CONTENTS}then LilyPond is run on CONTENTS. lilypond-book puts the
result back into the latex file. When you run the result through latex,
you get a document that mixes text and music. lilypond-book will insert
line width and font size definitions before CONTENTS , so the
music samples will match the layout of your document.
Very often, if you mix music and text, the music is only a few
notes or at most a few bars. This music should be as short as possible
and not stretched to be aligned to the right margin. lilypond-book does
this automatically if you don't use a You can also use \lilypondfile{foo.ly} All three forms can take several options. They are specified in brackets as follows: \lilypondfile[options, go, here]{ .. } \begin[options, go, here]{lilypond} .. \end{lilypond} \lilypond[options, go,here]{ .. } In the texinfo version, bitmaps of the music are also generated, so you can make a HTML document with embedded music. TeXinfo referenceYou specify the lilypond code like this: @lilypond[options, go, here] YOUR LILYPOND CODE @end lilypond @lilypond[option, go, here]{ YOUR LILYPOND CODE } @lilypondfile[options, go,here]{filename}
@pagesizes are not yet supported.
ExamplesTwo simple examples. 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:
LaTeX referenceYou specify the lilypond code like this: \begin[option, go, here]{lilypond} YOUR LILYPOND CODE \end{lilypond} \lilypondfile[options, go,here]{filename}or \lilypond{ YOUR LILYPOND CODE } Lilypond-book know about the The music will be surrounded by Examples\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:
Options
InvocationWhen 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{}} Command line options
BugsThe LaTeX \includeonly{...} command is ignored. The TeXinfo command Almost all LaTeX commands that change margins and line widths are ignored. Since 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 if you need this one of these options. AuthorsHan-Wen Nienhuys, http://www.cs.uu.nl/~hanwen Tom Cato AmundsenConverting to LilyPond format.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. Invoking midi2lymidi2ly [OPTION]... MIDI-FILE Options
Report bugs to bug-gnu-music@gnu.org. Written by janneke@gnu.org. etf2lyETF (Enigma Transport Format) is a format used by Coda Music Technology's Finale product. This program will convert part of an ETF file to a ready-to-use LilyPond file. Invoking etf2lyUsage: etf2ly [OPTION]... ETF-FILE Convert ETF to LilyPond. Options
BUGS Known: articulation scripts are buggy. Empty measures confuse etf2ly. Written by hanwen@cs.uu.nl. Report bugs to bug-gnu-music@gnu.org. abc2lyABC is a fairly simple ASCII based format. It is described at http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt. Invoking abc2lyabc2ly [OPTION]... ABC-FILE Convert ABC to LilyPond. There is a rudimentary facility for adding lilypond code to the ABC source file. If you say: %%LY voices \property Voice.noAutoBeaming=##t 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. Options
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. Written by hanwen@cs.uu.nl. Report bugs to bug-gnu-music@gnu.org. pmx2lyPMX is a Musixtex preprocessor written by Don Simons, see http://icking-music-archive.sunsite.dk/Misc/Music/musixtex/software/pmx/. Report bugs to bug-gnu-music@gnu.org. Invoking pmx2lypmx2ly [OPTION]... PMX-FILE Convert PMX to LilyPond. Options
Report bugs to bug-gnu-music@gnu.org. Written by hanwen@cs.uu.nl. 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
(http://www.ccarh.org/publications/books/beyondmidi/online/musedata).
musedata2ly converts a set of musedata files to one .ly file, and will
include a Invoking musedata2lymusedata2ly [OPTION]... MUSEDATA-FILE Convert Musedata to LilyPond. Options
Report bugs to bug-gnu-music@gnu.org. Written by hanwen@cs.uu.nl. 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. Invoking mup2lymup2ly [OPTION]... MUP-FILE Convert Mup to LilyPond. Options
BUGS Currently, only plain notes (pitches, durations), voices and staffs are converted. Written by janneke@gnu.org, based on pmx2ly. Report bugs to bug-gnu-music@gnu.org. 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
Function 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 Chords\include "english.ly" scheme = \chords { c % Major triad cs:m % Minor triad df:m5- % Diminished triad c:5^3 % Root-fifth chord c:4^3 % Suspended fourth triad c:5+ % Augmented triad c:2^3 % "2" chord c:m5-.7- % Diminished seventh c:7+ % Major seventh c:7.4^3 % Dominant seventh suspended fourth c:5+.7 % Augmented dominant seventh c:m5-.7 % "Half" diminished seventh c:5-.7 % Dominant seventh flat fifth c:5-.7+ % Major seventh flat fifth c:m7+ % Minor-major seventh c:m7 % Minor seventh c:7 % Dominant seventh c:6 % Major sixth c:m6 % Minor sixth c:9^7 % Major triad w/added ninth c:6.9^7 % Six/Nine chord c:9 % Dominant ninth c:7+.9 % Major ninth c:m7.9 % Minor ninth } \score { \notes < \context ChordNames \scheme \context Staff \transpose c'' \scheme > \paper { \translator { \ChordNamesContext ChordName \override #'word-space = #1 ChordName \override #'style = #'american } } } Jazz chordsSimilarly, Jazz style chord names are implemented as a variation on American style names: scheme = \chords { % major chords c c:6 % 6 = major triad with added sixth c:maj % triangle = maj c:6.9^7 % 6/9 c:9^7 % add9 % minor chords c:m % m = minor triad c:m.6 % m6 = minor triad with added sixth c:m.7+ % m triangle = minor major seventh chord c:3-.6.9^7 % m6/9 c:m.7 % m7 c:3-.9 % m9 c:3-.9^7 % madd9 % dominant chords c:7 % 7 = dominant c:7.5+ % +7 = augmented dominant c:7.5- % 7b5 = hard diminished dominant c:9 % 7(9) c:9- % 7(b9) c:9+ % 7(#9) c:13^9.11 % 7(13) c:13-^9.11 % 7(b13) c:13^11 % 7(9,13) c:13.9-^11 % 7(b9,13) c:13.9+^11 % 7(#9,13) c:13-^11 % 7(9,b13) c:13-.9-^11 % 7(b9,b13) c:13-.9+^11 % 7(#9,b13) % half diminished chords c:m5-.7 % slashed o = m7b5 c:9.3-.5- % o/7(pure 9) % diminished chords c:m5-.7- % o = diminished seventh chord } \score { \notes < \context ChordNames \scheme \context Staff \transpose c'' \scheme > \paper { \translator { \ChordNamesContext ChordName \override #'word-space = #1 ChordName \override #'style = #'jazz } } } MIDI 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)" 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 gnu-music-discuss@gnu.org. Please send comments on these web pages to (address unknown) Copyright (c) 1997--2001 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.4.2 by