LilyPond Notation Reference: 1.7.1 Inside the staff

[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Editorial annotations ]	[ Up : Editorial annotations ]	[ Selecting notation font size > ]

1.7.1 Inside the staff

This section discusses how to add emphasis to elements that are inside the staff.

[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Inside the staff ]	[ Up : Inside the staff ]	[ Fingering instructions > ]

Selecting notation font size

Note:
For font sizes of text, see Selecting font and font size.
For staff size, see Setting the staff size.
For cue notes, see Formatting cue notes.
For ossia staves, see Ossia staves.

To change the size of the notation without changing the staff size, specify a magnification factor with the \magnifyMusic command:

\new Staff <<
  \new Voice \relative {
    \voiceOne
    <e' e'>4 <f f'>8. <g g'>16 <f f'>8 <e e'>4 r8
  }
  \new Voice \relative {
    \voiceTwo
    \magnifyMusic 0.63 {
      \override Score.SpacingSpanner.spacing-increment = #(* 1.2 0.63)
      r32 c'' a c a c a c r c a c a c a c
      r c a c a c a c a c a c a c a c
    }
  }
>>

The \override in the example above is a bug workaround. See the “Known issues and warnings” at the end of this section.

If a normal sized note head is merged with a smaller one, the size of the smaller note may need to be reset (with ‘\once \normalsize’) so that the stems and accidentals align properly:

\new Staff <<
  \key fis \minor
  \mergeDifferentlyDottedOn
  \new Voice \relative {
    \voiceOne
    \magnifyMusic 0.63 {
      \override Score.SpacingSpanner.spacing-increment =
        #(* 1.2 0.63)

      \once \normalsize cis'32( cis' gis b a fis
        \once \normalsize d d'
      \once \normalsize cis, cis' gis b a gis
        \once \normalsize fis fis'
      \once \normalsize fis, fis' ais, cis b gis
        \once \normalsize eis eis'
      \once \normalsize a, a' bis, d cis b
        \once \normalsize gis gis')
    }
  }
  \new Voice \relative {
    \voiceTwo
    cis'8. d16 cis8. fis16 fis8. eis16 a8. gis16
  }
>>

The \magnifyMusic command is not intended for cue notes, grace notes, or ossia staves—there are more appropriate methods of entering each of those constructs. Instead, it is useful when the notation size changes in a single instrumental part on one staff, and where grace notes are not appropriate, such as in cadenza-like passages or in cases such as the above examples. Setting the \magnifyMusic value to 0.63 duplicates the dimensions of the CueVoice context.

Note: The \magnifyMusic command should not be used when also resizing the staff. See Setting the staff size.

Resizing individual layout objects

An individual layout object can be resized by using the \tweak or \override commands to adjust its font-size property:

\relative {
  % resize a note head
  <f' \tweak font-size -4 b e>-5
  % resize a fingering
  bes-\tweak font-size 0 -3
  % resize an accidental
  \once \override Accidental.font-size = -4 bes!-^
  % resize an articulation
  \once \override Script.font-size = 4 bes!-^
}

The default font-size value for each layout object is listed in the Internals Reference. The font-size property can only be set for layout objects that support the font-interface layout interface. If font-size is not specified in the object’s ‘Standard settings’ list, its value is 0. See All layout objects.

Understanding the `fontSize` property

The fontSize context property adjusts the relative size of all glyph-based notational elements in a context:

\relative {
  \time 3/4
  d''4---5 c8( b a g) |
  \set fontSize = -6
  e'4-- c!8-4( b a g) |
  \set fontSize = 0
  fis4---3 e8( d) fis4 |
  g2.
}

The fontSize value is a number indicating the size relative to the standard size for the current staff height. The default fontSize is 0; adding 6 to any fontSize value doubles the printed size of the glyphs, and subtracting 6 halves the size. Each step increases the size by approximately 12%.

The scheme function magnification->font-size is provided for convenience since the logarithmic units of the font-size property are not entirely intuitive. For example, to adjust the musical notation to 75% of the default size, use:

\set fontSize = #(magnification->font-size 0.75)

