5.4 Useful concepts and properties

5.4.1 Input modes

The way in which the notation contained within an input file is interpreted is determined by the current input mode. In general, there are two ways of specifying the mode: a long form, e.g. \chordmode, and a short form, e.g. \chords. The long form is typically used when supplying input to a variable or when entering input directly into an explicitly created context. The short form implicitly creates a context of the correct type for the input and passes the input directly to it. It is useful in simple situations when there is no requirement to explicitly create the receiving context.

Chord mode

This is activated with the \chordmode command, and causes input to be interpreted with the syntax of chord notation, see Chord notation. Music in chord mode is rendered as chords on a staff when entered into a Staff context, as chord names when entered into a ChordNames context or as fretboards when entered into a FretBoards context.

Chord mode is also activated with the \chords command. This also causes the following input to be interpreted with the syntax of chord notation but in addition it implicitly creates a new ChordNames context and renders the input into it as chord names, see Printing chord names.

Drum mode

This is activated with the \drummode command, and causes input to be interpreted with the syntax of drum notation, see Basic percussion notation. Music in drum mode is rendered as percussion notes when entered into a DrumStaff context.

Drum mode is also activated with the \drums command. This also causes the following input to be interpreted with the syntax of drum notation but in addition it implicitly creates a new DrumStaff context and renders the input into it as percussion notes, see Basic percussion notation.

Figure mode

This is activated with the \figuremode command, and causes input to be interpreted with the syntax of figured bass, see Entering figured bass. Music in figure mode is rendered as figured bass when entered into a FiguredBass context or a Staff context.

Figure mode is also activated with the \figures command. This also causes the following input to be interpreted with the figured bass syntax but in addition it implicitly creates a new FiguredBass context and renders the input into it as figured bass, see Introduction to figured bass.

Fret and tab modes

There are no special input modes for entering fret and tab symbols.

To create tab diagrams, enter notes or chords in note mode and render them in a TabStaff context, see Default tablatures.

To create fret diagrams above a staff, enter notes or chords in either note mode or chord mode and render them in a FretBoards context, see Automatic fret diagrams. Alternatively, fret diagrams can be entered as markup above the notes using the \fret-diagram command, see Fret diagram markups.

Lyrics mode

This is activated with the \lyricmode command, and causes input to be interpreted as lyric syllables with optional durations and associated lyric modifiers, see Vocal music. Input in lyric mode is rendered as lyric syllables when entered into a Lyrics context.

Lyric mode is also activated with the \lyrics command. This also causes the following input to be interpreted as lyric syllables but in addition it implicitly creates a new Lyrics context and renders the input into it as lyric syllables.

Lyric mode is also activated with the \addlyrics command. This also implicitly creates a new Lyrics context and in addition it adds an implicit \lyricsto command which associates the following lyrics with the preceding music, see Automatic syllable durations.

Markup mode

This is activated with the \markup command, and causes input to be interpreted with the syntax of markup, see Text markup commands.

Note mode

This is the default mode or it may be activated with the \notemode command. Input is interpreted as pitches, durations, markup, etc and typeset as musical notation on a staff.

It is not normally necessary to specify note mode explicitly, but it may be useful to do so in certain situations, for example if you are in lyric mode, chord mode or any other mode and want to insert something that only can be done with note mode syntax.

5.4.2 Direction and placement

In typesetting music the direction and placement of many items is a matter of choice. For example, the stems of notes can be directed up or down; lyrics, dynamics, and other expressive marks may be placed above or below the staff; text may be aligned left, right or center; etc. Most of these choices may be left to be determined automatically by LilyPond, but in some cases it may be desirable to force a particular direction or placement.

Articulation direction indicators

By default some directions are always up or always down (e.g., dynamics or fermata), while other things can alternate between up or down based on the stem direction (like slurs or accents).

The default action may be overridden by prefixing the articulation by a direction indicator. Three direction indicators are available: ^ (meaning “up”), _ (meaning “down”) and - (meaning “use default direction”). The direction indicator can usually be omitted, in which case - is assumed, but a direction indicator is always required before

• \tweak commands
• \markup commands
• \tag commands
• string markups, e.g., -"string"
• fingering instructions, e.g., -1
• articulation shortcuts, e.g., -., ->, --

Direction indicators affect only the next note:

