4 @c * more details about running lilypond; error messages,
5 @c compiling/viewing (emacs?)
6 @c * where to go from First steps+More basics?
13 Using LilyPond comes down to encoding music in an input file. After
14 entering the music, the program is run on the file producing output
15 which can be viewed or printed. In this tutorial, we will show step
16 by step how to enter such files, by showing fragments of input and the
17 corresponding output. At the end of every section, a paragraph will
18 list where to find further information on the topics discussed.
20 Many people learn programs by trying and fiddling around with the
21 program. This is also possible with LilyPond. If you click on a
22 picture in the HTML version of this manual, you will see the exact
23 LilyPond input that was used to generate that image.
25 For example, consider the following input:
26 @c TODO: intertext fixme
27 @lilypond[relative 1,singleline,verbatim,intertext="with the following output:"]
28 c'^\markup { \bold \huge { Click on this image! } }
32 By cutting and pasting the full input into a test file, you have a
33 starting template for experiments. If you like learning in this way,
34 you will probably want to print out or bookmark
38 @ref{Cheat sheet}, which is a table listing all commands for quick
42 This tutorial starts with a short introduction to the LilyPond music
43 language. After this first contact, we will show you how to to
44 produce printed output. You should then be able to create and print
45 your first sheets of music.
50 * More about pitches and accidentals::
52 * Combining music into compound expressions::
53 * Adding articulation marks to notes::
54 * Combining notes into chords::
57 * Listening to output::
59 * Single staff polyphony::
62 * Fine tuning layout::
63 * Organizing larger pieces::
64 * An orchestral part::
65 * Integrating text and music::
72 We start off by showing how very simple music is entered in LilyPond:
73 you get a note simply by typing its note name, from @samp{a}
74 through @samp{g}. So if you enter
81 then the result looks like this:
84 @c \transpose c c' { c d e f g a b }
86 @c \property Score.timing = ##f
87 @lilypond[notime, relative=2]
91 The length of a note is specified by adding a number, @samp{1} for a
92 @rglos{whole note}, @samp{2} for a @rglos{half note}, and so on:
99 \property Score.timing = ##f
100 \property Staff.autoBeaming = ##f
101 \transpose c c' { a1 a2 a4 a16 a32 s16_" " }
104 If you do not specify a @rglos{duration}, the previous one is used:
111 \property Score.timing = ##f
112 \transpose c c' { a a a2 a s16_" " }
116 Rests are entered just like notes, but with the name ``@code{r}'':
125 \property Score.timing = ##f
126 \property Staff.Clef = \turnOff
127 \property Staff.TimeSignature = \turnOff
135 Add a dot @samp{.} after the duration to get a @rglos{dotted note}:
142 \property Score.timing = ##f
143 \transpose c c' { a2. a4 a8. a16 s16_" " }
147 The @rglos{meter} (or @rglos{time signature}) can be set with the
148 @code{\time} command:
156 @c a clef here may lead to confusion
158 \property Staff.Clef \set #'transparent = ##t
168 The @rglos{clef} can be set using the @code{\clef} command:
170 @c what is more common name treble or violin?
171 @c in Dutch, its violin.
172 @c in English its definitely treble.
181 \property Score.timing = ##f
192 Notes and commands like @code{\clef} and @code{\time} , are enclosed
193 in @code{\notes @{@dots{}@}}. This indicates that music (as opposed
194 to @rglos{lyrics}) follows:
204 Now the piece of music is almost ready to be printed. The final step is to
205 combine the music with a printing command.
207 The printing command is the so-called @code{\paper} block. The
208 @code{\paper} block is used to customize printing specifics, but we
209 accept the defaults for now. The music and the @code{\paper} block
210 are combined by enclosing them in @code{\score @{ ... @}}. The
211 following is a complete and valid input file.
234 linewidth = 55 * \staffspace
239 During the rest of the tutorial, we will often leave out @code{\score}
240 and @code{\paper}, for clarity. However, both must be present when
241 feeding the file to LilyPond.
243 More elaborate information on entering pitches and durations is in
244 @ref{Pitches} and @ref{Durations}. Clefs are fully explained in
245 @ref{Clef}. Time signatures and other timing commands are described
246 in @ref{Time signature}.
249 @node Running LilyPond
250 @section Running LilyPond
252 In the last section we explained what kind of things you could enter
253 in a LilyPond file. In this section we explain what commands to run
254 and how to view or print the output. If you have not used LilyPond
255 before, want to test your setup, or want to run an example file
256 yourself, read this section. The instructions that follow are for
257 Unix-like systems. Some additional instructions for Microsoft Windows
258 are given at the end of this section.
260 Begin by opening a terminal window and starting a text editor. For
261 example, you could open an xterm and execute
262 @code{joe}.@footnote{There are macro files for VIM addicts, and there
263 is a @code{LilyPond-mode} for Emacs addicts. If it has not been
264 installed already, then refer to the file @file{INSTALL.txt}}. In
265 your text editor, enter the following input and save the file as
271 \notes @{ c'4 e' g' @}
276 To process @file{test.ly}, proceed as follows:
284 You will see something resembling:
289 Now processing: `/home/fred/ly/test.ly'
291 Interpreting music...[1]
292 @emph{ ... more interesting stuff ... }
293 PDF output to `test.pdf'...
294 DVI output to `test.dvi'...
298 @cindex Viewing music
301 The result is the file @file{test.pdf}.@footnote{For @TeX{}
302 afficionados, there is also a @file{test.dvi} file. It can be viewed
303 with @code{xdvi}. The DVI uses a lot of PostScript specials, which do
304 not show up in the magnifying glass. The specials also mean that the
305 DVI file cannot be processed with @code{dvilj}. Use @code{dvips} for
310 } One of the following commands should put the PDF on your
324 If the music on your screen looks good, you can print it by clicking
325 File/Print inside your viewing program.
329 @cindex Printing output
334 On Windows, the same procedure should work, the terminal is started by
335 clicking on the LilyPond or Cygwin icon. Any text editor (such as
336 NotePad, Emacs or Vim) may be used to edit the LilyPond file.
338 To view the PDF file, try the following:
341 If your system has a PDF viewer installed, open
342 @file{C:\Cygwin\home\@var{your-name}} in the explorer and double-click
345 If you prefer the keyboard, you can also try the list of commands
346 shown before. If none work, go to
347 @uref{http://www.cs.wisc.edu/~ghost/} to install the proper software.
350 The commands for formatting and printing music on all platforms are
351 detailed in @ref{Invoking LilyPond}.
353 @node More about pitches and accidentals
354 @section More about pitches and accidentals
356 A @rglos{sharp} (@texisharp{}) is made by adding @samp{is}, a
357 @rglos{flat} (@texiflat{}) by adding @samp{es}. As you might expect,
358 a @rglos{double sharp} or @rglos{double flat} is made by adding
359 @samp{isis} or @samp{eses}:@footnote{This syntax derived from note
360 naming conventions in Nordic and Germanic languages, like German and
368 \property Score.timing = ##f
369 \transpose c c' { cis1 ees fisis aeses s16_" " }
373 @cindex key signature, setting
375 The key signature is set with the command ``@code{\key}'', followed by
376 a pitch and @code{\major} or @code{\minor}:
386 \property Staff.TimeSignature = \turnOff
394 WARNING! The key signature only affects the way the output is printed,
395 not the music itself. If you type
404 LilyPond will print an F-natural. An F-sharp in the key of D major
405 is still an F-sharp! To print an F-sharp, you must use @code{fis},
406 no matter what the key signature is. See this example:
417 \score{ \notes { \relative c'{
426 A tie is created by adding a tilde ``@code{~}'' to the first note
429 @lilypond[fragment,verbatim,relative 2]
435 This example shows the key signature, accidentals and ties in action:
446 fis4 fis8 fis8 eis4 a8 gis-~
455 \notes { \transpose c c' {
461 fis4 fis8 fis8 eis4 a8 gis-~
464 \paper { linewidth = #(* 50 staffspace) }
470 There are some interesting points to note in this example. Bar lines
471 and beams are drawn automatically. Line breaks are calculated
472 automatically; it does not matter where the lines breaks are in the
473 source file. Finally, the order of time, key and clef changes is not
474 relevant: in the printout, these are ordered according to standard
475 notation conventions.
477 Accidentals (sharps and flats) do not have to be marked explicitly:
478 you just enter the pitch of the note, and an accidental is printed
479 only when necessary. The flip side of this mechanism, is that you have
480 to mark notes as sharp or flat, even when they do not get accidentals.
481 For example, in this example:
484 \property Staff.TimeSignature = #'()
486 cis dis eis fis gis ais bis
488 no note gets an explicit accidental, but still you enter
492 cis dis eis fis gis ais bis
495 Adding all alterations explicitly might require some more effort when
496 typing, but the advantage is that transposing is easier. It also makes
497 it possible to use different conventions for when to print
500 @cindex beams, by hand
501 Beams are drawn automatically, but if you do not like where they are
502 put, they can be entered by hand. Mark the first note to be beamed
503 with @code{[} and the last one with @code{]}:
505 @lilypond[fragment,relative 1, verbatim]
511 Rests are described in full detail in @ref{Rests}.
513 The notation manual discusses ties in @ref{Ties}.
517 @section Octave entry
520 @c Tim wants to move this quotes example just before the: quotes-do not-work
521 @c score, but we'd need to remove quotes from the other two (key and
524 @c better to have this just before the `octaves are bad' snipped
525 @c but we'd need to remove the ', from \key and tie
526 To raise a note by an octave, add a high quote @code{'} (apostrophe) to
527 the note name, to lower a note one octave, add a ``low quote'' @code{,}
528 (a comma). Middle C is @code{c'}:
532 c'4 c'' c''' \clef bass c c,
536 \property Score.timing = ##f
537 \property Staff.TimeSignature = \turnOff
538 c'4 c'' c''' \clef bass c c,
543 An example of the use of quotes is in the following Mozart fragment:
544 @lilypond[singleline,fragment,verbatim]
547 cis''8. d''16 cis''8 e''4 e''8
548 b'8. cis''16 b'8 d''4 d''8
551 This example shows that music in a high register needs lots of quotes.
552 This makes the input less readable, and it is a source of errors. The
553 solution is to use ``relative octave'' mode. In practice, this is the
554 most convenient way to copy existing music. To use relative mode, add
555 @code{\relative} before the piece of music. You must also give a note
556 from which relative starts, in this case @code{c''}. If you do not
557 use octavation quotes (i.e. do not add ' or , after a note), relative
558 mode chooses the note that is closest to the previous one.
559 For example, @code{c f} goes up while @code{c g} goes down:
569 \property Score.timing = ##f
570 \property Staff.TimeSignature = \turnOff
579 Since most music has small intervals, in relative mode pieces can be
580 written almost without using octavation quotes. In relative mode, the
581 Mozart example is entered as
583 @lilypond[singleline,fragment,verbatim]
593 @c needed better, maybe even redundant explanation
594 @c added another example below.
595 @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
596 @c in eerste instantie drong het `relative' niet door zonder extra uitleg.
597 Larger intervals are made by adding octavation quotes. Quotes or
598 commas do not determine the absolute height of a note; the height of a
599 note is relative to the previous one.
600 @c do not use commas or quotes in this sentence
601 For example: @code{c f,} goes down; @code{f, f} are both the same;
602 @code{c' c} are the same; and @code{c g'} goes up:
612 \property Score.timing = ##f
613 \property Staff.TimeSignature = \turnOff
622 Here is an example of the difference between relative mode and
623 ``normal'' (non-relative) mode:
634 \property Score.timing = ##f
635 \property Staff.TimeSignature = \turnOff
651 \property Score.timing = ##f
652 \property Staff.TimeSignature = \turnOff
667 @node Combining music into compound expressions
668 @section Combining music into compound expressions
670 To print more than one staff, each piece of music that makes up a
671 staff is marked by adding @code{\context Staff} before it. These
672 @code{Staff}'s are then grouped inside @code{\simultaneous @{} and
673 @code{@}}, as is demonstrated here:
676 @lilypond[fragment,verbatim]
678 \new Staff { \clef violin c'' }
679 \new Staff { \clef bass c }
685 In this example, @code{\simultaneous } indicates that both music
686 fragments happen at the same time, and must be printed stacked
687 vertically. The notation @code{<< .. >>} can also be used as a
688 shorthand for @code{\simultaneous @{ .. @}}.
690 @code{\context} introduces a ``notation context''. To understand this
691 concept, imagine that you are performing a piece of music. When you
692 perform the music, you combine the symbols printed at a certain point
693 with contextual information. For example, without knowing the current
694 clef, and the accidentals in the last measure, it would be impossible
695 to determine the pitch of a note. In other words, this information
696 forms context that helps you decipher a score. LilyPond produces
697 notation from music, so in effect, it does the inverse of reading
698 scores. Therefore, it also needs to keep track of contextual
699 information. This information is maintained in ``notation contexts.''
700 There are several types of contexts, e.g. @code{Staff}, @code{Voice}
701 and @code{Score}, but also @code{Lyrics} and
702 @code{ChordNames}. Prepending @code{\context} to a chunk of music
703 indicates what kind of context to use for interpreting it.
705 By specifying different names (in this case @code{staffA} and
706 @code{staffB}), two different contexts are created, leading to two
707 staves. It does not matter which names they are given, as long as they
708 are different. If they get the same name, the chunks of music are
709 assumed to belong on the same staff, and will be printed like that.
713 We can now typeset a melody with two staves:
716 @lilypond[verbatim,singleline]
737 The example shows how small chunks of music, for example, the notes
738 @code{c2}, @code{e4}, etc. of the second staff, are combined to form a
739 larger chunk by enclosing it in braces. Again, a larger chunk is
740 formed by prefix @code{\context Staff} to it, and that chunk is
741 combined with @code{<< >>}. This mechanism is similar with mathematical
742 formulas: in a formula, a so-called expression is formed by combining
743 simpler expressions into larger expressions. For example,
752 ((1 + 2) * 3) / (4 * 5)
755 @cindex music expression
756 is a sequence of expressions, where each expression is contained in
757 the next one. The simplest expressions are numbers and operators
758 (like +, * and /). Parentheses are used to group expressions. In
759 LilyPond input, a similar mechanism is used. Here, the simplest
760 expressions are notes and rests. By enclosing expressions in @code{<<
761 >>} and @code{@{ @}}, more complex music is formed. The @code{\context}
762 also forms new expressions; prepending it to a music expression yields
765 Like mathematical expressions, music expressions can be nested
766 arbitrarily deep, e.g.
767 @lilypond[verbatim,relative 1]
769 << { e f } { c <<b d>> }
776 When spreading expressions over multiple lines, it is customary to use
777 an indent that indicates the nesting level. Formatting music like this
778 eases reading, and helps you insert the right amount of closing
779 braces at the end of an expression. For example,
796 @node Adding articulation marks to notes
797 @section Adding articulation marks to notes
803 Common accents can be added to a note using a dash (`@code{-}') and a
806 @lilypond[verbatim,relative 1]
807 c-. c-- c-> c-^ c-+ c-_
813 Similarly, fingering indications can be added to a note using a dash
814 (`@code{-}') and the digit to be printed:
816 @lilypond[verbatim,relative 1]
821 Dynamic signs are made by adding the markings to the note:
823 @lilypond[verbatim,relative 1]
833 Crescendi and decrescendi are started with the commands @code{\<} and
834 @code{\>}. The command @code{\!} finishes a crescendo on the note it
837 @lilypond[verbatim,relative 1]
838 c2\< c2\!\ff c2\> c2\!
847 A slur is drawn across many notes, and indicates bound articulation
848 (legato). The starting note and ending note are marked with a
849 ``@code{(}'' and a ``@code{)}'' respectively:
852 @lilypond[fragment,relative 1, verbatim]
853 d4( c16)( cis d e c cis d e)( d4)
857 @cindex slurs versus ties
858 A slur is different from a tie. A tie simply makes the first note
859 sound longer, and can only be used on pairs of notes with the same
860 pitch. Slurs indicate the articulations of notes, and can be used on
861 larger groups of notes. Slurs and ties are also nested in practice:
862 @lilypond[fragment, relative=1]
863 c2-~( c8 fis fis4 ~ fis2 g2)
866 @cindex phrasing slurs
867 If you need two slurs at the same time (one for articulation, one for
868 phrasing), you can also make a phrasing slur with @code{\(} and
872 @lilypond[fragment,relative 1, verbatim]
873 a8(\( ais b c) cis2 b'2 a4 cis, c\)
878 More information on fingering, articulation, slurs, phrasing slurs,
879 and dynamics can be found in @ref{Fingering instructions},
880 @ref{Articulations}, @ref{Slurs}, @ref{Phrasing slurs}, and @ref{Dynamics},
883 @node Combining notes into chords
884 @section Combining notes into chords
887 Chords can be made by
888 surrounding pitches with @code{<} and @code{>}:
890 @lilypond[relative 0, fragment,verbatim]
897 You can combine beams and ties with chords. Beam and tie markings
898 must be placed outside the chord markers:
900 @lilypond[relative 0, fragment,verbatim]
901 r4 <c e g>8[ <c f a>]-~ <c f a>
907 r4 <c e g>8\>( <c e g> <c e g> <c f a>8\!)
909 @lilypond[relative 0, fragment]
911 r4 <c e g>8\>( <c e g> <c e g> <c f a>8\!)
919 * Basic rhythmical commands::
920 * Commenting input files::
923 @node Basic rhythmical commands
924 @subsection Basic rhythmical commands
929 @cindex partial measure
930 A pickup (or upstep) is entered with the keyword @code{\partial}. It
931 is followed by a duration: @code{\partial 4} is a quarter note upstep
932 and @code{\partial 8} an eighth note:
933 @lilypond[relative 1,verbatim,fragment]
940 Tuplets are made with the @code{\times} keyword. It takes two
941 arguments: a fraction and a piece of music. The duration of the piece
942 of music is multiplied by the fraction. Triplets make notes occupy
943 2/3 of their notated duration, so a triplet has 2/3 as its fraction:
945 @lilypond[relative 0,verbatim,fragment]
946 \times 2/3 { f8 g a }
952 Grace notes are also made by prefixing a note, or a set of notes with
953 a keyword. In this case, the keyword is @code{\grace}:
954 @lilypond[relative 1, verbatim,fragment]
956 \grace { d16( e } d4)
960 More information on grace notes, tuplets and upsteps are in @ref{Grace
961 notes}, @ref{Tuplets} and @ref{Partial measures}.
965 @node Commenting input files
966 @subsection Commenting input files
970 @cindex block comment
971 Comments are pieces of the input that are ignored. There are two
972 types of comments. A line comments is introduced by @code{%}: after
973 that, the rest of that line is ignored. Block comments span larger
974 sections of input. Anything that is enclosed in @code{%@{} and
975 @code{%@}} is ignored too. The following fragment shows possible uses
979 % notes for twinkle twinkle follow:
984 This line, and the notes below
985 are ignored, since they are in a
995 @node Printing lyrics
996 @section Printing lyrics
1001 Lyrics are entered by separating each syllable with a space, and
1002 surrounding them with @code{\lyrics @{ @dots{} @}}, for example,
1004 \lyrics @{ I want to break free @}
1007 Like notes, lyrics are also a form of music, but they must not be
1008 printed on a staff, which is the default way to print music. To print
1009 them as lyrics, they must be marked with @code{ \context Lyrics}:
1011 \context Lyrics \lyrics @{ I want to break free @}
1013 The melody for this song is as follows:
1015 @lilypond[fragment,relative=1]
1018 \times 2/3 { f4 g g } \times 2/3 { g4( a2) }
1021 The lyrics can be set to these notes, combining both with the
1022 @code{\addlyrics} keyword:
1025 \notes @{ @dots{} @}
1026 \context Lyrics @dots{}
1030 @lilypond[verbatim,linewidth=6.0cm]
1037 \times 2/3 { f g g } \times 2/3 { g4( a2) }
1039 \context Lyrics \lyrics { I want to break free }
1046 @cindex extender line
1048 This melody ends on a @rglos{melisma}, a single syllable (``free'')
1049 sung to more than one note. This is indicated with a @emph{extender
1050 line}. It is entered as two underscores, i.e.
1052 \lyrics @{ I want to break free __ @}
1061 \times 2/3 { f g g } \times 2/3 { g4( a2) }
1063 %% ugh, this is to deal with bugs in the extender implementation
1067 \context Lyrics \lyrics { I want to break free __ }
1069 \paper{ linewidth = 9.0 \cm }
1073 Similarly, hyphens between words can be entered as two dashes,
1074 resulting in a centered hyphen between two syllables:
1076 Twin -- kle twin -- kle
1078 @lilypond[singleline]
1080 \addlyrics \notes \relative f' { \time 2/4
1082 \context Lyrics \lyrics { Twin -- kle twin -- kle
1084 \paper { linewidth = 6.0 \cm }
1089 More options, like putting multiple lines of lyrics below a melody are
1090 discussed in @ref{Vocal music}.
1095 @section A lead sheet
1101 In popular music, it is common to denote accompaniment as chord-names.
1102 Using them in LilyPond has two parts, just like lyrics: entering the
1103 chords (with @code{\chords}), and printing them (with @code{\context
1106 Chord names are entered by starting chords mode (with @code{\chords}).
1107 In chords mode, you can enter chords with a letter (indicating the
1108 root of the chord), and a durations following that:
1111 \chords { c2 f4. g8 }
1115 The result of @code{\chords} is a list of chords, and is equivalent
1116 to entering chords with @code{<@dots{}>}.
1118 Other chords can be created by adding modifiers, after a colon. The
1119 following example shows a few common modifiers:
1122 \chords { c2 f4:m g4:maj7 gis1:dim7 }
1125 Printing chords is done by adding @code{\context ChordNames}
1126 before the chords thus entered:
1129 \context ChordNames \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
1133 When put together, chord names, lyrics and a melody form
1134 a lead sheet, for example,
1139 \context ChordNames \chords @{ @emph{chords} @}
1141 \notes @emph{the melody}
1142 \context Lyrics \lyrics @{ @emph{the text} @}
1150 \context ChordNames \chords { r8 c2:sus4 f }
1152 \notes \relative c' {
1155 \times 2/3 { f g g } \times 2/3 { g4( a2) } }
1156 \context Lyrics \lyrics { I want to break free __ }
1158 \paper{ raggedright = ##t }
1163 A complete list of modifiers, and other options for layout are in the
1164 reference manual section @ref{Chords}.
1166 @node Listening to output
1167 @section Listening to output
1172 MIDI (Musical Instrument Digital Interface) is a standard for
1173 connecting and recording digital instruments. A MIDI file is like a
1174 tape recording of a MIDI instrument. The @code{\midi} block makes the
1175 music go to a MIDI file, so you can listen to the music you entered.
1176 It is great for checking the music: octaves that are off, or
1177 accidentals that were mistyped, stand out very much when listening to
1178 the musical transcription.
1180 @code{\midi} can be used in similarly to @code{\paper @{ @}}, for
1185 \midi @{ \tempo 4=72 @}
1190 Here, the tempo is specified using the @code{\tempo} command. In this
1191 case the tempo of quarter notes is set to 72 beats per minute. More
1192 information on auditory output is in the @ref{Sound} section in the
1200 Bibliographic information is entered in a separate block, the
1201 @code{\header} block. The name of the piece, its composer, etc. are
1202 entered as assignment, within @code{\header @{ @dots{} @}}. For
1206 title = "Eight miniatures"
1207 composer = "Igor Stravinsky"
1208 tagline = "small is beautiful"
1211 \score @{ @dots{} @}
1214 @cindex bibliographic information
1217 @cindex Engraved by LilyPond
1219 When the file is processed by @code{lilypond}, the title and composer
1220 specified are printed above the music. The `tagline' is a short line
1221 printed at bottom of the last page, which normally says ``Engraved
1222 by LilyPond, version @dots{}''. In the example above, it is replaced by the
1223 line ``small is beautiful''.
1225 Normally, the @code{\header} is put at the top of the file. However,
1226 for a document that contains multiple pieces (e.g. a etude book, or
1227 part with multiple movements), then the header can be put into the
1228 @code{\score} block as follows; in this case, the name of each piece
1229 will be printed before each movement:
1232 @cindex Lily was here
1233 @cindex signature line
1238 title = "Eight miniatures"
1239 composer = "Igor Stravinsky"
1240 tagline = "small is beautiful"
1244 \header @{ piece = "Adagio" @}
1247 \header @{ piece = "Menuetto" @}
1251 More information on titling can be found in @ref{Invoking lilypond}.
1254 @node Single staff polyphony
1255 @section Single staff polyphony
1258 @cindex multiple voices
1259 @cindex voices, more -- on a staff
1261 When different melodic lines are combined on a single staff, these are
1262 printed as polyphonic voices: each voice has its own stems, slurs
1263 and beams, and the top voice has the stems up, while the bottom voice
1266 Entering such parts is done by entering each voice as a sequence (with
1267 @code{@{ .. @}}), and combining those simultaneously, separating the
1268 voices with @code{\\}:
1271 << @{ a4 g2 f4-~ f4 @} \\
1272 @{ r4 g4 f2 f4 @} >>
1274 @lilypond[relative 1]
1275 \context Staff << { a4 g2 f4-~ f4 } \\
1279 For polyphonic music typesetting, spacer rests can also be convenient: these
1280 are rests that do not print. It is useful for filling up voices that
1281 temporarily do not play:
1283 << @{ a4 g2 f4-~ f4 @} \\
1284 @{ s4 g4 f2 f4 @} >>
1286 @lilypond[relative 1]
1287 \context Staff << { a4 g2 f4-~ f4 } \\
1291 Again, these expressions can be nested arbitrarily:
1297 << { a4 g2 f4-~ f4 } \\
1300 << { \clef bass <c g>1 } \\
1307 More features of polyphonic typesetting are in the notation manual
1311 @section Piano staves
1313 @cindex staff switch, manual
1314 @cindex cross staff voice, manual
1315 @cindex @code{\translator}
1317 Piano music is always typeset in two staves connected by a brace.
1318 Printing such a staff is done similar to the polyphonic example in
1319 @ref{Combining music into compound expressions}:
1321 << \new Staff @{ @dots{} @}
1322 \new Staff @{ @dots{} @}
1325 but now this entire expression must be interpreted as a
1328 \context PianoStaff << \context Staff @dots{} >>
1331 Here is a full-fledged example:
1333 @lilypond[relative 0,fragment]
1335 << \new Staff { \time 2/4
1338 \clef bass c,, c' e c }
1342 More information on formatting piano music is in @ref{Piano music}.
1344 @node Setting variables
1345 @section Setting variables
1347 When the music is converted from notes to print, it is interpreted
1348 from left-to-right order, similar to what happens when we read
1349 music. During this step, context-sensitive information, such as the
1350 accidentals to print, and where barlines must be placed, are stored in
1351 variables. These variables are called @emph{translation properties}.
1352 The properties can also be manipulated from input files. Consider this input:
1354 \property Staff.autoBeaming = ##f
1356 It sets the property named @code{autoBeaming} in the current staff to
1357 @code{##f}, which means `false'. This property controls whether beams
1358 are printed automatically:
1359 @lilypond[relative 1,fragment,verbatim]
1361 \property Staff.autoBeaming = ##f
1366 LilyPond includes a built-in programming language, namely, a dialect
1367 of Scheme. The argument to @code{\property}, @code{##f}, is an
1368 expression in that language. The first hash-mark signals that a piece
1369 of Scheme code follows. The second hash character is part of the
1370 boolean value true (@code{#t}). Values of other types may be
1373 @item a string, enclosed in double quotes, for example,
1375 \property Staff.instrument = #"French Horn"
1377 @item a boolean: either @code{#t} or @code{#f}, for true and false
1380 \property Voice.autoBeaming = ##f
1381 \property Score.skipBars = ##t
1384 @item a number, such as
1386 \property Score.currentBarNumber = #20
1389 @item a symbol, which is introduced by a quote character, as in
1391 \property Staff.crescendoSpanner = #'dashed-line
1394 @item a pair, which is also introduced by a quote character, like in
1395 the following statements, which set properties to the pairs (-7.5, 6)
1396 and (3, 4) respectively:
1399 \property Staff.minimumVerticalExtent = #'(-7.5 . 6)
1400 \property Staff.timeSignatureFraction = #'(3 . 4)
1406 There are many different properties, and not all of them are listed in
1407 this manual. However, the internal documentation lists them all in the
1408 @internalsref{All translation properties}, and most properties
1409 are demonstrated in one of the
1411 @uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
1419 @node Fine tuning layout
1420 @section Fine tuning layout
1422 Sometimes it is necessary to change music layout by hand. When music
1423 is formatted, layout objects are created for each symbol. For
1424 example, every clef and every note head is represented by a layout
1425 object. These layout objects also carry variables, which we call
1426 @emph{layout properties}. By changing these variables from their
1427 values, we can alter the look of a formatted score:
1429 @lilypond[verbatim,relative 0]
1431 \property Voice.Stem \override #'thickness = #3.0
1436 In the example shown here, the layout property @code{thickness} (a
1437 symbol) is set to 3 in the @code{Stem} layout objects of the current
1438 Voice. As a result, the notes following @code{\property} have thicker
1441 In most cases of manual overrides, only a single object must be
1442 changed. This can be achieved by prefixing @code{\once} to the
1443 @code{\property} statement, i.e.
1446 \once \property Voice.Stem \set #'thickness = #3.0
1449 @lilypond[relative 0]
1451 \once \property Voice.Stem \set #'thickness = #3.0
1456 Some overrides are so common that predefined commands are provided as
1457 a short cut. For example, @code{\slurUp} and @code{\stemDown}. These
1458 commands are described in
1462 @ref{Notation manual}, under the sections for slurs and stems
1465 The exact tuning possibilities for each type of layout object are
1466 documented in the internal documentation of the respective
1467 object. However, many layout objects share properties, which can be
1468 used to apply generic tweaks. We mention a couple of these:
1471 @item The @code{extra-offset} property, which
1472 @cindex @code{extra-offset}
1473 has a pair of numbers as value, moves around objects in the printout.
1474 The first number controls left-right movement; a positive number will
1475 move the object to the right. The second number controls up-down
1476 movement; a positive number will move it higher. The unit of these
1477 offsets are staff-spaces. The @code{extra-offset} property is a
1478 low-level feature: the formatting engine is completely oblivious to
1481 In the following example example, the second fingering is moved a
1482 little to the left, and 1.8 staff space downwards:
1484 @cindex setting object properties
1486 @lilypond[relative 1,verbatim]
1489 \once \property Voice.Fingering
1490 \set #'extra-offset = #'(-0.3 . -1.8)
1495 Setting the @code{transparent} property will make an object be printed
1496 in `invisible ink': the object is not printed, but all its other
1497 behavior is retained. The object still takes space, it takes part in
1498 collisions, and slurs, ties and beams can be attached to it.
1500 @cindex transparent objects
1501 @cindex removing objects
1502 @cindex invisible objects
1503 The following example demonstrates how to connect different voices
1504 using ties. Normally ties only happen between notes of the same
1505 voice. By introducing a tie in a different voice, and blanking a stem
1506 in that voice, the tie appears to cross voices:
1508 @lilypond[fragment,relative 1,verbatim]
1510 \once \property Voice.Stem \set #'transparent = ##t
1518 The @code{padding} property for objects with
1519 @cindex @code{padding}
1520 @code{side-position-interface} can be set to increase distance between
1521 symbols that are printed above or below notes. We only give an
1522 example; a more elaborate explanation is in @ref{Constructing a
1525 @lilypond[relative 1]
1527 \property Voice.Script \set #'padding = #3
1533 More specific overrides are also possible. The notation manual
1534 discusses in depth how to figure out these statements for yourself, in
1535 @ref{Tuning output}.
1537 @node Organizing larger pieces
1538 @section Organizing larger pieces
1540 When all of the elements discussed earlier are combined to produce
1541 larger files, the @code{\score} blocks get a lot bigger, because the
1542 music expressions are longer, and, in the case of polyphonic and/or
1543 orchestral pieces, more deeply nested.
1545 By using variables, also known as identifiers, it is possible to break
1546 up complex music expressions.
1547 An identifier is assigned as follows:
1549 namedMusic = \notes @{ @dots{}
1552 The contents of the music expression @code{namedMusic}, can be used
1553 later by preceding the name with a backslash, i.e. @code{\namedMusic}.
1554 In the next example, a two note motive is repeated thrice by using
1555 variable substitution:
1557 @lilypond[singleline,verbatim]
1562 \seufzer \seufzer \seufzer
1566 The name of an identifier should only have alphabetic characters only,
1567 and no numbers, underscores or dashes. The assignment should be
1568 outside of the @code{\score} block.
1570 It is possible to use variables for many other types of objects in the
1575 aFivePaper = \paper @{ paperheight = 21.0 \cm @}
1577 Depending on its contents, the identifier can be used in different
1578 places. The following example uses the above variables:
1581 \notes @{ c4^\name @}
1589 More information on the possible uses of identifiers is in the
1590 technical manual, in @ref{Scheme datatypes}.
1593 @node An orchestral part
1594 @section An orchestral part
1596 In orchestral music, all notes are printed twice: both in a part for
1597 the musicians, and in a full score for the conductor. Identifiers can
1598 be used to avoid double work: the music is entered once, and stored in
1599 variable. The contents of that variable is then used to generate
1600 both the part and the score.
1602 It is convenient to define the notes in a special file, for example,
1603 suppose that the @file{horn-music.ly} contains the following part of a
1606 hornNotes = \notes \relative c @{
1612 Then, an individual part is made by putting the following in a file:
1614 \include "horn-music.ly"
1616 instrument = "Horn in F"
1619 \notes \transpose c' f \hornNotes
1622 The @code{\include} command substitutes the contents of the file at
1623 this position in the file, so that @code{hornNotes} is defined
1624 afterwards. The code @code{\transpose f c'} indicates that the
1625 argument, being @code{\hornNotes}, should be transposed by a fifth
1626 downwards: sounding @code{f} is denoted by notated @code{c'}, which
1627 corresponds with tuning of a normal French Horn in F. The
1628 transposition can be seen in the following output:
1630 @lilypond[singleline]
1632 \notes \transpose f c' \notes \relative c {
1639 In ensemble pieces, one of the voices often does not play for many
1640 measures. This is denoted by a special rest, the multi-measure
1641 rest. It is entered with a capital R, and followed by a duration (1
1642 for a whole note, 2 for a half note, etc.) By multiplying the
1643 duration, longer rests can be constructed. For example, the next rest
1644 takes 3 measures in 2/4 time:
1649 When printing the part, the following @code{skipBars} property must be
1650 set to false, to prevent the rest from being expanded in three one bar
1653 \property Score.skipBars = ##t
1655 Prepending the rest and the property setting above, leads to the
1658 @lilypond[singleline]
1659 \score {\notes { \transpose f c' \relative c { \time 2/4
1660 \property Score.skipBars = ##t
1662 r4 f8 a cis4 f e d } }}
1665 The score is made by combining all of the music in a @code{\score}
1666 block, assuming that the other voice is in @code{bassoonNotes}, in the
1667 file @file{bassoon-music.ly}:
1669 \include "bassoon-music.ly"
1670 \include "horn-music.ly"
1674 \new Staff \hornNotes
1675 \new Staff \bassoonNotes
1679 This would lead to the simple score depicted below:
1681 @lilypond[singleline]
1683 \notes \relative c \simultaneous {
1684 \new Staff { \time 2/4
1686 r4 f8 a cis4 f e d }
1687 \new Staff { \clef bass
1688 r4 d,8 f | gis4 c | b bes |
1689 a8 e f4 | g d | gis f }
1693 More in-depth information on preparing parts and scores is in the
1694 notation manual, in @ref{Orchestral music}.
1697 @node Integrating text and music
1698 @section Integrating text and music
1700 @cindex La@TeX{}, music in
1701 @cindex HTML, music in
1702 @cindex Texinfo, music in
1704 Sometimes you might want to use music examples in a text that you are
1705 writing (for example, a musicological treatise, a songbook, or (like us)
1706 the LilyPond manual). You can make such texts by hand, simply by
1707 importing a PostScript figure into your word processor. However,
1708 there is an automated procedure to reduce the amount of work.
1710 If you use HTML, La@TeX{}, or Texinfo, you can mix text and LilyPond
1711 code. A script called @code{lilypond-book} will extract the music
1712 fragments, run LilyPond on them, and put back the resulting notation.
1713 This program is fully described in @ref{lilypond-book manual}. Here
1714 we show a small example; since the example contains also explanatory
1715 text, we will not comment it further:
1718 \documentclass[a4paper]@{article@}
1721 In a lilypond-book document, you can freely mix music and text. For
1724 \score @{ \notes \relative c' @{
1725 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
1729 Notice that the music line length matches the margin settings of the
1732 If you have no \verb+\score+ block in the fragment,
1733 \texttt@{lilypond-book@} will supply one:
1739 In the example you see here, two things happened: a
1740 \verb+\score+ block was added, and the line width was set to natural
1741 length. You can specify options by putting them in brackets:
1743 \begin[26pt,verbatim]@{lilypond@}
1747 If you want to include large examples into the text, it is more
1748 convenient to put it in a separate file:
1750 \lilypondfile@{screech-boink.ly@}
1755 Under Unix, you can view the results as follows:
1759 $ lilypond-book --outdir=out/ lilbook.tex
1760 lilypond-book (GNU LilyPond) 1.7.23
1761 Reading `input/tutorial/lilbook.tex'
1762 Reading `input/screech-boink6.ly'
1763 @var{lots of stuff deleted}
1764 Writing `out/lilbook.latex'
1766 $ latex lilbook.latex
1767 @var{lots of stuff deleted}
1771 Running lilypond-book and running latex creates a lot of temporary
1772 files, and you would not want those to clutter up your working
1773 directory. The @code{outdir} option to lilypond-book creates the
1774 temporary files in a separate subdirectory @file{out}.
1776 The result looks more or less like this:
1780 In a lilypond-book document, you can freely mix music and text. For
1784 \notes \relative c' {
1785 c2 g'2 \times 2/3 { f8 e d } c'2 g4
1793 Notice that the music line length matches the margin settings of the
1796 If you have no @code{\score} block in the fragment,
1797 @code{lilypond-book} will supply one:
1803 In the example you see here, two things happened: a
1804 @code{score} block was added, and the line width was set to natural
1805 length. You can specify options by putting them in brackets:
1807 @lilypond[26pt,verbatim]
1811 If you want to include large examples into the text, it is more
1812 convenient to put it in a separate file:
1814 @lilypondfile{screech-boink.ly}