1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-learning.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
11 @chapter Tweaking output
13 This chapter discusses how to modify output. LilyPond is extremely
14 configurable; virtually every fragment of output may be changed.
16 NB: This chapter is still under development and this version is
17 somewhat experimental; nothing is fixed. Don't translate yet!
23 * The Internals Reference manual::
24 * Appearance of objects::
30 @section Tweaking basics
33 * Introduction to tweaks::
34 * Objects and interfaces::
35 * Naming conventions of objects and properties::
39 @node Introduction to tweaks
40 @subsection Introduction to tweaks
42 @q{Tweaking} is a LilyPond term for the various methods available
43 to the user for modifying the actions taken during interpretation
44 of the input file and modifying the appearance of the printed
45 output. Some tweaks are very easy to use; others are more
46 complex. But taken together the methods available for tweaking
47 permit almost any desired appearance of the printed music to be
50 In this section we cover the basic concepts required to understand
51 tweaking. Later we give a variety of potted commands which can
52 simply be copied to obtain the same effect in your own scores, and
53 at the same time we show how these commands may be constructed so
54 that you may learn how to develop your own tweaks.
56 Before starting on this Chapter you may wish to review the section
57 @ref{Contexts and engravers}, as Contexts, Engravers, and the
58 Properties contained within them are fundamental to understanding
59 and constructing Tweaks.
61 @node Objects and interfaces
62 @subsection Objects and interfaces
69 Tweaking involves modifying the internal operation and structures
70 of the LilyPond program, so we must first introduce some terms
71 which are used to describe those internal operations and
74 The term @q{Object} is a generic term used to refer to the
75 multitude of internal structures built by LilyPond during the
76 processing of an input file. So when a command like @code{\new
77 Staff} is encountered a new object of type @code{Staff} is
78 constructed. That @code{Staff} object then holds all the
79 properties associated with that particular staff, for example, its
80 name and its key signature, together with details of the engravers
81 which have been assigned to operate within that staff's context.
82 Similarly, there are @code{Voice} objects, @code{Score} objects,
83 @code{Lyric} objects, and objects to represent barlines,
84 noteheads, ties, dynamics, etc, each with their own set of
87 Some types of object are given special names. Objects which
88 represent items of notation on the printed output such as
89 noteheads, stems, slurs, ties, fingering, clefs, etc are called
90 @q{Layout objects}, often known as @q{Graphical Objects}, or
91 @q{Grobs} for short. These are still objects in the generic sense
92 above, and so they too all have properties associated with them,
93 such as their position, size, color, etc.
95 Some layout objects are still more specialised. Phrasing slurs,
96 crescendo hairpins, ottavo marks, and many other grobs are not
97 localised in a single place -- they have a starting point, an
98 ending point, and maybe other properties concerned with their
99 shape. Objects with an extended shape like these are called
102 It remains to explain what @q{Interfaces} are. Many objects,
103 even though they are quite different, share common features
104 which need to be processed in the same way.
105 For example, all grobs have a color, a size, a position, etc,
106 and all these properties are processed in the same way during
108 interpretation of the input file. To simplify these internal
109 operations these common actions and properties are grouped
110 together in an object called a @code{grob-interface}. There
111 are many other groupings of common properties like this, each
112 one given a name ending in @code{-interface}. In total there
113 are over 100 such interfaces. We shall see later why this is
114 of interest and use to the user.
116 These, then, are the main terms relating to objects which we
117 shall use in this chapter.
119 @node Naming conventions of objects and properties
120 @subsection Naming conventions of objects and properties
122 We met some object naming conventions previously, in
123 @ref{Contexts and engravers}. Here for reference is a list
124 of the most common object and property types together with
125 the conventions for naming them and a couple of examples of
126 some real names. We have used A to stand for any capitalised
127 alphabetic character and aaa to stand for any number of
128 lower-case alphabetic characters. Other charaters are used
131 @multitable @columnfractions .33 .33 .33
132 @headitem Object/property type
133 @tab Naming convention
135 @item Contexts, Layout Objects
136 @tab Aaaa or AaaaAaaaAaaa
137 @tab Staff, GrandStaff,
139 @tab Aaaa_aaa_engraver
140 @tab Clef_engraver, Note_heads_engraver
142 @tab aaa-aaa-interface
143 @tab grob-interface, break-aligned-interface
144 @item Context Properties
145 @tab aaa or aaaAaaaAaaa
146 @tab alignAboveContext, skipBars
147 @item Layout Object Properties
148 @tab aaa or aaa-aaa-aaa
149 @tab direction, beam-thickness
152 As we shall see shortly, the properties of different types of
153 object are modified by different commands, so it is useful to
154 be able to recognise the type of object from the names of its
158 @node Tweaking methods
159 @subsection Tweaking methods
161 We have already met the commands @code{\set} and @code{\with},
162 used to change the properties of @strong{contexts} and to remove
163 and add @strong{engravers}, in
164 @ref{Modifying context properties} and @ref{Adding
165 and removing engravers}. We now must meet one more command.
167 The command to change the properties of @strong{layout objects} is
168 @code{\override}. Because this command has to modify
169 internal properties deep within LilyPond its syntax is not
170 as simple as the commands you have met so far. It needs to
171 know precisely which property of which object in which context
172 has to be modified, and what its new value is to be. Let's see
175 The general syntax of this command is:
178 \override @emph{context}.@emph{layout_object} #'@emph{layout_property} = #@emph{value}
182 This will set the property with the name @emph{layout_property}
183 of the layout object with the name
184 @emph{layout_object}, which is a member of the @emph{context}
185 context, to the value @emph{value}.
187 The @emph{context} can be omitted (and usually is) when the
188 required context is unambiguously implied and is one of lowest
189 level contexts, i.e., @code{Voice} or @code{Lyrics}, and we shall
190 omit it in the following examples. Later we shall see when it
193 For now, don't worry about the @code{#'}, which must precede the
194 layout property, and the @code{#}, which must precede the value.
195 These must always be present in exactly this form. This is the
196 most common command used in tweaking, and most of the rest of
197 this chapter will be directed to presenting examples of how it is
200 Once overridden, the property retains its new value until it is
201 overridden again or a @code{\revert} command is encountered.
202 The @code{\revert} command has the following syntax and causes
203 the value of the property to revert to its original default
204 value; note, not its previous value if several @code{\override}
205 commands have been issued.
208 \revert @emph{context}.@emph{layout_object} #'@emph{layout_property}
211 Again, the @emph{context} will be omitted for now.
213 There is another form of the override command,
214 @code{\overrideProperty}, which is occasionally required.
215 We mention it here for completeness, but for details see
216 @ruser{Difficult tweaks}.
217 @c Maybe explain in a later iteration -td
219 The final tweaking command which is available is @code{\tweak}.
220 It is not really a new command but a shorthand for an
221 @code{\override} command which must be used in a few special
222 circumstances. Again, we shall not discuss or use it here.
223 You may find the details in
224 @ruser{Objects connected to the input}.
225 @c Maybe explain in a later iteration -td
227 @node The Internals Reference manual
228 @section The Internals Reference manual
230 @cindex Internals Reference
233 * Properties of layout objects::
234 * Properties found in interfaces::
235 * Types of properties::
238 @node Properties of layout objects
239 @subsection Properties of layout objects
241 @cindex properties of layout objects
242 @cindex properties of grobs
243 @cindex grobs, properties of
244 @cindex layout objects, properties of
246 Suppose you have a slur in a score which, to your mind,
247 appears too thin and you'd like to draw it a little heavier.
248 How do you go about doing this? You know from the statements
249 earlier about the flexibility of LilyPond that such a thing
250 should be possible, and you would probably guess that an
251 @code{\override} command would be needed. But is there a
252 heaviness property for a slur, and if there is, how might it
253 be modified? This is where the Internals Reference manual
254 comes in. It contains all the information you might need to
255 construct this and all other @code{\override} commands.
257 Before we look at the Internals Reference a word of warning.
258 This is a @strong{reference} document, which means there is
259 little or no explanation contained within it: its purpose is
260 to present information precisely and concisely. This
261 means it might look daunting at first sight. Don't worry!
262 The guidance and explanation presented here will enable you
263 to extract the information from the Internals Reference for
264 yourself with just a little practice.
266 @cindex override example
267 @cindex Internals Reference, example of using
269 Let's use a concrete example with a simple fragment of real
272 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
277 g[( e]) e d[( f]) a |
281 The man who feels love's sweet e -- mo -- tion
286 Suppose now that we decide we would like the slurs to be a
287 little heavier. Is this possible? The slur is certainly a
288 layout object, so the question is, @q{Is there a property
289 belonging to a slur which controls the heaviness?} To answer
290 this we must look in the Internals Reference, or IR for short.
292 The IR for the version of LilyPond you are using may be found
293 on the LilyPond website at http://lilypond.org. Go to the
294 documentation page and click on the Internals Reference link.
295 For learning purposes you should use the standard html version,
296 not the @q{one big page} or the PDF. For the next few
297 paragraphs to make sense you will need to actually do this
300 Under the heading @strong{Top} you will see five links. Select
301 the link to the @emph{Backend}, which is where information about
302 layout objects is to be found. There, under the heading
303 @strong{Backend}, select the link to @emph{All layout objects}.
304 The page that appears lists all the layout objects used in your
305 version of LilyPond, in alphabetic order. Select the link to
306 Slur, and the properties of Slurs are listed.
308 (An alternative way of finding this page is from the Notation
309 Reference. On one of the pages that deals with slurs you may
310 find a link to the Internals Reference. This link will
311 take you directly to this page, but often it is easier to go
312 straight to the IR and search there.)
314 This Slur page in the IR tells us first that Slur objects are
316 Slur_engraver. Then it lists the standard settings. Note
317 these are @strong{not} in alphabetic order. Browse down
318 them looking for a property that might control the heaviness
319 of slurs, and you should find
322 @code{thickness} (number)
324 Line thickness, generally measured in @code{line-thickness}
327 This looks a good bet to change the heaviness. It tells us that
328 the value of @code{thickness} is a simple @emph{number},
329 that the default value is 1.2, and that the units are
330 in another property called @code{line-thickness}.
332 As we said earlier, there are few to no explanations in the IR,
333 but we already have enough information to try changing the
334 slur thickness. We see that the name of the layout object
335 is @code{Slur}, that the name of the property to change is
336 @code{thickness} and that the new value should be a number
337 somewhat larger than 1.2 if we are to make slurs thicker.
339 We can now construct the @code{\override} command by simply
340 substituting the values we have found for the names, omitting
341 the context. Let's use a very large value for the thickness
342 at first, so we can be sure the command is working. We get:
345 \override Slur #'thickness = #5.0
348 Don't forget the @code{#'} preceding the
349 property name and and @code{#} preceding the new value!
351 The final question is, @q{Where should this command be
352 placed?} While you are unsure and learning, the best
353 answer is, @q{Within the music, before the first slur and
354 close to it.} Let's do that:
356 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
360 % Increase thickness of all following slurs from 1.2 to 5.0
361 \override Slur #'thickness = #5.0
363 g[( e]) e d[( f]) a |
367 The man who feels love's sweet e -- mo -- tion
373 and we see that the slur is indeed heavier.
375 So this is the basic way of constructing @code{\override}
376 commands. There are a few more complications that we
377 shall meet in later sections, but you now know all the
378 essentials required to make up your own -- but you will
379 still need some practice. This is provided in the examples
382 But first, what if we had needed to specifiy the Context?
383 What should it be? We could guess that slurs are in
384 the Voice context, as they are clearly closely associated
385 with individual lines of music, but can we be sure? To
386 find out, go back to the top of the IR page describing the
387 Slur, where it says @q{Slur objects are created by: Slur
388 engraver}. So slurs will be created in whichever context
389 the @code{Slur_engraver} is in. Follow the link to the
390 @code{Slur_engraver} page. At the very bottom it tells
391 us that @code{Slur_engraver} is part of five Voice contexts,
392 including the standard voice context, @code{Voice}, so our
393 guess was correct. And because @code{Voice} is one of the
394 lowest level contexts which is implied unambiguously by
395 the fact that we are entering notes, we can omit it in this
398 @heading Overriding once only
400 @cindex overriding once only
401 @cindex once override
404 As you can see, @emph{all} the slurs are thicker in the
405 final example above. But what if we
406 wanted just the first slur to be thicker? This is achieved
407 with the @code{\once} command. Placed immediately before
408 the @code{\override} command it causes it to change only the
409 slur on the @strong{immediately following} note. If the
410 immediately following note does not have a slur the command
411 has no effect at all -- it is not remembered until a slur
412 is encountered, it is simply discarded. So the command with
414 repositioned as follows:
416 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
421 % Increase thickness of immediately following slur only
422 \once \override Slur #'thickness = #5.0
424 g[( e]) e d[( f]) a |
428 The man who feels love's sweet e -- mo -- tion
434 Now only the first slur is made heavier.
438 Finally, what if we wanted just the first two slurs to be
439 heavier? Well, we could use two commands, each preceded by
440 @code{\once} placed immediately before each of the notes where
443 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
448 % Increase thickness of immediately following slur only
449 \once \override Slur #'thickness = #5.0
451 % Increase thickness of immediately following slur only
452 \once \override Slur #'thickness = #5.0
453 g[( e]) e d[( f]) a |
457 The man who feels love's sweet e -- mo -- tion
466 or we could omit the @code{\once} command and use the
467 @code{\revert} command
468 to return the @code{thickness} property to its default value
469 after the second slur:
471 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
476 % Increase thickness of all following slurs from 1.2 to 5.0
477 \override Slur #'thickness = #5.0
480 % Revert thickness of all following slurs to default of 1.2
481 \revert Slur #'thickness
486 The man who feels love's sweet e -- mo -- tion
492 The @code{\revert} command can be used to return any property
493 changed with @code{\override} back to its default value.
494 You may use whichever method best suits what you want to do.
496 That concludes our introduction to the IR, and the basic
497 method of tweaking. Several examples follow in the later
498 sections of this Chapter, partly to introduce you to some of the
499 additional features of the IR, and partly to give you more
500 practice in extracting information from it. These example will
501 contain progressively fewer words of guidance and explanation.
503 @node Properties found in interfaces
504 @subsection Properties found in interfaces
506 @cindex interface properties
507 @cindex properties in interfaces
509 Suppose now that we wish to print the lyrics in italics. What
510 @code{\override} command do we need to do this?
511 We first look in the IR page listing @q{All layout objects}, as
512 before, and look for an object that might print lyrics. We
513 find @code{LyricText}, which looks right. Clicking on this shows
514 the settable properties for lyric text. These include the
515 @code{font-series} and @code{font-size}, but nothing that might
516 give an italic shape.
517 This is because the shape property is one that is common to all
518 font objects, so, rather than including it in every layout
519 object, it is grouped together with other similar common
520 properties and placed in an @strong{Interface}, the
521 @code{font-interface}.
523 So now we need to learn how to find the properties of interfaces,
524 and to discover what objects use these interface properties.
526 Look again at the IR page which describes LyricText. At the
527 bottom of the page is a list of clickable (in the html versions
528 of the IR) interfaces which LyricText supports. The list has
529 seven items, including @code{font-interface}.
530 Clicking on this brings up the properties associated
531 with this interface, which are also properties of all the objects
532 which support it, including LyricText.
534 Now we see all the user-settable properties which control fonts,
535 including @code{font-shape(symbol)}, where @code{symbol} can be
536 set to @code{upright}, @code{italics} or @code{caps}.
538 You will notice that that @code{font-series} and @code{font-size}
539 are also listed there.
540 This immediately raises the question: Why are the common font
541 properties @code{font-series} and @code{font-size} listed under
542 @code{LyricText} as well as under the interface
543 @code{font-interface} but @code{font-shape} is not? The answer
544 is that @code{font-series} and @code{font-size} are changed
545 from their global default values when a @code{LyricText} object
546 is created, but @code{font-shape} is not. The entries in
547 @code{LyricText} then tell you the values for those two
548 properties which apply to @code{LyricText}. Other objects
549 which support @code{font-interface} will set these
550 properties diferently when they are created.
552 Let's see if we can now construct the @code{\override} command
553 to change the lyrics to italics. The object is @code{LyricText},
554 the property is @code{'font-shape} and the value is
555 @code{'italic}. As before, we'll omit the context.
557 As an aside, although it is an important one, note that because
559 @code{'font-shape} are symbols they must be introduced with a
560 single apostrophe, @code{'}. That is why apostrophes
561 are needed before @code{'thickness} in the earlier example
562 and @code{'font-shape}. These are both symbols too.
563 Symbols are special names which are known internally to
564 LilyPond. Some of them are the names of properties,
565 like @code{'thickness} or @code{'font-shape}, others are in
566 effect special values that can be given to properties, like
567 @code{'italic}. Note the distinction from arbitary
568 text strings, which would appear as @code{"a text string"}.
570 Ok, so the @code{\override} command we need to print the lyrics
574 \override LyricText #'font-shape = #'italic
578 and this should be placed just in front of and close to the
579 lyrics which it should affect, like this:
581 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
586 g[( e]) e d[( f]) a |
590 \override LyricText #'font-shape = #'italic
591 The man who feels love's sweet e -- mo -- tion
597 and the lyrics are all printed in italics.
599 In the case of lyrics, if you try specifying the context in the
600 format given earlier the command will fail. A syllable
601 entered in lyricmode is terminated by either a space,
602 a newline or a digit. All other characters are included
603 as part of the syllable. For this reason a space or newline
604 must appear before the terminating @code{@}} to prevent it being
605 included as part of the final syllable. Similarly,
606 spaces must be inserted before and after the
607 period or dot, @q{.}, separating the context name from the
608 object name, as otherwise the two names are run together and
609 the interpreter cannot recognise them. So the command should be:
612 \override Lyrics . LyricText #'font-shape = #'italic
615 @warning{In lyrics always leave whitespace between the final
616 syllable and the terminating brace.}
618 @warning{In overrides in lyrics always place spaces around
619 the dot between the context name and the object name.}
621 @node Types of properties
622 @subsection Types of properties
624 @cindex Property types
626 So far we have seen two types of property: @code{number} and
627 @code{symbol}. To be valid, the value given to a property
628 must be of the correct type and obey the rules for that type.
629 The type of property is always shown in brackets after the
630 property name in the IR. Here is a list of the types you may
631 need, together with the rules for that type, and some examples.
632 You must always add a hash symbol, @code{#}, of course,
633 to the front of these values when they are entered in the
634 @code{\override} command.
636 @multitable @columnfractions .2 .45 .35
637 @headitem Property type
641 @tab Either True or False, represented by #t or #f
642 @tab @code{#t}, @code{#f}
643 @item Dimension (in staff space)
644 @tab A positive decimal number (in units of staff space)
647 @tab A valid direction constant or its numerical equivalent
648 @tab @code{#LEFT}, @code{#CENTER}, @code{#UP}, 1, -1
650 @tab A positive whole number
653 @tab A bracketed set of items separated by spaces,
654 preceded by an apostrophe
655 @tab '(left-edge staff-bar), '(1), '(1.0 0.25 0.5)
657 @tab Any valid markup
658 @tab @code{\markup @{ \italic "cresc." @}}
660 @tab A fraction of a whole note constructed with the
662 @tab @code{(ly:make-moment 1 4)}, @code{(ly:make-moment 3 8)}
664 @tab Any positive or negative decimal value
666 @item Pair (of numbers)
667 @tab Two numbers separated by a @q{space . space} and enclosed
668 in brackets preceded by an apostrophe
669 @tab '(2 . 3.5), '(0.1 . -3.2)
671 @tab Any of the set of permitted symbols for that property,
672 preceded by an apostrophe
673 @tab @code{'italic}, @code{'inside}
675 @tab A procedure or #f (to cause no action)
676 @tab @code{bend::print}, @code{ly:text-interface::print}, #f
678 @tab A list of three items enclosed in brackets and preceded
679 by a hash, @code{#}, sign
680 @tab @code{#(#t #t #f)}
683 @node Appearance of objects
684 @section Appearance of objects
686 Let us now put what we have learnt into practice with a few
687 examples which show how tweaks may be used to change the
688 appearance of the printed music.
691 * Visibility and color of objects::
695 @node Visibility and color of objects
696 @subsection Visibility and color of objects
698 In the educational use of music we might wish to print a score
699 with certain elements omitted as an exercise where the student is
700 required to fill in the missing elements. As a simple example,
701 let use suppose the exercise is to supply the missing barlines
702 in a piece of music. How do we prevent the barlines printing?
704 As before, we go to the IR to find the layout object which prints
705 barlines. Going via @emph{Backend} and @emph{All layout objects}
707 is a layout object called @code{BarLine}. Its properties include
708 two that control its visibility: @code{break-visibility} and
709 @code{stencil}. Barline also supports a number of interfaces,
710 including the @code{grob-interface}, where we find the
711 @code{transparent} and the @code{color} properties. All
712 of these can affect the visibility of barlines (and, of course,
713 by extension, many other layout objects too.) Let's consider
714 each of these in turn.
719 This property controls the appearance of the barlines. In common
720 with many other properties, it can be set to print nothing by
721 setting its value to @code{#f}. Let's try it, as before, omitting
722 the implied Context, @code{Voice}:
724 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
727 \override BarLine #'stencil = ##f
734 The barlines are still printed. What is wrong? Go back to the
735 IR and look again at the page giving the properties of BarLine.
736 At the top of the page it says @qq{Barline objects are created
737 by: Bar_engraver}. Go to the @code{Bar_engraver} page.
739 it gives a list of Contexts in which the bar engraver operates.
740 All of them are of the type @code{Staff}, so the reason the
741 @code{\override} command failed to work as expected is because
742 @code{Barline} is not in the default @code{Voice} context.
744 is specified wrongly, the command simply does not work. No
745 error message is produced, and nothing is logged in the log
746 file. Let's try correcting it by adding the correct context:
748 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
751 \override Staff.BarLine #'stencil = ##f
758 Now the barlines have vanished.
760 @heading break-visibility
762 @cindex break-visibility
764 We see from the BarLine properties in the IR that the
765 break-visibility property requires a vector of three booleans.
766 These control respectively whether barlines are printed at
767 the end of a line, in the middle of lines, and at the beginning
768 of lines. For our example we want all barlines to be suppressed,
769 so the value we need is @code{#(#f #f #f)}.
770 Let's try that, remembering
771 to include the @code{Staff} context. Note also that in writing
772 this value we have two hash signs before the opening bracket.
773 One is required as part of the value to introduce a vector,
774 and one is required, as always, to precede the value in the
775 @code{\override} command.
777 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
780 \override Staff.BarLine #'break-visibility = ##(#f #f #f)
787 And we see this too removes all the barlines.
792 We see from the properties specified in the @code{grob-interface}
793 page in the IR that the @code{transparent} property is a boolean.
795 should be set to @code{#t} to make the grob transparent.
796 In this next example let us make the time signature invisible
797 rather than the barlines.
798 To do this we need to find the grob name for the time signature.
800 the @q{All layout objects} page in the IR to find the properties
801 of the @code{TimeSignature} layout object. This is produced by
802 the @code{Time_signature_engraver} which you can check also lives
803 in the @code{Staff} context and also supports the
804 @code{grob-interface}. So the command to make the time signature
807 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
810 \override Staff.TimeSignature #'transparent = ##t
818 The time signature is gone, but this command leaves a gap where
819 the time signature should be. If this is not wanted the stencil
820 for the time signature should be set to @code{#f} instead:
822 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
825 \override Staff.TimeSignature #'stencil = ##f
833 and the difference is obvious: setting the stencil to @code{#f}
834 removes the object entirely; making the object @code{transparent}
835 leaves it where it is, but makes it invisible.
840 Finally we could make the barlines invisible by coloring
841 them white. The @code{grob-interface} specifies that the
842 color property value is a list, but there is no
843 explanation of what that list should be. The list it
844 requires is actually a list of values in internal units,
845 but, to avoid having to know what these are, several ways
846 are provided to specify colors. The first way is to use one
847 of the @q{normal} colours listed in the first table in
848 @ruser{List of colors}. To set the barlines to white
851 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
854 \override Staff.BarLine #'color = #white
862 and again, we see the barlines are not visible. Note that
863 @emph{white} is not preceded by an apostrophe -- it is not
864 a symbol, but a @emph{function}. When called, it provides
865 the list of internal values required to set the color to
866 white. The other colors in the normal list are functions
867 too. To convince yourself this is working you might like
868 to change the color to one of the other functions in the
874 The second way of changing the color is to use the list of
875 X11 color names in the second list in @ruser{List of colors}.
876 However, these must be preceded by another function, which
877 converts X11 color names into the list of internal values,
878 @code{x11-color}, like this:
880 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
883 \override Staff.BarLine #'color = #(x11-color 'white)
891 Note that in this case the function @code{x11-color} takes
892 a symbol as an argument, so the symbol must be preceded by
893 an apostrophe and the two enclosed in brackets.
898 There is yet a third function which converts RGB values into
899 internal colors -- the @code{rgb-color} function. This takes
900 three arguments giving the intensities of the red, green and
901 blue colors. These take values in the range 0 to 1. So to
902 set the color to red the value should be @code{(rgb-color 1 0 0)}
903 and to white it should be @code{(rgb-color 1 1 1)}:
905 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
908 \override Staff.BarLine #'color = #(rgb-color 1 1 1)
915 Finally, there is also a grey scale available as part of the
916 X11 set of colors. These range from black, @code{'grey0'},
917 to white, @code{'grey100}, in steps of 1. Let's illustrate
918 this by setting all the layout objects in our example to
919 various shades of grey:
921 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
924 \override Staff.StaffSymbol #'color = #(x11-color 'grey30)
925 \override Staff.TimeSignature #'color = #(x11-color 'grey60)
926 \override Staff.Clef #'color = #(x11-color 'grey60)
927 \override Voice.NoteHead #'color = #(x11-color 'grey85)
928 \override Voice.Stem #'color = #(x11-color 'grey85)
929 \override Staff.BarLine #'color = #(x11-color 'grey10)
937 Note the contexts associated with each of the layout objects.
940 @node Size of objects
941 @subsection Size of objects
943 Let us begin by looking again at the earlier example
945 @c (see @ref{Nesting music expressions}) which showed
946 how to introduce a new temporary staff, as in an @rglos{ossia}.
948 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
956 alignAboveContext = "main" }
964 Ossia are normally written without clef and time signature, and
965 are usually printed slightly smaller than the main staff. We
966 already know now how to remove the clef and time signature --
967 we simply set the stencil of each to @code{#f}, as follows:
969 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
977 alignAboveContext = "main"
980 \override Staff.Clef #'stencil = ##f
981 \override Staff.TimeSignature #'stencil = ##f
991 where the extra pair of braces after the @code{\with} clause are
992 required to ensure the enclosed overrrides amd music are applied
995 But what is the difference between modifying the staff context by
996 using @code{\with} and modifying the stencils of the clef and the
997 time signature with \override? The main difference is that
998 changes made in a @code{\with} clause are made at the time the
999 context is created, and remain in force as the @strong{default}
1000 values for the duration of that context, whereas
1001 @code{\set} or @code{\override} commands embedded in the
1002 music are dynamic -- they make changes synchronised with
1003 a particular point in the music. If changes are unset or
1004 reverted using @code{\unset} or @code{\revert} they return to
1005 their default values, which will be the ones set in the
1006 @code{\with} clause, or if none have been set there, the normal
1009 Some context properties
1010 can be modified only in @code{\with} clauses. These are those
1011 properties which cannot sensibly be changed after the context
1012 has been created. @code{alignAboveContext} and its partner,
1013 @code{alignBelowContext}, are two such properties -- once the
1014 staff has been created its alignment is decided and it would
1015 make no sense to try to change it later.
1017 The default values of layout object propertiess can also be set
1018 in @code{\with} clauses. Simply use the normal @code{\override}
1019 command leaving out the context name, since this is unambiguously
1020 defined as the context the @code{\with} clause is modifying.
1021 If fact, an error will be generated if a context is specified
1024 So we could replace the example above with
1026 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1027 \new Staff ="main" {
1034 alignAboveContext = "main"
1035 % Don't print clefs in this staff
1036 \override Clef #'stencil = ##f
1037 % Don't print time signatures in this staff
1038 \override TimeSignature #'stencil = ##f
1047 Finally we come to changing the size of layout objects.
1049 Some layout objects are created as glyphs selected from
1050 a font. These include noteheads, accidentals, markup,
1051 clefs, time signatures, dynamics and lyrics.
1052 Their size is changed by modifying the
1053 @code{font-size} property, as we shall shortly see.
1054 Other layout objects such as slurs, ties, in general, spanner
1055 objects, are drawn individually, so there is no @code{font-size}
1056 associated with them. These objects generally derive their
1057 size from the objects to which they are attached, so usually
1058 there is no need to change their size manually. Still other
1059 properties such as the length of stems and barlines, thickness
1060 of beams and other lines, and the separation of staff lines all
1061 need to be modified in special ways.
1063 Returning to the ossia example, let us first change the font-size.
1064 We can do this in two ways. We can either change the size of the
1065 fonts of each object type, like @code{NoteHead}s with commands
1069 \override NoteHead #'font-size = #-2
1072 or we can change the size of all fonts by setting a special
1073 property, @code{fontSize}, using @code{\set}, or by including
1074 it in a @code{\with} clause (without the @code{\set}.
1080 In both examples the font size is reduced by 2 steps, where each
1081 step reduces or increases the size by 12%.
1083 Let's try it in our ossia example:
1085 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1086 \new Staff ="main" {
1093 alignAboveContext = "main"
1094 \override Clef #'stencil = ##f
1095 \override TimeSignature #'stencil = ##f
1096 % Reduce all font sizes by 24%
1106 This is still not quite right. The noteheads and flags are
1107 smaller, but the stems are too long in proportion and the
1108 staff lines are spaced too widely apart. These need to be
1109 scaled down in proportion to the font reduction.
1111 This can be done with the help of a special function called
1112 @code{magstep} provided for exactly this purpose. It takes
1113 one argument, the change in font size (#-2 in the example above)
1114 and returns a scaling factor suitable for reducing other
1115 objects in proportion. It is used like this:
1117 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1118 \new Staff ="main" {
1125 alignAboveContext = "main"
1126 \override Clef #'stencil = ##f
1127 \override TimeSignature #'stencil = ##f
1129 % Reduce stems and line spacing to match
1130 \override StaffSymbol #'staff-space = #(magstep -2)
1140 Since the length of stems is always calculated relative to the
1141 value of the @code{staff-space} property these are automatically
1142 scaled down in length too.
1144 This, then, completes the creation of an ossia. The sizes of all
1145 other objects may be modified in analogous ways.
1151 @c Old stuff follows -td
1154 @section Common tweaks
1160 * Fixing overlapping notation::
1161 * Other common tweaks::
1162 * Fitting music onto fewer pages::
1165 @node Moving objects
1166 @subsection Moving objects
1168 This may come as a surprise, but LilyPond is not perfect. Some notation
1169 elements can overlap. This is unfortunate, but (in most cases) is easily
1172 TODO: with the new spacing features in 2.12, these specific examples are no
1173 longer relevant. However, they still demonstrate powerful features
1174 of lilypond, so they remain until somebody creates some better examples.
1176 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1177 % temporary code to break this example:
1178 \override TextScript #'outside-staff-priority = ##f
1179 e4^\markup{ \italic ritenuto } g b e
1184 The easiest solution is to increase the distance between the object
1185 (in this case text, but it could easily be fingerings or dynamics
1186 instead) and the note. In LilyPond, this is called the
1187 @code{padding} property; it is measured in staff spaces. For most
1188 objects, this value is around 1.0 or less (it varies with each
1189 object). We want to increase it, so let's try 1.5
1191 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1192 % temporary code to break this example:
1193 \override TextScript #'outside-staff-priority = ##f
1194 \once \override TextScript #'padding = #1.5
1195 e4^\markup{ \italic ritenuto } g b e
1198 That looks better, but it isn't quite big enough. After experimenting
1199 with a few values, we think 2.3 is the best number in this case. However,
1200 this number is merely the result of experimentation and my personal
1201 taste in notation. Try the above example with 2.3... but also try higher
1202 (and lower) numbers. Which do you think looks the best?
1204 The @code{staff-padding} property is closely related. @code{padding}
1205 controls the minimum amount of space between an object and the nearest
1206 other object (generally the note or the staff lines);
1207 @code{staff-padding} controls the minimum amount of space between an
1208 object and the staff. This is a subtle difference, but you can see
1211 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1212 % temporary code to break this example:
1213 \override TextScript #'outside-staff-priority = ##f
1214 c4^"piu mosso" b a b
1215 \once \override TextScript #'padding = #4.6
1216 c4^"piu mosso" d e f
1217 \once \override TextScript #'staff-padding = #4.6
1218 c4^"piu mosso" fis a g
1220 c'4^"piu mosso" b a b
1221 \once \override TextScript #'padding = #4.6
1222 c4^"piu mosso" d e f
1223 \once \override TextScript #'staff-padding = #4.6
1224 c4^"piu mosso" fis a g
1227 @cindex extra-offset
1229 Another solution gives us complete control over placing the object -- we
1230 can move it horizontally or vertically. This is done with the
1231 @code{extra-offset} property. It is slightly more complicated and can
1232 cause other problems. When we move objects with @code{extra-offset},
1233 the movement is done after LilyPond has placed all other objects. This
1235 that the result can overlap with other objects.
1237 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1238 % temporary code to break this example:
1239 \override TextScript #'outside-staff-priority = ##f
1240 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
1241 e4^\markup{ \italic ritenuto } g b e
1244 With @code{extra-offset}, the first number controls the horizontal
1245 movement (left is negative); the second number controls the vertical
1246 movement (up is positive). After a bit of experimenting, we decided
1247 that these values look good
1249 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1250 % temporary code to break this example:
1251 \override TextScript #'outside-staff-priority = ##f
1252 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
1253 e4^\markup{ \italic ritenuto } g b e
1257 Again, these numbers are simply the result of a few experiments and
1258 looking at the output. You might prefer the text to be slightly higher,
1259 or to the left, or whatever. Try it and look at the result!
1261 One final warning: in this section, we used
1264 \once \override TextScript @dots{}
1267 This tweaks the display of text for the next note. If the note has
1268 no text, this tweak does nothing (and does @strong{not} wait until
1269 the next bit of text). To change the behavior of everything after
1270 the command, omit the @code{\once}. To stop this tweak, use a
1271 @code{\revert}. This is explained in depth in
1272 @ruser{The \override command}.
1274 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]
1275 % temporary code to break this example:
1276 \override TextScript #'outside-staff-priority = ##f
1278 \once \override TextScript #'padding = #4.6
1280 c4^"piu mosso" d e f
1281 \once \override TextScript #'padding = #4.6
1282 c4^"piu mosso" d e f
1283 c4^"piu mosso" d e f
1285 \override TextScript #'padding = #4.6
1286 c4^"piu mosso" d e f
1287 c4^"piu mosso" d e f
1288 \revert TextScript #'padding
1289 c4^"piu mosso" d e f
1294 This manual: @ruser{The \override command}, @ref{Common tweaks}.
1297 @node Fixing overlapping notation
1298 @subsection Fixing overlapping notation
1300 In @ref{Moving objects}, we saw how to move a @code{TextScript}
1301 object. The same mechanism can be used to move other types of
1302 objects; simply replace @code{TextScript} with the name of
1305 To find the object name, look at the @q{@strong{see also}} at
1306 bottom of the relevant documentation page. For example, at
1307 the bottom of @ruser{Dynamics}, we see
1312 Internals Reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
1313 Vertical positioning of these symbols is handled by
1314 @internalsref{DynamicLineSpanner}.
1318 So to move dynamics around vertically, we use
1321 \override DynamicLineSpanner #'padding = #2.0
1324 We cannot list every object, but here is a list of the most
1327 @multitable @columnfractions .33 .66
1328 @headitem Object type @tab Object name
1329 @item Dynamics (vertically) @tab @code{DynamicLineSpanner}
1330 @item Dynamics (horizontally) @tab @code{DynamicText}
1331 @item Ties @tab @code{Tie}
1332 @item Slurs @tab @code{Slur}
1333 @item Articulations @tab @code{Script}
1334 @item Fingerings @tab @code{Fingering}
1335 @item Text e.g. @code{^"text"} @tab @code{TextScript}
1336 @item Rehearsal / Text marks @tab @code{RehearsalMark}
1340 @node Other common tweaks
1341 @subsection Other common tweaks
1343 Some overrides are so common that predefined commands are provided as
1344 short-cuts, such as @code{\slurUp} and @code{\stemDown}. These
1345 commands are described in the Notation Reference under the appropriate
1348 The complete list of modifications available for each type of
1349 object (like slurs or beams) are documented in the Program
1350 Reference. However, many layout objects share properties which can be
1351 used to apply generic tweaks.
1358 The @code{padding} property can be set to increase
1359 (or decrease) the distance between symbols that are printed
1360 above or below notes. This applies to all objects with
1361 @code{side-position-interface}.
1363 @lilypond[quote,fragment,relative=1,verbatim]
1365 \override Script #'padding = #3
1369 @lilypond[quote,fragment,relative=1,verbatim]
1370 % This will not work, see below:
1371 \override MetronomeMark #'padding = #3
1375 \override Score.MetronomeMark #'padding = #3
1380 Note in the second example how important it is to figure out what
1381 context handles a certain object. Since the @code{MetronomeMark} object
1382 is handled in the @code{Score} context, property changes in the
1383 @code{Voice} context will not be noticed. For more details, see
1384 @ruser{Constructing a tweak}.
1386 @cindex extra-offset
1389 The @code{extra-offset} property moves objects around
1390 in the output; it requires a pair of numbers. The first number
1391 controls horizontal movement; a positive number will
1392 move the object to the right. The second number controls vertical
1393 movement; a positive number will move it higher. The
1394 @code{extra-offset} property is a low-level feature: the
1395 formatting engine is completely oblivious to these offsets.
1397 In the following example, the second fingering is moved a little to
1398 the left, and 1.8 staff space downwards:
1400 @lilypond[quote,fragment,relative=1,verbatim]
1403 \once \override Fingering
1404 #'extra-offset = #'(-0.3 . -1.8)
1409 Setting the @code{transparent} property will cause an object to be printed
1410 in @q{invisible ink}: the object is not printed, but all its other
1411 behavior is retained. The object still takes up space, it takes part in
1412 collisions, and slurs, ties, and beams can be attached to it.
1414 @cindex transparent objects
1415 @cindex removing objects
1416 @cindex hiding objects
1417 @cindex invisible objects
1418 The following example demonstrates how to connect different voices
1419 using ties. Normally, ties only connect two notes in the same
1420 voice. By introducing a tie in a different voice,
1422 @lilypond[quote,fragment,relative=2]
1431 and blanking the first up-stem in that voice, the tie appears to cross
1435 @lilypond[quote,fragment,relative=2,verbatim]
1437 \once \override Stem #'transparent = ##t
1444 To make sure that the just-blanked stem doesn't squeeze the tie too much,
1445 we also lengthen the stem, by setting the @code{length} to
1448 @lilypond[quote,fragment,relative=2,verbatim]
1450 \once \override Stem #'transparent = ##t
1451 \once \override Stem #'length = #8
1460 @cindex Tweaks, distances
1463 Distances in LilyPond are measured in staff-spaces, while most
1464 thickness properties are measured in line-thickness. Some
1465 properties are different; for example, the thickness of beams
1466 are measured in staff-spaces. For more information, see the
1467 relevant portion of the program reference.
1470 @node Fitting music onto fewer pages
1471 @subsection Fitting music onto fewer pages
1473 Sometimes you can end up with one or two staves on a second
1474 (or third, or fourth...) page. This is annoying, especially
1475 if you look at previous pages and it looks like there is plenty
1476 of room left on those.
1478 When investigating layout issues, @code{annotate-spacing} is
1479 an invaluable tool. This command prints the values of various
1480 layout spacing commands; see @ruser{Displaying spacing}, for more
1481 details. From the output of @code{annotate-spacing}, we can
1482 see which margins we may wish to alter.
1484 Other than margins, there are a few other options to save space:
1488 You may tell LilyPond to place systems as close together as
1489 possible (to fit as many systems as possible onto a page), but
1490 then to space those systems out so that there is no blank
1491 space at the bottom of the page.
1495 between-system-padding = #0.1
1496 between-system-space = #0.1
1497 ragged-last-bottom = ##f
1503 You may force the number of systems (i.e., if LilyPond wants
1504 to typeset some music with 11 systems, you could force it to
1514 Avoid (or reduce) objects which increase the vertical size of
1515 a system. For example, volta repeats (or alternate repeats)
1516 require extra space. If these repeats are spread over two
1517 systems, they will take up more space than one system with
1518 the volta repeats and another system without.
1520 Another example is moving dynamics which @q{stick out} of
1523 @lilypond[verbatim,quote,fragment]
1526 \override DynamicLineSpanner #'padding = #-1.8
1527 \override DynamicText #'extra-offset = #'( -2.1 . 0)
1533 Alter the horizontal spacing via @code{SpacingSpanner}. See
1534 @ruser{Changing horizontal spacing}, for more details.
1536 @lilypond[verbatim,quote]
1539 g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
1540 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
1541 d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
1542 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
1547 \override SpacingSpanner
1548 #'base-shortest-duration = #(ly:make-moment 1 4)
1557 @node TODO other name
1558 @section TODO other name
1561 * Predefined tweaks::
1562 * Advanced tweaks with Scheme::
1563 * Avoiding tweaks with slower processing::
1564 * The three methods of tweaking::
1567 @node Predefined tweaks
1568 @subsection Predefined tweaks
1570 TODO: Some tweaks are really common, blah blah.
1572 for example \slurUp, \fatText.
1574 Show example, then explain where to find ly/propert-ly.
1577 The Internals Reference documentation contains a lot of information
1578 about LilyPond, but even more information can be gathered from
1579 looking at the internal LilyPond files.
1581 Some default settings (such as the definitions for
1582 @code{\header@{@}}s) are stored as @code{.ly} files. Other
1583 settings (such as the definitions of markup commands) are
1584 stored as @code{.scm} (Scheme) files. Further explanation is
1585 outside the scope of this manual; users should be warned that
1586 a substantial amount of technical knowledge or time is required
1587 to understand these files.
1591 @item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/}
1594 @file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}.
1595 To access this, either @code{cd} into this directory from the
1596 Terminal, or control-click on the LilyPond application and select
1597 @q{Show Package Contents}.
1599 @item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/}
1603 The @file{ly/} and @file{scm/} directories will be of
1604 particular interest. Files such as @file{ly/property-init.ly} and
1605 @file{ly/declarations-init.ly} define all the common tweaks.
1608 @node Advanced tweaks with Scheme
1609 @subsection Advanced tweaks with Scheme
1611 We have seen how LilyPond output can be heavily modified using
1613 @code{\override TextScript #'extra-offset = ( 1 . -1)}. But
1614 we have even more power if we use Scheme. For a full explantion
1615 of this, see the @ref{Scheme tutorial}, and
1616 @ruser{Interfaces for programmers}.
1618 We can use Scheme to simply @code{\override} commands,
1620 @lilypond[quote,verbatim,ragged-right]
1621 padText = #(define-music-function (parser location padding) (number?)
1623 \once \override TextScript #'padding = #$padding
1627 c4^"piu mosso" b a b
1629 c4^"piu mosso" d e f
1631 c4^"piu mosso" fis a g
1635 We can use it to create new commands,
1637 @lilypond[quote,verbatim,ragged-right]
1638 tempoMark = #(define-music-function (parser location padding marktext)
1641 \once \override Score . RehearsalMark #'padding = $padding
1642 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
1643 \mark \markup { \bold $marktext }
1648 \tempoMark #3.0 #"Allegro"
1653 Even music expressions can be passed in.
1655 @lilypond[quote,verbatim,ragged-right]
1656 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
1663 \pattern {d16 dis} { ais16-> b\p }
1668 @node Avoiding tweaks with slower processing
1669 @subsection Avoiding tweaks with slower processing
1671 LilyPond can perform extra checks while it processes files. These
1672 commands will take extra time, but the result may require fewer
1676 %% makes sure text scripts and lyrics are within the paper margins
1677 \override Score.PaperColumn #'keep-inside-line = ##t
1678 \override Score.NonMusicalPaperColumn #'keep-inside-line = ##t
1681 In some cases (see issue 246), this must be done before
1682 @code{\override} commands can be processed.
1686 \override PaperColumn #'keep-inside-line = ##t
1687 \override NonMusicalPaperColumn #'keep-inside-line = ##t
1694 @node The three methods of tweaking
1695 @subsection The three methods of tweaking
1717 FIXME discuss \tweak
1721 FIXME: Move the following words and example into Tweaks or
1722 somewhere more suitable, leaving just a ref here. -td
1724 Ways of correcting horizontal placings are described fully
1725 in the Notation Reference.
1726 We introduce just one here, the @code{force-hshift} property of
1727 @code{NoteColumn}. The lower two notes of the first chord (i.e,
1728 those in the third voice) should not be shifted away from the
1729 note column of the higher two notes. To correct this we set
1730 @code{force-hshift} of these notes to zero.
1731 The lower note of the second chord is best placed just to the
1732 right of the higher notes. We achieve this by setting
1733 @code{force-hshift} of this note to 0.5, ie half a notehead's
1734 width to the right of the note column of the higher notes.
1736 Here's the final result:
1738 @lilypond[quote,verbatim,fragment,ragged-right]
1739 \new Staff \relative c'' {
1742 { c2 aes4. bes8 } \\
1745 \once \override NoteColumn #'force-hshift = #0 <ees c>2
1746 \once \override NoteColumn #'force-hshift = #0.5 des2
1757 - There is a section in the manual on \set vs \override (3.3.7),
1758 which is incomplete. First it doesn't mention \overrideProperty,
1759 nor does it mention properties which are not capitalized at all.
1760 And it should explain that \override should be used to set
1761 properties with hyphenated names, like auto-knee-gap. (I had to
1762 experiment to find out how to do this.)
1765 FIXME: moved from fundamental, dumped here at random.
1767 @lilypond[verbatim,quote,ragged-right]
1768 \new Staff = "main" {
1772 << % Start main and ossia in parallel
1773 { r8 f c c } % Main music
1774 \new Staff \with { % Start ossia staff
1775 \remove "Clef_engraver"
1776 \remove "Time_signature_engraver"
1777 % Reduce size of notes and staff
1779 \override StaffSymbol #'staff-space = #(magstep -2)
1780 alignAboveContext = "main" % Place above main staff
1782 { s8 f f c } % Ossia music
1783 >> % End parallel music