The scheme function magstep does the opposite: it converts a font-size value into a magnification factor.

The fontSize property will only affect notational elements that are drawn with glyphs, such as note heads, accidentals, scripts, etc. It will not affect the size of the staff itself, nor will it scale stems, beams, or horizontal spacing. To scale stems, beams, and horizontal spacing along with the notation size (without changing the staff size), use the \magnifyMusic command discussed above. To scale everything, including the staff size, see Setting the staff size.

Whenever the fontSize context property is set, its value is added to the value of the font-size grob property for individual layout objects, before any glyphs are printed. This can cause confusion when setting individual font-size properties while fontSize is already set:

% the default font-size for NoteHead is 0
% the default font-size for Fingering is -5
c''4-3

\set fontSize = -3
% the effective font size for NoteHead is now -3
% the effective font size for Fingering is now -8
c''4-3

\override Fingering.font-size = 0
% the effective font size for Fingering is now -3
c''4-3

The following shorthand commands are also available:

Command	Equivalent to	Relative size
`\teeny`	`\set fontSize = -3`	71%
`\tiny`	`\set fontSize = -2`	79%
`\small`	`\set fontSize = -1`	89%
`\normalsize`	`\set fontSize = 0`	100%
`\large`	`\set fontSize = 1`	112%
`\huge`	`\set fontSize = 2`	126%

\relative c'' {
  \teeny
  c4.-> d8---3
  \tiny
  c4.-> d8---3
  \small
  c4.-> d8---3
  \normalsize
  c4.-> d8---3
  \large
  c4.-> d8---3
  \huge
  c4.-> d8---3
}

Font size changes are achieved by scaling the design size that is closest to the desired size. The standard font size (for font-size = 0) depends on the standard staff height. For a 20pt staff, an 11pt font is selected.

Predefined commands

\magnifyMusic, \teeny, \tiny, \small, \normalsize, \large, \huge.

Known issues and warnings

There are currently two bugs that are preventing proper horizontal spacing when using \magnifyMusic. There is only one available workaround, and it is not guaranteed to work in every case. In the example below, replace the mag variable with your own value. You may also try removing one or both of the \newSpacingSection commands, and/or the \override and \revert commands:

\magnifyMusic mag {
  \newSpacingSection
  \override Score.SpacingSpanner.spacing-increment = #(* 1.2 mag)
  [music]
  \newSpacingSection
  \revert Score.SpacingSpanner.spacing-increment
}

[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Selecting notation font size ]	[ Up : Inside the staff ]	[ Gliding fingers > ]

Fingering instructions

Fingering instructions can be entered using ‘note-digit’:

\relative { c''4-1 d-2 f-4 e-3 }

Markup texts or strings may be used for finger changes.

\relative {
  c''4-1 d-2 f\finger \markup \tied-lyric "4~3" c\finger "2 - 3"
}

A thumb fingering can be added (e.g., cello music) to indicate that a note should be played with the thumb.

\relative { <a'_\thumb a'-3>2 <b_\thumb b'-3> }

Fingerings for chords can also be added to individual notes by adding them after the pitches.

\relative {
  <c''-1 e-2 g-3 b-5>2 <d-1 f-2 a-3 c-5>
}

Fingering instructions may be manually placed above or below the staff, see Direction and placement.

Selected Snippets

Controlling the placement of chord fingerings

The placement of fingering numbers can be controlled precisely. For fingering orientation to apply, it must be used within a chord construct <>, even for single notes. Orientation for string numbers and right-hand fingerings may be set in a similar way.

\relative c' {
  \set fingeringOrientations = #'(left)
  <c-1 e-3 a-5>4
  \set fingeringOrientations = #'(down)
  <c-1 e-3 a-5>4
  \set fingeringOrientations = #'(down right up)
  <c-1 e-3 a-5>4
  \set fingeringOrientations = #'(up)
  <c-1 e-3 a-5>4
  \set fingeringOrientations = #'(left)
  <c-1>2
  \set fingeringOrientations = #'(down)
  <e-3>2
  \set stringNumberOrientations = #'(up left down)
  <f\3 a\2 c\1>1
  \set strokeFingerOrientations = #'(down right up)
  <c\rightHandFinger #1 e\rightHandFinger #2 c'\rightHandFinger #4 >
}

