4 @c * more details about running lilypond; error messages,
5 @c compiling/viewing (emacs?)
6 @c * where to go from First steps+More basics?
12 <!--- @@WEB-TITLE@@=Tutorial --->
16 * First steps:: Music language of LilyPond.
17 * Running LilyPond:: Printing music.
21 * Listening to output::
23 * Single staff polyphony ::
26 * Fine tuning layout::
27 * Organizing larger pieces::
28 * An orchestral part::
29 * Integrating text and music:: Integrating text and music.
32 Printing music with LilyPond is a two step process. First, the music
33 to be printed is described in a text file. After that, LilyPond reads
34 this @emph{input file} that describes the music and produces an
35 @emph{output file} that can be printed or viewed.
37 This tutorial starts with a short introduction to the LilyPond music
38 language. After this first contact, we will show you how to to
39 produce printed output, normally using the program @code{ly2dvi}. You
40 should then be able to create and print your first sheets of music.
41 Before starting out, it will be convenient for you to print
45 @ref{Cheat sheet}, which is a table listing all commands for quick
53 We start off by showing how very simple music is entered in LilyPond:
54 you get a note simply by typing its @htmlref{note name}, from @samp{a}
55 through @samp{g}. So if you enter
62 then the result looks like this:
65 @c \transpose c c' { c d e f g a b }
67 @c \property Score.timing = ##f
68 @lilypond[notime, relative=2]
72 We will continue with this format: First we show a snippet of input,
73 then the resulting output.
75 The length of a note is specified by adding a number, @samp{1} for a
76 @rglos{whole note}, @samp{2} for a @rglos{half note}, and so on:
83 \property Score.timing = ##f
84 \property Staff.autoBeaming = ##f
85 \transpose c c' { a1 a2 a4 a16 a32 s16_" " }
88 If you do not specify a @rglos{duration}, the previous one is used:
95 \property Score.timing = ##f
96 \transpose c c' { a a a2 a s16_" " }
99 A @rglos{sharp} (@texisharp{}) is made by adding @samp{is}, a
100 @rglos{flat} (@texiflat{}) by adding @samp{es}. As you might expect,
101 a @rglos{double sharp} or @rglos{double flat} is made by adding
102 @samp{isis} or @samp{eses}:@footnote{This syntax derived from note
103 naming conventions in Nordic and Germanic languages, like German and
111 \property Score.timing = ##f
112 \transpose c c' { cis1 ees fisis aeses s16_" " }
115 Add a dot @samp{.} after the duration to get a @rglos{dotted note}:
122 \property Score.timing = ##f
123 \transpose c c' { a2. a4 a8. a16 s16_" " }
126 Entering pitches and durations is fully explained in @ref{Pitches} and
130 The @rglos{meter} (or @rglos{time signature}) can be set with the
131 @code{\time} command:
139 @c a clef here may lead to confusion
141 \property Staff.Clef \set #'transparent = ##t
150 Time signatures and other timing commands are described in @ref{Time
154 The @rglos{clef} can be set using the @code{\clef} command:
156 @c what is more common name treble or violin?
157 @c in Dutch, its violin.
158 @c in English its definitely treble.
167 \property Score.timing = ##f
178 Clefs are fully explained in @ref{Clef}.
181 These commands must be enclosed in @code{\notes @{@dots{}@}}. This
182 indicates that music (as opposed to @rglos{lyrics}) follows:
192 Now the piece of music is almost ready to be printed. The final step is to
193 combine the music with a printing command.
195 The printing command is the so-called @code{\paper} block. Later on
196 you will see that the @code{\paper} block is used to customize
197 printing specifics. The music and the @code{\paper} block are combined by
198 enclosing them in @code{\score @{ ... @}}. This is what a full source file looks like:
221 linewidth = 55 * \staffspace
227 @node Running LilyPond
228 @section Running LilyPond
230 In the last section we explained what kind of things you could enter
231 in a LilyPond file. In this section we explain what commands to run
232 and how to view or print the output. If you have not used LilyPond
233 before, want to test your setup, or want to run an example file
234 yourself, read this section. The instructions that follow are for
235 Unix-like systems. Some additional instructions for Microsoft Windows are given
236 at the end of this section.
238 Begin by opening a terminal window and starting a text editor.
239 For example, you could open an xterm and execute @code{joe}. In your
240 text editor, enter the following input and save the file as
246 \notes @{ c'4 e' g' @}
253 @c now this is weird, running ly2dvi to run LilyPond
254 @c (therefore name change proposal)
256 LilyPond is the program that computes the sheet music. All other
257 things, such as adding titles, page breaking and other page layout,
258 are done by a small wrapper program called
259 @code{ly2dvi}. @code{ly2dvi} calls LilyPond to render the music, and
260 then adds the titling and page layout instructions. To process
261 @file{test.ly} with @code{ly2dvi}, proceed as follows:
269 You will see the following on your screen:
274 Now processing: `/home/fred/ly/test.ly'
276 Interpreting music...[1]
277 @emph{ ... more interesting stuff ... }
278 PDF output to `test.pdf'...
279 DVI output to `test.dvi'...
283 @cindex Viewing music
286 The results of the ly2dvi run are two files, @file{test.dvi} and
287 @file{test.pdf}. The PDF file (@file{test.pdf}) is the one you can
288 print or view. For example, viewing PDF can be done with ghostview.
289 If a version of ghostview is installed on your system, one of these
290 commands will produce a window with some music notation on your
303 If the music on your screen looks good, you can print it by clicking
304 File/Print inside ghostview.
306 The DVI file (@file{test.dvi}) contains the same sheet music in a
307 different format. DVI files are more easily processed by the computer,
308 so viewing them usually is quicker. You can run @code{xdvi test.dvi}
309 @c KDVI doesn't grok the PS specials.
311 @c @code{kdvi test.dvi}
313 to view the DVI file. In Xdvi, the mouse buttons
314 activate magnifying glasses. Unfortunately, variable symbols (such as
315 beams and slurs) are not displayed in the magnifying glasses.
320 @cindex Printing output
324 If you are familiar with @TeX{}, be warned: do not use other DVI
325 drivers like @code{dvilj}. LilyPond DVI use embedded PostScript code
326 and will not render correctly with other DVI drivers besides
334 Various commands for formatting and printing music are detailed in
335 @ref{Invoking LilyPond}.
338 @unnumberedsubsec Windows users
340 On Windows, the terminal is started by clicking on the LilyPond or
341 Cygwin icon. Any text editor (such as NotePad, Emacs or Vim) may be
342 used to edit the LilyPond file. When Cygwin's @code{XFree86} X11
343 window system is installed along with @code{tetex-x11} and
344 @code{ghostscript-x11} packages, then the @code{dvi} output may be
345 viewed with @code{xdvi test.dvi} as described above. If you have
346 installed a PostScript/PDF viewer, such as @code{GSView} from
347 @uref{http://www.cs.wisc.edu/~ghost}, viewing the PDF file can be done
351 @code{gsview32 test.pdf}
354 Printing may be done by executing
357 @code{gsview32 /s test.pdf}
365 We continue with the introduction of more musical constructs. Normal
366 rests are entered just like notes with the name ``@code{r}'':
375 \property Score.timing = ##f
376 \property Staff.Clef = \turnOff
377 \property Staff.TimeSignature = \turnOff
384 Rests are described in full detail in @ref{Rests}.
387 @c Tim wants to move this quotes example just before the: quotes-do not-work
388 @c score, but we'd need to remove quotes from the other two (key and
391 @c better to have this just before the `octaves are bad' snipped
392 @c but we'd need to remove the ', from \key and tie
393 To raise a note by an octave, add a high quote @code{'} (apostrophe) to
394 the note name, to lower a note one octave, add a ``low quote'' @code{,}
395 (a comma). Middle C is @code{c'}:
399 c'4 c'' c''' \clef bass c c,
403 \property Score.timing = ##f
404 \property Staff.TimeSignature = \turnOff
405 c'4 c'' c''' \clef bass c c,
412 A tie is created by adding a tilde ``@code{~}'' to the first note
415 @lilypond[fragment,verbatim]
420 @cindex slurs versus ties
421 A tie is different from a slur. A tie simply makes the first note
422 sound longer, and can only be used on pairs of notes with the same
423 pitch. Slurs indicate the articulations of notes, and can be used on
424 larger groups of notes. Slurs and ties are also nested in practice:
425 @lilypond[fragment, relative=1]
426 c2-~-( c8 fis fis4 ~ fis2 g2-)
429 The notation manual discusses ties in @ref{Ties}.
431 @cindex key signature, setting
433 The key signature is set with the command ``@code{\key}'', followed by
434 a pitch and @code{\major} or @code{\minor}:
444 \property Staff.TimeSignature = \turnOff
454 @c bit on the long/complex/scary taste
455 @c cheating a bit: two lines makes for a friendlier look
456 This example shows notes, ties, octave marks, and rests in action.
465 r4 r8 d''8 cis''4 e''
467 cis''4 cis''8 cis'' bis'4 d''8 cis''-~
480 r4 r8 d''8 cis''4 e''
482 cis''4 cis''8 cis'' bis'4 d''8 cis''-~
485 \paper { linewidth = 50*\staffspace }
492 There are some interesting points to note in this example.
493 Accidentals (sharps and flats) do not have to be marked explicitly:
494 you just enter the note name, and an accidental is printed
495 automatically, only when necessary. Bar lines and beams are drawn
496 automatically. Line breaks are calculated automatically; it does not
497 matter where the lines breaks are in the source file. Finally, the
498 order of time, key and clef changes is not relevant: in the printout,
499 these are ordered using standard notation conventions.
501 The example also indicates that a piece of music written in a high
502 register needs lots of quotes. This makes the input less readable,
503 and is also a potential source of errors.
505 The solution is to use ``relative octave'' mode. In practice, this is
506 the most convenient way to copy existing music. To use relative mode,
507 add @code{\relative} before the piece of music. You must also give a
508 note from which relative starts, in this case @code{c''}. If you do
509 not use octavation quotes (i.e. do not add ' or , after a note),
510 relative mode chooses the note that is closest to the previous one.
511 @c do not use commas or quotes in this sentence
512 For example: @code{c f} goes up; @code{c g} goes down:
522 \property Score.timing = ##f
523 \property Staff.TimeSignature = \turnOff
532 Since most music has small intervals, in relative mode pieces can be
533 written almost without using octavation quotes.
535 @c needed better, maybe even redundant explanation
536 @c added another example below.
537 @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
538 @c in eerste instantie drong het `relative' niet door zonder extra uitleg.
539 Larger intervals are made by adding octavation quotes. Quotes or
540 commas do not determine the absolute height of a note; the height of a
541 note is relative to the previous one.
542 @c do not use commas or quotes in this sentence
543 For example: @code{c f,} goes down; @code{f, f} are both the same;
544 @code{c' c} are the same; and @code{c g'} goes up:
554 \property Score.timing = ##f
555 \property Staff.TimeSignature = \turnOff
564 Here is an example of the difference between relative mode and
565 ``normal'' (non-relative) mode:
576 \property Score.timing = ##f
577 \property Staff.TimeSignature = \turnOff
593 \property Score.timing = ##f
594 \property Staff.TimeSignature = \turnOff
603 A slur is drawn across many notes, and indicates bound articulation
604 (legato). The starting note and ending note are marked with a
605 ``@code{(}'' and a ``@code{)}'' respectively:
608 @lilypond[fragment,relative 1, verbatim]
609 d4-( c16-)-( cis d e c cis d e-)-( d4-)
614 @cindex phrasing slurs
615 If you need two slurs at the same time (one for articulation, one for
616 phrasing), you can also make a phrasing slur with @code{\(} and
621 @c fragment of 1st hrn in Adams' The Chairman Dances, with creative
622 @c chromatic thing pasted in front. (admittedly the original does not
623 @c have a phrasing slur. The problem is that we do not want the slur
624 @c and the Phrasing slur to collide. We are trying to make a good
628 @lilypond[fragment,relative 1, verbatim]
629 a8-(-\( ais b c-) cis2 b'2 a4 cis, c-\)
634 @cindex beams, by hand
635 Beams are drawn automatically, but if you do not like where they are
636 put, they can be entered by hand. Mark the first note to be beamed
637 with @code{[} and the last one with @code{]}:
639 @lilypond[fragment,relative 1, verbatim]
640 a8-[ ais-] d-[ es r d-]
646 * Combining music into compound expressions::
647 * Adding articulation marks to notes ::
648 * Basic rhythmical commands::
649 * Commenting input files::
652 @node Combining music into compound expressions
653 @subsection Combining music into compound expressions
655 To print more than one staff, each piece of music that makes up a staff
656 is marked by adding @code{\context Staff} before it. These
657 @code{Staff}'s are then grouped inside @code{\simultaneous @{} and @code{@}}, as is
661 @lilypond[fragment,verbatim]
663 \context Staff = staffA { \clef violin c'' }
664 \context Staff = staffB { \clef bass c }
669 In this example, @code{staffA} and @code{staffB} are names that are
670 given to the staves. It does not matter what names you give, as long
671 as each staff has a different name. If you give them the same name,
672 they are assumed to belong on the same staff, and will be printed like
673 that. @code{\simultaneous } indicates that both fragments happen at
674 the same time, and must be printed stacked vertically. The notation
675 @code{< .. >} can also be used as a shorthand for @code{\simultaneous
680 We can now typeset a melody with two staves:
683 @lilypond[verbatim,singleline]
686 < \context Staff = staffA {
690 e2-( d4 c2 b4 a8-[ a-]
691 b-[ b-] g-[ g-] a2.-) }
693 \context Staff = staffB {
704 The example shows how small chunks of music, for example the notes
705 @code{c2}, @code{e4}, etc. of the second staff, are combined to form a
706 larger chunk by enclosing it in braces. Again, a larger chunk is
707 formed by prefix @code{\context Staff} to it, and that chunk is
708 combined with @code{< >}. This mechanism is similar with mathematical
709 formulas: in a formula, a so-called expression is formed by combining
710 simpler expressions into larger expressions. For example,
719 ((1 + 2) * 3) / (4 * 5)
722 @cindex music expression
723 is a sequence of expressions, where each expression is contained in
724 the next one. The simplest expressions are numbers and operators
725 (like +, * and /). Parentheses are used to group expressions. In
726 LilyPond input, a similar mechanism is used. Here, the simplest
727 expressions are notes and rests. By enclosing expressions in @code{<
728 >} and @code{@{ @}}, more complex music is formed. The @code{\context}
729 also forms new expressions; it is prepended to a music expression.
732 When spreading expressions over multiple lines, it is customary to use
733 an indent that indicates the nesting level. Formatting music like this
734 eases reading, and helps you insert the right amount of closing
735 braces at the end of an expression. For example
749 @node Adding articulation marks to notes
750 @subsection Adding articulation marks to notes
756 Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
758 @lilypond[verbatim,relative 1]
765 Similarly, fingering indications can be added to a note using @code{-}
766 and the digit to be printed.
767 @lilypond[verbatim,relative 1]
772 Dynamic signs are made by adding the markings to the note:
774 @lilypond[verbatim,relative 1]
784 Crescendi and decrescendi are started with the commands @code{\<} and
785 @code{\>}. The command @code{\!} finishes a crescendo on the note it
788 @lilypond[verbatim,relative 1]
789 c2-\< c2-\!-\ff c2-\> c2-\!
795 Chords can be made by
796 surrounding pitches with @code{<<} and @code{>}>:
798 @lilypond[relative 0, fragment,verbatim]
799 r4 <<c e g>>4 <<c f a>>8
805 You can combine beams and ties with chords. Beam and tie markings
806 must be placed outside the chord markers:
808 @lilypond[relative 0, fragment,verbatim]
809 r4 <<c e g>>8-[ <<c f a>>-]-~ <<c f a>>
815 r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-)
817 @lilypond[relative 0, fragment]
819 r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-)
825 @node Basic rhythmical commands
826 @subsection Basic rhythmical commands
831 @cindex partial measure
832 A pickup (or upstep) is entered with the keyword @code{\partial}. It
833 is followed by a duration: @code{\partial 4} is a quarter note upstep
834 and @code{\partial 8} an eighth note.
835 @lilypond[relative 1,verbatim,fragment]
842 Tuplets are made with the @code{\times} keyword. It takes two
843 arguments: a fraction and a piece of music. The duration of the piece
844 of music is multiplied by the fraction. Triplets make notes occupy
845 2/3 of their notated duration, so a triplet has 2/3 as its fraction.
847 @lilypond[relative 0,verbatim,fragment]
848 \times 2/3 { f8 g a }
854 Grace notes are also made by prefixing a note, or a set of notes with
855 a keyword. In this case, the keyword is @code{\grace}.
856 @lilypond[relative 1, verbatim,fragment]
858 \grace { d16-( e } d4-)
862 More information on the use of grace notes is in @ref{Grace notes}.
865 @node Commenting input files
866 @subsection Commenting input files
870 @cindex block comment
871 Comments are pieces of the input that are ignored. There are two
872 types of comments. A line comments are introduced by @code{%}: after
873 that, the rest of that line is ignored. Block comments span larger
874 sections of input. Anything that is enclosed in @code{%@{} and
875 @code{%@}} is ignored too. The following fragment shows possible uses
879 % notes for twinkle twinkle follow:
884 This line, and the notes below
885 are ignored, since they are in a
895 @node Printing lyrics
896 @section Printing lyrics
901 Lyrics are entered by separating each syllable with a space, and
902 surrounding them with @code{\lyrics @{ @dots{} @}}, for example
904 \lyrics @{ I want to break free @}
907 Like notes, lyrics are also a form of music, but they must not be
908 printed on a staff, which is the default way to print music. To print
909 them as lyrics, they must be marked with @code{ \context Lyrics}:
911 \context Lyrics \lyrics @{ I want to break free @}
913 The melody for this song is as follows
915 @lilypond[fragment,relative=1]
918 \times 2/3 { f4 g g } \times 2/3 { g4-( a2-) }
921 The lyrics can be set to these notes, combining both with the
922 @code{\addlyrics} keyword:
926 \context Lyrics @dots{}
930 @lilypond[verbatim,linewidth=6.0cm]
937 \times 2/3 { f g g } \times 2/3 { g4-( a2-) }
939 \context Lyrics \lyrics { I want to break free }
946 @cindex extender line
948 This melody ends on a @rglos{melisma}, a single syllable (``free'')
949 sung to more than one note. This is indicated with a @emph{extender
950 line}. It is entered as two underscores, i.e.,
952 \lyrics @{ I want to break free __ @}
961 \times 2/3 { f g g } \times 2/3 { g4-( a2-) }
963 %% ugh, this is to deal with bugs in the extender implementation
967 \context Lyrics \lyrics { I want to break free __ }
969 \paper{ linewidth = 9.0 \cm }
973 Similarly, hyphens between words can be entered as two dashes,
974 resulting in a centered hyphen between two syllables.
976 Twin -- kle twin -- kle
978 @lilypond[singleline]
980 \addlyrics \notes \relative f' { \time 2/4
982 \context Lyrics \lyrics { Twin -- kle twin -- kle
984 \paper { linewidth = 6.0 \cm }
989 More options, like putting multiple lines of lyrics below a melody are
990 discussed in @ref{Vocal music}.
994 TODO: discuss contexts.
998 @section A lead sheet
1004 In popular music, it is common to denote accompaniment as chord-names.
1005 Using them in LilyPond has two parts, just like lyrics: entering the
1006 chords (with @code{\chords}), and printing them (with @code{\context
1009 Chord names are entered by starting chords mode (with @code{\chords}).
1010 In chords mode, you can enter chords with a letter (indicating the
1011 root of the chord), and a durations following that.
1014 \chords { c2 f4. g8 }
1018 The result of @code{\chords} is a list of chords, and is equivalent
1019 to entering chords with @code{<<@dots{}>>}.
1021 Other chords can be created by adding modifiers, after a colon. The
1022 following example shows a few common modifiers
1025 \chords { c2 f4:m g4:maj7 gis1:dim7 }
1028 Printing chords is done by adding @code{\context ChordNames}
1029 before the chords thus entered:
1032 \context ChordNames \chords \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
1035 A complete list of modifiers, and other options for layout are in the
1036 reference manual section @ref{Chords}.
1039 When put together, chord names, lyrics and a melody form
1040 a lead sheet, for example,
1045 \context ChordNames \chords @{ @emph{chords} @}
1047 \notes @emph{the melody}
1048 \context Lyrics \lyrics @{ @emph{the text} @}
1056 \context ChordNames \chords { r8 c2:sus4 f }
1058 \notes \relative c' {
1061 \times 2/3 { f g g } \times 2/3 { g4-( a2-) } }
1062 \context Lyrics \lyrics { I want to break free __ }
1064 \paper{ raggedright = ##t }
1069 @node Listening to output
1070 @section Listening to output
1075 MIDI (Musical Instrument Digital Interface) is a standard for
1076 connecting and recording digital instruments. A MIDI file is like a
1077 tape recording of a MIDI instrument. The @code{\midi} block makes the
1078 music go to a MIDI file, so you can listen to the music you entered.
1079 It is great for checking the music: octaves that are off, or
1080 accidentals that were mistyped, stand out very much when listening to
1081 the musical transcription.
1083 @code{\midi} can be used in similarly to @code{\paper @{ @}}, for
1088 \midi @{ \tempo 4=72 @}
1093 Here, the tempo is specified using the @code{\tempo} command. In this
1094 case the tempo of quarter notes is set to 72 beats per minute. More
1095 information on auditory output is in the @ref{Sound} section in the
1102 Bibliographic information is entered in a separate block, the
1103 @code{\header} block. The name of the piece, its composer, etc. are
1104 entered as assignment within @code{\header @{ @dots{} @}}. For
1108 title = "Eight miniatures"
1109 composer = "Igor Stravinsky"
1110 tagline = "small is beautiful"
1113 \score @{ @dots{} @}
1116 @cindex bibliographic information
1122 When the file is processed by @code{ly2dvi}, the title and composer
1123 specified are printed above the music. The `tagline' is a short line
1124 printed at bottom of the last page, which normally says ``Lily was
1125 here, version @dots{}''. In the example above, it is replaced by the
1126 line ``small is beautiful.''
1128 Normally, the @code{\header} is put at the top of the file. However,
1129 for a document that contains multiple pieces (e.g. a etude book, or
1130 part with multiple movements), then the header can be put into the
1131 @code{\score} block as follows In this case, the name of each piece
1132 will be printed before each movement.
1135 @cindex Lily was here
1136 @cindex signature line
1141 title = "Eight miniatures"
1142 composer = "Igor Stravinsky"
1143 tagline = "small is beautiful"
1147 \header @{ piece = "Adagio" @}
1150 \header @{ piece = "Menuetto" @}
1154 More information on titling can be found in @ref{Invoking ly2dvi}.
1157 @node Single staff polyphony
1158 @section Single staff polyphony
1161 @cindex multiple voices
1162 @cindex voices, more -- on a staff
1164 When different melodic lines are combined on a single staff, these are
1165 printed as polyphonic voices: each voice has its own stems, slurs
1166 and beams, and the top voice has the stems up, while the bottom voice
1169 Entering such parts is done by entering each voice as a sequence (with
1170 @code{@{ .. @}}), and combing those simultaneously, separating the
1171 voices with @code{\\}:
1174 < @{ a4 g2 f4-~ f4 @} \\
1177 @lilypond[relative 1]
1178 \context Staff < { a4 g2 f4-~ f4 } \\
1182 For polyphonic typesetting spacer rests can also be convenient: these
1183 are rests that do not print. It is useful for filling up voices that
1184 temporarily do not play:
1186 < @{ a4 g2 f4-~ f4 @} \\
1189 @lilypond[relative 1]
1190 \context Staff < { a4 g2 f4-~ f4 } \\
1194 More features of polyphonic typesetting are in the notation manual
1198 @section Piano staffs
1200 @cindex staff switch, manual
1201 @cindex cross staff voice, manual
1202 @cindex @code{\translator}
1204 Piano music is always typeset in two staffs connected by a brace.
1205 Printing such a staff is done similar to the polyphonic example in
1208 < \context Staff = up @{ @dots{} @}
1209 \context Staff = down @{ @dots{} @}
1212 but now this entire expression must be interpreted as a
1215 \context PianoStaff < \context Staff @dots{} >
1218 Here is a full-fledged example:
1220 @lilypond[relative 0,fragment]
1222 < \context Staff = up {
1224 \context Staff = down {
1225 \clef bass c,, c' e c }
1229 More information on formatting piano music is in @ref{Piano music}.
1231 @node Setting variables
1232 @section Setting variables
1234 When the music is converted from notes to print, it is interpreted
1235 from left-to-right order, similar to what happens when we read
1236 music. During this step, context-sensitive information, such as the
1237 accidentals to print, and where barlines must be placed, are stored in
1238 variables. These variables are called @emph{translation properties}.
1239 The properties can also be manipulated from input files: for example,
1241 \property Staff.autoBeaming = ##f
1243 sets the property named @code{autoBeaming} in the current staff to
1244 @code{##f} which means `false'. This property controls whether beams
1245 are printed automatically:
1246 @lilypond[relative 1,fragment,verbatim]
1248 \property Staff.autoBeaming = ##f
1253 LilyPond includes a built-in programming language, namely, a dialect
1254 of Scheme. The argument to @code{\property}, @code{##f}, is an
1255 expression in that language. The first hash-mark signals that a piece
1256 of Scheme code follows. The second hash character is part of the
1257 boolean value true (@code{#t}). Values of other types may be
1260 @item a string, enclosed in double quotes, for example
1262 \property Staff.instrument = #"French Horn"
1264 @item a boolean: either @code{#t} or @code{#f}, for true and false
1267 \property Voice.autoBeaming = ##f
1268 \property Score.skipBars = ##t
1273 \property Score.currentBarNumber = #20
1276 @item a symbol, which is introduced by a quote character,
1278 \property Staff.crescendoSpanner = #'dashed-line
1281 @item a pair, which is also introduced by a quote character.
1282 The following statements set properties to the pairs (-7.5, 6) and
1283 (3, 4) respectively.
1286 \property Staff.minimumVerticalExtent = #'(-7.5 . 6)
1287 \property Staff.timeSignatureFraction = #'(3 . 4)
1293 There are many different properties, and not all of them are listed in
1294 this manual. However, the internal documentation lists them all in the
1295 @internalsref{All translation properties}, and almost all properties
1296 are demonstrated in one of the
1298 @uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
1306 @node Fine tuning layout
1307 @section Fine tuning layout
1309 Sometimes it is necessary to change music layout by hand. When music
1310 is formatted, layout objects are created for each symbol. For
1311 example, every clef and every note head is represented by a layout
1312 object. These layout objects also carry variables, which we call
1313 @emph{layout properties}. By changing these variables from their
1314 values, we can alter the look of a formatted score.
1316 @lilypond[verbatim,relative 0]
1318 \property Voice.Stem \override #'thickness = #3.0
1323 In the example shown here, the layout property @code{thickness} (a
1324 symbol) is set to 3 in the @code{Stem} layout objects of the current
1325 Voice. As a result, the notes following @code{\property} have thicker
1328 In most cases of manual overrides, only a single object must be
1329 changed. This can be achieved by prefix @code{\once} to the
1330 @code{\property} statement, i.e.,
1333 \once \property Voice.Stem \set #'thickness = #3.0
1336 @lilypond[relative 0]
1338 \once \property Voice.Stem \set #'thickness = #3.0
1343 Some overrides are so common that predefined commands are provided as
1344 a short cut. For example, @code{\slurUp} and @code{\stemDown}. These
1345 commands are described in the @ref{Notation manual}, under the
1346 sections for slurs and stems respectively.
1348 The exact tuning possibilities for each type of layout object are
1349 documented in the internal documentation of the respective
1350 object. However, many layout objects share properties, which can be
1351 used to apply generic tweaks. We mention a couple of these:
1354 @cindex @code{extra-offset}
1355 @item The @code{extra-offset} property
1356 moves around objects in the printout. The unit of these offsets are
1357 staff-spaces. The first number controls left-right movement; a
1358 positive number will move the object to the right. The second number
1359 controls up-down movement; a positive number will move it higher. The
1360 @code{extra-offset} is a low-level feature: the formatting engine is
1361 completely oblivious to these offsets.
1363 In the following example example, the second fingering is moved a
1364 little to the left, and 1.8 staff space downwards.
1366 @cindex setting object properties
1368 @lilypond[relative 1,verbatim]
1371 \once \property Voice.Fingering
1372 \set #'extra-offset = #'(-0.3 . -1.8)
1377 Setting the @code{transparent} property will make an object be
1378 printed in `invisible ink': the object is not printed, but all its
1379 other behavior is retained. The object still takes space, takes part
1380 in collisions, and slurs, ties and beams can be attached to it.
1382 @cindex transparent objects
1383 @cindex removing objects
1384 @cindex invisible objects
1385 The following example demonstrates how to connect different voices
1386 using ties. Normally ties only happen between notes of the same
1387 voice. By introducing a tie in a different voice, and blanking a stem
1388 in that voice, the tie appears to cross voices.
1390 @lilypond[fragment,relative 1]
1392 \once \property Voice.Stem \set #'transparent = ##t
1400 The @code{padding} property for objects with
1401 @code{side-position-interface} can be set to increase distance between
1402 symbols that are printed above or below notes. An example of the use
1403 of padding is in @ref{Constructing a tweak}.
1406 More specific overrides are also possible. The notation manual
1407 discusses in depth how to figure out these statements for yourself, in
1408 @ref{Tuning output}.
1410 @node Organizing larger pieces
1411 @section Organizing larger pieces
1413 When all of the elements discussed earlier are combined to produce
1414 larger files, the @code{\score} blocks get a lot bigger, because the
1415 music expressions are longer, and, in the case of polyphonic and/or
1416 orchestral pieces, more deeply nested.
1418 By using variables, also known as identifiers, it is possible to break
1419 up complex music expressions.
1420 An identifier is assigned as follows
1422 namedMusic = \notes @{ @dots{}
1425 The contents of the music expression @code{namedMusic}, can be used
1426 later by preceding the name with a backslash, i.e. @code{\namedMusic}.
1429 @lilypond[singleline,verbatim]
1438 The name of an identifier should only have alphabetic characters only,
1439 and no numbers, underscores or dashes. The assignment should be
1440 outside of the @code{\score} block.
1442 It is possible to use variables for many other types of objects in the
1447 aFivePaper = \paper @{ paperheight = 22.7 \cm @}
1449 Depending on its contents, the identifier can be used in different
1450 places. The following example uses the above variables:
1453 \notes @{ c4^\name @}
1461 More information on the possible uses of identifiers is in the
1462 technical manual, in @ref{Scheme datatypes}.
1465 @node An orchestral part
1466 @section An orchestral part
1468 In orchestral music, all notes are printed twice: both in a part for
1469 the musicians, and in a full score for the which is printed both in
1470 parts as in full score. Identifiers can be used to avoid double work:
1471 the music is entered once, and stored in an variables. The contents of
1472 that variable is then used to generate both the part and the score.
1474 It is convenient to define the notes in a special file, for example,
1475 suppose that the following is in @file{horn-music.ly}:
1477 hornNotes = \notes \relative c @{
1483 Then, an individual part is made by putting the following in a file
1485 \include "horn-music.ly"
1487 instrument = "Horn in F"
1490 \notes \transpose c' f \hornNotes
1493 The @code{\include} command substitutes the contents of the file at
1494 this position in the file, so that @code{hornNotes} is defined
1495 afterwards. Since the horn is tuned in F, the @code{\transpose}
1496 command is used. The code @code{\transpose c' f} indicates that the
1497 argument, being @code{\hornNotes} should be transposed by a fifth
1498 downwards: the @code{c'} becomes a @code{f}. The transposition can be
1499 seen in the following output:
1501 @lilypond[singleline]
1503 \notes \transpose c' f \notes \relative c' {
1510 In ensemble pieces, one of the voices often does not play for many
1511 measures. This is denoted by a special rest, the multi-measure
1512 rest. It is entered with a capital R, and followed by a duration (1
1513 for a whole note, 2 for a half note, etc.) By multiplying the
1514 duration, longer rests can be constructed. For example, the next rest
1515 takes 3 measures in 2/4 time.
1520 When printing the part, the following @code{skipBars} property must be
1521 set to false, to prevent the rest from being expanded in three one bar
1524 \property Score.skipBars = ##t
1527 The result would look like
1529 @lilypond[singleline]
1530 \score {\notes { \transpose c' f \relative c' { \time 2/4
1531 \property Score.skipBars = ##t
1533 r4 f8 a cis4 f e d } }}
1536 The score is made by combining all of the music in a @code{\score}
1537 block, assuming that the other voice is in @code{hornNotes}, in the
1538 file @file{horn-music.ly}:
1540 \include "fagot-music.ly"
1541 \include "horn-music.ly"
1545 \context Staff = hornStaff \hornNotes
1546 \context Staff = fagStaff \fagottoNotes
1550 This would lead to the following output:
1552 @lilypond[singleline]
1554 \notes \relative c \simultaneous {
1555 \context Staff = hornStaff { \time 2/4
1557 r4 f8 a cis4 f e d }
1558 \context Staff = fagStaff { \clef bass
1559 r4 d,8 f | gis4 c | b bes |
1560 a8 e f4 | g d | gis f }
1564 More in depth information is in the notation manual, in
1565 @ref{Orchestral music}.
1568 @node Integrating text and music
1569 @section Integrating text and music
1573 @cindex La@TeX{}, music in
1574 @cindex HTML, music in
1575 @cindex Texinfo, music in
1577 Sometimes you might want to use music examples in a text that you are
1578 writing (for example a musicological treatise, a songbook, or (like us)
1579 the LilyPond manual). You can make such texts by hand, simply by
1580 importing a PostScript figure into your word processor. However,
1581 there is an automated procedure to reduce the amount of work.
1583 If you use HTML, La@TeX{}, or Texinfo, you can mix text and LilyPond
1584 code. A script called @code{lilypond-book} will extract the music
1585 fragments, run LilyPond on them, and put back the resulting notation.
1586 This program is fully described in @ref{lilypond-book manual}. Here
1587 we show a small example. Since the example also contains explanatory
1588 text, we will not comment it further.
1591 \documentclass[a4paper]@{article@}
1594 In a lilypond-book document, you can freely mix music and text. For
1597 \score @{ \notes \relative c' @{
1598 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
1602 Notice that the music line length matches the margin settings of the
1605 If you have no \verb+\score+ block in the fragment,
1606 \texttt@{lilypond-book@} will supply one:
1612 In the example you see here, two things happened: a
1613 \verb+\score+ block was added, and the line width was set to natural
1614 length. You can specify many more options using \LaTeX style options
1617 \begin[verbatim,11pt,singleline,
1618 fragment,relative,intertext="hi there!"]@{lilypond@}
1622 The option \texttt@{verbatim@} prints the LilyPond code in addition to
1623 the graphical score, \texttt@{11pt@} selects the default music size,
1624 \texttt@{fragment@} adds a score block, \texttt@{relative@} uses
1625 relative mode for the fragment, and \texttt@{intertext@} specifies
1626 what to print between the \texttt@{verbatim@} code and the music.
1628 If you want to include large examples into the text, it may be more
1629 convenient to put the example in a separate file:
1631 \lilypondfile[printfilename]@{screech-boink.ly@}
1633 The \texttt@{printfilename@} option adds the file name to the output.
1638 Under Unix, you can view the results as follows.
1642 $ lilypond-book --outdir=out/ lilbook.tex
1643 lilypond-book (GNU LilyPond) 1.7.23
1644 Reading `input/tutorial/lilbook.tex'
1645 Reading `input/screech-boink6.ly'
1646 @var{lots of stuff deleted}
1647 Writing `out/lilbook.latex'
1649 $ latex lilbook.latex
1650 @var{lots of stuff deleted}
1654 Running lilypond-book and running latex creates a lot of temporary
1655 files, and you would not want those to clutter up your working
1656 directory. The @code{outdir} option to lilypond-book creates the
1657 temporary files in a separate subdirectory @file{out}.
1659 The result looks more or less like this:
1663 In a lilypond-book document, you can freely mix music and text. For
1667 \notes \relative c' {
1668 c2 g'2 \times 2/3 { f8 e d } c'2 g4
1676 Notice that the music line length matches the margin settings of the
1679 If you have no @code{\score} block in the fragment,
1680 @code{lilypond-book} will supply one:
1686 In the example you see here, a number of things happened: a
1687 @code{\score} block was added, and the line width was set to natural
1688 length. You can specify many more options using La@TeX{} style options
1691 @lilypond[verbatim,11pt,singleline,
1692 fragment,relative,intertext="hi there!"]
1696 The option @code{verbatim} also shows the LilyPond code, @code{11pt} selects
1697 the default music size, @code{fragment} adds a score block,
1698 @code{relative} uses relative mode for the fragment, and
1699 @code{intertext} specifies what to print between the
1700 @code{verbatim} code and the music.
1702 If you include large examples into the text, it may be more convenient
1703 to put the example in a separate file:
1705 @lilypondfile[printfilename]{screech-boink.ly}
1707 The @code{printfilename} option adds the file name to the output.