1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
4 @c A menu is needed before every deeper *section nesting of @node's; run
5 @c M-x texinfo-all-menus-update
6 @c to automatically fill in these menus before saving changes
11 This section deals with general lilypond issues, rather than
16 * A single music expression::
17 * Titles and headers::
20 * Multiple movements::
22 * Displaying LilyPond notation::
30 The main format of input for LilyPond are text files. By convention,
31 these files end with ``@code{.ly}''.
34 * File structure (introduction)::
36 * Including LilyPond files::
41 @node File structure (introduction)
42 @subsection File structure (introduction)
44 A basic example of a lilypond input file is
49 @{ @} % this is a single music expression;
50 % all the music goes in here.
58 There are many variations of this basic pattern, but this
59 example serves as a useful starting place.
61 The major part of this manual is concerned with entering various
62 forms of music in LilyPond. However, many music expressions are not
63 valid input on their own, for example, a @code{.ly} file containing
70 will result in a parsing error. Instead, music should be inside other
71 expressions, which may be put in a file by themselves. Such
72 expressions are called toplevel expressions. The next section enumerates
77 @subsection File structure
79 A @code{.ly} file contains any number of toplevel expressions, where a
80 toplevel expression is one of the following
84 An output definition, such as @code{\paper}, @code{\midi}, and
85 @code{\layout}. Such a definition at the toplevel changes the default
86 settings for the block entered.
89 A direct scheme expression, such as
90 @code{#(set-default-paper-size "a7" 'landscape)} or
91 @code{#(ly:set-option 'point-and-click #f)}.
94 A @code{\header} block. This sets the global header block. This
95 is the block containing the definitions for book-wide settings, like
99 An @code{\addquote} statement. See @ref{Quoting other voices}
100 for more information.
103 A @code{\score} block. This score will be collected with other
104 toplevel scores, and combined as a single @code{\book}.
106 This behavior can be changed by setting the variable
107 @code{toplevel-score-handler} at toplevel. The default handler is
108 defined in the init file @file{scm/@/lily@/.scm}.
110 The @code{\score} must begin with a music expression, and may
111 contain only one music expression.
114 A @code{\book} block logically combines multiple movements
115 (i.e., multiple @code{\score} blocks) in one document. If there are
116 a number of @code{\scores}, a single output file will be created
117 in which all movements are concatenated.
119 This behavior can be changed by setting the variable
120 @code{toplevel-book-handler} at toplevel. The default handler is
121 defined in the init file @file{scm/@/lily@/.scm}.
124 A compound music expression, such as
129 This will add the piece in a @code{\score} and format it in a
130 single book together with all other toplevel @code{\score}s and music
131 expressions. In other words, a file containing only the above
132 music expression will be translated into
148 This behavior can be changed by setting the variable
149 @code{toplevel-music-handler} at toplevel. The default handler is
150 defined in the init file @file{scm/@/lily@/.scm}.
153 A markup text, a verse for example
156 2. The first line verse two.
160 Markup texts are rendered above, between or below the scores or music
161 expressions, wherever they appear.
164 An identifier, such as
169 This can be used later on in the file by entering @code{\foo}. The
170 name of an identifier should have alphabetic characters only; no
171 numbers, underscores or dashes.
175 The following example shows three things that may be entered at
180 % movements are non-justified by default
192 At any point in a file, any of the following lexical instructions can
196 @item @code{\version}
197 @item @code{\include}
198 @item @code{\renameinput}
202 @node Including LilyPond files
203 @subsection Including LilyPond files
206 @cindex including files
208 A large project may be split up into separate files. To refer to another
212 \include "otherfile.ly"
215 The line @code{\include "file.ly"} is equivalent to pasting the contents
216 of file.ly into the current file at the place where you have the
217 \include. For example, for a large project you might write separate files
218 for each instrument part and create a ``full score'' file which brings
219 together the individual instrument files.
221 The initialization of LilyPond is done in a number of files that are
222 included by default when you start the program, normally transparent to the
223 user. Run lilypond --verbose to see a list of paths and files that Lily
226 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
227 VERSION is in the form ``2.6.1'') are on the path and available to
228 @code{\include}. Files in the
229 current working directory are available to \include, but a file of the same
230 name in LilyPond's installation takes precedence. Files are
231 available to \include from directories in the search path specified as an
232 option when invoking @code{lilypond --include=DIR} which adds DIR to the
235 The @code{\include} statement can use full path information, but with the Unix
236 convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example,
237 if @file{stuff.ly} is located one directory higher than the current working
241 \include "../stuff.ly"
246 @subsection Text encoding
248 LilyPond uses the Pango library to format multi-lingual texts, and
249 does not perform any input-encoding conversions. This means that any
250 text, be it title, lyric text, or musical instruction containing
251 non-ASCII characters, must be utf-8. The easiest way to enter such text is
252 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
253 popular modern editors have utf-8 support, for example, vim, Emacs,
256 Depending on the fonts installed, the following fragment shows Hebrew
263 @lilypondfile[fontload]{utf-8.ly}
265 The @TeX{} backend does not handle encoding specially at all. Strings
266 in the input are put in the output as-is. Extents of text items in the
267 @TeX{} backend, are determined by reading a file created via the
268 @file{texstr} backend,
271 lilypond -b texstr input/les-nereides.ly
272 latex les-nereides.texstr
275 The last command produces @file{les-nereides.textmetrics}, which is
276 read when you execute
279 lilypond -b tex input/les-nereides.ly
282 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
283 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
284 interpreting non-ASCII strings.
286 To use a Unicode escape sequence, use
289 #(ly:export (ly:wide-char->utf-8 #x2014))
295 @inputfileref{input/regression,utf-8.ly}
299 @node A single music expression
300 @section A single music expression
302 A @code{\score} must contain a single music expression. However,
303 this music expression may be of any size. Recall that music
304 expressions may be included inside other expressions to form
305 larger expressions. All of these examples are single music
306 expressions; note the curly braces @{ @} or angle brackets <<
307 >> at the beginning and ending of the music.
313 @lilypond[ragged-right,verbatim,quote]
320 @lilypond[ragged-right,verbatim,quote]
322 \new Staff { c'4 c' c' c' }
323 \new Staff { d'4 d' d' d' }
331 \new Staff @{ \flute @}
332 \new Staff @{ \oboe @}
335 \new Staff @{ \violinI @}
336 \new Staff @{ \violinII @}
343 @node Titles and headers
344 @section Titles and headers
346 Almost all printed music includes a title and the composer's name;
347 some pieces include a lot more information.
355 @node Creating titles
356 @subsection Creating titles
358 Titles are created for each @code{\score} block, and over a
361 The contents of the titles are taken from the @code{\header} blocks.
362 The header block for a book supports the following
368 The dedicatee of the music, centered at the top of the first page.
372 The title of the music, centered just below the dedication.
376 Subtitle, centered below the title.
380 Subsubtitle, centered below the subtitle.
384 Name of the poet, flush-left below the subtitle.
388 Name of the composer, flush-right below the subtitle.
392 Meter string, flush-left below the poet.
396 Name of the opus, flush-right below the composer.
400 Name of the arranger, flush-right below the opus.
404 Name of the instrument, centered below the arranger. Also
405 centered at the top of pages (other than the first page).
409 Name of the piece, flush-left below the instrument.
411 @cindex page breaks, forcing
414 This forces the title to start on a new page (set to ##t or ##f).
418 Copyright notice, centered at the bottom of the first page. To
419 insert the copyright symbol, see @ref{Text encoding}.
423 Centered at the bottom of the last page.
427 Here is a demonstration of the fields available. Note that you
428 may use any @ref{Text markup} commands in the header.
430 @lilypond[quote,verbatim,line-width=11.0\cm]
433 paper-height = 10.0\cm
438 dedication = "dedicated to me"
439 title = \markup \center-align { "Title first line" "Title second line,
441 subtitle = "the subtitle,"
442 subsubtitle = #(string-append "subsubtitle LilyPond version "
445 composer = \markup \center-align { "composer" \small "(1847-1973)" }
446 texttranslator = "Text Translator"
447 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
449 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
450 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
451 instrument = \markup \bold \italic "instrument"
475 As demonstrated before, you can use multiple @code{\header} blocks.
476 When same fields appear in different blocks, the latter is used.
477 Here is a short example.
481 composer = "Composer"
489 piece = "New piece" % overwrite previous one
494 If you define the @code{\header} inside the @code{\score} block, then
495 normally only the @code{piece} and @code{opus} headers will be printed.
496 Note that the music expression must come before the @code{\header}.
498 @lilypond[quote,verbatim,line-width=11.0\cm]
502 title = "title" % not printed
509 @findex printallheaders
511 You may change this behavior (and print all the headers when defining
512 @code{\header} inside @code{\score}) by using
522 @subsection Custom titles
524 A more advanced option is to change the definitions of the following
525 variables in the @code{\paper} block. The init file
526 @file{ly/titling-init.ly} lists the default layout.
529 @findex bookTitleMarkup
530 @item bookTitleMarkup
531 This is the title put over an entire @code{\book} block. Typically,
532 it has the composer and the title of the piece
534 @findex scoreTitleMarkup
535 @item scoreTitleMarkup
536 This is the title put over a @code{\score} block within a
537 @code{\book}. Typically, it has the name of the movement (@code{piece}
540 @findex oddHeaderMarkup
541 @item oddHeaderMarkup
542 This is the page header for odd-numbered pages.
544 @findex evenHeaderMarkup
545 @item evenHeaderMarkup
546 This is the page header for even-numbered pages. If unspecified,
547 the odd header is used instead.
549 By default, headers are defined such that the page number is on the
550 outside edge, and the instrument is centered.
552 @findex oddFooterMarkup
553 @item oddFooterMarkup
554 This is the page footer for odd-numbered pages.
556 @findex evenFotterMarkup
557 @item evenFooterMarkup
558 This is the page footer for even-numbered pages. If unspecified,
559 the odd header is used instead.
561 By default, the footer has the copyright notice on the first, and
562 the tagline on the last page.
572 The following definition will put the title flush left, and the
573 composer flush right on a single line.
577 bookTitleMarkup = \markup {
579 \fromproperty #'header:title
580 \fromproperty #'header:composer
589 The @code{breakbefore=##t} header requires that there is a @code{piece}
590 header as well. It may be used as a normal header, or left blank
591 (@code{=""}) as in the example above, but it must be present.
595 @node Paper and pages
596 @section Paper and pages
598 This section deals with the display of music on physical paper.
607 @subsection Paper size
613 To change the paper size, there are two commands,
615 #(set-default-paper-size "a4")
617 #(set-paper-size "a4")
621 The first command sets the size of all pages. The second command sets the
623 of the pages that the @code{\paper} block applies to -- if the @code{\paper}
624 block is at the top of the file, then it will apply to all pages. If the
625 @code{\paper} block is inside a @code{\book}, then the paper size will only
628 Support for the following paper sizes are included by default,
629 @code{a6}, @code{a5}, @code{a4}, @code{a3}, @code{legal}, @code{letter},
630 @code{11x17} (also known as tabloid).
632 Extra sizes may be added by editing the definition for
633 @code{paper-alist} in the initialization file @file{scm/paper.scm}.
638 If the symbol @code{landscape} is supplied as an argument to
639 @code{set-default-paper-size}, the pages will be rotated by 90 degrees,
640 and wider line widths will be set correspondingly.
643 #(set-default-paper-size "a6" 'landscape)
646 Setting the paper size will adjust a number of @code{\paper} variables
647 (such as margins). To use a particular paper size with altered
648 @code{\paper} variables, set the paper size before setting the variables.
651 @node Page formatting
652 @subsection Page formatting
654 @cindex page formatting
659 LilyPond will do page layout, set margins, and add headers and
660 footers to each page.
662 @findex annotate-spacing
663 @cindex Spacing, display of properties
665 To graphically display the dimensions of vertical properties
666 that may be altered for page formatting, use
670 annotate-spacing = ##t
675 @c FIXME: really bad vagueness due to bug in annotate-spacing. -gp
676 Some unit dimensions are measured in staff spaces, while others
677 are measured in millimeters.
679 (@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
680 @var{b} the upper edge of the interval.
682 The default layout responds to the following settings in the
689 @findex first-page-number
690 @item first-page-number
691 The value of the page number of the first page. Default is@tie{}1.
693 @findex printfirst-page-number
694 @item printfirst-page-number
695 If set to true, will print the page number in the first page. Default is
698 @findex print-page-number
699 @item print-page-number
700 If set to false, page numbers will not be printed.
704 The width of the page.
708 The height of the page.
712 Margin between header and top of the page.
714 @findex bottom-margin
716 Margin between footer and bottom of the page.
720 Margin between the left side of the page and the beginning of the music.
724 The length of the systems.
726 @findex head-separation
727 @item head-separation
728 Distance between the top-most music system and the page header.
730 @findex foot-separation
731 @item foot-separation
732 Distance between the bottom-most music system and the page footer.
734 @findex page-top-space
735 Distance from the top of the printable area to the center of the first
736 staff. This only works for staves which are vertically small. Big staves
737 are set with the top of their bounding box aligned to the top of the
740 @findex ragged-bottom
742 If set to true, systems will not be spread vertically across the page. This
743 does not affect the last page.
745 This should be set to true for pieces that have only two or three
746 systems per page, for example orchestral scores.
748 @findex ragged-last-bottom
749 @item ragged-last-bottom
750 If set to false, systems will be spread vertically to fill the last page.
752 Pieces that amply fill two pages or more should have this set to
757 This variable, if set, specifies into how many lines a score should be
760 @findex between-system-space
761 @item between-system-space
762 This dimensions determines the distance between systems. It is the
763 ideal distance between the center of the bottom staff of one system
764 and the center of the top staff of the next system.
766 Increasing this will provide a more even appearance of the page at the
767 cost of using more vertical space.
769 @findex between-system-padding
770 @item between-system-padding
771 This dimension is the minimum amount of white space that will always
772 be present between the bottom-most symbol of one system, and the
773 top-most of the next system.
775 Increasing this will put systems whose bounding boxes almost touch
779 @findex horizontal-shift
780 @item horizontal-shift
781 All systems (including titles and system separators) are shifted by
782 this amount to the right. Page markup, such as headers and footers are
783 not affected by this. The purpose of this variable is to make space
784 for instrument names at the left.
786 @findex after-title-space
787 @item after-title-space
788 Amount of space between the title and the first system.
790 @findex after-title-space
791 @item before-title-space
792 Amount of space between the last system of the previous piece and the
795 @findex between-title-space
796 @item between-title-space
797 Amount of space between consecutive titles (e.g., the title of the
798 book and the title of a piece).
800 @findex printallheaders
801 @item printallheaders
802 Setting this to #t will print all headers for each \score in a
803 \book. Normally only the piece and opus \headers are printed.
805 @findex systemSeparatorMarkup
806 @item systemSeparatorMarkup
807 This contains a markup object, which will be inserted between
808 systems. This is often used for orchestral scores.
810 The markup command @code{\slashSeparator} is provided as a sensible
813 @lilypond[ragged-right]
816 \relative { c1 \break c1 }
819 systemSeparatorMarkup = \slashSeparator
835 ragged-last-bottom = ##t
839 You can also define these values in Scheme. In that case @code{mm},
840 @code{in}, @code{pt}, and @code{cm} are variables defined in
841 @file{paper-defaults.ly} with values in millimeters. That's why the
842 value has to be multiplied in the example
846 #(define bottom-margin (* 2 cm))
853 The default footer is empty, except for the first page, where the
854 @code{copyright} field from @code{\header} is inserted, and the last
855 page, where @code{tagline} from @code{\header} is added. The default
856 tagline is ``Music engraving by LilyPond (@var{version})''.@footnote{Nicely
857 printed parts are good PR for us, so please leave the tagline if you
860 The header and footer are created by the functions @code{make-footer}
861 and @code{make-header}, defined in @code{\paper}. The default
862 implementations are in @file{ly/@/paper@/-defaults@/.ly} and
863 @file{ly/@/titling@/-init@/.ly}.
865 The page layout itself is done by two functions in the
866 @code{\paper} block, @code{page-music-height} and
867 @code{page-make-stencil}. The former tells the line-breaking algorithm
868 how much space can be spent on a page, the latter creates the actual
869 page given the system to put on it.
874 The option right-margin is defined but doesn't set the right margin
875 yet. The value for the right margin has to be defined adjusting the
876 values of @code{left-margin} and @code{line-width}.
878 The default page header puts the page number and the @code{instrument}
879 field from the @code{\header} block on a line.
881 The titles (from the @code{\header@{@}} section) are treated as a
882 system, so @code{ragged-bottom} and @code{ragged-last-bottom} will
883 add space between the titles and the first system of the score.
887 @section Music layout
889 This section deals with the manner in which the music is printed
890 within the boundaries defined by the @code{\paper} block.
892 The global paper layout is determined by three factors: the page layout, the
893 line breaks, and the spacing. These all influence each other. The
894 choice of spacing determines how densely each system of music is set.
895 This influences where line breaks are chosen, and thus ultimately, how
896 many pages a piece of music takes.
898 Globally spoken, this procedure happens in three steps: first,
899 flexible distances (``springs'') are chosen, based on durations. All
900 possible line breaking combinations are tried, and the one with the
901 best results -- a layout that has uniform density and requires as
902 little stretching or cramping as possible -- is chosen.
904 After spacing and linebreaking, the systems are distributed across
905 pages, taking into account the size of the page, and the size of the
909 * Setting global staff size::
910 * Selecting notation font size::
913 * Vertical spacing of piano staves::
914 * Horizontal spacing::
921 @node Setting global staff size
922 @subsection Setting global staff size
924 @cindex font size, setting
925 @cindex staff size, setting
928 To set the global staff size, use @code{set-global-staff-size}.
931 #(set-global-staff-size 14)
935 This sets the global default size to 14pt staff height and scales all
938 The Feta font provides musical symbols at eight different
939 sizes. Each font is tuned for a different staff size: at a smaller size
940 the font becomes heavier, to match the relatively heavier staff lines.
941 The recommended font sizes are listed in the following table:
944 @multitable @columnfractions .15 .2 .22 .2
947 @tab @b{staff height (pt)}
948 @tab @b{staff height (mm)}
990 @c modern rental material?
995 These fonts are available in any sizes. The context property
996 @code{fontSize} and the layout property @code{staff-space} (in
997 @internalsref{StaffSymbol}) can be used to tune the size for individual
998 staves. The sizes of individual staves are relative to the global size.
1006 This manual: @ref{Selecting notation font size}.
1009 @node Selecting notation font size
1010 @subsection Selecting notation font size
1012 The easiest method of setting the font size of any context, is by
1013 setting the @code{fontSize} property.
1015 @lilypond[quote,fragment,relative=1,verbatim]
1024 It does not change the size of variable symbols, such as beams or
1027 Internally, the @code{fontSize} context property will cause the
1028 @code{font-size} property to be set in all layout objects. The value
1029 of @code{font-size} is a number indicating the size relative to the
1030 standard size for the current staff height. Each step up is an
1031 increase of approximately 12% of the font size. Six steps is exactly a
1032 factor two. The Scheme function @code{magstep} converts a
1033 @code{font-size} number to a scaling factor.
1035 @lilypond[quote,fragment,relative=1,verbatim]
1037 \override NoteHead #'font-size = #-4
1039 \override NoteHead #'font-size = #3
1043 LilyPond has fonts in different design sizes. The music fonts for
1044 smaller sizes are chubbier, while the text fonts are relatively wider.
1045 Font size changes are achieved by scaling the design size that is
1046 closest to the desired size. The standard font size (for
1047 @code{font-size} equals 0), depends on the standard staff height. For
1048 a 20pt staff, a 10pt font is selected.
1050 The @code{font-size} property can only be set on layout objects that
1051 use fonts. These are the ones supporting the
1052 @internalsref{font-interface} layout interface.
1056 The following commands set @code{fontSize} for the current voice:
1067 @subsection Score layout
1071 While @code{\paper} contains settings that relate to the page formatting
1072 of the whole document, @code{\layout} contains settings for score-specific
1079 \override VerticalAxisGroup #'minimum-Y-extent = #'(-6 . 6)
1082 \override TextScript #'padding = #1.0
1083 \override Glissando #'thickness = #3
1091 This manual: @ref{Changing context default settings}
1094 @node Vertical spacing
1095 @subsection Vertical spacing
1097 @cindex vertical spacing
1098 @cindex distance between staves
1099 @cindex staff distance
1100 @cindex between staves, distance
1101 @cindex staves per page
1102 @cindex space between staves
1104 The height of each system is determined automatically. To prevent
1105 systems from bumping into each other, some minimum distances are set.
1106 By changing these, you can put staves closer together, and thus put
1107 more systems onto one page.
1109 Normally staves are stacked vertically. To make staves maintain a
1110 distance, their vertical size is padded. This is done with the
1111 property @code{minimum-Y-extent}. When applied to a
1112 @internalsref{VerticalAxisGroup}, it controls the size of a horizontal
1113 line, such as a staff or a line of lyrics. @code{minimum-Y-extent}
1114 takes a pair of numbers, so
1115 if you want to make it smaller than its default @code{#'(-4 . 4)}
1119 \override Staff.VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
1123 This sets the vertical size of the current staff to 3 staff spaces on
1124 either side of the center staff line. The value @code{(-3 . 3)} is
1125 interpreted as an interval, where the center line is the 0, so the
1126 first number is generally negative. The staff can be made larger at
1127 the bottom by setting it to @code{(-6 . 4)}.
1129 The spacing of staves in a system may also be tuned per system. This is
1130 done with the command
1134 #"Score.NonMusicalPaperColumn"
1135 #'line-break-system-details
1136 #'((alignment-extra-space . 15))
1140 at the line break before the system to be changed. The distance
1141 @code{15} is distributed over all staves that have a fixed distance
1142 alignment. For example,
1144 @lilypond[ragged-right, fragment, relative=2, staffsize=13]
1150 #"Score.NonMusicalPaperColumn"
1151 #'line-break-system-details
1152 #'((fixed-alignment-extra-space . 15))
1160 The distance for @code{alignment-extra-space} may also be negative.
1163 To change the amount of space between systems, use
1164 @code{between-system-space}. A score with only one staff is still
1165 considered to have systems, so setting @code{between-system-space} will
1166 be much more useful than changing @code{minimum-Y-extent} of a Staff
1171 between-system-space = 10\mm
1175 If you simply want to tell LilyPond ``fit as much as possible onto
1176 these pages, then expand to fill any available space on the pages,''
1177 then use the following
1181 between-system-padding = #1
1183 ragged-last-bottom=##f
1188 @c let's wait for a some comments before writing more.
1190 The vertical spacing on a page can also be changed for each system
1192 Some examples are found in the example file
1193 @inputfileref{input/regression/,page-spacing.ly}.
1195 When setting @code{annotate-spacing} in the @code{\paper} block LilyPond
1196 will graphically indicate the dimensions of properties that may be set
1200 #(set-default-paper-size "a7" 'landscape)
1201 \paper { annotate-spacing = ##t }
1206 All units dimensions are measured in staff spaces. The pairs
1207 (@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
1208 @var{b} the upper edge of the interval.
1212 Internals: Vertical alignment of staves is handled by the
1213 @internalsref{VerticalAlignment} object. The context parameters
1214 specifying the vertical extent are described in connection with
1215 the @internalsref{Axis_group_engraver}.
1217 Example files: @inputfileref{input/regression/,page-spacing.ly},
1218 @inputfileref{input/regression/,alignment-vertical-spacing.ly}.
1223 @node Vertical spacing of piano staves
1224 @subsection Vertical spacing of piano staves
1226 The distance between staves of a @internalsref{PianoStaff} cannot be
1227 computed during formatting. Rather, to make cross-staff beaming work
1228 correctly, that distance has to be fixed beforehand.
1230 The distance of staves in a @code{PianoStaff} is set with the
1231 @code{forced-distance} property of the
1232 @internalsref{VerticalAlignment} object, created in
1233 @internalsref{PianoStaff}.
1235 It can be adjusted as follows
1237 \new PianoStaff \with @{
1238 \override VerticalAlignment #'forced-distance = #7
1245 This would bring the staves together at a distance of 7 staff spaces,
1246 measured from the center line of each staff.
1248 The difference is demonstrated in the following example,
1249 @lilypond[quote,verbatim]
1251 \new PianoStaff \with {
1252 \override VerticalAlignment #'forced-distance = #7
1265 It is also possible to change the distance between for each system
1266 individually. This is done by including the command
1270 #"Score.NonMusicalPaperColumn"
1271 #'line-break-system-details
1272 #'((fixed-alignment-extra-space . 15))
1276 at the line break before the system to be changed. The distance
1277 @code{15} is distributed over all staves that have a fixed distance
1278 alignment. For example,
1280 @lilypond[ragged-right, fragment, relative=2, staffsize=13]
1286 #"Score.NonMusicalPaperColumn"
1287 #'line-break-system-details
1288 #'((fixed-alignment-extra-space . 15))
1296 The distance for @code{fixed-alignment-extra-space} may also be
1301 Example files: @inputfileref{input/regression/,alignment-vertical-spacing.ly}.
1303 @node Horizontal spacing
1304 @subsection Horizontal Spacing
1306 The spacing engine translates differences in durations into stretchable
1307 distances (``springs'') of differring lengths. Longer durations get
1308 more space, shorter durations get less. The shortest durations get a
1309 fixed amount of space (which is controlled by
1310 @code{shortest-duration-space} in the @internalsref{SpacingSpanner}
1311 object). The longer the duration, the more space it gets: doubling a
1312 duration adds a fixed amount (this amount is controlled by
1313 @code{spacing-increment}) of space to the note.
1315 For example, the following piece contains lots of half, quarter, and
1316 8th notes; the eighth note is followed by 1 note head width (NHW).
1317 The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
1319 @lilypond[quote,fragment,verbatim,relative=1]
1320 c2 c4. c8 c4. c8 c4. c8 c8
1324 Normally, @code{spacing-increment} is set to 1.2 staff space, which is
1325 approximately the width of a note head, and
1326 @code{shortest-duration-space} is set to 2.0, meaning that the
1327 shortest note gets 2.4 staff space (2.0 times the
1328 @code{spacing-increment}) of horizontal space. This space is counted
1329 from the left edge of the symbol, so the shortest notes are generally
1330 followed by one NHW of space.
1332 If one would follow the above procedure exactly, then adding a single
1333 32nd note to a score that uses 8th and 16th notes, would widen up the
1334 entire score a lot. The shortest note is no longer a 16th, but a 32nd,
1335 thus adding 1 NHW to every note. To prevent this, the shortest
1336 duration for spacing is not the shortest note in the score, but rather
1337 the one which occurs most frequently.
1340 The most common shortest duration is determined as follows: in every
1341 measure, the shortest duration is determined. The most common shortest
1342 duration is taken as the basis for the spacing, with the stipulation
1343 that this shortest duration should always be equal to or shorter than
1344 an 8th note. The shortest duration is printed when you run
1345 @code{lilypond} with the @code{--verbose} option.
1347 These durations may also be customized. If you set the
1348 @code{common-shortest-duration} in @internalsref{SpacingSpanner}, then
1349 this sets the base duration for spacing. The maximum duration for this
1350 base (normally an 8th), is set through @code{base-shortest-duration}.
1352 @findex common-shortest-duration
1353 @findex base-shortest-duration
1354 @findex stem-spacing-correction
1357 Notes that are even shorter than the common shortest note are
1358 followed by a space that is proportional to their duration relative to
1359 the common shortest note. So if we were to add only a few 16th notes
1360 to the example above, they would be followed by half a NHW:
1362 @lilypond[quote,fragment,verbatim,relative=2]
1363 c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
1367 In the introduction (see @ref{Engraving}), it was explained that stem
1368 directions influence spacing. This is controlled with the
1369 @code{stem-spacing-correction} property in the
1370 @internalsref{NoteSpacing}, object. These are generated for every
1371 @internalsref{Voice} context. The @code{StaffSpacing} object
1372 (generated in @internalsref{Staff} context) contains the same property
1373 for controlling the stem/bar line spacing. The following example shows
1374 these corrections, once with default settings, and once with
1375 exaggerated corrections:
1377 @lilypond[quote,ragged-right]
1381 \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
1382 \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
1388 Proportional notation is supported; see @ref{Proportional notation}.
1390 By default, spacing in tuplets depends on various non-duration
1391 factors (such as accidentals, clef changes, etc). To disregard
1392 such symbols and force uniform equal-duration spacing, use
1393 @code{Score.SpacingSpanner #'uniform-stretching}. This
1394 property can only be changed at the beginning of a score,
1396 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1398 \override SpacingSpanner #'uniform-stretching = ##t
1416 When @code{strict-note-spacing} is set, notes are spaced without
1417 regard for clefs, bar lines, and grace notes,
1419 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1420 \override Score.SpacingSpanner #'strict-note-spacing = ##t
1421 \new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c] c32[ c32] }
1427 Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
1428 @internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
1429 @internalsref{SeparatingGroupSpanner}.
1433 Spacing is determined on a score wide basis. If you have a score that
1434 changes its character (measured in durations) halfway during the
1435 score, the part containing the longer durations will be spaced too
1438 There is no convenient mechanism to manually override spacing. The
1439 following work-around may be used to insert extra space into a score.
1441 \once \override Score.SeparationItem #'padding = #1
1444 No work-around exists for decreasing the amount of space.
1448 @subsection Line length
1451 @cindex breaking pages
1455 @findex ragged-right
1458 @c Although line-width can be set in \layout, it should be set in paper
1459 @c block, to get page layout right.
1460 @c Setting indent in \paper block makes not much sense, but it works.
1462 @c Bit verbose and vague, use examples?
1463 The most basic settings influencing the spacing are @code{indent} and
1464 @code{line-width}. They are set in the @code{\layout} block. They
1465 control the indentation of the first line of music, and the lengths of
1468 If @code{ragged-right} is set to true in the @code{\layout} block, then
1469 systems ends at their natural horizontal length, instead of being spread
1470 horizontally to fill the whole line. This is useful for
1471 short fragments, and for checking how tight the natural spacing is.
1474 @cindex vertical spacing
1476 The option @code{ragged-last} is similar to @code{ragged-right}, but
1477 only affects the last line of the piece. No restrictions are put on
1478 that line. The result is similar to formatting text paragraphs. In a
1479 paragraph, the last line simply takes its natural horizontal length.
1480 @c Note that for text there are several options for the last line.
1481 @c While Knuth TeX uses natural length, lead typesetters use the same
1482 @c stretch as the previous line. eTeX uses \lastlinefit to
1483 @c interpolate between both these solutions.
1495 @subsection Line breaking
1498 @cindex breaking lines
1500 Line breaks are normally computed automatically. They are chosen so
1501 that lines look neither cramped nor loose, and that consecutive lines
1502 have similar density.
1504 Occasionally you might want to override the automatic breaks; you can
1505 do this by specifying @code{\break}. This will force a line break at
1506 this point. Line breaks can only occur at places where there are bar
1507 lines. If you want to have a line break where there is no bar line,
1508 you can force an invisible bar line by entering @code{\bar
1509 ""}. Similarly, @code{\noBreak} forbids a line break at a
1513 @cindex regular line breaks
1514 @cindex four bar music.
1516 For line breaks at regular intervals use @code{\break} separated by
1517 skips and repeated with @code{\repeat}:
1519 << \repeat unfold 7 @{
1520 s1 \noBreak s1 \noBreak
1521 s1 \noBreak s1 \break @}
1522 @emph{the real music}
1527 This makes the following 28 measures (assuming 4/4 time) be broken every
1528 4 measures, and only there.
1532 @code{\break}, and @code{\noBreak}.
1538 Internals: @internalsref{BreakEvent}.
1540 A linebreaking configuration can now be saved as a @code{.ly} file
1541 automatically. This allows vertical alignments to be stretched to
1542 fit pages in a second formatting run. This is fairly new and
1543 complicated; see @inputfileref{input/regression/,page-layout-twopass.ly}
1548 Line breaks can only occur if there is a ``proper'' bar line. A note
1549 which is hanging over a bar line is not proper, such as
1551 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1552 c4 c2 c2 \break % this does nothing
1553 c2 c4 | % a break here would work
1554 c4 c2 c4 ~ \break % as does this break
1560 @subsection Page breaking
1562 The default page breaking may be overriden by inserting
1563 @code{\pageBreak} or @code{\noPageBreak} commands. These commands are
1564 analogous to @code{\break} and @code{\noBreak}. They should be
1565 inserted at a bar line. These commands force and forbid a page-break
1566 from happening. Of course, the @code{\pageBreak} command also forces
1569 Page breaks are computed by the @code{page-breaking} function in the
1570 @code{\paper} block.
1572 To force a new page for a new piece (in a collection of pieces or a
1573 piece in several movements), use @code{breakbefore} in the header.
1586 @findex \noPageBreak
1592 The @code{breakbefore=##t} header requires that there is a @code{piece}
1593 header as well. It may be used as a normal header, or left blank
1594 (@code{=""}) as in the example above, but it must be present.
1598 @node Multiple movements
1599 @section Multiple movements
1601 @cindex bibliographic information
1604 @cindex Music engraving by LilyPond
1606 A document may contain multiple pieces of music and texts. Examples
1607 of these are an etude book, or an orchestral part with multiple
1608 movements. Each movement is entered with a @code{\score} block,
1616 and texts are entered with a @code{\markup} block,
1626 The movements and texts are combined together in a @code{\book} block,
1644 The header for each piece of music can be put inside the @code{\score}
1645 block. The @code{piece} name from the header will be printed before
1646 each movement. The title for the entire book can be put inside the
1647 @code{\book}, but if it is not present, the @code{\header} which is at
1648 the top of the file is inserted.
1650 @cindex Engraved by LilyPond
1651 @cindex signature line
1656 title = "Eight miniatures"
1657 composer = "Igor Stravinsky"
1661 \header @{ piece = "Romanze" @}
1664 ..text of second verse..
1667 ..text of third verse..
1671 \header @{ piece = "Menuetto" @}
1679 @section MIDI output
1684 MIDI (Musical Instrument Digital Interface) is a standard for
1685 connecting and controlling digital instruments. A MIDI file is a
1686 series of notes in a number of tracks. It is not an actual
1687 sound file; you need special software to translate between the
1688 series of notes and actual sounds.
1690 Pieces of music can be converted to MIDI files, so you can listen to
1691 what was entered. This is convenient for checking the music; octaves
1692 that are off or accidentals that were mistyped stand out very much
1693 when listening to the MIDI output.
1697 Many musically interesting effects, such as swing, articulation,
1698 slurring, etc., are not translated to midi.
1700 The midi output allocates a channel for each staff, and one for global
1701 settings. Therefore the midi file should not have more than 15 staves
1702 (or 14 if you do not use drums). Other staves will remain silent.
1704 Not all midi players correctly handle tempo changes in the midi
1705 output. Players that are known to work include
1706 @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
1709 * Creating MIDI files::
1711 * MIDI instrument names::
1714 @node Creating MIDI files
1715 @subsection Creating MIDI files
1717 To create a MIDI from a music piece of music, add a @code{\midi} block
1718 to a score, for example,
1723 \midi @{ \tempo 4=72 @}
1727 The tempo is specified using the @code{\tempo} command. In this
1728 example the tempo of quarter notes is set to 72 beats per minute.
1731 If there is a @code{\midi} command in a @code{\score}, only MIDI will
1732 be produced. When notation is needed too, a @code{\layout} block must
1738 \midi @{ \tempo 4=72 @}
1742 @cindex layout block
1746 Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
1747 crescendi and decrescendi translate into MIDI volume levels. Dynamic
1748 marks translate to a fixed fraction of the available MIDI volume
1749 range, crescendi and decrescendi make the volume vary linearly between
1750 their two extremes. The fractions can be adjusted by
1751 @code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
1752 For each type of MIDI instrument, a volume range can be defined. This
1753 gives a basic equalizer control, which can enhance the quality of
1754 the MIDI output remarkably. The equalizer can be controlled by
1755 setting @code{instrumentEqualizer}, or by setting
1758 \set Staff.midiMinimumVolume = #0.2
1759 \set Staff.midiMaximumVolume = #0.8
1762 To remove dynamics from the MIDI output, insert the following lines
1763 in the @code{\midi@{@}} section.
1770 \remove "Dynamic_performer"
1771 \remove "Span_dynamic_performer"
1779 Unterminated (de)crescendos will not render properly in the midi file,
1780 resulting in silent passages of music. The workaround is to explicitly
1781 terminate the (de)crescendo. For example,
1788 will not work properly but
1799 @subsection MIDI block
1803 The MIDI block is analogous to the layout block, but it is somewhat
1804 simpler. The @code{\midi} block can contain
1808 @item a @code{\tempo} definition, and
1809 @item context definitions.
1812 A number followed by a period is interpreted as a real number, so
1813 for setting the tempo for dotted notes, an extra space should be
1814 inserted, for example
1817 \midi @{ \tempo 4 . = 120 @}
1821 @cindex context definition
1823 Context definitions follow precisely the same syntax as within the
1824 \layout block. Translation modules for sound are called performers.
1825 The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
1828 @node MIDI instrument names
1829 @subsection MIDI instrument names
1831 @cindex instrument names
1832 @findex Staff.midiInstrument
1834 The MIDI instrument name is set by the @code{Staff.midiInstrument}
1835 property. The instrument name should be chosen from the list in
1836 @ref{MIDI instruments}.
1839 \set Staff.midiInstrument = "glockenspiel"
1843 If the selected instrument does not exactly match an instrument from
1844 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
1848 @c Yes, this is a cop-out; this info doesn't belong in the Scheme
1849 @c chapter, but I'm not certain where to stick it.
1850 @c I think I'll eventually split this chapter into a "paper/layout"
1851 @c chapter and a "misc issues" chapter. -gp
1852 @node Displaying LilyPond notation
1853 @section Displaying LilyPond notation
1855 @findex \displayLilyMusc
1856 Displaying a music expression in LilyPond notation can be
1857 done using the music function @code{\displayLilyMusic}. For example,
1861 \displayLilyMusic \transpose c a, @{ c e g a bes @}
1868 @{ a, cis e fis g @}
1871 By default, LilyPond will print these messages to the console along
1872 with all the other messages. To split up these messages and save
1873 the results of @code{\display@{STUFF@}}, redirect the output to
1877 lilypond file.ly >display.txt
1884 @c FIXME: yeah, it really needs to be moved soon. -gp
1886 * Skipping corrected music::
1887 * Writing music in parallel::
1890 @node Skipping corrected music
1891 @subsection Skipping corrected music
1894 @findex skipTypesetting
1895 @findex showLastLength
1897 When entering or copying music, usually only the music near the end (where
1899 are adding notes) is interesting to view and correct. To speed up
1900 this correction process, it is possible to skip typesetting of all but
1901 the last few measures. This is achieved by putting
1904 showLastLength = R1*5
1909 in your source file. This will render only the last 5 measures
1910 (assuming 4/4 time signature) of every @code{\score} in the input
1911 file. For longer pieces, rendering only a small part is often an order
1912 of magnitude quicker than rendering it completely
1914 Skipping parts of a score can be controlled in a more fine-grained
1915 fashion with the property @code{Score.skipTypesetting}. When it is
1916 set, no typesetting is performed at all.
1918 This property is also used to control output to the MIDI file. Note that
1919 it skips all events, including tempo and instrument changes. You have
1922 @lilypond[quote,fragment,ragged-right,verbatim]
1925 \set Score.skipTypesetting = ##t
1927 \set Score.skipTypesetting = ##f
1931 In polyphonic music, @code{Score.skipTypesetting} will affect all
1932 voices and staves, saving even more time.
1935 @node Writing music in parallel
1936 @subsection Writing music in parallel
1937 @cindex Writing music in parallel
1938 @cindex Interleaved music
1940 Music for multiple parts can be interleaved
1942 @lilypond[quote,fragment,verbatim]
1943 \parallelMusic #'(voiceA voiceB) {
1944 r8 g'16[ c''] e''[ g' c'' e''] r8 g'16[ c''] e''[ g' c'' e''] |
1946 r8 a'16[ d''] f''[ a' d'' f''] r8 a'16[ d''] f''[ a' d'' f''] |
1950 \new Staff \new Voice \voiceA
1951 \new Staff \new Voice \voiceB