Allowing fingerings to be printed inside the staff

By default, vertically oriented fingerings are positioned outside the staff; that behavior, however, may be disabled. Attention needs to be paid to situations where fingerings and stems are in the same direction: by default, fingerings will avoid only beamed stems. That setting can be changed to avoid no stems or all stems; the following example demonstrates these two options, as well as how to go back to the default behavior.

\relative c' {
  <c-1 e-2 g-3 b-5>2
  \override Fingering.staff-padding = #'()
  <c-1 e-2 g-3 b-5>4 g'-0
  a8[-1 b]-2 g-0 r
  \override Fingering.add-stem-support = ##f
  a[-1 b]-2 g-0 r
  \override Fingering.add-stem-support = ##t
  a[-1 b]-2 g-0 r
  \override Fingering.add-stem-support = #only-if-beamed
  a[-1 b]-2 g-0 r
}

Gliding fingers

For stringed instruments a gliding finger is often indicated by a line connecting the same finger to be used for notes played at different positions on the same string. This line is initiated with \\glide entered before a Fingering and ends with the next occurence of the same finger. The line may be printed in various styles.

mus = {
  \set fingeringOrientations = #'(right)
  <a'\glide-1>2.
  \set fingeringOrientations = #'(left)
  <d'-1>4
}

{
  <>^"line"
  \mus
  <>^"stub-left"
  \override FingerGlideSpanner.style = #'stub-left
  \mus
  <>^"stub-right"
  \override FingerGlideSpanner.style = #'stub-right
  \mus
  <>^"stub-both"
  \override FingerGlideSpanner.style = #'stub-both
  \mus
  <>^"dashed-line"
  \override  FingerGlideSpanner.style = #'dashed-line
  \mus
  \break
  <>^"dotted-line"
  \override FingerGlideSpanner.style = #'dotted-line
  \mus
  <>^"bow"
  \override FingerGlideSpanner.style = #'bow
  \mus
  <>^"trill"
  \override FingerGlideSpanner.style = #'trill
  \mus
  <>^"zigzag"
  \override FingerGlideSpanner.style = #'zigzag
  \mus
}

If style is set to 'bow the direction of the bow may be adjusted using direction modifiers.

{
  \override FingerGlideSpanner.style = #'bow
  \set fingeringOrientations = #'(down)
  <b\glide-1>4 <d'-1>
  \set fingeringOrientations = #'(up)
  <e''\glide-2> <c''-2>

  \set fingeringOrientations = #'(down)
  <b^\glide-1>4 <d'-1>
  \set fingeringOrientations = #'(up)
  <e''^\glide-2> <c''-2>

  \set fingeringOrientations = #'(down)
  <b_\glide-1>4 <d'-1>
  \set fingeringOrientations = #'(up)
  <e''_\glide-2> <c''-2>
}

If the Finger_glide_engraver is moved to Staff context Fingering grobs from different Voice contexts may be connected.

\score {
  \new Staff <<
    \new Voice {
      \voiceOne
      \set fingeringOrientations = #'(right)
      <e''-3>2
      \set fingeringOrientations = #'(left)
      <d''-\tweak bound-details.left.padding #2.5 \glide-2>
      <c''-2>
      \bar "||"
    }
    \new Voice {
      \voiceTwo
      \set fingeringOrientations = #'(right)
      <c''\glide-2>
      \set fingeringOrientations = #'(left)
      <b'-\tweak bound-details.left.padding #2.5 \glide-4>
      <a'-4>
    }
  >>
  \layout {
    ragged-right = ##f
    \context {
      \Voice
      \remove Finger_glide_engraver
    }
    \context {
      \Staff
      \consists Finger_glide_engraver
    }
  }
}

Known issues and warnings

Multiple glides with the same finger are not supported and lead to unexpected results. A workaround is to use different fingers and to use \tweak text.

