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.
13 @chapter Tweaking output
15 This chapter discusses how to modify output. LilyPond is extremely
16 configurable; virtually every fragment of output may be changed.
21 * The Internals Reference manual::
22 * Appearance of objects::
23 * Placement of objects::
24 * Collisions of objects::
29 @section Tweaking basics
32 * Introduction to tweaks::
33 * Objects and interfaces::
34 * Naming conventions of objects and properties::
38 @node Introduction to tweaks
39 @subsection Introduction to tweaks
41 @q{Tweaking} is a LilyPond term for the various methods available
42 to the user for modifying the actions taken during interpretation
43 of the input file and modifying the appearance of the printed
44 output. Some tweaks are very easy to use; others are more
45 complex. But taken together the methods available for tweaking
46 permit almost any desired appearance of the printed music to be
49 In this section we cover the basic concepts required to understand
50 tweaking. Later we give a variety of ready-made commands which can
51 simply be copied to obtain the same effect in your own scores, and
52 at the same time we show how these commands may be constructed so
53 that you may learn how to develop your own tweaks.
55 Before starting on this Chapter you may wish to review the section
56 @ref{Contexts and engravers}, as Contexts, Engravers, and the
57 Properties contained within them are fundamental to understanding
58 and constructing Tweaks.
60 @node Objects and interfaces
61 @subsection Objects and interfaces
68 Tweaking involves modifying the internal operation and structures
69 of the LilyPond program, so we must first introduce some terms
70 which are used to describe those internal operations and
73 The term @q{Object} is a generic term used to refer to the
74 multitude of internal structures built by LilyPond during the
75 processing of an input file. So when a command like @code{\new
76 Staff} is encountered a new object of type @code{Staff} is
77 constructed. That @code{Staff} object then holds all the
78 properties associated with that particular staff, for example, its
79 name and its key signature, together with details of the engravers
80 which have been assigned to operate within that staff's context.
81 Similarly, there are objects to hold the properties of all other
82 contexts, such as @code{Voice} objects, @code{Score} objects,
83 @code{Lyrics} objects, as well as objects to represent all
84 notational elements such as bar lines,
85 note heads, ties, dynamics, etc. Every object has its own set of
88 Some types of object are given special names. Objects which
89 represent items of notation on the printed output such as
90 note heads, stems, slurs, ties, fingering, clefs, etc are called
91 @q{Layout objects}, often known as @q{Graphical Objects}, or
92 @q{Grobs} for short. These are still objects in the generic sense
93 above, and so they too all have properties associated with them,
94 such as their position, size, color, etc.
96 Some layout objects are still more specialized. Phrasing slurs,
97 crescendo hairpins, ottava marks, and many other grobs are not
98 localized in a single place -- they have a starting point, an
99 ending point, and maybe other properties concerned with their
100 shape. Objects with an extended shape like these are called
103 It remains to explain what @q{Interfaces} are. Many objects,
104 even though they are quite different, share common features
105 which need to be processed in the same way.
106 For example, all grobs have a color, a size, a position, etc,
107 and all these properties are processed in the same way during
109 interpretation of the input file. To simplify these internal
110 operations these common actions and properties are grouped
111 together in an object called a @code{grob-interface}. There
112 are many other groupings of common properties like this, each
113 one given a name ending in @code{interface}. In total there
114 are over 100 such interfaces. We shall see later why this is
115 of interest and use to the user.
117 These, then, are the main terms relating to objects which we
118 shall use in this chapter.
120 @node Naming conventions of objects and properties
121 @subsection Naming conventions of objects and properties
123 We met some object naming conventions previously, in
124 @ref{Contexts and engravers}. Here for reference is a list
125 of the most common object and property types together with
126 the conventions for naming them and a couple of examples of
127 some real names. We have used A to stand for any capitalized
128 alphabetic character and aaa to stand for any number of
129 lower-case alphabetic characters. Other characters are used
132 @multitable @columnfractions .33 .33 .33
133 @headitem Object/property type
134 @tab Naming convention
137 @tab Aaaa or AaaaAaaaAaaa
138 @tab Staff, GrandStaff
140 @tab Aaaa or AaaaAaaaAaaa
143 @tab Aaaa_aaa_engraver
144 @tab Clef_engraver, Note_heads_engraver
146 @tab aaa-aaa-interface
147 @tab grob-interface, break-aligned-interface
148 @item Context Properties
149 @tab aaa or aaaAaaaAaaa
150 @tab alignAboveContext, skipBars
151 @item Layout Object Properties
152 @tab aaa or aaa-aaa-aaa
153 @tab direction, beam-thickness
156 As we shall see shortly, the properties of different types of
157 object are modified by different commands, so it is useful to
158 be able to recognize the type of object from the names of its
162 @node Tweaking methods
163 @subsection Tweaking methods
165 @strong{\override command}
167 @cindex override command
170 We have already met the commands @code{\set} and @code{\with},
171 used to change the properties of @strong{contexts} and to remove
172 and add @strong{engravers}, in
173 @ref{Modifying context properties} and @ref{Adding
174 and removing engravers}. We now must meet some more important
177 The command to change the properties of @strong{layout objects} is
178 @code{\override}. Because this command has to modify
179 internal properties deep within LilyPond its syntax is not
180 as simple as the commands you have met so far. It needs to
181 know precisely which property of which object in which context
182 has to be modified, and what its new value is to be. Let's see
185 The general syntax of this command is:
188 \override @emph{context}.@emph{layout_object}
189 #'@emph{layout_property} = #@emph{value}
193 This will set the property with the name @emph{layout_property}
194 of the layout object with the name
195 @emph{layout_object}, which is a member of the @emph{context}
196 context, to the value @emph{value}.
198 The @emph{context} can be omitted (and usually is) when the
199 required context is unambiguously implied and is one of lowest
200 level contexts, i.e., @code{Voice}, @code{ChordNames} or
201 @code{Lyrics}, and we shall omit it in many of the following
202 examples. We shall see later when it must be specified.
204 Later sections deal comprehensively with properties and their
205 values, but to illustrate the format and use of these commands
206 we shall use just a few simple properties and values which are
209 For now, don't worry about the @code{#'}, which must precede the
210 layout property, and the @code{#}, which must precede the value.
211 These must always be present in exactly this form. This is the
212 most common command used in tweaking, and most of the rest of
213 this chapter will be directed to presenting examples of how it is
214 used. Here is a simple example to change the color of the
217 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
219 \override NoteHead #'color = #red
221 \override NoteHead #'color = #green
225 @strong{\revert command}
227 @cindex revert command
230 Once overridden, the property retains its new value until it is
231 overridden again or a @code{\revert} command is encountered.
232 The @code{\revert} command has the following syntax and causes
233 the value of the property to revert to its original default
234 value; note, not its previous value if several @code{\override}
235 commands have been issued.
238 \revert @emph{context}.@emph{layout_object} #'@emph{layout_property}
241 Again, just like @emph{context} in the @code{\override} command,
242 @emph{context} is often not needed. It will be omitted
243 in many of the following examples. Here we revert the color
244 of the note head to the default value for the final two notes:
246 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
248 \override NoteHead #'color = #red
250 \override NoteHead #'color = #green
252 \revert NoteHead #'color
256 @strong{\once prefix}
258 Both the @code{\override} and the @code{\set} commands may be
259 prefixed by @code{\once}. This causes the following
260 @code{\override} or @code{\set} command to be effective only
261 during the current musical moment before the property reverts
262 back to its default value. Using the same example, we can
263 change the color of a single note like this:
265 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
267 \once \override NoteHead #'color = #red
269 \once \override NoteHead #'color = #green
273 @strong{\overrideProperty command}
275 @cindex overrideProperty command
276 @funindex \overrideProperty
278 There is another form of the override command,
279 @code{\overrideProperty}, which is occasionally required.
280 We mention it here for completeness, but for details see
281 @ruser{Difficult tweaks}.
282 @c Maybe explain in a later iteration -td
284 @strong{\tweak command}
286 @cindex tweak command
289 The final tweaking command which is available is @code{\tweak}.
290 This should be used to change the properties of objects which
291 occur at the same musical moment, such as the notes within a
292 chord. Using @code{\override} would affect all the notes
293 within a chord, whereas @code{\tweak} affects just the following
294 item in the input stream.
296 Here's an example. Suppose we wish to change the size of the
297 middle note (the E) in a C major chord. Let's first see what
298 @code{\once \override} would do:
300 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
302 \once \override NoteHead #'font-size = #-3
307 We see the override affects @emph{all} the notes in the chord.
308 This is because all the notes of a chord occur at the same
309 @emph{musical moment}, and the action of @code{\once} is to
310 apply the override to all layout objects of the type specified
311 which occur at the same musical moment as the @code{\override}
314 The @code{\tweak} command operates in a different way. It acts
315 on the immediately following item in the input stream. However,
316 it is effective only on objects which are created directly from
317 the input stream, essentially note heads and articulations.
318 (Objects such as stems and accidentals are created later and
319 cannot be tweaked in this way). Furthermore, when it is applied
320 to note heads these @emph{must} be within a chord, i.e., within
321 single angle brackets, so to tweak a single note the @code{\tweak}
322 command must be placed inside single angle brackets with the
325 So to return to our example, the size of the middle note of
326 a chord would be changed in this way:
328 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
330 <c \tweak #'font-size #-3 e g>4
333 Note that the syntax of @code{\tweak} is different from that
334 of the @code{\override} command. Neither the context nor the
335 layout object should be specified; in fact, it would generate
336 an error to do so. These are both implied by the following
337 item in the input stream. So the general syntax of the
338 @code{\tweak} command is simply:
341 \tweak #'@emph{layout_property} = #@emph{value}
344 A @code{\tweak} command can also be used to modify just one in
345 a series of articulations, as shown here:
347 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
349 -\tweak #'color #red ^Red
350 -\tweak #'color #green _Green
353 Note that the @code{\tweak} command must be preceded by an
354 articulation mark as if it were an articulation itself.
356 @cindex tuplets, nested
357 @cindex triplets, nested
358 @cindex bracket, tuplet
359 @cindex tuplet bracket
360 @cindex triplet bracket
361 @funindex TupletBracket
363 The @code{\tweak} command must also be used to change the
364 appearance of one of a set of nested tuplets which begin at the
365 same musical moment. In the following example, the long tuplet
366 bracket and the first of the three short brackets begin at the
367 same musical moment, so any @code{\override} command would apply
368 to both of them. In the example, @code{\tweak} is used to
369 distinguish between them. The first @code{\tweak} command
370 specifies that the long tuplet bracket is to be placed above the
371 notes and the second one specifies that the tuplet number is to be
372 printed in red on the first short tuplet bracket.
374 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
375 \tweak #'direction #up
378 \times 2/3 { c8[ c8 c8] }
379 \times 2/3 { c8[ c8 c8] }
380 \times 2/3 { c8[ c8 c8] }
384 You can find more details of the @code{\tweak} command in
385 @ruser{Objects connected to the input}.
387 If nested tuplets do not begin at the same moment their
388 appearance may be modified in the usual way with
389 @code{\override} commands:
391 @c NOTE Tuplet brackets collide if notes are high on staff
393 @lilypond[quote,ragged-right,verbatim,fragment,relative=1]
394 \times 2/3 { c8[ c c]}
395 \once \override TupletNumber
396 #'text = #tuplet-number::calc-fraction-text
400 \once \override TupletNumber #'transparent = ##t
401 \times 2/3 { c8[ c c] }
402 \times 2/3 { c8[ c c]}
407 @node The Internals Reference manual
408 @section The Internals Reference manual
410 @cindex Internals Reference
413 * Properties of layout objects::
414 * Properties found in interfaces::
415 * Types of properties::
418 @node Properties of layout objects
419 @subsection Properties of layout objects
421 @cindex properties of layout objects
422 @cindex properties of grobs
423 @cindex grobs, properties of
424 @cindex layout objects, properties of
426 Suppose you have a slur in a score which, to your mind,
427 appears too thin and you'd like to draw it a little heavier.
428 How do you go about doing this? You know from the statements
429 earlier about the flexibility of LilyPond that such a thing
430 should be possible, and you would probably guess that an
431 @code{\override} command would be needed. But is there a
432 heaviness property for a slur, and if there is, how might it
433 be modified? This is where the Internals Reference manual
434 comes in. It contains all the information you might need to
435 construct this and all other @code{\override} commands.
437 Before we look at the Internals Reference a word of warning.
438 This is a @strong{reference} document, which means there is
439 little or no explanation contained within it: its purpose is
440 to present information precisely and concisely. This
441 means it might look daunting at first sight. Don't worry!
442 The guidance and explanation presented here will enable you
443 to extract the information from the Internals Reference for
444 yourself with just a little practice.
446 @cindex override example
447 @cindex Internals Reference, example of using
449 Let's use a concrete example with a simple fragment of real
452 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
457 g[( e]) e d[( f]) a |
461 The man who feels love's sweet e -- mo -- tion
466 Suppose now that we decide we would like the slurs to be a
467 little heavier. Is this possible? The slur is certainly a
468 layout object, so the question is, @q{Is there a property
469 belonging to a slur which controls the heaviness?} To answer
470 this we must look in the Internals Reference, or IR for short.
472 The IR for the version of LilyPond you are using may be found
473 on the LilyPond website at @uref{http://lilypond.org}. Go to the
474 documentation page and click on the Internals Reference link.
475 For learning purposes you should use the standard html version,
476 not the @q{one big page} or the PDF. For the next few
477 paragraphs to make sense you will need to actually do this
480 Under the heading @strong{Top} you will see five links. Select
481 the link to the @emph{Backend}, which is where information about
482 layout objects is to be found. There, under the heading
483 @strong{Backend}, select the link to @emph{All layout objects}.
484 The page that appears lists all the layout objects used in your
485 version of LilyPond, in alphabetic order. Select the link to
486 Slur, and the properties of Slurs are listed.
488 (An alternative way of finding this page is from the Notation
489 Reference. On one of the pages that deals with slurs you may
490 find a link to the Internals Reference. This link will
491 take you directly to this page, but often it is easier to go
492 straight to the IR and search there.)
494 This Slur page in the IR tells us first that Slur objects are
496 Slur_engraver. Then it lists the standard settings. Note
497 these are @strong{not} in alphabetic order. Browse down
498 them looking for a property that might control the heaviness
499 of slurs, and you should find
502 @code{thickness} (number)
504 Line thickness, generally measured in @code{line-thickness}
507 This looks a good bet to change the heaviness. It tells us that
508 the value of @code{thickness} is a simple @emph{number},
509 that the default value is 1.2, and that the units are
510 in another property called @code{line-thickness}.
512 As we said earlier, there are few to no explanations in the IR,
513 but we already have enough information to try changing the
514 slur thickness. We see that the name of the layout object
515 is @code{Slur}, that the name of the property to change is
516 @code{thickness} and that the new value should be a number
517 somewhat larger than 1.2 if we are to make slurs thicker.
519 We can now construct the @code{\override} command by simply
520 substituting the values we have found for the names, omitting
521 the context. Let's use a very large value for the thickness
522 at first, so we can be sure the command is working. We get:
525 \override Slur #'thickness = #5.0
528 Don't forget the @code{#'} preceding the
529 property name and and @code{#} preceding the new value!
531 The final question is, @q{Where should this command be
532 placed?} While you are unsure and learning, the best
533 answer is, @q{Within the music, before the first slur and
534 close to it.} Let's do that:
536 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
540 % Increase thickness of all following slurs from 1.2 to 5.0
541 \override Slur #'thickness = #5.0
543 g[( e]) e d[( f]) a |
547 The man who feels love's sweet e -- mo -- tion
553 and we see that the slur is indeed heavier.
555 So this is the basic way of constructing @code{\override}
556 commands. There are a few more complications that we
557 shall meet in later sections, but you now know all the
558 essentials required to make up your own -- but you will
559 still need some practice. This is provided in the examples
562 @subheading Finding the context
563 @cindex context, finding
565 But first, what if we had needed to specify the Context?
566 What should it be? We could guess that slurs are in
567 the Voice context, as they are clearly closely associated
568 with individual lines of music, but can we be sure? To
569 find out, go back to the top of the IR page describing the
570 Slur, where it says @q{Slur objects are created by: Slur
571 engraver}. So slurs will be created in whichever context
572 the @code{Slur_engraver} is in. Follow the link to the
573 @code{Slur_engraver} page. At the very bottom it tells
574 us that @code{Slur_engraver} is part of five Voice contexts,
575 including the standard voice context, @code{Voice}, so our
576 guess was correct. And because @code{Voice} is one of the
577 lowest level contexts which is implied unambiguously by
578 the fact that we are entering notes, we can omit it in this
581 @subheading Overriding once only
583 @cindex overriding once only
584 @cindex once override
587 As you can see, @emph{all} the slurs are thicker in the
588 final example above. But what if we
589 wanted just the first slur to be thicker? This is achieved
590 with the @code{\once} command. Placed immediately before
591 the @code{\override} command it causes it to change only the
592 slur which begins on the @strong{immediately following} note.
594 immediately following note does not begin a slur the command
595 has no effect at all -- it is not remembered until a slur
596 is encountered, it is simply discarded. So the command with
598 repositioned as follows:
600 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
605 % Increase thickness of immediately following slur only
606 \once \override Slur #'thickness = #5.0
608 g[( e]) e d[( f]) a |
612 The man who feels love's sweet e -- mo -- tion
618 Now only the first slur is made heavier.
620 The @code{\once} command can also be used before the @code{\set}
623 @subheading Reverting
626 @cindex default properties, reverting
629 Finally, what if we wanted just the first two slurs to be
630 heavier? Well, we could use two commands, each preceded by
631 @code{\once} placed immediately before each of the notes where
634 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
639 % Increase thickness of immediately following slur only
640 \once \override Slur #'thickness = #5.0
642 % Increase thickness of immediately following slur only
643 \once \override Slur #'thickness = #5.0
644 g[( e]) e d[( f]) a |
648 The man who feels love's sweet e -- mo -- tion
654 or we could omit the @code{\once} command and use the
655 @code{\revert} command
656 to return the @code{thickness} property to its default value
657 after the second slur:
659 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
664 % Increase thickness of all following slurs from 1.2 to 5.0
665 \override Slur #'thickness = #5.0
668 % Revert thickness of all following slurs to default of 1.2
669 \revert Slur #'thickness
674 The man who feels love's sweet e -- mo -- tion
680 The @code{\revert} command can be used to return any property
681 changed with @code{\override} back to its default value.
682 You may use whichever method best suits what you want to do.
684 That concludes our introduction to the IR, and the basic
685 method of tweaking. Several examples follow in the later
686 sections of this Chapter, partly to introduce you to some of the
687 additional features of the IR, and partly to give you more
688 practice in extracting information from it. These examples will
689 contain progressively fewer words of guidance and explanation.
691 @node Properties found in interfaces
692 @subsection Properties found in interfaces
694 @cindex interface properties
695 @cindex properties in interfaces
697 Suppose now that we wish to print the lyrics in italics. What
698 form of @code{\override} command do we need to do this?
699 We first look in the IR page listing @q{All layout objects}, as
700 before, and look for an object that might control lyrics. We
701 find @code{LyricText}, which looks right. Clicking on this shows
702 the settable properties for lyric text. These include the
703 @code{font-series} and @code{font-size}, but nothing that might
704 give an italic shape.
705 This is because the shape property is one that is common to all
706 font objects, so, rather than including it in every layout
707 object, it is grouped together with other similar common
708 properties and placed in an @strong{Interface}, the
709 @code{font-interface}.
711 So now we need to learn how to find the properties of interfaces,
712 and to discover what objects use these interface properties.
714 Look again at the IR page which describes LyricText. At the
715 bottom of the page is a list of clickable (in the html versions
716 of the IR) interfaces which LyricText supports. The list has
717 seven items, including @code{font-interface}.
718 Clicking on this brings up the properties associated
719 with this interface, which are also properties of all the objects
720 which support it, including LyricText.
722 Now we see all the user-settable properties which control fonts,
723 including @code{font-shape(symbol)}, where @code{symbol} can be
724 set to @code{upright}, @code{italics} or @code{caps}.
726 You will notice that @code{font-series} and @code{font-size}
727 are also listed there.
728 This immediately raises the question: Why are the common font
729 properties @code{font-series} and @code{font-size} listed under
730 @code{LyricText} as well as under the interface
731 @code{font-interface} but @code{font-shape} is not? The answer
732 is that @code{font-series} and @code{font-size} are changed
733 from their global default values when a @code{LyricText} object
734 is created, but @code{font-shape} is not. The entries in
735 @code{LyricText} then tell you the values for those two
736 properties which apply to @code{LyricText}. Other objects
737 which support @code{font-interface} will set these
738 properties differently when they are created.
740 Let's see if we can now construct the @code{\override} command
741 to change the lyrics to italics. The object is @code{LyricText},
742 the property is @code{font-shape} and the value is
743 @code{italic}. As before, we'll omit the context.
745 As an aside, although it is an important one, note that because
747 @code{font-shape} are symbols they must be introduced with a
748 single apostrophe, @code{'}. That is why apostrophes
749 are needed before @code{thickness} in the earlier example
750 and @code{font-shape}. These are both symbols too.
751 Symbols are special names which are known internally to
752 LilyPond. Some of them are the names of properties,
753 like @code{thickness} or @code{font-shape}, others are in
754 effect special values that can be given to properties, like
755 @code{italic}. Note the distinction from arbitrary
756 text strings, which would appear as @code{"a text string"}.
758 Ok, so the @code{\override} command we need to print the lyrics
762 \override LyricText #'font-shape = #'italic
766 and this should be placed just in front of and close to the
767 lyrics which it should affect, like this:
769 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
774 g[( e]) e d[( f]) a |
778 \override LyricText #'font-shape = #'italic
779 The man who feels love's sweet e -- mo -- tion
785 and the lyrics are all printed in italics.
787 @subheading Specifying the context in lyric mode
788 @cindex context, specifying in lyric mode
790 In the case of lyrics, if you try specifying the context in the
791 format given earlier the command will fail. A syllable
792 entered in lyricmode is terminated by either a space,
793 a newline or a digit. All other characters are included
794 as part of the syllable. For this reason a space or newline
795 must appear before the terminating @code{@}} to prevent it being
796 included as part of the final syllable. Similarly,
797 spaces must be inserted before and after the
798 period or dot, @q{.}, separating the context name from the
799 object name, as otherwise the two names are run together and
800 the interpreter cannot recognize them. So the command should be:
803 \override Lyrics . LyricText #'font-shape = #'italic
806 @warning{In lyrics always leave whitespace between the final
807 syllable and the terminating brace.}
809 @warning{In overrides in lyrics always place spaces around
810 the dot between the context name and the object name.}
812 @node Types of properties
813 @subsection Types of properties
815 @cindex Property types
817 So far we have seen two types of property: @code{number} and
818 @code{symbol}. To be valid, the value given to a property
819 must be of the correct type and obey the rules for that type.
820 The type of property is always shown in brackets after the
821 property name in the IR. Here is a list of the types you may
822 need, together with the rules for that type, and some examples.
823 You must always add a hash symbol, @code{#}, of course,
824 to the front of these values when they are entered in the
825 @code{\override} command.
827 @multitable @columnfractions .2 .45 .35
828 @headitem Property type
832 @tab Either True or False, represented by #t or #f
833 @tab @code{#t}, @code{#f}
834 @item Dimension (in staff space)
835 @tab A positive decimal number (in units of staff space)
836 @tab @code{2.5}, @code{0.34}
838 @tab A valid direction constant or its numerical equivalent
839 @tab @code{#LEFT}, @code{#CENTER}, @code{#UP},
842 @tab A positive whole number
843 @tab @code{3}, @code{1}
845 @tab A bracketed set of items separated by spaces,
846 preceded by an apostrophe
847 @tab @code{'(left-edge staff-bar)}, @code{'(1)},
848 @code{'(1.0 0.25 0.5)}
850 @tab Any valid markup
851 @tab @code{\markup @{ \italic "cresc." @}}
853 @tab A fraction of a whole note constructed with the
855 @tab @code{(ly:make-moment 1 4)},
856 @code{(ly:make-moment 3 8)}
858 @tab Any positive or negative decimal value
859 @tab @code{3.5}, @code{-2.45}
860 @item Pair (of numbers)
861 @tab Two numbers separated by a @q{space . space} and enclosed
862 in brackets preceded by an apostrophe
863 @tab @code{'(2 . 3.5)}, @code{'(0.1 . -3.2)}
865 @tab Any of the set of permitted symbols for that property,
866 preceded by an apostrophe
867 @tab @code{'italic}, @code{'inside}
869 @tab A procedure or @code{#f} (to cause no action)
870 @tab @code{bend::print}, @code{ly:text-interface::print},
873 @tab A list of three items enclosed in brackets and preceded
874 by a hash sign, @code{#}.
875 @tab @code{#(#t #t #f)}
878 @node Appearance of objects
879 @section Appearance of objects
881 Let us now put what we have learnt into practice with a few
882 examples which show how tweaks may be used to change the
883 appearance of the printed music.
886 * Visibility and color of objects::
888 * Length and thickness of objects::
891 @node Visibility and color of objects
892 @subsection Visibility and color of objects
894 In the educational use of music we might wish to print a score
895 with certain elements omitted as an exercise for the student,
896 who is required to supply them. As a simple example,
897 let us suppose the exercise is to supply the missing bar lines
898 in a piece of music. But the bar lines are normally inserted
899 automatically. How do we prevent them printing?
901 Before we tackle this, let us remember that object properties
902 are grouped in what are called @emph{interfaces} -- see
903 @ref{Properties found in interfaces}. This is simply to
904 group together those properties that are commonly required
905 together -- if one of them is required for an object, so are
906 the others. Some objects then need the properties in some
907 interfaces, others need them from other interfaces. The
908 interfaces which contain the properties required by a
909 particular grob are listed in the IR at the bottom of the
910 page describing that grob, and those properties may be
911 viewed by looking at those interfaces.
913 We explained how to find information about grobs in
914 @ref{Properties of layout objects}. Using the same approach,
915 we go to the IR to find the layout object which prints
916 bar lines. Going via @emph{Backend} and @emph{All layout objects}
918 is a layout object called @code{BarLine}. Its properties include
919 two that control its visibility: @code{break-visibility} and
920 @code{stencil}. Barline also supports a number of interfaces,
921 including the @code{grob-interface}, where we find the
922 @code{transparent} and the @code{color} properties. All
923 of these can affect the visibility of bar lines (and, of course,
924 by extension, many other layout objects too.) Let's consider
925 each of these in turn.
928 @cindex stencil property
930 This property controls the appearance of the bar lines by specifying
931 the symbol (glyph) which should be printed. In common
932 with many other properties, it can be set to print nothing by
933 setting its value to @code{#f}. Let's try it, as before, omitting
934 the implied Context, @code{Voice}:
936 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
939 \override BarLine #'stencil = ##f
946 The bar lines are still printed. What is wrong? Go back to the
947 IR and look again at the page giving the properties of BarLine.
948 At the top of the page it says @qq{Barline objects are created
949 by: Bar_engraver}. Go to the @code{Bar_engraver} page.
951 it gives a list of Contexts in which the bar engraver operates.
952 All of them are of the type @code{Staff}, so the reason the
953 @code{\override} command failed to work as expected is because
954 @code{Barline} is not in the default @code{Voice} context.
956 is specified wrongly, the command simply does not work. No
957 error message is produced, and nothing is logged in the log
958 file. Let's try correcting it by adding the correct context:
960 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
963 \override Staff.BarLine #'stencil = ##f
970 Now the bar lines have vanished.
972 @subheading break-visibility
974 @cindex break-visibility property
976 We see from the @code{BarLine} properties in the IR that the
977 @code{break-visibility} property requires a vector of three
979 These control respectively whether bar lines are printed at
980 the end of a line, in the middle of lines, and at the beginning
981 of lines. For our example we want all bar lines to be suppressed,
982 so the value we need is @code{#(#f #f #f)}.
983 Let's try that, remembering
984 to include the @code{Staff} context. Note also that in writing
985 this value we have two hash signs before the opening bracket.
986 One is required as part of the value to introduce a vector,
987 and one is required, as always, to precede the value itself in
988 the @code{\override} command.
990 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
993 \override Staff.BarLine #'break-visibility = ##(#f #f #f)
1000 And we see this too removes all the bar lines.
1002 @subheading transparent
1003 @cindex transparent property
1005 We see from the properties specified in the @code{grob-interface}
1006 page in the IR that the @code{transparent} property is a boolean.
1008 should be set to @code{#t} to make the grob transparent.
1009 In this next example let us make the time signature invisible
1010 rather than the bar lines.
1011 To do this we need to find the grob name for the time signature.
1013 the @q{All layout objects} page in the IR to find the properties
1014 of the @code{TimeSignature} layout object. This is produced by
1015 the @code{Time_signature_engraver} which you can check also lives
1016 in the @code{Staff} context and also supports the
1017 @code{grob-interface}. So the command to make the time signature
1020 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1023 \override Staff.TimeSignature #'transparent = ##t
1025 g, a16 b8 c d4 e16 |
1031 The time signature is gone, but this command leaves a gap where
1032 the time signature should be. Maybe this is what is wanted for
1033 an exercise for the student to fill it in, but in other
1034 circumstances a gap might be undesirable. To remove it, the
1035 stencil for the time signature should be set to @code{#f}
1038 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1041 \override Staff.TimeSignature #'stencil = ##f
1043 g, a16 b8 c d4 e16 |
1049 and the difference is obvious: setting the stencil to @code{#f}
1050 removes the object entirely; making the object @code{transparent}
1051 leaves it where it is, but makes it invisible.
1054 @cindex color property
1056 Finally we could make the bar lines invisible by coloring
1057 them white. The @code{grob-interface} specifies that the
1058 color property value is a list, but there is no
1059 explanation of what that list should be. The list it
1060 requires is actually a list of values in internal units,
1061 but, to avoid having to know what these are, several ways
1062 are provided to specify colors. The first way is to use one
1063 of the @q{normal} colors listed in the first table in
1064 @ruser{List of colors}. To set the bar lines to white
1067 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1070 \override Staff.BarLine #'color = #white
1072 g, a16 b8 c d4 e16 |
1078 and again, we see the bar lines are not visible. Note that
1079 @emph{white} is not preceded by an apostrophe -- it is not
1080 a symbol, but a @emph{function}. When called, it provides
1081 the list of internal values required to set the color to
1082 white. The other colors in the normal list are functions
1083 too. To convince yourself this is working you might like
1084 to change the color to one of the other functions in the
1090 The second way of changing the color is to use the list of
1091 X11 color names in the second list in @ruser{List of colors}.
1092 However, these must be preceded by another function, which
1093 converts X11 color names into the list of internal values,
1094 @code{x11-color}, like this:
1096 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1099 \override Staff.BarLine #'color = #(x11-color 'white)
1101 g, a16 b8 c d4 e16 |
1107 Note that in this case the function @code{x11-color} takes
1108 a symbol as an argument, so the symbol must be preceded by
1109 an apostrophe and the two enclosed in brackets.
1114 There is yet a third function, one which converts RGB values into
1115 internal colors -- the @code{rgb-color} function. This takes
1116 three arguments giving the intensities of the red, green and
1117 blue colors. These take values in the range 0 to 1. So to
1118 set the color to red the value should be @code{(rgb-color 1 0 0)}
1119 and to white it should be @code{(rgb-color 1 1 1)}:
1121 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1124 \override Staff.BarLine #'color = #(rgb-color 1 1 1)
1126 g, a16 b8 c d4 e16 |
1131 Finally, there is also a grey scale available as part of the
1132 X11 set of colors. These range from black, @code{'grey0'},
1133 to white, @code{'grey100}, in steps of 1. Let's illustrate
1134 this by setting all the layout objects in our example to
1135 various shades of grey:
1137 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1140 \override Staff.StaffSymbol #'color = #(x11-color 'grey30)
1141 \override Staff.TimeSignature #'color = #(x11-color 'grey60)
1142 \override Staff.Clef #'color = #(x11-color 'grey60)
1143 \override Voice.NoteHead #'color = #(x11-color 'grey85)
1144 \override Voice.Stem #'color = #(x11-color 'grey85)
1145 \override Staff.BarLine #'color = #(x11-color 'grey10)
1147 g, a16 b8 c d4 e16 |
1153 Note the contexts associated with each of the layout objects.
1154 It is important to get these right, or the commands will not
1155 work! Remember, the context is the one in which the appropriate
1156 engraver is placed. The default context for engravers can be
1157 found by starting from the layout object, going from there to
1158 the engraver which produces it, and on the engraver page in the
1159 IR it tells you in which context the engraver will normally be
1163 @node Size of objects
1164 @subsection Size of objects
1166 Let us begin by looking again at the earlier example
1167 see @ref{Nesting music expressions}) which showed
1168 how to introduce a new temporary staff, as in an @rglos{ossia}.
1170 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1171 \new Staff ="main" {
1178 alignAboveContext = "main" }
1186 Ossia are normally written without clef and time signature, and
1187 are usually printed slightly smaller than the main staff. We
1188 already know now how to remove the clef and time signature --
1189 we simply set the stencil of each to @code{#f}, as follows:
1191 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1192 \new Staff ="main" {
1199 alignAboveContext = "main"
1202 \override Staff.Clef #'stencil = ##f
1203 \override Staff.TimeSignature #'stencil = ##f
1213 where the extra pair of braces after the @code{\with} clause are
1214 required to ensure the enclosed overrides and music are applied
1217 But what is the difference between modifying the staff context by
1218 using @code{\with} and modifying the stencils of the clef and the
1219 time signature with \override? The main difference is that
1220 changes made in a @code{\with} clause are made at the time the
1221 context is created, and remain in force as the @strong{default}
1222 values for the duration of that context, whereas
1223 @code{\set} or @code{\override} commands embedded in the
1224 music are dynamic -- they make changes synchronized with
1225 a particular point in the music. If changes are unset or
1226 reverted using @code{\unset} or @code{\revert} they return to
1227 their default values, which will be the ones set in the
1228 @code{\with} clause, or if none have been set there, the normal
1231 Some context properties
1232 can be modified only in @code{\with} clauses. These are those
1233 properties which cannot sensibly be changed after the context
1234 has been created. @code{alignAboveContext} and its partner,
1235 @code{alignBelowContext}, are two such properties -- once the
1236 staff has been created its alignment is decided and it would
1237 make no sense to try to change it later.
1239 The default values of layout object properties can also be set
1240 in @code{\with} clauses. Simply use the normal @code{\override}
1241 command leaving out the context name, since this is unambiguously
1242 defined as the context which the @code{\with} clause is modifying.
1243 If fact, an error will be generated if a context is specified
1246 So we could replace the example above with
1248 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1249 \new Staff ="main" {
1256 alignAboveContext = "main"
1257 % Don't print clefs in this staff
1258 \override Clef #'stencil = ##f
1259 % Don't print time signatures in this staff
1260 \override TimeSignature #'stencil = ##f
1269 Finally we come to changing the size of layout objects.
1271 Some layout objects are created as glyphs selected from
1272 a typeface font. These include note heads, accidentals, markup,
1273 clefs, time signatures, dynamics and lyrics.
1274 Their size is changed by modifying the
1275 @code{font-size} property, as we shall shortly see. Other
1276 layout objects such as slurs and ties -- in general, spanner
1277 objects -- are drawn individually, so there is no
1279 associated with them. These objects generally derive their
1280 size from the objects to which they are attached, so usually
1281 there is no need to change their size manually. Still other
1282 properties such as the length of stems and bar lines, thickness
1283 of beams and other lines, and the separation of staff lines all
1284 need to be modified in special ways.
1286 Returning to the ossia example, let us first change the font-size.
1287 We can do this in two ways. We can either change the size of the
1288 fonts of each object type, like @code{NoteHead}s with commands
1292 \override NoteHead #'font-size = #-2
1295 or we can change the size of all fonts by setting a special
1296 property, @code{fontSize}, using @code{\set}, or by including
1297 it in a @code{\with} clause (but without the @code{\set}).
1303 Both of these statements would cause the font size to be reduced
1304 by 2 steps from its previous value, where each
1305 step reduces or increases the size by approximately 12%.
1307 Let's try it in our ossia example:
1309 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1310 \new Staff ="main" {
1317 alignAboveContext = "main"
1318 \override Clef #'stencil = ##f
1319 \override TimeSignature #'stencil = ##f
1320 % Reduce all font sizes by ~24%
1330 This is still not quite right. The note heads and flags are
1331 smaller, but the stems are too long in proportion and the
1332 staff lines are spaced too widely apart. These need to be
1333 scaled down in proportion to the font reduction. The next
1334 sub-section discusses how this is done.
1336 @node Length and thickness of objects
1337 @subsection Length and thickness of objects
1343 @cindex size, changing
1344 @cindex stem length, changing
1345 @cindex staff line spacing, changing
1347 Distances and lengths in LilyPond are generally measured in
1348 staff-spaces, the distance between adjacent lines in the staff,
1349 (or occasionally half staff spaces) while most @code{thickness}
1350 properties are measured in units of an internal property called
1351 @code{line-thickness.} For example, by default, the lines of
1352 hairpins are given a thickness of 1 unit of @code{line-thickness},
1353 while the @code{thickness} of a note stem is 1.3. Note, though,
1354 that some thickness properties are different; for example, the
1355 thickness of beams is measured in staff-spaces.
1357 So how are lengths to be scaled in proportion to the font size?
1358 This can be done with the help of a special function called
1359 @code{magstep} provided for exactly this purpose. It takes
1360 one argument, the change in font size (#-2 in the example above)
1361 and returns a scaling factor suitable for reducing other
1362 objects in proportion. It is used like this:
1364 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1365 \new Staff ="main" {
1372 alignAboveContext = "main"
1373 \override Clef #'stencil = ##f
1374 \override TimeSignature #'stencil = ##f
1376 % Reduce stem length and line spacing to match
1377 \override StaffSymbol #'staff-space = #(magstep -2)
1387 Since the length of stems and many other length-related properties
1388 are always calculated relative to the
1389 value of the @code{staff-space} property these are automatically
1390 scaled down in length too. Note that this affects only the
1391 vertical scale of the ossia -- the horizontal scale is determined
1392 by the layout of the main music in order to remain synchronized
1393 with it, so it is not affected by any of these changes in size.
1394 Of course, if the scale of all the main music were changed in this
1395 way then the horizontal spacing would be affected. This is
1396 discussed later in the layout section.
1398 This, then, completes the creation of an ossia. The sizes and
1399 lengths of all other objects may be modified in analogous ways.
1401 For small changes in scale, as in the example above, the
1402 thickness of the various drawn lines such as bar lines,
1403 beams, hairpins, slurs, etc does not usually require global
1404 adjustment. If the thickness of any particular layout object
1405 needs to be adjusted this can be best achieved by overriding its
1406 @code{thickness} property. An example of changing the thickness
1407 of slurs was shown above in @ref{Properties of layout objects}.
1408 The thickness of all drawn objects (i.e., those not produced
1409 from a font) may be changed in the same way.
1412 @node Placement of objects
1413 @section Placement of objects
1416 * Automatic behavior::
1417 * Within-staff objects::
1418 * Outside staff objects::
1422 @node Automatic behavior
1423 @subsection Automatic behavior
1425 There are some objects in musical notation that belong to
1426 the staff and there are other objects that should be
1427 placed outside the staff. These are called within-staff
1428 objects and outside-staff objects respectively.
1430 Within-staff objects are those that are located on the staff
1431 -- note heads, stems, accidentals, etc. The positions of
1432 these are usually fixed by the music itself -- they are
1433 vertically positioned on specific lines of the staff or are
1434 tied to other objects that are so positioned. Collisions of
1435 note heads, stems and accidentals in closely set chords are
1436 normally avoided automatically. There are commands and
1437 overrides which can modify this automatic behavior, as we
1440 Objects belonging outside the staff include things such as
1441 rehearsal marks, text and dynamic markings. LilyPond's rule for
1442 the vertical placement of outside-staff objects is to place them
1443 as close to the staff as possible but not so close that they
1444 collide with any other object. LilyPond uses the
1445 @code{outside-staff-priority} property to determine the order in
1446 which the objects should be placed, as follows.
1448 First, LilyPond places all the within-staff objects.
1449 Then it sorts the outside-staff objects according to their
1450 @code{outside-staff-priority}. The outside-staff objects are
1451 taken one by one, beginning with the object with the lowest
1452 @code{outside-staff-priority}, and placed so that they do not
1453 collide with any objects that have already been placed. That is,
1454 if two outside-staff grobs are competing for the same space, the
1455 one with the lower @code{outside-staff-priority} will be placed
1456 closer to the staff. If two objects have the same
1457 @code{outside-staff-priority} the one encountered first will be
1458 placed closer to the staff.
1460 In the following example all the markup texts have the same
1461 priority (since it is not explicitly set). Note that @q{Text3}
1462 is automatically positioned close to the staff again, nestling
1465 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1472 Staves are also positioned, by default, as closely together as
1473 possible (subject to a minimum separation). If notes project
1474 a long way towards an adjacent staff they will force the
1475 staves further apart only if an overlap of the notation
1476 would otherwise occur. The following example demonstrates
1477 this @q{nestling} of the notes on adjacent staves:
1479 @lilypond[quote,ragged-right,verbatim]
1482 \relative c' { c a, }
1485 \relative c'''' { c a, }
1491 @node Within-staff objects
1492 @subsection Within-staff objects
1494 We have already seen how the commands @code{\voiceXXX} affect
1495 the direction of slurs, ties, fingering and
1496 everything else which depends on the direction of the stems.
1497 These commands are essential when writing polyphonic music to
1498 permit interweaving melodic lines to be distinguished.
1499 But occasionally it may be necessary to override this automatic
1500 behavior. This can be done for whole sections of music or even
1501 for an individual note. The property which controls this
1502 behavior is the @code{direction} property of each layout object.
1503 We first explain what this does, and then introduce a number of
1504 ready-made commands which avoid your having to code explicit
1505 overrides for the more common modifications.
1507 Some layout objects like slurs and ties curve, bend or point
1508 either up or down; others like stems and flags also move to
1509 right or left when they point up or down. This is controlled
1510 automatically when @code{direction} is set.
1512 The following example shows in bar 1 the default behavior of
1514 with those on high notes pointing down and those on low notes
1515 pointing up, followed by four notes with all stems forced down,
1516 four notes with all stems forced up, and finally four notes
1517 reverted back to the default behavior.
1519 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1521 \override Stem #'direction = #DOWN
1523 \override Stem #'direction = #UP
1525 \revert Stem #'direction
1529 Here we use the constants @code{DOWN} and @code{UP}.
1530 These have the values @code{-1} and @code{+1} respectively, and
1531 these numerical values may be used instead. The value @code{0}
1532 may also be used in some cases. It is simply treated as meaning
1533 @code{UP} for stems, but for some objects it means @q{center}.
1534 There is a constant, @code{CENTER} which has the value @code{0}.
1536 However, these explicit overrides are not usually used, as there
1537 are simpler equivalent predefined commands available.
1538 Here is a table of the commonest. The meaning of each is stated
1539 where it is not obvious.
1541 @multitable @columnfractions .2 .2 .2 .4
1546 @item @code{\arpeggioDown}
1547 @tab @code{\arpeggioUp}
1548 @tab @code{\arpeggioNeutral}
1549 @tab Arrow is at bottom, at top, or no arrow
1550 @item @code{\dotsDown}
1552 @tab @code{\dotsNeutral}
1553 @tab Direction of movement to avoid staff lines
1554 @item @code{\dynamicDown}
1555 @tab @code{\dynamicUp}
1556 @tab @code{\dynamicNeutral}
1558 @item @code{\phrasingSlurDown}
1559 @tab @code{\phrasingSlurUp}
1560 @tab @code{\phrasingSlurNeutral}
1561 @tab Note: distinct from slur commands
1562 @item @code{\slurDown}
1564 @tab @code{\slurNeutral}
1566 @item @code{\stemDown}
1568 @tab @code{\stemNeutral}
1570 @item @code{\textSpannerDown}
1571 @tab @code{\textSpannerUp}
1572 @tab @code{\textSpannerNeutral}
1573 @tab Text entered as spanner is below/above staff
1574 @item @code{\tieDown}
1576 @tab @code{\tieNeutral}
1578 @item @code{\tupletDown}
1579 @tab @code{\tupletUp}
1580 @tab @code{\tupletNeutral}
1581 @tab Tuplets are below/above notes
1584 Note that these predefined commands may @strong{not} be
1585 preceded by @code{\once}. If you wish to limit the
1586 effect to a single note you must either use the equivalent
1587 @code{\once \override} command or use the predefined command
1588 followed after the affected note by the corresponding
1589 @code{\xxxNeutral} command.
1591 @subheading Fingering
1592 @cindex fingering, placement
1594 The placement of fingering is also affected by the value
1595 of its @code{direction} property, but there are special
1596 commands which allow the fingering of individual notes
1597 of chords to be controlled, with the fingering being placed
1598 above, below, to the left or to the right of each note.
1600 First, here's the effect of @code{direction} on fingering,
1601 the first bar shows the default, then the effect of specifying
1602 @code{DOWN} and @code{UP}:
1604 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1606 \override Fingering #'direction = #DOWN
1608 \override Fingering #'direction = #UP
1612 This is how to control fingering on single notes, but the
1614 property is ignored for chords. Instead, by default, the
1615 fingering is automatically placed both above and below the
1616 notes of a chord, as shown:
1618 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1624 Greater control over the placement of fingering of the
1625 individual notes in a chord is possible by using
1626 the @code{\set fingeringOrientations} command. The format of
1630 @code{\set fingeringOrientations = #'([up] [left/right] [down])}
1634 @code{\set} is used because @code{fingeringOrientations} is a
1635 property of the @code{Voice} context, created and used by the
1636 @code{New_fingering_engraver}.
1638 The property may be set to a list of one to three values.
1639 It controls whether fingerings may be placed above (if
1640 @code{up} appears in the list), below (if @code{down} appears),
1641 to the left (if @code{left} appears, or to the right
1642 (if @code{right} appears). Conversely, if a location is not
1643 listed, no fingering is placed there. LilyPond takes these
1644 constraints and works out the best placement for the fingering
1645 of the notes of the following chords. Note that @code{left} and
1646 @code{right} are mutually exclusive -- fingering may be placed
1647 only on one side or the other, not both.
1649 To control the placement of the fingering of a single note
1650 using this command it is necessary to write it as a single
1651 note chord by placing angle brackets round it.
1653 Here are a few examples:
1655 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
1656 \set fingeringOrientations = #'(left)
1658 < c-1 e-2 g-3 b-5 > 4
1659 \set fingeringOrientations = #'(left)
1661 < c-1 e-2 g-3 b-5 > 4
1662 \set fingeringOrientations = #'(up left down)
1664 < c-1 e-2 g-3 b-5 > 4
1665 \set fingeringOrientations = #'(up left)
1667 < c-1 e-2 g-3 b-5 > 4
1668 \set fingeringOrientations = #'(right)
1670 < c-1 e-2 g-3 b-5 > 4
1674 If the fingering seems a little crowded the @code{font-size}
1675 could be reduced. The default value can be seen from the
1676 @code{Fingering} object in the IR to be @code{-5}, so let's
1679 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
1680 \override Fingering #'font-size = #-7
1681 \set fingeringOrientations = #'(left)
1683 < c-1 e-2 g-3 b-5 > 4
1684 \set fingeringOrientations = #'(left)
1686 < c-1 e-2 g-3 b-5 > 4
1687 \set fingeringOrientations = #'(up left down)
1689 < c-1 e-2 g-3 b-5 > 4
1690 \set fingeringOrientations = #'(up left)
1692 < c-1 e-2 g-3 b-5 > 4
1693 \set fingeringOrientations = #'(right)
1695 < c-1 e-2 g-3 b-5 > 4
1698 @node Outside staff objects
1699 @subsection Outside staff objects
1701 Outside-staff objects are automatically placed to avoid collisions.
1702 Objects with the lower value of the @code{outside-staff-priority}
1703 property are placed nearer to the staff, and other outside-staff
1704 objects are then raised as far as necessary to avoid collisions.
1705 The @code{outside-staff-priority} is defined in the
1706 @code{grob-interface} and so is a property of all layout objects.
1707 By default it is set to @code{#f} for all within-staff objects,
1708 and to a numerical value appropriate to each outside-staff object
1709 when the object is created. The following table shows
1710 the default numerical values for some of the commonest
1711 outside-staff objects which are, by default, placed in the
1712 @code{Staff} or @code{Voice} contexts.
1714 @multitable @columnfractions .3 .3 .3
1715 @headitem Layout Object
1717 @tab Controls position of:
1718 @item @code{MultiMeasureRestText}
1720 @tab Text over full-bar rests
1721 @item @code{TextScript}
1724 @item @code{OttavaBracket}
1726 @tab Ottava brackets
1727 @item @code{TextSpanner}
1730 @item @code{DynamicLineSpanner}
1732 @tab All dynamic markings
1733 @item @code{VoltaBracketSpanner}
1736 @item @code{TrillSpanner}
1738 @tab Spanning trills
1741 Here is an example showing the default placement of some of
1744 @cindex text spanner
1745 @funindex \startTextSpan
1746 @funindex \stopTextSpan
1747 @cindex ottava bracket
1749 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
1750 % Set details for later Text Spanner
1751 \override TextSpanner #'bound-details #'left #'text
1752 = \markup { \small \bold Slower }
1753 % Place dynamics above staff
1755 % Start Ottava Bracket
1760 % Add Dynamic Line Spanner
1766 c\ff c \stopTextSpan
1767 % Stop Ottava Bracket
1772 This example also shows how to create Text Spanners --
1773 text with extender lines above a section of music. The
1774 spanner extends from the @code{\startTextSpan} command to
1775 the @code{\stopTextSpan} command, and the format of the
1776 text is defined by the @code{\override TextSpanner} command.
1777 For more details see @ruser{Text spanners}.
1779 It also shows how ottava brackets are created.
1781 Note that bar numbers, metronome marks and rehearsal marks
1782 are not shown. By default these are created in the
1783 @code{Score} context and their @code{outside-staff-priority}
1784 is ignored relative to the layout objects which are created
1785 in the @code{Staff} context.
1786 If you wish to place bar numbers, metronome marks or rehearsal
1787 marks in accordance with the value of their
1788 @code{outside-staff-priority} the @code{Bar_number_engraver},
1789 @code{Metronome_mark_engraver} or @code{Mark_engraver} respectively
1790 should be removed from the @code{Score} context and placed in the
1791 top @code{Staff} context. If this is done, these marks will be
1792 given the following default @code{outside-staff-priority} values:
1794 @multitable @columnfractions .3 .3
1795 @headitem Layout Object @tab Priority
1796 @item @code{RehearsalMark} @tab @code{1500}
1797 @item @code{MetronomeMark} @tab @code{1000}
1798 @item @code{BarNumber} @tab @code{ 100}
1801 If the default values of @code{outside-staff-priority} do not
1802 give you the placing you want, the priority of any of the objects
1803 may be overridden. Suppose we would
1804 like the ottava bracket to be placed below the text spanner in the
1805 example above. All we need to do is to look up the priority of
1806 @code{OttavaBracket} in the IR or in the tables above, and reduce
1807 it to a value lower than that of a @code{TextSpanner}, remembering
1808 that @code{OttavaBracket} is created in the @code{Staff} context:
1810 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
1811 % Set details for later Text Spanner
1812 \override TextSpanner #'bound-details #'left #'text
1813 = \markup { \small \bold Slower }
1814 % Place dynamics above staff
1816 %Place following Ottava Bracket below Text Spanners
1817 \once \override Staff.OttavaBracket #'outside-staff-priority = #340
1818 % Start Ottava Bracket
1823 % Add Dynamic Line Spanner
1829 c\ff c \stopTextSpan
1830 % Stop Ottava Bracket
1835 Changing the @code{outside-staff-priority} can also be used to
1836 control the vertical placement of individual objects, although
1837 the results may not always be desirable. Suppose we would
1838 like @qq{Text3} to be placed above @qq{Text4} in the example
1839 under Automatic behavior, above (see @ref{Automatic behavior}).
1840 All we need to do is to look up the priority of @code{TextScript}
1841 in the IR or in the tables above, and increase the priority of
1842 @qq{Text3} to a higher value:
1844 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1847 \once \override TextScript #'outside-staff-priority = #500
1852 This certainly lifts @qq{Text3} above @qq{Text4} but it also
1853 lifts it above @qq{Text2}, and @qq{Text4} now drops down.
1854 Perhaps this is not so good. What we would really like to do
1855 is to position all the annotation at the same distance above
1856 the staff? To do this, we clearly
1857 will need to space the notes out horizontally to make more
1858 room for the text. This is done using the @code{textLengthOn}
1861 @subheading \textLengthOn
1863 @funindex \textLengthOn
1864 @cindex notes, spreading out with text
1866 By default, text produced by markup takes up no horizontal space
1867 as far as laying out the music is concerned. The @code{\textLengthOn}
1868 command reverses this behavior, causing the notes to be spaced
1869 out as far as is necessary to accommodate the text:
1871 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1872 \textLengthOn % Cause notes to space out to accommodate text
1879 The command to revert to the default behavior is
1880 @code{\textLengthOff}. Remember @code{\once} only works with
1881 @code{\override}, @code{\set}, @code{\revert} or @code{unset},
1882 so cannot be used with @code{\textLengthOn}.
1884 Markup text will also avoid notes which project above the staff.
1885 If this is not desired, the automatic displacement upwards may
1886 be turned off by setting the priority to @code{#f}. Here's an
1887 example to show how markup text interacts with such notes.
1889 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1890 % This markup is short enough to fit without collision
1894 % This is too long to fit, so it is displaced upwards
1898 % Turn off collision avoidance
1899 \once \override TextScript #'outside-staff-priority = ##f
1903 % Turn off collision avoidance
1904 \once \override TextScript #'outside-staff-priority = ##f
1905 \textLengthOn % and turn on textLengthOn
1906 c,,2^"Long Text " % Spaces at end are honored
1911 @subheading Dynamics
1913 Dynamic markings will normally be positioned beneath the
1914 staff, but may be positioned above with the @code{dynamicUp}
1915 command. They will be positioned vertically relative to the
1916 note to which they are attached, and will float below (or above)
1917 all within-staff objects such as phrasing slurs and bar numbers.
1918 This can give quite acceptable results, as this example
1921 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
1926 bes4.~\f\< \( bes4 bes8 des4\ff\> c16 bes\! |
1927 ees,2.~\)\mf ees4 r8 |
1930 However, if the notes and attached dynamics are close
1931 together the automatic placement will avoid collisions
1932 by displacing later dynamic markings further away, but this may
1933 not be the optimum placement, as this rather artificial example
1936 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1942 Should a similar situation arise in @q{real} music, it may
1943 be preferable to space out the notes
1944 a little further, so the dynamic markings can all fit at the
1945 same vertical distance from the staff. We were able to do this
1946 for markup text by using the @code{\textLengthOn} command, but there
1947 is no equivalent command for dynamic marks. So we shall have to
1948 work out how to do this using @code{\override} commands.
1950 @subheading Grob sizing
1953 @cindex sizing grobs
1954 @cindex @code{X-offset}
1955 @cindex @code{Y-offset}
1956 @cindex @code{X-extent}
1957 @cindex @code{Y-extent}
1959 First we must learn how grobs are sized. All grobs have a
1960 reference point defined within them which is used to position
1961 them relative to their parent object. This point in the grob
1962 is then positioned at a horizontal distance, @code{X-offset},
1963 and at a vertical distance, @code{Y-offset}, from its parent.
1964 The horizontal extent of the object is given by a pair of
1965 numbers, @code{X-extent}, which say where the left and right
1966 edges are relative to the reference point. The vertical extent
1967 is similarly defined by a pair of numbers, @code{Y-extent}.
1968 These are properties of all grobs which support the
1969 @code{grob-interface}.
1971 @cindex @code{extra-spacing-width}
1973 By default, outside-staff objects are given a width of zero so
1974 that they may overlap in the horizontal direction. This is done
1975 by the trick of adding infinity to the leftmost extent and
1976 minus infinity to the rightmost extent by setting the
1977 @code{extra-spacing-width} to @code{'(+inf.0 . -inf.0)}. So
1978 to ensure they do not overlap in the horizontal direction we
1979 must override this value of @code{extra-spacing-width} to
1980 @code{'(0 . 0)} so the true width shines through. This is
1981 the command to do this for dynamic text:
1984 \override DynamicText #'extra-spacing-width = #'(0 . 0)
1988 Let's see if this works in our previous example:
1990 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
1992 \override DynamicText #'extra-spacing-width = #'(0 . 0)
1997 Well, it has certainly stopped the dynamic marks being
1998 displaced, but two problems remain. The marks should be
1999 spaced a little further apart and it would be better
2000 if they were all the same distance from the staff.
2001 We can solve the first problem easily. Instead of making
2002 the @code{extra-spacing-width} zero we could add a little
2003 more to it. The units are the space between two staff
2004 lines, so moving the left edge half a unit to the left and the
2005 right edge half a unit to the right should do it:
2007 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
2009 % Extend width by 1 staff space
2010 \override DynamicText #'extra-spacing-width = #'(-0.5 . 0.5)
2015 This looks better, but maybe we would prefer the dynamic marks
2016 to be aligned along the same baseline rather than going up and
2017 down with the notes. The property to do this is
2018 @code{staff-padding} which is covered in the following section.
2021 @node Collisions of objects
2022 @section Collisions of objects
2026 * Fixing overlapping notation::
2027 * Real music example::
2030 @node Moving objects
2031 @subsection Moving objects
2033 This may come as a surprise, but LilyPond is not perfect. Some
2034 notation elements can overlap. This is unfortunate, but in fact
2035 rather rare. Usually the need to move objects is for clarity or
2036 aesthetic reasons -- they would look better with a little more
2037 or a little less space around them.
2039 There are three main approaches to resolving overlapping
2040 notation. They should be considered in the following order:
2044 The @strong{direction} of one of the overlapping objects may
2045 be changed using the predefined commands listed above for
2046 within-staff objects (see @ref{Within-staff objects}).
2047 Stems, slurs, beams, ties, dynamics, text and tuplets may be
2048 repositioned easily in this way. The limitation is that you
2049 have a choice of only two positions, and neither may be
2053 The @strong{object properties}, which LilyPond uses
2054 when positioning layout objects, may be modified using
2055 @code{\override}. The advantages
2056 of making changes to this type of property are (a) that some
2057 other objects will be moved automatically if necessary to make
2058 room and (b) the single override can apply to all instances of
2059 the same type of object. Such properties include:
2065 This has already been covered in some detail -- see
2066 @ref{Within-staff objects}.
2069 @code{padding}, @code{left-padding},
2070 @code{right-padding}, @code{staff-padding}
2072 @cindex left-padding property
2073 @cindex padding property
2074 @cindex right-padding property
2075 @cindex staff-padding property
2076 As an object is being positioned the value of its @code{padding}
2077 property specifies the gap that must be left between itself and
2078 the nearest edge of the object against which it is being
2079 positioned. Note that it is the @code{padding} value of the object
2080 @strong{being placed} that is used;
2081 the @code{padding} value of the object which is already placed is
2082 ignored. Gaps specified by @code{padding} can be applied
2083 to all objects which support the @code{side-position-interface}.
2085 Instead of @code{padding}, the placement of groups of accidentals
2086 is controlled by @code{left-padding} and @code{right-padding}.
2087 These properties are to be found in the @code{AccidentalPlacement}
2088 object which, note, lives in the @strong{staff} context. Because
2089 accidentals are always positioned after and to the left of
2090 note heads only the @code{right-padding} property has any effect.
2092 The @code{staff-padding} property is closely related to the
2093 @code{padding} property: @code{padding}
2094 controls the minimum amount of space between any object which
2095 supports the @code{side-position-interface} and the nearest
2096 other object (generally the note or the staff lines);
2097 @code{staff-padding} applies only to those objects which are always
2098 set outside the staff -- it controls the minimum amount of space
2099 that should be inserted between that object and the staff. Note
2100 that @code{staff-padding} has no effect on objects which are
2101 positioned relative to the note rather than the staff, even though
2102 it may be overridden without error for such objects -- it is simply
2105 To discover which padding property is required for the object
2106 you wish to reposition, you
2107 need to return to the IR and look up the object's properties.
2108 Be aware that the padding properties might not be located in the
2109 obvious object, so look in objects that appear to be related.
2111 All padding values are measured in staff spaces. For most
2112 objects, this value is set by default to be around 1.0 or less
2113 (it varies with each object). It may be overridden if a larger
2114 (or smaller) gap is required.
2117 @code{self-alignment-X}
2119 @cindex self-alignment-X property
2120 This property can be used to align the object to the left, to
2121 the right, or to center it with respect to the parent object's
2122 reference point. It may be used with all objects which support
2123 the @code{self-alignment-interface}. In general these are objects
2124 that contain text. The values are @code{LEFT}, @code{RIGHT}
2125 or @code{CENTER}. Alternatively, a numerical value between
2126 @code{-1} and @code{+1} may be specified, where @code{-1} is
2127 left-aligned, @code{+1} is right-aligned, and numbers in between
2128 move the text progressively from left-aligned to right-aligned.
2129 Numerical values greater than @code{1} may be specified to move
2130 the text even further to the left, or less than @code{-1} to
2131 move the text even further to the right. A change of @code{1}
2132 in the value corresponds to a movement of half the text's length.
2135 @code{extra-spacing-width}
2137 @cindex extra-spacing-width property
2138 This property is available for all objects which support the
2139 @code{item-interface}. It takes two numbers, the first is added
2140 to the leftmost extent and the second is added to the rightmost
2141 extent. Negative numbers move the edge to the left, positive to
2142 the right, so to widen an object the first number must be negative,
2143 the second positive. Note that not all objects honor both
2144 numbers. For example, the @code{Accidental} object only takes
2145 notice of the first (left edge) number.
2148 @code{staff-position}
2150 @cindex staff-position property
2151 @code{staff-position} is a property of the
2152 @code{staff-symbol-referencer-interface}, which is supported by
2153 objects which are positioned relative to the staff. It specifies
2154 the vertical position of the object relative to the center line
2155 of the staff in half staff-spaces. It is useful in resolving
2156 collisions between layout objects like multi-measure rests, ties
2157 and notes in different voices.
2162 @cindex force-hshift property
2164 Closely spaced notes in a chord, or notes occurring at the same
2165 time in different voices, are arranged in two, occasionally more,
2166 columns to prevent the note heads overlapping. These are called
2167 note columns, and an object called @code{NoteColumn} is created
2168 to lay out the notes in that column.
2170 The @code{force-hshift}
2171 property is a property of a @code{NoteColumn} (actually of the
2172 @code{note-column-interface}). Changing it permits a note column
2173 to be moved in units appropriate to a note column, viz. the note
2174 head width of the first voice note. It should be used in
2175 complex situations where the normal @code{\shiftOn} commands (see
2176 @ref{Explicitly instantiating voices}) do
2177 not resolve the note conflict. It is preferable to the
2178 @code{extra-offset} property for this purpose as there is no need
2179 to work out the distance in staff-spaces, and moving the notes
2180 into or out of a @code{NoteColumn} affects other actions such as
2186 Finally, when all else fails, objects may be manually repositioned
2187 relative to the staff center line vertically, or by
2188 displacing them by any distance to a new position. The
2189 disadvantages are that the correct values for the repositioning
2190 have to be worked out, often by trial and error, for every object
2191 individually, and, because the movement is done after LilyPond has
2192 placed all other objects, the user is responsible for avoiding any
2193 collisions that might ensue. But the main difficulty with this
2194 approach is that the repositioning values may need to be reworked
2195 if the music is later modified. The properties that can be used
2196 for this type of manual repositioning are:
2200 @cindex extra-offset property
2201 This property applies to any layout object
2202 supporting the @code{grob-interface}. It takes a pair of
2203 numbers which specify the extra displacement in the horizontal and
2204 vertical directions. Negative numbers move the object to
2205 the left or down. The units are staff-spaces. The extra
2206 displacement is made after the typesetting of objects is
2207 finished, so an object may be repositioned anywhere without
2208 affecting anything else.
2211 @cindex positions property
2212 This is most useful for manually adjusting the slope and height
2213 of beams, slurs, and tuplets. It takes a pair of numbers
2214 giving the position of the left and right ends of the beam, slur,
2215 etc. relative to the center line of the staff. Units are
2216 staff-spaces. Note, though, that slurs and phrasing slurs cannot
2217 be repositioned by arbitrarily large amounts. LilyPond first
2218 generates a list of possible positions for the slur and by default
2219 finds the slur that @qq{looks best}. If the @code{positions}
2220 property has been overridden the slur that is closest to the
2221 requested positions is selected from the list.
2226 A particular object may not have all of these properties.
2227 It is necessary to go to the IR to look up which properties
2228 are available for the object in question.
2230 Here is a list of the objects which are most likely to be
2231 involved in collisions, together with the name of the object which
2232 should be looked up in the IR in order to discover which properties
2233 should be used to move them.
2235 @multitable @columnfractions .5 .5
2236 @headitem Object type @tab Object name
2237 @item Articulations @tab @code{Script}
2238 @item Beams @tab @code{Beam}
2239 @item Dynamics (vertically) @tab @code{DynamicLineSpanner}
2240 @item Dynamics (horizontally) @tab @code{DynamicText}
2241 @item Fingerings @tab @code{Fingering}
2242 @item Rehearsal / Text marks @tab @code{RehearsalMark}
2243 @item Slurs @tab @code{Slur}
2244 @item Text e.g. @code{^"text"} @tab @code{TextScript}
2245 @item Ties @tab @code{Tie}
2246 @item Tuplets @tab @code{TupletBracket}
2250 @node Fixing overlapping notation
2251 @subsection Fixing overlapping notation
2253 Let's now see how the properties in the previous section can
2254 help to resolve overlapping notation.
2256 @subheading padding property
2257 @cindex padding property
2259 The @code{padding} property can be set to increase
2260 (or decrease) the distance between symbols that are printed
2261 above or below notes.
2263 @lilypond[quote,fragment,relative=1,verbatim]
2265 \override Script #'padding = #3
2269 @lilypond[quote,fragment,relative=1,verbatim]
2270 % This will not work, see below:
2271 \override MetronomeMark #'padding = #3
2275 \override Score.MetronomeMark #'padding = #3
2280 Note in the second example how important it is to figure out what
2281 context handles a certain object. Since the @code{MetronomeMark}
2283 is handled in the @code{Score} context, property changes in the
2284 @code{Voice} context will not be noticed. For more details, see
2285 @ruser{Constructing a tweak}.
2287 If the @code{padding} property of an object is increased when that
2288 object is in a stack of objects being positioned according to
2289 their @code{outside-staff-priority}, then that object and all
2290 objects outside it are moved.
2293 @subheading left-padding and right-padding
2294 @cindex left-padding property
2295 @cindex right-padding property
2297 The @code{right-padding} property affects the spacing between the
2298 accidental and the note to which it applies. It is not often
2299 required, but the following example shows one situation where it
2300 is needed. Suppose we wish to show a chord containing both
2301 a B-natural and a B-flat. To avoid ambiguity we would like to
2302 precede the notes with both a natural and a flat sign. Here
2303 are a few attempts to do this:
2305 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
2311 None work, with the second two showing bad collisions between
2314 One way of achieving this is to override the accidental stencil
2315 with a markup containing the natural and flat symbols in the
2316 order we would like, like this:
2318 @lilypond[quote,ragged-right,verbatim]
2319 naturalplusflat = \markup { \natural \flat }
2321 \once \override Accidental
2322 #'stencil = #ly:text-interface::print
2323 \once \override Accidental #'text = #naturalplusflat
2324 \once \override Score.AccidentalPlacement #'right-padding = #1.5
2330 This necessarily uses an override for the accidental stencil which
2331 will not be covered until later. The stencil type must be a
2332 procedure, here changed to print the contents of the @code{text}
2333 property of @code{Accidental}, which itself is set to be a natural
2334 sign followed by a flat sign. These are then moved further away
2335 from the note head by overriding @code{right-padding}.
2339 @subheading staff-padding property
2340 @cindex staff-padding property
2342 @code{staff-padding} can be used to align objects such as dynamics
2343 along a baseline at a fixed height above the staff, rather than
2344 at a height dependent on the position of the note to which they
2345 are attached. It is not a property of
2346 @code{DynamicText} but of @code{DynamicLineSpanner}.
2347 This is because the baseline should apply equally to @strong{all}
2348 dynamics, including those created as extended spanners.
2349 So this is the way to align the dynamic marks in the example
2350 taken from the previous section:
2352 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
2354 % Extend width by 1 unit
2355 \override DynamicText #'extra-spacing-width = #'(-0.5 . 0.5)
2356 % Align dynamics to a base line 2 units above staff
2357 \override DynamicLineSpanner #'staff-padding = #2
2362 @subheading self-alignment-X property
2363 @cindex self-alignment-X property
2365 The following example shows how this can resolve the collision
2366 of a string fingering object with a note's stem by aligning the
2367 right edge with the reference point of the parent note:
2369 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]
2372 \once \override StringNumber #'self-alignment-X = #RIGHT
2376 @subheading staff-position property
2377 @cindex staff-position property
2379 Multimeasure rests in one voice can collide with notes in another.
2380 Since these rests are typeset centered between the bar lines, it
2381 would require significant effort for LilyPond to figure out which
2382 other notes might collide with it, since all the current collision
2383 handling between notes and between notes and rests is done only
2384 for notes and rests that occur at the same time. Here's an
2385 example of a collision of this type:
2387 @lilypond[quote,verbatim,fragment,ragged-right, relative=1]
2388 << {c c c c} \\ {R1} >>
2391 The best solution here is to move the multimeasure rest down,
2392 since the rest is in voice two.
2393 The default in @code{\voiceTwo} (i.e. in the second voice of a
2394 @code{<<@{...@} \\ @{...@}>>} construct)
2395 is that @code{staff-position} is set to -4 for MultiMeasureRest,
2396 so we need to move it, say, four half-staff spaces down to
2399 @lilypond[quote,verbatim,fragment,ragged-right, relative=1]
2403 \override MultiMeasureRest #'staff-position = #-8
2408 This is better than using, for example, @code{extra-offset},
2409 because the ledger line above the rest is inserted automatically.
2411 @subheading extra-offset property
2412 @cindex extra-offset property
2414 The @code{extra-offset} property provides complete control over the
2415 positioning of an object both horizontally and vertically.
2417 In the following example, the second fingering is moved a little to
2418 the left, and 1.8 staff space downwards:
2420 @lilypond[quote,fragment,relative=1,verbatim]
2423 \once \override Fingering
2424 #'extra-offset = #'(-0.3 . -1.8)
2429 @subheading positions property
2430 @cindex positions property
2432 The @code{positions} property allows the position and slope of
2433 tuplets, slurs, phrasing slurs and beams to be controlled
2434 manually. Here's an example which has an ugly phrasing slur
2435 due to its trying to avoid the slur on the acciaccatura.
2437 @lilypond[quote,verbatim,fragment,ragged-right,relative=1]
2438 r4 \acciaccatura e8\( d8 c ~c d c d\)
2442 We could simply move the phrasing slur above the notes, and this
2443 would be the preferred solution:
2445 @lilypond[quote,verbatim,fragment,ragged-right,relative=1]
2448 \acciaccatura e8\( d8 c ~c d c d\)
2452 but if there were some reason why this could not be done the
2453 other alternative would be to move the left end of the phrasing
2454 slur down a little using the @code{positions} property. This
2455 also resolves the rather nasty shape.
2457 @lilypond[quote,verbatim,fragment,ragged-right,relative=1]
2459 \once \override PhrasingSlur #'positions = #'(-4 . -3)
2461 e8\( d8 c ~c d c d\)
2464 Here's a further example taken from the opening of the left-hand
2465 staff of Chopin's Prelude Op 28 No. 2. We see that the beam
2466 collides with the upper notes:
2468 @lilypond[quote,verbatim,fragment,ragged-right]
2471 << {b,8 ais, b, g,} \\ {e, g e, g} >>
2472 << {b,8 ais, b, g,} \\ {e, g e, g} >>
2477 This can be resolved by manually moving both ends of the beam
2478 up from their position at 2 staff-spaces above the center line to,
2481 @lilypond[quote,verbatim,fragment,ragged-right]
2485 \override Beam #'positions = #'(3 . 3)
2490 << {b,8 ais, b, g,} \\ {e, g e, g} >>
2495 Note that the override continues to apply in the first voice of
2496 the second block of quavers, but not to any of the beams in the
2499 @subheading force-hshift property
2500 @cindex force-hshift property
2501 @c FIXME: formatting stuff (ie not important right now IMO)
2502 @c @a nchor Chopin finally corrected TODOgp
2504 We can now see how to apply the final corrections to the Chopin
2505 example introduced at the end of @ref{I'm hearing Voices}, which
2506 was left looking like this:
2508 @lilypond[quote,verbatim,fragment,ragged-right]
2509 \new Staff \relative c'' {
2512 { c2 aes4. bes8 } \\
2524 The lower two notes of the first chord (i.e,
2525 those in the third voice) should not be shifted away from the
2526 note column of the higher two notes. To correct this we set
2527 @code{force-hshift}, which is a property of
2528 @code{NoteColumn}, of these notes to zero.
2529 The lower note of the second chord is best placed just to the
2530 right of the higher notes. We achieve this by setting
2531 @code{force-hshift} of this note to 0.5, ie half a note head's
2532 width to the right of the note column of the higher notes.
2534 Here's the final result:
2536 @lilypond[quote,verbatim,fragment,ragged-right]
2537 \new Staff \relative c'' {
2540 { c2 aes4. bes8 } \\
2543 \once \override NoteColumn #'force-hshift = #0 <ees c>2
2544 \once \override NoteColumn #'force-hshift = #0.5 des2
2552 @node Real music example
2553 @subsection Real music example
2555 We end this section on Tweaks by showing the steps to be taken to
2556 deal with a tricky example which needs several tweaks to produce
2557 the desired output. The example has been deliberately chosen to
2558 illustrate the use of the Notation Reference to resolve unusual
2559 problems with notation. It is not representative of more usual
2560 engraving process, so please do not let these difficulties put
2561 you off! Fortunately, difficulties like these are not very common!
2563 The example is from Chopin's Première Ballade, Op. 23, bars 6 to
2564 9, the transition from the opening Lento to Moderato.
2565 Here, first, is what we want the output to look like, but to avoid
2566 over-complicating the example too much we have left out the
2567 dynamics, fingering and pedalling.
2569 @c The following should appear as music without code
2570 @lilypond[quote,ragged-right]
2571 rhMusic = \relative c'' {
2574 \once \override Tie #'staff-position = #3.5
2578 \override Staff.NoteCollision #'merge-differently-headed = ##t
2579 \override Staff.NoteCollision #'merge-differently-dotted = ##t
2580 bes2.^\markup {\bold "Moderato"} r8
2582 {c,8[ d fis bes a] | }
2584 % Reposition the c2 to the right of the merged note
2585 {c,8~ \once \override NoteColumn #'force-hshift = #1.0
2586 % Move the c2 out of the main note column so the merge will work
2589 % Stem on the d2 must be down to permit merging
2590 {s8 \stemDown \once \override Stem #'transparent = ##t d2}
2594 \revert Staff.NoteCollision #'merge-differently-headed
2595 \revert Staff.NoteCollision #'merge-differently-dotted
2599 lhMusic = \relative c' {
2601 <d g, d>1)\arpeggio |
2608 \new Staff = "RH" <<
2612 \new Staff = "LH" <<
2621 We note first that the right hand part in the third bar
2622 requires four voices. These are the five beamed eighth notes,
2623 the tied C, the half-note D which is merged with the eighth note
2624 D, and the dotted quarter note F-sharp, which is also merged with
2625 the eighth note at the same pitch. Everything else is in a single
2626 voice, so the easiest way is to introduce these four voices
2627 temporarily at the time they are needed. If you have forgotten
2628 how to do this, look at @ref{I'm hearing Voices}. Let us begin
2629 by entering the notes as two variables and setting up the staff
2630 structure in a score block, and see what LilyPond produces by
2633 @lilypond[quote,verbatim,ragged-right]
2634 rhMusic = \relative c'' {
2639 % Start polyphonic section of four voices
2641 {c,8 d fis bes a | }
2652 lhMusic = \relative c' {
2661 \new Staff = "RH" <<
2665 \new Staff = "LH" <<
2674 All the notes are right, but the appearance is far from
2675 satisfactory. The tie clashes with the change in time signature,
2676 the beaming in the third bar is wrong, the notes are not
2677 merged together, and several notation elements are missing.
2678 Let's first deal with the easier things.
2679 We can correct the beaming by inserting a beam
2680 manually, and we can easily add the left hand slur and the right
2681 hand phrasing slur, since these were all covered in the Tutorial.
2684 @lilypond[quote,verbatim,ragged-right]
2685 rhMusic = \relative c'' {
2690 % Start polyphonic section of four voices
2692 {c,8[ d fis bes a] | }
2703 lhMusic = \relative c' {
2712 \new Staff = "RH" <<
2716 \new Staff = "LH" <<
2725 The first bar is now correct. The second bar contains an arpeggio
2726 and is terminated by a double bar line. How do we do these, as they
2727 have not been mentioned in this Learning Manual? This is where
2728 we need to turn to the Notation Reference. Looking up @q{arpeggio}
2729 and @q{bar line} in the
2730 index quickly shows us that an arpeggio is produced by appending
2731 @code{\arpeggio} to a chord, and a double bar line is produced by
2732 the @code{\bar "||"} command. That's easily done. We next need
2733 to correct the collision of the tie with the time signature. This
2734 is best done by moving the tie upwards. Moving objects was covered
2735 earlier in @ref{Moving objects}, which says that objects positioned
2736 relative to the staff can be moved by overriding their
2737 @code{staff-position} property, which is specified in half staff
2738 spaces relative to the center line of the staff. So the following
2739 override placed just before the first tied note would move the tie
2740 up to 3.5 half staff spaces above the center line:
2742 @code{\once \override Tie #'staff-position = #3.5}
2744 This completes bar two, giving:
2746 @lilypond[quote,verbatim,ragged-right]
2747 rhMusic = \relative c'' {
2749 \once \override Tie #'staff-position = #3.5
2754 % Start polyphonic section of four voices
2756 {c,8[ d fis bes a] | }
2767 lhMusic = \relative c' {
2769 <d g, d>1)\arpeggio |
2776 \new Staff = "RH" <<
2780 \new Staff = "LH" <<
2789 On to bar three and the start of the Moderato section. The
2790 tutorial showed how to add embolded text with the
2791 @code{\markup} command, so adding @q{Moderato} in bold is easy.
2792 But how do we merge notes in different voices together? The
2793 index in the Notation Reference does not mention merging,
2794 but a search of the text for @q{merge} quickly leads us to
2795 the overrides for merging differently headed and differently
2796 dotted notes in @ruser{Collision resolution}. In our
2797 example we need to merge both types of note for the duration
2798 of the polyphonic section in bar 3, so using the information
2799 in the Notation Reference we add
2802 \override Staff.NoteCollision #'merge-differently-headed = ##t
2803 \override Staff.NoteCollision #'merge-differently-dotted = ##t
2807 to the start of that section and
2810 \revert Staff.NoteCollision #'merge-differently-headed
2811 \revert Staff.NoteCollision #'merge-differently-dotted
2817 @lilypond[quote,verbatim,ragged-right]
2818 rhMusic = \relative c'' {
2820 \once \override Tie #'staff-position = #3.5
2824 bes2.^\markup {\bold "Moderato"} r8
2825 \override Staff.NoteCollision #'merge-differently-headed = ##t
2826 \override Staff.NoteCollision #'merge-differently-dotted = ##t
2827 % Start polyphonic section of four voices
2829 {c,8[ d fis bes a] | }
2837 \revert Staff.NoteCollision #'merge-differently-headed
2838 \revert Staff.NoteCollision #'merge-differently-dotted
2842 lhMusic = \relative c' {
2844 <d g, d>1)\arpeggio |
2851 \new Staff = "RH" <<
2855 \new Staff = "LH" <<
2864 These overrides have merged the two F-sharp notes, but not the two
2865 on D. Why not? The answer is there in the same section in the
2866 Notation Reference -- notes being merged must have stems in
2867 opposite directions and two notes cannot be merged successfully if
2868 there is a third note in the same note column. Here the two D's
2869 both have upward stems and there is a third note -- the C. We know
2870 how to change the stem direction using @code{\stemDown}, and
2871 the Notation Reference also says how to move the C -- apply a shift
2872 using one of the @code{\shift} commands. But which one?
2873 The C is in voice two which has shift off, and the two D's are in
2874 voices one and three, which have shift off and shift on,
2875 respectively. So we have to shift the C a further level still
2876 using @code{\shiftOnn} to avoid it interfering with the two D's.
2877 Applying these changes gives:
2879 @lilypond[quote,verbatim,ragged-right]
2880 rhMusic = \relative c'' {
2882 \once \override Tie #'staff-position = #3.5
2886 bes2.^\markup {\bold "Moderato"} r8
2887 \override Staff.NoteCollision #'merge-differently-headed = ##t
2888 \override Staff.NoteCollision #'merge-differently-dotted = ##t
2889 % Start polyphonic section of four voices
2891 {c,8[ d fis bes a] | }
2893 % Move the c2 out of the main note column so the merge will work
2894 {c,8~ \shiftOnn c2 | }
2896 % Stem on the d2 must be down to permit merging
2897 {s8 \stemDown d2 | }
2901 \revert Staff.NoteCollision #'merge-differently-headed
2902 \revert Staff.NoteCollision #'merge-differently-dotted
2906 lhMusic = \relative c' {
2908 <d g, d>1)\arpeggio |
2915 \new Staff = "RH" <<
2919 \new Staff = "LH" <<
2928 Nearly there. Only two problems remain: The downward stem on the
2929 merged D should not be there, and the C would be better positioned
2930 to the right of the D's. We know how to do both of these from the
2931 earlier tweaks: we make the stem transparent, and move the C with
2932 the @code{force-hshift} property. Here's the final result:
2934 @lilypond[quote,verbatim,ragged-right]
2935 rhMusic = \relative c'' {
2938 \once \override Tie #'staff-position = #3.5
2942 bes2.^\markup {\bold "Moderato"} r8
2943 \override Staff.NoteCollision #'merge-differently-headed = ##t
2944 \override Staff.NoteCollision #'merge-differently-dotted = ##t
2946 {c,8[ d fis bes a] | }
2948 % Reposition the c2 to the right of the merged note
2949 {c,8~ \once \override NoteColumn #'force-hshift = #1.0
2950 % Move the c2 out of the main note column so the merge will work
2953 % Stem on the d2 must be down to permit merging
2954 {s8 \stemDown \once \override Stem #'transparent = ##t d2}
2958 \revert Staff.NoteCollision #'merge-differently-headed
2959 \revert Staff.NoteCollision #'merge-differently-dotted
2963 lhMusic = \relative c' {
2965 <d g, d>1)\arpeggio |
2972 \new Staff = "RH" <<
2976 \new Staff = "LH" <<
2986 @node Further tweaking
2987 @section Further tweaking
2990 * Other uses for tweaks::
2991 * Using variables for tweaks::
2992 * Other sources of information::
2993 * Avoiding tweaks with slower processing::
2994 * Advanced tweaks with Scheme::
2997 @node Other uses for tweaks
2998 @subsection Other uses for tweaks
3000 @cindex transparent property, use of
3001 @cindex objects, making invisible
3002 @cindex removing objects
3003 @cindex objects, removing
3004 @cindex hiding objects
3005 @cindex invisible objects
3006 @cindex tying notes across voices
3008 @subheading Tying notes across voices
3010 The following example demonstrates how to connect notes in
3011 different voices using ties. Normally, only two notes in the
3012 same voice can be connected with ties. By using two voices,
3013 with the tied notes in one of them
3015 @lilypond[quote,fragment,relative=2]
3016 << { b8~ b8\noBeam }
3022 and blanking the first up-stem in that voice, the tie appears to
3025 @lilypond[quote,fragment,relative=2,verbatim]
3028 \once \override Stem #'transparent = ##t
3036 To make sure that the just-blanked stem doesn't squeeze the tie
3037 too much, we can lengthen the stem by setting the
3038 @code{length} to @code{8},
3040 @lilypond[quote,fragment,relative=2,verbatim]
3043 \once \override Stem #'transparent = ##t
3044 \once \override Stem #'length = #8
3052 @subheading Simulating a fermata
3054 @cindex stencil property, use of
3055 @cindex fermata, implementing in MIDI
3057 For outside-staff objects it is usually better to override the
3058 object's @code{stencil} property rather than its @code{transparent}
3059 property when you wish to remove it from the printed output.
3060 Setting the @code{stencil} property of an object to @code{#f} will
3061 remove that object entirely from the printed output. This means it
3062 has no effect on the placement of other objects placed relative to
3065 For example, if we wished to change the metronome setting in order
3066 to simulate a fermata in the MIDI output we would not want the
3067 metronome markings to appear in the printed output, and we would
3068 not want it to influence the spacing between the two systems or
3069 the spacing of the notes on the staff. So setting its
3070 @code{stencil} property to @code{#f} would be the best way.
3071 We show here the effect of the two methods:
3073 @lilypond[quote,verbatim,ragged-right]
3076 % Visible tempo marking
3079 \once \override Score.MetronomeMark #'transparent = ##t
3080 % Invisible tempo marking to lengthen fermata note in MIDI
3083 \once \override Score.MetronomeMark #'stencil = ##f
3084 % Invisible tempo marking to restore tempo in MIDI
3094 Both methods remove the metronome mark from the printed output,
3095 and both affect the MIDI timing as required, but the first
3096 (transparent) metronome mark still influences the note spacing
3097 while the second (with no stencil) does not.
3099 @node Using variables for tweaks
3100 @subsection Using variables for tweaks
3102 Override commands are often long and tedious to type, and they
3103 have to be absolutely correct. If the same overrides are to be
3104 used many times it may be worth defining variables to hold them.
3105 Suppose we wish to emphasize certain words in lyrics by printing
3106 them in bold italics. The @code{\italic} and @code{\bold}
3107 commands do not work within lyrics so we must instead use the
3108 following @code{\override} and @code{\revert} commands:
3111 @code{\override Lyrics . LyricText #'font-shape = #'italic}
3112 @code{\override Lyrics . LyricText #'font-series = #'bold}
3114 @code{\revert Lyrics . LyricText #'font-shape}
3115 @code{\revert Lyrics . LyricText #'font-series}
3118 These would be extremely tedious to enter if there were many words
3119 requiring emphasis. So instead we define these as two variables,
3120 and use them as follows:
3122 @lilypond[quote,verbatim]
3124 \override Lyrics . LyricText #'font-shape = #'italic
3125 \override Lyrics . LyricText #'font-series = #'bold
3128 \revert Lyrics . LyricText #'font-shape
3129 \revert Lyrics . LyricText #'font-series
3132 global = { \time 4/4 \partial 4 \key c \major}
3133 SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
3134 AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
3135 TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
3136 BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
3137 VerseOne = \lyrics { E -- | ter -- nal \emph Fa -- ther, \norm | strong to save, }
3138 VerseTwo = \lyricmode { O | \emph Christ, \norm whose voice the | wa -- ters heard, }
3139 VerseThree = \lyricmode { O | \emph Ho -- ly Spi -- rit, \norm | who didst brood }
3140 VerseFour = \lyricmode { O | \emph Tri -- ni -- ty \norm of | love and pow'r }
3146 \new Voice = "Sop" { \voiceOne \global \SopMusic }
3147 \new Voice = "Alto" { \voiceTwo \AltoMusic }
3148 \new Lyrics \lyricsto "Sop" { \VerseOne }
3149 \new Lyrics \lyricsto "Sop" { \VerseTwo }
3150 \new Lyrics \lyricsto "Sop" { \VerseThree }
3151 \new Lyrics \lyricsto "Sop" { \VerseFour }
3155 \new Voice = "Tenor" { \voiceOne \TenorMusic }
3156 \new Voice = "Bass" { \voiceTwo \BassMusic }
3164 @node Other sources of information
3165 @subsection Other sources of information
3167 The Internals Reference documentation contains a lot of information
3168 about LilyPond, but even more information can be gathered by
3169 looking at the internal LilyPond files. To explore these, first
3170 find the directory appropriate to your system, as follows:
3175 @file{@var{installdir}/lilypond/usr/share/lilypond/current/}
3180 @file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}
3181 by either @code{cd}-ing into this directory from the
3182 Terminal, or control-clicking on the LilyPond application and
3183 selecting @q{Show Package Contents}.
3187 Using Windows Explorer, navigate to
3188 @file{@var{installdir}/LilyPond/usr/share/lilypond/current/}
3190 Within this directory the two interesting subdirectories are
3193 @item @file{../ly/ } - contains files in LilyPond format
3194 @item @file{../scm/} - contains files in Scheme format
3197 Let's begin by looking at some files in @file{../ly/}.
3198 Open @file{../ly/property-init.ly} in a text editor. The one
3199 you normally use for @code{.ly} files will be fine. This file
3200 contains the definitions of all the standard LilyPond built-in
3201 commands, such as @code{\stemUp} and @code{\slurDotted}. You will
3202 see that these are nothing more than definitions of variables
3203 containing one or a group of @code{\override} commands. For
3204 example, @code{/tieDotted} is defined to be:
3208 \override Tie #'dash-period = #0.75
3209 \override Tie #'dash-fraction = #0.1
3213 If you do not like the default values these built-in commands can
3214 be redefined easily, just like any other variable, at the
3215 head of your input file.
3217 The following are the most useful files to be found in
3220 @multitable @columnfractions .4 .6
3223 @item @file{../ly/engraver-init.ly}
3224 @tab Definitions of engraver Contexts
3225 @item @file{../ly/paper-defaults.ly}
3226 @tab Specifications of paper-related defaults
3227 @item @file{../ly/performer-init.ly}
3228 @tab Definitions of performer Contexts
3229 @item @file{../ly/property-init.ly}
3230 @tab Definitions of all common built-in commands
3233 Other settings (such as the definitions of markup commands) are
3234 stored as @code{.scm} (Scheme) files. The Scheme programming
3235 language is used to provide a programmable interface into
3236 LilyPond internal operation. Further explanation of these files
3237 is currently outside the scope of this manual, as a knowledge of
3238 the Scheme language is required. Users should be warned that
3239 a substantial amount of technical knowledge or time is required
3240 to understand Scheme and these files (see @ref{Scheme tutorial}).
3242 If you have this knowledge, the Scheme files which may be of
3245 @multitable @columnfractions .4 .6
3248 @item @file{../scm/auto-beam.scm}
3249 @tab Sub-beaming defaults
3250 @item @file{../scm/define-grobs.scm}
3251 @tab Default settings for grob properties
3252 @item @file{../scm/define-markup-commands.scm}
3253 @tab Specify all markup commands
3254 @item @file{../scm/midi.scm}
3255 @tab Default settings for MIDI output
3256 @item @file{../scm/output-lib.scm}
3257 @tab Settings that affect appearance of frets, colors,
3258 accidentals, bar lines, etc
3259 @item @file{../scm/parser-clef.scm}
3260 @tab Definitions of supported clefs
3261 @item @file{../scm/script.scm}
3262 @tab Default settings for articulations
3267 @node Avoiding tweaks with slower processing
3268 @subsection Avoiding tweaks with slower processing
3270 LilyPond can perform extra checks while it processes input files. These
3271 checks will take extra time to perform, but fewer manual tweaks
3272 may be required to obtain an acceptable result. If a text script
3273 or part of the lyrics extends over the margins these checks will
3274 compress that line of the score just enough to fit within the
3277 To be effective under all circumstances these checks must be enabled
3278 by placing the overrides in a Score @code{\with} block, rather than
3279 in-line in music, as follows:
3283 % Makes sure text scripts and lyrics are within the paper margins
3284 \override PaperColumn #'keep-inside-line = ##t
3285 \override NonMusicalPaperColumn #'keep-inside-line = ##t
3291 @node Advanced tweaks with Scheme
3292 @subsection Advanced tweaks with Scheme
3294 Although many things are possible with the @code{\override} and
3295 @code{\tweak} commands, an even more powerful way of modifying
3296 the action of LilyPond is available through a programmable
3297 interface to the LilyPond internal operation. Code written in
3298 the Scheme programming language can be incorporated directly in
3299 the internal operation of LilyPond. Of course, at least a basic
3300 knowledge of programming in Scheme is required to do this, and an
3301 introduction is provided in the @ref{Scheme tutorial}.
3303 As an illustration of one of the many possibilities, instead of
3304 setting a property to a constant it can be set to a Scheme
3305 procedure which is then called whenever that property is accessed
3306 by LilyPond. The property can then be set dynamically to a value
3307 determined by the procedure at the time it is called. In this
3308 example we color the note head in accordance with its position on
3311 @lilypond[quote,verbatim,ragged-right]
3312 #(define (color-notehead grob)
3313 "Color the notehead according to its position on the staff."
3314 (let ((mod-position (modulo (ly:grob-property grob 'staff-position) 7)))
3316 ;; Return rainbow colors
3317 ((1) (x11-color 'red )) ; for C
3318 ((2) (x11-color 'orange )) ; for D
3319 ((3) (x11-color 'yellow )) ; for E
3320 ((4) (x11-color 'green )) ; for F
3321 ((5) (x11-color 'blue )) ; for G
3322 ((6) (x11-color 'purple )) ; for A
3323 ((0) (x11-color 'violet )) ; for B
3329 % Arrange to obtain color from color-notehead procedure
3330 \override NoteHead #'color = #color-notehead
3337 Some -- where o -- ver the Rain -- bow, way up high,
3341 Further examples showing the use of these programmable interfaces
3342 can be found in @ref{Tweaking with Scheme}.