2 @c This file is part of lilypond.tely
5 @c * more details about running lilypond; error messages,
6 @c compiling/viewing (emacs?)
7 @c * where to go from First steps+More basics?
14 Using LilyPond comes down to encoding music in an input file. After
15 entering the music, the program is run on the file producing output
16 which can be viewed or printed. In this tutorial, we will show step
17 by step how to enter such files, and illustrate the process with
18 fragments of input and the corresponding output. At the end of every
19 section, a paragraph will list where to find further information on
22 Many people learn programs by trying and fiddling around with the
23 program. This is also possible with LilyPond. If you click on a
24 picture in the HTML version of this manual, you will see the exact
25 LilyPond input that was used to generate that image.
27 For example, consider the following input:
29 c'^\markup @{ \bold \huge @{ Click on this image! @} @}
31 @c @lily pond[relative=1,raggedright,with the following output:]
32 with the following output:
33 @lilypond[relative=1,raggedright]
34 c'^\markup { \bold \huge { Click on this image! } }
38 By cutting and pasting the full input into a test file, you have a
39 starting template for experiments. If you like learning in this way,
40 you will probably want to print out or bookmark
44 @ref{Cheat sheet}, which is a table listing all commands for quick
48 This tutorial starts with a short introduction to the LilyPond music
49 language. After this first contact, we will show you how to to
50 produce printed output. You should then be able to create and print
51 your first sheets of music.
56 * More about pitches::
58 * Combining music into compound expressions::
59 * Adding articulation marks to notes::
60 * Combining notes into chords::
61 * Basic rhythmical commands::
62 * Commenting input files::
65 * Listening to output::
67 * Single staff polyphony::
70 * Fine tuning layout::
71 * Organizing larger pieces::
72 * An orchestral part::
73 * Integrating text and music::
80 We start off by showing how very simple music is entered in LilyPond:
81 you get a note simply by typing its note name, from @samp{a}
82 through @samp{g}. So if you enter
89 then the result looks like this:
91 @lilypond[notime,relative]
95 The length of a note is specified by adding a number, @samp{1} for a
96 @rglos{whole note}, @samp{2} for a @rglos{half note}, and so on:
103 \set Score.timing = ##f
104 \set Staff.autoBeaming = ##f
105 \transpose c c' { a1 a2 a4 a16 a32 s16_" " }
108 If you do not specify a @rglos{duration}, the previous one is used:
115 \set Score.timing = ##f
116 \transpose c c' { a a a2 a s16_" " }
120 Rests are entered just like notes, but with the name ``@code{r}'':
129 \set Score.timing = ##f
130 \set Staff.Clef = \turnOff
131 \set Staff.TimeSignature = \turnOff
139 Add a dot @samp{.} after the duration to get a @rglos{dotted note}:
146 \set Score.timing = ##f
147 \transpose c c' { a2. a4 a8. a16 s16_" " }
151 The @rglos{meter} (or @rglos{time signature}) can be set with the
152 @code{\time} command:
160 @c a clef here may lead to confusion
162 \override Staff.Clef #'transparent = ##t
172 The @rglos{clef} can be set using the @code{\clef} command:
174 @c what is more common name treble or violin?
175 @c in Dutch, it's violin.
176 @c in English it's definitely treble.
185 \set Score.timing = ##f
196 Notes and commands like @code{\clef} and @code{\time}, are enclosed
197 in @code{\notes @{@dots{}@}}. This indicates that music (as opposed
198 to @rglos{lyrics}) follows:
208 Now the piece of music is almost ready to be printed. Enclosing the
209 music in a @code{\score} processes them to printed output,
210 so the following is a complete and valid input file:
232 linewidth = 55 * \staffspace
237 In many examples in this manual, @code{\score} is left out for
238 clarity. However, it must be present when feeding the file to
241 For more elaborate information on
244 @item entering pitches and durations
246 @ref{Pitches} and @ref{Durations}.
249 @item Time signatures and other timing commands
250 see @ref{Time signature}.
253 @node Running LilyPond
254 @section Running LilyPond
256 In the last section we explained what kind of things you could enter
257 in a LilyPond file. In this section we will explain what commands to run
258 and how to view or print the output. If you have not used LilyPond
259 before, want to test your setup, or want to run an example file
260 yourself, read this section. The instructions that follow are for
261 Unix-like systems. Some additional instructions for Microsoft Windows
262 are given at the end of this section.
264 Begin by opening a terminal window and starting a text editor. For
265 example, you could open an xterm and execute
266 @code{joe}.@footnote{There are macro files for VIM addicts, and there
267 is a @code{LilyPond-mode} for Emacs addicts. If it has not been
268 installed already, then refer to the file @file{INSTALL.txt}}. In
269 your text editor, enter the following input and save the file as
275 \notes @{ c'4 e' g' @}
280 To process @file{test.ly}, proceed as follows:
288 You will see something resembling:
293 Now processing: `/home/fred/ly/test.ly'
295 Interpreting music...[1]
296 @emph{ ... more interesting stuff ... }
297 PDF output to `test.pdf'...
298 DVI output to `test.dvi'...
302 @cindex Viewing music
305 The result is the file @file{test.pdf}.@footnote{For @TeX{}
306 afficionados: there is also a @file{test.dvi} file. It can be viewed
307 with @code{xdvi}. The DVI uses a lot of PostScript specials, which do
308 not show up in the magnifying glass. The specials also mean that the
309 DVI file cannot be processed with @code{dvilj}. Use @code{dvips} for
314 } One of the following commands should put the PDF on your
330 If the music on your screen looks good, you can print it by clicking
331 File/Print inside your viewing program.
335 @cindex Printing output
340 On Windows, the same procedure should work. The terminal is started by
341 clicking on the LilyPond or Cygwin icon. Any text editor (such as
342 Notepad, Emacs or Vim) may be used to edit the LilyPond file.
344 To view the PDF file, try the following:
347 If your system has a PDF viewer installed, open
348 @file{C:\Cygwin\home\@var{your-name}} in the explorer and double-click
351 If you prefer the keyboard, you can try to enter one of the commands
352 from the list shown before in the terminal. If none work, go to
353 @uref{http://www.cs.wisc.edu/~ghost/} to install the proper software.
356 The commands for formatting and printing music on all platforms are
357 detailed in @ref{Invoking LilyPond}.
359 @node More about pitches
360 @section More about pitches
362 A @rglos{sharp} (@texisharp{}) pitch is made by adding @samp{is} to
363 the name, a @rglos{flat} (@texiflat{}) pitch by adding @samp{es}. As
364 you might expect, a @rglos{double sharp} or @rglos{double flat} is
365 made by adding @samp{isis} or @samp{eses}:@footnote{This syntax
366 derived from note naming conventions in Nordic and Germanic languages,
367 like German and Dutch.}
374 \set Score.timing = ##f
375 \transpose c c' { cis1 ees fisis aeses s16_" " }
379 @cindex key signature, setting
381 The key signature is set with the command ``@code{\key}'', followed by
382 a pitch and @code{\major} or @code{\minor}:
392 \set Staff.TimeSignature = \turnOff
401 Key signatures together with the pitches (including alterations) are
402 used together to determine when to print accidentals. This is a
403 feature that often causes confusion to newcomers, so let us explain it
407 LilyPond makes a sharp distinction between musical content and
408 layout. The alteration (flat, natural or sharp) of a note is part of
409 the pitch, and is therefore musical content. Whether an accidental (a
410 flat, natural or sharp @emph{sign}) is a printed in front of the
411 corresponding note is a question of layout. Layout is something that
412 follows rules, so accidentals are printed automatically according to
413 those rules. The pitches in your music are works of art, so they will
414 not be added automatically, and you must enter what you want to hear.
416 For example, in this example:
418 \set Staff.TimeSignature = \turnOff
424 no note gets an explicit accidental, but still you enter
431 The code @code{d} does not mean ``print a black dot just below the
432 staff.'' Rather, it means: ``a note with pitch D-natural.'' In the key
433 of A-flat, it gets an accidental:
436 \set Staff.TimeSignature = \turnOff
447 Adding all alterations explicitly might require some more effort when
448 typing, but the advantage is that transposing is easier, and music can
449 be printed according to different conventions. See @ref{Accidentals}
450 for some examples how accidentals can be printed according to
455 A tie is created by adding a tilde ``@code{~}'' to the first note
458 @lilypond[fragment,verbatim,relative=2]
464 This example shows the key signature, accidentals and ties in action:
475 fis4 fis8 fis8 eis4 a8 gis~
483 \notes { \transpose c c' {
489 fis4 fis8 fis8 eis4 a8 gis~
492 \paper { linewidth = #(* 50 staffspace) }
498 There are some interesting points to note in this example. Bar lines
499 and beams are drawn automatically. Line breaks are calculated
500 automatically; it does not matter where the line breaks are in the
501 source file. Finally, the order in which time, key and clef changes are entered is not
502 relevant: in the printout, these are ordered according to standard
503 notation conventions.
506 @cindex beams, by hand
507 Beams are drawn automatically, but if you do not like where they are
508 put, they can be entered by hand. Mark the first note to be beamed
509 with @code{[} and the last one with @code{]}:
511 @lilypond[fragment,relative=1,verbatim]
517 For more information on
526 see @ref{Accidentals}
529 see @ref{Key signature}
537 @section Octave entry
540 @c Tim wants to move this quotes example just before the: quotes-do not-work
541 @c score, but we'd need to remove quotes from the other two (key and
544 @c better to have this just before the `octaves are bad' snipped
545 @c but we'd need to remove the ', from \key and tie
546 To raise a note by an octave, add a high quote @code{'} (apostrophe) to
547 the note name, to lower a note one octave, add a ``low quote'' @code{,}
548 (a comma). Middle C is @code{c'}:
552 c'4 c'' c''' \clef bass c c,
556 \set Score.timing = ##f
557 \set Staff.TimeSignature = \turnOff
558 c'4 c'' c''' \clef bass c c,
563 An example of the use of quotes is in the following Mozart fragment:
564 @lilypond[raggedright,fragment,verbatim]
567 cis''8. d''16 cis''8 e''4 e''8
568 b'8. cis''16 b'8 d''4 d''8
571 This example shows that music in a high register needs lots of quotes.
572 This makes the input less readable, and it is a source of errors. The
573 solution is to use ``relative octave'' mode. In practice, this is the
574 most convenient way to copy existing music. To use relative mode, add
575 @code{\relative} before the piece of music. You must also give a note
576 from which relative starts, in this case @code{c''}. If you do not
577 use octavation quotes (i.e. do not add @code{'} or @code{,} after a
578 note), relative mode chooses the note that is closest to the previous
579 one. For example, @code{c f} goes up while @code{c g} goes down:
589 \set Score.timing = ##f
590 \set Staff.TimeSignature = \turnOff
599 Since most music has small intervals, pieces can be written almost
600 without octavation quotes in relative mode. The previous example is
603 @lilypond[raggedright,fragment,verbatim]
613 @c needed better, maybe even redundant explanation
614 @c added another example below.
615 @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
616 @c in eerste instantie drong het `relative' niet door zonder extra uitleg.
617 Larger intervals are made by adding octavation quotes.
626 \set Score.timing = ##f
627 \set Staff.TimeSignature = \turnOff
635 Quotes or commas do not determine the absolute height of a note; the
636 height of a note is relative to the previous one.
637 @c do not use commas or quotes in this sentence
638 For example: @code{c f,} goes down; @code{f, f} are both the same;
639 @code{c' c} are the same; and @code{c g'} goes up:
643 Here is an example of the difference between relative mode and
644 ``normal'' (non-relative) mode:
655 \set Score.timing = ##f
656 \set Staff.TimeSignature = \turnOff
672 \set Score.timing = ##f
673 \set Staff.TimeSignature = \turnOff
681 For more information on Relative octaves see @ref{Relative octaves}
682 and @ref{Octave check}.
689 @node Combining music into compound expressions
690 @section Combining music into compound expressions
692 To print more than one staff, each piece of music that makes up a
693 staff is marked by adding @code{\context Staff} before it. These
694 @code{Staff}'s are then grouped inside @code{\simultaneous @{} and
695 @code{@}}, as is demonstrated here:
698 @lilypond[fragment,verbatim]
700 \new Staff { \clef violin c'' }
701 \new Staff { \clef bass c }
707 In this example, @code{\simultaneous } indicates that both music
708 fragments happen at the same time, and must be printed stacked
709 vertically. The notation @code{<< .. >>} can also be used as a
710 shorthand for @code{\simultaneous @{ .. @}}.
712 The command @code{\new} introduces a ``notation context''. To
713 understand this concept, imagine that you are performing a piece of
714 music. When you are playing, you combine the symbols printed at a
715 certain point with contextual information. For example, without
716 knowing the current clef, and the accidentals in the last measure, it
717 would be impossible to determine the pitch of a note. In other words,
718 this information forms a context that helps you decipher a
719 score. LilyPond produces notation from music, so in effect, it does
720 the inverse of reading scores. Therefore, it also needs to keep track
721 of contextual information. This information is maintained in
722 ``notation contexts.'' There are several types of contexts,
723 e.g. @code{Staff}, @code{Voice} and @code{Score}, but also
724 @code{Lyrics} and @code{ChordNames}. Prepending @code{\new} to a chunk
725 of music indicates what kind of context to use for interpreting it,
726 and ensures that the argument is interpreted with a fresh instance of
727 the context indicated.
732 We can now typeset a melody with two staves:
735 @lilypond[verbatim,raggedright]
755 The example shows how small chunks of music, for example, the notes
756 @code{c2}, @code{e4}, etc. of the second staff, are combined to form a
757 larger chunk by enclosing it in braces. Again, a larger chunk is
758 formed by prefix @code{\new Staff} to it, and that chunk is combined
759 with @code{<< >>}. This mechanism is similar to mathematical
760 formulas: a big formula is created by composing small formulas. Such
761 formulas are called expressions, and their definition is recursive, so
762 you can make arbitrarily complex and large expressions. For example,
771 ((1 + 2) * 3) / (4 * 5)
774 @cindex music expression
775 This example shows a sequence of expressions, where each expression is
776 contained in the next one. The simplest expressions are numbers and
777 operators (like +, * and /). Parentheses are used to group
778 expressions. In LilyPond input, a similar mechanism is used. Here,
779 the simplest expressions are notes and rests. By enclosing
780 expressions in @code{<< >>} and @code{@{ @}}, more complex music is
781 formed. The @code{\new} command also forms new expressions; prepending
782 it to a music expression yields a new expression.
784 Like mathematical expressions, music expressions can be nested
785 arbitrarily deep, e.g.
786 @lilypond[verbatim,relative=1]
788 << { e f } { c <<b d>> }
795 When spreading expressions over multiple lines, it is customary to use
796 an indent that indicates the nesting level. Formatting music like this
797 eases reading, and helps you insert the right number of closing
798 braces at the end of an expression. For example,
813 For more information on context see the Technical manual description
814 in @ref{Interpretation context}.
818 @node Adding articulation marks to notes
819 @section Adding articulation marks to notes
825 Common accents can be added to a note using a dash (`@code{-}') and a
828 @lilypond[verbatim,relative=1]
829 c-. c-- c-> c-^ c-+ c-_
835 Similarly, fingering indications can be added to a note using a dash
836 (`@code{-}') and the digit to be printed:
838 @lilypond[verbatim,relative=1]
843 Dynamic signs are made by adding the markings to the note:
845 @lilypond[verbatim,relative=1]
855 Crescendi and decrescendi are started with the commands @code{\<} and
856 @code{\>}. The command @code{\!} finishes a crescendo on the note it
859 @lilypond[verbatim,relative=1]
860 c2\< c2\!\ff\> c2 c2\!
869 A slur is drawn across many notes, and indicates bound articulation
870 (legato). The starting note and ending note are marked with a
871 ``@code{(}'' and a ``@code{)}'' respectively:
874 @lilypond[fragment,relative=1,verbatim]
875 d4( c16)( cis d e c cis d e)( d4)
879 @cindex slurs versus ties
880 A slur looks like a tie, but it has a different meaning. A tie simply
881 makes the first note sound longer, and can only be used on pairs of
882 notes with the same pitch. Slurs indicate the articulations of notes,
883 and can be used on larger groups of notes. Slurs and ties are also
886 @lilypond[fragment,relative=1]
887 c2~( c8 fis fis4 ~ fis2 g2)
890 @cindex phrasing slurs
891 If you need two slurs at the same time (one for articulation, one for
892 phrasing), you can also make a phrasing slur with @code{\(} and
896 @lilypond[fragment,relative=1,verbatim]
897 a8(\( ais b c) cis2 b'2 a4 cis, c\)
902 For more information on
905 see @ref{Fingering instructions}
907 see @ref{Articulations}
911 see @ref{Phrasing slurs}
917 @node Combining notes into chords
918 @section Combining notes into chords
921 Chords can be made by
922 surrounding pitches with @code{<} and @code{>}:
924 @lilypond[relative,fragment,verbatim]
931 You can combine beams and ties with chords. Beam and tie markings
932 must be placed outside the chord markers:
934 @lilypond[relative,fragment,verbatim]
935 r4 <c e g>8[ <c f a>]~ <c f a>
941 r4 <c e g>8\>( <c e g> <c e g> <c f a>8\!)
943 @lilypond[relative,fragment]
945 r4 <c e g>8\>( <c e g> <c e g> <c f a>8\!)
953 @node Basic rhythmical commands
954 @section Basic rhythmical commands
959 @cindex partial measure
960 A pickup (or upstep) is entered with the keyword @code{\partial}. It
961 is followed by a duration: @code{\partial 4} is a quarter note upstep
962 and @code{\partial 8} an eighth note:
963 @lilypond[relative=1,verbatim,fragment]
970 Tuplets are made with the @code{\times} keyword. It takes two
971 arguments: a fraction and a piece of music. The duration of the piece
972 of music is multiplied by the fraction. Triplets make notes occupy
973 2/3 of their notated duration, so a triplet has 2/3 as its fraction:
975 @lilypond[relative,verbatim,fragment]
976 \times 2/3 { f8 g a }
982 Grace notes are also made by prefixing a note, or a set of notes with
983 a keyword. In this case, the keywords are @code{\appoggiatura}
984 and @code{\acciaccatura}
988 @lilypond[relative=1,verbatim,fragment]
989 c4 \appoggiatura b16 c4
990 c4 \acciaccatura b16 c4
995 For more information on
998 see @ref{Grace notes},
1002 see @ref{Partial measures}.
1007 @node Commenting input files
1008 @section Commenting input files
1011 @cindex line comment
1012 @cindex block comment
1013 Comments are pieces of the input that are ignored. There are two
1014 types of comments. A line comment is introduced by @code{%}: after
1015 that, the rest of that line is ignored. Block comments span larger
1016 sections of input. Anything that is enclosed in @code{%@{} and
1017 @code{%@}} is ignored too. The following fragment shows possible uses
1021 % notes for twinkle twinkle follow:
1026 This line, and the notes below
1027 are ignored, since they are in a
1037 @node Printing lyrics
1038 @section Printing lyrics
1043 Lyrics are entered by separating each syllable with a space, and
1044 surrounding them with @code{\lyrics @{ @dots{} @}}, for example,
1046 \lyrics @{ I want to break free @}
1049 Like notes, lyrics are also a form of music, but they must not be
1050 printed on a staff, which is the default way to print music. To print
1051 them as lyrics, they must be marked with @code{ \new Lyrics}:
1053 \new Lyrics \lyrics @{ I want to break free @}
1055 The melody for this song is as follows:
1057 @lilypond[fragment,relative=1]
1060 \times 2/3 { f4 g g } \times 2/3 { g4( a2) }
1063 The lyrics can be set to these notes, combining both with the
1064 @code{\lyricsto} keyword:
1066 \lyricsto "@var{name}" \new Lyrics @dots{}
1068 where @var{name} identifies to which melody the lyrics should be
1069 aligned. In this case, there is only one melody, so we can leave it
1073 @lilypond[verbatim,fragment]
1076 \relative c' \new Voice {
1079 \times 2/3 { f g g } \times 2/3 { g4( a2) }
1081 \lyricsto "" \new Lyrics \lyrics { I want to break free }
1087 @cindex extender line
1089 This melody ends on a @rglos{melisma}, a single syllable (``free'')
1090 sung to more than one note. This is indicated with an @emph{extender
1091 line}. It is entered as two underscores, i.e.
1093 \lyrics @{ I want to break free __ @}
1095 @lilypond[raggedright]
1098 \relative c' \new Voice {
1101 \times 2/3 { f g g } \times 2/3 { g4( a2) } }
1102 \lyricsto "" \new Lyrics \lyrics { I want to break free __ }
1107 Similarly, hyphens between words can be entered as two dashes,
1108 resulting in a centered hyphen between two syllables:
1110 Twin -- kle twin -- kle
1112 @lilypond[raggedright]
1114 << \notes \relative f' { \time 2/4
1116 \new Lyrics \lyrics { Twin -- kle twin -- kle }
1118 \paper { raggedright = ##t }
1122 More options, like putting multiple lines of lyrics below a melody are
1123 discussed in @ref{Vocal music}.
1128 @section A lead sheet
1134 In popular music, it is common to denote accompaniment as chord-names.
1135 Using them in LilyPond has two parts, just like lyrics: entering the
1136 chords (with @code{\chords}), and printing them (with @code{\new
1139 Chord names are entered by starting chords mode (with @code{\chords}).
1140 In chords mode, you can enter chords with a letter (indicating the
1141 root of the chord), and a durations following that:
1144 \chords { c2 f4. g8 }
1148 The result of @code{\chords} is a list of chords, and is equivalent
1149 to entering chords with @code{<@dots{}>}.
1151 Other chords can be created by adding modifiers after a colon. The
1152 following example shows a few common modifiers:
1155 \chords { c2 f4:m g4:maj7 gis1:dim7 }
1158 Printing chords is done by adding @code{\context ChordNames}
1159 before the chords thus entered:
1162 \context ChordNames \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
1167 When put together, chord names, lyrics and a melody form
1168 a lead sheet, for example,
1173 \context ChordNames \chords @{ @emph{chords} @}
1174 \notes @emph{the melody}
1175 \lyricsto "" \new Lyrics \lyrics @{ @emph{the text} @}
1182 \context ChordNames \chords { r8 c2:sus4 f }
1183 \notes \relative c' {
1186 \times 2/3 { f g g } \times 2/3 { g4( a2) } }
1187 \new Lyrics \lyricsto "" \lyrics { I want to break free __ }
1189 \paper{ raggedright = ##t }
1194 A complete list of modifiers and other options for layout are in the
1195 reference manual section @ref{Chords}.
1197 @node Listening to output
1198 @section Listening to output
1203 MIDI (Musical Instrument Digital Interface) is a standard for
1204 connecting and recording digital instruments. A MIDI file is like a
1205 tape recording of a MIDI instrument. The @code{\midi} block causes LilyPond
1206 to create a MIDI file, so you can listen to the music you entered.
1207 It is great for checking the music: octaves that are off or
1208 accidentals that were mistyped stand out very much when listening to
1209 the musical transcription.
1211 The @code{\midi} block is added to @code{\score}, for example,
1215 \midi @{ \tempo 4=72 @}
1219 Here, the tempo is specified using the @code{\tempo} command. In this
1220 case the tempo of quarter notes is set to 72 beats per minute. More
1221 information on auditory output is in the @ref{Sound} section in the
1224 If there is a @code{\midi} command in a @code{\score}, then only MIDI
1225 will be produced. If notation is needed too, then a @code{\paper}
1226 block must be added too:
1231 \midi @{ \tempo 4=72 @}
1241 Bibliographic information is entered in a separate block, the
1242 @code{\header} block. The name of the piece, its composer, etc. are
1243 entered as an assignment, within @code{\header @{ @dots{} @}}. For
1247 title = "Eight miniatures"
1248 composer = "Igor Stravinsky"
1249 tagline = "small is beautiful"
1252 \score @{ @dots{} @}
1255 @cindex bibliographic information
1258 @cindex Engraved by LilyPond
1260 When the file is processed by the @code{lilypond} wrapper script
1261 the title and composer specified are printed above the music. The
1262 `tagline' is a short line printed at bottom of the last page which
1263 normally says ``Engraved by LilyPond, version @dots{}''. In the
1264 example above it is replaced by the line ``small is
1265 beautiful.''@footnote{Nicely printed parts are good PR for us, so do
1266 us a favor, and leave the tagline if you can.}
1268 Normally, the @code{\header} is put at the top of the file. However,
1269 for a document that contains multiple pieces (e.g. an etude book, or
1270 an orchestral part with multiple movements), the header can be
1271 put in the @code{\score} block as follows; in this case, the name of
1272 each piece will be printed before each movement:
1275 @cindex Engraved by LilyPond
1276 @cindex signature line
1281 title = "Eight miniatures"
1282 composer = "Igor Stravinsky"
1283 tagline = "small is beautiful"
1287 \header @{ piece = "Adagio" @}
1290 \header @{ piece = "Menuetto" @}
1294 More information on titling can be found in @ref{Invoking lilypond}.
1297 @node Single staff polyphony
1298 @section Single staff polyphony
1301 @cindex multiple voices
1302 @cindex voices, more -- on a staff
1304 When different melodic lines are combined on a single staff they are
1305 printed as polyphonic voices: each voice has its own stems, slurs and
1306 beams, and the top voice has the stems up, while the bottom voice has
1309 Entering such parts is done by entering each voice as a sequence (with
1310 @code{@{ .. @}}), and combining those simultaneously, separating the
1311 voices with @code{\\}:
1314 << @{ a4 g2 f4~ f4 @} \\
1315 @{ r4 g4 f2 f4 @} >>
1317 @lilypond[relative=1]
1318 \context Staff << { a4 g2 f4~ f4 } \\
1322 For polyphonic music typesetting, spacer rests can also be convenient: these
1323 are rests that do not print. It is useful for filling up voices that
1324 temporarily do not play:
1326 << @{ a4 g2 f4~ f4 @} \\
1327 @{ s4 g4 f2 f4 @} >>
1329 @lilypond[relative=1]
1330 \context Staff << { a4 g2 f4~ f4 } \\
1334 Again, these expressions can be nested arbitrarily:
1340 << { a4 g2 f4~ f4 } \\
1343 << { \clef bass <c g>1 ~ <c g>4 } \\
1350 More features of polyphonic typesetting are in the notation manual
1354 @section Piano staves
1356 @cindex staff switch, manual
1357 @cindex cross staff voice, manual
1358 @cindex @code{\translator}
1360 Piano music is always typeset in two staves connected by a brace.
1361 Printing such a staff is similar to the polyphonic example in
1362 @ref{Combining music into compound expressions}:
1364 << \new Staff @{ @dots{} @}
1365 \new Staff @{ @dots{} @}
1368 but now this entire expression must be interpreted as a
1371 \new PianoStaff << \new Staff @dots{} >>
1374 Here is a full-fledged example:
1376 @lilypond[relative,fragment]
1378 << \new Staff { \time 2/4
1381 \clef bass c,, c' e c }
1385 More information on formatting piano music is in @ref{Piano music}.
1387 @node Setting variables
1388 @section Setting variables
1390 When the music is converted from notes to print it is interpreted
1391 in left-to-right order. This is similar to what happens when we read
1392 music. During this step context-sensitive information such as the
1393 accidentals to print, and where bar lines must be placed, are stored in
1394 variables. These variables are called @emph{context properties}.
1395 The properties can also be manipulated from input files. Consider this input:
1397 \set Staff.autoBeaming = ##f
1401 It sets the property named @code{autoBeaming} in the current staff at
1402 this point in the music to @code{##f}, which means `false'. This
1403 property controls whether beams are printed automatically:
1405 @lilypond[relative=1,fragment,verbatim]
1407 \set Staff.autoBeaming = ##f
1412 LilyPond includes a built-in programming language, namely, a dialect
1413 of Scheme. The argument to @code{\set}, @code{##f}, is an
1414 expression in that language. The first hash-mark signals that a piece
1415 of Scheme code follows. The second hash character is part of the
1416 boolean value true (@code{#t}). Values of other types may be
1419 @item a string, enclosed in double quotes, for example,
1421 \set Staff.instrument = #"French Horn"
1423 @item a boolean: either @code{#t} or @code{#f}, for true and false
1426 \set autoBeaming = ##f
1427 \set Score.skipBars = ##t
1430 @item a number, such as
1432 \set Score.currentBarNumber = #20
1435 @item a symbol, which is introduced by a quote character, as in
1437 \set Staff.crescendoSpanner = #'dashed-line
1440 @item a pair, which is also introduced by a quote character, like in
1441 the following statements, which set properties to the pairs (-7.5, 6)
1442 and (3, 4) respectively:
1445 \set Staff.minimumVerticalExtent = #'(-7.5 . 6)
1446 \set Staff.timeSignatureFraction = #'(3 . 4)
1449 @item a list, which is also introduced by a quote character. In the
1450 following example, the @code{breakAlignOrder} property is set to a
1453 \set Score.breakAlignOrder =
1454 #'(left-edge time-signature key-signatures)
1460 There are many different properties. Not all of them are listed in
1461 this manual. However, the program reference lists them all in the
1462 section @internalsref{Context-properties}, and most properties are
1463 demonstrated in one of the
1465 @uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
1473 @node Fine tuning layout
1474 @section Fine tuning layout
1476 Sometimes it is necessary to change music layout by hand. When music
1477 is formatted, layout objects are created for each symbol. For
1478 example, every clef and every note head is represented by a layout
1479 object. These layout objects also carry variables, which we call
1480 @emph{layout properties}. By changing these variables from their
1481 values, we can alter the look of a formatted score:
1483 @lilypond[verbatim,relative]
1485 \override Stem #'thickness = #3.0
1490 In the example shown here, the layout property @code{thickness} (a
1491 symbol) is set to 3 in the @code{Stem} layout objects of the current
1492 As a result, the notes following @code{\override} have thicker
1495 For the most part, a manual override is needed only on a case by
1496 case basis and not for all subsequent instances of the altered
1497 property. To accomplish this, simply prefix @code{\once} to the
1498 @code{\override} statement and the override will apply only once,
1499 immediately reverting to its default setting, i.e.
1502 \once \override Stem #'thickness = #3.0
1507 \once \override Stem #'thickness = #3.0
1512 Some overrides are so common that predefined commands are provided as
1513 a short cut. For example, @code{\slurUp} and @code{\stemDown}. These
1514 commands are described in
1518 @ref{Notation manual}, under the sections for slurs and stems
1521 The exact tuning possibilities for each type of layout object are
1522 documented in the program reference of the respective
1523 object. However, many layout objects share properties, which can be
1524 used to apply generic tweaks. We mention a couple of these:
1527 @item The @code{extra-offset} property, which
1528 @cindex @code{extra-offset}
1529 has a pair of numbers as value, moves around objects in the printout.
1530 The first number controls left-right movement; a positive number will
1531 move the object to the right. The second number controls up-down
1532 movement; a positive number will move it higher. The units of these
1533 offsets are staff-spaces. The @code{extra-offset} property is a
1534 low-level feature: the formatting engine is completely oblivious to
1537 In the following example, the second fingering is moved a little to
1538 the left, and 1.8 staff space downwards:
1540 @cindex setting object properties
1542 @lilypond[relative=1,verbatim]
1545 \once \override Fingering
1546 #'extra-offset = #'(-0.3 . -1.8)
1551 Setting the @code{transparent} property will cause an object to be printed
1552 in `invisible ink': the object is not printed, but all its other
1553 behavior is retained. The object still takes up space, it takes part in
1554 collisions, and slurs, and ties and beams can be attached to it.
1556 @cindex transparent objects
1557 @cindex removing objects
1558 @cindex invisible objects
1559 The following example demonstrates how to connect different voices
1560 using ties. Normally, ties only connect two notes in the same
1561 voice. By introducing a tie in a different voice, and blanking a stem
1562 in that voice, the tie appears to cross voices:
1564 @lilypond[fragment,relative=1,verbatim]
1566 \once \override Stem #'transparent = ##t
1574 The @code{padding} property for objects with
1575 @cindex @code{padding}
1576 @code{side-position-interface} can be set to increase distance between
1577 symbols that are printed above or below notes. We only give an
1578 example; a more elaborate explanation is in @ref{Constructing a
1581 @lilypond[relative=1,verbatim]
1583 \override Script #'padding = #3
1589 More specific overrides are also possible. The notation manual
1590 discusses in depth how to figure out these statements for yourself, in
1591 @ref{Tuning output}.
1593 @node Organizing larger pieces
1594 @section Organizing larger pieces
1596 When all of the elements discussed earlier are combined to produce
1597 larger files, the @code{\score} blocks get a lot bigger, because the
1598 music expressions are longer, and, in the case of polyphonic and/or
1599 orchestral pieces, more deeply nested. Such large expressions can
1602 By using variables, also known as identifiers, it is possible to break
1603 up complex music expressions. An identifier is assigned as follows:
1606 namedMusic = \notes @{ @dots{}
1609 The contents of the music expression @code{namedMusic}, can be used
1610 later by preceding the name with a backslash, i.e. @code{\namedMusic}.
1611 In the next example, a two note motive is repeated two times by using
1612 variable substitution:
1614 @lilypond[raggedright,verbatim]
1623 The name of an identifier should have alphabetic characters only;
1624 no numbers, underscores or dashes. The assignment should be outside of
1625 the @code{\score} block.
1627 It is possible to use variables for many other types of objects in the
1632 aFivePaper = \paper @{ paperheight = 21.0 \cm @}
1634 Depending on its contents, the identifier can be used in different
1635 places. The following example uses the above variables:
1638 \notes @{ c4^\name @}
1646 More information on the possible uses of identifiers is in the
1647 technical manual, in @ref{Scheme data types}.
1650 @node An orchestral part
1651 @section An orchestral part
1653 In orchestral music, all notes are printed twice: both in a part for
1654 the musicians, and in a full score for the conductor. Identifiers can
1655 be used to avoid double work: the music is entered once, and stored in
1656 a variable. The contents of that variable is then used to generate
1657 both the part and the score.
1659 It is convenient to define the notes in a special file, for example,
1660 suppose that the @file{horn-music.ly} contains the following part of a
1663 hornNotes = \notes \relative c @{
1669 Then, an individual part is made by putting the following in a file:
1671 \include "horn-music.lyinc"
1673 instrument = "Horn in F"
1676 \notes \transpose f c' \hornNotes
1679 The @code{\include} command substitutes the contents of the file at
1680 this position in the file, so that @code{hornNotes} is defined
1681 afterwards. The code @code{\transpose f c'} indicates that the
1682 argument, being @code{\hornNotes}, should be transposed by a fifth
1683 downwards: sounding @code{f} is denoted by notated @code{c'}, which
1684 corresponds with tuning of a normal French Horn in F. The
1685 transposition can be seen in the following output:
1687 @lilypond[raggedright]
1689 \notes \transpose f c' \notes \relative c {
1696 In ensemble pieces, one of the voices often does not play for many
1697 measures. This is denoted by a special rest, the multi-measure
1698 rest. It is entered with a capital R followed by a duration (1
1699 for a whole note, 2 for a half note, etc.) By multiplying the
1700 duration, longer rests can be constructed. For example, this rest
1701 takes 3 measures in 2/4 time:
1706 When printing the part, the following @code{skipBars} property must be
1707 set to true, to prevent the rest from being expanded to three one bar
1710 \set Score.skipBars = ##t
1712 Prepending the rest and the property setting above, leads to the
1715 @lilypond[raggedright]
1716 \score {\notes { \transpose f c' \relative c { \time 2/4
1717 \set Score.skipBars = ##t
1719 r4 f8 a cis4 f e d } }}
1722 The score is made by combining all of the music in a @code{\score}
1723 block, assuming that the other voice is in @code{bassoonNotes}, in the
1724 file @file{bassoon-music.ly}:
1726 \include "bassoon-music.lyinc"
1727 \include "horn-music.lyinc"
1731 \new Staff \hornNotes
1732 \new Staff \bassoonNotes
1736 This would lead to the simple score depicted below:
1738 @lilypond[raggedright]
1740 \notes \relative c \simultaneous {
1741 \new Staff { \time 2/4
1743 r4 f8 a cis4 f e d }
1744 \new Staff { \clef bass
1745 r4 d,8 f | gis4 c | b bes |
1746 a8 e f4 | g d | gis f }
1750 More in-depth information on preparing parts and scores is in the
1751 notation manual, in @ref{Orchestral music}.
1754 @node Integrating text and music
1755 @section Integrating text and music
1757 @cindex La@TeX{}, music in
1758 @cindex HTML, music in
1759 @cindex Texinfo, music in
1761 Sometimes you might want to use music examples in a text that you are
1762 writing (for example, a musicological treatise, a songbook, or (like us)
1763 the LilyPond manual). You can make such texts by hand, simply by
1764 importing a PostScript figure into your word processor. However,
1765 there is an automated procedure to reduce the amount of work.
1767 If you use HTML, La@TeX{}, or Texinfo, you can mix text and LilyPond
1768 code. A script called @code{lilypond-book} will extract the music
1769 fragments, run LilyPond on them, and put back the resulting notation.
1770 This program is fully described in @ref{lilypond-book manual}. Here
1771 we show a small example. The example also contains explanatory text,
1772 so we will not comment on it further:
1775 \documentclass[a4paper]@{article@}
1778 In a lilypond-book document, you can freely mix music and text. For
1781 \score @{ \notes \relative c' @{
1782 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
1786 If you have no \verb+\score+ block in the fragment,
1787 \texttt@{lilypond-book@} will supply one:
1793 In the example you see here two things happened: a
1794 \verb+\score+ block was added, and the line width was set to natural
1795 length. You can specify options by putting them in brackets:
1797 \begin[staffsize=26,verbatim]@{lilypond@}
1801 If you want to include large examples in the text it is more
1802 convenient to put it in a separate file:
1804 \lilypondfile@{screech-boink.ly@}
1809 Under Unix, you can view the results as follows:
1813 $ lilypond-book --output=out/ lilybook.tex
1814 lilypond-book (GNU LilyPond) 2.1.19
1815 Reading `input/tutorial/lilybook.tex'
1816 Reading `input/screech-boink.ly'
1817 @var{lots of stuff deleted}
1818 Writing `out/lilybook.latex'
1820 $ latex lilybook.latex
1821 @var{lots of stuff deleted}
1825 To convert the file into a nice PDF document, run the following
1828 $ dvips -Ppdf -u +lilypond lilybook
1829 $ ps2pdf lilybook.ps
1833 Running lilypond-book and running latex creates a lot of temporary
1834 files. You would not want those to clutter up your working
1835 directory. The @code{outdir} option to lilypond-book creates the
1836 temporary files in a separate subdirectory @file{out}.
1838 The result looks more or less like this:
1842 In a lilypond-book document, you can freely mix music and text. For
1846 \notes \relative c' {
1847 c2 g'2 \times 2/3 { f8 e d } c'2 g4
1855 If you have no @code{\score} block in the fragment,
1856 @code{lilypond-book} will supply one:
1862 In the example you see here, two things happened: a
1863 @code{score} block was added, and the line width was set to natural
1864 length. You can specify options by putting them in brackets:
1866 @lilypond[staffsize=26,verbatim]
1870 If you want to include large examples in the text, it is more
1871 convenient to put it in a separate file:
1873 @lilypondfile{screech-boink.ly}