{
    \clef "G_8"
    <a\glide-1 cis'\glide-1>2 <bes-1 d'-1>
    <a\glide-1 cis'\glide-\tweak text "1"-2>2
    <bes-1 d'-\tweak text "1"-2>
}

[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Gliding fingers ]	[ Up : Inside the staff ]	[ Coloring objects > ]

Hidden notes

Hidden (or invisible or transparent) notes can be useful in preparing theory or composition exercises.

\relative {
  c''4 d
  \hideNotes
  e4 f
  \unHideNotes
  g a
  \hideNotes
  b
  \unHideNotes
  c
}

Note heads, stems, and flags, and rests are invisible. Beams are invisible if they start on a hidden note. Objects that are attached to invisible notes are still visible.

\relative c'' {
  e8(\p f g a)--
  \hideNotes
  e8(\p f g a)--
}

Predefined commands

\hideNotes, \unHideNotes.

Coloring objects

Individual objects may be assigned colors. Valid color names are listed in the List of colors.

\override NoteHead.color = #red
c''4 c''
\override NoteHead.color = #(x11-color 'SlateGrey)
d''
\override Stem.color = "deepskyblue"
e''

In addition to a limited set of simple colors available as predefined variables (see ‘Normal colors’ in List of colors), any color may be entered as a string. That string may be either a CSS-style predefined color name, or a hexadecimal color code prefixed by the # character (inside the double quotes):

\override NoteHead.color = "lightsalmon"
\override Flag.color = "#E30074"
\override Beam.color = "#5e45ad"
\override Rest.color = "#3058"
g'8 \huge r4 a'16 f'

If that color code includes an alpha channel for semi-transparency, by using an eight-character code "#RRGGBBAA" or its shorthand form "#RGBA", it will be used in SVG output but not in PostScript/PDF output. In the previous example, the rest can be seen through only if the code is compiled with the SVG backend, as explained in Alternative output formats.

In a different way, the full range of colors defined for X11 can be accessed by using the Scheme function x11-color. That function takes one argument, which can be a symbol, such as 'DarkSeaGreen4, or a string, such as "DarkSeaGreen4". The first form is quicker to write and slightly more efficient; however, the second form also makes it possible to specify X11 colors as multiple words: in this instance, "dark sea green 4".

If x11-color cannot make sense of the parameter, then the color returned defaults to black.

\new Staff \with {
  instrumentName = \markup {
    \with-color #(x11-color 'SlateGrey) "Clarinet"
    }
  }
  \relative c'' {
  \override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
  gis8 a
  \override Beam.color = #(x11-color "medium turquoise")
  gis a
  \override Accidental.color = #(x11-color 'orange)
  gis a
  \override NoteHead.color = #(x11-color "LimeGreen")
  gis a
  % this is deliberate nonsense; note that the stems remain black
  \override Stem.color = #(x11-color 'Boggle)
  b2 cis
}

LilyPond also supports a set of eight color names that is unambiguous to both color-blind and non-color-blind people. Use universal-color to access them.

\markup \with-color #(universal-color 'vermillion) vermillion

Exact RGB colors can be specified using the Scheme function rgb-color. This function takes three arguments used respectively for the red, green and blue channels, and an optional alpha number for semi-transparency. (All values must be numbers from 0 to 1.) Again, transparency is only supported in SVG output; for example, in the following fragment the staff’s clef can be seen through when rendered in SVG.

\new Staff \with {
    instrumentName = \markup {
      \with-color #(x11-color 'red) "Clarinet"
      }
    \override Clef.color = #(rgb-color 0 0 0 0.5)
  }
\relative c'' {
  \override Staff.StaffSymbol.color = #(x11-color 'SlateBlue2)
  \override Stem.color = #(rgb-color 0 0 0)
  gis8 a
  \override Stem.color = #(rgb-color 1 1 1)
  gis8 a
  \override Stem.color = #(rgb-color 0 0 0.5)
  gis4 a
}

Known issues and warnings

An X11 color is not necessarily exactly the same shade as a similarly named normal color.

