LilyPond — Changes

Major changes in LilyPond

• Margins are now wider by default following the general layout of several publishers (and the recommendations of Elaine Gould).

  In order to switch back to the previous settings (e.g., to keep the same layout when upgrading an existing score to version 2.25.29), add the following code:

  \paper {
    top-margin = 5\mm
    bottom-margin = 6\mm
    top-system-spacing.basic-distance = 1
    top-markup-spacing.basic-distance = 0
    left-margin = 10\mm
    right-margin = 10\mm
    inner-margin = 10\mm
    outer-margin = 20\mm
    binding-offset = 0\mm
  }
  

• Instead of generating PostScript or SVG output by itself, LilyPond can now use the Cairo library to produce its output. This is referred to as the ‘Cairo backend’, and can be turned on using the -dbackend=cairo command-line option. This works for all output formats (PDF, SVG, PNG, PostScript), and brings speed and rendering fidelity improvements in SVG output in particular. However, keep in mind that this backend does not yet implement all features of the default backends. Among the features not currently supported are PDF outlines, the -dembed-source-code option for PDF, and the output-attributes property for SVG.
• The distances between clefs and time signatures, together with the distances between clefs and key signatures, are now calculated differently. As a consequence, you will get better spacing for extra-wide clefs (like \clef "GG") or extra-slim clefs (like \clef "petrucci-c3").

  In the following image, both old and new positions are shown. The percentage gives the width difference of clef plus time signature and clef plus key signature, respectively.

  

  Note that, as before, the widest clef in a staff group determines the horizontal position of all clefs in a system; this means, for example, that a piano score containing a treble and a bass clef doesn’t change at all.

  If you want to restore the previous default values for whatever reason, add

  \override Staff.Clef.space-alist.time-signature =
              #'(minimum-space . 3.5)
  \override Staff.Clef.space-alist.key-cancellation =
              #'(minimum-space . 3.5)
  \override Staff.Clef.space-alist.key-signature =
              #'(minimum-space . 4.2)
  

  to your score.

• The LilyPond major mode for the GNU Emacs text editor provided by the Emacs Lisp package lilypond-mode.el has been renamed from LilyPond-mode to lilypond-mode. The namespace prefix for the package is changed to all lowercase lilypond- from LilyPond-, meaning all its functions, variables, etc., now have the all-lowercase prefix. This change is made to comply with the idiomatic Emacs naming convention, most importantly, having the major mode name be the same as the package name that provides it. Therefore, this also makes it easier for new users to set up LilyPond in Emacs.

  As a result, this will break some existing Emacs configurations for end users. However, it only requires minimal changes to the Emacs initialization file. Here’s an example of setting up lilypond-mode using the built-in use-package macro in Emacs:

  (use-package lilypond-mode
    :ensure nil
    :mode "\\.\\(ly\\|ily\\)$")
  

New for musical notation

New for specialist notation

