[icon]

GNU LilyPond

-- --

What is LilyPond
Home
Examples
Templates
Download
GNU/Linux binaries
Windows binaries
Source code
Documentation
Tutorial
Manual
Glossary
Index

Support
Mailing lists
Search
WikiWiki

External sites
lilypond.org/stable
lilypond.org/development
savannah.gnu.org
ftp.lilypond.org
Mutopia
Other music online

Fine tuning a piece

In this section we show some ways to fine tune the final output of a piece. We do so using a single measure of a moderately complex piano piece: a Brahms intermezzo (opus 119, no. 1). Both fragments (the tuned and the untuned versions) are in input/tutorial/.

The code for the untuned example shows us some new things.

     \version "1.7.6"
     \score {
         \notes\context PianoStaff <
         \context Staff = up
         \relative c'' <
             {   \key d\major
                 fis4-3_\p-(-~
                 fis16 a-)-5 } \\
             {
                 fis16-(-\> d b-\! \translator Staff = down
                 \clef treble g-~ <<g e>>8-) } \\
             { s16
               d'
               ~ <<d b>>4 }
         >
         \context Staff = down {
             \key d \major
             \time 3/8 \clef bass s4. }
         >
         \paper { linewidth = -1. }
     }
     
     %% new-chords-done %%
     
     
     
[picture of music]

Hairpin dynamics can be easily added to Lilypond scores. Beginning a crescendo is indicated with \< and ending a crescendo is indicated with \!. A decrescendo can be indicated with \> and \!. Absolute dynamics (sometimes called "Letter dynamics") can be entered using \p, \mf, etc. All these dynamics will apply to the whole chord where they are entered, but for syntactical reasons they must be attached to one of the notes of the chord.

Fingering indications are entered with -N, where N is a digit.

Now that we have the basic piece of music entered, we want to fine tune it so that we get something that resembles the original printed edition by Schott/Universal Edition:

[picture of music]

Fine tuning involves overriding the defaults of the printing system. We do this by setting variables which control how Lilypond prints symbols. Printed symbols are called graphical objects (often abbreviated to grob). Each object is described by a bunch of settings. Every setting is a variable: it has a name and a value which you can change. These values determine the fonts, offsets, sub-routines to be called on the object, etc. The initial values of these settings are set in the Scheme file scm/grob-description.scm.

We start with the slur in the upper part, running from F sharp to A. In the printed edition, this slur runs from stem to stem; in our version, the slur begins at the note head of the F sharp. The following property setting forces all slurs to run from stem to stem (not from or to note heads!).

       \property Voice.Slur \set #'attachment = #'(stem . stem)
     

More precisely, this command modifies the definition of the Slur object in the current Voice. The variable attachment is set to the pair of symbols '(stem . stem).

Although this fixes the slur, it isn't very helpful for fine tuning in general: the lilypond back-end supports approximately 240 variables like attachment, each with their own meaning and own type (eg. number, symbol, list, etc). Besides slur, LilyPond has 80 different types of graphical objects, that may be created in 14 different context types besides Voice.

The interesting information is how you can figure out which properties to tune for your own scores. To discover this, you must have a copy of the internals document. This is a set of HTML pages which should be included if you installed a binary distribution1. These HTML pages are also available on the web: go to the lilypond website, click "Documentation: Index" on the side bar, look in the "Information for uses" section, and click on "Documentation of internals".

You might want to bookmark either the HTML files on your disk, or the one on the web (the HTML on your hard drive will load much faster than the ones on the web!). One word of caution: the internals documentation is generated from the definitions that lily uses. For that reason, it is strongly tied to the version of LilyPond that you use. Before you proceed, please make sure that you are using the documentation that corresponds to the version of LilyPond that you are using.

Suppose that you wanted to tune the behavior of the slur. The first step is to get some general information on slurs in lilypond. Turn to the index, and look up "slur". The section on slurs says

The grob for this object is Slur , generally in Voice context.

So the graphical object for this object is called Slur, and slurs are created in the Voice context. If you are reading this tutorial in the HTML version, then you can simply click Slur, otherwise, you should look it up the internal documentation: click "grob overview" and select "slur" (the list is alphabetical).

Now you get a list of all the properties that the slur object supports, along with their default values. Among the properties we find the attachment property with its default setting. The property documentation explains that the following setting will produce the desired effect:

      \property Voice.Slur \set #'attachment = #'(stem . stem)
     

If you ran the previous example, you have unknowingly already used this kind of command. The ly/property-init.ly contains the definition of \stemUp:

       stemUp = \property Voice.Stem \set #'direction = #1
     