Not all X11 colors are distinguishable in a web browser, i.e., a web browser might not display a difference between LimeGreen and ForestGreen. For web use CSS colors are recommended, as detailed in List of colors.

Notes in a chord cannot be separately colored with \override; use \tweak or the equivalent \single\override before the respective note instead, see The \tweak command.

[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Coloring objects ]	[ Up : Inside the staff ]	[ Parentheses > ]

Staff highlights

For analytical or pedagogical purposes, it may be useful to “highlight” musical passages, for example in order to show local tonality. This can be done using the \staffHighlight command, which expects a color. For all ways to enter colors, see Coloring objects. The highlight is terminated using \stopStaffHighlight.

\relative {
  \time 2/4
  c'4 4
  \staffHighlight "lightsteelblue"
  g'8( fis g4)-.
  \stopStaffHighlight
  c2
}

If there are consecutive highlights, it is not necessary to write \stopStaffHighlight, as \staffHighlight also implicitly terminates the current highlight, if any. Similarly, it is not necessary to add \stopStaffHighlight at the end of the piece. This is particularly handy if every measure is to be highlighted.

\relative {
  \time 2/4
  \staffHighlight "lightpink"
  c'4 4
  \staffHighlight "lightsteelblue"
  g'8( fis g4)-.
  \staffHighlight "lightpink"
  c2
}

By default, staves are highlighted separately.

music = {
  \time 2/4
  \staffHighlight "lightpink"
  c'4 4
  \staffHighlight "lightsteelblue"
  g'8( fis g4)-.
  \staffHighlight "lightpink"
  c2
}

<<
  \new Staff \music
  \new Staff \music
>>

However, several staves can be highlighted together by moving Staff_highlight_engraver to a higher context than Staff (or RhythmicStaff, or similar). This is done using the \consists and \remove commands; See Modifying context plug-ins for more information. For example, if the engraver is moved to Score, the highlights are shared by all staves.

\layout {
  \context {
    \Staff
    \remove Staff_highlight_engraver
  }
  \context {
    \Score
    \consists Staff_highlight_engraver
  }
}

music = {
  \time 2/4
  \staffHighlight "lightpink"
  c'4 4
  \staffHighlight "lightsteelblue"
  g'8( fis g4)-.
  \staffHighlight "lightpink"
  c2
}

<<
  \new Staff \music
  \new Staff \music
>>

Staff_highlight_engraver may also be moved to intermediate contexts such as StaffGroup.

music = {
  \time 2/4
  \staffHighlight "lightpink"
  c'4 4
  \staffHighlight "lightsteelblue"
  g'8( fis g4)-.
  \staffHighlight "lightpink"
  c2
}

<<
  \new StaffGroup \with { \consists Staff_highlight_engraver } <<
    \new Staff \with { \remove Staff_highlight_engraver } \music
    \new Staff \with { \remove Staff_highlight_engraver } \music
  >>
  \new Staff \music
>>

The StaffHighlight.shorten-pair property may be used to tweak the horizontal start and end of the highlight span.

{
  c'1
  \once \override Staff.StaffHighlight.shorten-pair = #'(1.0 . 1.0)
  \staffHighlight lightsteelblue
  c'1
}

Predefined commands

\staffHighlight, \stopStaffHighlight.

Known issues and warnings

The behavior of highlights may not be what is expected at start repeat bar lines. The shorten-pair property demonstrated above can be used to work around this issue.

{
  \staffHighlight "lightsteelblue"
  c'1
  \stopStaffHighlight
  \repeat volta 2 { c'1 }
  c'1
}

[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Staff highlights ]	[ Up : Inside the staff ]	[ Stems > ]

Parentheses

Objects may be parenthesized by prefixing \parenthesize to the music event. When prefixed to a chord, it parenthesizes every note. Individual notes inside a chord may also be parenthesized.

\relative {
  c''2 \parenthesize d
  c2 \parenthesize <c e g>
  c2 <c \parenthesize e g>
}

Non-note objects may be parenthesized as well. For articulations, a hyphen is needed before the \parenthesize command.

\relative {
  c''2-\parenthesize -. d
  c2 \parenthesize r
}

When \parenthesize applies to a chord, all of its notes are enclosed in the parentheses.

\relative c' {
  \parenthesize <e f>
}

