2 @chapter Using LilyPond
13 @node Setting variables
14 @section Setting variables
16 When the music is converted from notes to print it is interpreted
17 in left-to-right order. This is similar to what happens when we read
18 music. During this step context-sensitive information such as the
19 accidentals to print, and where bar lines must be placed, are stored in
20 variables. These variables are called @emph{context properties}.
21 The properties can also be manipulated from input files. Consider this input:
23 \set Staff.autoBeaming = ##f
27 It sets the property named @code{autoBeaming} in the current staff at
28 this point in the music to @code{##f}, which means `false'. This
29 property controls whether beams are printed automatically:
31 @lilypond[relative=1,fragment,verbatim]
33 \set Staff.autoBeaming = ##f
38 LilyPond includes a built-in programming language, namely, a dialect
39 of Scheme. The argument to @code{\set}, @code{##f}, is an
40 expression in that language. The first hash-mark signals that a piece
41 of Scheme code follows. The second hash character is part of the
42 boolean value true (@code{#t}). Values of other types may be
45 @item a string, enclosed in double quotes, for example,
47 \set Staff.instrument = #"French Horn"
49 @item a boolean: either @code{#t} or @code{#f}, for true and false
52 \set autoBeaming = ##f
53 \set Score.skipBars = ##t
56 @item a number, such as
58 \set Score.currentBarNumber = #20
61 @item a symbol, which is introduced by a quote character, as in
63 \set Staff.crescendoSpanner = #'dashed-line
66 @item a pair, which is also introduced by a quote character, like in
67 the following statements, which set properties to the pairs (-7.5, 6)
68 and (3, 4) respectively:
71 \set Staff.minimumVerticalExtent = #'(-7.5 . 6)
72 \set Staff.timeSignatureFraction = #'(3 . 4)
75 @item a list, which is also introduced by a quote character. In the
76 following example, the @code{breakAlignOrder} property is set to a
79 \set Score.breakAlignOrder =
80 #'(left-edge time-signature key-signatures)
86 There are many different properties. Not all of them are listed in
87 this manual. However, the program reference lists them all in the
88 section @internalsref{Context-properties}, and most properties are
89 demonstrated in one of the
91 @uref{../../../input/test/out-www/collated-files.html,tips-and-tricks}
99 @node Fine tuning layout
100 @section Fine tuning layout
102 Sometimes it is necessary to change music layout by hand. When music
103 is formatted, layout objects are created for each symbol. For
104 example, every clef and every note head is represented by a layout
105 object. These layout objects also carry variables, which we call
106 @emph{layout properties}. By changing these variables from their
107 values, we can alter the look of a formatted score:
109 @lilypond[verbatim,relative]
111 \override Stem #'thickness = #3.0
116 In the example shown here, the layout property @code{thickness} (a
117 symbol) is set to 3 in the @code{Stem} layout objects of the current
118 As a result, the notes following @code{\override} have thicker
121 For the most part, a manual override is needed only on a case by
122 case basis and not for all subsequent instances of the altered
123 property. To accomplish this, simply prefix @code{\once} to the
124 @code{\override} statement and the override will apply only once,
125 immediately reverting to its default setting, i.e.
128 \once \override Stem #'thickness = #3.0
133 \once \override Stem #'thickness = #3.0
138 Some overrides are so common that predefined commands are provided as
139 a short cut. For example, @code{\slurUp} and @code{\stemDown}. These
140 commands are described in
144 @ref{Notation manual}, under the sections for slurs and stems
147 The exact tuning possibilities for each type of layout object are
148 documented in the program reference of the respective
149 object. However, many layout objects share properties, which can be
150 used to apply generic tweaks. We mention a couple of these:
153 @item The @code{extra-offset} property, which
154 @cindex @code{extra-offset}
155 has a pair of numbers as value, moves around objects in the printout.
156 The first number controls left-right movement; a positive number will
157 move the object to the right. The second number controls up-down
158 movement; a positive number will move it higher. The units of these
159 offsets are staff-spaces. The @code{extra-offset} property is a
160 low-level feature: the formatting engine is completely oblivious to
163 In the following example, the second fingering is moved a little to
164 the left, and 1.8 staff space downwards:
166 @cindex setting object properties
168 @lilypond[relative=1,verbatim]
171 \once \override Fingering
172 #'extra-offset = #'(-0.3 . -1.8)
177 Setting the @code{transparent} property will cause an object to be printed
178 in `invisible ink': the object is not printed, but all its other
179 behavior is retained. The object still takes up space, it takes part in
180 collisions, and slurs, and ties and beams can be attached to it.
182 @cindex transparent objects
183 @cindex removing objects
184 @cindex invisible objects
185 The following example demonstrates how to connect different voices
186 using ties. Normally, ties only connect two notes in the same
187 voice. By introducing a tie in a different voice, and blanking a stem
188 in that voice, the tie appears to cross voices:
190 @lilypond[fragment,relative=1,verbatim]
192 \once \override Stem #'transparent = ##t
200 The @code{padding} property for objects with
201 @cindex @code{padding}
202 @code{side-position-interface} can be set to increase distance between
203 symbols that are printed above or below notes. We only give an
204 example; a more elaborate explanation is in @ref{Constructing a
207 @lilypond[relative=1,verbatim]
209 \override Script #'padding = #3
215 More specific overrides are also possible. The notation manual
216 discusses in depth how to figure out these statements for yourself, in
223 @section Tuning output
225 There are situations where default layout decisions are not
226 sufficient. In this section we discuss ways to override these
229 Formatting is internally done by manipulating so called objects
230 (graphic objects). Each object carries with it a set of properties
231 (object or layout properties) specific to that object. For example, a
232 stem object has properties that specify its direction, length and
235 The most direct way of tuning the output is by altering the values of
236 these properties. There are two ways of doing that: first, you can
237 temporarily change the definition of one type of object, thus
238 affecting a whole set of objects. Second, you can select one specific
239 object, and set a layout property in that object.
241 Do not confuse layout properties with translation
242 properties. Translation properties always use a mixed caps style
243 naming, and are manipulated using @code{\set} and @code{\unset}:
245 \set Context.propertyName = @var{value}
248 Layout properties are use Scheme style variable naming, i.e. lower
249 case words separated with dashes. They are symbols, and should always
250 be quoted using @code{#'}. For example, this could be an imaginary
251 layout property name:
253 #'layout-property-name
258 The introduction of the @ref{Technical manual} gives a more in-depth
259 treatment of the difference between translation and layout.
263 * Constructing a tweak::
271 @subsection Tuning objects
273 @cindex object description
275 The definition of an object is a list of default object
276 properties. For example, the definition of the Stem object (available
277 in @file{scm/define-grobs.scm}), includes the following definitions
278 for @internalsref{Stem}:
282 (beamed-lengths . (3.5 3.5 3.5 4.5 5.0))
283 (Y-extent-callback . ,Stem::height)
288 Adding variables on top of this existing definition overrides the
289 system default, and alters the resulting appearance of the layout
295 Changing a variable for only one object is commonly achieved with
299 \once \override @var{context}.@var{objectname}
300 @var{symbol} = @var{value}
302 Here @var{symbol} is a Scheme expression of symbol type, @var{context}
303 and @var{objectname} is a string and @var{value} is a Scheme expression.
304 This command applies a setting only during one moment in the score.
306 In the following example, only one @internalsref{Stem} object is
307 changed from its original setting:
309 @lilypond[verbatim,fragment,relative=1]
311 \once \override Voice.Stem #'thickness = #4
317 For changing more objects, the same command, without @code{\once} can
320 \override @var{context}.@var{objectname} @var{symbol} = @var{value}
322 This command adds @code{@var{symbol} = @var{value}} to the definition
323 of @var{objectname} in the context @var{context}, and this definition
324 stays in place until it is removed.
326 An existing definition may be removed by the following command:
329 \property @var{context}.@var{objectname} \revert @var{symbol}
335 c'4 \override Stem #'thickness = #4.0
337 c'4 \revert Stem #'thickness
341 The following example gives exactly the same result as the previous
342 one (assuming the system default for stem thickness is 1.3):
345 c'4 \override Stem #'thickness = #4.0
347 c'4 \override Stem #'thickness = #1.3
351 Reverting a setting which was not set in the first place has no
357 Internals: @internalsref{OverrideProperty}, @internalsref{RevertProperty},
358 @internalsref{PropertySet}, @internalsref{All-backend-properties}, and
359 @internalsref{All-layout-objects}.
364 The back-end is not very strict in type-checking object properties.
365 Cyclic references in Scheme values for properties can cause hangs
369 * Constructing a tweak::
375 @node Constructing a tweak
376 @subsection Constructing a tweak
379 @cindex internal documentation
380 @cindex finding graphical objects
381 @cindex graphical object descriptions
383 @cindex @code{\override}
385 @cindex internal documentation
389 Three pieces of information are required to use @code{\override} and
390 @code{\set}: the name of the layout object, the context and the name
391 of the property. We demonstrate how to glean this information from
392 the notation manual and the generated documentation.
394 The generated documentation is a set of HTML pages which should be
395 included if you installed a binary distribution, typically in
396 @file{/usr/share/doc/lilypond}. They are also available on the web:
397 go to the @uref{http://lilypond.org,LilyPond website}, click
398 ``Documentation'', select the correct version, and click then
399 ``Program reference.'' It is advisable to bookmark the local HTML
400 files. They will load faster than the ones on the web. If you use the
401 version from the web, you must check whether the documentation matches
402 the program version: it is generated from the definitions that the
403 program uses, and therefore it is strongly tied to the LilyPond
407 @c [TODO: revise for new site.]
409 Suppose we want to move the fingering indication in the fragment below:
411 @lilypond[relative=2,verbatim]
417 If you visit the documentation of @code{Fingering} (in @ref{Fingering
418 instructions}), you will notice that there is written:
423 Internals: @internalsref{FingerEvent} and @internalsref{Fingering}.
430 In other words, the fingerings once entered, are internally stored as
431 @code{FingerEvent} music objects. When printed, a @code{Fingering}
432 layout object is created for every @code{FingerEvent}.
434 The Fingering object has a number of different functions, and each of
435 those is captured in an interface. The interfaces are listed under
436 @internalsref{Fingering} in the program reference.
440 The @code{Fingering} object has a fixed size
441 (@internalsref{item-interface}), the symbol is a piece of text
442 (@internalsref{text-interface}), whose font can be set
443 (@internalsref{font-interface}). It is centered horizontally
444 (@internalsref{self-alignment-interface}), it is placed next to other
445 objects (@internalsref{side-position-interface}) vertically, and its
446 placement is coordinated with other scripts
447 (@internalsref{text-script-interface}). It also has the standard
448 @internalsref{grob-interface} (grob stands for Graphical object)
450 @cindex graphical object
451 @cindex layout object
452 @cindex object, layout
453 with all the variables that come with
454 it. Finally, it denotes a fingering instruction, so it has
455 @internalsref{finger-interface}.
457 For the vertical placement, we have to look under
458 @code{side-position-interface}:
460 @code{side-position-interface}
462 Position a victim object (this one) next to other objects (the
463 support). In this case, the property @code{direction} signifies where to put the
464 victim object relative to the support (left or right, up or down?)
469 below this description, the variable @code{padding} is described as
473 (dimension, in staff space)
475 add this much extra space between objects that are next to each
476 other. Default value: @code{0.6}
480 By increasing the value of @code{padding}, we can move away the
481 fingering. The following command inserts 3 staff spaces of white
482 between the note and the fingering:
484 \once \override Fingering #'padding = #3
487 Inserting this command before the Fingering object is created,
488 i.e. before @code{c2}, yields the following result:
490 @lilypond[relative=2,fragment,verbatim]
491 \once \override Fingering
498 The context name @code{Voice} in the example above can be determined
499 as follows. In the documentation for @internalsref{Fingering}, it says
501 Fingering grobs are created by: @internalsref{Fingering_engraver} @c
504 Clicking @code{Fingering_engraver} shows the documentation of
505 the module responsible for interpreting the fingering instructions and
506 translating them to a @code{Fingering} object. Such a module is called
507 an @emph{engraver}. The documentation of the @code{Fingering_engraver}
510 Fingering_engraver is part of contexts: Voice
512 so tuning the settings for Fingering should be done with
514 \override Fingering @dots{}
517 Of course, the tweak may also done in a larger context than
518 @code{Voice}, for example, @internalsref{Staff} or
519 @internalsref{Score}.
523 Internals: the program reference also contains alphabetical lists of
524 @internalsref{Contexts}, @internalsref{All-layout-objects} and
525 @internalsref{Music-expressions}, so you can also find which objects
526 to tweak by browsing the internals document.
530 @subsection Applyoutput
532 The most versatile way of tuning an object is @code{\applyoutput}. Its
535 \applyoutput @var{proc}
539 where @var{proc} is a Scheme function, taking three arguments.
541 When interpreted, the function @var{proc} is called for every layout
542 object found in the context, with the following arguments:
544 @item the layout object itself,
545 @item the context where the layout object was created, and
546 @item the context where @code{\applyoutput} is processed.
550 In addition, the cause of the layout object, i.e. the music
551 expression or object that was responsible for creating it, is in the
552 object property @code{cause}. For example, for a note head, this is a
553 @internalsref{NoteHead} event, and for a @internalsref{Stem} object,
554 this is a @internalsref{NoteHead} object.
556 Here is a simple example of @code{\applyoutput}; it blanks note-heads on the
559 (define (blanker grob grob-origin context)
560 (if (and (memq (ly:grob-property grob 'interfaces)
562 (eq? (ly:grob-property grob 'staff-position) 0))
564 (ly:grob-set-property! grob 'transparent #t)))
570 @subsection Font selection
572 The most common thing to change about the appearance of fonts is their
573 size. The font size of any context can be easily changed by setting
574 the @code{fontSize} property for that context. Its value is a number:
575 negative numbers make the font smaller, positive numbers larger. An
576 example is given below:
578 @lilypond[fragment,relative=1,verbatim]
579 c4 c4 \set fontSize = #-1
582 This command will set @code{font-size} (see below), and does
583 not change the size of variable symbols, such as beams or slurs.
585 One of the uses of @code{fontSize} is to get smaller symbols for cue
586 notes. An elaborate example of those is in
587 @inputfileref{input/test,cue-notes.ly}.
589 @cindex magnification
592 The font used for printing a object can be selected by setting
593 @code{font-name}, e.g.
595 \override Staff.TimeSignature
596 #'font-name = #"cmr17"
600 Any font can be used, as long as it is available to @TeX{}. Possible
601 fonts include foreign fonts or fonts that do not belong to the
602 Computer Modern font family. The size of fonts selected in this way
603 can be changed with the @code{font-magnification} property. For
604 example, @code{2.0} blows up all letters by a factor 2 in both
608 @cindex font magnification
610 Font selection for the standard fonts, @TeX{}'s Computer Modern fonts,
611 can also be adjusted with a more fine-grained mechanism. By setting
612 the object properties described below, you can select a different font;
613 all three mechanisms work for every object that supports
614 @code{font-interface}:
619 is a symbol indicating the general class of the typeface. Supported are
620 @code{roman} (Computer Modern), @code{braces} (for piano staff
621 braces), @code{music} (the standard music font, including ancient
622 glyphs), @code{dynamic} (for dynamic signs) and @code{typewriter}.
625 is a symbol indicating the shape of the font, there are typically several
626 font shapes available for each font family. Choices are @code{italic},
627 @code{caps} and @code{upright}.
630 is a symbol indicating the series of the font. There are typically several
631 font series for each font family and shape. Choices are @code{medium}
636 For any of these properties, the value @code{*} (i.e. the symbol
637 @code{*}, entered as @code{#'*}), acts as a wildcard. This can be used
638 to override default setting, which are always present. For example:
640 \override Lyrics .LyricText #'font-series = #'bold
641 \override Lyrics .LyricText #'font-family = #'typewriter
642 \override Lyrics .LyricText #'font-shape = #'*
645 @cindex @code{font-style}
647 The font size is set by modifying the @code{font-size} property. Its
648 value is a number indicating the size relative to the standard size.
649 Each step up is an increase of approximately 12% of the font size. Six
650 steps is exactly a factor two. The Scheme function @code{magstep}
651 converts a @code{font-size} number to a scaling factor.
653 LilyPond has fonts in different design sizes: the music fonts for
654 smaller sizes are chubbier, while the text fonts are relatively wider.
655 Font size changes are achieved by scaling the design size that is
656 closest to the desired size.
658 The @code{font-size} mechanism does not work for fonts selected
659 through @code{font-name}. These may be scaled with
660 @code{font-magnification}.
664 The following commands set @code{fontSize} for the current voice.
668 @cindex @code{\small}
670 @cindex @code{\normalsize}
675 Init files: @file{ly/declarations-init.ly} contains hints how new
676 fonts may be added to LilyPond.
680 There is no style sheet provided for other fonts besides the @TeX{}
681 Computer Modern family.
683 @cindex font selection
684 @cindex font magnification
685 @cindex @code{font-interface}
696 LilyPond has an internal mechanism to typeset texts. You can access it
697 with the keyword @code{\markup}. Within markup mode, you can enter texts
698 similar to lyrics: simply enter them, surrounded by spaces:
701 @lilypond[verbatim,fragment,relative=1]
703 c1_\markup { hi there }
704 c1^\markup { hi \bold there, is \italic anyone home? }
707 @cindex font switching
709 The markup in the example demonstrates font switching commands. The
710 command @code{\bold} and @code{\italic} only apply to the first
711 following word; enclose a set of texts with braces to apply a command
714 \markup @{ \bold @{ hi there @} @}
718 For clarity, you can also do this for single arguments, e.g.
721 \markup { is \italic { anyone } home }
724 @cindex font size, texts
727 In markup mode you can compose expressions, similar to mathematical
728 expressions, XML documents and music expressions. The braces group
729 notes into horizontal lines. Other types of lists also exist: you can
730 stack expressions grouped with @code{<}, and @code{>} vertically with
731 the command @code{\column}. Similarly, @code{\center-align} aligns
732 texts by their center lines:
734 @lilypond[verbatim,fragment,relative=1]
735 c1^\markup { \column < a bbbb c > }
736 c1^\markup { \center-align < a bbbb c > }
737 c1^\markup { \line < a b c > }
741 Markups can be stored in variables, and these variables
742 may be attached to notes, like
744 allegro = \markup { \bold \large { Allegro } }
745 \notes { a^\allegro b c d }
749 Some objects have alignment procedures of their own, which cancel out
750 any effects of alignments applied to their markup arguments as a
751 whole. For example, the @internalsref{RehearsalMark} is horizontally
752 centered, so using @code{\mark \markup @{ \left-align .. @}} has no
753 effect. Similarly, whole texts over notes cannot be moved vertically
754 with @code{\raise}. For moving and aligning complete objects, grob
755 properties should be used.
761 Init files: @file{scm/new-markup.scm}.
766 Text layout is ultimately done by @TeX{}, which does kerning of
767 letters. LilyPond does not account for kerning, so texts will be
768 spaced slightly too wide.
770 Syntax errors for markup mode are confusing.
772 Markup texts cannot be used in the titling of the @code{\header}
773 field. Titles are made by La@TeX{}, so La@TeX{} commands should be used
779 * Overview of text markup commands::
780 * Markup construction in scheme::
781 * Markup command definition::
784 @node Overview of text markup commands
785 @subsection Overview of text markup commands
787 @include markup-commands.tely
789 @node Markup construction in scheme
790 @subsection Markup construction in scheme
792 @cindex defining markup commands
794 The @code{markup} macro builds markup expressions in Scheme while
795 providing a LilyPond-like syntax. For example,
797 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
798 #:bigger #:line ("foo" "bar" "baz")))
804 \markup \column < @{ \bold \italic "hello" \raise #0.4 "world" @}
805 \bigger @{ foo bar baz @} >
809 This example exposes the main translation rules between regular
810 LilyPond markup syntax and scheme markup syntax, which are summed up
812 @multitable @columnfractions .5 .5
813 @item @b{LilyPond} @tab @b{Scheme}
814 @item @code{\command} @tab @code{#:command}
815 @item @code{\variable} @tab @code{variable}
816 @item @code{@{ ... @}} @tab @code{#:line ( ... )}
817 @item @code{\center-align < ... >} @tab @code{#:center ( ... )}
818 @item @code{string} @tab @code{"string"}
819 @item @code{#scheme-arg} @tab @code{scheme-arg}
822 Besides, the whole scheme language is accessible inside the
823 @code{markup} macro: thus, one may use function calls inside
824 @code{markup} in order to manipulate character strings for
825 instance. This proves useful when defining new markup commands (see
826 @ref{Markup command definition}).
830 One can not feed the @code{#:line} (resp @code{#:center},
831 @code{#:column}) command with a variable or the result of a function
834 (markup #:line (fun-that-returns-markups))
836 is illegal. One should use the @code{make-line-markup} (resp
837 @code{make-center-markup}, @code{make-column-markup}) function
840 (markup (make-line-markup (fun-that-returns-markups)))
843 @node Markup command definition
844 @subsection Markup command definition
846 New markup commands can be defined thanks to the @code{def-markup-command} scheme macro.
848 (def-markup-command (@var{command-name} @var{paper} @var{props} @var{arg1} @var{arg2} ...)
849 (@var{arg1-type?} @var{arg2-type?} ...)
852 @var{argi}: i@var{th} command argument
853 @var{argi-type?}: a type predicate for the i@var{th} argument
854 @var{paper}: the `paper' definition
855 @var{props}: a list of alists, containing all active properties.
858 As a simple example, we show how to add a @code{\smallcaps} command,
859 which selects @TeX{}'s small caps font. Normally, we could select the
860 small caps font as follows:
863 \markup { \override #'(font-shape . caps) Text-in-caps }
866 This selects the caps font by setting the @code{font-shape} property to
867 @code{#'caps} for interpreting @code{Text-in-caps}.
869 To make the above available as @code{\smallcaps} command, we have to
870 define a function using @code{def-markup-command}. The command should
871 take a single argument, of markup type. Therefore, the start of the
872 definition should read
874 (def-markup-command (smallcaps paper props argument) (markup?)
879 What follows is the content of the command: we should interpret
880 the @code{argument} as a markup, i.e.
883 (interpret-markup paper @dots{} argument)
887 This interpretation should add @code{'(font-shape . caps)} to the active
888 properties, so we substitute the the following for the @dots{} in the
892 (cons (list '(font-shape . caps) ) props)
896 The variable @code{props} is a list of alists, and we prepend to it by
897 consing a list with the extra setting.
899 However, suppose that we are using a font that does not have a
900 small-caps variant. In that case, we have to fake the small caps font,
901 by setting a string in upcase, with the first letter a little larger:
904 #(def-markup-command (smallcaps paper props str) (string?)
905 "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
906 (interpret-markup paper props
909 (if (= (string-length s) 0)
911 (markup #:large (string-upcase (substring s 0 1))
912 #:translate (cons -0.6 0)
913 #:tiny (string-upcase (substring s 1)))))
914 (string-split str #\Space)))))
917 The @code{smallcaps} command first splits its string argument into
918 tokens separated by spaces (@code{(string-split str #\Space)}); for
919 each token, a markup is built with the first letter made large and
920 upcased (@code{#:large (string-upcase (substring s 0 1))}), and a
921 second markup built with the following letters made tiny and upcased
922 (@code{#:tiny (string-upcase (substring s 1))}). As LilyPond
923 introduces a space between markups on a line, the second markup is
924 translated to the left (@code{#:translate (cons -0.6 0) ...}). Then,
925 the markups built for each token are put in a line
926 (@code{(make-line-markup ...)}). Finally, the resulting markup is
927 passed to the @code{interpret-markup} function, with the @code{paper}
928 and @code{props} arguments.
930 Finally, suppose that we are typesetting a recitative in an opera, and
931 we would like to define a command that will show character names in a
932 custom manner. Names should be printed with small caps and translated a
933 bit to the left and top. We will define a @code{\character} command
934 that takes into account the needed translation, and uses the newly
935 defined @code{\smallcaps} command:
938 #(def-markup-command (character paper props name) (string?)
939 "Print the character name in small caps, translated to the left and
940 top. Syntax: \\character #\"name\""
941 (interpret-markup paper props
942 (markup "" #:translate (cons -4 2) #:smallcaps name)))
945 There is one complication that needs explanation: texts above and below
946 the staff are moved vertically to be at a certain distance (the
947 @code{padding} property) from the staff and the notes. To make sure
948 that this mechanism does not annihilate the vertical effect of our
949 @code{#:translate}, we add an empty string (@code{""}) before the
950 translated text. Now the @code{""} will be put above the notes, and the
951 @code{name} is moved in relation to that empty string. The net effect is
952 that the text is moved to the upper left.
954 The final result is as follows:
958 c''^\markup \character #"Cleopatra"
959 e'^\markup \character #"Giulio Cesare"
964 @lilypond[raggedright]
965 #(def-markup-command (smallcaps paper props str) (string?)
966 "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
967 (interpret-markup paper props
970 (if (= (string-length s) 0)
972 (markup #:large (string-upcase (substring s 0 1))
973 #:translate (cons -0.6 0)
974 #:tiny (string-upcase (substring s 1)))))
975 (string-split str #\Space)))))
977 #(def-markup-command (character paper props name) (string?)
978 "Print the character name in small caps, translated to the left and
979 top. Syntax: \\character #\"name\""
980 (interpret-markup paper props
981 (markup "" #:translate (cons -4 0) #:smallcaps name)))
985 c''^\markup \character #"Cleopatra"
986 e'^\markup \character #"Giulio Cesare"
994 @section Global layout
996 The global layout determined by three factors: the page layout, the
997 line breaks and the spacing. These all influence each other. The
998 choice of spacing determines how densely each system of music is set,
999 which influences where line breaks breaks are chosen, and thus
1000 ultimately how many pages a piece of music takes. This section
1001 explains how to tune the algorithm for spacing.
1003 Globally spoken, this procedure happens in three steps: first,
1004 flexible distances (``springs'') are chosen, based on durations. All
1005 possible line breaking combination are tried, and the one with the
1006 best results---a layout that has uniform density and requires as
1007 little stretching or cramping as possible---is chosen. When the score
1008 is processed by @TeX{}, each page is filled with systems, and page breaks
1009 are chosen whenever the page gets full.
1014 * Vertical spacing::
1015 * Horizontal spacing::
1022 @node Vertical spacing
1023 @subsection Vertical spacing
1025 @cindex vertical spacing
1026 @cindex distance between staves
1027 @cindex staff distance
1028 @cindex between staves, distance
1029 @cindex staffs per page
1030 @cindex space between staves
1032 The height of each system is determined automatically by LilyPond, to
1033 keep systems from bumping into each other, some minimum distances are
1034 set. By changing these, you can put staves closer together, and thus
1035 put more systems onto one page.
1037 Normally staves are stacked vertically. To make
1038 staves maintain a distance, their vertical size is padded. This is
1039 done with the property @code{minimumVerticalExtent}. It takes a pair
1040 of numbers, so if you want to make it smaller from its, then you could
1043 \set Staff.minimumVerticalExtent = #'(-4 . 4)
1045 This sets the vertical size of the current staff to 4 staff spaces on
1046 either side of the center staff line. The argument of
1047 @code{minimumVerticalExtent} is interpreted as an interval, where the
1048 center line is the 0, so the first number is generally negative. The
1049 staff can be made larger at the bottom by setting it to @code{(-6
1052 The piano staves are handled a little differently: to make cross-staff
1053 beaming work correctly, it is necessary that the distance between staves
1054 is fixed beforehand. This is also done with a
1055 @internalsref{VerticalAlignment} object, created in
1056 @internalsref{PianoStaff}. In this object the distance between the
1057 staves is fixed by setting @code{forced-distance}. If you want to
1058 override this, use a @code{\translator} block as follows:
1063 \override VerticalAlignment #'forced-distance = #9
1068 This would bring the staves together at a distance of 9 staff spaces,
1069 measured from the center line of each staff.
1073 Internals: Vertical alignment of staves is handled by the
1074 @internalsref{VerticalAlignment} object.
1079 @node Horizontal spacing
1080 @subsection Horizontal Spacing
1082 The spacing engine translates differences in durations into
1083 stretchable distances (``springs'') of differing lengths. Longer
1084 durations get more space, shorter durations get less. The shortest
1085 durations get a fixed amount of space (which is controlled by
1086 @code{shortest-duration-space} in the @internalsref{SpacingSpanner} object).
1087 The longer the duration, the more space it gets: doubling a
1088 duration adds a fixed amount (this amount is controlled by
1089 @code{spacing-increment}) of space to the note.
1091 For example, the following piece contains lots of half, quarter and
1092 8th notes, the eighth note is followed by 1 note head width (NHW).
1093 The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
1094 @lilypond[fragment,verbatim,relative=1] c2 c4. c8 c4. c8 c4. c8 c8
1098 Normally, @code{shortest-duration-space} is set to 1.2, which is the
1099 width of a note head, and @code{shortest-duration-space} is set to
1100 2.0, meaning that the shortest note gets 2 NHW (i.e. 2 times
1101 @code{shortest-duration-space}) of space. For normal notes, this space
1102 is always counted from the left edge of the symbol, so the shortest
1103 notes are generally followed by one NHW of space.
1105 If one would follow the above procedure exactly, then adding a single
1106 32th note to a score that uses 8th and 16th notes, would widen up the
1107 entire score a lot. The shortest note is no longer a 16th, but a 32nd,
1108 thus adding 1 NHW to every note. To prevent this, the
1109 shortest duration for spacing is not the shortest note in the score,
1110 but the most commonly found shortest note. Notes that are even
1111 shorter this are followed by a space that is proportional to their
1112 duration relative to the common shortest note. So if we were to add
1113 only a few 16th notes to the example above, they would be followed by
1116 @lilypond[fragment,verbatim,relative=2]
1117 c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
1120 The most common shortest duration is determined as follows: in every
1121 measure, the shortest duration is determined. The most common short
1122 duration, is taken as the basis for the spacing, with the stipulation
1123 that this shortest duration should always be equal to or shorter than
1124 1/8th note. The shortest duration is printed when you run lilypond
1125 with @code{--verbose}. These durations may also be customized. If you
1126 set the @code{common-shortest-duration} in
1127 @internalsref{SpacingSpanner}, then this sets the base duration for
1128 spacing. The maximum duration for this base (normally 1/8th), is set
1129 through @code{base-shortest-duration}.
1131 @cindex @code{common-shortest-duration}
1132 @cindex @code{base-shortest-duration}
1133 @cindex @code{stem-spacing-correction}
1134 @cindex @code{spacing}
1136 In the introduction it was explained that stem directions influence
1137 spacing. This is controlled with @code{stem-spacing-correction}
1138 property in @internalsref{NoteSpacing}, which are generated for every
1139 @internalsref{Voice} context. The @code{StaffSpacing} object
1140 (generated at @internalsref{Staff} context) contains the same property
1141 for controlling the stem/bar line spacing. The following example
1142 shows these corrections, once with default settings, and once with
1143 exaggerated corrections:
1149 \override Staff.NoteSpacing #'stem-spacing-correction
1151 \override Staff.StaffSpacing #'stem-spacing-correction
1156 \paper { raggedright = ##t } }
1159 @cindex SpacingSpanner, overriding properties
1161 Properties of the @internalsref{SpacingSpanner} must be overridden
1162 from the @code{\paper} block, since the @internalsref{SpacingSpanner} is
1163 created before any property commands are interpreted.
1165 \paper @{ \translator @{
1167 SpacingSpanner \override #'spacing-increment = #3.0
1174 Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
1175 @internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
1176 @internalsref{SeparatingGroupSpanner}.
1180 Spacing is determined on a score wide basis. If you have a score that
1181 changes its character (measured in durations) halfway during the
1182 score, the part containing the longer durations will be spaced too
1185 There is no convenient mechanism to manually override spacing.
1190 @subsection Font size
1191 @cindex font size, setting
1192 @cindex staff size, setting
1193 @cindex @code{paper} file
1195 The Feta font provides musical symbols at eight seven different
1196 sizes. Each font is tuned for a different staff size: at smaller sizes
1197 the font gets heavier, to match the relatively heavier staff lines.
1198 The recommended font sizes are listed in the following table:
1200 @multitable @columnfractions .25 .25 .25 .25
1203 @tab @b{staff height (pt)}
1204 @tab @b{staff height (mm)}
1246 @c modern rental material ?
1250 These fonts are available in any sizes. The context property
1251 @code{fontSize} and the layout property @code{staff-space} (in
1252 @internalsref{StaffSymbol}) can be used to tune size for individual
1253 staffs. The size of individual staffs are relative to the global size,
1254 which can be set in the following manner:
1257 #(set-global-staff-size 14)
1260 This sets the global default size to 14pt staff height, and scales all
1266 @subsection Line breaking
1269 @cindex breaking lines
1271 Line breaks are normally computed automatically. They are chosen such
1272 that lines look neither cramped nor loose, and that consecutive lines
1273 have similar density.
1275 Occasionally you might want to override the automatic breaks; you can
1276 do this by specifying @code{\break}. This will force a line break at
1277 this point. Line breaks can only occur at places where there are bar
1278 lines. If you want to have a line break where there is no bar line,
1279 you can force an invisible bar line by entering @code{\bar
1280 ""}. Similarly, @code{\noBreak} forbids a line break at a
1284 @cindex regular line breaks
1285 @cindex four bar music.
1287 For line breaks at regular intervals use @code{\break} separated by
1288 skips and repeated with @code{\repeat}:
1290 << \repeat unfold 7 @{
1291 s1 \noBreak s1 \noBreak
1292 s1 \noBreak s1 \break @}
1293 @emph{the real music}
1298 This makes the following 28 measures (assuming 4/4 time) be broken every
1299 4 measures, and only there.
1303 @code{\break}, @code{\noBreak}
1304 @cindex @code{\break}
1305 @cindex @code{\noBreak}
1309 Internals: @internalsref{BreakEvent}.
1313 @subsection Page layout
1316 @cindex breaking pages
1318 @cindex @code{indent}
1319 @cindex @code{linewidth}
1321 The most basic settings influencing the spacing are @code{indent} and
1322 @code{linewidth}. They are set in the @code{\paper} block. They
1323 control the indentation of the first line of music, and the lengths of
1326 If @code{raggedright} is set to true in the @code{\paper}
1327 block, then the lines are justified at their natural length. This
1328 useful for short fragments, and for checking how tight the natural
1332 @cindex vertical spacing
1334 The page layout process happens outside the LilyPond formatting
1335 engine: variables controlling page layout are passed to the output,
1336 and are further interpreted by @code{lilypond} wrapper program. It
1337 responds to the following variables in the @code{\paper} block. The
1338 variable @code{textheight} sets the total height of the music on each
1339 page. The spacing between systems is controlled with
1340 @code{interscoreline}, its default is 16pt. The distance between the
1341 score lines will stretch in order to fill the full page
1342 @code{interscorelinefill} is set to a positive number. In that case
1343 @code{interscoreline} specifies the minimum spacing.
1345 @cindex @code{textheight}
1346 @cindex @code{interscoreline}
1347 @cindex @code{interscorelinefill}
1349 If the variable @code{lastpagefill} is defined,
1350 @c fixme: this should only be done if lastpagefill= #t
1351 systems are evenly distributed vertically on the last page. This
1352 might produce ugly results in case there are not enough systems on the
1353 last page. The @command{lilypond-book} command ignores
1354 @code{lastpagefill}. See @ref{lilypond-book manual} for more
1357 @cindex @code{lastpagefill}
1359 Page breaks are normally computed by @TeX{}, so they are not under
1360 direct control of LilyPond. However, you can insert a commands into
1361 the @file{.tex} output to instruct @TeX{} where to break pages. This
1362 is done by setting the @code{between-systems-strings} on the
1363 @internalsref{NonMusicalPaperColumn} where the system is broken.
1364 An example is shown in @inputfileref{input/regression,between-systems.ly}.
1365 The predefined command @code{\newpage} also does this.
1369 @cindex @code{papersize}
1371 To change the paper size, use the following Scheme code:
1374 #(set-paper-size "a4")
1381 @cindex @code{\newpage}
1387 In this manual: @ref{Invoking lilypond}.
1389 Examples: @inputfileref{input/regression,between-systems.ly}.
1391 Internals: @internalsref{NonMusicalPaperColumn}.
1395 LilyPond has no concept of page layout, which makes it difficult to
1396 reliably choose page breaks in longer pieces.
1405 Entered music can also be converted to MIDI output. The performance
1406 is good enough for proof-hearing the music for errors.
1408 Ties, dynamics and tempo changes are interpreted. Dynamic marks,
1409 crescendi and decrescendi translate into MIDI volume levels. Dynamic
1410 marks translate to a fixed fraction of the available MIDI volume
1411 range, crescendi and decrescendi make the volume vary linearly between
1412 their two extremities. The fractions can be adjusted by
1413 @code{dynamicAbsoluteVolumeFunction} in @internalsref{Voice} context.
1414 For each type of MIDI instrument, a volume range can be defined. This
1415 gives a basic equalizer control, which can enhance the quality of
1416 the MIDI output remarkably. The equalizer can be controlled by
1417 setting @code{instrumentEqualizer}.
1421 Many musically interesting effects, such as swing, articulation,
1422 slurring, etc., are not translated to MIDI.
1424 Since slurs are not interpreted, @code{\lyricsto} and
1425 @code{\addlyrics} sections will be interpreted wrongly.
1427 The MIDI output allocates a channel for each Staff, and one for global
1428 settings. Hence, the MIDI file should not have more than 15 staves
1429 (or 14 if you do not use drums).
1434 * MIDI instrument names::
1439 @subsection MIDI block
1443 The MIDI block is analogous to the paper block, but it is somewhat
1444 simpler. The @code{\midi} block can contain:
1448 @item a @code{\tempo} definition, and
1449 @item context definitions.
1452 Assignments in the @code{\midi} block are not allowed.
1454 A number followed by a period is interpreted as a real number, so
1455 for setting the tempo for dotted notes, an extra space should be
1456 inserted, for example:
1459 \midi @{ \tempo 4 . = 120 @}
1463 @cindex context definition
1465 Context definitions follow precisely the same syntax as within the
1466 \paper block. Translation modules for sound are called performers.
1467 The contexts for MIDI output are defined in @file{ly/performer-init.ly}.
1470 @node MIDI instrument names
1471 @subsection MIDI instrument names
1473 @cindex instrument names
1474 @cindex @code{Staff.midiInstrument}
1476 The MIDI instrument name is set by the @code{Staff.midiInstrument}
1477 property. The instrument name should be chosen from the list in
1478 @ref{MIDI instruments}.
1482 If the selected string does not exactly match, then the default is
1483 used, which is the Grand Piano.