Next we want to move the fingering `3'. In the printed edition it is not above the stem, but a little lower and slightly left of the stem. From the user manual we find that the associated graphical object is called Fingering, but how do we know if we should use Voice or Staff? In many cases, Voice is a safe bet, but you can also deduce this information from the internals documentation: if you visit the documentation of Fingering, you will notice

     Fingering grobs are created by: Fingering_engraver
     

Clicking Fingering_engraver will show you the documentation of the module responsible for interpreting the fingering instructions and translating them to a Fingering object. Such a module is called an engraver. The documentation of the Fingering_engraver says

     Fingering_engraver is part of contexts: Voice and TabVoice
     
so tuning the settings for Fingering should be done using either
       \property Voice.Fingering \set ...
     
or
       \property TabVoice.Fingering \set ...
     

Since the TabVoice is only used for tab notation, we see that the first guess Voice was indeed correct.

For shifting the fingering, we use the property extra-offset. The following command manually adds an offset to the object. We move it a little to the left, and 1.8 staff space downwards.

      \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8)
     
The extra-offset is a low-level feature: it moves around objects in the printout; the formatting engine is completely oblivious to these offsets. The unit of these offsets are staff-spaces. The first number controls left-right movement; a positive number will move the object to the right. The second number controls up-down movement; a positive number will move it higher.

We only want to offset a single object, so after the F-sharp we must undo the setting. The technical term is to revert the property.

       \property Voice.Fingering \revert #'extra-offset
     



There are three different types of variables in LilyPond, something which can be confusing at first (and for some people it stays confusing :). Variables such as extra-offset and attachment are called grob properties. They are not the same as translator properties, like autoBeaming. Finally, music expressions are internally stored using properties (so-called music properties). You will encounter music properties if you run Scheme functions on music using \apply.

The second fingering instruction should be moved up a little to avoid a collision with the slur. This could be achieved with extra-offset, but in this case, a simpler mechanism also works. We insert an empty text between the 5 and the note. The empty text pushes the fingering instruction away:

       a-)^" "^\markup { \finger "5" }
     

A fingering instruction, which would be entered as ^5, is put as close to the notes as possible, closer than the space entered to push away the 5. Hence, the 5 is entered as a normal text, formatting of fingering instructions.



Normally one would specify all dynamics in the same voice, so that dynamics (such as f and p) will be aligned with hairpins. But in this case, we don't want the decrescendo to be aligned with the piano sign. We achieve this by putting the dynamic markings in different voices. The crescendo should be above the upper staff. This can be forced by using the precooked command

       \dynamicsUp
     

However, if you do that the decrescendo will be too close to the upper voice and collide with the stems. Looking at the manual for dynamics, we notice that "Vertical positioning of these symbols is handled by the DynamicLineSpanner grob.". If we turn to the documentation of DynamicLineSpanner, we find that DynamicLineSpanner supports several so-called `interfaces'. This object not only puts dynamic objects next to the staff (side-position-interface), but it also groups dynamic objects (axis-group-interface), is considered a dynamic sign itself (dynamic-interface), and is an object. It has the standard grob-interface with all the variables that come with it.

For the moment we are interested in side positioning:

side-position-interface

Position a victim object (this one) next to other objects (the support). In this case, the direction signifies where to put the victim object relative to the support (left or right, up or down?)

Between the object and its support (in this case the notes in the voice going down), there should be more space. This space is controlled by padding, so we increase it.
     \property Voice.DynamicLineSpanner \override #'padding = #5.0
     

This command is almost like the command for setting slur attachments, but subtly different in its details. Grob properties can be manipulated with two commands: \override extends the variables with a setting, and \revert releases this setting. This has a certain theoretical appeal: the operations are simple and symmetric. But for practical use, it can be cumbersome. The commands act like parentheses: you should carefully balance the use of \override and \revert. The \set command is more friendly: it first does a \revert followed by \override.



Brahms uses music notation is a slightly unorthodox way. Ties usually happen only within one voice. In this piece, the composer gladly produces ties that jump voices. We deal with this by faking these ties: whenever we need such a tie, we insert a notehead in a different voice, and blank the stem. This is done in the following snippet of code.

     \property Voice.Stem \set #'transparent = ##t
     d'
     
Blanking the stem should be done for only one object. One of the ways to achieve that, is by setting the property before a note. Reverting it afterwards is tedious, so for setting a property only once, we have the syntax \once: it reverts the property directly before proceeding to the next step in time.

The \once keyword is added to \property.

Finally, the last tie is forced up using \tieUp.



Here's the complete "fine tuned" version, which includes all the modifications we discussed in this section:

     \version "1.7.6"
     \score {
         \notes\context PianoStaff <
         \context Staff = up
         \relative c'' <
             {   \key d\major
                 \property Voice.Slur \set #'attachment = #'(stem . stem)
     
                 \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8)
                fis4-3_\p-(-~
     
     
                 \property Voice.Fingering \revert #'extra-offset
                 fis16 a-)^" "^\markup { \finger "5" } } \\
             {
                 \dynamicUp
                 \property Voice.DynamicLineSpanner \override #'padding = #5.0
                 \tieUp
                 fis16-(-\> d b-\! \translator Staff = down
     	    \stemUp
     	    \clef treble g-~ <<g e>>8-) } \\
             { s16
     	  \property Voice.Stem \set #'transparent = ##t
               d'
               \property Voice.Stem \revert #'transparent
               ~ <<d b>>4 }
         >
         \context Staff = down {
             \key d \major
             \time 3/8 \clef bass s4. }
         >
         \paper { linewidth = -1. }
     }
     
     
     %% new-chords-done %%
     
     
[picture of music]

Footnotes

  1. You can also compile them by executing make -C Documentation/user/ out/lilypond-internals.html in the source package.


Go back to index of LilyPond.

Please send GNU LilyPond questions and comments to lilypond-user@gnu.org.

Please send comments on these web pages to (address unknown)

Copyright (c) 1997--2002 Han-Wen Nienhuys and Jan Nieuwenhuizen.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.


This page was built from LilyPond-1.7.14 (development-branch) by

Buchan Milne <(address unknown)>, Thu Mar 6 21:11:35 2003 CET.