To parenthesize only certain notes in a chord, use a parallel music construct << … >>.

\new Voice \relative c {
  <<
    { \tweak Parentheses.font-size 0 \parenthesize <ces des> }
    { \parenthesize ees' }
    { \tweak Parentheses.font-size -2 \parenthesize <c' e> }
  >>
}

A second form of the \parenthesize command involves a grob path: either \parenthesize ContextName.GrobName or just \parenthesize GrobName (the latter implying the bottommost context, typically Voice). This should be added before the musical moment, like a \once \override. This form makes it possible to parenthesize grobs that are only caused indirectly by events.

\new Staff \relative <<
  {
    \parenthesize NoteHead
    c'1
  }
  \new CueVoice {
    s2
    \voiceOne
    \once \override Staff.Parentheses.font-size = 3
    \parenthesize Staff.CueClef
    \cueClef treble
    e'8 f a g
  }
>>

Known issues and warnings

Currently, the font-size property of the Parentheses grob has to be adjusted manually to obtain correctly sized parentheses on chords and some other objects.

[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Parentheses ]	[ Up : Inside the staff ]	[ Outside the staff > ]

Stems

Whenever a note is found, a Stem object is created automatically. For whole notes and rests, they are also created but made invisible.

Stems may be manually placed to point up or down; see Direction and placement.

Predefined commands

\stemUp, \stemDown, \stemNeutral.

Selected Snippets

Default direction of stems on the center line of the staff

The default direction of stems on the center line of the staff is set by the Stem property neutral-direction.

\relative c'' {
  a4 b c b
  \override Stem.neutral-direction = #up
  a4 b c b
  \override Stem.neutral-direction = #down
  a4 b c b
}

Automatically changing the stem direction of the middle note based on the melody

LilyPond can alter the stem direction of the middle note on a staff so that it follows the melody, by adding the Melody_engraver to the Voice context.

The context property suspendMelodyDecisions may be used to turn off this behavior locally.

\relative c'' {
  \time 3/4
  a8 b g f b g |
  \set suspendMelodyDecisions = ##t
  a  b g f b g |
  \unset suspendMelodyDecisions
  c  b d c b c |
}

\layout {
  \context {
    \Voice
    \consists "Melody_engraver"
    \autoBeamOff
  }
}

1.7.1 Inside the staff

Selecting notation font size

Resizing individual layout objects

Understanding the `fontSize` property

Predefined commands

See also

Known issues and warnings

Fingering instructions

Selected Snippets

Controlling the placement of chord fingerings

Allowing fingerings to be printed inside the staff

See also

Gliding fingers

See also

Known issues and warnings

Hidden notes

Predefined commands

See also

Coloring objects

See also

Known issues and warnings

Staff highlights

Predefined commands

See also

Known issues and warnings

Parentheses

See also

Known issues and warnings

Stems

Predefined commands

Selected Snippets

Default direction of stems on the center line of the staff

Automatically changing the stem direction of the middle note based on the melody

See also

LilyPond — Notation Reference v2.23.82 (development-branch).

1.7.1 Inside the staff

Selecting notation font size

Resizing individual layout objects

Understanding the fontSize property

Predefined commands

See also

Known issues and warnings

Fingering instructions

Selected Snippets

Controlling the placement of chord fingerings

Allowing fingerings to be printed inside the staff

See also

Gliding fingers

See also

Known issues and warnings

Hidden notes

Predefined commands

See also

Coloring objects

See also

Known issues and warnings

Staff highlights

Predefined commands

See also

Known issues and warnings

Parentheses

See also

Known issues and warnings

Stems

Predefined commands

Selected Snippets

Default direction of stems on the center line of the staff

Automatically changing the stem direction of the middle note based on the melody

See also

LilyPond — Notation Reference v2.23.82 (development-branch).

Understanding the `fontSize` property