• For consistency with other ancient clefs, five new mensural clefs are available: "mensural-f2", "mensural-f3", "mensural-f4" (same as "mensural-f"), "mensural-f5", "mensural-g1", "mensural-g2" (same as "mensural-g").
• The default time signature and accidental style in a PetrucciStaff context is now the same as in MensuralStaff.
• White mensural ligatures now support some rare ligatures (semibreves alone or in the middle), and allow tweaks to show some non-necessary stems.

  \score {
    \relative {
      \set Score.timing = ##f
      \set Score.measureBarType = #'()
      \override NoteHead.style = #'petrucci
      \override Staff.TimeSignature.style = #'mensural
      \clef "petrucci-c4"
      \[ a1 g f e \]
      \[ a1 g\longa \]
      \[ \tweak left-down-stem ##t a\breve b
         \tweak right-down-stem ##t g\longa \]
      \[ \tweak right-down-stem ##t b\maxima
         \tweak right-up-stem ##t g\longa \]
    }
    \layout {
      \context {
        \Voice
        \remove Ligature_bracket_engraver
        \consists Mensural_ligature_engraver
      }
    }
  }
  

  

• The use of the file gregorian.ly is deprecated. While still distributed for backward compatibility, it should be replaced with a VaticanaScore context together with some manual \layout changes (if necessary): code like

  \include "gregorian.ly"
  
  \score {
    \new VaticanaStaff { ... }
  }
  

  should become

  \new VaticanaScore {
    \new VaticanaStaff { ... }
  }
  
  \layout {
    indent = 0
    ragged-last = ##t
  }
  

• LilyPond’s ‘arabic’ note name language is deprecated. While still working for backward compatibility (if you load hel-arabic.ly), it is recommended to use ‘english’, ‘italiano’, or your preferred note name language instead.
• Defaults for fret labels in fret diagrams have changed.
  • The default value for fret-label-vertical-offset is set to -0.5, which centers the label in the fret space.
  • The default number format is now 'custom, with a format string of "~dfr" (resulting in ‘3fr’, for example), instead of 'roman-lower.
• Two new options are available for fret-diagram-details:
  • string-overhang allows to define the extension of string lines beyond the last fret line, in multiples of fret-distance. Default value 1.
  • barre-thickness defines the thickness of the barre line, in multiples of dot-radius. Only defined for barre-type=straight. Default value 1.
• The command \autoBeamOff now stops auto-beaming immediately. Previously, its effect was delayed if a beam generated by the auto-beamer engraver was still active.
• It is no longer necessary to switch off auto-beaming while using \crossStaff.
• The \upbow and \downbow signs are now properly inverted if used below a staff. As a consequence, the glyphs scripts.upbow and scripts.downbow have been renamed to scripts.uupbow and scripts.udownbow, respectively, and the new inverted glyphs are named scripts.dupbow and scripts.ddownbow.

  \relative c' {
    f4^\downbow f^\upbow f_\downbow f_\upbow
  }
  

  

• In lyrics aligned to a melody, extender lines can now be added automatically for words ending in a melisma.

  \relative {
    d'4 e f4 g8( f
    e4 d c2)
  }
  \addlyrics {
    \set autoExtenders = ##t
    A me -- lis -- ma.
  }
  

  

Miscellaneous improvements

