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 * Music expressions again::
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 @code{\header} block. This sets the global header block. This
88 is the block containing the definitions for book-wide settings, like
92 An @code{\addquote} statement. See @ref{Quoting other voices}
96 A @code{\score} block. This score will be collected with other
97 toplevel scores, and combined as a single @code{\book}.
99 This behavior can be changed by setting the variable
100 @code{toplevel-score-handler} at toplevel. The default handler is
101 defined in the init file @file{scm/@/lily@/.scm}.
103 The @code{\score} must begin with music, and may contain only
107 A @code{\book} block logically combines multiple movements
108 (i.e., multiple @code{\score} blocks) in one document. A number of
109 @code{\scores} creates a single output file, where all movement are
112 This behavior can be changed by setting the variable
113 @code{toplevel-book-handler} at toplevel. The default handler is
114 defined in the init file @file{scm/@/lily@/.scm}.
117 A compound music expression, such as
122 This will add the piece in a @code{\score} and format it in a
123 single book together with all other toplevel @code{\score}s and music
124 expressions. In other words, a file containing only the above
125 music expression will be translated into
141 This behavior can be changed by setting the variable
142 @code{toplevel-music-handler} at toplevel. The default handler is
143 defined in the init file @file{scm/@/lily@/.scm}.
146 A markup text, a verse for example
149 2. The first line verse two.
153 Markup texts are rendered above, between or below the scores or music
154 expressions, wherever they appear.
157 An identifier, such as
162 This can be used later on in the file by entering @code{\foo}. The
163 name of an identifier should have alphabetic characters only; no
164 numbers, underscores or dashes.
168 The following example shows three things that may be entered at
173 % movements are non-justified by default
185 At any point in a file, any of the following lexical instructions can
189 @item @code{\version}
190 @item @code{\include}
191 @item @code{\renameinput}
195 @node Including LilyPond files
196 @subsection Including LilyPond files
198 @cindex @code{\include}
199 @cindex including files
201 A large project may be split up into separate files. To refer to another
205 \include "otherfile.ly"
208 The line @code{\include "file.ly"} is equivalent to pasting the contents
209 of file.ly into the current file at the place where you have the
210 \include. For example, for a large project you might write separate files
211 for each instrument part and create a ``full score'' file which brings
212 together the individual instrument files.
214 The initialization of LilyPond is done in a number of files that are
215 included by default when you start the program, normally transparent to the
216 user. Run lilypond --verbose to see a list of paths and files that Lily
219 Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
220 VERSION is in the form ``2.6.1'') are on the path and available to
221 @code{\include}. Files in the
222 current working directory are available to \include, but a file of the same
223 name in LilyPond's installation takes precedence. Files are
224 available to \include from directories in the search path specified as an
225 option when invoking @code{lilypond --include=DIR} which adds DIR to the search
228 The @code{\include} statement can use full path information, but with the Unix
229 convention @code{"/"} rather than the DOS/Windows @code{"\"}. For example,
230 if @file{stuff.ly} is located one directory higher than the current working
234 \include "../stuff.ly"
239 @subsection Text encoding
241 LilyPond uses the Pango library to format multi-lingual texts, and
242 does not perform any input-encoding conversions. This means that any
243 text, be it title, lyric text, or musical instruction containing
244 non-ASCII characters, must be utf-8. Easiest to enter such texts is
245 by using a Unicode-aware editor, and save using utf-8 encoding. Most
246 popular modern editors have utf-8 support, for example, vim, Emacs,
249 Depending on the fonts installed, the following fragment shows Hebrew
256 @lilypondfile[fontload]{utf-8.ly}
258 The @TeX{} backend does not handle encoding specially at all. Strings
259 in the input are put in the output as-is. Extents of text items in the
260 @TeX{} backend, are determined by reading a file created via the
261 @file{texstr} backend,
264 lilypond -b texstr input/les-nereides.ly
265 latex les-nereides.texstr
268 The last command produces @file{les-nereides.textmetrics}, which is
269 read when you execute
272 lilypond -b tex input/les-nereides.ly
275 Both @file{les-nereides.texstr} and @file{les-nereides.tex} need
276 suitable LaTeX wrappers to load appropriate La@TeX{} packages for
277 interpreting non-ASCII strings.
279 To use a Unicode escape sequence, use
282 #(ly:export (ly:wide-char->utf-8 #x2014))
288 @inputfileref{input/regression,utf-8.ly}
292 @c FIXME: --must-- delete/modify this before 2.8.0!!! -gp
293 @node Music expressions again
294 @section Music expressions again
296 Should we include anything about this here?
299 @node Titles and headers
300 @section Titles and headers
302 Almost all printed music includes a title and the composer's name;
303 some pieces include a lot more information.
311 @node Creating titles
312 @subsection Creating titles
314 Titles are created for each @code{\score} block, and over a
317 The contents of the titles are taken from the @code{\header} blocks.
318 The header block for a book supports the following
321 The dedicatee of the music, centered at the top of the first page.
324 The title of the music, centered just below the dedication.
327 Subtitle, centered below the title.
330 Subsubtitle, centered below the subtitle.
333 Name of the poet, flush-left below the subtitle.
336 Name of the composer, flush-right below the subtitle.
339 Meter string, flush-left below the poet.
342 Name of the opus, flush-right below the composer.
345 Name of the arranger, flush-right below the opus.
348 Name of the instrument, centered below the arranger. Also
349 centered at the top of pages (other than the first page).
352 Name of the piece, flush-left below the instrument.
354 @cindex page breaks, forcing
356 This forces the title to start on a new page (set to ##t or ##f).
359 Copyright notice, centered at the bottom of the first page. To
360 insert the copyright symbol, see @ref{Text encoding}.
363 Centered at the bottom of the last page.
367 Here is a demonstration of the fields available. Note that you
368 may use any @ref{Text markup} commands in the header.
370 @lilypond[quote,verbatim,line-width=11.0\cm]
373 paper-height = 10.0\cm
378 dedication = "dedicated to me"
379 title = \markup \center-align { "Title first line" "Title second line, longer" }
380 subtitle = "the subtitle,"
381 subsubtitle = #(string-append "subsubtitle LilyPond version " (lilypond-version))
383 composer = \markup \center-align { "composer" \small "(1847-1973)" }
384 texttranslator = "Text Translator"
385 meter = \markup { \teeny "m" \tiny "e" \normalsize "t" \large "e" \huge "r" }
386 arranger = \markup { \fontsize #8.5 "a" \fontsize #2.5 "r" \fontsize #-2.5 "r" \fontsize #-5.3 "a" \fontsize #7.5 "nger" }
387 instrument = \markup \bold \italic "instrument"
411 As demonstrated before, you can use multiple @code{\header} blocks.
412 When same fields appear in different blocks, the latter is used.
413 Here is a short example.
417 composer = "Composer"
425 title = "New title" % overwrite previous one
430 If you define the @code{\header} inside the @code{\score} block, then
431 normally only the @code{piece} and @code{opus} headers will be printed.
432 Note that the music expression must come before the @code{\header}.
434 @lilypond[quote,verbatim,line-width=11.0\cm]
438 title = "title" % not printed
445 @cindex @code{printallheaders}
447 You may change this behavior (and print all the headers when defining
448 @code{\header} inside @code{\score}) by using
458 @subsection Custom titles
460 A more advanced option is to change the definitions of the following
461 variables in the @code{\paper} block. The init file
462 @file{ly/titling-init.ly} lists the default layout.
465 @cindex @code{bookTitleMarkup}
466 @item bookTitleMarkup
467 This is the title put over an entire @code{\book} block. Typically,
468 it has the composer and the title of the piece
470 @cindex @code{scoreTitleMarkup}
471 @item scoreTitleMarkup
472 This is the title put over a @code{\score} block within a
473 @code{\book}. Typically, it has the name of the movement (@code{piece}
476 @cindex @code{oddHeaderMarkup}
477 @item oddHeaderMarkup
478 This is the page header for odd-numbered pages.
480 @cindex @code{evenHeaderMarkup}
481 @item evenHeaderMarkup
482 This is the page header for even-numbered pages. If unspecified,
483 the odd header is used instead.
485 By default, headers are defined such that the page number is on the
486 outside edge, and the instrument is centered.
488 @cindex @code{oddFooterMarkup}
489 @item oddFooterMarkup
490 This is the page footer for odd-numbered pages.
492 @cindex @code{evenFotterMarkup}
493 @item evenFooterMarkup
494 This is the page footer for even-numbered pages. If unspecified,
495 the odd header is used instead.
497 By default, the footer has the copyright notice on the first, and
498 the tagline on the last page.
508 The following definition will put the title flush left, and the
509 composer flush right on a single line.
513 bookTitleMarkup = \markup {
515 \fromproperty #'header:title
516 \fromproperty #'header:composer
525 The @code{breakbefore=##t} header requires that there is a @code{piece} header as well. It may be used as a normal header, or left blank (@code{=""}) as in the example above, but it must be present.
529 @node Paper and pages
530 @section Paper and pages
532 This section deals with the display of music on physical paper.
541 @subsection Paper size
545 @cindex @code{papersize}
547 To change the paper size, there are two commands,
549 #(set-default-paper-size "a4")
551 #(set-paper-size "a4")
555 The first command sets the size of all pages. The second command sets the size
556 of the pages that the @code{\paper} block applies to -- if the @code{\paper}
557 block is at the top of the file, then it will apply to all pages. If the
558 @code{\paper} block is inside a @code{\book}, then the paper size will only
561 Support for the following paper sizes are included by default,
562 @code{a6}, @code{a5}, @code{a4}, @code{a3}, @code{legal}, @code{letter},
563 @code{11x17} (also known as tabloid).
565 Extra sizes may be added by editing the definition for
566 @code{paper-alist} in the initialization file @file{scm/paper.scm}.
571 If the symbol @code{landscape} is supplied as an argument to
572 @code{set-default-paper-size}, the pages will be rotated by 90 degrees,
573 and wider line widths will be set correspondingly.
576 #(set-default-paper-size "a6" 'landscape)
580 @node Page formatting
581 @subsection Page formatting
583 @cindex page formatting
588 LilyPond will do page layout, set margins, and add headers and
589 footers to each page.
591 The default layout responds to the following settings in the
594 @cindex @code{\paper}
598 @cindex @code{first-page-number}
599 @item first-page-number
600 The value of the page number of the first page. Default is@tie{}1.
602 @cindex @code{printfirst-page-number}
603 @item printfirst-page-number
604 If set to true, will print the page number in the first page. Default is
607 @cindex @code{print-page-number}
608 @item print-page-number
609 If set to false, page numbers will not be printed.
611 @cindex @code{paper-width}
613 The width of the page.
615 @cindex @code{paper-height}
617 The height of the page.
619 @cindex @code{top-margin}
621 Margin between header and top of the page.
623 @cindex @code{bottom-margin}
625 Margin between footer and bottom of the page.
627 @cindex @code{left-margin}
629 Margin between the left side of the page and the beginning of the music.
631 @cindex @code{line-width}
633 The length of the systems.
635 @cindex @code{heap-separation}
636 @item heap-separation
637 Distance between the top-most music system and the page header.
639 @cindex @code{foot-separation}
640 @item foot-separation
641 Distance between the bottom-most music system and the page footer.
643 @cindex @code{page-top-space}
644 Distance from the top of the printable area to the center of the first
645 staff. This only works for staves which are vertically small. Big staves
646 are set with the top of their bounding box aligned to the top of the
649 @cindex @code{ragged-bottom}
651 If set to true, systems will not be spread across the page.
653 This should be set false for pieces that have only two or three
654 systems per page, for example orchestral scores.
656 @cindex @code{ragged-last-bottom}
657 @item ragged-last-bottom
658 If set to false, systems will be spread to fill the last page.
660 Pieces that amply fill two pages or more should have this set to
663 @cindex @code{between-system-space}
664 @item between-system-space
665 This dimensions determines the distance between systems. It is the
666 ideal distance between the center of the bottom staff of one system
667 and the center of the top staff of the next system.
669 Increasing this will provide a more even appearance of the page at the
670 cost of using more vertical space.
672 @cindex @code{between-system-padding}
673 @item between-system-padding
674 This dimension is the minimum amount of white space that will always
675 be present between the bottom-most symbol of one system, and the
676 top-most of the next system.
678 Increasing this will put systems whose bounding boxes almost touch
682 @cindex @code{horizontal-shift}
683 @item horizontal-shift
684 All systems (including titles and system separators) are shifted by
685 this amount to the right. Page markup, such as headers and footers are
686 not affected by this. The purpose of this variable is to make space
687 for instrument names at the left.
689 @cindex @code{after-title-space}
690 @item after-title-space
691 Amount of space between the title and the first system.
693 @cindex @code{after-title-space}
694 @item before-title-space
695 Amount of space between the last system of the previous piece and the
698 @cindex @code{between-title-space}
699 @item between-title-space
700 Amount of space between consecutive titles (e.g., the title of the
701 book and the title of a piece).
703 @cindex @code{printallheaders}
704 @item printallheaders
705 Setting this to #t will print all headers for each \score in a
706 \book. Normally only the piece and opus \headers are printed.
708 @cindex @code{systemSeparatorMarkup}
709 @item systemSeparatorMarkup
710 This contains a markup object, which will be inserted between
711 systems. This is often used for orchestral scores.
713 The markup command @code{\slashSeparator} is provided as a sensible
716 @lilypond[ragged-right]
718 systemSeparatorMarkup = \slashSeparator
721 \relative { c1 \break c1 }
735 ragged-last-bottom = ##t
739 You can also define these values in Scheme. In that case @code{mm},
740 @code{in}, @code{pt}, and @code{cm} are variables defined in
741 @file{paper-defaults.ly} with values in millimeters. That's why the
742 value has to be multiplied in the example
746 #(define bottom-margin (* 2 cm))
753 The default footer is empty, except for the first page, where the
754 @code{copyright} field from @code{\header} is inserted, and the last
755 page, where @code{tagline} from @code{\header} is added. The default
756 tagline is ``Music engraving by LilyPond (@var{version})''.@footnote{Nicely
757 printed parts are good PR for us, so please leave the tagline if you
760 The header and footer are created by the functions @code{make-footer}
761 and @code{make-header}, defined in @code{\paper}. The default
762 implementations are in @file{scm/@/page@/-layout@/.scm}.
764 The page layout itself is done by two functions in the
765 @code{\paper} block, @code{page-music-height} and
766 @code{page-make-stencil}. The former tells the line-breaking algorithm
767 how much space can be spent on a page, the latter creates the actual
768 page given the system to put on it.
773 The option right-margin is defined but doesn't set the right margin
774 yet. The value for the right margin has to be defined adjusting the
775 values of @code{left-margin} and @code{line-width}.
777 The default page header puts the page number and the @code{instrument}
778 field from the @code{\header} block on a line.
783 @section Music layout
785 This section deals with the manner in which the music is printed
786 within the boundaries defined by the @code{\paper} block.
788 The global paper layout is determined by three factors: the page layout, the
789 line breaks, and the spacing. These all influence each other. The
790 choice of spacing determines how densely each system of music is set.
791 This influences where line breaks are chosen, and thus ultimately, how
792 many pages a piece of music takes.
794 Globally spoken, this procedure happens in three steps: first,
795 flexible distances (``springs'') are chosen, based on durations. All
796 possible line breaking combinations are tried, and the one with the
797 best results -- a layout that has uniform density and requires as
798 little stretching or cramping as possible -- is chosen.
800 After spacing and linebreaking, the systems are distributed across
801 pages, taking into account the size of the page, and the size of the
805 * Setting global staff size::
806 * Selecting notation font size::
809 * Vertical spacing of piano staves::
810 * Horizontal spacing::
817 @node Setting global staff size
818 @subsection Setting global staff size
820 @cindex font size, setting
821 @cindex staff size, setting
822 @cindex @code{layout} file
824 To set the global staff size, use @code{set-global-staff-size}.
827 #(set-global-staff-size 14)
831 This sets the global default size to 14pt staff height and scales all
834 The Feta font provides musical symbols at eight different
835 sizes. Each font is tuned for a different staff size: at a smaller size
836 the font becomes heavier, to match the relatively heavier staff lines.
837 The recommended font sizes are listed in the following table:
840 @multitable @columnfractions .15 .2 .22 .2
843 @tab @b{staff height (pt)}
844 @tab @b{staff height (mm)}
886 @c modern rental material?
891 These fonts are available in any sizes. The context property
892 @code{fontSize} and the layout property @code{staff-space} (in
893 @internalsref{StaffSymbol}) can be used to tune the size for individual
894 staves. The sizes of individual staves are relative to the global size.
902 This manual: @ref{Selecting notation font size}.
905 @node Selecting notation font size
906 @subsection Selecting notation font size
908 The easiest method of setting the font size of any context, is by
909 setting the @code{fontSize} property.
911 @lilypond[quote,fragment,relative=1,verbatim]
920 It does not change the size of variable symbols, such as beams or
923 Internally, the @code{fontSize} context property will cause the
924 @code{font-size} property to be set in all layout objects. The value
925 of @code{font-size} is a number indicating the size relative to the
926 standard size for the current staff height. Each step up is an
927 increase of approximately 12% of the font size. Six steps is exactly a
928 factor two. The Scheme function @code{magstep} converts a
929 @code{font-size} number to a scaling factor.
931 @lilypond[quote,fragment,relative=1,verbatim]
933 \override NoteHead #'font-size = #-4
935 \override NoteHead #'font-size = #3
939 LilyPond has fonts in different design sizes. The music fonts for
940 smaller sizes are chubbier, while the text fonts are relatively wider.
941 Font size changes are achieved by scaling the design size that is
942 closest to the desired size. The standard font size (for
943 @code{font-size} equals 0), depends on the standard staff height. For
944 a 20pt staff, a 10pt font is selected.
946 The @code{font-size} property can only be set on layout objects that
947 use fonts. These are the ones supporting the
948 @internalsref{font-interface} layout interface.
952 The following commands set @code{fontSize} for the current voice:
956 @cindex @code{\small}
958 @cindex @code{\normalsize}
963 @subsection Score layout
965 @cindex @code{\layout}
967 While @code{\paper} contains settings that relate to the page formatting
968 of the whole document, @code{\layout} contains settings for score-specific
975 \override VerticalAxisGroup #'minimum-Y-extent = #'(-6 . 6)
978 \override TextScript #'padding = #1.0
979 \override Glissando #'thickness = #3
987 This manual: @ref{Changing context default settings}
990 @node Vertical spacing
991 @subsection Vertical spacing
993 @cindex vertical spacing
994 @cindex distance between staves
995 @cindex staff distance
996 @cindex between staves, distance
997 @cindex staves per page
998 @cindex space between staves
1000 The height of each system is determined automatically. To prevent
1001 systems from bumping into each other, some minimum distances are set.
1002 By changing these, you can put staves closer together, and thus put
1003 more systems onto one page.
1005 Normally staves are stacked vertically. To make staves maintain a
1006 distance, their vertical size is padded. This is done with the
1007 property @code{minimum-Y-extent}. It takes a pair of numbers, so
1008 if you want to make it smaller than its default @code{#'(-4 . 4)},
1009 then you could set. When applied to a
1010 @internalsref{VerticalAxisGroup}, it controls the size of a horizontal
1011 line, such as a staff or a line of lyrics.
1014 \override Staff.VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
1018 This sets the vertical size of the current staff to 3 staff spaces on
1019 either side of the center staff line. The value @code{(-3 . 3)} is
1020 interpreted as an interval, where the center line is the 0, so the
1021 first number is generally negative. The staff can be made larger at
1022 the bottom by setting it to @code{(-6 . 4)}.
1024 The spacing of staves in a system may also be tuned per system. This is
1025 done with the command
1029 #"Score.NonMusicalPaperColumn"
1030 #'line-break-system-details
1031 #'((alignment-extra-space . 15))
1035 at the line break before the system to be changed. The distance
1036 @code{15} is distributed over all staves that have a fixed distance
1037 alignment. For example,
1039 @lilypond[ragged-right, fragment, relative=2, staffsize=13]
1045 #"Score.NonMusicalPaperColumn"
1046 #'line-break-system-details
1047 #'((fixed-alignment-extra-space . 15))
1055 The distance for @code{alignment-extra-space} may also be negative.
1058 To change the amount of space between systems, use
1059 @code{between-system-space}. A score with only one staff is still
1060 considered to have systems, so setting @code{between-system-space} will
1061 be much more useful than changing @code{minimum-Y-extent} of a Staff
1066 between-system-space = 10\mm
1070 If you simply want to tell LilyPond ``fit as much as possible onto
1071 these pages, then expand to fill any available space on the pages,''
1072 then use the following
1076 between-system-padding = #1
1078 ragged-last-bottom=##f
1083 @c let's wait for a some comments before writing more.
1085 The vertical spacing on a page can also be changed for each system individually.
1086 Some examples are found in the example file
1087 @inputfileref{input/regression/,page-spacing.ly}.
1089 When setting @code{annotatespacing} in the @code{\paper} block LilyPond
1090 will graphically indicate the dimensions of properties that may be set
1094 #(set-default-paper-size "a7" 'landscape)
1095 \paper { annotatespacing = ##t }
1100 All units dimensions are measured in staff spaces. The pairs
1101 (@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
1102 @var{b} the upper edge of the interval.
1106 Internals: Vertical alignment of staves is handled by the
1107 @internalsref{VerticalAlignment} object. The context parameters
1108 specifying the vertical extent are described in connection with
1109 the @internalsref{Axis_group_engraver}.
1111 Example files: @inputfileref{input/regression/,page-spacing.ly},
1112 @inputfileref{input/regression/,alignment-vertical-spacing.ly}.
1117 @node Vertical spacing of piano staves
1118 @subsection Vertical spacing of piano staves
1120 The distance between staves of a @internalsref{PianoStaff} cannot be
1121 computed during formatting. Rather, to make cross-staff beaming work
1122 correctly, that distance has to be fixed beforehand.
1124 The distance of staves in a @code{PianoStaff} is set with the
1125 @code{forced-distance} property of the
1126 @internalsref{VerticalAlignment} object, created in
1127 @internalsref{PianoStaff}.
1129 It can be adjusted as follows
1131 \new PianoStaff \with @{
1132 \override VerticalAlignment #'forced-distance = #7
1139 This would bring the staves together at a distance of 7 staff spaces,
1140 measured from the center line of each staff.
1142 The difference is demonstrated in the following example,
1143 @lilypond[quote,verbatim]
1145 \new PianoStaff \with {
1146 \override VerticalAlignment #'forced-distance = #7
1159 It is also possible to change the distance between for each system
1160 individually. This is done by including the command
1164 #"Score.NonMusicalPaperColumn"
1165 #'line-break-system-details
1166 #'((fixed-alignment-extra-space . 15))
1170 at the line break before the system to be changed. The distance
1171 @code{15} is distributed over all staves that have a fixed distance
1172 alignment. For example,
1174 @lilypond[ragged-right, fragment, relative=2, staffsize=13]
1180 #"Score.NonMusicalPaperColumn"
1181 #'line-break-system-details
1182 #'((fixed-alignment-extra-space . 15))
1190 The distance for @code{fixed-alignment-extra-space} may also be
1195 Example files: @inputfileref{input/regression/,alignment-vertical-spacing.ly}.
1197 @node Horizontal spacing
1198 @subsection Horizontal Spacing
1200 The spacing engine translates differences in durations into stretchable
1201 distances (``springs'') of differring lengths. Longer durations get
1202 more space, shorter durations get less. The shortest durations get a
1203 fixed amount of space (which is controlled by
1204 @code{shortest-duration-space} in the @internalsref{SpacingSpanner}
1205 object). The longer the duration, the more space it gets: doubling a
1206 duration adds a fixed amount (this amount is controlled by
1207 @code{spacing-increment}) of space to the note.
1209 For example, the following piece contains lots of half, quarter, and
1210 8th notes; the eighth note is followed by 1 note head width (NHW).
1211 The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
1213 @lilypond[quote,fragment,verbatim,relative=1]
1214 c2 c4. c8 c4. c8 c4. c8 c8
1218 Normally, @code{spacing-increment} is set to 1.2 staff space, which is
1219 approximately the width of a note head, and
1220 @code{shortest-duration-space} is set to 2.0, meaning that the
1221 shortest note gets 2.4 staff space (2.0 times the
1222 @code{spacing-increment}) of horizontal space. This space is counted
1223 from the left edge of the symbol, so the shortest notes are generally
1224 followed by one NHW of space.
1226 If one would follow the above procedure exactly, then adding a single
1227 32nd note to a score that uses 8th and 16th notes, would widen up the
1228 entire score a lot. The shortest note is no longer a 16th, but a 32nd,
1229 thus adding 1 NHW to every note. To prevent this, the shortest
1230 duration for spacing is not the shortest note in the score, but rather
1231 the one which occurs most frequently.
1234 The most common shortest duration is determined as follows: in every
1235 measure, the shortest duration is determined. The most common shortest
1236 duration is taken as the basis for the spacing, with the stipulation
1237 that this shortest duration should always be equal to or shorter than
1238 an 8th note. The shortest duration is printed when you run
1239 @code{lilypond} with the @code{--verbose} option.
1241 These durations may also be customized. If you set the
1242 @code{common-shortest-duration} in @internalsref{SpacingSpanner}, then
1243 this sets the base duration for spacing. The maximum duration for this
1244 base (normally an 8th), is set through @code{base-shortest-duration}.
1246 @cindex @code{common-shortest-duration}
1247 @cindex @code{base-shortest-duration}
1248 @cindex @code{stem-spacing-correction}
1249 @cindex @code{spacing}
1251 Notes that are even shorter than the common shortest note are
1252 followed by a space that is proportional to their duration relative to
1253 the common shortest note. So if we were to add only a few 16th notes
1254 to the example above, they would be followed by half a NHW:
1256 @lilypond[quote,fragment,verbatim,relative=2]
1257 c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
1261 In the introduction (see @ref{Engraving}), it was explained that stem
1262 directions influence spacing. This is controlled with the
1263 @code{stem-spacing-correction} property in the
1264 @internalsref{NoteSpacing}, object. These are generated for every
1265 @internalsref{Voice} context. The @code{StaffSpacing} object
1266 (generated in @internalsref{Staff} context) contains the same property
1267 for controlling the stem/bar line spacing. The following example shows
1268 these corrections, once with default settings, and once with
1269 exaggerated corrections:
1271 @lilypond[quote,ragged-right]
1275 \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
1276 \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
1282 Proportional notation is supported; see @ref{Proportional notation}.
1284 @c check this before release --gp
1285 Symbol sizes (such as accidentals) may be disregarded for determining
1288 @lilypond[quote,ragged-right,relative=2,fragment]
1291 \new Staff { c16[ c c c c c c c] c[ c c c c c c c] }
1293 c16[ cisis ces cis c cisis ces cis]
1294 \override Score.SpacingSpanner #'uniform-stretching = ##t
1295 c16[ cisis ces cis c cisis ces cis]
1301 When @code{strict-note-spacing} is set, notes are spaced without
1302 regard for clefs, bar lines, and grace notes,
1304 @lilypond[quote,ragged-right,relative=2,fragment]
1305 \override Score.SpacingSpanner #'strict-note-spacing = ##t
1306 \new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c] c32[ c32] }
1312 Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
1313 @internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
1314 @internalsref{SeparatingGroupSpanner}.
1318 Spacing is determined on a score wide basis. If you have a score that
1319 changes its character (measured in durations) halfway during the
1320 score, the part containing the longer durations will be spaced too
1323 There is no convenient mechanism to manually override spacing. The
1324 following work-around may be used to insert extra space into a score.
1326 \once \override Score.SeparationItem #'padding = #1
1329 No work-around exists for decreasing the amount of space.
1333 @subsection Line length
1336 @cindex breaking pages
1338 @cindex @code{indent}
1339 @cindex @code{line-width}
1340 @cindex @code{ragged-right}
1342 @c Although line-width can be set in \layout, it should be set in paper
1343 @c block, to get page layout right.
1344 @c Setting indent in \paper block makes not much sense, but it works.
1346 @c Bit verbose and vague, use examples?
1347 The most basic settings influencing the spacing are @code{indent} and
1348 @code{line-width}. They are set in the @code{\layout} block. They
1349 control the indentation of the first line of music, and the lengths of
1352 If @code{ragged-right} is set to true in the @code{\layout} block, then
1353 the lines are justified at their natural length. This is useful for
1354 short fragments, and for checking how tight the natural spacing is.
1357 @cindex vertical spacing
1359 The option @code{raggedlast} is similar to @code{ragged-right}, but
1360 only affects the last line of the piece. No restrictions are put on
1361 that line. The result is similar to formatting text paragraphs. In a
1362 paragraph, the last line simply takes its natural length.
1363 @c Note that for text there are several options for the last line.
1364 @c While Knuth TeX uses natural length, lead typesetters use the same
1365 @c stretch as the previous line. eTeX uses \lastlinefit to
1366 @c interpolate between both these solutions.
1370 @subsection Line breaking
1373 @cindex breaking lines
1375 Line breaks are normally computed automatically. They are chosen so
1376 that lines look neither cramped nor loose, and that consecutive lines
1377 have similar density.
1379 Occasionally you might want to override the automatic breaks; you can
1380 do this by specifying @code{\break}. This will force a line break at
1381 this point. Line breaks can only occur at places where there are bar
1382 lines. If you want to have a line break where there is no bar line,
1383 you can force an invisible bar line by entering @code{\bar
1384 ""}. Similarly, @code{\noBreak} forbids a line break at a
1388 @cindex regular line breaks
1389 @cindex four bar music.
1391 For line breaks at regular intervals use @code{\break} separated by
1392 skips and repeated with @code{\repeat}:
1394 << \repeat unfold 7 @{
1395 s1 \noBreak s1 \noBreak
1396 s1 \noBreak s1 \break @}
1397 @emph{the real music}
1402 This makes the following 28 measures (assuming 4/4 time) be broken every
1403 4 measures, and only there.
1407 @code{\break}, and @code{\noBreak}.
1408 @cindex @code{\break}
1409 @cindex @code{\noBreak}
1413 Internals: @internalsref{BreakEvent}.
1415 A linebreaking configuration can now be saved as a @code{.ly} file
1416 automatically. This allows vertical alignments to be stretched to
1417 fit pages in a second formatting run. This is fairly new and
1418 complicated; see @inputfileref{input/regression/,page-layout-twopass.ly}
1423 @subsection Page breaking
1425 The default page breaking may be overriden by inserting
1426 @code{\pageBreak} or @code{\noPageBreak} commands. These commands are
1427 analogous to @code{\break} and @code{\noBreak}. They should be
1428 inserted at a bar line. These commands force and forbid a page-break
1429 from happening. Of course, the @code{\pageBreak} command also forces
1432 Page breaks are computed by the @code{page-breaking} function in the
1433 @code{\paper} block.
1435 To force a new page for a new piece (in a collection of pieces or a
1436 piece in several movements), use @code{breakbefore} in the header.
1447 @cindex @code{\pageBreak}
1449 @cindex @code{\noPageBreak}
1455 The @code{breakbefore=##t} header requires that there is a @code{piece} header as well. It may be used as a normal header, or left blank (@code{=""}) as in the example above, but it must be present.
1459 @node Multiple movements
1460 @section Multiple movements
1462 @cindex bibliographic information
1465 @cindex Music engraving by LilyPond
1467 A document may contain multiple pieces of music and texts. Examples
1468 of these are an etude book, or an orchestral part with multiple
1469 movements. Each movement is entered with a @code{\score} block,
1477 and texts are entered with a @code{\markup} block,
1485 @cindex @code{\book}
1487 The movements and texts are combined together in a @code{\book} block,
1505 The header for each piece of music can be put inside the @code{\score}
1506 block. The @code{piece} name from the header will be printed before
1507 each movement. The title for the entire book can be put inside the
1508 @code{\book}, but if it is not present, the @code{\header} which is at
1509 the top of the file is inserted.
1511 @cindex Engraved by LilyPond
1512 @cindex signature line
1517 title = "Eight miniatures"
1518 composer = "Igor Stravinsky"
1522 \header @{ piece = "Romanze" @}
1525 ..text of second verse..
1528 ..text of third verse..
1532 \header @{ piece = "Menuetto" @}
1540 @section MIDI output
1545 MIDI (Musical Instrument Digital Interface) is a standard for
1546 connecting and controlling digital instruments. A MIDI file is a
1547 series of notes in a number of tracks. It is not an actual
1548 sound file; you need special software to translate between the
1549 series of notes and actual sounds.
1551 Pieces of music can be converted to MIDI files, so you can listen to
1552 what was entered. This is convenient for checking the music; octaves
1553 that are off or accidentals that were mistyped stand out very much
1554 when listening to the MIDI output.
1558 Many musically interesting effects, such as swing, articulation,
1559 slurring, etc., are not translated to midi.
1561 The midi output allocates a channel for each staff, and one for global
1562 settings. Therefore the midi file should not have more than 15 staves
1563 (or 14 if you do not use drums). Other staves will remain silent.
1565 Not all midi players correctly handle tempo changes in the midi
1566 output. Players that are known to work include
1567 @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.
1570 * Creating MIDI files::
1572 * MIDI instrument names::
1575 @node Creating MIDI files
1576 @subsection Creating MIDI files
1578 To create a MIDI from a music piece of music, add a @code{\midi} block
1579 to a score, for example,
1584 \midi @{ \tempo 4=72 @}
1588 The tempo is specified using the @code{\tempo} command. In this
1589 example the tempo of quarter notes is set to 72 beats per minute.
1592 If there is a @code{\midi} command in a @code{\score}, only MIDI will
1593 be produced. When notation is needed too, a @code{\layout} block must
1599 \midi @{ \tempo 4=72 @}
1603 @cindex layout block
1607 Ties, dynamics, and tempo changes are interpreted. Dynamic marks,
1608 crescendi and decrescendi translate into MIDI volume levels. Dynamic
1609 marks translate to a fixed fraction of the available MIDI volume
1610 range, crescendi and decrescendi make the volume vary linearly between
1611 their two extremes. The fractions can be adjusted by
1612 @code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
1613 For each type of MIDI instrument, a volume range can be defined. This
1614 gives a basic equalizer control, which can enhance the quality of
1615 the MIDI output remarkably. The equalizer can be controlled by
1616 setting @code{instrumentEqualizer}.
1618 To remove dynamics from the MIDI output, insert the following lines
1619 in the @code{\midi@{@}} section.
1626 \remove "Dynamic_performer"
1627 \remove "Span_dynamic_performer"
1634 @subsection MIDI block
1638 The MIDI block is analogous to the layout block, but it is somewhat
1639 simpler. The @code{\midi} block can contain
1643 @item a @code{\tempo} definition, and
1644 @item context definitions.
1647 A number followed by a period is interpreted as a real number, so
1648 for setting the tempo for dotted notes, an extra space should be
1649 inserted, for example
1652 \midi @{ \tempo 4 . = 120 @}
1656 @cindex context definition
1658 Context definitions follow precisely the same syntax as within the
1659 \layout block. Translation modules for sound are called performers.
1660 The contexts for MIDI output are defined in @file{ly/@/performer@/-init@/.ly}.
1663 @node MIDI instrument names
1664 @subsection MIDI instrument names
1666 @cindex instrument names
1667 @cindex @code{Staff.midiInstrument}
1669 The MIDI instrument name is set by the @code{Staff.midiInstrument}
1670 property. The instrument name should be chosen from the list in
1671 @ref{MIDI instruments}.
1674 \set Staff.midiInstrument = "glockenspiel"
1678 If the selected instrument does not exactly match an instrument from
1679 the list of MIDI instruments, the Grand Piano (@code{"acoustic grand"})