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::
29 The main format of input for LilyPond are text files. By convention,
30 these files end with ``@code{.ly}''.
33 * File structure (introduction)::
35 * Including LilyPond files::
40 @node File structure (introduction)
41 @subsection File structure (introduction)
43 A basic example of a lilypond input file is
48 @{ @} % this is a single music expression;
49 % all the music goes in here.
57 There are many variations of this basic pattern, but this
58 example serves as a useful starting place.
60 The major part of this manual is concerned with entering various
61 forms of music in LilyPond. However, many music expressions are not
62 valid input on their own, for example, a @code{.ly} file containing
69 will result in a parsing error. Instead, music should be inside other
70 expressions, which may be put in a file by themselves. Such
71 expressions are called toplevel expressions. The next section enumerates
76 @subsection File structure
78 A @code{.ly} file contains any number of toplevel expressions, where a
79 toplevel expression is one of the following
83 An output definition, such as @code{\paper}, @code{\midi}, and
84 @code{\layout}. Such a definition at the toplevel changes the default
85 settings for the block entered.
88 A direct scheme expression, such as
89 @code{#(set-default-paper-size "a7" 'landscape)} or
90 @code{#(ly:set-option 'point-and-click #f)}.
93 A @code{\header} block. This sets the global header block. This
94 is the block containing the definitions for book-wide settings, like
98 An @code{\addquote} statement. See @ref{Quoting other voices}
102 A @code{\score} block. This score will be collected with other
103 toplevel scores, and combined as a single @code{\book}.
105 This behavior can be changed by setting the variable
106 @code{toplevel-score-handler} at toplevel. The default handler is
107 defined in the init file @file{scm/@/lily@/.scm}.
109 The @code{\score} must begin with a music expression, and may
110 contain only one music expression.
113 A @code{\book} block logically combines multiple movements
114 (i.e., multiple @code{\score} blocks) in one document. If there are
115 a number of @code{\scores}, a single output file will be created
116 in which all movements are concatenated.
118 This behavior can be changed by setting the variable
119 @code{toplevel-book-handler} at toplevel. The default handler is
120 defined in the init file @file{scm/@/lily@/.scm}.
123 A compound music expression, such as
128 This will add the piece in a @code{\score} and format it in a
129 single book together with all other toplevel @code{\score}s and music
130 expressions. In other words, a file containing only the above
131 music expression will be translated into
147 This behavior can be changed by setting the variable
148 @code{toplevel-music-handler} at toplevel. The default handler is
149 defined in the init file @file{scm/@/lily@/.scm}.
152 A markup text, a verse for example
155 2. The first line verse two.
159 Markup texts are rendered above, between or below the scores or music
160 expressions, wherever they appear.
163 An identifier, such as
168 This can be used later on in the file by entering @code{\foo}. The
169 name of an identifier should have alphabetic characters only; no
170 numbers, underscores or dashes.
174 The following example shows three things that may be entered at
179 % movements are non-justified by default
191 At any point in a file, any of the following lexical instructions can
195 @item @code{\version}
196 @item @code{\include}
197 @item @code{\renameinput}
201 @node Including LilyPond files
202 @subsection Including LilyPond files
204 @cindex @code{\include}
205 @cindex including files
207 A large project may be split up into separate files. To refer to another
211 \include "otherfile.ly"
214 The line @code{\include "file.ly"} is equivalent to pasting the contents
215 of file.ly into the current file at the place where you have the
216 \include. For example, for a large project you might write separate files
217 for each instrument part and create a ``full score'' file which brings
218 together the individual instrument files.
220 The initialization of LilyPond is done in a number of files that are
221 included by default when you start the program, normally transparent to the
222 user. Run lilypond --verbose to see a list of paths and files that Lily
225 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
226 VERSION is in the form ``2.6.1'') are on the path and available to
227 @code{\include}. Files in the
228 current working directory are available to \include, but a file of the same
229 name in LilyPond's installation takes precedence. Files are
230 available to \include from directories in the search path specified as an
231 option when invoking @code{lilypond --include=DIR} which adds DIR to the
234 The @code{\include} statement can use full path information, but with the Unix
235 convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example,
236 if @file{stuff.ly} is located one directory higher than the current working
240 \include "../stuff.ly"
245 @subsection Text encoding
247 LilyPond uses the Pango library to format multi-lingual texts, and
248 does not perform any input-encoding conversions. This means that any
249 text, be it title, lyric text, or musical instruction containing
250 non-ASCII characters, must be utf-8. The easiest way to enter such text is
251 by using a Unicode-aware editor and saving the file with utf-8 encoding. Most
252 popular modern editors have utf-8 support, for example, vim, Emacs,
255 Depending on the fonts installed, the following fragment shows Hebrew
262 @lilypondfile[fontload]{utf-8.ly}
264 The @TeX{} backend does not handle encoding specially at all. Strings
265 in the input are put in the output as-is. Extents of text items in the
266 @TeX{} backend, are determined by reading a file created via the
267 @file{texstr} backend,
270 lilypond -b texstr input/les-nereides.ly
271 latex les-nereides.texstr
274 The last command produces @file{les-nereides.textmetrics}, which is
275 read when you execute
278 lilypond -b tex input/les-nereides.ly
281 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
282 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
283 interpreting non-ASCII strings.
285 To use a Unicode escape sequence, use
288 #(ly:export (ly:wide-char->utf-8 #x2014))
294 @inputfileref{input/regression,utf-8.ly}
298 @node A single music expression
299 @section A single music expression
301 A @code{\score} must contain a single music expression. However,
302 this music expression may be of any size. Recall that music
303 expressions may be included inside other expressions to form
304 larger expressions. All of these examples are single music
305 expressions; note the curly braces @{ @} or angle brackets <<
306 >> at the beginning and ending of the music.
312 @lilypond[ragged-right,verbatim,quote]
319 @lilypond[ragged-right,verbatim,quote]
321 \new Staff { c'4 c' c' c' }
322 \new Staff { d'4 d' d' d' }
330 \new Staff @{ \flute @}
331 \new Staff @{ \oboe @}
334 \new Staff @{ \violinI @}
335 \new Staff @{ \violinII @}
342 @node Titles and headers
343 @section Titles and headers
345 Almost all printed music includes a title and the composer's name;
346 some pieces include a lot more information.
354 @node Creating titles
355 @subsection Creating titles
357 Titles are created for each @code{\score} block, and over a
360 The contents of the titles are taken from the @code{\header} blocks.
361 The header block for a book supports the following
364 The dedicatee of the music, centered at the top of the first page.
367 The title of the music, centered just below the dedication.
370 Subtitle, centered below the title.
373 Subsubtitle, centered below the subtitle.
376 Name of the poet, flush-left below the subtitle.
379 Name of the composer, flush-right below the subtitle.
382 Meter string, flush-left below the poet.
385 Name of the opus, flush-right below the composer.
388 Name of the arranger, flush-right below the opus.
391 Name of the instrument, centered below the arranger. Also
392 centered at the top of pages (other than the first page).
395 Name of the piece, flush-left below the instrument.
397 @cindex page breaks, forcing
399 This forces the title to start on a new page (set to ##t or ##f).
402 Copyright notice, centered at the bottom of the first page. To
403 insert the copyright symbol, see @ref{Text encoding}.
406 Centered at the bottom of the last page.
410 Here is a demonstration of the fields available. Note that you
411 may use any @ref{Text markup} commands in the header.
413 @lilypond[quote,verbatim,line-width=11.0\cm]
416 paper-height = 10.0\cm
421 dedication = "dedicated to me"
422 title = \markup \center-align { "Title first line" "Title second line,
424 subtitle = "the subtitle,"
425 subsubtitle = #(string-append "subsubtitle LilyPond version "
428 composer = \markup \center-align { "composer" \small "(1847-1973)" }
429 texttranslator = "Text Translator"
430 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge
432 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize
433 #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
434 instrument = \markup \bold \italic "instrument"
458 As demonstrated before, you can use multiple @code{\header} blocks.
459 When same fields appear in different blocks, the latter is used.
460 Here is a short example.
464 composer = "Composer"
472 piece = "New piece" % overwrite previous one
477 If you define the @code{\header} inside the @code{\score} block, then
478 normally only the @code{piece} and @code{opus} headers will be printed.
479 Note that the music expression must come before the @code{\header}.
481 @lilypond[quote,verbatim,line-width=11.0\cm]
485 title = "title" % not printed
492 @cindex @code{printallheaders}
494 You may change this behavior (and print all the headers when defining
495 @code{\header} inside @code{\score}) by using
505 @subsection Custom titles
507 A more advanced option is to change the definitions of the following
508 variables in the @code{\paper} block. The init file
509 @file{ly/titling-init.ly} lists the default layout.
512 @cindex @code{bookTitleMarkup}
513 @item bookTitleMarkup
514 This is the title put over an entire @code{\book} block. Typically,
515 it has the composer and the title of the piece
517 @cindex @code{scoreTitleMarkup}
518 @item scoreTitleMarkup
519 This is the title put over a @code{\score} block within a
520 @code{\book}. Typically, it has the name of the movement (@code{piece}
523 @cindex @code{oddHeaderMarkup}
524 @item oddHeaderMarkup
525 This is the page header for odd-numbered pages.
527 @cindex @code{evenHeaderMarkup}
528 @item evenHeaderMarkup
529 This is the page header for even-numbered pages. If unspecified,
530 the odd header is used instead.
532 By default, headers are defined such that the page number is on the
533 outside edge, and the instrument is centered.
535 @cindex @code{oddFooterMarkup}
536 @item oddFooterMarkup
537 This is the page footer for odd-numbered pages.
539 @cindex @code{evenFotterMarkup}
540 @item evenFooterMarkup
541 This is the page footer for even-numbered pages. If unspecified,
542 the odd header is used instead.
544 By default, the footer has the copyright notice on the first, and
545 the tagline on the last page.
555 The following definition will put the title flush left, and the
556 composer flush right on a single line.
560 bookTitleMarkup = \markup {
562 \fromproperty #'header:title
563 \fromproperty #'header:composer
572 The @code{breakbefore=##t} header requires that there is a @code{piece}
573 header as well. It may be used as a normal header, or left blank
574 (@code{=""}) as in the example above, but it must be present.
578 @node Paper and pages
579 @section Paper and pages
581 This section deals with the display of music on physical paper.
590 @subsection Paper size
594 @cindex @code{papersize}
596 To change the paper size, there are two commands,
598 #(set-default-paper-size "a4")
600 #(set-paper-size "a4")
604 The first command sets the size of all pages. The second command sets the
606 of the pages that the @code{\paper} block applies to -- if the @code{\paper}
607 block is at the top of the file, then it will apply to all pages. If the
608 @code{\paper} block is inside a @code{\book}, then the paper size will only
611 Support for the following paper sizes are included by default,
612 @code{a6}, @code{a5}, @code{a4}, @code{a3}, @code{legal}, @code{letter},
613 @code{11x17} (also known as tabloid).
615 Extra sizes may be added by editing the definition for
616 @code{paper-alist} in the initialization file @file{scm/paper.scm}.
621 If the symbol @code{landscape} is supplied as an argument to
622 @code{set-default-paper-size}, the pages will be rotated by 90 degrees,
623 and wider line widths will be set correspondingly.
626 #(set-default-paper-size "a6" 'landscape)
629 Setting the paper size will adjust a number of @code{\paper} variables
630 (such as margins). To use a particular paper size with altered
631 @code{\paper} variables, set the paper size before setting the variables.
634 @node Page formatting
635 @subsection Page formatting
637 @cindex page formatting
642 LilyPond will do page layout, set margins, and add headers and
643 footers to each page.
645 @cindex @code{annotate-spacing}
646 @cindex Spacing, display of properties
648 To graphically display the dimensions of properties that may
649 be altered for page formatting, use
653 annotate-spacing = ##t
658 All units dimensions are measured in staff spaces. The pairs
659 (@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
660 @var{b} the upper edge of the interval.
662 The default layout responds to the following settings in the
665 @cindex @code{\paper}
669 @cindex @code{first-page-number}
670 @item first-page-number
671 The value of the page number of the first page. Default is@tie{}1.
673 @cindex @code{printfirst-page-number}
674 @item printfirst-page-number
675 If set to true, will print the page number in the first page. Default is
678 @cindex @code{print-page-number}
679 @item print-page-number
680 If set to false, page numbers will not be printed.
682 @cindex @code{paper-width}
684 The width of the page.
686 @cindex @code{paper-height}
688 The height of the page.
690 @cindex @code{top-margin}
692 Margin between header and top of the page.
694 @cindex @code{bottom-margin}
696 Margin between footer and bottom of the page.
698 @cindex @code{left-margin}
700 Margin between the left side of the page and the beginning of the music.
702 @cindex @code{line-width}
704 The length of the systems.
706 @cindex @code{head-separation}
707 @item head-separation
708 Distance between the top-most music system and the page header.
710 @cindex @code{foot-separation}
711 @item foot-separation
712 Distance between the bottom-most music system and the page footer.
714 @cindex @code{page-top-space}
715 Distance from the top of the printable area to the center of the first
716 staff. This only works for staves which are vertically small. Big staves
717 are set with the top of their bounding box aligned to the top of the
720 @cindex @code{ragged-bottom}
722 If set to true, systems will not be spread vertically across the page. This
723 does not affect the last page.
725 This should be set to true for pieces that have only two or three
726 systems per page, for example orchestral scores.
728 @cindex @code{ragged-last-bottom}
729 @item ragged-last-bottom
730 If set to false, systems will be spread vertically to fill the last page.
732 Pieces that amply fill two pages or more should have this set to
735 @cindex @code{system-count}
737 This variable, if set, specifies into how many lines a score should be
740 @cindex @code{between-system-space}
741 @item between-system-space
742 This dimensions determines the distance between systems. It is the
743 ideal distance between the center of the bottom staff of one system
744 and the center of the top staff of the next system.
746 Increasing this will provide a more even appearance of the page at the
747 cost of using more vertical space.
749 @cindex @code{between-system-padding}
750 @item between-system-padding
751 This dimension is the minimum amount of white space that will always
752 be present between the bottom-most symbol of one system, and the
753 top-most of the next system.
755 Increasing this will put systems whose bounding boxes almost touch
759 @cindex @code{horizontal-shift}
760 @item horizontal-shift
761 All systems (including titles and system separators) are shifted by
762 this amount to the right. Page markup, such as headers and footers are
763 not affected by this. The purpose of this variable is to make space
764 for instrument names at the left.
766 @cindex @code{after-title-space}
767 @item after-title-space
768 Amount of space between the title and the first system.
770 @cindex @code{after-title-space}
771 @item before-title-space
772 Amount of space between the last system of the previous piece and the
775 @cindex @code{between-title-space}
776 @item between-title-space
777 Amount of space between consecutive titles (e.g., the title of the
778 book and the title of a piece).
780 @cindex @code{printallheaders}
781 @item printallheaders
782 Setting this to #t will print all headers for each \score in a
783 \book. Normally only the piece and opus \headers are printed.
785 @cindex @code{systemSeparatorMarkup}
786 @item systemSeparatorMarkup
787 This contains a markup object, which will be inserted between
788 systems. This is often used for orchestral scores.
790 The markup command @code{\slashSeparator} is provided as a sensible
793 @lilypond[ragged-right]
796 \relative { c1 \break c1 }
799 systemSeparatorMarkup = \slashSeparator
815 ragged-last-bottom = ##t
819 You can also define these values in Scheme. In that case @code{mm},
820 @code{in}, @code{pt}, and @code{cm} are variables defined in
821 @file{paper-defaults.ly} with values in millimeters. That's why the
822 value has to be multiplied in the example
826 #(define bottom-margin (* 2 cm))
833 The default footer is empty, except for the first page, where the
834 @code{copyright} field from @code{\header} is inserted, and the last
835 page, where @code{tagline} from @code{\header} is added. The default
836 tagline is ``Music engraving by LilyPond (@var{version})''.@footnote{Nicely
837 printed parts are good PR for us, so please leave the tagline if you
840 The header and footer are created by the functions @code{make-footer}
841 and @code{make-header}, defined in @code{\paper}. The default
842 implementations are in @file{ly/@/paper@/-defaults@/.ly} and
843 @file{ly/@/titling@/-init@/.ly}.
845 The page layout itself is done by two functions in the
846 @code{\paper} block, @code{page-music-height} and
847 @code{page-make-stencil}. The former tells the line-breaking algorithm
848 how much space can be spent on a page, the latter creates the actual
849 page given the system to put on it.
854 The option right-margin is defined but doesn't set the right margin
855 yet. The value for the right margin has to be defined adjusting the
856 values of @code{left-margin} and @code{line-width}.
858 The default page header puts the page number and the @code{instrument}
859 field from the @code{\header} block on a line.
861 The titles (from the @code{\header@{@}} section) are treated as a
862 system, so @code{ragged-bottom} and @code{ragged-last-bottom} will
863 add space between the titles and the first system of the score.
867 @section Music layout
869 This section deals with the manner in which the music is printed
870 within the boundaries defined by the @code{\paper} block.
872 The global paper layout is determined by three factors: the page layout, the
873 line breaks, and the spacing. These all influence each other. The
874 choice of spacing determines how densely each system of music is set.
875 This influences where line breaks are chosen, and thus ultimately, how
876 many pages a piece of music takes.
878 Globally spoken, this procedure happens in three steps: first,
879 flexible distances (``springs'') are chosen, based on durations. All
880 possible line breaking combinations are tried, and the one with the
881 best results -- a layout that has uniform density and requires as
882 little stretching or cramping as possible -- is chosen.
884 After spacing and linebreaking, the systems are distributed across
885 pages, taking into account the size of the page, and the size of the
889 * Setting global staff size::
890 * Selecting notation font size::
893 * Vertical spacing of piano staves::
894 * Horizontal spacing::
901 @node Setting global staff size
902 @subsection Setting global staff size
904 @cindex font size, setting
905 @cindex staff size, setting
906 @cindex @code{layout} file
908 To set the global staff size, use @code{set-global-staff-size}.
911 #(set-global-staff-size 14)
915 This sets the global default size to 14pt staff height and scales all
918 The Feta font provides musical symbols at eight different
919 sizes. Each font is tuned for a different staff size: at a smaller size
920 the font becomes heavier, to match the relatively heavier staff lines.
921 The recommended font sizes are listed in the following table:
924 @multitable @columnfractions .15 .2 .22 .2
927 @tab @b{staff height (pt)}
928 @tab @b{staff height (mm)}
970 @c modern rental material?
975 These fonts are available in any sizes. The context property
976 @code{fontSize} and the layout property @code{staff-space} (in
977 @internalsref{StaffSymbol}) can be used to tune the size for individual
978 staves. The sizes of individual staves are relative to the global size.
986 This manual: @ref{Selecting notation font size}.
989 @node Selecting notation font size
990 @subsection Selecting notation font size
992 The easiest method of setting the font size of any context, is by
993 setting the @code{fontSize} property.
995 @lilypond[quote,fragment,relative=1,verbatim]
1004 It does not change the size of variable symbols, such as beams or
1007 Internally, the @code{fontSize} context property will cause the
1008 @code{font-size} property to be set in all layout objects. The value
1009 of @code{font-size} is a number indicating the size relative to the
1010 standard size for the current staff height. Each step up is an
1011 increase of approximately 12% of the font size. Six steps is exactly a
1012 factor two. The Scheme function @code{magstep} converts a
1013 @code{font-size} number to a scaling factor.
1015 @lilypond[quote,fragment,relative=1,verbatim]
1017 \override NoteHead #'font-size = #-4
1019 \override NoteHead #'font-size = #3
1023 LilyPond has fonts in different design sizes. The music fonts for
1024 smaller sizes are chubbier, while the text fonts are relatively wider.
1025 Font size changes are achieved by scaling the design size that is
1026 closest to the desired size. The standard font size (for
1027 @code{font-size} equals 0), depends on the standard staff height. For
1028 a 20pt staff, a 10pt font is selected.
1030 The @code{font-size} property can only be set on layout objects that
1031 use fonts. These are the ones supporting the
1032 @internalsref{font-interface} layout interface.
1036 The following commands set @code{fontSize} for the current voice:
1038 @cindex @code{\tiny}
1040 @cindex @code{\small}
1042 @cindex @code{\normalsize}
1047 @subsection Score layout
1049 @cindex @code{\layout}
1051 While @code{\paper} contains settings that relate to the page formatting
1052 of the whole document, @code{\layout} contains settings for score-specific
1059 \override VerticalAxisGroup #'minimum-Y-extent = #'(-6 . 6)
1062 \override TextScript #'padding = #1.0
1063 \override Glissando #'thickness = #3
1071 This manual: @ref{Changing context default settings}
1074 @node Vertical spacing
1075 @subsection Vertical spacing
1077 @cindex vertical spacing
1078 @cindex distance between staves
1079 @cindex staff distance
1080 @cindex between staves, distance
1081 @cindex staves per page
1082 @cindex space between staves
1084 The height of each system is determined automatically. To prevent
1085 systems from bumping into each other, some minimum distances are set.
1086 By changing these, you can put staves closer together, and thus put
1087 more systems onto one page.
1089 Normally staves are stacked vertically. To make staves maintain a
1090 distance, their vertical size is padded. This is done with the
1091 property @code{minimum-Y-extent}. When applied to a
1092 @internalsref{VerticalAxisGroup}, it controls the size of a horizontal
1093 line, such as a staff or a line of lyrics. @code{minimum-Y-extent}
1094 takes a pair of numbers, so
1095 if you want to make it smaller than its default @code{#'(-4 . 4)}
1099 \override Staff.VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
1103 This sets the vertical size of the current staff to 3 staff spaces on
1104 either side of the center staff line. The value @code{(-3 . 3)} is
1105 interpreted as an interval, where the center line is the 0, so the
1106 first number is generally negative. The staff can be made larger at
1107 the bottom by setting it to @code{(-6 . 4)}.
1109 The spacing of staves in a system may also be tuned per system. This is
1110 done with the command
1114 #"Score.NonMusicalPaperColumn"
1115 #'line-break-system-details
1116 #'((alignment-extra-space . 15))
1120 at the line break before the system to be changed. The distance
1121 @code{15} is distributed over all staves that have a fixed distance
1122 alignment. For example,
1124 @lilypond[ragged-right, fragment, relative=2, staffsize=13]
1130 #"Score.NonMusicalPaperColumn"
1131 #'line-break-system-details
1132 #'((fixed-alignment-extra-space . 15))
1140 The distance for @code{alignment-extra-space} may also be negative.
1143 To change the amount of space between systems, use
1144 @code{between-system-space}. A score with only one staff is still
1145 considered to have systems, so setting @code{between-system-space} will
1146 be much more useful than changing @code{minimum-Y-extent} of a Staff
1151 between-system-space = 10\mm
1155 If you simply want to tell LilyPond ``fit as much as possible onto
1156 these pages, then expand to fill any available space on the pages,''
1157 then use the following
1161 between-system-padding = #1
1163 ragged-last-bottom=##f
1168 @c let's wait for a some comments before writing more.
1170 The vertical spacing on a page can also be changed for each system
1172 Some examples are found in the example file
1173 @inputfileref{input/regression/,page-spacing.ly}.
1175 When setting @code{annotate-spacing} in the @code{\paper} block LilyPond
1176 will graphically indicate the dimensions of properties that may be set
1180 #(set-default-paper-size "a7" 'landscape)
1181 \paper { annotate-spacing = ##t }
1186 All units dimensions are measured in staff spaces. The pairs
1187 (@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
1188 @var{b} the upper edge of the interval.
1192 Internals: Vertical alignment of staves is handled by the
1193 @internalsref{VerticalAlignment} object. The context parameters
1194 specifying the vertical extent are described in connection with
1195 the @internalsref{Axis_group_engraver}.
1197 Example files: @inputfileref{input/regression/,page-spacing.ly},
1198 @inputfileref{input/regression/,alignment-vertical-spacing.ly}.
1203 @node Vertical spacing of piano staves
1204 @subsection Vertical spacing of piano staves
1206 The distance between staves of a @internalsref{PianoStaff} cannot be
1207 computed during formatting. Rather, to make cross-staff beaming work
1208 correctly, that distance has to be fixed beforehand.
1210 The distance of staves in a @code{PianoStaff} is set with the
1211 @code{forced-distance} property of the
1212 @internalsref{VerticalAlignment} object, created in
1213 @internalsref{PianoStaff}.
1215 It can be adjusted as follows
1217 \new PianoStaff \with @{
1218 \override VerticalAlignment #'forced-distance = #7
1225 This would bring the staves together at a distance of 7 staff spaces,
1226 measured from the center line of each staff.
1228 The difference is demonstrated in the following example,
1229 @lilypond[quote,verbatim]
1231 \new PianoStaff \with {
1232 \override VerticalAlignment #'forced-distance = #7
1245 It is also possible to change the distance between for each system
1246 individually. This is done by including the command
1250 #"Score.NonMusicalPaperColumn"
1251 #'line-break-system-details
1252 #'((fixed-alignment-extra-space . 15))
1256 at the line break before the system to be changed. The distance
1257 @code{15} is distributed over all staves that have a fixed distance
1258 alignment. For example,
1260 @lilypond[ragged-right, fragment, relative=2, staffsize=13]
1266 #"Score.NonMusicalPaperColumn"
1267 #'line-break-system-details
1268 #'((fixed-alignment-extra-space . 15))
1276 The distance for @code{fixed-alignment-extra-space} may also be
1281 Example files: @inputfileref{input/regression/,alignment-vertical-spacing.ly}.
1283 @node Horizontal spacing
1284 @subsection Horizontal Spacing
1286 The spacing engine translates differences in durations into stretchable
1287 distances (``springs'') of differring lengths. Longer durations get
1288 more space, shorter durations get less. The shortest durations get a
1289 fixed amount of space (which is controlled by
1290 @code{shortest-duration-space} in the @internalsref{SpacingSpanner}
1291 object). The longer the duration, the more space it gets: doubling a
1292 duration adds a fixed amount (this amount is controlled by
1293 @code{spacing-increment}) of space to the note.
1295 For example, the following piece contains lots of half, quarter, and
1296 8th notes; the eighth note is followed by 1 note head width (NHW).
1297 The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
1299 @lilypond[quote,fragment,verbatim,relative=1]
1300 c2 c4. c8 c4. c8 c4. c8 c8
1304 Normally, @code{spacing-increment} is set to 1.2 staff space, which is
1305 approximately the width of a note head, and
1306 @code{shortest-duration-space} is set to 2.0, meaning that the
1307 shortest note gets 2.4 staff space (2.0 times the
1308 @code{spacing-increment}) of horizontal space. This space is counted
1309 from the left edge of the symbol, so the shortest notes are generally
1310 followed by one NHW of space.
1312 If one would follow the above procedure exactly, then adding a single
1313 32nd note to a score that uses 8th and 16th notes, would widen up the
1314 entire score a lot. The shortest note is no longer a 16th, but a 32nd,
1315 thus adding 1 NHW to every note. To prevent this, the shortest
1316 duration for spacing is not the shortest note in the score, but rather
1317 the one which occurs most frequently.
1320 The most common shortest duration is determined as follows: in every
1321 measure, the shortest duration is determined. The most common shortest
1322 duration is taken as the basis for the spacing, with the stipulation
1323 that this shortest duration should always be equal to or shorter than
1324 an 8th note. The shortest duration is printed when you run
1325 @code{lilypond} with the @code{--verbose} option.
1327 These durations may also be customized. If you set the
1328 @code{common-shortest-duration} in @internalsref{SpacingSpanner}, then
1329 this sets the base duration for spacing. The maximum duration for this
1330 base (normally an 8th), is set through @code{base-shortest-duration}.
1332 @cindex @code{common-shortest-duration}
1333 @cindex @code{base-shortest-duration}
1334 @cindex @code{stem-spacing-correction}
1335 @cindex @code{spacing}
1337 Notes that are even shorter than the common shortest note are
1338 followed by a space that is proportional to their duration relative to
1339 the common shortest note. So if we were to add only a few 16th notes
1340 to the example above, they would be followed by half a NHW:
1342 @lilypond[quote,fragment,verbatim,relative=2]
1343 c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
1347 In the introduction (see @ref{Engraving}), it was explained that stem
1348 directions influence spacing. This is controlled with the
1349 @code{stem-spacing-correction} property in the
1350 @internalsref{NoteSpacing}, object. These are generated for every
1351 @internalsref{Voice} context. The @code{StaffSpacing} object
1352 (generated in @internalsref{Staff} context) contains the same property
1353 for controlling the stem/bar line spacing. The following example shows
1354 these corrections, once with default settings, and once with
1355 exaggerated corrections:
1357 @lilypond[quote,ragged-right]
1361 \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
1362 \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
1368 Proportional notation is supported; see @ref{Proportional notation}.
1370 By default, spacing in tuplets depends on various non-duration
1371 factors (such as accidentals, clef changes, etc). To disregard
1372 such symbols and force uniform equal-duration spacing, use
1373 @code{Score.SpacingSpanner #'uniform-stretching}. This
1374 property can only be changed at the beginning of a score,
1376 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1378 \override SpacingSpanner #'uniform-stretching = ##t
1396 When @code{strict-note-spacing} is set, notes are spaced without
1397 regard for clefs, bar lines, and grace notes,
1399 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1400 \override Score.SpacingSpanner #'strict-note-spacing = ##t
1401 \new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c] c32[ c32] }
1407 Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
1408 @internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
1409 @internalsref{SeparatingGroupSpanner}.
1413 Spacing is determined on a score wide basis. If you have a score that
1414 changes its character (measured in durations) halfway during the
1415 score, the part containing the longer durations will be spaced too
1418 There is no convenient mechanism to manually override spacing. The
1419 following work-around may be used to insert extra space into a score.
1421 \once \override Score.SeparationItem #'padding = #1
1424 No work-around exists for decreasing the amount of space.
1428 @subsection Line length
1431 @cindex breaking pages
1433 @cindex @code{indent}
1434 @cindex @code{line-width}
1435 @cindex @code{ragged-right}
1436 @cindex @code{ragged-last}
1438 @c Although line-width can be set in \layout, it should be set in paper
1439 @c block, to get page layout right.
1440 @c Setting indent in \paper block makes not much sense, but it works.
1442 @c Bit verbose and vague, use examples?
1443 The most basic settings influencing the spacing are @code{indent} and
1444 @code{line-width}. They are set in the @code{\layout} block. They
1445 control the indentation of the first line of music, and the lengths of
1448 If @code{ragged-right} is set to true in the @code{\layout} block, then
1449 systems ends at their natural horizontal length, instead of being spread
1450 horizontally to fill the whole line. This is useful for
1451 short fragments, and for checking how tight the natural spacing is.
1454 @cindex vertical spacing
1456 The option @code{ragged-last} is similar to @code{ragged-right}, but
1457 only affects the last line of the piece. No restrictions are put on
1458 that line. The result is similar to formatting text paragraphs. In a
1459 paragraph, the last line simply takes its natural horizontal length.
1460 @c Note that for text there are several options for the last line.
1461 @c While Knuth TeX uses natural length, lead typesetters use the same
1462 @c stretch as the previous line. eTeX uses \lastlinefit to
1463 @c interpolate between both these solutions.
1475 @subsection Line breaking
1478 @cindex breaking lines
1480 Line breaks are normally computed automatically. They are chosen so
1481 that lines look neither cramped nor loose, and that consecutive lines
1482 have similar density.
1484 Occasionally you might want to override the automatic breaks; you can
1485 do this by specifying @code{\break}. This will force a line break at
1486 this point. Line breaks can only occur at places where there are bar
1487 lines. If you want to have a line break where there is no bar line,
1488 you can force an invisible bar line by entering @code{\bar
1489 ""}. Similarly, @code{\noBreak} forbids a line break at a
1493 @cindex regular line breaks
1494 @cindex four bar music.
1496 For line breaks at regular intervals use @code{\break} separated by
1497 skips and repeated with @code{\repeat}:
1499 << \repeat unfold 7 @{
1500 s1 \noBreak s1 \noBreak
1501 s1 \noBreak s1 \break @}
1502 @emph{the real music}
1507 This makes the following 28 measures (assuming 4/4 time) be broken every
1508 4 measures, and only there.
1512 @code{\break}, and @code{\noBreak}.
1513 @cindex @code{\break}
1514 @cindex @code{\noBreak}
1518 Internals: @internalsref{BreakEvent}.
1520 A linebreaking configuration can now be saved as a @code{.ly} file
1521 automatically. This allows vertical alignments to be stretched to
1522 fit pages in a second formatting run. This is fairly new and
1523 complicated; see @inputfileref{input/regression/,page-layout-twopass.ly}
1528 Line breaks can only occur if there is a ``proper'' bar line. A note
1529 which is hanging over a bar line is not proper, such as
1531 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
1532 c4 c2 c2 \break % this does nothing
1533 c2 c4 | % a break here would work
1534 c4 c2 c4 ~ \break % as does this break
1540 @subsection Page breaking
1542 The default page breaking may be overriden by inserting
1543 @code{\pageBreak} or @code{\noPageBreak} commands. These commands are
1544 analogous to @code{\break} and @code{\noBreak}. They should be
1545 inserted at a bar line. These commands force and forbid a page-break
1546 from happening. Of course, the @code{\pageBreak} command also forces
1549 Page breaks are computed by the @code{page-breaking} function in the
1550 @code{\paper} block.
1552 To force a new page for a new piece (in a collection of pieces or a
1553 piece in several movements), use @code{breakbefore} in the header.
1564 @cindex @code{\pageBreak}
1566 @cindex @code{\noPageBreak}
1572 The @code{breakbefore=##t} header requires that there is a @code{piece}
1573 header as well. It may be used as a normal header, or left blank
1574 (@code{=""}) as in the example above, but it must be present.
1578 @node Multiple movements
1579 @section Multiple movements
1581 @cindex bibliographic information
1584 @cindex Music engraving by LilyPond
1586 A document may contain multiple pieces of music and texts. Examples
1587 of these are an etude book, or an orchestral part with multiple
1588 movements. Each movement is entered with a @code{\score} block,
1596 and texts are entered with a @code{\markup} block,
1604 @cindex @code{\book}
1606 The movements and texts are combined together in a @code{\book} block,
1624 The header for each piece of music can be put inside the @code{\score}
1625 block. The @code{piece} name from the header will be printed before
1626 each movement. The title for the entire book can be put inside the
1627 @code{\book}, but if it is not present, the @code{\header} which is at
1628 the top of the file is inserted.
1630 @cindex Engraved by LilyPond
1631 @cindex signature line
1636 title = "Eight miniatures"
1637 composer = "Igor Stravinsky"
1641 \header @{ piece = "Romanze" @}
1644 ..text of second verse..
1647 ..text of third verse..
1651 \header @{ piece = "Menuetto" @}
1659 @section MIDI output
1664 MIDI (Musical Instrument Digital Interface) is a standard for
1665 connecting and controlling digital instruments. A MIDI file is a
1666 series of notes in a number of tracks. It is not an actual
1667 sound file; you need special software to translate between the
1668 series of notes and actual sounds.
1670 Pieces of music can be converted to MIDI files, so you can listen to
1671 what was entered. This is convenient for checking the music; octaves
1672 that are off or accidentals that were mistyped stand out very much
1673 when listening to the MIDI output.
1677 Many musically interesting effects, such as swing, articulation,
1678 slurring, etc., are not translated to midi.
1680 The midi output allocates a channel for each staff, and one for global
1681 settings. Therefore the midi file should not have more than 15 staves
1682 (or 14 if you do not use drums). Other staves will remain silent.
1684 Not all midi players correctly handle tempo changes in the midi
1685 output. Players that are known to work include
1686 @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
1689 * Creating MIDI files::
1691 * MIDI instrument names::
1694 @node Creating MIDI files
1695 @subsection Creating MIDI files
1697 To create a MIDI from a music piece of music, add a @code{\midi} block
1698 to a score, for example,
1703 \midi @{ \tempo 4=72 @}
1707 The tempo is specified using the @code{\tempo} command. In this
1708 example the tempo of quarter notes is set to 72 beats per minute.
1711 If there is a @code{\midi} command in a @code{\score}, only MIDI will
1712 be produced. When notation is needed too, a @code{\layout} block must
1718 \midi @{ \tempo 4=72 @}
1722 @cindex layout block
1726 Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
1727 crescendi and decrescendi translate into MIDI volume levels. Dynamic
1728 marks translate to a fixed fraction of the available MIDI volume
1729 range, crescendi and decrescendi make the volume vary linearly between
1730 their two extremes. The fractions can be adjusted by
1731 @code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
1732 For each type of MIDI instrument, a volume range can be defined. This
1733 gives a basic equalizer control, which can enhance the quality of
1734 the MIDI output remarkably. The equalizer can be controlled by
1735 setting @code{instrumentEqualizer}, or by setting
1738 \set Staff.midiMinimumVolume = #0.2
1739 \set Staff.midiMaximumVolume = #0.8
1742 To remove dynamics from the MIDI output, insert the following lines
1743 in the @code{\midi@{@}} section.
1750 \remove "Dynamic_performer"
1751 \remove "Span_dynamic_performer"
1759 Unterminated (de)crescendos will not render properly in the midi file,
1760 resulting in silent passages of music. The workaround is to explicitly
1761 terminate the (de)crescendo. For example,
1768 will not work properly but
1779 @subsection MIDI block
1783 The MIDI block is analogous to the layout block, but it is somewhat
1784 simpler. The @code{\midi} block can contain
1788 @item a @code{\tempo} definition, and
1789 @item context definitions.
1792 A number followed by a period is interpreted as a real number, so
1793 for setting the tempo for dotted notes, an extra space should be
1794 inserted, for example
1797 \midi @{ \tempo 4 . = 120 @}
1801 @cindex context definition
1803 Context definitions follow precisely the same syntax as within the
1804 \layout block. Translation modules for sound are called performers.
1805 The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
1808 @node MIDI instrument names
1809 @subsection MIDI instrument names
1811 @cindex instrument names
1812 @cindex @code{Staff.midiInstrument}
1814 The MIDI instrument name is set by the @code{Staff.midiInstrument}
1815 property. The instrument name should be chosen from the list in
1816 @ref{MIDI instruments}.
1819 \set Staff.midiInstrument = "glockenspiel"
1823 If the selected instrument does not exactly match an instrument from
1824 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})
1828 @c Yes, this is a cop-out; this info doesn't belong in the Scheme
1829 @c chapter, but I'm not certain where to stick it.
1830 @c I think I'll eventually split this chapter into a "paper/layout"
1831 @c chapter and a "misc issues" chapter. -gp
1832 @node Displaying LilyPond notation
1833 @section Displaying LilyPond notation
1835 @cindex @code{\displayLilyMusc}
1836 Displaying a music expression in LilyPond notation can be
1837 done using the music function @code{\displayLilyMusic}. For example,
1841 \displayLilyMusic \transpose c a, @{ c e g a bes @}
1848 @{ a, cis e fis g @}
1851 By default, LilyPond will print these messages to the console along
1852 with all the other messages. To split up these messages and save
1853 the results of @code{\display@{STUFF@}}, redirect the output to
1857 lilypond file.ly >display.txt