\relative { c''2( c) c2_( c) c2( c) c2^( c) }

The direction property

The position or direction of many layout objects is controlled by the direction property.

The value of the direction property may be set to 1, meaning “up” or “above”, or to -1, meaning “down” or “below”. The symbols UP and DOWN may be used instead of 1 and -1 respectively. The default direction may be specified by setting direction to 0 or CENTER. Alternatively, in many cases predefined commands exist to specify the direction. These are of the form

\xxxUp, \xxxDown or \xxxNeutral

where \xxxNeutral means “use the default” direction. See (learning)Within-staff objects section ‘Within-staff objects’ in Learning Manual.

In a few cases, arpeggio for example, the value of the direction property can specify whether the object is to be placed to the right or left of the parent. In this case -1 or LEFT means “to the left” and 1 or RIGHT means “to the right”. 0 or CENTER means “use the default” direction.

These indications affect all notes until they are canceled.

\relative { c''2( c) \slurDown c2( c) c2( c) \slurNeutral c2( c) }

In polyphonic music, it is generally better to specify an explicit voice than change an object’s direction. For more information, see Multiple voices.

See also

Learning Manual: (learning)Within-staff objects section ‘Within-staff objects’ in Learning Manual.

Notation Reference: Multiple voices.

5.4.3 Distances and measurements

Distances in LilyPond are of two types: absolute and scaled.

Absolute distances are used for specifying margins, indents, and other page layout details, and are by default specified in millimeters. Distances may be specified in other units by following the quantity by \mm, \cm, \in (inches), or \pt (points, 1/72.27 of an inch). Page layout distances can also be specified in scalable units (see the following paragraph) by appending \staff-space to the quantity. Page layout is described in detail in Page layout.

Scaled distances are always specified in units of the staff-space or, rarely, the half staff-space. The staff-space is the distance between two adjacent staff lines. The default value can be changed globally by setting the global staff size, or it can be overridden locally by changing the staff-space property of StaffSymbol. Scaled distances automatically scale with any change to the either the global staff size or the staff-space property of StaffSymbol, but fonts scale automatically only with changes to the global staff size. The global staff size thus enables the overall size of a rendered score to be easily varied. For the methods of setting the global staff size see Setting the staff size.

If just a section of a score needs to be rendered to a different scale, for example an ossia section or a footnote, the global staff size cannot simply be changed as this would affect the entire score. In such cases the change in size is made by overriding both the staff-space property of StaffSymbol and the size of the fonts. A Scheme function, magstep, is available to convert from a font size change to the equivalent change in staff-space. For an explanation and an example of its use, see (learning)Length and thickness of objects section ‘Length and thickness of objects’ in Learning Manual.

See also

Learning Manual: (learning)Length and thickness of objects section ‘Length and thickness of objects’ in Learning Manual.

Notation Reference: Page layout, Setting the staff size.

5.4.4 Dimensions

The dimensions of a graphical object specify the positions of the left and right edges and the bottom and top edges of the objects’ bounding box as distances from the objects’ reference point in units of staff-spaces. These positions are usually coded as two Scheme pairs. For example, the text markup command \with-dimensions takes three arguments, the first two of which are a Scheme pair giving the left and right edge positions and a Scheme pair giving the bottom and top edge positions:

\with-dimensions #'(-5 . 10) #'(-3 . 15) arg

This specifies a bounding box for arg with its left edge at -5, its right edge at 10, its bottom edge at -3 and its top edge at 15, all measured from the objects’ reference point in units of staff-spaces.

See also

Notation Reference: Distances and measurements.

5.4.5 Staff symbol properties

The vertical position of staff lines and the number of staff lines can be defined at the same time. As the following example shows, note positions are not influenced by the staff line positions.

