![]() |
GNU LilyPondWelcome to the home of the GNU Music Typesetter |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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. Table of Contents
TutorialIntroductionLilyPond prints music from a specification that you, the user, supply. You have to give that specification using a language. This chapter is a gentle introduction to that language. 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 Running LilyPondBefore we dive into describing the input language of LilyPond, we first show you through the procedure for getting notes on your screen and out of your printer. The first step is creating an input file. Using your favorite
text-editor, create \header { title = "Test"; } \score { \notes { c'4 e'4 g'4 } \paper { } } UnixIf you run Unix, proceed as follows: run lilypond on the file, i.e., lilypond testYou will the following on your screen: GNU LilyPond 1.3.125. Now processing: `input/tutorial/test.ly' Parsing... Interpreting music...[1] Preprocessing elements... Calculating column positions... [2] paper output to test.tex... Now, run TeX2. The result should resemble this: This is TeX, Version 3.14159 (Web2C 7.3.1) (test.tex (/home/hanwen/usr/share/lilypond/tex/lilyponddefs.tex (/home/hanwen/usr/share/lilypond/tex/lilypond-plaintex.tex LilyPond Plain TeX settings) (/home/hanwen/usr/src/ ... (/home/hanwen/usr/share/lilypond/tex/lily-ps-defs.tex) [footer empty] (/home/hanwen/usr/share/lilypond/tex/fetdefs.tex)) [1] ) Output written on test.dvi (1 page, 3716 bytes). Transcript written on test.log.The result of the TeX run is a TeX "DeVice Independent" file ( test.dvi ).
To view the output, run Xdvi, i.e. xdvi testYou should will see this
When you're satisfied with the result, you can print it. For printing, you have to generate a postscript file: dvips -o test.ps test.dviwhich looks like this: This is dvips(k) 5.86 Copyright 1999 Radical Eye Soft ... ' TeX output 2001.01.27:1806' -> test.ps <texc.pro><special.pro>. [1] PostScript is a page description language, similar to PDF. Some printers can understand a postscript file directly, but the cheapers need the intervention of GhostScript, a PostScript emulator that runs on your computer instead of your printer. Most Linux distributions nowadays have GhostScript running "in the background", so any configured printer will act as a PostScript printer. Assuming this, the following command will print the file lpr test.psIf this does not make your printer produce a page of music, then you should look into installing and configuring ghostscript. Refer to GhostScript's website at http://www.ghostscript.com. There are two different routes: firstly, you can add titling to the
output. This is done by a separate program called ly2dvi: this program
first calls LilyPond to process the ly2dvi test.lyAfter some disk-activity, you should end up with a .dvi file.
6
Secondly, you can generate PostScript directly. This is not very useful
currently, but here goes:
lilypond -f ps test.ly [treat FAQs here, eg. about env vars.] WindowsThe first tuneTo demonstrate what LilyPond input looks like, we start off with a
full-fledged, yet simple example. It is a convoluted version
of the famous menuet in J. S. Bach's Klavierbüchlein. The file
is included in the distribution as % lines preceded by a percent are comments which % are 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 wide for a book linewidth = 14.0 \cm; } }
We will analyse the input, line by line. % lines preceded by a percent are comments which % are ignored by Lilypond.The percent sign, % , introduces a line comment. If you want to
make larger comments, you can use block comments. These are delimited
by %{ and %}
\include "paper16.ly"By default, LilyPond will use definitions for a staff that is 20 point3 high. We want smaller output (16 point staff height), so we must import the settings for that size, which is done here. \score {A lilypond file combines music with directions for outputting that music. The music is combined with the output directions by putting them into a \score block.
\notesThis makes LilyPond ready for accepting notes. \relative c'' As we will see, pitches are combinations of octave, note name and
chromatic alteration. In this scheme, the octave is indicated by
using raised quotes ( For pitches in a long piece you might have to type many quotes. To remedy this, LilyPond has a "relative" octave entry mode. In this mode, octaves of notes without quotes are chosen such that a note is as close as possible (graphically, on the staff) to the the preceding note. If you add a high-quote an extra octave is added. The 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/4;This command changes the time signature of the current piece: a 3/4 sign is printed. This command is also used to generate bar lines in the right spots. \key g \major;This command changes the current key signature to G-major. Although this command comes after the \time command, in the output, the key
signature comes before the time signature: LilyPond knows about music
typesetting conventions.
\repeat "volta" 2This command tells LilyPond that the following piece of music must be played twice. The first argument indicates the type of repeat. In this case, "volta" means that volta brackets are be used for
alternatives--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.
d4This is a note with pitch d (determined up to octaves). The
relative music was started with a c'' , so the real pitch of this
note is d'' . The 4 designates the duration of the note
(it is a quarter note).
a bThese are notes with pitch a and b . Because their
duration is the same as the g , there is no need to enter the
duration (You may enter it anyway, e.g. a4 b4 )
d4 g, g |Three more notes. The | character is a `bar check'. When
processing the music, LilyPond will verify that bar checks are found at
the start of a measure. This can help you track down errors.
So far, no notes were chromatically altered. Here is the first one
that is: c8 d e fisLilyPond guesses were beams can be added to eighth and shorter notes. In this case, a beam over 4 eighths is added. c4 d8( )c b a( )b4 c8 b a g |The next line shows how to make a slur: the beginning and ending note of the slur is marked with an opening and closing parenthesis respectively. In the line shown above, this is done for two slurs. Slur markers (parentheses) are put between the slurred notes. a4 [b8 a] [g fis]Automatic beaming can be overridden by inserting beam marks (brackets). Brackets are put around the notes you want beamed. g2. |A duration with augmentation dot is notated with the duration number followed by a period. }This ends the sequential music to be repeated. LilyPond will typeset a repeat bar. cis'4 b8 cis a4 |This line shows that Lily will print an accidental if that is needed: 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 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 notename d2.-\fermataAll articulations have a verbose form, like \fermata . The
command \fermata is not part of the core of the language (most
of the other discussed elements are), but it is a shorthand for a more
complicated description of a fermata. \fermata names that
description and is therefore called an identifier.
} Here the music ends. \paper { linewidth = 14.0\cm; }This specifies a conversion from music to notation output. Most of the details of this conversions (font sizes, dimensions, etc.) have been taken care of, but to fit the output in this document, it has to be smaller. 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.4. 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 this5. 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. An assignment starts
with a string. (which is unquoted, in this case). Then comes the
equal sign. After the equal sign comes the expression you
want to store. In this case, you want to put in strings. The
information has to be quoted here, because it contains spaces. Each
assignment is finished with a semicolon.
\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 \minor;The 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 will turn automatic beams off, and use explicit beaming where needed. }This ends the definition of melody . Note that there are no
semicolons after assignments at top level.
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, called \chords . There is a special mode (analogous
to \lyrics and \notes mode) where you can give the names
of the chords you want, instead of 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, while a minor triad is wanted. d:min es4 c8:min r8 Some modifiers have predefined names, eg. 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.
\context ChordNames \accompanimentNormally, the notes that you enter are transformed into note heads. The 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 only exist during a run of LilyPond. Interpretation contexts that are for printing music (as opposed to playing music) are called `notation contexts'. By default, LilyPond will create a Staff context for you. If you
removed the We don't want that default here, because we want chord names, not note heads.
An interpretation context can also created upon explicit request. The
keyword for such a request is \addlyrics The lyrics need to be aligned with the melody. This is done by
combining both with \context Staff = mel { This is the argument of \property Staff.noAutoBeaming = ##tAn interpretation context has variables that tune its behaviour. One of the variables is noAutoBeaming . If set to ##t , which is
the boolean value true, LilyPond will not try to put automatic beaming
on the current staff.
LilyPond internally uses GUILE, a Scheme-interpreter6 to represent data throughout the whole
program. The hash-sign ( \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 notes
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.
}This ends \simultaneous .
\midi { \tempo 4=72;}This makes the music go to a MIDI file. MIDI is great for checking music you enter. You listen to the MIDI file: if you hear something unexpected, it's probably a typing error. \midi starts an output
definition, a declaration that specifies how to output music analogous
to \paper { } . You can specify the tempo using the
\tempo command, in this case the tempo of quarter notes is set to
72 beats per minute.
\paper { linewidth = 10.0\cm; }We also want notation output. The linewidth is short so the piece will be set in two lines. }End the score block. More movementsYou probably ran
For example, the following file ( \version "1.3.124"; \header { title = "Two miniatures"; } #(set! point-and-click #t) \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"; } }results in something like this7 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, ... \placebox{-5 \outputscale }% { 8.7229 \outputscale }% {\magfontWXGEomMMBo\char90 }% \placebox{-4 \outputscale }% { 81.0647 \outputscale }% ...
\geometry{width=540.602362pt,headheight=2mm, ... \renewcommand{\@oddfoot}{\parbox{\textwidth}{\mbox{} ... \begin{document} \lilypondtitle{foo}% \makelilytitle \input{ly2dvi.tex}
Next, now we'll look at the examples line by line to explain new things. \version "1.3.124";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. #(set! point-and-click #t) This is Scheme code. It sets the 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: 8 when you view the file with Xdvi and click on a note using control-mousebutton 19, your editor will jump to the spot where that note was entered. More information is in in 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 would put it closest to its
predecessor. Besides relative, there is also absolute octave
specification, and it is turned on by default. In this input mode, the
central C is denoted by 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, either by hand (ie. composing) or by computer, absolute octaves are probably less work. \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 third 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' { c8 \stemdown c'8 \stemup } 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 it looks like incomprehensible gibberish to you, then you are right. This example has been doctored to have as many quirks as possible. stemdown = \property Voice.Stem \override #'direction = #-1 As you can see, this example features more voices on one staff. To make room for those voices, their notes have to be stemmed in opposite directions. These are the commands to make that happen. The symbols that are printed, are internally represented by so-called
Graphical Objects (or 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 This statement adds a the setting for all Stem grobs in the current
Voice: \property Voice.Stem \revert #'direction This statement reverts the old setting. If you do this, the effect of a
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 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 an 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. 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 8This repeat print the following sequence notes 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 = downThe rest of this melody must be in 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.
\context PianoStaffA special context is needed to get cross staff beaming right. This context is called PianoStaff .
\context Staff = bottom < \time 2/2; \clef bass;The bottom staff must have a different clef. indent = 0.0;To 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. [TODO: * arpeggio, glissando, * \apply, \outputproperty, \translator {}, \molecule hacking. * font-size, cadenza. rhythmic staff, multi-stanza. * Orchestral: demonstrate Hara-Kiri, part combining, part extraction, scores, transposition, instrument names, The endThat's all folks. From here, you can either try fiddling with input files, or you can read the reference manual. Reference ManualThis document describes GNU LilyPond and its input format. This document has been revised for LilyPond 1.3.125 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 esthetic decisions. All symbols and their placement is generated from a high-level musical description. In other words, LilyPond would be best described by `music compiler' or `music to notation compiler'. Internally, LilyPond is written in a mixture of Scheme and C++. Most of the algorithms and low-level routines are written in C++, but these low level components are glued together using Scheme data structures. LilyPond is linked to GUILE, GNU's Scheme library for extension. When lilypond is run to typeset sheet music, the following happens:
These stages, involve data of a specific type: during parsing, Music objects are created. During the interpretation, context is constructed, and with this context af network of graphical objects ("grobs") is created. The 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. This manual is ordered in terms of user tasks. With each concept will be explained to which of the three parts it belongs. LilyPond input can be classified into three types:
Modifying musicFIXME: more verbose titling: music expressions? Repeat? Repeated music? Repeating music expressions? ApplyApply allows a Scheme-function to operate directly on the internal representation of music. \apply #func musicThe function takes two arguments, being a function and an musical argument for that function. The function should return a music expression. This example replaces the text string of a script. It also shows a dump of the music it processes. #(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 { c4_"foo" } }
For more information on what is possible, see the Tricks and the automatically generated documentation. RepeatsIn order to specify repeats, use the
Repeat syntaxThe syntax for repeats is \repeat variant repeatcount repeatbody If you have alternative endings, you may add \alternative where 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:10 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 3 { e | c2 d2 | e2 f2 | } \alternative { { g4 g g } { a | a a a a | b2. } } } } As you can see, LilyPond doesn't remember the timing information, nor are slurs or ties repeated. We hope to fix this after 1.4. It is possible to nest Manual repeat commandsThe property
c''4 \property Score.repeatCommands = #'((volta "93") end-repeat) c4 c4 \property Score.repeatCommands = #'((volta #f)) c4 c4 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 } \paper { linewidth = 40*\staffspace; } } Tremolo subdivisionTremolo marks can be printed on a single note by adding
` c'2:8 c':32
Tremolos in this style do not carry over into the MIDI output. Using this mechanism pays off when you entering many tremolos, since the default argument saves a lot of typing. Note entryNotes modeNote mode is introduced by the keyword
Since combinations of numbers and dots are used for indicating durations, it is not possible to enter real numbers in this mode. 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
LilyPond has predefined sets of notenames 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' d' e' f' g' a' b' c''
cis' dis' eis' fis' gis' ais' bis'
ces' des' es' fes' ges' as' bes'
cisis' eisis' gisis' aisis' beses'
ceses' eses' geses' ases' beses' Defining pitch namesNote names and chord modifiers can be customised for nationalities. The syntax is as follows. \pitchnames scheme-alist \chordmodifiers scheme-alist See DurationsThe syntax for an verbose duration specification is \duration scmduration 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 note, use identifiers. c'\longa 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 As you can see, the longa is not printed. To get a longa note head, you have to use a different style of note heads. See [TODO]. If the duration is omitted then it is set equal to the previous duration
entered. At the start of parsing there is no previous duration, so then
a quarter note is assumed. The duration can be followed by a dot
(` a'4. b'4.
You can alter the length of duration by writing ` NotesA note specification has the form pitch[octavespec][!][?][duration] LilyPond will determine what accidentals to typeset depending on the key
and context, so alteration refer to what note is heard, not to whether
accidentals are printed. A reminder accidental
can be forced by adding an exclamation mark i.e., an accidental within parentheses can be obtained by adding the
question mark ` cis' d' e' cis' c'? d' e' c'! RestsRests are entered like notes, with note name ` Skip \skip duration
Skips the amount of time specified by duration. If no other music is played, a gap will be left for the skipped time with no notes printed. It works in Note Mode or Lyrics Mode. In Note mode, this has the same effect as the spacer rest. Music notationKey
Change the key signature. type should be Clef changes \clef clefname
Short-cut for \property Staff.clefGlyph = symbol associated with clefname \property Staff.clefPosition = clef Y-position for clefname \property Staff.clefOctavation = extra pitch of clefname Supported clef-names include Time signature\time numerator A short-cut for doing \property Score.timeSignatureFraction = #'(numerator . denominator) See the documentation of Partial \partial duration
Short cut for \property Score.measurePosition = length of duration See the documentation of Polyphony[todo : collisiosn, rest-collisinos, voiceX identifiers, how to which contexts to instantiate.]
SpannersBeamsAutomatic beamsLilyPond will group flagged notes and generate beams autmatically, where appropriate. This feature can be disabled by setting the A large number of Voice properties are used to decide how to generate
beams. Their default values appear in \property Voice.autoBeamSettings \override #'(end * * * *) = #(make-moment 1 4) \property Voice.autoBeamSettings \override #'(begin * * * *) = #(make-moment 1 8) To allow different settings for different time signatures, instead of
the first two asterisks To allow different endings for notes of different durations, instead of
th last two asterisks you can specify a duration; use For example, to specify beam endings for beams that contain 32nd notes,
you would use 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, so if you want that, specify the begin and end point
manually using \context Staff { r4 [r8 g'' a r8] r8 [g | a] r8 } Adjusting beamsSlurSlurs connects chords and try to avoid crossing stems. A slur is
started with f'()g'()a' [a'8 b'(] a'4 g'2 )f'4
Adjusting slursSlur attachmentsThe ending of a slur should whenever possible be attached to a note
head. Only in some instances where beams are involved, LilyPond may
attach a slur to a stem end. In some cases, you may want to override
LilyPond's decision, e.g., to attach the slur to the stem end. This can
be done through \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 Similarly, slurs can be attached to note heads even when beams are involved: \property Voice.Slur \set #'direction = #1 \property Voice.Slur \set #'attachment = #'(head . head) g''16()g()g()g()d'()d()d()d If a slur would strike through a stem or beam, LilyPond will move the slur away vertically (upward or downward). In some cases, this may cause ugly slurs that you may want to correct: \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.. LilyPond will increase the curvature of a slur trying to stay free of
note heads and stems. However, if the curvature would increase too much,
the slur will be reverted to its default shape. This decision is based
on [hoe gedefd?? wat betekent beautiful = X?] \score { \notes \context PianoStaff < \time 6/4; \context Staff=up { s1 * 6/4 } \context Staff=down < \clef bass; \autochange Staff \context Voice \notes \relative c { d,8( a' d f a d f d a f d )a } > > \paper { linewidth = -1.; \translator { \VoiceContext Slur \override #'beautiful = #5.0 Slur \override #'direction = #1 Stem \override #'direction = #-1 autoBeamSettings \override #'(end * * * *) = #(make-moment 1 2) } \translator { \PianoStaffContext VerticalAlignment \override #'threshold = #'(5 . 5) } } } TieA tie connects two adjacent note heads of the same pitch. When used
with chords, it connects all of the note heads whose pitches match.
Ties are indicated using the tilde symbol ` e' ~ e' <c' e' g'> ~ <c' e' g'>
TupletsTuplets are made out of a music expression by multiplying their 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
[todo: document tupletSpannerDuration] Text spannerOttavaOttava[move to trick. Not a supported feature.] 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" Span requests\spanrequest startstop type Define a spanning request. The startstop parameter is either -1
( You can attach a (general) span request to a note using c'4-\spanrequest \start "slur" c'4-\spanrequest \stop "slur"
The slur syntax with parentheses is a shorthand for this. OrnamentsArticulationA 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 Text scriptsFIXME: markup In addition, it is possible to place arbitrary strings of text or
TeX above or below notes by using a string instead of an
identifier: FingeringsTo save typing, fingering instructions (digits 0 to 9 are supported) and single characters shorthands exist for a few common symbols
\textscript text style Defines a text to be printed over or under a note. style is a
string that may be one of You can attach a general textscript request using this syntax: c4-\textscript "6" "finger" c4-\textscript "foo" "normal" This is equivalent to \script alias Prints a symbol above or below a note. The argument is a string which
points into the script-alias table defined in For information on how to add scripts, consult Grace notes\grace musicexpr A grace note expression has duration 0; the next real note is assumed to be the main note. You cannot have the grace note after the main note, in terms of
duration, and main notes, but you can typeset the grace notes to the
right of the main note using the property
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 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. This behavior can be controlled with the
\relative c'' { \grace c8 c4 \grace { [c16 c16] } c4 \grace { \property Grace.flagStyle = "" c16 } c4 } At present, 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 is not robust and generally kludgy. We expect it to change after LilyPond 1.4. Syntax changes might also be implemented. GlissandoA glissando line can be requested by attaching a c'' \glissando c' Printing of an additional text (such as gliss.) must be done manually. DynamicsDynamic marks are specified by using an identifier after a note:
Crescendo and DecrescendoA crescendo mark is started with c'' \< \! c'' d'' \decr e'' \rced < f''1 { s4 \< \! s2 \> \! 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 } Bar lines\bar bartype; This is a short-cut for doing \property Score.whichBar = bartype You are encouraged to use Breath marksBar 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, Piano musicAutomatic staff changesManual staff switches\translator contexttype = name A music expression indicating that the context which is a direct child of the a context of type contexttype should be shifted to a context of type contexttype and the specified name. Usually this is used to switch staffs in Piano music, e.g. \translator Staff = top Music PedalsArpeggioYou 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>} > Follow Thread[todo: different name, eg. voice line ? ] Whenever 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.followThread = ##t \context Staff \context Voice { c'1 \translator Staff=two b2 a } \context Staff=two {\clef bass; \skip 1*2;} > LyricsLyrics modeLyrics mode is introduced by the keyword 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 ` Ah! % a word 2B_||_!2B % not a word because it starts with a digit ``Hello'' % not a word because it starts with ` _ _ _ _ % 4 words, each one a space Since combinations of numbers and dots are used for indicating durations, you can not enter real numbers in this mode. Syllables are entered like notes, with pitches replaced by text. For
example, Spaces can be introduced into a lyric either by using quotes
( Printing lyricsLyric syllables must be interpreted within a \score { < \notes \transpose c'' { c d e c | c d e c | e f g2 | e4 f g2 \bar "|."; } \context Lyrics \lyrics { Va-4 der Ja- cob Va- der Ja- cob Slaapt gij nog?2 Slaapt4 gij nog?2 } > } You may want a continuous line after the syllables to show melismata.
To achieve this effect, add a \score { < \notes \relative c'' { a4 () b () c () d | c () d () b () a | c () d () b () a } \context Lyrics \lyrics { foo1 __ | bar2. __ _4 | baz1 __ } > } If you want to have hyphens centered between syllables (rather than
attached to the end of the first syllable) you can use the special
` \score { < \notes \transpose c'' { c d e c | c d e c | e f g2 | e4 f g2 \bar "|."; } \context Lyrics \lyrics { Va4 -- der Ja -- cob | Va -- der Ja -- cob | Slaapt gij nog?2 | Slaapt4 gij nog?2 } > } Automatic syllable durations[explain automatic phrasing] If you have lyrics that are set to a melody, you can import the rhythm
of that melody into the lyrics using \addlyrics musicexpr1 musicexpr2 This means that both musicexpr1 and musicexpr2 are interpreted, but that every non-command atomic music expression ("every syllable") in musicexpr2 is interpreted using timing of musicexpr1. If the property \addlyrics \transpose c'' { \property Voice.automaticMelismata = ##t c8 () cis d8. e16 f2 } \context Lyrics \lyrics { do4 re mi fa } You should use a single rhythm melody, and single rhythm lyrics (a constant duration is the obvious choice). If you do not, you will get undesired effects when using multiple stanzas: \addlyrics \transpose c'' { c8 () cis d8. e16 f2 } \context Lyrics \lyrics < { do4 re mi fa } { do8 re mi fa } > It is valid (but probably not very useful) to use notes instead of lyrics for musicexpr2. Chords[chords vs. simultaneous music] Chords modeChord mode is introduced by the keyword
Since combinations of numbers and dots are used for indicating durations, you can not enter real numbers in this mode. Dashes and carets are used to indicate chord additions and subtractions, so scripts can not be entered in Chord mode. Entering named chordsChord names are a way to generate simultaneous music expressions that correspond with traditional chord names. It can only be used in Chord mode (see section Lexical modes). 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 chord additions, which 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- c:4.6.8 } } 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 } }
The most interesting application is printing chord names, which is explained in the next subsection. You should not combine Printing named chordsFor displaying printed chord names, use the scheme = \notes { \chords {a1 b c} <d f g> <e g b> } \score { \notes< \context ChordNamesVoice \scheme \context Staff \transpose c'' \scheme > \paper { linewidth = -1.; } } You can make the chord changes stand out more by setting property
scheme = \chords { c1:m \break c:m c:m c:m d } \score { \notes < \context ChordNames \scheme \context Staff \transpose c'' \scheme > \paper{ linewidth = 40 * \staffspace; \translator { \ChordNamesContext chordChanges = ##t } } } 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 added base, 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 ChordNamesVoice \scheme \context Staff \scheme > \paper { linewidth = -1.; } } To specify chord inversions, append scheme = \chords { d1 d/a d/+gis } \score { \notes < \context ChordNames \scheme \context Staff \transpose c'' \scheme > \paper { linewidth = -1.; } } The chord names that LilyPond should print are fully customizable. The
code to print chord names is written in Scheme. It can be found in
\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 } } } Similarly, 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 } } } Writing parts[TODO: partcombine rehearsal marks bar numbering tranposing midi property. Rehearsal marks\mark unsigned; \mark string; Prints a mark over or under the staff. 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 Multi measure restsMulti measure rests are entered using ` \time 3/4; R2.*2 \property Score.skipBars = ##t R2.*17 R2.*4
Currently, there is no way to condense multiple rests into a single multimeasure rest. Page layoutPaper 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:
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" \score { ... \paper { \paperSixteen } } The file "paper16.ly" will now include a file named 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 Similarly, The \penalty int
This imposes encourages or discourages LilyPond to make a line break at this point. Warning do not use Page breakPage breaks are normally computed by TeX, so they are not under direct
control. However, you can insert a commands into the SoundMIDI 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 [FIXME: to appendix ] "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)" Tempo \tempo duration = perminute
Used to specify the tempo. For example, Music entryRelativeOctaves 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.
The octave changing marks This distance is determined without regarding accidentals: a
Entering scales is straightforward in relative mode. \relative c'' { g a b c d e f g g, g }
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. But 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 Point and clickEngraversSelecting contexts\context contexttype [= contextname] musicexpr Interpret musicexpr within a context of type contexttype. If the context does not exist, it will be created. The new context can optionally be given a name. Context definitionsA notation contexts is defined by the following information
A context definition has this syntax: \translator translatorinit can be an identifier or \type typename
where typename is one of
translatormodifierlist is a list of items where each item is one of
In the \paper { foo = \translator { ... } } \score { \notes { ... } \paper { \translator { \foo ... } } } Some pre-defined identifiers can simplify modification of translators. The pre-defined identifiers are:
Using these pre-defined values, you can remove or add items to the translator: \paper { \translator { \StaffContext \remove Some_engraver; \consists Different_engraver; } } Notation ContextsNotation contexts are objects that only exist during a run of
LilyPond. During the interpretation phase of LilyPond, the Music
expression contained in a A context is an object that holds the reading state of the expression; 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. Contexts are created either manually or automatically. Initially, the
top level music expression is interpreted by the top level context (the
\score { \notes { c4 } } The sequential music, ` You can also create contexts manually, and you probably have to do so
if you want to typeset complicated multiple part material. If a
` [type vs id] If a context of the specified type and name can not be found, a new one is created. For example, \score { \notes \relative c'' { c4 <d4 \context Staff = "another" e4> f } } In this example, the Almost all music expressions inherit their interpretation context from their parent. In other words, suppose that the syntax for a music expression is \keyword musicexpr1 musicexpr2 ... When the interpretation of this music expression starts, the context for musicexpr1, musicexpr2, etc. is that of the total expression. Lastly, you may wonder, why this: \score { \notes \relative c'' { c4 d4 e4 } } doesn't result in this:
For the 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 preset within the propname
This assignment happens before interpretation starts, so a
The property settings are used during the interpretation phase. They are read by the LilyPond modules where interpretation contexts are built of. These modules are called translators. Translators for notation are called engravers, and translators for sound are called performers. Syntactic detailsTop levelThis section describes what you may enter at top level. Score definitionThe 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 no output
definition is supplied, the default ScorePaperMidiHeaderThe syntax is \header { key1 = val1; key2 = val2; ... } A header describes the file's contents. It can also appear in a
It is customary to put the Default outputA paper block for all scores that lack an explicit paper block. IdentifiersAll of the information in a LilyPond input file, is 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. Other compound music expressions include \repeat expr \transpose pitch expr \apply func expr \context type = id expr \times fraction expr In principle, the way in which you nest sequential and simultaneous to produce music is not relevant. In the following example, three chords are expressed in two different ways: \notes \context Voice { <a c'> <b d' > <c' e'> < { a b c' } { c' d' e' } > }
However, in some cases, LilyPond will also try to choose contexts, and
use the structure of the music expression to do so. This can have
undesired effects: for example, LilyPond will create a separate staff
for each note if you start a \score { \notes <c''4 e''> \paper { linewidth = -1.; } }
\score { \notes\context Voice <c''4 e''> \paper { linewidth = -1.; } }
AssignmentsIdentifiers allow objects to be assigned to names during the parse
stage. To assign an identifier, you use name Semicolons are forbidden after top level assignments, but mandatory in other places. The rules about semicolons and assignments are very confusing, but when LilyPond input evolves more towards Scheme, we hope that this problem will grow smaller. 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 detailsCommentsA 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: whereever it is allowed, #schemeevaluates the specified Scheme code. If this is used at toplevel, then the result is discarded. Example: \property Staff.TestObject \override #'foobar = #(+ 1 2)
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 The tokenizer accepts the following commands. They have no grammatical function, hence they can appear anywhere in the input. Main inputThe Main inputFile 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 Defining pitch namesA AssignmentsIdentifier assignments may appear at top level. Assignments Direct schemeScheme statements maybe issued to produce interesting side-effects. Lexical modesTo simplify entering notes, lyrics, and chords, LilyPond has three
special input modes on top of 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 expressions
In each of these cases, these expressions do not add anything to the meaning of their arguments. They are just a way to indicate that the arguments should be parsed in indicated mode. The modes are treated in more detail in the sections Note entry, Lyrics and Chords. You may nest different input modes. AmbiguitiesThe grammar contains a number of ambiguities. We hope to resolve them at some time.
Unsorted[mucho todo] Translation? Translation property[todo: add \set/\override/\revert] \property contextname.propname = value Sets the propname property of the context contextname to the specified value. All three arguments are strings. Depending on the context, it may be necessary to quote the strings or to leave space on both sides of the dot. Output propertiesThese allow you to tweak what is happening in the back-end directly. If you want to control every detail of the output formatting, this is the feature to use. The downside to this is that you need to know exactly how the backend works. Example: \relative c'' { c4 \context Staff \outputproperty #(make-type-checker 'note-head-interface) #'extra-offset = #'(0.5 . 0.75) <c8 e g> }
This selects all note heads occurring at current staff level, and sets
the Use of this feature is entirely on your own risk: if you use this, the result will depend very heavily on the implementation of the backend, which we change regularly and unscrupulously. Don't move the finger 2, only text "m.d." ... #(define (make-text-checker text) (lambda (grob) (equal? text (ly-get-elt-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." } \paper { linewidth = -1.; } } TricksManual beam settingsConventionally, stems and beams extend to the middle staff line. This
extension can be controlled through \grace a'8 a4 \property Voice.Stem \set #'no-stem-extend = ##t \grace g8 g4 [g8 g] The beam symbol can be tweaked through 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 = #2 \property Voice.Beam \set #'height = #-2 [c'8 c] The direction of a perfectly centred beams can be
controlled through [b''8 b] \property Voice.Beam \set #'default-neutral-direction = #-1 [b b] There are several ways to calculate the direction of a beam.
You can spot the differences of these settings from these simple examples: [d''8 a] \property Voice.Beam \set #'dir-function = #beam-dir-mean [d a] \property Voice.Beam \set #'dir-function = #beam-dir-median [d a] \time 3/8; [d''8 a a] \property Voice.Beam \set #'dir-function = #beam-dir-mean [d a a] \property Voice.Beam \set #'dir-function = #beam-dir-median [d a a] These beam direction functions are defined in Engraver hackingNo time signature, no barlines... \score { \notes \relative c'' { a b c d d c b a } \paper { linewidth = -1.; \translator { \StaffContext whichBar = #"" \remove "Time_signature_engraver"; } } }
No staff, no clef, squash pitches \score { \notes { c4 c4 c8 c8 } \paper { linewidth = -1.; \translator { \StaffContext \remove Staff_symbol_engraver; \consists Pitch_squash_engraver; \remove Clef_engraver; } } } Part combiner\score{ \context Staff = flauti < \time 4/4; \context Voice=one \partcombine Voice \context Thread=one \notes\relative c'' { c4 d e f | b,4 d c d | r2 e4 f | c4 d e f | c4 r e f | c4 r e f | c4 r a r | a a r a | a2 \property Voice.soloADue = ##f a | } \context Thread=two \notes\relative c'' { g4 b d f | r2 c4 d | a c c d | a4. b8 c4 d c r e r | r2 s2 | a,4 r a r | a r r a | a2 \property Voice.soloADue = ##f a | } > \paper{ linewidth = 80 * \staffspace; \translator{ \ThreadContext \consists Rest_engraver; } \translator{ \VoiceContext \remove Rest_engraver; } } } Markup textMetrome hack... [todo: hack this into C++, use \tempo] #(define note '(rows (music "noteheads-2" ((kern . -0.1) "flags-stem")))) #(define eight-note `(rows ,note ((kern . -0.1) (music ((raise . 3.5) "flags-u3"))))) #(define dotted-eight-note `(rows ,eight-note (music "dots-dot"))) \score { \notes\relative c'' { a1^#`(rows ,dotted-eight-note " = 64") } \paper { linewidth = -1.; \translator{ \ScoreContext TextScript \override #'font-shape = #'upright } } } Apply hackingmusic = \notes { c'4 d'4( e'4 f'4 } #(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)) \score { \context Voice { \music \apply #reverse-music \music } \paper { linewidth = -1.; } } Embedded TeXa''^"3 $\\times$ \\`a deux" Embedded PostScriptArbitrary lines and curves not supported... [TODO:] Make a direct postscript command? \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; } } InternalsConversion stagesWhen translating the input to notation, there are number of distinct phases. We list them here:
MomentMoment is a rational number. Since GUILE doesn't support them natively, so we created our own rational data type.
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 defintion
of the "Stem" grob with the setting What is a grob?[TODO: document/explain interfaces] 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 node in that graph. A grob stores references to other grobs, the directed edges in the graph. The objective of this big graph of grobs, is to specify the notation problem. The solution of this problem is a description of the printout that is in closed form, i.e. but 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, or 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. Whenever 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 Often, a grob also is associated with a symbol. However, some
grobs do not print any symbols, but take care of grouping objects. For
example, there is a separate grob that stacks staffs vertically, so they
are not printed in overstrike. The A complete list of grob types is found in (lilypond-internals)LilyPond backend Grobs are created in the "Interpreting music" phase, by objects in LilyPond called engravers. In this phase of the translation, a load of grobs are created, and they are linked into a giant network of objects. This network of grobs forms the "specification" of the print problem. This problem is then solved: configurations, directions, dimensions, line breaks, etc. are calculated. Finally, the printing description in the form of Molecules (Molecules) is extracted from the network. These are then dumped into the output file 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: Y-offset-callbacks is also a property) Offset callbacks can be stacked, ie. \property .... \override #'Y-offset-callbacks = #(list callback1 callback2 callback3) The callbacks will be executed in the order callback3 callback2 callback1. This is used for quantized positioning: the staccato dot is above or below a note head, and it must not be on a staff-line. To achieve this, for the staccato there are two callbacks: one callback that positions the grob above or below the note head, and one callback that rounds the Y-position of the grob to the nearest open space. 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. From C++, element properties can be accessed using the 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); In GUILE, LilyPond provides ly-get-grob-property GROB SYMBOL ly-set-grob-property GROB SYMBOL VALUE All lookup functions identify undefined properties with
end-of-list (ie. Properties are stored in two ways:
There are two ways to manually set grob properties. You can change immutable grob properties. This is done with the \override syntax: \property Voice.Stem \override #'direction = #1 This will push the entry \property Voice.stem \revert #'direction If you use this a lot, this gets old quickly. So we also have a shorthand, \property Context.GrobType \set #'prop = #VAL this does a The second way is \outputproperty. This construct looks like \context ContextName \outputproperty pred #sym = #val In this case, in every grob that satisfies pred, the property assignment sym = val is done. For example \outputproperty #(lambda (gr) (string? (ly-get-grob-property gr 'text))) #'extra-offset = #'(-1.0 . 0.0) This shifts all elements that have a Items and SpannersGrobs can also be distinguished in their role in the horizontal spacing.
A lot of 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 (ie. 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 visibility-lambda. This is a function taking a direction (-1, 0 or 1) and returns a cons of booleans, signifying wether this grob should be transparent and have no extent. Grob Scheme functions
Duration
Pitch data type
EngraverEngravers are building blocks of contexts. They are not yet user accessible.
Music_iteratorThis data-type is a direct hook into some C++ constructor functions. It is not yet user-serviceable.
MusicMusic is the data type that music expressions are stored in. The data type does not yet offer many manipulations.
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:12. A molecule is an object that combines dimension information (how large is this glyph ?) with what-to-print-where. 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 (refer to the C++ code for more details). All visible,
i.e. non-transparant, grobs have a callback to create a Molecule. The
name of the property is [insert example of write your own.]
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 (
Miscellaneous Scheme functions
Invoking LilyPondlilypond [OPTION]... [MUDELA-FILE]... Command Options
When invoked with a filename that has no extension, LilyPond will try
adding ` 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://appel.lilypond.org/wiki?LilyPondBugs. ly2dvi
One or more LaTeX files are created, based on information found in the output (TeX) files, and latex is finally run to create one or more DVI files. The majority of this utility came from a bourne script written by Jan
Arne Fagertun name Invoking ly2dvily2dvi [options] inputfile[.ly] [....] Options
FeaturesLy2dvi responds to several parameters specified in the LilyPond file. They are overridden by corresponding command line options.
Environment
Files
VARIABLE-NAME=VALUE Where VARIABLE-NAME is the name of the variable documented below and VALUE is either a string, a 1, or a 0. All files are parsed, in the shown sequence. In the current version the following are allowed:
Initialization SequenceThe initialization process reads inputs for several sources. Below is a list of priorities for lowest to hightest proirity. [FIXME: should use ly2dvirc iso lilyrc]
BugsSee Bug reports. If you have found a bug, you should send a bugreport.
RemarksMany papersizes are now supported. Information on other sizes (LaTeX names, horizontal and vertical sizes) should be mailed to the author or to the mailing list. Supported papersizes are: a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, archA, archB, archC, archD, archE, b0, b1, b2, b3, b4, b5, flsa, flse, halfletter, ledger, legal, letter, note AuthorsPython Version author: Jeffrey B. Reed, http://home.austin.rr.com/jbr/jeff/lilypond/ Original bourne shell version author: Jan Arne Fagertun, http://www.termo.unit.no/mtf/people/janaf/ convert-lyConvert-ly sequentially applies different conversions to upgrade a
Lilypond input file. It uses Invoking convert-lyconvert-ly [options] [files]
Not all language changes are handled. Multiple output options won't work.
Converting to LilyPond format.midi2lyMidi2ly translates a MIDI input file to a LilyPond source file. Midi2ly is part of the GNU LilyPond music typesetting package. Human players usually are rhythmically not very exact when they record MIDI files. midi2ly tries to compensate for these errors, but is not very good at this. It is therefore not recommended to use midi2ly for human-generated midi files. Correcting the quantization mistakes of the human player takes a lot of time. Hackers who know about signal processing are invited to write a more robust midi2ly. Invoking midi2lymidi2ly [options] midi-file Options
etf2lyInvoking etf2lyUsage: etf2ly [OPTION]... ETF-FILE Convert ETF to LilyPond. Options:
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. Report bugs to bug-gnu-music@gnu.org Written by Han-Wen Nienhuys [descibe abc2ly, pmx2ly, etf2ly, musedata2ly here] LiteratureIf you need to know more about music notation, here are some interesting titles to read
Index
Function Index
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, 1998, 1999, 2000 Han-Wen Nienhuys and Jan Nieuwenhuizen. Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.
|