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 FIXME: explain what/why. maybe in other sections.
21 * The Internals Reference manual::
27 @section Tweaking basics
29 NB: This section is still under development and may change
31 @q{Tweaking} is a LilyPond term for the various methods available
32 to the user for modifying the actions taken during interpretation
33 of the input file and modifying the appearance of the printed
34 output. Some tweaks are very easy to use; others are more
35 complex. But taken together the methods available for tweaking
36 permit almost any desired appearance of the printed music to be achieved.
38 In this section we cover the basic concepts required to understand
39 tweaking. Later we give a variety of potted commands which can
40 simply be copied to obtain the same effect in your own scores, and
41 at the same time we show how these commands may be constructed so
42 that you may learn how to develop your own tweaks.
44 Before starting on this Chapter you may wish to review the section
45 @ref{Contexts and engravers}, as Contexts, Engravers and the
46 Properties contained within them are fundamental to understanding
47 and constructing Tweaks.
50 * Objects and grobs and spanners and interfaces TODOname::
51 * Naming conventions of objects and properties::
55 @node Objects and grobs and spanners and interfaces TODOname
56 @subsection Objects and grobs and spanners and interfaces TODOname
63 Tweaking involves modifying the internal operation and structures
64 of the LilyPond program, so we must first introduce some terms
65 which are used to describe those internal operations and
68 The term @q{Object} is a generic term used to refer to the
69 multitude of internal structures built by LilyPond during the
70 processing of an input file. So when a command like @code{\new
71 Staff} is encountered a new object of type @code{Staff} is
72 constructed. That @code{Staff} object then holds all the
73 properties associated with that particular staff, for example, its
74 name and its key signature, together with details of the engravers
75 which have been assigned to operate within that staff's context.
76 Similarly, there are @code{Voice} objects, @code{Score} objects,
77 @code{Lyric} objects, and objects to represent barlines,
78 noteheads, ties, dynamics, etc, each with their own set of
81 Some types of object are given special names. Objects which
82 represent items of notation on the printed output such as
83 noteheads, stems, slurs, ties, fingering, clefs, etc are called
84 @q{Layout objects}, often known as @q{Graphical Objects}, or
85 @q{Grobs} for short. These are still objects in the generic sense
86 above, and so they too all have properties associated with them,
87 such as their position, size, color, etc.
89 Some layout objects are still more specialised. Phrasing slurs,
90 crescendo hairpins, ottavo marks, and many other grobs are not
91 localised in a single place -- they have a starting point, an
92 ending point, and maybe other properties concerned with their
93 shape. Objects with an extended shape like these are called
96 It remains to explain what @q{Interfaces} are. Many different
97 types of object often require to be processed in the same way.
98 For example, all grobs have a color, a size, a position, etc,
99 and all these properties are processed in the same way during
101 interpretation of the input file. To simplify these internal
102 operations these common actions and properties are grouped
103 together in an object called a @code{grob-interface}. Many
104 other groupings into interfaces are made. In total there are
105 over 100 such interfaces. We shall see later why this is of
106 interest and use to the user.
108 These, then, are the main terms relating to objects which we
109 shall use in this chapter.
111 @node Naming conventions of objects and properties
112 @subsection Naming conventions of objects and properties
114 We met some object naming conventions previously, in
115 @ref{Contexts and engravers}. Here for reference is a list
116 of the most common object types together with the conventions
117 for naming them and a couple of examples of some real names.
119 @multitable @columnfractions .33 .33 .33
120 @headitem Object type
121 @tab Naming convention
123 @item Contexts, Layout Objects
124 @tab Aaaa or AaaaAaaaAaaa
125 @tab Staff, GrandStaff,
127 @tab Aaaa_aaa_engraver
128 @tab Clef_engraver, Note_heads_engraver
130 @tab aaa-aaa-interface
131 @tab grob-interface, break-aligned-interface
132 @item Context Properties
133 @tab aaa or aaaAaaaAaaa
134 @tab alignAboveContext, skipBars
135 @item Layout Object Properties
136 @tab aaa or aaa-aaa-aaa
137 @tab direction, beam-thickness
140 As we shall see shortly, the properties of different types of
141 object are modified by different commands, so it is useful to
142 be able to recognise the type of object from the names of its
146 @node Tweaking methods
147 @subsection Tweaking methods
149 We have already met the commands @code{\set} and @code{\with},
150 used to change the properties of @strong{contexts} and to remove
152 engravers, in @ref{Modifying context properties} and @ref{Adding
153 and removing engravers}. We now must meet one more command.
155 The command to change the properties of @strong{layout objects} is
156 @code{\override}. Because this command has to modify
157 internal properties deep within LilyPond its syntax is not
158 as simple as the commands you have met so far. It needs to
159 know precisely which property of which object in which context
160 has to be modified, and what its new value is to be. Let's see
163 The general syntax of this command is:
166 \override @emph{context}.@emph{layout_object}
167 #'@emph{layout_property} = #@emph{value}
171 This will set the @emph{layout_property} of the specified
172 @emph{layout_object}, which is a member of the @emph{context}
173 context, to the value @emph{value}.
175 For now, don't worry about the @code{#'}, which must precede the
176 layout property, and the @code{#}, which must precede the value.
177 These must always be present in exactly this form. This is the
178 most common command used in tweaking, and most of the rest of
179 this chapter will be directed to presenting examples of how it is
182 There is another form of the override command,
183 @code{\overrideProperty}, which is occasionally required.
184 We mention it here for completeness, but for details see
185 @ruser{Difficult tweaks}.
187 The final tweaking command which is available is @code{\tweak}.
188 It is not really a new command but a shorthand for an
189 @code{\override} command which may be used in a few special
190 circumstances. Again, we shall not discuss or
191 use it here. You may find the details in @ruser{Objects
192 connected to the input}.
194 @node The Internals Reference manual
195 @section The Internals Reference manual
197 @cindex Internals Reference
199 Suppose you have a slur in a score which, to your mind,
200 appears too thin and you'd like to draw it a little thicker.
201 How do you go about doing this? You know from the statements
202 earlier about the flexibility of LilyPond that such a thing
203 should be possible, and you would probably guess that an
204 @code{\override} command would be needed. But is there a
205 thickness property for a slur, and if there is, how might it
206 be modified? This is where the Internals Reference manual
207 comes in. It contains all the information you might need to
208 construct this and all other @code{\override} commands.
210 Before we look at the Internals Reference a word of warning.
211 This is a @strong{reference} document, which means there is
212 little or no explanation contained within it: its purpose is
213 to present information precisely and concisely. This
214 might mean it looks daunting at first sight. Don't worry!
215 The guidance and explanation presented here will enable you
216 to extract the information from the Internals Reference for
217 yourself with just a little practice.
219 Let's use a concrete example.
224 @c Old stuff follows -td
227 @section Common tweaks
233 * Fixing overlapping notation::
234 * Other common tweaks::
235 * Fitting music onto fewer pages::
239 @subsection Moving objects
241 This may come as a surprise, but LilyPond is not perfect. Some notation
242 elements can overlap. This is unfortunate, but (in most cases) is easily
245 TODO: with the new spacing features in 2.12, these specific examples are no
246 longer relevant. However, they still demonstrate powerful features
247 of lilypond, so they remain until somebody creates some better examples.
249 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
250 % temporary code to break this example:
251 \override TextScript #'outside-staff-priority = ##f
252 e4^\markup{ \italic ritenuto } g b e
257 The easiest solution is to increase the distance between the object
258 (in this case text, but it could easily be fingerings or dynamics
259 instead) and the note. In LilyPond, this is called the
260 @code{padding} property; it is measured in staff spaces. For most
261 objects, this value is around 1.0 or less (it varies with each
262 object). We want to increase it, so let's try 1.5
264 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
265 % temporary code to break this example:
266 \override TextScript #'outside-staff-priority = ##f
267 \once \override TextScript #'padding = #1.5
268 e4^\markup{ \italic ritenuto } g b e
271 That looks better, but it isn't quite big enough. After experimenting
272 with a few values, we think 2.3 is the best number in this case. However,
273 this number is merely the result of experimentation and my personal
274 taste in notation. Try the above example with 2.3... but also try higher
275 (and lower) numbers. Which do you think looks the best?
277 The @code{staff-padding} property is closely related. @code{padding}
278 controls the minimum amount of space between an object and the nearest
279 other object (generally the note or the staff lines);
280 @code{staff-padding} controls the minimum amount of space between an
281 object and the staff. This is a subtle difference, but you can see
284 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
285 % temporary code to break this example:
286 \override TextScript #'outside-staff-priority = ##f
288 \once \override TextScript #'padding = #4.6
290 \once \override TextScript #'staff-padding = #4.6
291 c4^"piu mosso" fis a g
293 c'4^"piu mosso" b a b
294 \once \override TextScript #'padding = #4.6
296 \once \override TextScript #'staff-padding = #4.6
297 c4^"piu mosso" fis a g
302 Another solution gives us complete control over placing the object -- we
303 can move it horizontally or vertically. This is done with the
304 @code{extra-offset} property. It is slightly more complicated and can
305 cause other problems. When we move objects with @code{extra-offset},
306 the movement is done after LilyPond has placed all other objects. This
308 that the result can overlap with other objects.
310 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
311 % temporary code to break this example:
312 \override TextScript #'outside-staff-priority = ##f
313 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
314 e4^\markup{ \italic ritenuto } g b e
317 With @code{extra-offset}, the first number controls the horizontal
318 movement (left is negative); the second number controls the vertical
319 movement (up is positive). After a bit of experimenting, we decided
320 that these values look good
322 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
323 % temporary code to break this example:
324 \override TextScript #'outside-staff-priority = ##f
325 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
326 e4^\markup{ \italic ritenuto } g b e
330 Again, these numbers are simply the result of a few experiments and
331 looking at the output. You might prefer the text to be slightly higher,
332 or to the left, or whatever. Try it and look at the result!
334 One final warning: in this section, we used
337 \once \override TextScript @dots{}
340 This tweaks the display of text for the next note. If the note has
341 no text, this tweak does nothing (and does @strong{not} wait until
342 the next bit of text). To change the behavior of everything after
343 the command, omit the @code{\once}. To stop this tweak, use a
344 @code{\revert}. This is explained in depth in
345 @ruser{The \override command}.
347 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]
348 % temporary code to break this example:
349 \override TextScript #'outside-staff-priority = ##f
351 \once \override TextScript #'padding = #4.6
354 \once \override TextScript #'padding = #4.6
358 \override TextScript #'padding = #4.6
361 \revert TextScript #'padding
367 This manual: @ruser{The \override command}, @ref{Common tweaks}.
370 @node Fixing overlapping notation
371 @subsection Fixing overlapping notation
373 In @ref{Moving objects}, we saw how to move a @code{TextScript}
374 object. The same mechanism can be used to move other types of
375 objects; simply replace @code{TextScript} with the name of
378 To find the object name, look at the @q{@strong{see also}} at
379 bottom of the relevant documentation page. For example, at
380 the bottom of @ruser{Dynamics}, we see
385 Internals Reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
386 Vertical positioning of these symbols is handled by
387 @internalsref{DynamicLineSpanner}.
391 So to move dynamics around vertically, we use
394 \override DynamicLineSpanner #'padding = #2.0
397 We cannot list every object, but here is a list of the most
400 @multitable @columnfractions .33 .66
401 @headitem Object type @tab Object name
402 @item Dynamics (vertically) @tab @code{DynamicLineSpanner}
403 @item Dynamics (horizontally) @tab @code{DynamicText}
404 @item Ties @tab @code{Tie}
405 @item Slurs @tab @code{Slur}
406 @item Articulations @tab @code{Script}
407 @item Fingerings @tab @code{Fingering}
408 @item Text e.g. @code{^"text"} @tab @code{TextScript}
409 @item Rehearsal / Text marks @tab @code{RehearsalMark}
413 @node Other common tweaks
414 @subsection Other common tweaks
416 Some overrides are so common that predefined commands are provided as
417 short-cuts, such as @code{\slurUp} and @code{\stemDown}. These
418 commands are described in the Notation Reference under the appropriate
421 The complete list of modifications available for each type of
422 object (like slurs or beams) are documented in the Program
423 Reference. However, many layout objects share properties which can be
424 used to apply generic tweaks.
431 The @code{padding} property can be set to increase
432 (or decrease) the distance between symbols that are printed
433 above or below notes. This applies to all objects with
434 @code{side-position-interface}.
436 @lilypond[quote,fragment,relative=1,verbatim]
438 \override Script #'padding = #3
442 @lilypond[quote,fragment,relative=1,verbatim]
443 % This will not work, see below:
444 \override MetronomeMark #'padding = #3
448 \override Score.MetronomeMark #'padding = #3
453 Note in the second example how important it is to figure out what
454 context handles a certain object. Since the @code{MetronomeMark} object
455 is handled in the @code{Score} context, property changes in the
456 @code{Voice} context will not be noticed. For more details, see
457 @ruser{Constructing a tweak}.
462 The @code{extra-offset} property moves objects around
463 in the output; it requires a pair of numbers. The first number
464 controls horizontal movement; a positive number will
465 move the object to the right. The second number controls vertical
466 movement; a positive number will move it higher. The
467 @code{extra-offset} property is a low-level feature: the
468 formatting engine is completely oblivious to these offsets.
470 In the following example, the second fingering is moved a little to
471 the left, and 1.8 staff space downwards:
473 @lilypond[quote,fragment,relative=1,verbatim]
476 \once \override Fingering
477 #'extra-offset = #'(-0.3 . -1.8)
482 Setting the @code{transparent} property will cause an object to be printed
483 in @q{invisible ink}: the object is not printed, but all its other
484 behavior is retained. The object still takes up space, it takes part in
485 collisions, and slurs, ties, and beams can be attached to it.
487 @cindex transparent objects
488 @cindex removing objects
489 @cindex hiding objects
490 @cindex invisible objects
491 The following example demonstrates how to connect different voices
492 using ties. Normally, ties only connect two notes in the same
493 voice. By introducing a tie in a different voice,
495 @lilypond[quote,fragment,relative=2]
504 and blanking the first up-stem in that voice, the tie appears to cross
508 @lilypond[quote,fragment,relative=2,verbatim]
510 \once \override Stem #'transparent = ##t
517 To make sure that the just-blanked stem doesn't squeeze the tie too much,
518 we also lengthen the stem, by setting the @code{length} to
521 @lilypond[quote,fragment,relative=2,verbatim]
523 \once \override Stem #'transparent = ##t
524 \once \override Stem #'length = #8
533 @cindex Tweaks, distances
536 Distances in LilyPond are measured in staff-spaces, while most
537 thickness properties are measured in line-thickness. Some
538 properties are different; for example, the thickness of beams
539 are measured in staff-spaces. For more information, see the
540 relevant portion of the program reference.
543 @node Fitting music onto fewer pages
544 @subsection Fitting music onto fewer pages
546 Sometimes you can end up with one or two staves on a second
547 (or third, or fourth...) page. This is annoying, especially
548 if you look at previous pages and it looks like there is plenty
549 of room left on those.
551 When investigating layout issues, @code{annotate-spacing} is
552 an invaluable tool. This command prints the values of various
553 layout spacing commands; see @ruser{Displaying spacing}, for more
554 details. From the output of @code{annotate-spacing}, we can
555 see which margins we may wish to alter.
557 Other than margins, there are a few other options to save space:
561 You may tell LilyPond to place systems as close together as
562 possible (to fit as many systems as possible onto a page), but
563 then to space those systems out so that there is no blank
564 space at the bottom of the page.
568 between-system-padding = #0.1
569 between-system-space = #0.1
570 ragged-last-bottom = ##f
576 You may force the number of systems (i.e., if LilyPond wants
577 to typeset some music with 11 systems, you could force it to
587 Avoid (or reduce) objects which increase the vertical size of
588 a system. For example, volta repeats (or alternate repeats)
589 require extra space. If these repeats are spread over two
590 systems, they will take up more space than one system with
591 the volta repeats and another system without.
593 Another example is moving dynamics which @q{stick out} of
596 @lilypond[verbatim,quote,fragment]
599 \override DynamicLineSpanner #'padding = #-1.8
600 \override DynamicText #'extra-offset = #'( -2.1 . 0)
606 Alter the horizontal spacing via @code{SpacingSpanner}. See
607 @ruser{Changing horizontal spacing}, for more details.
609 @lilypond[verbatim,quote]
612 g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
613 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
614 d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
615 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
620 \override SpacingSpanner
621 #'base-shortest-duration = #(ly:make-moment 1 4)
630 @node TODO other name
631 @section TODO other name
634 * Predefined tweaks::
635 * Advanced tweaks with Scheme::
636 * Avoiding tweaks with slower processing::
637 * The three methods of tweaking::
640 @node Predefined tweaks
641 @subsection Predefined tweaks
643 TODO: Some tweaks are really common, blah blah.
645 for example \slurUp, \fatText.
647 Show example, then explain where to find ly/propert-ly.
650 The Internals Reference documentation contains a lot of information
651 about LilyPond, but even more information can be gathered from
652 looking at the internal LilyPond files.
654 Some default settings (such as the definitions for
655 @code{\header@{@}}s) are stored as @code{.ly} files. Other
656 settings (such as the definitions of markup commands) are
657 stored as @code{.scm} (Scheme) files. Further explanation is
658 outside the scope of this manual; users should be warned that
659 a substantial amount of technical knowledge or time is required
660 to understand these files.
664 @item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/}
667 @file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}.
668 To access this, either @code{cd} into this directory from the
669 Terminal, or control-click on the LilyPond application and select
670 @q{Show Package Contents}.
672 @item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/}
676 The @file{ly/} and @file{scm/} directories will be of
677 particular interest. Files such as @file{ly/property-init.ly} and
678 @file{ly/declarations-init.ly} define all the common tweaks.
681 @node Advanced tweaks with Scheme
682 @subsection Advanced tweaks with Scheme
684 We have seen how LilyPond output can be heavily modified using
686 @code{\override TextScript #'extra-offset = ( 1 . -1)}. But
687 we have even more power if we use Scheme. For a full explantion
688 of this, see the @ref{Scheme tutorial}, and
689 @ruser{Interfaces for programmers}.
691 We can use Scheme to simply @code{\override} commands,
693 @lilypond[quote,verbatim,ragged-right]
694 padText = #(define-music-function (parser location padding) (number?)
696 \once \override TextScript #'padding = #$padding
704 c4^"piu mosso" fis a g
708 We can use it to create new commands,
710 @lilypond[quote,verbatim,ragged-right]
711 tempoMark = #(define-music-function (parser location padding marktext)
714 \once \override Score . RehearsalMark #'padding = $padding
715 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
716 \mark \markup { \bold $marktext }
721 \tempoMark #3.0 #"Allegro"
726 Even music expressions can be passed in.
728 @lilypond[quote,verbatim,ragged-right]
729 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
736 \pattern {d16 dis} { ais16-> b\p }
741 @node Avoiding tweaks with slower processing
742 @subsection Avoiding tweaks with slower processing
744 LilyPond can perform extra checks while it processes files. These
745 commands will take extra time, but the result may require fewer
749 %% makes sure text scripts and lyrics are within the paper margins
750 \override Score.PaperColumn #'keep-inside-line = ##t
751 \override Score.NonMusicalPaperColumn #'keep-inside-line = ##t
754 In some cases (see issue 246), this must be done before
755 @code{\override} commands can be processed.
759 \override PaperColumn #'keep-inside-line = ##t
760 \override NonMusicalPaperColumn #'keep-inside-line = ##t
767 @node The three methods of tweaking
768 @subsection The three methods of tweaking
794 FIXME: Move the following words and example into Tweaks or
795 somewhere more suitable, leaving just a ref here. -td
797 Ways of correcting horizontal placings are described fully
798 in the Notation Reference.
799 We introduce just one here, the @code{force-hshift} property of
800 @code{NoteColumn}. The lower two notes of the first chord (i.e,
801 those in the third voice) should not be shifted away from the
802 note column of the higher two notes. To correct this we set
803 @code{force-hshift} of these notes to zero.
804 The lower note of the second chord is best placed just to the
805 right of the higher notes. We achieve this by setting
806 @code{force-hshift} of this note to 0.5, ie half a notehead's
807 width to the right of the note column of the higher notes.
809 Here's the final result:
811 @lilypond[quote,verbatim,fragment,ragged-right]
812 \new Staff \relative c'' {
818 \once \override NoteColumn #'force-hshift = #0 <ees c>2
819 \once \override NoteColumn #'force-hshift = #0.5 des2
830 - There is a section in the manual on \set vs \override (3.3.7),
831 which is incomplete. First it doesn't mention \overrideProperty,
832 nor does it mention properties which are not capitalized at all.
833 And it should explain that \override should be used to set
834 properties with hyphenated names, like auto-knee-gap. (I had to
835 experiment to find out how to do this.)
838 FIXME: moved from fundamental, dumped here at random.
840 @lilypond[verbatim,quote,ragged-right]
841 \new Staff = "main" {
845 << % Start main and ossia in parallel
846 { r8 f c c } % Main music
847 \new Staff \with { % Start ossia staff
848 \remove "Clef_engraver"
849 \remove "Time_signature_engraver"
850 % Reduce size of notes and staff
852 \override StaffSymbol #'staff-space = #(magstep -2)
853 alignAboveContext = "main" % Place above main staff
855 { s8 f f c } % Ossia music
856 >> % End parallel music