\new Staff \with { \override StaffSymbol.line-positions = #'(7 3 0 -4 -6 -7) } \relative { a4 e' f b | d1 }

The width of a staff can be modified. The units are staff spaces. The spacing of objects inside the staff is not affected by this setting.

\new Staff \with { \override StaffSymbol.width = #23 } \relative { a4 e' f b | d1 }

5.4.6 Spanners

Many objects of musical notation extend over several notes or even several bars. Examples are slurs, beams, tuplet brackets, volta repeat brackets, crescendi, trills, and glissandi. Such objects are collectively called “spanners”, and have special properties to control their appearance and behaviour. Some of these properties are common to all spanners; others are restricted to a sub-set of the spanners.

All spanners support the spanner-interface. A few, essentially those that draw a straight line between the two objects, support in addition the line-spanner-interface.

Using the spanner-interface

This interface provides two properties that apply to several spanners.

The minimum-length property

The minimum length of the spanner is specified by the minimum-length property. Increasing this usually has the necessary effect of increasing the spacing of the notes between the two end points. However, this override has no effect on many spanners, as their length is determined by other considerations. A few examples where it is effective are shown below.

a'~ a' a' % increase the length of the tie -\tweak minimum-length #5 ~ a'

\relative \compressMMRests { a'1 R1*23 % increase the length of the rest bar \once \override MultiMeasureRest.minimum-length = #20 R1*23 a1 }

\relative { a' \< a a a \! % increase the length of the hairpin \override Hairpin.minimum-length = #20 a \< a a a \! }

This override can also be used to increase the length of slurs and phrasing slurs:

\relative { a'( g) a -\tweak minimum-length #5 ( g) a\( g\) a -\tweak minimum-length #5 \( g\) }

For some layout objects, the minimum-length property becomes effective only if the set-spacing-rods procedure is called explicitly. To do this, the springs-and-rods property should be set to ly:spanner::set-spacing-rods. For example, the minimum length of a glissando has no effect unless the springs-and-rods property is set:

% default e' \glissando c'' % not effective alone \once \override Glissando.minimum-length = #20 e' \glissando c'' % effective only when both overrides are present \once \override Glissando.minimum-length = #20 \once \override Glissando.springs-and-rods = #ly:spanner::set-spacing-rods e' \glissando c''

The same is true of the Beam object:

% not effective alone \once \override Beam.minimum-length = #20 e'8 e' e' e' % effective only when both overrides are present \once \override Beam.minimum-length = #20 \once \override Beam.springs-and-rods = #ly:spanner::set-spacing-rods e'8 e' e' e'

The to-barline property

The second useful property of the spanner-interface is to-barline. By default this is true, causing hairpins and other spanners which are terminated on the first note of a measure to end instead on the immediately preceding bar line. If set to false, the spanner will extend beyond the bar line and end on the note itself:

\relative { a' \< a a a a \! a a a \break \override Hairpin.to-barline = ##f a \< a a a a \! a a a }

This property is not effective for all spanners. For example, setting it to #t has no effect on slurs or phrasing slurs or on other spanners for which terminating on the bar line would not be meaningful.

Using the line-spanner-interface

Objects which support the line-spanner-interface include

• DynamicTextSpanner
• Glissando
• TextSpanner
• TrillSpanner
• VoiceFollower

The routine responsible for drawing the stencils for these spanners is ly:line-spanner::print. This routine determines the exact location of the two end points and draws a line between them, in the style requested. The locations of the two end points of the spanner are computed on-the-fly, but it is possible to override their Y-coordinates. The properties which need to be specified are nested two levels down within the property hierarchy, but the syntax of the \override command is quite simple:

e''2 \glissando b' \once \override Glissando.bound-details.left.Y = #3 \once \override Glissando.bound-details.right.Y = #-2 e''2 \glissando b'

The units for the Y property are staff-spaces, with the center line of the staff being the zero point. For the glissando, this is the value for Y at the X-coordinate corresponding to the center point of each note head, if the line is imagined to be extended to there.

If Y is not set, the value is computed from the vertical position of the corresponding attachment point of the spanner.

In case of a line break, the values for the end points are specified by the left-broken and right-broken sub-lists of bound-details. For example:

\override Glissando.breakable = ##t \override Glissando.bound-details.right-broken.Y = #-3 c''1 \glissando \break f''1

A number of further properties of the left and right sub-lists of the bound-details property may be modified in the same way as Y:

Y

This sets the Y-coordinate of the end point, in staff-spaces offset from the staff center line. By default, it is the center of the bound object, so a glissando points to the vertical center of the note head.

For horizontal spanners, such as text spanners and trill spanners, it is hardcoded to 0.

attach-dir

This determines where the line starts and ends in the X-direction, relative to the bound object. So, a value of -1 (or LEFT) makes the line start/end at the left side of the note head it is attached to.

X

This is the absolute X-coordinate of the end point. It is usually computed on the fly, and overriding it has little useful effect.

stencil

Line spanners may have symbols at the beginning or end, which is contained in this sub-property. This is for internal use; it is recommended that text be used instead.

text

This is a markup that is evaluated to yield the stencil. It is used to put cresc., tr and other text on horizontal spanners.

\override TextSpanner.bound-details.left.text = \markup { \small \bold Slower } \relative { c''2\startTextSpan b c a\stopTextSpan }

stencil-align-dir-y

stencil-offset

Without setting one of these, the stencil is simply put at the end-point, centered on the line, as defined by the X and Y sub-properties. Setting either stencil-align-dir-y or stencil-offset will move the symbol at the edge vertically relative to the end point of the line:

\override TextSpanner.bound-details.left.stencil-align-dir-y = #-2 \override TextSpanner.bound-details.right.stencil-align-dir-y = #UP \override TextSpanner.bound-details.left.text = "ggg" \override TextSpanner.bound-details.right.text = "hhh" \relative { c'4^\startTextSpan c c c \stopTextSpan }

Note that negative values move the text up, contrary to the effect that might be expected, as a value of -1 or DOWN means align the bottom edge of the text with the spanner line. A value of 1 or UP aligns the top edge of the text with the spanner line.

arrow

Setting this sub-property to #t produces an arrowhead at the end-points of the line.

padding

This sub-property controls the space between the specified end point of the line and the actual end. Without padding, a glissando would start and end in the center of each note head.

The music function \endSpanners terminates the spanner which starts on the immediately following note prematurely. It is terminated after exactly one note, or at the following bar line if to-barline is true and a bar line occurs before the next note.

\relative c'' { \endSpanners c2 \startTextSpan c2 c2 \endSpanners c2 \< c2 c2 }

When using \endSpanners it is not necessary to close \startTextSpan with \stopTextSpan, nor is it necessary to close hairpins with \!.

See also

Internals Reference: (internals)TextSpanner section ‘TextSpanner’ in Internals Reference, (internals)Glissando section ‘Glissando’ in Internals Reference, (internals)VoiceFollower section ‘VoiceFollower’ in Internals Reference, (internals)TrillSpanner section ‘TrillSpanner’ in Internals Reference, (internals)line-spanner-interface section ‘line-spanner-interface’ in Internals Reference.

5.4.7 Visibility of objects

There are four main ways in which the visibility of layout objects can be controlled: their stencil can be removed, they can be made transparent, they can be colored white, or their break-visibility property can be overridden. The first three apply to all layout objects; the last to just a few – the breakable objects. The Learning Manual introduces these four techniques, see (learning)Visibility and color of objects section ‘Visibility and color of objects’ in Learning Manual.

There are also a few other techniques which are specific to certain layout objects. These are covered under Special considerations.

Removing the stencil

Every layout object has a stencil property. By default this is set to the specific function which draws that object. If this property is overridden to #f no function will be called and the object will not be drawn. The default action can be recovered with \revert.

a1 a \override Score.BarLine.stencil = ##f a a \revert Score.BarLine.stencil a a a

This rather common operation has a shortcut \omit:

a1 a \omit Score.BarLine a a \undo \omit Score.BarLine a a a

Making objects transparent

Every layout object has a transparent property which by default is set to #f. If set to #t the object still occupies space but is made invisible.

a'4 a' \once \override NoteHead.transparent = ##t a' a'

This rather common operation has a shortcut \hide:

a'4 a' \once \hide NoteHead a' a'

Painting objects white

Every layout object has a color property which by default is set to black. If this is overridden to white the object will be indistinguishable from the white background. However, if the object crosses other objects the color of the crossing points will be determined by the order in which they are drawn, and this may leave a ghostly image of the white object, as shown here:

\override Staff.Clef.color = #white a'1

This may be avoided by changing the order of printing the objects. All layout objects have a layer property which should be set to an integer. Objects with the lowest value of layer are drawn first, then objects with progressively higher values are drawn, so objects with higher values overwrite objects with lower values. By default most objects are assigned a layer value of 1, although a few objects, including StaffSymbol and BarLine, are assigned a value of 0. The order of printing objects with the same value of layer is indeterminate.

In the example above the white clef, with a default layer value of 1, is drawn after the staff lines (default layer value 0), so overwriting them. To change this, the Clef object must be given in a lower value of layer, say -1, so that it is drawn earlier:

\override Staff.Clef.color = #white \override Staff.Clef.layer = #-1 a'1

Using break-visibility

Most layout objects are printed only once, but some like bar lines, clefs, time signatures and key signatures, may need to be printed twice when a line break occurs – once at the end of the line and again at the start of the next line. Such objects are called breakable, and have a property, the break-visibility property to control their visibility at the three positions in which they may appear – at the start of a line, within a line if they are changed, and at the end of a line if a change takes place there.

For example, the time signature by default will be printed at the start of the first line, but nowhere else unless it changes, when it will be printed at the point at which the change occurs. If this change occurs at the end of a line the new time signature will be printed at the start of the next line and a cautionary time signature will be printed at the end of the previous line as well.

This behaviour is controlled by the break-visibility property, which is explained in (learning)Visibility and color of objects section ‘Visibility and color of objects’ in Learning Manual. This property takes a vector of three booleans which, in order, determine whether the object is printed at the end of, within the body of, or at the beginning of a line. Or to be more precise, before a line break, where there is no line break, or after a line break.

Alternatively, these eight combinations may be specified by pre-defined functions, defined in ‘scm/output-lib.scm’, where the last three columns indicate whether the layout objects will be visible in the positions shown at the head of the columns:

The default settings of break-visibility depend on the layout object. The following table shows all the layout objects of interest which are affected by break-visibility and the default setting of this property:

The example below shows the use of the vector form to control the visibility of bar lines:

\relative { f'4 g a b f4 g a b % Remove bar line at the end of the current line \once \override Score.BarLine.break-visibility = ##(#f #t #t) \break f4 g a b f4 g a b }

Although all three components of the vector used to override break-visibility must be present, not all of them are effective with every layout object, and some combinations may even give errors. The following limitations apply:

• Bar lines cannot be printed at the start of line.
• A bar number cannot be printed at the start of the first line unless it is set to be different from 1.
• Clef – see the next section.
• Double percent repeats are either all printed or all suppressed. Use begin-of-line-invisible to print them and all-invisible to suppress them.
• Key signature – see the next section.
• ClefModifier – see the next section.

Special considerations

Visibility following explicit changes

The break-visibility property controls the visibility of key signatures and changes of clef only at the start of lines, i.e., after a break. It has no effect on the visibility of the key signature or clef following an explicit key change or an explicit clef change within or at the end of a line. In the following example the key signature following the explicit change to B-flat major is still visible, even though all-invisible is set.

\relative { \key g \major f'4 g a b % Try to remove all key signatures \override Staff.KeySignature.break-visibility = #all-invisible \key bes \major f4 g a b \break f4 g a b f4 g a b }

The visibility of such explicit key signature and clef changes is controlled by the explicitKeySignatureVisibility and explicitClefVisibility properties. These are the equivalent of the break-visibility property and both take a vector of three booleans or the predefined functions listed above, exactly like break-visibility. Both are properties of the Staff context, not the layout objects themselves, and so they are set using the \set command. Both are set by default to all-visible. These properties control only the visibility of key signatures and clefs resulting from explicit changes and do not affect key signatures and clefs at the beginning of lines; break-visibility must still be overridden in the appropriate object to remove these.

\relative { \key g \major f'4 g a b \set Staff.explicitKeySignatureVisibility = #all-invisible \override Staff.KeySignature.break-visibility = #all-invisible \key bes \major f4 g a b \break f4 g a b f4 g a b }

Visibility of cancelling accidentals

To remove the cancelling accidentals printed at an explicit key change, set the Staff context property printKeyCancellation to #f:

\relative { \key g \major f'4 g a b \set Staff.explicitKeySignatureVisibility = #all-invisible \set Staff.printKeyCancellation = ##f \override Staff.KeySignature.break-visibility = #all-invisible \key bes \major f4 g a b \break f4 g a b f4 g a b }

With these overrides only the accidentals before the notes remain to indicate the change of key.

Note that when changing the key to C major or A minor the cancelling accidentals would be the only indication of the key change. In this case setting printKeyCancellation to #f has no effect:

\relative { \key g \major f'4 g a b \set Staff.explicitKeySignatureVisibility = #all-invisible \set Staff.printKeyCancellation = ##f \key c \major f4 g a b \break f4 g a b f4 g a b }

To suppress the cancelling accidentals even when the key is changed to C major or A minor, override the visibility of the KeyCancellation grob instead:

\relative { \key g \major f'4 g a b \set Staff.explicitKeySignatureVisibility = #all-invisible \override Staff.KeyCancellation.break-visibility = #all-invisible \key c \major f4 g a b \break f4 g a b f4 g a b }

Automatic bars

As a special case, the printing of bar lines can also be turned off by setting the automaticBars property in the Score context. If set to #f, bar lines will not be printed automatically; they must be explicitly created with a \bar command. Unlike the \cadenzaOn predefined command, measures are still counted. Bar generation will resume according to that count if this property is later set to #t. When set to #f, line breaks can occur only at explicit \bar commands.

Transposed clefs

The small transposition symbol on transposed clefs is produced by the ClefModifier layout object. Its visibility is automatically inherited from the Clef object, so it is not necessary to apply any required break-visibility overrides to the ClefModifier layout objects to suppress transposition symbols for invisible clefs.

For explicit clef changes, the explicitClefVisibility property controls both the clef symbol and any transposition symbol associated with it.

See also

Learning Manual: (learning)Visibility and color of objects section ‘Visibility and color of objects’ in Learning Manual.

5.4.8 Line styles

Some performance indications, e.g., rallentando and accelerando and trills are written as text and are extended over many measures with lines, sometimes dotted or wavy.

These all use the same routines as the glissando for drawing the texts and the lines, and tuning their behavior is therefore also done in the same way. It is done with a spanner, and the routine responsible for drawing the spanners is ly:line-spanner::print. This routine determines the exact location of the two span points and draws a line between them, in the style requested.

Here is an example showing the different line styles available, and how to tune them.

\relative { d''2 \glissando d'2 \once \override Glissando.style = #'dashed-line d,2 \glissando d'2 \override Glissando.style = #'dotted-line d,2 \glissando d'2 \override Glissando.style = #'zigzag d,2 \glissando d'2 \override Glissando.style = #'trill d,2 \glissando d'2 }

The locations of the end-points of the spanner are computed on-the-fly for every graphic object, but it is possible to override these:

\relative { e''2 \glissando f \once \override Glissando.bound-details.right.Y = #-2 e2 \glissando f }

The value for Y is set to -2 for the right end point. The left side may be similarly adjusted by specifying left instead of right.

If Y is not set, the value is computed from the vertical position of the left and right attachment points of the spanner.

Other adjustments of spanners are possible, for details, see Spanners.

5.4.9 Rotating objects

Both layout objects and elements of markup text can be rotated by any angle about any point, but the method of doing so differs.

Rotating layout objects

All layout objects which support the grob-interface can be rotated by setting their rotation property. This takes a list of three items: the angle of rotation counter-clockwise, and the x and y coordinates of the point relative to the object’s reference point about which the rotation is to be performed. The angle of rotation is specified in degrees and the coordinates in staff-spaces.

The angle of rotation and the coordinates of the rotation point must be determined by trial and error.

There are only a few situations where the rotation of layout objects is useful; the following example shows one situation where they may be:

g4\< e' d'' f''\! \override Hairpin.rotation = #'(15 -1 0) g4\< e' d'' f''\!

Rotating markup

All markup text can be rotated to lie at any angle by prefixing it with the \rotate command. The command takes two arguments: the angle of rotation in degrees counter-clockwise and the text to be rotated. The extents of the text are not rotated: they take their values from the extremes of the x and y coordinates of the rotated text. In the following example the outside-staff-priority property for text is set to #f to disable the automatic collision avoidance, which would push some of the text too high.

\override TextScript.outside-staff-priority = ##f g4^\markup { \rotate #30 "a G" } b^\markup { \rotate #30 "a B" } des'^\markup { \rotate #30 "a D-Flat" } fis'^\markup { \rotate #30 "an F-Sharp" }

This document was generated by gub on July 13, 2020 using texi2html 1.82.

Jiné jazyky: català, deutsch, español, français, italiano, 日本語.
O automatickém výběru řeči.