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::
28 The main format of input for LilyPond are text files. By convention,
29 these files end with ``@code{.ly}''.
32 * File structure (introduction)::
34 * Including LilyPond files::
39 @node File structure (introduction)
40 @subsection File structure (introduction)
42 A basic example of a lilypond input file is
47 @{ @} % this is a single music expression;
48 % all the music goes in here.
56 There are many variations of this basic pattern, but this
57 example serves as a useful starting place.
59 The major part of this manual is concerned with entering various
60 forms of music in LilyPond. However, many music expressions are not
61 valid input on their own, for example, a @code{.ly} file containing
68 will result in a parsing error. Instead, music should be inside other
69 expressions, which may be put in a file by themselves. Such
70 expressions are called toplevel expressions. The next section enumerates
75 @subsection File structure
77 A @code{.ly} file contains any number of toplevel expressions, where a
78 toplevel expression is one of the following
82 An output definition, such as @code{\paper}, @code{\midi}, and
83 @code{\layout}. Such a definition at the toplevel changes the default
84 settings for the block entered.
87 A direct scheme expression, such as
88 @code{#(set-default-paper-size "a7" 'landscape)} or
89 @code{#(ly:set-option 'point-and-click #f)}.
92 A @code{\header} block. This sets the global header block. This
93 is the block containing the definitions for book-wide settings, like
97 An @code{\addquote} statement. See @ref{Quoting other voices}
101 A @code{\score} block. This score will be collected with other
102 toplevel scores, and combined as a single @code{\book}.
104 This behavior can be changed by setting the variable
105 @code{toplevel-score-handler} at toplevel. The default handler is
106 defined in the init file @file{scm/@/lily@/.scm}.
108 The @code{\score} must begin with a music expression, and may
109 contain only one music expression.
112 A @code{\book} block logically combines multiple movements
113 (i.e., multiple @code{\score} blocks) in one document. If there are
114 a number of @code{\scores}, a single output file will be created
115 in which all movements are concatenated.
117 This behavior can be changed by setting the variable
118 @code{toplevel-book-handler} at toplevel. The default handler is
119 defined in the init file @file{scm/@/lily@/.scm}.
122 A compound music expression, such as
127 This will add the piece in a @code{\score} and format it in a
128 single book together with all other toplevel @code{\score}s and music
129 expressions. In other words, a file containing only the above
130 music expression will be translated into
146 This behavior can be changed by setting the variable
147 @code{toplevel-music-handler} at toplevel. The default handler is
148 defined in the init file @file{scm/@/lily@/.scm}.
151 A markup text, a verse for example
154 2. The first line verse two.
158 Markup texts are rendered above, between or below the scores or music
159 expressions, wherever they appear.
162 An identifier, such as
167 This can be used later on in the file by entering @code{\foo}. The
168 name of an identifier should have alphabetic characters only; no
169 numbers, underscores or dashes.
173 The following example shows three things that may be entered at
178 % movements are non-justified by default
190 At any point in a file, any of the following lexical instructions can
194 @item @code{\version}
195 @item @code{\include}
196 @item @code{\renameinput}
200 @node Including LilyPond files
201 @subsection Including LilyPond files
203 @cindex @code{\include}
204 @cindex including files
206 A large project may be split up into separate files. To refer to another
210 \include "otherfile.ly"
213 The line @code{\include "file.ly"} is equivalent to pasting the contents
214 of file.ly into the current file at the place where you have the
215 \include. For example, for a large project you might write separate files
216 for each instrument part and create a ``full score'' file which brings
217 together the individual instrument files.
219 The initialization of LilyPond is done in a number of files that are
220 included by default when you start the program, normally transparent to the
221 user. Run lilypond --verbose to see a list of paths and files that Lily
224 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
225 VERSION is in the form ``2.6.1'') are on the path and available to
226 @code{\include}. Files in the
227 current working directory are available to \include, but a file of the same
228 name in LilyPond's installation takes precedence. Files are
229 available to \include from directories in the search path specified as an
230 option when invoking @code{lilypond --include=DIR} which adds DIR to the
233 The @code{\include} statement can use full path information, but with the Unix
234 convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example,
235 if @file{stuff.ly} is located one directory higher than the current working
239 \include "../stuff.ly"
244 @subsection Text encoding
246 LilyPond uses the Pango library to format multi-lingual texts, and
247 does not perform any input-encoding conversions. This means that any
248 text, be it title, lyric text, or musical instruction containing
249 non-ASCII characters, must be utf-8. The easiest way to enter such text is
250 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
251 popular modern editors have utf-8 support, for example, vim, Emacs,
254 Depending on the fonts installed, the following fragment shows Hebrew
261 @lilypondfile[fontload]{utf-8.ly}
263 The @TeX{} backend does not handle encoding specially at all. Strings
264 in the input are put in the output as-is. Extents of text items in the
265 @TeX{} backend, are determined by reading a file created via the
266 @file{texstr} backend,
269 lilypond -b texstr input/les-nereides.ly
270 latex les-nereides.texstr
273 The last command produces @file{les-nereides.textmetrics}, which is
274 read when you execute
277 lilypond -b tex input/les-nereides.ly
280 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
281 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
282 interpreting non-ASCII strings.
284 To use a Unicode escape sequence, use
287 #(ly:export (ly:wide-char->utf-8 #x2014))
293 @inputfileref{input/regression,utf-8.ly}
297 @node A single music expression
298 @section A single music expression
300 A @code{\score} must contain a single music expression. However,
301 this music expression may be of any size. Recall that music
302 expressions may be included inside other expressions to form
303 larger expressions. All of these examples are single music
304 expressions; note the curly braces @{ @} or angle brackets <<
305 >> at the beginning and ending of the music.
311 @lilypond[ragged-right,verbatim,quote]
318 @lilypond[ragged-right,verbatim,quote]
320 \new Staff { c'4 c' c' c' }
321 \new Staff { d'4 d' d' d' }
329 \new Staff @{ \flute @}
330 \new Staff @{ \oboe @}
333 \new Staff @{ \violinI @}
334 \new Staff @{ \violinII @}
341 @node Titles and headers
342 @section Titles and headers
344 Almost all printed music includes a title and the composer's name;
345 some pieces include a lot more information.
353 @node Creating titles
354 @subsection Creating titles
356 Titles are created for each @code{\score} block, and over a
359 The contents of the titles are taken from the @code{\header} blocks.
360 The header block for a book supports the following
363 The dedicatee of the music, centered at the top of the first page.
366 The title of the music, centered just below the dedication.
369 Subtitle, centered below the title.
372 Subsubtitle, centered below the subtitle.
375 Name of the poet, flush-left below the subtitle.
378 Name of the composer, flush-right below the subtitle.
381 Meter string, flush-left below the poet.
384 Name of the opus, flush-right below the composer.
387 Name of the arranger, flush-right below the opus.
390 Name of the instrument, centered below the arranger. Also
391 centered at the top of pages (other than the first page).
394 Name of the piece, flush-left below the instrument.
396 @cindex page breaks, forcing
398 This forces the title to start on a new page (set to ##t or ##f).
401 Copyright notice, centered at the bottom of the first page. To
402 insert the copyright symbol, see @ref{Text encoding}.
405 Centered at the bottom of the last page.
409 Here is a demonstration of the fields available. Note that you
410 may use any @ref{Text markup} commands in the header.
412 @lilypond[quote,verbatim,line-width=11.0\cm]
415 paper-height = 10.0\cm
420 dedication = "dedicated to me"
421 title = \markup \center-align { "Title first line" "Title second line,
423 subtitle = "the subtitle,"
424 subsubtitle = #(string-append "subsubtitle LilyPond version "
427 composer = \markup \center-align { "composer" \small "(1847-1973)" }
428 texttranslator = "Text Translator"
429 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
431 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
432 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
433 instrument = \markup \bold \italic "instrument"
457 As demonstrated before, you can use multiple @code{\header} blocks.
458 When same fields appear in different blocks, the latter is used.
459 Here is a short example.
463 composer = "Composer"
471 piece = "New piece" % overwrite previous one
476 If you define the @code{\header} inside the @code{\score} block, then
477 normally only the @code{piece} and @code{opus} headers will be printed.
478 Note that the music expression must come before the @code{\header}.
480 @lilypond[quote,verbatim,line-width=11.0\cm]
484 title = "title" % not printed
491 @cindex @code{printallheaders}
493 You may change this behavior (and print all the headers when defining
494 @code{\header} inside @code{\score}) by using
504 @subsection Custom titles
506 A more advanced option is to change the definitions of the following
507 variables in the @code{\paper} block. The init file
508 @file{ly/titling-init.ly} lists the default layout.
511 @cindex @code{bookTitleMarkup}
512 @item bookTitleMarkup
513 This is the title put over an entire @code{\book} block. Typically,
514 it has the composer and the title of the piece
516 @cindex @code{scoreTitleMarkup}
517 @item scoreTitleMarkup
518 This is the title put over a @code{\score} block within a
519 @code{\book}. Typically, it has the name of the movement (@code{piece}
522 @cindex @code{oddHeaderMarkup}
523 @item oddHeaderMarkup
524 This is the page header for odd-numbered pages.
526 @cindex @code{evenHeaderMarkup}
527 @item evenHeaderMarkup
528 This is the page header for even-numbered pages. If unspecified,
529 the odd header is used instead.
531 By default, headers are defined such that the page number is on the
532 outside edge, and the instrument is centered.
534 @cindex @code{oddFooterMarkup}
535 @item oddFooterMarkup
536 This is the page footer for odd-numbered pages.
538 @cindex @code{evenFotterMarkup}
539 @item evenFooterMarkup
540 This is the page footer for even-numbered pages. If unspecified,
541 the odd header is used instead.
543 By default, the footer has the copyright notice on the first, and
544 the tagline on the last page.
554 The following definition will put the title flush left, and the
555 composer flush right on a single line.
559 bookTitleMarkup = \markup {
561 \fromproperty #'header:title
562 \fromproperty #'header:composer
571 The @code{breakbefore=##t} header requires that there is a @code{piece}
572 header as well. It may be used as a normal header, or left blank
573 (@code{=""}) as in the example above, but it must be present.
577 @node Paper and pages
578 @section Paper and pages
580 This section deals with the display of music on physical paper.
589 @subsection Paper size
593 @cindex @code{papersize}
595 To change the paper size, there are two commands,
597 #(set-default-paper-size "a4")
599 #(set-paper-size "a4")
603 The first command sets the size of all pages. The second command sets the
605 of the pages that the @code{\paper} block applies to -- if the @code{\paper}
606 block is at the top of the file, then it will apply to all pages. If the
607 @code{\paper} block is inside a @code{\book}, then the paper size will only
610 Support for the following paper sizes are included by default,
611 @code{a6}, @code{a5}, @code{a4}, @code{a3}, @code{legal}, @code{letter},
612 @code{11x17} (also known as tabloid).
614 Extra sizes may be added by editing the definition for
615 @code{paper-alist} in the initialization file @file{scm/paper.scm}.
620 If the symbol @code{landscape} is supplied as an argument to
621 @code{set-default-paper-size}, the pages will be rotated by 90 degrees,
622 and wider line widths will be set correspondingly.
625 #(set-default-paper-size "a6" 'landscape)
628 Setting the paper size will adjust a number of @code{\paper} variables
629 (such as margins). To use a particular paper size with altered
630 @code{\paper} variables, set the paper size before setting the variables.
633 @node Page formatting
634 @subsection Page formatting
636 @cindex page formatting
641 LilyPond will do page layout, set margins, and add headers and
642 footers to each page.
644 @cindex @code{annotate-spacing}
645 @cindex Spacing, display of properties
647 To graphically display the dimensions of properties that may
648 be altered for page formatting, use
652 annotate-spacing = ##t
657 All units dimensions are measured in staff spaces. The pairs
658 (@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
659 @var{b} the upper edge of the interval.
661 The default layout responds to the following settings in the
664 @cindex @code{\paper}
668 @cindex @code{first-page-number}
669 @item first-page-number
670 The value of the page number of the first page. Default is@tie{}1.
672 @cindex @code{printfirst-page-number}
673 @item printfirst-page-number
674 If set to true, will print the page number in the first page. Default is
677 @cindex @code{print-page-number}
678 @item print-page-number
679 If set to false, page numbers will not be printed.
681 @cindex @code{paper-width}
683 The width of the page.
685 @cindex @code{paper-height}
687 The height of the page.
689 @cindex @code{top-margin}
691 Margin between header and top of the page.
693 @cindex @code{bottom-margin}
695 Margin between footer and bottom of the page.
697 @cindex @code{left-margin}
699 Margin between the left side of the page and the beginning of the music.
701 @cindex @code{line-width}
703 The length of the systems.
705 @cindex @code{head-separation}
706 @item head-separation
707 Distance between the top-most music system and the page header.
709 @cindex @code{foot-separation}
710 @item foot-separation
711 Distance between the bottom-most music system and the page footer.
713 @cindex @code{page-top-space}
714 Distance from the top of the printable area to the center of the first
715 staff. This only works for staves which are vertically small. Big staves
716 are set with the top of their bounding box aligned to the top of the
719 @cindex @code{ragged-bottom}
721 If set to true, systems will not be spread vertically across the page. This
722 does not affect the last page.
724 This should be set to true for pieces that have only two or three
725 systems per page, for example orchestral scores.
727 @cindex @code{ragged-last-bottom}
728 @item ragged-last-bottom
729 If set to false, systems will be spread vertically to fill the last page.
731 Pieces that amply fill two pages or more should have this set to
734 @cindex @code{system-count}
736 This variable, if set, specifies into how many lines a score should be
739 @cindex @code{between-system-space}
740 @item between-system-space
741 This dimensions determines the distance between systems. It is the
742 ideal distance between the center of the bottom staff of one system
743 and the center of the top staff of the next system.
745 Increasing this will provide a more even appearance of the page at the
746 cost of using more vertical space.
748 @cindex @code{between-system-padding}
749 @item between-system-padding
750 This dimension is the minimum amount of white space that will always
751 be present between the bottom-most symbol of one system, and the
752 top-most of the next system.
754 Increasing this will put systems whose bounding boxes almost touch
758 @cindex @code{horizontal-shift}
759 @item horizontal-shift
760 All systems (including titles and system separators) are shifted by
761 this amount to the right. Page markup, such as headers and footers are
762 not affected by this. The purpose of this variable is to make space
763 for instrument names at the left.
765 @cindex @code{after-title-space}
766 @item after-title-space
767 Amount of space between the title and the first system.
769 @cindex @code{after-title-space}
770 @item before-title-space
771 Amount of space between the last system of the previous piece and the
774 @cindex @code{between-title-space}
775 @item between-title-space
776 Amount of space between consecutive titles (e.g., the title of the
777 book and the title of a piece).
779 @cindex @code{printallheaders}
780 @item printallheaders
781 Setting this to #t will print all headers for each \score in a
782 \book. Normally only the piece and opus \headers are printed.
784 @cindex @code{systemSeparatorMarkup}
785 @item systemSeparatorMarkup
786 This contains a markup object, which will be inserted between
787 systems. This is often used for orchestral scores.
789 The markup command @code{\slashSeparator} is provided as a sensible
792 @lilypond[ragged-right]
795 \relative { c1 \break c1 }
798 systemSeparatorMarkup = \slashSeparator
814 ragged-last-bottom = ##t
818 You can also define these values in Scheme. In that case @code{mm},
819 @code{in}, @code{pt}, and @code{cm} are variables defined in
820 @file{paper-defaults.ly} with values in millimeters. That's why the
821 value has to be multiplied in the example
825 #(define bottom-margin (* 2 cm))
832 The default footer is empty, except for the first page, where the
833 @code{copyright} field from @code{\header} is inserted, and the last
834 page, where @code{tagline} from @code{\header} is added. The default
835 tagline is ``Music engraving by LilyPond (@var{version})''.@footnote{Nicely
836 printed parts are good PR for us, so please leave the tagline if you
839 The header and footer are created by the functions @code{make-footer}
840 and @code{make-header}, defined in @code{\paper}. The default
841 implementations are in @file{ly/@/paper@/-defaults@/.ly} and
842 @file{ly/@/titling@/-init@/.ly}.
844 The page layout itself is done by two functions in the
845 @code{\paper} block, @code{page-music-height} and
846 @code{page-make-stencil}. The former tells the line-breaking algorithm
847 how much space can be spent on a page, the latter creates the actual
848 page given the system to put on it.
853 The option right-margin is defined but doesn't set the right margin
854 yet. The value for the right margin has to be defined adjusting the
855 values of @code{left-margin} and @code{line-width}.
857 The default page header puts the page number and the @code{instrument}
858 field from the @code{\header} block on a line.
860 The titles (from the @code{\header@{@}} section) are treated as a
861 system, so @code{ragged-bottom} and @code{ragged-last-bottom} will
862 add space between the titles and the first system of the score.
866 @section Music layout
868 This section deals with the manner in which the music is printed
869 within the boundaries defined by the @code{\paper} block.
871 The global paper layout is determined by three factors: the page layout, the
872 line breaks, and the spacing. These all influence each other. The
873 choice of spacing determines how densely each system of music is set.
874 This influences where line breaks are chosen, and thus ultimately, how
875 many pages a piece of music takes.
877 Globally spoken, this procedure happens in three steps: first,
878 flexible distances (``springs'') are chosen, based on durations. All
879 possible line breaking combinations are tried, and the one with the
880 best results -- a layout that has uniform density and requires as
881 little stretching or cramping as possible -- is chosen.
883 After spacing and linebreaking, the systems are distributed across
884 pages, taking into account the size of the page, and the size of the
888 * Setting global staff size::
889 * Selecting notation font size::
892 * Vertical spacing of piano staves::
893 * Horizontal spacing::
900 @node Setting global staff size
901 @subsection Setting global staff size
903 @cindex font size, setting
904 @cindex staff size, setting
905 @cindex @code{layout} file
907 To set the global staff size, use @code{set-global-staff-size}.
910 #(set-global-staff-size 14)
914 This sets the global default size to 14pt staff height and scales all
917 The Feta font provides musical symbols at eight different
918 sizes. Each font is tuned for a different staff size: at a smaller size
919 the font becomes heavier, to match the relatively heavier staff lines.
920 The recommended font sizes are listed in the following table:
923 @multitable @columnfractions .15 .2 .22 .2
926 @tab @b{staff height (pt)}
927 @tab @b{staff height (mm)}
969 @c modern rental material?
974 These fonts are available in any sizes. The context property
975 @code{fontSize} and the layout property @code{staff-space} (in
976 @internalsref{StaffSymbol}) can be used to tune the size for individual
977 staves. The sizes of individual staves are relative to the global size.
985 This manual: @ref{Selecting notation font size}.
988 @node Selecting notation font size
989 @subsection Selecting notation font size
991 The easiest method of setting the font size of any context, is by
992 setting the @code{fontSize} property.
994 @lilypond[quote,fragment,relative=1,verbatim]
1003 It does not change the size of variable symbols, such as beams or
1006 Internally, the @code{fontSize} context property will cause the
1007 @code{font-size} property to be set in all layout objects. The value
1008 of @code{font-size} is a number indicating the size relative to the
1009 standard size for the current staff height. Each step up is an
1010 increase of approximately 12% of the font size. Six steps is exactly a
1011 factor two. The Scheme function @code{magstep} converts a
1012 @code{font-size} number to a scaling factor.
1014 @lilypond[quote,fragment,relative=1,verbatim]
1016 \override NoteHead #'font-size = #-4
1018 \override NoteHead #'font-size = #3
1022 LilyPond has fonts in different design sizes. The music fonts for
1023 smaller sizes are chubbier, while the text fonts are relatively wider.
1024 Font size changes are achieved by scaling the design size that is
1025 closest to the desired size. The standard font size (for
1026 @code{font-size} equals 0), depends on the standard staff height. For
1027 a 20pt staff, a 10pt font is selected.
1029 The @code{font-size} property can only be set on layout objects that
1030 use fonts. These are the ones supporting the
1031 @internalsref{font-interface} layout interface.
1035 The following commands set @code{fontSize} for the current voice:
1037 @cindex @code{\tiny}
1039 @cindex @code{\small}
1041 @cindex @code{\normalsize}
1046 @subsection Score layout
1048 @cindex @code{\layout}
1050 While @code{\paper} contains settings that relate to the page formatting
1051 of the whole document, @code{\layout} contains settings for score-specific
1058 \override VerticalAxisGroup #'minimum-Y-extent = #'(-6 . 6)
1061 \override TextScript #'padding = #1.0
1062 \override Glissando #'thickness = #3
1070 This manual: @ref{Changing context default settings}
1073 @node Vertical spacing
1074 @subsection Vertical spacing
1076 @cindex vertical spacing
1077 @cindex distance between staves
1078 @cindex staff distance
1079 @cindex between staves, distance
1080 @cindex staves per page
1081 @cindex space between staves
1083 The height of each system is determined automatically. To prevent
1084 systems from bumping into each other, some minimum distances are set.
1085 By changing these, you can put staves closer together, and thus put
1086 more systems onto one page.
1088 Normally staves are stacked vertically. To make staves maintain a
1089 distance, their vertical size is padded. This is done with the
1090 property @code{minimum-Y-extent}. When applied to a
1091 @internalsref{VerticalAxisGroup}, it controls the size of a horizontal
1092 line, such as a staff or a line of lyrics. @code{minimum-Y-extent}
1093 takes a pair of numbers, so
1094 if you want to make it smaller than its default @code{#'(-4 . 4)}
1098 \override Staff.VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
1102 This sets the vertical size of the current staff to 3 staff spaces on
1103 either side of the center staff line. The value @code{(-3 . 3)} is
1104 interpreted as an interval, where the center line is the 0, so the
1105 first number is generally negative. The staff can be made larger at
1106 the bottom by setting it to @code{(-6 . 4)}.
1108 The spacing of staves in a system may also be tuned per system. This is
1109 done with the command
1113 #"Score.NonMusicalPaperColumn"
1114 #'line-break-system-details
1115 #'((alignment-extra-space . 15))
1119 at the line break before the system to be changed. The distance
1120 @code{15} is distributed over all staves that have a fixed distance
1121 alignment. For example,
1123 @lilypond[ragged-right, fragment, relative=2, staffsize=13]
1129 #"Score.NonMusicalPaperColumn"
1130 #'line-break-system-details
1131 #'((fixed-alignment-extra-space . 15))
1139 The distance for @code{alignment-extra-space} may also be negative.
1142 To change the amount of space between systems, use
1143 @code{between-system-space}. A score with only one staff is still
1144 considered to have systems, so setting @code{between-system-space} will
1145 be much more useful than changing @code{minimum-Y-extent} of a Staff
1150 between-system-space = 10\mm
1154 If you simply want to tell LilyPond ``fit as much as possible onto
1155 these pages, then expand to fill any available space on the pages,''
1156 then use the following
1160 between-system-padding = #1
1162 ragged-last-bottom=##f
1167 @c let's wait for a some comments before writing more.
1169 The vertical spacing on a page can also be changed for each system
1171 Some examples are found in the example file
1172 @inputfileref{input/regression/,page-spacing.ly}.
1174 When setting @code{annotate-spacing} in the @code{\paper} block LilyPond
1175 will graphically indicate the dimensions of properties that may be set
1179 #(set-default-paper-size "a7" 'landscape)
1180 \paper { annotate-spacing = ##t }
1185 All units dimensions are measured in staff spaces. The pairs
1186 (@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
1187 @var{b} the upper edge of the interval.
1191 Internals: Vertical alignment of staves is handled by the
1192 @internalsref{VerticalAlignment} object. The context parameters
1193 specifying the vertical extent are described in connection with
1194 the @internalsref{Axis_group_engraver}.
1196 Example files: @inputfileref{input/regression/,page-spacing.ly},
1197 @inputfileref{input/regression/,alignment-vertical-spacing.ly}.
1202 @node Vertical spacing of piano staves
1203 @subsection Vertical spacing of piano staves
1205 The distance between staves of a @internalsref{PianoStaff} cannot be
1206 computed during formatting. Rather, to make cross-staff beaming work
1207 correctly, that distance has to be fixed beforehand.
1209 The distance of staves in a @code{PianoStaff} is set with the
1210 @code{forced-distance} property of the
1211 @internalsref{VerticalAlignment} object, created in
1212 @internalsref{PianoStaff}.
1214 It can be adjusted as follows
1216 \new PianoStaff \with @{
1217 \override VerticalAlignment #'forced-distance = #7
1224 This would bring the staves together at a distance of 7 staff spaces,
1225 measured from the center line of each staff.
1227 The difference is demonstrated in the following example,
1228 @lilypond[quote,verbatim]
1230 \new PianoStaff \with {
1231 \override VerticalAlignment #'forced-distance = #7
1244 It is also possible to change the distance between for each system
1245 individually. This is done by including the command
1249 #"Score.NonMusicalPaperColumn"
1250 #'line-break-system-details
1251 #'((fixed-alignment-extra-space . 15))
1255 at the line break before the system to be changed. The distance
1256 @code{15} is distributed over all staves that have a fixed distance
1257 alignment. For example,
1259 @lilypond[ragged-right, fragment, relative=2, staffsize=13]
1265 #"Score.NonMusicalPaperColumn"
1266 #'line-break-system-details
1267 #'((fixed-alignment-extra-space . 15))
1275 The distance for @code{fixed-alignment-extra-space} may also be
1280 Example files: @inputfileref{input/regression/,alignment-vertical-spacing.ly}.
1282 @node Horizontal spacing
1283 @subsection Horizontal Spacing
1285 The spacing engine translates differences in durations into stretchable
1286 distances (``springs'') of differring lengths. Longer durations get
1287 more space, shorter durations get less. The shortest durations get a
1288 fixed amount of space (which is controlled by
1289 @code{shortest-duration-space} in the @internalsref{SpacingSpanner}
1290 object). The longer the duration, the more space it gets: doubling a
1291 duration adds a fixed amount (this amount is controlled by
1292 @code{spacing-increment}) of space to the note.
1294 For example, the following piece contains lots of half, quarter, and
1295 8th notes; the eighth note is followed by 1 note head width (NHW).
1296 The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
1298 @lilypond[quote,fragment,verbatim,relative=1]
1299 c2 c4. c8 c4. c8 c4. c8 c8
1303 Normally, @code{spacing-increment} is set to 1.2 staff space, which is
1304 approximately the width of a note head, and
1305 @code{shortest-duration-space} is set to 2.0, meaning that the
1306 shortest note gets 2.4 staff space (2.0 times the
1307 @code{spacing-increment}) of horizontal space. This space is counted
1308 from the left edge of the symbol, so the shortest notes are generally
1309 followed by one NHW of space.
1311 If one would follow the above procedure exactly, then adding a single
1312 32nd note to a score that uses 8th and 16th notes, would widen up the
1313 entire score a lot. The shortest note is no longer a 16th, but a 32nd,
1314 thus adding 1 NHW to every note. To prevent this, the shortest
1315 duration for spacing is not the shortest note in the score, but rather
1316 the one which occurs most frequently.
1319 The most common shortest duration is determined as follows: in every
1320 measure, the shortest duration is determined. The most common shortest
1321 duration is taken as the basis for the spacing, with the stipulation
1322 that this shortest duration should always be equal to or shorter than
1323 an 8th note. The shortest duration is printed when you run
1324 @code{lilypond} with the @code{--verbose} option.
1326 These durations may also be customized. If you set the
1327 @code{common-shortest-duration} in @internalsref{SpacingSpanner}, then
1328 this sets the base duration for spacing. The maximum duration for this
1329 base (normally an 8th), is set through @code{base-shortest-duration}.
1331 @cindex @code{common-shortest-duration}
1332 @cindex @code{base-shortest-duration}
1333 @cindex @code{stem-spacing-correction}
1334 @cindex @code{spacing}
1336 Notes that are even shorter than the common shortest note are
1337 followed by a space that is proportional to their duration relative to
1338 the common shortest note. So if we were to add only a few 16th notes
1339 to the example above, they would be followed by half a NHW:
1341 @lilypond[quote,fragment,verbatim,relative=2]
1342 c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
1346 In the introduction (see @ref{Engraving}), it was explained that stem
1347 directions influence spacing. This is controlled with the
1348 @code{stem-spacing-correction} property in the
1349 @internalsref{NoteSpacing}, object. These are generated for every
1350 @internalsref{Voice} context. The @code{StaffSpacing} object
1351 (generated in @internalsref{Staff} context) contains the same property
1352 for controlling the stem/bar line spacing. The following example shows
1353 these corrections, once with default settings, and once with
1354 exaggerated corrections:
1356 @lilypond[quote,ragged-right]
1360 \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
1361 \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
1367 Proportional notation is supported; see @ref{Proportional notation}.
1369 By default, spacing in tuplets depends on various non-duration
1370 factors (such as accidentals, clef changes, etc). To disregard
1371 such symbols and force uniform equal-duration spacing, use
1372 @code{Score.SpacingSpanner #'uniform-stretching}. This
1373 property can only be changed at the beginning of a score,
1375 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1377 \override SpacingSpanner #'uniform-stretching = ##t
1395 When @code{strict-note-spacing} is set, notes are spaced without
1396 regard for clefs, bar lines, and grace notes,
1398 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1399 \override Score.SpacingSpanner #'strict-note-spacing = ##t
1400 \new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c] c32[ c32] }
1406 Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
1407 @internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
1408 @internalsref{SeparatingGroupSpanner}.
1412 Spacing is determined on a score wide basis. If you have a score that
1413 changes its character (measured in durations) halfway during the
1414 score, the part containing the longer durations will be spaced too
1417 There is no convenient mechanism to manually override spacing. The
1418 following work-around may be used to insert extra space into a score.
1420 \once \override Score.SeparationItem #'padding = #1
1423 No work-around exists for decreasing the amount of space.
1427 @subsection Line length
1430 @cindex breaking pages
1432 @cindex @code{indent}
1433 @cindex @code{line-width}
1434 @cindex @code{ragged-right}
1435 @cindex @code{ragged-last}
1437 @c Although line-width can be set in \layout, it should be set in paper
1438 @c block, to get page layout right.
1439 @c Setting indent in \paper block makes not much sense, but it works.
1441 @c Bit verbose and vague, use examples?
1442 The most basic settings influencing the spacing are @code{indent} and
1443 @code{line-width}. They are set in the @code{\layout} block. They
1444 control the indentation of the first line of music, and the lengths of
1447 If @code{ragged-right} is set to true in the @code{\layout} block, then
1448 systems ends at their natural horizontal length, instead of being spread
1449 horizontally to fill the whole line. This is useful for
1450 short fragments, and for checking how tight the natural spacing is.
1453 @cindex vertical spacing
1455 The option @code{ragged-last} is similar to @code{ragged-right}, but
1456 only affects the last line of the piece. No restrictions are put on
1457 that line. The result is similar to formatting text paragraphs. In a
1458 paragraph, the last line simply takes its natural horizontal length.
1459 @c Note that for text there are several options for the last line.
1460 @c While Knuth TeX uses natural length, lead typesetters use the same
1461 @c stretch as the previous line. eTeX uses \lastlinefit to
1462 @c interpolate between both these solutions.
1474 @subsection Line breaking
1477 @cindex breaking lines
1479 Line breaks are normally computed automatically. They are chosen so
1480 that lines look neither cramped nor loose, and that consecutive lines
1481 have similar density.
1483 Occasionally you might want to override the automatic breaks; you can
1484 do this by specifying @code{\break}. This will force a line break at
1485 this point. Line breaks can only occur at places where there are bar
1486 lines. If you want to have a line break where there is no bar line,
1487 you can force an invisible bar line by entering @code{\bar
1488 ""}. Similarly, @code{\noBreak} forbids a line break at a
1492 @cindex regular line breaks
1493 @cindex four bar music.
1495 For line breaks at regular intervals use @code{\break} separated by
1496 skips and repeated with @code{\repeat}:
1498 << \repeat unfold 7 @{
1499 s1 \noBreak s1 \noBreak
1500 s1 \noBreak s1 \break @}
1501 @emph{the real music}
1506 This makes the following 28 measures (assuming 4/4 time) be broken every
1507 4 measures, and only there.
1511 @code{\break}, and @code{\noBreak}.
1512 @cindex @code{\break}
1513 @cindex @code{\noBreak}
1517 Internals: @internalsref{BreakEvent}.
1519 A linebreaking configuration can now be saved as a @code{.ly} file
1520 automatically. This allows vertical alignments to be stretched to
1521 fit pages in a second formatting run. This is fairly new and
1522 complicated; see @inputfileref{input/regression/,page-layout-twopass.ly}
1527 Line breaks can only occur if there is a ``proper'' bar line. A note
1528 which is hanging over a bar line is not proper, such as
1530 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1531 c4 c2 c2 \break % this does nothing
1532 c2 c4 | % a break here would work
1533 c4 c2 c4 ~ \break % as does this break
1539 @subsection Page breaking
1541 The default page breaking may be overriden by inserting
1542 @code{\pageBreak} or @code{\noPageBreak} commands. These commands are
1543 analogous to @code{\break} and @code{\noBreak}. They should be
1544 inserted at a bar line. These commands force and forbid a page-break
1545 from happening. Of course, the @code{\pageBreak} command also forces
1548 Page breaks are computed by the @code{page-breaking} function in the
1549 @code{\paper} block.
1551 To force a new page for a new piece (in a collection of pieces or a
1552 piece in several movements), use @code{breakbefore} in the header.
1563 @cindex @code{\pageBreak}
1565 @cindex @code{\noPageBreak}
1571 The @code{breakbefore=##t} header requires that there is a @code{piece}
1572 header as well. It may be used as a normal header, or left blank
1573 (@code{=""}) as in the example above, but it must be present.
1577 @node Multiple movements
1578 @section Multiple movements
1580 @cindex bibliographic information
1583 @cindex Music engraving by LilyPond
1585 A document may contain multiple pieces of music and texts. Examples
1586 of these are an etude book, or an orchestral part with multiple
1587 movements. Each movement is entered with a @code{\score} block,
1595 and texts are entered with a @code{\markup} block,
1603 @cindex @code{\book}
1605 The movements and texts are combined together in a @code{\book} block,
1623 The header for each piece of music can be put inside the @code{\score}
1624 block. The @code{piece} name from the header will be printed before
1625 each movement. The title for the entire book can be put inside the
1626 @code{\book}, but if it is not present, the @code{\header} which is at
1627 the top of the file is inserted.
1629 @cindex Engraved by LilyPond
1630 @cindex signature line
1635 title = "Eight miniatures"
1636 composer = "Igor Stravinsky"
1640 \header @{ piece = "Romanze" @}
1643 ..text of second verse..
1646 ..text of third verse..
1650 \header @{ piece = "Menuetto" @}
1658 @section MIDI output
1663 MIDI (Musical Instrument Digital Interface) is a standard for
1664 connecting and controlling digital instruments. A MIDI file is a
1665 series of notes in a number of tracks. It is not an actual
1666 sound file; you need special software to translate between the
1667 series of notes and actual sounds.
1669 Pieces of music can be converted to MIDI files, so you can listen to
1670 what was entered. This is convenient for checking the music; octaves
1671 that are off or accidentals that were mistyped stand out very much
1672 when listening to the MIDI output.
1676 Many musically interesting effects, such as swing, articulation,
1677 slurring, etc., are not translated to midi.
1679 The midi output allocates a channel for each staff, and one for global
1680 settings. Therefore the midi file should not have more than 15 staves
1681 (or 14 if you do not use drums). Other staves will remain silent.
1683 Not all midi players correctly handle tempo changes in the midi
1684 output. Players that are known to work include
1685 @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
1688 * Creating MIDI files::
1690 * MIDI instrument names::
1693 @node Creating MIDI files
1694 @subsection Creating MIDI files
1696 To create a MIDI from a music piece of music, add a @code{\midi} block
1697 to a score, for example,
1702 \midi @{ \tempo 4=72 @}
1706 The tempo is specified using the @code{\tempo} command. In this
1707 example the tempo of quarter notes is set to 72 beats per minute.
1710 If there is a @code{\midi} command in a @code{\score}, only MIDI will
1711 be produced. When notation is needed too, a @code{\layout} block must
1717 \midi @{ \tempo 4=72 @}
1721 @cindex layout block
1725 Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
1726 crescendi and decrescendi translate into MIDI volume levels. Dynamic
1727 marks translate to a fixed fraction of the available MIDI volume
1728 range, crescendi and decrescendi make the volume vary linearly between
1729 their two extremes. The fractions can be adjusted by
1730 @code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
1731 For each type of MIDI instrument, a volume range can be defined. This
1732 gives a basic equalizer control, which can enhance the quality of
1733 the MIDI output remarkably. The equalizer can be controlled by
1734 setting @code{instrumentEqualizer}, or by setting
1737 \set Staff.midiMinimumVolume = #0.2
1738 \set Staff.midiMaximumVolume = #0.8
1741 To remove dynamics from the MIDI output, insert the following lines
1742 in the @code{\midi@{@}} section.
1749 \remove "Dynamic_performer"
1750 \remove "Span_dynamic_performer"
1758 Unterminated (de)crescendos will not render properly in the midi file,
1759 resulting in silent passages of music. The workaround is to explicitly
1760 terminate the (de)crescendo. For example,
1767 will not work properly but
1778 @subsection MIDI block
1782 The MIDI block is analogous to the layout block, but it is somewhat
1783 simpler. The @code{\midi} block can contain
1787 @item a @code{\tempo} definition, and
1788 @item context definitions.
1791 A number followed by a period is interpreted as a real number, so
1792 for setting the tempo for dotted notes, an extra space should be
1793 inserted, for example
1796 \midi @{ \tempo 4 . = 120 @}
1800 @cindex context definition
1802 Context definitions follow precisely the same syntax as within the
1803 \layout block. Translation modules for sound are called performers.
1804 The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
1807 @node MIDI instrument names
1808 @subsection MIDI instrument names
1810 @cindex instrument names
1811 @cindex @code{Staff.midiInstrument}
1813 The MIDI instrument name is set by the @code{Staff.midiInstrument}
1814 property. The instrument name should be chosen from the list in
1815 @ref{MIDI instruments}.
1818 \set Staff.midiInstrument = "glockenspiel"
1822 If the selected instrument does not exactly match an instrument from
1823 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})