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
396 A tie is created by adding a tilde ``@code{~}'' to the first note
399 @lilypond[fragment,verbatim,relative 2]
405 This example shows the key signature, accidentals and ties in action:
416 fis4 fis8 fis8 eis4 a8 gis-~
425 \notes { \transpose c c' {
431 fis4 fis8 fis8 eis4 a8 gis-~
434 \paper { linewidth = #(* 50 staffspace) }
440 There are some interesting points to note in this example. Bar lines
441 and beams are drawn automatically. Line breaks are calculated
442 automatically; it does not matter where the lines breaks are in the
443 source file. Finally, the order of time, key and clef changes is not
444 relevant: in the printout, these are ordered according to standard
445 notation conventions.
447 Accidentals (sharps and flats) do not have to be marked explicitly:
448 you just enter the pitch of the note, and an accidental is printed
449 only when necessary. The flip side of this mechanism, is that you have
450 to mark notes as sharp or flat, even when they do not get accidentals.
451 For example, in this example:
454 \property Staff.TimeSignature = #'()
456 cis dis eis fis gis ais bis
458 no note gets an explicit accidental, but still you enter
462 cis dis eis fis gis ais bis
465 Adding all alterations explicitly might require some more effort when
466 typing, but the advantage is that transposing is easier. It also makes
467 it possible to use different conventions for when to print
470 @cindex beams, by hand
471 Beams are drawn automatically, but if you do not like where they are
472 put, they can be entered by hand. Mark the first note to be beamed
473 with @code{[} and the last one with @code{]}:
475 @lilypond[fragment,relative 1, verbatim]
481 Rests are described in full detail in @ref{Rests}.
483 The notation manual discusses ties in @ref{Ties}.
487 @section Octave entry
490 @c Tim wants to move this quotes example just before the: quotes-do not-work
491 @c score, but we'd need to remove quotes from the other two (key and
494 @c better to have this just before the `octaves are bad' snipped
495 @c but we'd need to remove the ', from \key and tie
496 To raise a note by an octave, add a high quote @code{'} (apostrophe) to
497 the note name, to lower a note one octave, add a ``low quote'' @code{,}
498 (a comma). Middle C is @code{c'}:
502 c'4 c'' c''' \clef bass c c,
506 \property Score.timing = ##f
507 \property Staff.TimeSignature = \turnOff
508 c'4 c'' c''' \clef bass c c,
513 An example of the use of quotes is in the following Mozart fragment:
514 @lilypond[singleline,fragment,verbatim]
517 cis''8. d''16 cis''8 e''4 e''8
518 b'8. cis''16 b'8 d''4 d''8
521 This example shows that music in a high register needs lots of quotes.
522 This makes the input less readable, and it is a source of errors. The
523 solution is to use ``relative octave'' mode. In practice, this is the
524 most convenient way to copy existing music. To use relative mode, add
525 @code{\relative} before the piece of music. You must also give a note
526 from which relative starts, in this case @code{c''}. If you do not
527 use octavation quotes (i.e. do not add ' or , after a note), relative
528 mode chooses the note that is closest to the previous one.
529 For example, @code{c f} goes up while @code{c g} goes down:
539 \property Score.timing = ##f
540 \property Staff.TimeSignature = \turnOff
549 Since most music has small intervals, in relative mode pieces can be
550 written almost without using octavation quotes. In relative mode, the
551 Mozart example is entered as
553 @lilypond[singleline,fragment,verbatim]
563 @c needed better, maybe even redundant explanation
564 @c added another example below.
565 @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
566 @c in eerste instantie drong het `relative' niet door zonder extra uitleg.
567 Larger intervals are made by adding octavation quotes. Quotes or
568 commas do not determine the absolute height of a note; the height of a
569 note is relative to the previous one.
570 @c do not use commas or quotes in this sentence
571 For example: @code{c f,} goes down; @code{f, f} are both the same;
572 @code{c' c} are the same; and @code{c g'} goes up:
582 \property Score.timing = ##f
583 \property Staff.TimeSignature = \turnOff
592 Here is an example of the difference between relative mode and
593 ``normal'' (non-relative) mode:
604 \property Score.timing = ##f
605 \property Staff.TimeSignature = \turnOff
621 \property Score.timing = ##f
622 \property Staff.TimeSignature = \turnOff
637 @node Combining music into compound expressions
638 @section Combining music into compound expressions
640 To print more than one staff, each piece of music that makes up a
641 staff is marked by adding @code{\context Staff} before it. These
642 @code{Staff}'s are then grouped inside @code{\simultaneous @{} and
643 @code{@}}, as is demonstrated here:
646 @lilypond[fragment,verbatim]
648 \new Staff { \clef violin c'' }
649 \new Staff { \clef bass c }
655 In this example, @code{\simultaneous } indicates that both music
656 fragments happen at the same time, and must be printed stacked
657 vertically. The notation @code{< .. >} can also be used as a
658 shorthand for @code{\simultaneous @{ .. @}}.
660 @code{\context} introduces a ``notation context''. To understand this
661 concept, imagine that you are performing a piece of music. When you
662 perform the music, you combine the symbols printed at a certain point
663 with contextual information. For example, without knowing the current
664 clef, and the accidentals in the last measure, it would be impossible
665 to determine the pitch of a note. In other words, this information
666 forms context that helps you decipher a score. LilyPond produces
667 notation from music, so in effect, it does the inverse of reading
668 scores. Therefore, it also needs to keep track of contextual
669 information. This information is maintained in ``notation contexts.''
670 There are several types of contexts, e.g. @code{Staff}, @code{Voice}
671 and @code{Score}, but also @code{Lyrics} and
672 @code{ChordNames}. Prepending @code{\context} to a chunk of music
673 indicates what kind of context to use for interpreting it.
675 By specifying different names (in this case @code{staffA} and
676 @code{staffB}), two different contexts are created, leading to two
677 staves. It does not matter which names they are given, as long as they
678 are different. If they get the same name, the chunks of music are
679 assumed to belong on the same staff, and will be printed like that.
683 We can now typeset a melody with two staves:
686 @lilypond[verbatim,singleline]
707 The example shows how small chunks of music, for example, the notes
708 @code{c2}, @code{e4}, etc. of the second staff, are combined to form a
709 larger chunk by enclosing it in braces. Again, a larger chunk is
710 formed by prefix @code{\context Staff} to it, and that chunk is
711 combined with @code{< >}. This mechanism is similar with mathematical
712 formulas: in a formula, a so-called expression is formed by combining
713 simpler expressions into larger expressions. For example,
722 ((1 + 2) * 3) / (4 * 5)
725 @cindex music expression
726 is a sequence of expressions, where each expression is contained in
727 the next one. The simplest expressions are numbers and operators
728 (like +, * and /). Parentheses are used to group expressions. In
729 LilyPond input, a similar mechanism is used. Here, the simplest
730 expressions are notes and rests. By enclosing expressions in @code{<
731 >} and @code{@{ @}}, more complex music is formed. The @code{\context}
732 also forms new expressions; prepending it to a music expression yields
735 Like mathematical expressions, music expressions can be nested
736 arbitrarily deep, e.g.
737 @lilypond[verbatim,relative 1]
739 < { e f } { c <b d> }
746 When spreading expressions over multiple lines, it is customary to use
747 an indent that indicates the nesting level. Formatting music like this
748 eases reading, and helps you insert the right amount of closing
749 braces at the end of an expression. For example,
766 @node Adding articulation marks to notes
767 @section Adding articulation marks to notes
773 Common accents can be added to a note using a dash (`@code{-}') and a
776 @lilypond[verbatim,relative 1]
777 c-. c-- c-> c-^ c-+ c-_
783 Similarly, fingering indications can be added to a note using a dash
784 (`@code{-}') and the digit to be printed:
786 @lilypond[verbatim,relative 1]
791 Dynamic signs are made by adding the markings to the note:
793 @lilypond[verbatim,relative 1]
803 Crescendi and decrescendi are started with the commands @code{\<} and
804 @code{\>}. The command @code{\!} finishes a crescendo on the note it
807 @lilypond[verbatim,relative 1]
808 c2\< c2\!\ff c2\> c2\!
817 A slur is drawn across many notes, and indicates bound articulation
818 (legato). The starting note and ending note are marked with a
819 ``@code{(}'' and a ``@code{)}'' respectively:
822 @lilypond[fragment,relative 1, verbatim]
823 d4( c16)( cis d e c cis d e)( d4)
827 @cindex slurs versus ties
828 A slur is different from a tie. A tie simply makes the first note
829 sound longer, and can only be used on pairs of notes with the same
830 pitch. Slurs indicate the articulations of notes, and can be used on
831 larger groups of notes. Slurs and ties are also nested in practice:
832 @lilypond[fragment, relative=1]
833 c2-~( c8 fis fis4 ~ fis2 g2)
836 @cindex phrasing slurs
837 If you need two slurs at the same time (one for articulation, one for
838 phrasing), you can also make a phrasing slur with @code{\(} and
842 @lilypond[fragment,relative 1, verbatim]
843 a8(\( ais b c) cis2 b'2 a4 cis, c\)
848 More information on fingering, articulation, slurs, phrasing slurs,
849 and dynamics can be found in @ref{Fingering instructions},
850 @ref{Articulations}, @ref{Slurs}, @ref{Phrasing slurs}, and @ref{Dynamics},
853 @node Combining notes into chords
854 @section Combining notes into chords
857 Chords can be made by
858 surrounding pitches with @code{<<} and @code{>}>:
860 @lilypond[relative 0, fragment,verbatim]
861 r4 <<c e g>>4 <<c f a>>8
867 You can combine beams and ties with chords. Beam and tie markings
868 must be placed outside the chord markers:
870 @lilypond[relative 0, fragment,verbatim]
871 r4 <<c e g>>8[ <<c f a>>]-~ <<c f a>>
877 r4 <<c e g>>8\>( <<c e g>> <<c e g>> <<c f a>>8\!)
879 @lilypond[relative 0, fragment]
881 r4 <<c e g>>8\>( <<c e g>> <<c e g>> <<c f a>>8\!)
889 * Basic rhythmical commands::
890 * Commenting input files::
893 @node Basic rhythmical commands
894 @subsection Basic rhythmical commands
899 @cindex partial measure
900 A pickup (or upstep) is entered with the keyword @code{\partial}. It
901 is followed by a duration: @code{\partial 4} is a quarter note upstep
902 and @code{\partial 8} an eighth note:
903 @lilypond[relative 1,verbatim,fragment]
910 Tuplets are made with the @code{\times} keyword. It takes two
911 arguments: a fraction and a piece of music. The duration of the piece
912 of music is multiplied by the fraction. Triplets make notes occupy
913 2/3 of their notated duration, so a triplet has 2/3 as its fraction:
915 @lilypond[relative 0,verbatim,fragment]
916 \times 2/3 { f8 g a }
922 Grace notes are also made by prefixing a note, or a set of notes with
923 a keyword. In this case, the keyword is @code{\grace}:
924 @lilypond[relative 1, verbatim,fragment]
926 \grace { d16( e } d4)
930 More information on grace notes, tuplets and upsteps are in @ref{Grace
931 notes}, @ref{Tuplets} and @ref{Partial measures}.
935 @node Commenting input files
936 @subsection Commenting input files
940 @cindex block comment
941 Comments are pieces of the input that are ignored. There are two
942 types of comments. A line comments is introduced by @code{%}: after
943 that, the rest of that line is ignored. Block comments span larger
944 sections of input. Anything that is enclosed in @code{%@{} and
945 @code{%@}} is ignored too. The following fragment shows possible uses
949 % notes for twinkle twinkle follow:
954 This line, and the notes below
955 are ignored, since they are in a
965 @node Printing lyrics
966 @section Printing lyrics
971 Lyrics are entered by separating each syllable with a space, and
972 surrounding them with @code{\lyrics @{ @dots{} @}}, for example,
974 \lyrics @{ I want to break free @}
977 Like notes, lyrics are also a form of music, but they must not be
978 printed on a staff, which is the default way to print music. To print
979 them as lyrics, they must be marked with @code{ \context Lyrics}:
981 \context Lyrics \lyrics @{ I want to break free @}
983 The melody for this song is as follows:
985 @lilypond[fragment,relative=1]
988 \times 2/3 { f4 g g } \times 2/3 { g4( a2) }
991 The lyrics can be set to these notes, combining both with the
992 @code{\addlyrics} keyword:
996 \context Lyrics @dots{}
1000 @lilypond[verbatim,linewidth=6.0cm]
1007 \times 2/3 { f g g } \times 2/3 { g4( a2) }
1009 \context Lyrics \lyrics { I want to break free }
1016 @cindex extender line
1018 This melody ends on a @rglos{melisma}, a single syllable (``free'')
1019 sung to more than one note. This is indicated with a @emph{extender
1020 line}. It is entered as two underscores, i.e.
1022 \lyrics @{ I want to break free __ @}
1031 \times 2/3 { f g g } \times 2/3 { g4( a2) }
1033 %% ugh, this is to deal with bugs in the extender implementation
1037 \context Lyrics \lyrics { I want to break free __ }
1039 \paper{ linewidth = 9.0 \cm }
1043 Similarly, hyphens between words can be entered as two dashes,
1044 resulting in a centered hyphen between two syllables:
1046 Twin -- kle twin -- kle
1048 @lilypond[singleline]
1050 \addlyrics \notes \relative f' { \time 2/4
1052 \context Lyrics \lyrics { Twin -- kle twin -- kle
1054 \paper { linewidth = 6.0 \cm }
1059 More options, like putting multiple lines of lyrics below a melody are
1060 discussed in @ref{Vocal music}.
1065 @section A lead sheet
1071 In popular music, it is common to denote accompaniment as chord-names.
1072 Using them in LilyPond has two parts, just like lyrics: entering the
1073 chords (with @code{\chords}), and printing them (with @code{\context
1076 Chord names are entered by starting chords mode (with @code{\chords}).
1077 In chords mode, you can enter chords with a letter (indicating the
1078 root of the chord), and a durations following that:
1081 \chords { c2 f4. g8 }
1085 The result of @code{\chords} is a list of chords, and is equivalent
1086 to entering chords with @code{<<@dots{}>>}.
1088 Other chords can be created by adding modifiers, after a colon. The
1089 following example shows a few common modifiers:
1092 \chords { c2 f4:m g4:maj7 gis1:dim7 }
1095 Printing chords is done by adding @code{\context ChordNames}
1096 before the chords thus entered:
1099 \context ChordNames \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
1103 When put together, chord names, lyrics and a melody form
1104 a lead sheet, for example,
1109 \context ChordNames \chords @{ @emph{chords} @}
1111 \notes @emph{the melody}
1112 \context Lyrics \lyrics @{ @emph{the text} @}
1120 \context ChordNames \chords { r8 c2:sus4 f }
1122 \notes \relative c' {
1125 \times 2/3 { f g g } \times 2/3 { g4( a2) } }
1126 \context Lyrics \lyrics { I want to break free __ }
1128 \paper{ raggedright = ##t }
1133 A complete list of modifiers, and other options for layout are in the
1134 reference manual section @ref{Chords}.
1136 @node Listening to output
1137 @section Listening to output
1142 MIDI (Musical Instrument Digital Interface) is a standard for
1143 connecting and recording digital instruments. A MIDI file is like a
1144 tape recording of a MIDI instrument. The @code{\midi} block makes the
1145 music go to a MIDI file, so you can listen to the music you entered.
1146 It is great for checking the music: octaves that are off, or
1147 accidentals that were mistyped, stand out very much when listening to
1148 the musical transcription.
1150 @code{\midi} can be used in similarly to @code{\paper @{ @}}, for
1155 \midi @{ \tempo 4=72 @}
1160 Here, the tempo is specified using the @code{\tempo} command. In this
1161 case the tempo of quarter notes is set to 72 beats per minute. More
1162 information on auditory output is in the @ref{Sound} section in the
1170 Bibliographic information is entered in a separate block, the
1171 @code{\header} block. The name of the piece, its composer, etc. are
1172 entered as assignment, within @code{\header @{ @dots{} @}}. For
1176 title = "Eight miniatures"
1177 composer = "Igor Stravinsky"
1178 tagline = "small is beautiful"
1181 \score @{ @dots{} @}
1184 @cindex bibliographic information
1189 When the file is processed by @code{lilypond}, the title and composer
1190 specified are printed above the music. The `tagline' is a short line
1191 printed at bottom of the last page, which normally says ``Engraved
1192 by LilyPond, version @dots{}''. In the example above, it is replaced by the
1193 line ``small is beautiful''.
1195 Normally, the @code{\header} is put at the top of the file. However,
1196 for a document that contains multiple pieces (e.g. a etude book, or
1197 part with multiple movements), then the header can be put into the
1198 @code{\score} block as follows; in this case, the name of each piece
1199 will be printed before each movement:
1202 @cindex Lily was here
1203 @cindex signature line
1208 title = "Eight miniatures"
1209 composer = "Igor Stravinsky"
1210 tagline = "small is beautiful"
1214 \header @{ piece = "Adagio" @}
1217 \header @{ piece = "Menuetto" @}
1221 More information on titling can be found in @ref{Invoking lilypond}.
1224 @node Single staff polyphony
1225 @section Single staff polyphony
1228 @cindex multiple voices
1229 @cindex voices, more -- on a staff
1231 When different melodic lines are combined on a single staff, these are
1232 printed as polyphonic voices: each voice has its own stems, slurs
1233 and beams, and the top voice has the stems up, while the bottom voice
1236 Entering such parts is done by entering each voice as a sequence (with
1237 @code{@{ .. @}}), and combining those simultaneously, separating the
1238 voices with @code{\\}:
1241 < @{ a4 g2 f4-~ f4 @} \\
1244 @lilypond[relative 1]
1245 \context Staff < { a4 g2 f4-~ f4 } \\
1249 For polyphonic music typesetting, spacer rests can also be convenient: these
1250 are rests that do not print. It is useful for filling up voices that
1251 temporarily do not play:
1253 < @{ a4 g2 f4-~ f4 @} \\
1256 @lilypond[relative 1]
1257 \context Staff < { a4 g2 f4-~ f4 } \\
1261 Again, these expressions can be nested arbitrarily:
1267 < { a4 g2 f4-~ f4 } \\
1270 < { \clef bass <<c g>>1 } \\
1277 More features of polyphonic typesetting are in the notation manual
1281 @section Piano staves
1283 @cindex staff switch, manual
1284 @cindex cross staff voice, manual
1285 @cindex @code{\translator}
1287 Piano music is always typeset in two staves connected by a brace.
1288 Printing such a staff is done similar to the polyphonic example in
1289 @ref{Combining music into compound expressions}:
1291 < \new Staff @{ @dots{} @}
1292 \new Staff @{ @dots{} @}
1295 but now this entire expression must be interpreted as a
1298 \context PianoStaff < \context Staff @dots{} >
1301 Here is a full-fledged example:
1303 @lilypond[relative 0,fragment]
1305 < \new Staff { \time 2/4
1308 \clef bass c,, c' e c }
1312 More information on formatting piano music is in @ref{Piano music}.
1314 @node Setting variables
1315 @section Setting variables
1317 When the music is converted from notes to print, it is interpreted
1318 from left-to-right order, similar to what happens when we read
1319 music. During this step, context-sensitive information, such as the
1320 accidentals to print, and where barlines must be placed, are stored in
1321 variables. These variables are called @emph{translation properties}.
1322 The properties can also be manipulated from input files. Consider this input:
1324 \property Staff.autoBeaming = ##f
1326 It sets the property named @code{autoBeaming} in the current staff to
1327 @code{##f}, which means `false'. This property controls whether beams
1328 are printed automatically:
1329 @lilypond[relative 1,fragment,verbatim]
1331 \property Staff.autoBeaming = ##f
1336 LilyPond includes a built-in programming language, namely, a dialect
1337 of Scheme. The argument to @code{\property}, @code{##f}, is an
1338 expression in that language. The first hash-mark signals that a piece
1339 of Scheme code follows. The second hash character is part of the
1340 boolean value true (@code{#t}). Values of other types may be
1343 @item a string, enclosed in double quotes, for example,
1345 \property Staff.instrument = #"French Horn"
1347 @item a boolean: either @code{#t} or @code{#f}, for true and false
1350 \property Voice.autoBeaming = ##f
1351 \property Score.skipBars = ##t
1354 @item a number, such as
1356 \property Score.currentBarNumber = #20
1359 @item a symbol, which is introduced by a quote character, as in
1361 \property Staff.crescendoSpanner = #'dashed-line
1364 @item a pair, which is also introduced by a quote character, like in
1365 the following statements, which set properties to the pairs (-7.5, 6)
1366 and (3, 4) respectively:
1369 \property Staff.minimumVerticalExtent = #'(-7.5 . 6)
1370 \property Staff.timeSignatureFraction = #'(3 . 4)
1376 There are many different properties, and not all of them are listed in
1377 this manual. However, the internal documentation lists them all in the
1378 @internalsref{All translation properties}, and most properties
1379 are demonstrated in one of the
1381 @uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
1389 @node Fine tuning layout
1390 @section Fine tuning layout
1392 Sometimes it is necessary to change music layout by hand. When music
1393 is formatted, layout objects are created for each symbol. For
1394 example, every clef and every note head is represented by a layout
1395 object. These layout objects also carry variables, which we call
1396 @emph{layout properties}. By changing these variables from their
1397 values, we can alter the look of a formatted score:
1399 @lilypond[verbatim,relative 0]
1401 \property Voice.Stem \override #'thickness = #3.0
1406 In the example shown here, the layout property @code{thickness} (a
1407 symbol) is set to 3 in the @code{Stem} layout objects of the current
1408 Voice. As a result, the notes following @code{\property} have thicker
1411 In most cases of manual overrides, only a single object must be
1412 changed. This can be achieved by prefixing @code{\once} to the
1413 @code{\property} statement, i.e.
1416 \once \property Voice.Stem \set #'thickness = #3.0
1419 @lilypond[relative 0]
1421 \once \property Voice.Stem \set #'thickness = #3.0
1426 Some overrides are so common that predefined commands are provided as
1427 a short cut. For example, @code{\slurUp} and @code{\stemDown}. These
1428 commands are described in
1432 @ref{Notation manual}, under the sections for slurs and stems
1435 The exact tuning possibilities for each type of layout object are
1436 documented in the internal documentation of the respective
1437 object. However, many layout objects share properties, which can be
1438 used to apply generic tweaks. We mention a couple of these:
1441 @item The @code{extra-offset} property, which
1442 @cindex @code{extra-offset}
1443 has a pair of numbers as value, moves around objects in the printout.
1444 The first number controls left-right movement; a positive number will
1445 move the object to the right. The second number controls up-down
1446 movement; a positive number will move it higher. The unit of these
1447 offsets are staff-spaces. The @code{extra-offset} property is a
1448 low-level feature: the formatting engine is completely oblivious to
1451 In the following example example, the second fingering is moved a
1452 little to the left, and 1.8 staff space downwards:
1454 @cindex setting object properties
1456 @lilypond[relative 1,verbatim]
1459 \once \property Voice.Fingering
1460 \set #'extra-offset = #'(-0.3 . -1.8)
1465 Setting the @code{transparent} property will make an object be printed
1466 in `invisible ink': the object is not printed, but all its other
1467 behavior is retained. The object still takes space, it takes part in
1468 collisions, and slurs, ties and beams can be attached to it.
1470 @cindex transparent objects
1471 @cindex removing objects
1472 @cindex invisible objects
1473 The following example demonstrates how to connect different voices
1474 using ties. Normally ties only happen between notes of the same
1475 voice. By introducing a tie in a different voice, and blanking a stem
1476 in that voice, the tie appears to cross voices:
1478 @lilypond[fragment,relative 1,verbatim]
1480 \once \property Voice.Stem \set #'transparent = ##t
1488 The @code{padding} property for objects with
1489 @cindex @code{padding}
1490 @code{side-position-interface} can be set to increase distance between
1491 symbols that are printed above or below notes. We only give an
1492 example; a more elaborate explanation is in @ref{Constructing a
1495 @lilypond[relative 1]
1497 \property Voice.Script \set #'padding = #3
1503 More specific overrides are also possible. The notation manual
1504 discusses in depth how to figure out these statements for yourself, in
1505 @ref{Tuning output}.
1507 @node Organizing larger pieces
1508 @section Organizing larger pieces
1510 When all of the elements discussed earlier are combined to produce
1511 larger files, the @code{\score} blocks get a lot bigger, because the
1512 music expressions are longer, and, in the case of polyphonic and/or
1513 orchestral pieces, more deeply nested.
1515 By using variables, also known as identifiers, it is possible to break
1516 up complex music expressions.
1517 An identifier is assigned as follows:
1519 namedMusic = \notes @{ @dots{}
1522 The contents of the music expression @code{namedMusic}, can be used
1523 later by preceding the name with a backslash, i.e. @code{\namedMusic}.
1524 In the next example, a two note motive is repeated thrice by using
1525 variable substitution:
1527 @lilypond[singleline,verbatim]
1532 \seufzer \seufzer \seufzer
1536 The name of an identifier should only have alphabetic characters only,
1537 and no numbers, underscores or dashes. The assignment should be
1538 outside of the @code{\score} block.
1540 It is possible to use variables for many other types of objects in the
1545 aFivePaper = \paper @{ paperheight = 21.0 \cm @}
1547 Depending on its contents, the identifier can be used in different
1548 places. The following example uses the above variables:
1551 \notes @{ c4^\name @}
1559 More information on the possible uses of identifiers is in the
1560 technical manual, in @ref{Scheme datatypes}.
1563 @node An orchestral part
1564 @section An orchestral part
1566 In orchestral music, all notes are printed twice: both in a part for
1567 the musicians, and in a full score for the conductor. Identifiers can
1568 be used to avoid double work: the music is entered once, and stored in
1569 variable. The contents of that variable is then used to generate
1570 both the part and the score.
1572 It is convenient to define the notes in a special file, for example,
1573 suppose that the @file{horn-music.ly} contains the following part of a
1576 hornNotes = \notes \relative c @{
1582 Then, an individual part is made by putting the following in a file:
1584 \include "horn-music.ly"
1586 instrument = "Horn in F"
1589 \notes \transpose c' f \hornNotes
1592 The @code{\include} command substitutes the contents of the file at
1593 this position in the file, so that @code{hornNotes} is defined
1594 afterwards. The code @code{\transpose f c'} indicates that the
1595 argument, being @code{\hornNotes}, should be transposed by a fifth
1596 downwards: sounding @code{f} is denoted by notated @code{c'}, which
1597 corresponds with tuning of a normal French Horn in F. The
1598 transposition can be seen in the following output:
1600 @lilypond[singleline]
1602 \notes \transpose f c' \notes \relative c {
1609 In ensemble pieces, one of the voices often does not play for many
1610 measures. This is denoted by a special rest, the multi-measure
1611 rest. It is entered with a capital R, and followed by a duration (1
1612 for a whole note, 2 for a half note, etc.) By multiplying the
1613 duration, longer rests can be constructed. For example, the next rest
1614 takes 3 measures in 2/4 time:
1619 When printing the part, the following @code{skipBars} property must be
1620 set to false, to prevent the rest from being expanded in three one bar
1623 \property Score.skipBars = ##t
1625 Prepending the rest and the property setting above, leads to the
1628 @lilypond[singleline]
1629 \score {\notes { \transpose f c' \relative c { \time 2/4
1630 \property Score.skipBars = ##t
1632 r4 f8 a cis4 f e d } }}
1635 The score is made by combining all of the music in a @code{\score}
1636 block, assuming that the other voice is in @code{bassoonNotes}, in the
1637 file @file{bassoon-music.ly}:
1639 \include "bassoon-music.ly"
1640 \include "horn-music.ly"
1644 \new Staff \hornNotes
1645 \new Staff \bassoonNotes
1649 This would lead to the simple score depicted below:
1651 @lilypond[singleline]
1653 \notes \relative c \simultaneous {
1654 \new Staff { \time 2/4
1656 r4 f8 a cis4 f e d }
1657 \new Staff { \clef bass
1658 r4 d,8 f | gis4 c | b bes |
1659 a8 e f4 | g d | gis f }
1663 More in-depth information on preparing parts and scores is in the
1664 notation manual, in @ref{Orchestral music}.
1667 @node Integrating text and music
1668 @section Integrating text and music
1670 @cindex La@TeX{}, music in
1671 @cindex HTML, music in
1672 @cindex Texinfo, music in
1674 Sometimes you might want to use music examples in a text that you are
1675 writing (for example, a musicological treatise, a songbook, or (like us)
1676 the LilyPond manual). You can make such texts by hand, simply by
1677 importing a PostScript figure into your word processor. However,
1678 there is an automated procedure to reduce the amount of work.
1680 If you use HTML, La@TeX{}, or Texinfo, you can mix text and LilyPond
1681 code. A script called @code{lilypond-book} will extract the music
1682 fragments, run LilyPond on them, and put back the resulting notation.
1683 This program is fully described in @ref{lilypond-book manual}. Here
1684 we show a small example; since the example contains also explanatory
1685 text, we will not comment it further:
1688 \documentclass[a4paper]@{article@}
1691 In a lilypond-book document, you can freely mix music and text. For
1694 \score @{ \notes \relative c' @{
1695 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
1699 Notice that the music line length matches the margin settings of the
1702 If you have no \verb+\score+ block in the fragment,
1703 \texttt@{lilypond-book@} will supply one:
1709 In the example you see here, two things happened: a
1710 \verb+\score+ block was added, and the line width was set to natural
1711 length. You can specify options by putting them in brackets:
1713 \begin[26pt,verbatim]@{lilypond@}
1717 If you want to include large examples into the text, it is more
1718 convenient to put it in a separate file:
1720 \lilypondfile@{screech-boink.ly@}
1725 Under Unix, you can view the results as follows:
1729 $ lilypond-book --outdir=out/ lilbook.tex
1730 lilypond-book (GNU LilyPond) 1.7.23
1731 Reading `input/tutorial/lilbook.tex'
1732 Reading `input/screech-boink6.ly'
1733 @var{lots of stuff deleted}
1734 Writing `out/lilbook.latex'
1736 $ latex lilbook.latex
1737 @var{lots of stuff deleted}
1741 Running lilypond-book and running latex creates a lot of temporary
1742 files, and you would not want those to clutter up your working
1743 directory. The @code{outdir} option to lilypond-book creates the
1744 temporary files in a separate subdirectory @file{out}.
1746 The result looks more or less like this:
1750 In a lilypond-book document, you can freely mix music and text. For
1754 \notes \relative c' {
1755 c2 g'2 \times 2/3 { f8 e d } c'2 g4
1763 Notice that the music line length matches the margin settings of the
1766 If you have no @code{\score} block in the fragment,
1767 @code{lilypond-book} will supply one:
1773 In the example you see here, two things happened: a
1774 @code{score} block was added, and the line width was set to natural
1775 length. You can specify options by putting them in brackets:
1777 @lilypond[26pt,verbatim]
1781 If you want to include large examples into the text, it is more
1782 convenient to put it in a separate file:
1784 @lilypondfile{screech-boink.ly}