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}'':
374 \property Score.timing = ##f
375 \property Staff.Clef = \turnOff
376 \property Staff.TimeSignature = \turnOff
383 Rests are described in full detail in @ref{Rests}.
386 @c Tim wants to move this quotes example just before the: quotes-do not-work
387 @c score, but we'd need to remove quotes from the other two (key and
390 @c better to have this just before the `octaves are bad' snipped
391 @c but we'd need to remove the ', from \key and tie
392 To raise a note by an octave, add a high quote @code{'} (apostrophe) to
393 the note name, to lower a note one octave, add a ``low quote'' @code{,}
394 (a comma). Middle C is @code{c'}:
398 c'4 c'' c''' \clef bass c c,
402 \property Score.timing = ##f
403 \property Staff.TimeSignature = \turnOff
404 c'4 c'' c''' \clef bass c c,
409 A tie is created by adding a tilde ``@code{~}'' to the first note
412 @lilypond[fragment,verbatim]
417 A tie is different from a slur. A tie simply makes the first note
418 sound longer, and can only be used on pairs of notes with the same
419 pitch. Slurs indicate the articulations of notes, and can be used on
420 larger groups of notes. Slurs and ties are also nested in practice:
421 @lilypond[fragment, relative=1]
422 c2-~-( c8 fis fis4 ~ fis2 g2-)
425 The notation manual discusses ties in @ref{Ties}.
427 The key signature is set with the command ``@code{\key}'', followed by
428 a pitch and @code{\major} or @code{\minor}:
438 \property Staff.TimeSignature = \turnOff
448 @c bit on the long/complex/scary taste
449 @c cheating a bit: two lines makes for a friendlier look
450 This example shows notes, ties, octave marks, and rests in action.
459 r4 r8 d''8 cis''4 e''
461 cis''4 cis''8 cis'' bis'4 d''8 cis''-~
474 r4 r8 d''8 cis''4 e''
476 cis''4 cis''8 cis'' bis'4 d''8 cis''-~
479 \paper { linewidth = 50*\staffspace }
485 There are some interesting points to note in this example.
486 Accidentals (sharps and flats) do not have to be marked explicitly:
487 you just enter the note name, and an accidental is printed
488 automatically, only when necessary. Bar lines and beams are drawn
489 automatically. Line breaks are calculated automatically; it does not
490 matter where the lines breaks are in the source file. Finally, the
491 order of time, key and clef changes is not relevant: in the printout,
492 these are ordered using standard notation conventions.
494 The example also indicates that a piece of music written in a high
495 register needs lots of quotes. This makes the input less readable,
496 and is also a potential source of errors.
498 The solution is to use ``relative octave'' mode. In practice, this is
499 the most convenient way to copy existing music. To use relative mode,
500 add @code{\relative} before the piece of music. You must also give a
501 note from which relative starts, in this case @code{c''}. If you do
502 not use octavation quotes (i.e. do not add ' or , after a note),
503 relative mode chooses the note that is closest to the previous one.
504 @c do not use commas or quotes in this sentence
505 For example: @code{c f} goes up; @code{c g} goes down:
515 \property Score.timing = ##f
516 \property Staff.TimeSignature = \turnOff
525 Since most music has small intervals, in relative mode pieces can be
526 written almost without using octavation quotes.
528 @c needed better, maybe even redundant explanation
529 @c added another example below.
530 @c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
531 @c in eerste instantie drong het `relative' niet door zonder extra uitleg.
532 Larger intervals are made by adding octavation quotes. Quotes or
533 commas do not determine the absolute height of a note; the height of a
534 note is relative to the previous one.
535 @c do not use commas or quotes in this sentence
536 For example: @code{c f,} goes down; @code{f, f} are both the same;
537 @code{c' c} are the same; and @code{c g'} goes up:
547 \property Score.timing = ##f
548 \property Staff.TimeSignature = \turnOff
557 Here is an example of the difference between relative mode and
558 ``normal'' (non-relative) mode:
569 \property Score.timing = ##f
570 \property Staff.TimeSignature = \turnOff
586 \property Score.timing = ##f
587 \property Staff.TimeSignature = \turnOff
594 A slur is drawn across many notes, and indicates bound articulation
595 (legato). The starting note and ending note are marked with a
596 ``@code{(}'' and a ``@code{)}'' respectively:
599 @lilypond[fragment,relative 1, verbatim]
600 d4-( c16-)-( cis d e c cis d e-)-( d4-)
605 If you need two slurs at the same time (one for articulation, one for
606 phrasing), you can also make a phrasing slur with @code{\(} and
611 @c fragment of 1st hrn in Adams' The Chairman Dances, with creative
612 @c chromatic thing pasted in front. (admittedly the original does not
613 @c have a phrasing slur. The problem is that we do not want the slur
614 @c and the Phrasing slur to collide. We are trying to make a good
618 @lilypond[fragment,relative 1, verbatim]
619 a8-(-\( ais b c-) cis2 b'2 a4 cis, c-\)
624 Beams are drawn automatically, but if you do not like where they are
625 put, they can be entered by hand. Mark the first note to be beamed
626 with @code{[} and the last one with @code{]}:
628 @lilypond[fragment,relative 1, verbatim]
629 a8-[ ais-] d-[ es r d-]
635 * Combining music into compound expressions::
636 * Adding articulation marks to notes ::
637 * More basic rhythms::
638 * Commenting input files::
641 @node Combining music into compound expressions
642 @subsection Combining music into compound expressions
644 To print more than one staff, each piece of music that makes up a staff
645 is marked by adding @code{\context Staff} before it. These
646 @code{Staff}'s are then grouped inside @code{\simultaneous @{} and @code{@}}, as is
650 @lilypond[fragment,verbatim]
652 \context Staff = staffA { \clef violin c'' }
653 \context Staff = staffB { \clef bass c }
658 In this example, @code{staffA} and @code{staffB} are names that are
659 given to the staves. It does not matter what names you give, as long
660 as each staff has a different name. If you give them the same name,
661 they are assumed to belong on the same staff, and will be printed like
662 that. @code{\simultaneous } indicates that both fragments happen at
663 the same time, and must be printed stacked vertically. The notation
664 @code{< .. >} can also be used as a shorthand for @code{\simultaneous
669 We can now typeset a melody with two staves:
672 @lilypond[verbatim,singleline]
675 < \context Staff = staffA {
679 e2-( d4 c2 b4 a8-[ a-]
680 b-[ b-] g-[ g-] a2.-) }
682 \context Staff = staffB {
693 The example shows how small chunks of music, for example the notes
694 @code{c2}, @code{e4}, etc. of the second staff, are combined to form a
695 larger chunk by enclosing it in braces. Again, a larger chunk is
696 formed by prefix @code{\context Staff} to it, and that chunk is
697 combined with @code{< >}. This mechanism is similar with mathematical
698 formulas: in a formula, a so-called expression is formed by combining
699 simpler expressions into larger expressions. For example,
708 ((1 + 2) * 3) / (4 * 5)
710 is a sequence of expressions, where each expression is contained in
711 the next one. The simplest expressions are numbers and operators
712 (like +, * and /). Parentheses are used to group expressions. In
713 LilyPond input, a similar mechanism is used. Here, the simplest
714 expressions are notes and rests. By enclosing expressions in @code{<
715 >} and @code{@{ @}}, more complex music is formed. The @code{\context}
716 also forms new expressions; it is prepended to a music expression.
718 When spreading expressions over multiple lines, it is customary to use
719 an indent that indicates the nesting level. Formatting music like this
720 eases reading, and helps you insert the right amount of closing
721 braces at the end of an expression. For example
735 @node Adding articulation marks to notes
736 @subsection Adding articulation marks to notes
738 Common accents can be added to a note using @code{-.}, @code{--}, @code{->}:
740 @lilypond[verbatim,relative 1]
746 Similarly, fingering indications can be added to a note using @code{-}
747 and the digit to be printed.
748 @lilypond[verbatim,relative 1]
753 Dynamic signs are made by adding the markings to the note:
755 @lilypond[verbatim,relative 1]
761 Crescendi and decrescendi are started with the commands @code{\<} and
762 @code{\>}. The command @code{\!} finishes a crescendo on the note it
765 @lilypond[verbatim,relative 1]
766 c2-\< c2-\!-\ff c2-\> c2-\!
771 Chords can be made by
772 surrounding pitches with @code{<<} and @code{>}>:
774 @lilypond[relative 0, fragment,verbatim]
775 r4 <<c e g>>4 <<c f a>>8
781 You can combine beams and ties with chords. Beam and tie markings
782 must be placed outside the chord markers:
784 @lilypond[relative 0, fragment,verbatim]
785 r4 <<c e g>>8-[ <<c f a>>-]-~ <<c f a>>
791 r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-)
793 @lilypond[relative 0, fragment]
795 r4 <<c e g>>8-\>-( <<c e g>> <<c e g>> <<c f a>>8-\!-)
801 @node More basic rhythms
802 @subsection More basic rhythms
804 A pickup (or upstep) is entered with the keyword @code{\partial}. It
805 is followed by a duration: @code{\partial 4} is a quarter note upstep
806 and @code{\partial 8} an eighth note.
807 @lilypond[relative 1,verbatim,fragment]
812 Tuplets are made with the @code{\times} keyword. It takes two
813 arguments: a fraction and a piece of music. The duration of the piece
814 of music is multiplied by the fraction. Triplets make notes occupy
815 2/3 of their notated duration, so a triplet has 2/3 as its fraction.
817 @lilypond[relative 0,verbatim,fragment]
818 \times 2/3 { f8 g a }
822 Grace notes are also made by prefixing a note, or a set of notes with
823 a keyword. In this case, the keyword is @code{\grace}.
824 @lilypond[relative 1, verbatim,fragment]
826 \grace { d16-( e } d4-)
830 More information on the use of grace notes is in @ref{Grace notes}.
833 @node Commenting input files
834 @subsection Commenting input files
836 Comments are pieces of the input that are ignored. There are two
837 types of comments. A line comments are introduced by @code{%}: after
838 that, the rest of that line is ignored. Block comments span larger
839 sections of input. Anything that is enclosed in @code{%@{} and
840 @code{%@}} is ignored too. The following fragment shows possible uses
844 % notes for twinkle twinkle follow:
849 This line, and the notes below
850 are ignored, since they are in a
860 @node Printing lyrics
861 @section Printing lyrics
864 Lyrics are entered by separating each syllable with a space, and
865 surrounding them with @code{\lyrics @{ @dots{} @}}, for example
867 \lyrics @{ I want to break free @}
870 Like notes, lyrics are also a form of music, but they must not be
871 printed on a staff, which is the default way to print music. To print
872 them as lyrics, they must be marked with @code{ \context Lyrics}:
874 \context Lyrics \lyrics @{ I want to break free @}
876 The melody for this song is as follows
878 @lilypond[fragment,relative=1]
881 \times 2/3 { f4 g g } \times 2/3 { g4-( a2-) }
884 The lyrics can be set to these notes, combining both with the
885 @code{\addlyrics} keyword:
889 \context Lyrics @dots{}
893 @lilypond[verbatim,linewidth=6.0cm]
900 \times 2/3 { f g g } \times 2/3 { g4-( a2-) }
902 \context Lyrics \lyrics { I want to break free }
908 This melody ends on a @rglos{melisma}, a single syllable (``free'')
909 sung to more than one note. This is indicated with a @emph{extender
910 line}. It is entered as two underscores, i.e.,
912 \lyrics @{ I want to break free __ @}
921 \times 2/3 { f g g } \times 2/3 { g4-( a2-) }
923 %% ugh, this is to deal with bugs in the extender implementation
927 \context Lyrics \lyrics { I want to break free __ }
929 \paper{ linewidth = 9.0 \cm }
933 Similarly, hyphens between words can be entered as two dashes,
934 resulting in a centered hyphen between two syllables.
936 Twin -- kle twin -- kle
938 @lilypond[singleline]
940 \addlyrics \notes \relative f' { \time 2/4
942 \context Lyrics \lyrics { Twin -- kle twin -- kle
944 \paper { linewidth = 6.0 \cm }
949 More options, like putting multiple lines of lyrics below a melody are
950 discussed in @ref{Vocal music}.
954 TODO: discuss contexts.
958 @section A lead sheet
960 In popular music, it is common to denote accompaniment as chord-names.
961 Using them in LilyPond has two parts, just like lyrics: entering the
962 chords (with @code{\chords}), and printing them (with @code{\context
965 Chord names are entered by starting chords mode (with @code{\chords}).
966 In chords mode, you can enter chords with a letter (indicating the
967 root of the chord), and a durations following that.
970 \chords { c2 f4. g8 }
974 The result of @code{\chords} is a list of chords, and is equivalent
975 to entering chords with @code{<<@dots{}>>}.
977 Other chords can be created by adding modifiers, after a colon. The
978 following example shows a few common modifiers
981 \chords { c2 f4:m g4:maj7 gis1:dim7 }
984 Printing chords is done by adding @code{\context ChordNames}
985 before the chords thus entered:
988 \context ChordNames \chords \chords { c2 f4.:m g4.:maj7 gis8:dim7 }
991 A complete list of modifiers, and other options for layout are in the
992 reference manual section @ref{Chords}.
995 When put together, chord names, lyrics and a melody form
996 a lead sheet, for example,
1001 \context ChordNames \chords @{ @emph{chords} @}
1003 \notes @emph{the melody}
1004 \context Lyrics \lyrics @{ @emph{the text} @}
1012 \context ChordNames \chords { r8 c2:sus4 f }
1014 \notes \relative c' {
1017 \times 2/3 { f g g } \times 2/3 { g4-( a2-) } }
1018 \context Lyrics \lyrics { I want to break free __ }
1020 \paper{ raggedright = ##t }
1025 @node Listening to output
1026 @section Listening to output
1028 MIDI (Musical Instrument Digital Interface) is a standard for
1029 connecting and recording digital instruments. A MIDI file is like a
1030 tape recording of a MIDI instrument. The @code{\midi} block makes the
1031 music go to a MIDI file, so you can listen to the music you entered.
1032 It is great for checking the music: octaves that are off, or
1033 accidentals that were mistyped, stand out very much when listening to
1034 the musical transcription.
1036 @code{\midi} can be used in similarly to @code{\paper @{ @}}, for
1041 \midi @{ \tempo 4=72 @}
1046 Here, the tempo is specified using the @code{\tempo} command. In this
1047 case the tempo of quarter notes is set to 72 beats per minute. More
1048 information on auditory output is in the @ref{Sound} section in the
1055 Bibliographic information is entered in a separate block, the
1056 @code{\header} block. The name of the piece, its composer, etc. are
1057 entered as assignment within @code{\header @{ @dots{} @}}. For
1061 title = "Eight miniatures"
1062 composer = "Igor Stravinsky"
1063 tagline = "small is beautiful"
1066 \score @{ @dots{} @}
1069 @cindex bibliographic information
1075 When the file is processed by @code{ly2dvi}, the title and composer
1076 specified are printed above the music. The `tagline' is a short line
1077 printed at bottom of the last page, which normally says ``Lily was
1078 here, version @dots{}''. In the example above, it is replaced by the
1079 line ``small is beautiful.''
1081 Normally, the @code{\header} is put at the top of the file. However,
1082 for a document that contains multiple pieces (e.g. a etude book, or
1083 part with multiple movements), then the header can be put into the
1084 @code{\score} block as follows In this case, the name of each piece
1085 will be printed before each movement.
1088 @cindex Lily was here
1089 @cindex signature line
1094 title = "Eight miniatures"
1095 composer = "Igor Stravinsky"
1096 tagline = "small is beautiful"
1100 \header @{ piece = "Adagio" @}
1103 \header @{ piece = "Menuetto" @}
1107 More information on titling can be found in @ref{Invoking ly2dvi}.
1110 @node Single staff polyphony
1111 @section Single staff polyphony
1113 When different melodic lines are combined on a single staff, these are
1114 printed as polyphonic voices: each voice has its own stems, slurs
1115 and beams, and the top voice has the stems up, while the bottom voice
1118 Entering such parts is done by entering each voice as a sequence (with
1119 @code{@{ .. @}}), and combing those simultaneously, separating the
1120 voices with @code{\\}:
1123 < @{ a4 g2 f4-~ f4 @} \\
1126 @lilypond[relative 1]
1127 \context Staff < { a4 g2 f4-~ f4 } \\
1131 For polyphonic typesetting spacer rests can also be convenient: these
1132 are rests that do not print. It is useful for filling up voices that
1133 temporarily do not play:
1135 < @{ a4 g2 f4-~ f4 @} \\
1138 @lilypond[relative 1]
1139 \context Staff < { a4 g2 f4-~ f4 } \\
1143 More features of polyphonic typesetting are in the notation manual
1147 @section Piano staffs
1149 @cindex staff switch, manual
1150 @cindex cross staff voice, manual
1151 @cindex @code{\translator}
1153 Piano music is always typeset in two staffs connected by a brace.
1154 Printing such a staff is done similar to the polyphonic example in
1157 < \context Staff = up @{ @dots{} @}
1158 \context Staff = down @{ @dots{} @}
1161 but now this entire expression must be interpreted as a
1164 \context PianoStaff < \context Staff @dots{} >
1167 Here is a full-fledged example:
1169 @lilypond[relative 0,fragment]
1171 < \context Staff = up {
1173 \context Staff = down {
1174 \clef bass c, c' e c }
1178 More information on formatting piano music is in @ref{Piano music}.
1180 @node Setting variables
1181 @section Setting variables
1183 When the music is converted from notes to print, it is interpreted
1184 from left-to-right order, similar to what happens when we read
1185 music. During this step, context-sensitive information, such as the
1186 accidentals to print, and where barlines must be placed, are stored in
1187 variables. These variables are called @emph{translation properties}.
1188 The properties can also be manipulated from input files: for example,
1190 \property Staff.autoBeaming = ##f
1192 sets the property named @code{autoBeaming} in the current staff to
1193 @code{##f} which means `false'. This property controls whether beams
1194 are printed automatically:
1195 @lilypond[relative 1,fragment,verbatim]
1197 \property Staff.autoBeaming = ##f
1202 LilyPond includes a built-in programming language, namely, a dialect
1203 of Scheme. The argument to @code{\property}, @code{##f}, is an
1204 expression in that language. The first hash-mark signals that a piece
1205 of Scheme code follows. The second hash character is part of the
1206 boolean value true (@code{#t}). Values of other types may be
1209 @item a string, enclosed in double quotes, for example
1211 \property Staff.instrument = #"French Horn"
1213 @item a boolean: either @code{#t} or @code{#f}, for true and false
1216 \property Voice.autoBeaming = ##f
1217 \property Score.skipBars = ##t
1222 \property Score.currentBarNumber = #20
1225 @item a symbol, which is introduced by a quote character,
1227 \property Staff.crescendoSpanner = #'dashed-line
1230 @item a pair, which is also introduced by a quote character.
1231 The following statements set properties to the pairs (-7.5, 6) and
1232 (3, 4) respectively.
1235 \property Staff.minimumVerticalExtent = #'(-7.5 . 6)
1236 \property Staff.timeSignatureFraction = #'(3 . 4)
1242 There are many different properties, and not all of them are listed in
1243 this manual. However, the internal documentation lists them all in the
1244 @internalsref{All translation properties}, and almost all properties
1245 are demonstrated in one of the
1247 @uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
1255 @node Fine tuning layout
1256 @section Fine tuning layout
1258 Sometimes it is necessary to change music layout by hand. When music
1259 is formatted, layout objects are created for each symbol. For
1260 example, every clef and every note head is represented by a layout
1261 object. These layout objects also carry variables, which we call
1262 @emph{layout properties}. By changing these variables from their
1263 values, we can alter the look of a formatted score.
1265 @lilypond[verbatim,relative 0]
1267 \property Voice.Stem \override #'thickness = #3.0
1272 In the example shown here, the layout property @code{thickness} (a
1273 symbol) is set to 3 in the @code{Stem} layout objects of the current
1274 Voice. As a result, the notes following @code{\property} have thicker
1277 In most cases of manual overrides, only a single object must be
1278 changed. This can be achieved by prefix @code{\once} to the
1279 @code{\property} statement, i.e.,
1282 \once \property Voice.Stem \set #'thickness = #3.0
1285 @lilypond[relative 0]
1287 \once \property Voice.Stem \set #'thickness = #3.0
1292 Some overrides are so common that predefined commands are provided as
1293 a short cut. For example, @code{\slurUp} and @code{\stemDown}. These
1294 commands are described in the @ref{Notation manual}, under the
1295 sections for slurs and stems respectively.
1297 The exact tuning possibilities for each type of layout object are
1298 documented in the internal documentation of the respective
1299 object. However, many layout objects share properties, which can be
1300 used to apply generic tweaks. We mention a couple of these:
1303 @cindex @code{extra-offset}
1304 @item The @code{extra-offset} property
1305 moves around objects in the printout. The unit of these offsets are
1306 staff-spaces. The first number controls left-right movement; a
1307 positive number will move the object to the right. The second number
1308 controls up-down movement; a positive number will move it higher. The
1309 @code{extra-offset} is a low-level feature: the formatting engine is
1310 completely oblivious to these offsets.
1312 In the following example example, the second fingering is moved a
1313 little to the left, and 1.8 staff space downwards.
1315 @cindex setting object properties
1317 @lilypond[relative 1,verbatim]
1320 \once \property Voice.Fingering
1321 \set #'extra-offset = #'(-0.3 . -1.8)
1326 Setting the @code{transparent} property will make an object be
1327 printed in `invisible ink': the object is not printed, but all its
1328 other behavior is retained. The object still takes space, takes part
1329 in collisions, and slurs, ties and beams can be attached to it.
1331 @cindex transparent objects
1332 @cindex removing objects
1333 @cindex invisible objects
1334 The following example demonstrates how to connect different voices
1335 using ties. Normally ties only happen between notes of the same
1336 voice. By introducing a tie in a different voice, and blanking a stem
1337 in that voice, the tie appears to cross voices.
1339 @lilypond[fragment,relative 1]
1341 \once \property Voice.Stem \set #'transparent = ##t
1349 The @code{padding} property for objects with
1350 @code{side-position-interface} can be set to increase distance between
1351 symbols that are printed above or below notes. An example of the use
1352 of padding is in @ref{Constructing a tweak}.
1355 More specific overrides are also possible. The notation manual
1356 discusses in depth how to figure out these statements for yourself, in
1357 @ref{Tuning output}.
1359 @node Organizing larger pieces
1360 @section Organizing larger pieces
1362 When all of the elements discussed earlier are combined to produce
1363 larger files, the @code{\score} blocks get a lot bigger, because the
1364 music expressions are longer, and, in the case of polyphonic and/or
1365 orchestral pieces, more deeply nested.
1367 By using variables, also known as identifiers, it is possible to break
1368 up complex music expressions.
1369 An identifier is assigned as follows
1371 namedMusic = \notes @{ @dots{}
1374 The contents of the music expression @code{namedMusic}, can be used
1375 later by preceding the name with a backslash, i.e. @code{\namedMusic}.
1378 @lilypond[singleline,verbatim]
1387 The name of an identifier should only have alphabetic characters only,
1388 and no numbers, underscores or dashes. The assignment should be
1389 outside of the @code{\score} block.
1391 It is possible to use variables for many other types of objects in the
1396 aFivePaper = \paper @{ paperheight = 22.7 \cm @}
1398 Depending on its contents, the identifier can be used in different
1399 places. The following example uses the above variables:
1402 \notes @{ c4^\name @}
1410 More information on the possible uses of identifiers is in the
1411 technical manual, in @ref{Scheme datatypes}.
1414 @node An orchestral part
1415 @section An orchestral part
1417 In orchestral music, all notes are printed twice: both in a part for
1418 the musicians, and in a full score for the which is printed both in
1419 parts as in full score. Identifiers can be used to avoid double work:
1420 the music is entered once, and stored in an variables. The contents of
1421 that variable is then used to generate both the part and the score.
1423 It is convenient to define the notes in a special file, for example,
1424 suppose that the following is in @file{horn-music.ly}:
1426 hornNotes = \notes \relative c @{
1432 Then, an individual part is made by putting the following in a file
1434 \include "horn-music.ly"
1436 instrument = "Horn in F"
1439 \notes \transpose c' f \hornNotes
1442 The @code{\include} command substitutes the contents of the file at
1443 this position in the file, so that @code{hornNotes} is defined
1444 afterwards. Since the horn is tuned in F, the @code{\transpose}
1445 command is used. The code @code{\transpose c' f} indicates that the
1446 argument, being @code{\hornNotes} should be transposed by a fifth
1447 downwards: the @code{c'} becomes a @code{f}. The transposition can be
1448 seen in the following output:
1450 @lilypond[singleline]
1452 \notes \transpose c' f \notes \relative c' {
1459 In ensemble pieces, one of the voices often does not play for many
1460 measures. This is denoted by a special rest, the multi-measure
1461 rest. It is entered with a capital R, and followed by a duration (1
1462 for a whole note, 2 for a half note, etc.) By multiplying the
1463 duration, longer rests can be constructed. For example, the next rest
1464 takes 3 measures in 2/4 time.
1469 When printing the part, the following @code{skipBars} property must be
1470 set to false, to prevent the rest from being expanded in three one bar
1473 \property Score.skipBars = ##t
1476 The result would look like
1478 @lilypond[singleline]
1479 \score {\notes { \transpose c' f \relative c' { \time 2/4
1480 \property Score.skipBars = ##t
1482 r4 f8 a cis4 f e d } }}
1485 The score is made by combining all of the music in a @code{\score}
1486 block, assuming that the other voice is in @code{hornNotes}, in the
1487 file @file{horn-music.ly}:
1489 \include "fagot-music.ly"
1490 \include "horn-music.ly"
1494 \context Staff = hornStaff \hornNotes
1495 \context Staff = fagStaff \fagottoNotes
1499 This would lead to the following output:
1501 @lilypond[singleline]
1503 \notes \relative c \simultaneous {
1504 \context Staff = hornStaff { \time 2/4
1506 r4 f8 a cis4 f e d }
1507 \context Staff = fagStaff { \clef bass
1508 r4 d,8 f | gis4 c | b bes |
1509 a8 e f4 | g d | gis f }
1513 More in depth information is in the notation manual, in
1514 @ref{Orchestral music}.
1517 @node Integrating text and music
1518 @section Integrating text and music
1522 @cindex La@TeX{}, music in
1523 @cindex HTML, music in
1524 @cindex Texinfo, music in
1526 Sometimes you might want to use music examples in a text that you are
1527 writing (for example a musicological treatise, a songbook, or (like us)
1528 the LilyPond manual). You can make such texts by hand, simply by
1529 importing a PostScript figure into your word processor. However,
1530 there is an automated procedure to reduce the amount of work.
1532 If you use HTML, La@TeX{}, or Texinfo, you can mix text and LilyPond
1533 code. A script called @code{lilypond-book} will extract the music
1534 fragments, run LilyPond on them, and put back the resulting notation.
1535 This program is fully described in @ref{lilypond-book manual}. Here
1536 we show a small example. Since the example also contains explanatory
1537 text, we will not comment it further.
1540 \documentclass[a4paper]@{article@}
1543 In a lilypond-book document, you can freely mix music and text. For
1546 \score @{ \notes \relative c' @{
1547 c2 g'2 \times 2/3 @{ f8 e d @} c'2 g4
1551 Notice that the music line length matches the margin settings of the
1554 If you have no \verb+\score+ block in the fragment,
1555 \texttt@{lilypond-book@} will supply one:
1561 In the example you see here, two things happened: a
1562 \verb+\score+ block was added, and the line width was set to natural
1563 length. You can specify many more options using \LaTeX style options
1566 \begin[verbatim,11pt,singleline,
1567 fragment,relative,intertext="hi there!"]@{lilypond@}
1571 The option \texttt@{verbatim@} prints the LilyPond code in addition to
1572 the graphical score, \texttt@{11pt@} selects the default music size,
1573 \texttt@{fragment@} adds a score block, \texttt@{relative@} uses
1574 relative mode for the fragment, and \texttt@{intertext@} specifies
1575 what to print between the \texttt@{verbatim@} code and the music.
1577 If you want to include large examples into the text, it may be more
1578 convenient to put the example in a separate file:
1580 \lilypondfile[printfilename]@{screech-boink.ly@}
1582 The \texttt@{printfilename@} option adds the file name to the output.
1587 Under Unix, you can view the results as follows.
1591 $ lilypond-book --outdir=out/ lilbook.tex
1592 lilypond-book (GNU LilyPond) 1.7.23
1593 Reading `input/tutorial/lilbook.tex'
1594 Reading `input/screech-boink6.ly'
1595 @var{lots of stuff deleted}
1596 Writing `out/lilbook.latex'
1598 $ latex lilbook.latex
1599 @var{lots of stuff deleted}
1603 Running lilypond-book and running latex creates a lot of temporary
1604 files, and you would not want those to clutter up your working
1605 directory. The @code{outdir} option to lilypond-book creates the
1606 temporary files in a separate subdirectory @file{out}.
1608 The result looks more or less like this:
1612 In a lilypond-book document, you can freely mix music and text. For
1616 \notes \relative c' {
1617 c2 g'2 \times 2/3 { f8 e d } c'2 g4
1625 Notice that the music line length matches the margin settings of the
1628 If you have no @code{\score} block in the fragment,
1629 @code{lilypond-book} will supply one:
1635 In the example you see here, a number of things happened: a
1636 @code{\score} block was added, and the line width was set to natural
1637 length. You can specify many more options using La@TeX{} style options
1640 @lilypond[verbatim,11pt,singleline,
1641 fragment,relative,intertext="hi there!"]
1645 The option @code{verbatim} also shows the LilyPond code, @code{11pt} selects
1646 the default music size, @code{fragment} adds a score block,
1647 @code{relative} uses relative mode for the fragment, and
1648 @code{intertext} specifies what to print between the
1649 @code{verbatim} code and the music.
1651 If you include large examples into the text, it may be more convenient
1652 to put the example in a separate file:
1654 @lilypondfile[printfilename]{screech-boink.ly}
1656 The @code{printfilename} option adds the file name to the output.