• The timeSignatureFraction context property is deprecated in favor of timeSignature. The new property accepts subdivided and alternating time signatures in addition to the simple fractions that the old property accepted. Accessing the old property transparently derives a simple fraction from the new property and triggers a warning.
• (make-music 'Music) and (make-music 'Event) now create music expressions that have the void property set to #t by default. The function empty-music has been removed in favor of (make-music 'Music). The new predicate unspecified-music? recognizes any music expression with the void flag set.
• The new Scheme function ly:number->duration converts a duration expressed in units of whole notes to a ly:duration. The log, number of dots, and scaling factor are chosen automatically.
• The markup commands \hspace and \vspace are used to insert space, which may be negative. Other objects are moved accordingly. This movement may be indicated by arrows printed by the new markup command annotate-moving. Note that the arrows do not reflect the actual extents of the objects created by \vspace and \hspace; you might use \box for that.

  \markup {
    left \annotate-moving \hspace #4 right
    \column { top \annotate-moving \vspace #-4/3 bottom }
  }
  

  

• The new \contextPropertyCheck command verifies that a property is set to an expected value or is unset in a specific context.
• Various context properties that previously held ly:moment values now hold rational numbers. To ease this transition, each number property is paired with a fallback ly:moment property. Using the fallback property transparently accesses the number property and triggers a warning.

  Deprecated Context Property	New Context Property
  baseMoment	beatBase
  completionUnitAsMoment	completionUnit
  gridIntervalAsMoment	gridInterval
  measureLengthAsMoment	measureLength
  minimumPageTurnLength	pageTurnMinimumRestLength
  minimumRepeatLengthForPageTurn	pageTurnMinimumRepeatLength
  proportionalNotationDurationAsMoment	proportionalNotationDuration
  tempoWholesPerMinuteAsMoment	tempoWholesPerMinute
  tupletSpannerDurationAsMoment	tupletSpannerDuration
  voltaSpannerDurationAsMoment	voltaSpannerDuration

• \tempo dur = min - max used to set the context property tempoWholesPerMinute after rounding the center of the range to the nearest integer. It no longer rounds. This is expected to change the MIDI tempo in certain cases.
• The Scheme functions duration-length and ly:duration-length are renamed to ly:duration->number and ly:duration->moment, respectively.
• The new Scheme function ly:parser-append-to-include-path appends its argument to the current parser’s include path.
• The value of the timeSignatureSettings context property uses the symbol beatBase where it formerly used baseMoment. convert-ly does not address this change.
• Embedding PNG images is now supported using the new \image markup command. This supplements the existing \epsfile command for EPS images.

  \image works for both PNG and EPS images. For EPS images, the difference between using \image and \epsfile is that \image adds a white background by default, while \epsfile does not.

• The new \qr-code markup command inserts a QR code of the specified size for the specified URL. This can be used to link to, e.g., the website of a composer or publisher, the LilyPond source files for the score, recordings, etc.

  \markup \qr-code #10 "https://lilypond.org"
  

  

• Parentheses for text markup have been added to the Emmentaler fonts, which harmonize with digits (in contrast to the already available parentheses for accidentals).
• Glyphs for a figure-dash (U+2012), an en-dash (U+2013), and a slash (U+002F) have been added to the Emmentaler fonts.
• A figure space (U+2007), a thin space (U+2009), and a hair space (U+200A) have been added to the Emmentaler fonts.
• The -dinclude-settings option can now be given multiple times to include several stylesheets.
• In the LaTeX backend of lilypond-book, all inline images are now vertically shifted. The amount can be controlled globally with command-line option --inline-vshift and locally with an argument to the snippet option inline.
• It is possible to use various command-line options of musicxml2ly as options for lilypond-book’s musicxmlfile command. This was actually introduced in version 2.15.9 (in 2011) but stayed undocumented until now.
• Two new command-line options -dfirst and -dlast have been introduced; they are equivalent to setting showFirstLength and showLastLength, respectively, in a LilyPond input file. For example, saying

  lilypond -dlast=R1*5 ...
  

  makes LilyPond render only the last five measures (assuming a 4/4 time signature).

• A visual index of all LilyPond graphical objects (grobs) is now available as a manual. This is based on Joram Berger’s work for LilyPond 2.19.
• LilyPond provides support for in-notes, i.e., footnote-like annotations between music systems. This isn’t new (it has actually been available since version 2.15.17, published in 2011) but it had some flaws and wasn’t documented until now.
• The lilysong script has been removed. Besides lacking any documentation, it hasn’t been maintained for a long time. Additionally, it has been using an external speech synthesis program called festival, which is no longer maintained either.
• Two new spacing styles are available for the space-alist grob property: shrink-space and semi-shrink-space; these spaces only shrink and don’t stretch. They are also used directly in LilyPond, improving the formatting of tightly spaced staves.
• The lilypond binary has a new command-line option -dstaff-size to set the global staff size, equivalent to setting set-global-staff-size in a LilyPond input file.
• Instead of the functions \bookOutputName and \bookOutputSuffix we now recommend using the paper variables output-filename and output-suffix (which are not new but stayed undocumented until now). While the former will work unchanged, the latter is more coherent and easier to understand, especially if combined with predefined paper variables.
• The Stem.details.lengths property now also accepts pairs as list elements, allowing to set the length for up and down stems separately.
• The ly:self-alignment-interface::aligned-on-x-parent function (used by many grobs to compute the x-offset) now listens to a new PaperColumn property called X-alignment-extent. Set by default, it provides a fallback width for the PaperColumn grob in case it doesn’t contain note heads. This helps align dynamic scripts that are attached to spacer rests, for example.

  music =
    \new Staff <<
      { f'2 g'2 }
      { s4\f s\f s\f s\f }
    >>
  
  \score {
    \music
  }
  
  \score {
    \music
  
    \layout {
      \context {
        \Score
        \override PaperColumn.X-alignment-extent = ##f
      }
    }
  }
  

  

• BassFigureContinuation grobs now support horizontal-line-spanner-interface; the padding property has been replaced with the corresponding sub-properties in bound-details.
• The \align-on-other markup command now accepts #f as a value for the alignment, indicating a markup’s reference point.
• A new function \withRelativeDir is now available for markup commands that include files, and where such files should be found relative to the input file. Example:

  \markup { \image #X #3 \withRelativeDir "test.png" }
  

• The positioning of horizontal (analysis) brackets has been improved; in particular, the HorizontalBracket grob now has an outside-staff-priority value of 800. As a consequence, however, nested horizontal brackets might be positioned differently than before. You can fix this by adjusting outside-staff-priority values with \tweak (where the outermost bracket should get the highest priority value).
• A new Scheme function to-staff-space is provided to convert absolute dimensions (in various units) to staff-space units. Examples:

  top-markup-spacing.basic-distance = #(to-staff-space 2 'cm)
  
  % default unit is pt
  \markup
    \override #`(baseline-skip . ,(to-staff-space 20))
    \column {
      foo
      bar
    }
  

• Two new markup functions \abs-hspace and \abs-vspace are available to provide absolute dimensions that stay the same regardless of the current staff size.
• The data emitted by the command-line option -dshow-available-fonts is now sent to standard output.
• The function ly:font-config-display-fonts now takes an optional argument for output port selection.
• Scheme command-line option handling is now more robust. In the course of the new implementation, some minor changes were necessary.
  • On the command line, the argument for the -dpaper-size option no longer needs to be extra-quoted, i.e., a call like -dpaper-size=a3 works just fine.
  • The pixmap-format option now expects a string as a value, not a symbol. No change on the command line, but a call like

    #(ly:set-option 'pixmap-format 'pngalpha)
    

    must be changed to

    #(ly:set-option 'pixmap-format "pngalpha")
    

    The same holds for options separate-page-formats and tall-page-formats. Note that convert-ly can handle this automatically.

• The side-position-interface now offers two new properties, X-padding and minimum-X-space, to control the horizontal padding and minimum distance to a grob’s parent object, independently of the vertical padding and minimum distance. This is useful for grobs like Fingering that can be attached either horizontally or vertically to note heads, and which need different padding values for the X- and Y-axis, respectively.
• \pushContextProperty and \popContextProperty are two new commands for manipulating context properties. The first one pushes the current value to a stack, while the second one pops off the value from the stack and uses it to restore the property.

  {
    c'
    \pushContextProperty Staff.fontSize
    \set Staff.fontSize = 3
    c'
    \pushContextProperty Staff.fontSize
    \set Staff.fontSize = 6
    c'
    \popContextProperty Staff.fontSize
    c'
    \popContextProperty Staff.fontSize
    c'
  }
  

  

• A new grob property whiteout-color is available to set the color used for white-out operations. Similarly, the \whiteout markup command now listens to a color property to do the same.
• The musicxml2ly script has been completely revised to better convert MusicXML to LilyPond. It now supports more MusicXML features and elements and tries to be more faithful in the conversion, retaining more of the original appearance if possible (and sensible).

  Here is a list of some notable changes (not taking bug fixes into account).

  • The script is now much faster.
  • Overlapping and nested slurs work as expected.
  • Better automatic support of circumventing LilyPond’s infamous issue #34 (i.e., synchronization of grace note timing between staves at the beginning of a piece).
  • Support of two-stem tremolos and nested tuplets.
  • Color and font size support for almost all MusicXML elements. A new command-line option --dynamics-scale helps compensate glyph size differences of dynamics signs in various music fonts.
  • Correct handling of ottava endings for MusicXML files created by Finale. The script looks at the <software> element to detect the used notation software. If necessary, this can be overridden with the new command-line option --ottavas-end-early.
  • Option --shift-meter has been replaced with option --shift-durations, using a simpler syntax.
  • New command-line option --no-tagline to suppress the output of a LilyPond tagline.
  • New command-line option --book to wrap the top-level score with \book.
  • If <credit> elements are present, they now fill the fields in LilyPond’s \header block instead of metadata elements like <work-title> or <creator>.
  • New command-line option --credit-page to specify the page from which LilyPond should take <credit> data to fill the \header block.
  • All metadata elements that are not mapped to standard \header fields (and which are not ignored like the ‘page number’ type) are output with more consistent field names: the prefix ‘id: ’ is used for <identification> children, ‘credit: ’ for <credit> elements, and the MusicXML element name (without a prefix) in all other cases. As a consequence, some (unused) fields got new names.

    old	new
    movementnumber	movement-number
    encodingsoftware	id: software
    encodingdate	id: encoding-date
    encoder	id: encoder
    encodingdescription	id: encoding-description
    source	id: source

  • The bar numbers shown as comments in the created LilyPond input file are now as expected, i.e., the values shown refer to the previous bar.
• The markup command \page-ref has a new property x-align to control the X-alignment of the gauge replacement.

  \markup {
    \box
      \page-ref #'foo "???" "?" " right-aligned (default)"
  }
  \markup {
    \box
      \override #`(x-align . ,LEFT)
      \page-ref #'foo "???" "?" " left-aligned"
  }
  \markup {
    \box
      \override #'(x-align . -2.5)
      \page-ref #'foo "???" "?" " left outside"
  }
  

  

• It is now also possible to set the ledger-extra property via the NoteHead grob.

  {
    c'''1
    \tweak ledger-extra #4 c'''1
    c'''1
  }
  

  

For older news, go to https://lilypond.org/doc/v2.22/Documentation/changes/, or go back to the Documentation index.