LilyPond — Extending

1.1.1 Scheme sandbox

The LilyPond installation includes the Guile implementation of Scheme. A hands-on Scheme sandbox with all of LilyPond loaded is available with this command line:

lilypond scheme-sandbox

Once the sandbox is running, you will receive a guile prompt:

guile>

You can enter Scheme expressions at this prompt to experiment with Scheme. If you want to be able to use the GNU readline library for nicer editing of the Scheme command line, check the file ly/scheme-sandbox.ly for more information. If you already have enabled the readline library for your interactive Guile sessions outside of LilyPond, this should work in the sandbox as well.

1.1.2 Scheme variables

Scheme variables can have any valid Scheme value, including a Scheme procedure.

Scheme variables are created with define:

guile> (define a 2)
guile>

Scheme variables can be evaluated at the guile prompt simply by typing the variable name:

guile> a
2
guile>

Scheme variables can be printed on the display by using the display function:

guile> (display a)
2guile>

Note that both the value 2 and the guile prompt guile showed up on the same line. This can be avoided by calling the newline procedure or displaying a newline character.

guile> (display a)(newline)
2
guile> (display a)(display "\n")
2
guile>

Once a variable has been created, its value can be changed with set!:

guile> (set! a 12345)
guile> a
12345
guile>

1.1.3 Scheme simple data types

The most basic concept in a language is data typing: numbers, character strings, lists, etc. Here is a list of simple Scheme data types that are often used with LilyPond.

Booleans

Boolean values are True or False. The Scheme for True is #t and False is #f.

Numbers

Numbers are entered in the standard fashion, 1 is the (integer) number one, while -1.5 is a floating point number (a non-integer number).

Strings

Strings are enclosed in double quotes:

"this is a string"

Strings may span several lines:

"this
is
a string"

and the newline characters at the end of each line will be included in the string.

Newline characters can also be added by including \n in the string.

"this\nis a\nmultiline string"

Quotation marks and backslashes are added to strings by preceding them with a backslash. The string \a said "b" is entered as

"\\a said \"b\""

There are additional Scheme data types that are not discussed here. For a complete listing see the Guile reference guide, https://www.gnu.org/software/guile/docs/docs-1.8/guile-ref/Simple-Data-Types.html.

1.1.4 Scheme compound data types

There are also compound data types in Scheme. The types commonly used in LilyPond programming include pairs, lists, alists, and hash tables.

guile> (cons 4 5)
(4 . 5)
guile>

guile> '(4 . 5)
(4 . 5)
guile>

guile> (cons #t #f)
(#t . #f)
guile> '("blah-blah" . 3.1415926535)
("blah-blah" . 3.1415926535)
guile>

guile> (define mypair (cons 123 "hello there")
… )
guile> (car mypair)
123
guile> (cdr mypair)
"hello there"
guile>

guile> (list 1 2 3 "abc" 17.5)
(1 2 3 "abc" 17.5)

(1 . (2 . (3 . ("abc" . (17.5 . ())))))

guile> '(17 23 "foo" "bar" "bazzle")
(17 23 "foo" "bar" "bazzle")

guile> (define my-alist '((1  . "A") (2 . "B") (3 . "C")))
guile> my-alist
((1 . "A") (2 . "B") (3 . "C"))
guile> (assoc 2 my-alist)
(2 . "B")
guile> (cdr (assoc 2 my-alist))
"B"
guile>

guile> (define h (make-hash-table 10))
guile> h
#<hash-table 0/31>
guile> (hashq-set! h 'key1 "val1")
"val1"
guile> (hashq-set! h 'key2 "val2")
"val2"
guile> (hashq-set! h 3 "val3")
"val3"

guile> (hashq-ref h 3)
"val3"
guile> (hashq-ref h 'key2)
"val2"
guile>

guile> (hashq-get-handle h 'key1)
(key1 . "val1")
guile> (hashq-get-handle h 'frob)
#f
guile>

1.1.5 Calculations in Scheme

Scheme can be used to do calculations. It uses prefix syntax. Adding 1 and 2 is written as (+ 1 2) rather than the traditional 1+2.

guile> (+ 1 2)
3

Calculations may be nested; the result of a function may be used for another calculation.

guile> (+ 1 (* 3 4))
13

These calculations are examples of evaluations; an expression like (* 3 4) is replaced by its value 12.

Scheme calculations are sensitive to the differences between integers and non-integers. Integer calculations are exact, while non-integers are calculated to the appropriate limits of precision:

guile> (/ 7 3)
7/3
guile> (/ 7.0 3.0)
2.33333333333333

When the Scheme interpreter encounters an expression that is a list, the first element of the list is treated as a procedure to be evaluated with the arguments of the remainder of the list. Therefore, all operators in Scheme are prefix operators.

If the first element of a Scheme expression that is a list passed to the interpreter is not an operator or procedure, an error will occur:

guile> (1 2 3)

Backtrace:
In current input:
  52: 0* [1 2 3]

<unnamed port>:52:1: In expression (1 2 3):
<unnamed port>:52:1: Wrong type to apply: 1
ABORT: (misc-error)
guile>

Here you can see that the interpreter was trying to treat 1 as an operator or procedure, and it couldn’t. Hence the error is "Wrong type to apply: 1".

Therefore, to create a list we need to use the list operator, or to quote the list so that the interpreter will not try to evaluate it.

guile> (list 1 2 3)
(1 2 3)
guile> '(1 2 3)
(1 2 3)
guile>

This is an error that can appear as you are working with Scheme in LilyPond.

1.1.6 Scheme procedures

Scheme procedures are executable Scheme expressions that return a value resulting from their execution. They can also manipulate variables defined outside of the procedure.

(define (function-name arg1 arg2 … argn)
 scheme-expression-that-gives-a-return-value)

guile> (define (average x y) (/ (+ x y) 2))
guile> average
#<procedure average (x y)>

guile> (average 3 12)
15/2

guile> (define (less-than-ten? x) (< x 10))
guile> (less-than-ten? 9)
#t
guile> (less-than-ten? 15)
#f

guile> (begin (+ 1 2) (- 5 8) (* 2 2))
4

guile> (let ((x 2) (y 3) (z 4)) (display (+ x y)) (display (- z 4))
… (+ (* x y) (/ z x)))
508

1.1.7 Scheme conditionals

(if test-expression true-expression false-expression)

guile> (define a 3)
guile> (define b 5)
guile> (if (> a b) "a is greater than b" "a is not greater than b")
"a is not greater than b"

(cond (test-expression-1 result-expression-sequence-1)
      (test-expression-2 result-expression-sequence-2)
      …
      (test-expression-n result-expression-sequence-n))

guile> (define a 6)
guile> (define b 8)
guile> (cond ((< a b) "a is less than b")
...          ((= a b) "a equals b")
...          ((> a b) "a is greater than b"))
"a is less than b"

1.2.1 LilyPond Scheme syntax

The Guile interpreter is part of LilyPond, which means that Scheme can be included in LilyPond input files. There are several methods for including Scheme in LilyPond.

The simplest way is to use a hash mark # before a Scheme expression.

Now LilyPond’s input is structured into tokens and expressions, much like human language is structured into words and sentences. LilyPond has a lexer that recognizes tokens (literal numbers, strings, Scheme elements, pitches and so on), and a parser that understands the syntax. Once it knows that a particular syntax rule applies, it executes actions associated with it.

The hash mark # method of embedding Scheme is a natural fit for this system. Once the lexer sees a hash mark, it calls the Scheme reader to read one full Scheme expression (this can be an identifier, an expression enclosed in parentheses, or several other things). After the Scheme expression is read, it is stored away as the value for an SCM_TOKEN in the grammar. Once the parser knows how to make use of this token, it calls Guile for evaluating the Scheme expression. Since the parser usually requires a bit of lookahead from the lexer to make its parsing decisions, this separation of reading and evaluation between lexer and parser is exactly what is needed to keep the execution of LilyPond and Scheme expressions in sync. For this reason, you should use the hash mark # for calling Scheme whenever this is feasible.

Another way to call the Scheme interpreter from LilyPond is the use of dollar $ instead of a hash mark for introducing Scheme expressions. In this case, LilyPond evaluates the code right after the lexer has read it. It checks the resulting type of the Scheme expression and then picks a token type (one of several xxx_IDENTIFIER in the syntax) for it. It creates a copy of the value and uses that for the value of the token. If the value of the expression is void (Guile’s value of *unspecified*), nothing at all is passed to the parser.

This is, in fact, exactly the same mechanism that LilyPond employs when you call any variable or music function by name, as \name, with the only difference that the name is determined by the LilyPond lexer without consulting the Scheme reader, and thus only variable names consistent with the current LilyPond mode are accepted.

The immediate action of $ can lead to surprises, see Importing Scheme in LilyPond. Using # where the parser supports it is usually preferable. Inside of music expressions, expressions created using # are interpreted as music. However, they are not copied before use. If they are part of some structure that might still get used, you may need to use ly:music-deep-copy explicitly.

There are also ‘list splicing’ operators $@ and #@ that insert all elements of a list in the surrounding context.

Now let’s take a look at some actual Scheme code. Scheme procedures can be defined in LilyPond input files:

#(define (average a b c) (/ (+ a b c) 3))

Note that LilyPond comments (% and %{ %}) cannot be used within Scheme code, even in a LilyPond input file, because the Guile interpreter, not the LilyPond lexer, is reading the Scheme expression. Comments in Guile Scheme are entered as follows:

; this is a single-line comment

#!
  This a (non-nestable) Guile-style block comment
  But these are rarely used by Schemers and never in
  LilyPond source code
!#

For the rest of this section, we will assume that the data is entered in a music file, so we add a # at the beginning of each Scheme expression.

All of the top-level Scheme expressions in a LilyPond input file can be combined into a single Scheme expression by use of the begin statement:

#(begin
  (define foo 0)
  (define bar 1))

1.2.2 LilyPond variables

LilyPond variables are stored internally in the form of Scheme variables. Thus,

twelve = 12

is equivalent to

#(define twelve 12)

This means that LilyPond variables are available for use in Scheme expressions. For example, we could use

twentyFour = #(* 2 twelve)

which would result in the number 24 being stored in the LilyPond (and Scheme) variable twentyFour.

Scheme allows modifying complex expressions in-place and LilyPond makes use of this ‘in-place modification’ when using music functions. But when music expressions are stored in variables rather than entered directly the usual expectation, when passing them to music functions, would be that the original value is unmodified. So when referencing a music variable with leading backslash (such as \twentyFour), LilyPond creates a copy of that variable’s music value for use in the surrounding music expression rather than using the variable’s value directly.

Therefore, Scheme music expressions written with the # syntax should be used for material that is created ‘from scratch’ (or that is explicitly copied) rather than being used, instead, to directly reference material.

See also

Extending: LilyPond Scheme syntax.

1.2.3 Debugging Scheme code

When debugging large Scheme programs, it is helpful when an error occurs to be pointed to the precise line in the program where it was raised. In order to enable source locations to be shown for errors in Scheme code, LilyPond must be run with the command-line option -dcompile-scheme-code. Alternatively, writing #(ly:set-option 'compile-scheme-code) at the top of the LilyPond file has the same effect.

Furthermore, to obtain even more information about the error, you may use the -ddebug-eval option, or the code #(debug-enable 'backtrace) in the file. Under this mode, when an error occurs, a verbose “backtrace” is displayed, containing information about all function calls that led to the problematic spot.

Known issues and warnings

Due to a limitation in the Guile implementation, the -dcompile-scheme-code option currently makes it impossible to compile LilyPond files with more than a few thousand Scheme expressions.

1.2.4 Input variables and Scheme

The input format supports the notion of variables: in the following example, a music expression is assigned to a variable with the name traLaLa.

traLaLa = { c'4 d'4 }

There is also a form of scoping: in the following example, the \layout block also contains a traLaLa variable, which is independent of the outer \traLaLa.

traLaLa = { c'4 d'4 }
\layout { traLaLa = 1.0 }

In effect, each input file is a scope, and all \header, \midi, and \layout blocks are scopes nested inside that toplevel scope.

Both variables and scoping are implemented in the Guile module system. An anonymous Scheme module is attached to each scope. An assignment of the form:

traLaLa = { c'4 d'4 }

is internally converted to a Scheme definition:

(define traLaLa Scheme value of '…')

This means that LilyPond variables and Scheme variables may be freely mixed. In the following example, a music fragment is stored in the variable traLaLa, and duplicated using Scheme. The result is imported in a \score block by means of a second variable twice:

traLaLa = { c'4 d'4 }

#(define newLa (map ly:music-deep-copy
  (list traLaLa traLaLa)))
#(define twice
  (make-sequential-music newLa))

\twice

This is actually a rather interesting example. The assignment will only take place after the parser has ascertained that nothing akin to \addlyrics follows, so it needs to check what comes next. It reads # and the following Scheme expression without evaluating it, so it can go ahead with the assignment, and afterwards execute the Scheme code without problem.

1.2.5 Importing Scheme in LilyPond

The above example shows how to ‘export’ music expressions from the input to the Scheme interpreter. The opposite is also possible. By placing it after $, a Scheme value is interpreted as if it were entered in LilyPond syntax. Instead of defining \twice, the example above could also have been written as

…
$(make-sequential-music newLa)

You can use $ with a Scheme expression anywhere you could use \name after having assigned the Scheme expression to a variable name. This replacement happens in the ‘lexer’, so LilyPond is not even aware of the difference.

One drawback, however, is that of timing. If we had been using $ instead of # for defining newLa in the above example, the following Scheme definition would have failed because traLaLa would not yet have been defined. For an explanation of this timing problem, LilyPond Scheme syntax.

A further convenience can be the ‘list splicing’ operators $@ and #@ for inserting the elements of a list in the surrounding context. Using those, the last part of the example could have been written as

…
{ #@newLa }

Here, every element of the list stored in newLa is taken in sequence and inserted into the list, as if we had written

{ #(first newLa) #(second newLa) }

Now in all of these forms, the Scheme code is evaluated while the input is still being consumed, either in the lexer or in the parser. If you need it to be executed at a later point of time, check out Void Scheme functions, or store it in a procedure:

#(define (nopc)
  (ly:set-option 'point-and-click #f))

…
#(nopc)
{ c'4 }

1.2.6 Object properties

Object properties are stored in LilyPond in the form of alist-chains, which are lists of alists. Properties are set by adding values at the beginning of the property list. Properties are read by retrieving values from the alists.

Setting a new value for a property requires assigning a value to the alist with both a key and a value. The LilyPond syntax for doing this is:

\override Stem.thickness = #2.6

This instruction adjusts the appearance of stems. An alist entry '(thickness . 2.6) is added to the property list of the Stem object. thickness is measured relative to the thickness of staff lines, so these stem lines will be 2.6 times the width of staff lines. This makes stems almost twice as thick as their normal size. To distinguish between variables defined in input files (like twentyFour in the example above) and variables of internal objects, we will call the latter ‘properties’ and the former ‘variables.’ So, the stem object has a thickness property, while twentyFour is a variable.

1.2.7 LilyPond compound variables

\override TextScript.extra-offset = #'(1 . 2)

1.2.8 Internal music representation

Internally, music is represented as a Scheme list. The list contains various elements that affect the printed output. Parsing is the process of converting music from the LilyPond input representation to the internal Scheme representation.

When a music expression is parsed, it is converted into a set of Scheme music objects. The defining property of a music object is that it takes up time. The time it takes up is called its duration. Durations are expressed as a rational number that measures the length of the music object in whole notes.

A music object has three kinds of types:

• music name: Each music expression has a name. For example, a note leads to a NoteEvent, and \simultaneous leads to a SimultaneousMusic. A list of all expressions available is in the Internals Reference manual, under Music expressions.
• ‘type’ or interface: Each music name has several ‘types’ or interfaces, for example, a note is an event, but it is also a note-event, a rhythmic-event, and a melodic-event. All classes of music are listed in the Internals Reference, under Music classes.
• C++ object: Each music object is represented by an object of the C++ class Music.

The actual information of a music expression is stored in properties. For example, a NoteEvent has pitch and duration properties that store the pitch and duration of that note. A list of all properties available can be found in the Internals Reference, under Music properties.

A compound music expression is a music object that contains other music objects in its properties. A list of objects can be stored in the elements property of a music object, or a single ‘child’ music object in the element property. For example, SequentialMusic has its children in elements, and GraceMusic has its single argument in element. The body of a repeat is stored in the element property of VoltaRepeatedMusic, and the alternatives in elements.

1.3.1 A first approach (example)

1. The problem

   Using the following input, the ‘espressivo’ sign (i.e., the two small hairpins) should become wider, but not taller.

   { f'\espressivo }
   

   

2. Possible solutions
   1. create a new stencil
   2. scale the default stencil in direction of the X-axis
3. Thoughts about previous item

   Solution A is doable. However, it will result in a higher coding effort. On the other hand, solution B is cheaper, but it has the disadvantage that it doesn’t print acceptable results in all cases (although you may not know this before you’ve actually tried).

   ⇒ choose solution B.

4. Coding
   • If you want to manipulate the default stencil you have to find information about it.

     The espressivo sign is a Script grob. Looking this up in the IR (Script), we see

     ‘stencil’ (stencil):
          ‘ly:script-interface::print’
     

     Let us test whether this is correct. To be sure that we affect the correct grob we are going to use colors. There is a predefined function for that, see Scheme functions.

     -- Function: stencil-with-color stencil color
         Return a modified version of the given stencil that is
         colored with the given color.  See ‘normalize-color’ for
         possible color formats.
     

     -- Function: normalize-color color
         Convert a color given in any of the supported formats into
         a list of 4 numbers: R, G, B, A.  Possible formats are:
         such a list of 4 numbers; a list of 3 numbers (transparency
         defaults to 1.0); a CSS string (named color, or “#RRGGBB”,
         or “#RRGGBBAA”, or “#RGB”, or “#RGBA”).
     

     Using a named color (‘red’), this results in the following code.

     colorDefaultStencil =
     \once \override Script.stencil =
       % `lambda` starts a procedure; its argument is `grob`.
       #(lambda (grob)
          ;; With `let`, local variables are defined.
          (let ((stil (ly:script-interface::print grob)))
            ;; The procedure returns the colored default stencil.
            (stencil-with-color stil red)))
     
     { \colorDefaultStencil f'\espressivo }
     

     

     Fine, works.

   • This kind of operation – taking a default stencil or property and returning a modified version of it – is very common, and LilyPond provides a special function for it: grob-transformer.

     -- Function: grob-transformer property func
         Create an override value good for applying FUNC to either
         pure or unpure values.  FUNC is called with the
         respective grob as first argument and the default value
         (after resolving all callbacks) as the second.
     

     Let’s try that. (The concept of pure vs. unpure gets explained later, see Unpure-pure containers; we can ignore it for now).

     colorDefaultStencil =
     \once \override Script.stencil =
       #(grob-transformer 'stencil
          (lambda (grob orig)
            (stencil-with-color orig red)))
     
     { \colorDefaultStencil f'\espressivo }
     

     

     Success!

   • To get a scaled stencil we have to use

     -- Function: ly:stencil-scale stil x y
         Scale stencil STIL using the horizontal and vertical
         scaling factors X and optional Y (defaulting to X).
         Negative values flip or mirror STIL without changing its
         origin; this may result in collisions unless it is
         repositioned.
     

     from the same chapter in the Internals Reference.

     Result:

     scaleColorDefaultStencil =
     \once \override Script.stencil =
       #(grob-transformer 'stencil
          (lambda (grob orig)
            (stencil-with-color
             (ly:stencil-scale
              orig
              ;; 1 is the neutral element with ly:stencil-scale,
              ;; i.e., scaling with '1 1' (for x- and y-axis)
              ;; returns a visibly unchanged stencil.
              2 1)
             red)))
     
     { \scaleColorDefaultStencil f'\espressivo }
     

     

     Apart from the color that seems to be the desired output.

   • There are some problems, though, as can be seen in the following example

     { \scaleColorDefaultStencil f'_\espressivo ^\fermata }
     

     

     • − The fermata is scaled, too.
     • − Having to type the command before the note(s) and \espressivo after the note(s) is annoying.

     Solution for both: use \tweak!

     {
       f'-\tweak stencil
           #(grob-transformer 'stencil
              (lambda (grob orig)
                (stencil-with-color
                 (ly:stencil-scale orig 2 1)
                 red)))
           _\espressivo
         ^\fermata
     }
     

     

     This does what we want, however, typing so much isn’t nice – let’s define a variable and use it with the tweak. With some copy and paste we get

     #(define longer-script
        (grob-transformer 'stencil
          (lambda (grob orig)
            (stencil-with-color
             (ly:stencil-scale orig 2 1)
             red))))
     
     {
       f'-\tweak stencil #longer-script _\espressivo
         ^\fermata
     }
     

     

     Works fine, though the scaling values are hard-coded, and typing -\tweak stencil #longer-script repeatedly is still awkward.

     To fix that, let’s first introduce some variables in longer-script for x and y scaling values.

     #(define (longer-script x y)
        (grob-transformer 'stencil
          (lambda (grob orig)
            (stencil-with-color
             (ly:stencil-scale orig x y)
             red))))
     

     Second, to reduce typing, we define an event function, see Event functions. The elements in the first parenthesis group (‘(x-val y-val)’) are the function variables, the elements in the second parenthesis group the respective variable types (two times we check for a number; see Predefined type predicates for possible tests).

     scaleEspr =
     #(define-event-function (x-val y-val) (number? number?)
       #{
         \tweak stencil #(longer-script x-val y-val)
         \espressivo
       #})
     
     { f'_\scaleEspr 2 1
          ^\fermata }
     

     

     Works as expected, fine! Note the use of #{ … #}: Within this Scheme construction, we can use LilyPond syntax, and the function’s arguments (like x-val) are properly expanded. See LilyPond code blocks.

5. The finished code

   Finally, we want to do some clean-up.

   • − We only want scaling in the x-direction, so let’s hard-code y-scaling in the event function.
   • − Delete the color.

   This eventually leads to the following code.

   #(define (longer-script x y)
      (grob-transformer 'stencil
        (lambda (grob orig)
          (ly:stencil-scale orig x y))))
   
   longEspressivo =
   #(define-event-function (x-val) (number?)
     #{
       \tweak stencil #(longer-script x-val 1)
       \espressivo
     #})
   
   { f'^\longEspressivo #2 _\fermata }
   

   

   Voilà!

   The main benefit of using grob-transformer is that we no longer have to take care of the actual name of the stencil function. In the next example we rotate the stencil of a slur and a beam by 90 degrees – that the actual stencil functions are called ly:slur::print and ly:beam::print, respectively, is of no concern here.

   #(define rotate-90
      (grob-transformer 'stencil
        (lambda (grob orig)
          (ly:stencil-rotate orig 90 0 0))))
   
   { f'8( g')
     f'8-\tweak stencil #rotate-90 ( g')
     f'8[ g']
     f'8-\tweak stencil #rotate-90 [ g'] }
   

   

1.3.2 Displaying music expressions

When writing a music function it is often instructive to inspect how a music expression is stored internally. This can be done with the music function \displayMusic.

{
  \displayMusic { c'4\f }
}

will display

(make-music
  'SequentialMusic
  'elements
  (list (make-music
          'NoteEvent
          'articulations
          (list (make-music
                  'AbsoluteDynamicEvent
                  'text
                  "f"))
          'duration
          (ly:make-duration 2 0 1/1)
          'pitch
          (ly:make-pitch 0 0 0))))

By default, LilyPond will print these messages to the console along with all the other messages. To split up these messages and save the results of \display{STUFF}, you can specify an optional output port to use:

{
  \displayMusic #(open-output-file "display.txt") { c'4\f }
}

This will overwrite a previous output file whenever it is called; if you need to write more than one expression, you would use a variable for your port and reuse it:

{
  port = #(open-output-file "display.txt")
  \displayMusic \port { c'4\f }
  \displayMusic \port { d'4 }
  #(close-output-port port)
}

Guile’s manual describes ports in detail. Closing the port is actually only necessary if you need to read the file before LilyPond finishes; in the first example, we did not bother to do so.

A bit of reformatting makes the above information easier to read:

(make-music 'SequentialMusic
  'elements (list
             (make-music 'NoteEvent
               'articulations (list
                               (make-music 'AbsoluteDynamicEvent
                                           'text
                                           "f"))
               'duration (ly:make-duration 2 0 1/1)
               'pitch    (ly:make-pitch 0 0 0))))

A { … } music sequence has the name SequentialMusic, and its inner expressions are stored as a list in its 'elements property. A note is represented as a NoteEvent object (storing the duration and pitch properties) with attached information (in this case, an AbsoluteDynamicEvent with a "f" text property) stored in its articulations property.

\displayMusic returns the music it displays, so it will get interpreted as well as displayed. To avoid interpretation, write \void before \displayMusic.

1.3.3 Music properties

Let’s look at an example:

someNote = c'
\displayMusic \someNote
===>
(make-music
  'NoteEvent
  'duration
  (ly:make-duration 2 0 1/1)
  'pitch
  (ly:make-pitch 0 0 0))

The NoteEvent object is the representation of someNote. Straightforward. How about putting c’ in a chord?

someNote = <c'>
\displayMusic \someNote
===>
(make-music
  'EventChord
  'elements
  (list (make-music
          'NoteEvent
          'duration
          (ly:make-duration 2 0 1/1)
          'pitch
          (ly:make-pitch 0 0 0))))

Now the NoteEvent object is the first object of the 'elements property of someNote.

The display-scheme-music function is the function used by \displayMusic to display the Scheme representation of a music expression.

#(display-scheme-music (first (ly:music-property someNote 'elements)))
===>
(make-music
  'NoteEvent
  'duration
  (ly:make-duration 2 0 1/1)
  'pitch
  (ly:make-pitch 0 0 0))

Then the note pitch is accessed through the 'pitch property of the NoteEvent object.

#(display-scheme-music
   (ly:music-property (first (ly:music-property someNote 'elements))
                      'pitch))
===>
(ly:make-pitch 0 0 0)

The note pitch can be changed by setting this 'pitch property.

#(set! (ly:music-property (first (ly:music-property someNote 'elements))
                          'pitch)
       (ly:make-pitch 0 1 0)) ;; set the pitch to d'.
\displayLilyMusic \someNote
===>
d'4

1.3.4 Doubling a note with slurs (example)

Suppose we want to create a function that translates input like a into { a( a) }. We begin by examining the internal representation of the desired result.

\displayMusic{ a'( a') }
===>
(make-music
  'SequentialMusic
  'elements
  (list (make-music
          'NoteEvent
          'articulations
          (list (make-music
                  'SlurEvent
                  'span-direction
                  -1))
          'duration
          (ly:make-duration 2 0 1/1)
          'pitch
          (ly:make-pitch 0 5 0))
        (make-music
          'NoteEvent
          'articulations
          (list (make-music
                  'SlurEvent
                  'span-direction
                  1))
          'duration
          (ly:make-duration 2 0 1/1)
          'pitch
          (ly:make-pitch 0 5 0))))

The bad news is that the SlurEvent expressions must be added ‘inside’ the note (in its articulations property).

Now we examine the input.

\displayMusic a'
===>
(make-music
  'NoteEvent
  'duration
  (ly:make-duration 2 0 1/1)
  'pitch
  (ly:make-pitch 0 5 0))))

So in our function, we need to clone this expression (so that we have two notes to build the sequence), add a SlurEvent to the 'articulations property of each one, and finally make a SequentialMusic with the two NoteEvent elements. For adding to a property, it is useful to know that an unset property is read out as '(), the empty list, so no special checks are required before we put another element at the front of the articulations property.

doubleSlur = #(define-music-function (note) (ly:music?)
         "Return: { note ( note ) }.
         `note` is supposed to be a single note."
         (let ((note2 (ly:music-deep-copy note)))
           (set! (ly:music-property note 'articulations)
                 (cons (make-music 'SlurEvent 'span-direction -1)
                       (ly:music-property note 'articulations)))
           (set! (ly:music-property note2 'articulations)
                 (cons (make-music 'SlurEvent 'span-direction 1)
                       (ly:music-property note2 'articulations)))
           (make-music 'SequentialMusic 'elements (list note note2))))

1.3.5 Adding articulation to notes (example)

The easy way to add articulation to notes is to juxtapose two music expressions. However, suppose that we want to write a music function that does this.

A $variable inside the #{…#} notation is like a regular \variable in classical LilyPond notation. We could write

{ \music -. -> }

but for the sake of this example, we will learn how to do this in Scheme. We begin by examining our input and desired output.

%  input
\displayMusic c4
===>
(make-music
  'NoteEvent
  'duration
  (ly:make-duration 2 0 1/1)
  'pitch
  (ly:make-pitch -1 0 0))))
=====
%  desired output
\displayMusic c4->
===>
(make-music
  'NoteEvent
  'articulations
  (list (make-music
          'ArticulationEvent
          'articulation-type 'accent))
  'duration
  (ly:make-duration 2 0 1/1)
  'pitch
  (ly:make-pitch -1 0 0))

We see that a note (c4) is represented as a NoteEvent expression. To add an accent articulation, an ArticulationEvent expression must be added to the articulations property of the NoteEvent expression.

To build this function, we begin with

(define (add-accent note-event)
  "Add an accent ArticulationEvent to the articulations of `note-event`,
  which is supposed to be a NoteEvent expression."
  (set! (ly:music-property note-event 'articulations)
        (cons (make-music 'ArticulationEvent
                'articulation-type 'accent)
              (ly:music-property note-event 'articulations)))
  note-event)

The first line is the way to define a function in Scheme: the function name is add-accent, and has one variable called note-event. In Scheme, the type of variable is often clear from its name. (this is good practice in other programming languages, too!)

"Add an accent…"

is a description of what the function does. This is not strictly necessary, but just like clear variable names, it is good practice.

You may wonder why we modify the note event directly instead of working on a copy (ly:music-deep-copy can be used for that). The reason is a silent contract: music functions are allowed to modify their arguments: they are either generated from scratch (like user input) or are already copied (referencing a music variable with ‘\name’ or music from immediate Scheme expressions ‘$(…)’ provides a copy). Since it would be inefficient to create unnecessary copies, the return value from a music function is not copied. So to heed that contract, you must not use any arguments more than once, and returning it counts as one use.

In an earlier example, we constructed music by repeating a given music argument. In that case, at least one repetition had to be a copy of its own. If it weren’t, strange things may happen. For example, if you use \relative or \transpose on the resulting music containing the same elements multiple times, those will be subjected to relativation or transposition multiple times. If you assign them to a music variable, the curse is broken since referencing ‘\name’ will again create a copy which does not retain the identity of the repeated elements.

Now while the above function is not a music function, it will normally be used within music functions. So it makes sense to heed the same contract we use for music functions: the input may be modified for producing the output, and the caller is responsible for creating copies if it still needs the unchanged argument itself. If you take a look at LilyPond’s own functions like music-map, you’ll find that they stick with the same principles.

Where were we? We now have a note-event we may modify, not because of using ly:music-deep-copy but because of a long-winded explanation. We add the accent to its 'articulations list property.

(set! place new-value)

Here, what we want to set (the ‘place’) is the 'articulations property of note-event expression.

(ly:music-property note-event 'articulations)

ly:music-property is the function used to access music properties (the 'articulations, 'duration, 'pitch, etc, that we see in the \displayMusic output above). The new value is the former 'articulations property, with an extra item: the ArticulationEvent expression, which we copy from the \displayMusic output,

(cons (make-music 'ArticulationEvent
        'articulation-type 'accent)
      (ly:music-property result-event-chord 'articulations))

cons is used to add an element to the front of a list without modifying the original list. This is what we want: the same list as before, plus the new ArticulationEvent expression. The order inside the 'articulations property is not important here.

Finally, once we have added the accent articulation to its articulations property, we can return note-event, hence the last line of the function.

Now we transform the add-accent function into a music function (a matter of some syntactic sugar and a declaration of the type of its argument).

addAccent = #(define-music-function (note-event) (ly:music?)
  "Add an accent ArticulationEvent to the articulations of `note-event`,
  which is supposed to be a NoteEvent expression."
  (set! (ly:music-property note-event 'articulations)
        (cons (make-music 'ArticulationEvent
                'articulation-type 'accent)
              (ly:music-property note-event 'articulations)))
  note-event)

We then verify that this music function works correctly:

\displayMusic \addAccent c4

2.2.1 Scheme function definitions

The general form for defining Scheme functions is:

function =
#(define-scheme-function
     (arg1 arg2 …)
     (type1? type2? …)
   body)

where

argN

nth argument.

typeN?

A Scheme type predicate for which argN must return #t. There is also a special form (predicate? default) for specifying optional arguments. If the actual argument is missing when the function is being called, the default value is substituted instead. Default values are evaluated at definition time (including LilyPond code blocks!), so if you need a default calculated at runtime, instead write a special value you can easily recognize. If you write the predicate in parentheses but don’t follow it with a default value, #f is used as the default. Default values are not verified with predicate? at either definition or run time: it is your responsibility to deal with the values you specify. Default values that happen to be music expressions are copied while setting origin to the current input location.

body

A sequence of Scheme forms evaluated in order, the last one being used as the return value of the Scheme function. It may contain LilyPond code blocks enclosed in hashed braces ( #{…#} ), like described in LilyPond code blocks. Within LilyPond code blocks, use ‘#’ to reference function arguments (e.g., #arg1) or to start an inline Scheme expression containing function arguments (e.g., ‘#(cons arg1 arg2)’). Where normal Scheme expressions using ‘#’ don’t do the trick, you might need to revert to immediate Scheme expressions using ‘$’, for example as $music.

If your function returns a music expression, it is given a useful value of origin.

Suitability of arguments for the predicates is determined by actually calling the predicate after LilyPond has already converted them into a Scheme expression. As a consequence, the argument can be specified in Scheme syntax if desired (introduced with ‘#’ or as the result of calling a Scheme function), but LilyPond will also convert a number of LilyPond constructs into Scheme before actually checking the predicate on them. Currently, those include music, postevents, simple strings (with or without quotes), numbers, full markups and markup lists, score, book, bookpart, context definition and output definition blocks.

Some ambiguities LilyPond sorts out by checking with predicate functions: is ‘-3’ a fingering postevent or a negative number? Is "a" 4 in lyric mode a string followed by a number, or a lyric event of duration 4? LilyPond tries the argument predicate on successive interpretations until success, with an order designed to minimize inconsistent interpretations and lookahead.

For example, a predicate accepting both music expressions and pitches will consider c'' to be a pitch rather than a music expression. Immediately following durations or postevents will change that interpretation. It’s best to avoid overly permissive predicates like scheme? when the application rather calls for more specific argument types.

For a list of available predefined type predicates, see Predefined type predicates.

See also

Notation Reference: Predefined type predicates.

Installed Files: lily/music-scheme.cc, scm/c++.scm, scm/lily.scm.

2.2.2 Scheme function usage

Scheme functions can be called pretty much anywhere where a Scheme expression starting with ‘#’ can be written. You call a Scheme function from LilyPond by writing its name preceded by \, followed by its arguments. Once an optional argument predicate does not match an argument, LilyPond skips this and all following optional arguments, replacing them with their specified default, and ‘backs up’ the argument that did not match to the place of the next mandatory argument. Since the backed up argument needs to go somewhere, optional arguments are not actually considered optional unless followed by a mandatory argument.

There is one exception: if you write \default in the place of an optional argument, this and all following optional arguments are skipped and replaced by their default. This works even when no mandatory argument follows since \default does not need to get backed up. The mark and key commands make use of that trick to provide their default behavior when just followed by \default.

Apart from places where a Scheme value is required, there are a few places where ‘#’ expressions are currently accepted and evaluated for their side effects but otherwise ignored. Mostly those are the places where an assignment would be acceptable as well.

Since it is a bad idea to return values that can be misinterpreted in some context, you should use normal Scheme functions only for those cases where you always return a useful value, and use void Scheme functions (see Void Scheme functions) otherwise.

For convenience, Scheme functions may also be called directly from Scheme bypassing the LilyPond parser. Their name can be used like the name of an ordinary function. Typechecking of the arguments and skipping optional arguments will happen in the same manner as when called from within LilyPond, with the Scheme value *unspecified* taking the role of the \default reserved word for explicitly skipping optional arguments. Optional arguments at the end of an argument list can just be omitted without indication when called via Scheme.

2.2.3 Void Scheme functions

Sometimes a procedure is executed in order to perform an action rather than return a value. Some programming languages (like C and Scheme) use functions for either concept and just discard the returned value (usually by allowing any expression to act as statement, ignoring the result). This is clever but error-prone: most C compilers nowadays offer warnings for various non-‘void’ expressions being discarded. For many functions executing an action, the Scheme standards declare the return value to be unspecified. LilyPond’s Scheme interpreter Guile has a unique value *unspecified* that it usually (such when using set! directly on a variable) but unfortunately not consistently returns in such cases.

Defining a LilyPond function with define-void-function makes sure that this special value (the only value satisfying the predicate void?) will be returned.

noPointAndClick =
#(define-void-function
     ()
     ()
   (ly:set-option 'point-and-click #f))
…
\noPointAndClick   % disable point and click

If you want to evaluate an expression only for its side-effect and don’t want any value it may return interpreted, you can do so by prefixing it with \void:

\void #(hashq-set! some-table some-key some-value)

That way, you can be sure that LilyPond will not assign meaning to the returned value regardless of where it encounters it. This will also work for music functions such as \displayMusic.

2.3.1 Music function definitions

The general form for defining music functions is:

function =
#(define-music-function
     (arg1 arg2 …)
     (type1? type2? …)
   body)

quite in analogy to Scheme function definitions. More often than not, body will be a LilyPond code block.

For a list of available type predicates, see Predefined type predicates.

See also

Notation Reference: Predefined type predicates.

Installed Files: lily/music-scheme.cc, scm/c++.scm, scm/lily.scm.

2.3.2 Music function usage

With regard to handling the argument list, music functions don’t differ from Scheme functions, Scheme function usage.

A ‘music function’ has to return an expression matching the predicate ly:music?. This makes music function calls suitable as arguments of type ly:music? for another music function call.

When using a music function call in other contexts, the context may cause further semantic restrictions.

• At the top level in a music expression a post-event is not accepted.
• When a music function (as opposed to an event function) returns an expression of type post-event, LilyPond requires one of the named direction indicators (-, ^, and _) in order to properly integrate the post-event produced by the music function call into the surrounding expression.
• As a chord constituent. The returned expression must be of a rhythmic-event type, most likely a NoteEvent.

‘Polymorphic’ functions, like \tweak, can be applied to post-events, chord constituent and top level music expressions.

2.3.3 Simple substitution functions

Simple substitution functions are music functions whose output music expression is written in LilyPond format and contains function arguments in the output expression. They are described in Substitution function examples.

2.3.4 Intermediate substitution functions

Intermediate substitution functions involve a mix of Scheme code and LilyPond code in the music expression to be returned.

Some \override commands require an argument consisting of a pair of numbers (called a cons cell in Scheme).

The pair can be directly passed into the music function, using a pair? variable:

manualBeam =
#(define-music-function
     (beg-end)
     (pair?)
   #{
     \once \override Beam.positions = #beg-end
   #})

\relative c' {
  \manualBeam #'(3 . 6) c8 d e f
}

Alternatively, the numbers making up the pair can be passed as separate arguments, and the Scheme code used to create the pair can be included in the music expression:

manualBeam =
#(define-music-function
     (beg end)
     (number? number?)
   #{
     \once \override Beam.positions = #(cons beg end)
   #})

\relative c' {
  \manualBeam #3 #6 c8 d e f
}

Properties are maintained conceptually using one stack per property per grob per context. Music functions may need to override one or several properties for the duration of the function, restoring them to their previous value before exiting. However, normal overrides pop and discard the top of the current property stack before pushing to it, so the previous value of the property is lost when it is overridden. When the previous value must be preserved, prefix the \override command with \temporary, like this:

\temporary \override …

The use of \temporary causes the (usually set) pop-first property in the override to be cleared, so the previous value is not popped off the property stack before pushing the new value onto it. When a subsequent \revert pops off the temporarily overriden value, the previous value will re-emerge.

In other words, calling \temporary \override and \revert in succession on the same property will have a net effect of zero. Similarly, pairing \temporary and \undo on the same music containing overrides will have a net effect of zero.

Here is an example of a music function which makes use of this. The use of \temporary ensures the values of the cross-staff and style properties are restored on exit to whatever values they had when the crossStaff function was called. Without \temporary the default values would have been set on exit.

crossStaff =
#(define-music-function (notes) (ly:music?)
  (_i "Create cross-staff stems")
  #{
  \temporary \override Stem.cross-staff = #cross-staff-connect
  \temporary \override Flag.style = #'no-flag
  #notes
  \revert Stem.cross-staff
  \revert Flag.style
#})

2.3.5 Mathematics in functions

Music functions can involve Scheme programming in addition to simple substitution,

AltOn =
#(define-music-function
     (mag)
     (number?)
   #{
     \override Stem.length = #(* 7.0 mag)
     \override NoteHead.font-size =
       #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
   #})

AltOff = {
  \revert Stem.length
  \revert NoteHead.font-size
}

\relative {
  c'2 \AltOn #0.5 c4 c
  \AltOn #1.5 c c \AltOff c2
}

This example may be rewritten to pass in music expressions,

withAlt =
#(define-music-function
     (mag music)
     (number? ly:music?)
   #{
     \override Stem.length = #(* 7.0 mag)
     \override NoteHead.font-size =
       #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
     #music
     \revert Stem.length
     \revert NoteHead.font-size
   #})

\relative {
  c'2 \withAlt #0.5 { c4 c }
  \withAlt #1.5 { c c } c2
}

2.3.6 Functions without arguments

In most cases a function without arguments should be written with a variable,

dolce = \markup{ \italic \bold dolce }

However, in rare cases it may be useful to create a music function without arguments,

displayBarNum =
#(define-music-function
     ()
     ()
   (if (eq? #t (ly:get-option 'display-bar-numbers))
       #{ \once \override Score.BarNumber.break-visibility = ##f #}
       #{#}))

To actually display bar numbers where this function is called, invoke lilypond with

lilypond -d display-bar-numbers FILENAME.ly

2.3.7 Void music functions

A music function must return a music expression. If you want to execute a function only for its side effect, you should use define-void-function. But there may be cases where you sometimes want to produce a music expression, and sometimes not (like in the previous example). Returning a void music expression via #{ #} will achieve that.

2.5.1 Markup construction in Scheme

Markup expressions are internally represented in Scheme using the markup macro:

(markup expr)

To see a markup expression in its Scheme form, use the \displayScheme command:

\displayScheme
\markup {
  \column {
    \line { \bold \italic "hello" \raise #0.4 "world" }
    \larger \line { foo bar baz }
  }
}

Compiling the code above will send the following to the display console:

(markup
  #:line
  (#:column
   (#:line
    (#:bold (#:italic "hello") #:raise 0.4 "world")
    #:larger
    (#:line ("foo" "bar" "baz")))))

To prevent the markup from printing on the page, use ‘\void \displayScheme markup’. Also, as with the \displayMusic command, the output of \displayScheme can be saved to an external file. See Displaying music expressions.

This example demonstrates the main translation rules between regular LilyPond markup syntax and Scheme markup syntax. Using #{ … #} for entering in LilyPond syntax will often be most convenient, but we explain how to use the markup macro to get a Scheme-only solution.

LilyPond	Scheme
\markup markup1	(markup markup1)
\markup { markup1 markup2 … }	(markup markup1 markup2 …)
\markup-command	#:markup-command
\variable	variable
\center-column { … }	#:center-column (…)
string	"string"
#scheme-arg	scheme-arg

The whole Scheme language is accessible inside the markup macro. For example, You may use function calls inside markup in order to manipulate character strings. This is useful when defining new markup commands (see New markup command definition).

Known issues and warnings

The markup-list argument of commands such as #:line, #:center-column, and #:column cannot be a variable or the result of a function call.

(markup #:line (function-that-returns-markups))

is invalid. One should use the make-line-markup, make-center-column-markup, or make-column-markup functions instead,

(markup (make-line-markup (function-that-returns-markups)))

2.5.2 How markups work internally

In a markup like

\raise #0.5 "text example"

\raise is actually represented by the raise-markup function. The markup expression is stored as

(list raise-markup 0.5 "text example")

When the markup is converted to printable objects (Stencils), the raise-markup function is called as

(apply raise-markup
       \layout object
       list of property alists
       0.5
       the "text example" markup)

The raise-markup function first creates the stencil for the text example string, and then it raises that Stencil by 0.5 staff space. This is a rather simple example; more complex examples are in the rest of this section, and in scm/define-markup-commands.scm.

2.5.3 New markup command definition

This section discusses the definition of new markup commands.

(define-markup-command (command-name layout props arg1 arg2 …)
    (arg1-type? arg2-type? …)
    [ #:properties ((property1 default-value1)
                    …) ]
    [ #:as-string expression ]
  …command body…)

(ly:output-def-lookup layout 'line-width)

#(define-markup-command (double-box layout props text) (markup?)
  "Draw a double box around text."
  (interpret-markup layout props
    #{\markup \override #'(box-padding . 0.4) \box
            \override #'(box-padding . 0.6) \box { #text }#}))

#(define-markup-command (double-box layout props text) (markup?)
  "Draw a double box around text."
  (interpret-markup layout props
    (markup #:override '(box-padding . 0.4) #:box
            #:override '(box-padding . 0.6) #:box text)))

\markup \double-box A

#(define-markup-command (double-box layout props text) (markup?)
  #:properties ((inter-box-padding 0.4)
                (box-padding 0.6))
  "Draw a double box around text."
  (interpret-markup layout props
    #{\markup \override #`(box-padding . ,inter-box-padding) \box
               \override #`(box-padding . ,box-padding) \box
               { #text } #}))

#(define-markup-command (double-box layout props text) (markup?)
  #:properties ((inter-box-padding 0.4)
                (box-padding 0.6))
  "Draw a double box around text."
  (interpret-markup layout props
    (markup #:override `(box-padding . ,inter-box-padding) #:box
            #:override `(box-padding . ,box-padding) #:box text)))

(define-markup-command (draw-line layout props dest)
  (number-pair?)
  #:category graphic
  #:properties ((thickness 1))
  "…documentation…"
  (let ((th (* (ly:output-def-lookup layout 'line-thickness)
               thickness))
        (x (car dest))
        (y (cdr dest)))
    (make-line-stencil th 0 0 x y)))

(define-markup-command (draw-double-line layout props dest)
  (number-pair?)
  #:properties ((thickness 1))
  "…documentation…"
  (let ((th (* (ly:output-def-lookup layout 'line-thickness)
               thickness))
        (x (car dest))
        (y (cdr dest)))
    (make-line-stencil th 0 0 x y)))

(define-markup-command (draw-double-line layout props dest)
  (number-pair?)
  #:properties ((thickness 1)
                (line-gap 0.6))
  "…documentation…"
  …

2.5.4 New markup list command definition

Markup list commands are defined with the define-markup-list-command Scheme macro, which is similar to the define-markup-command macro described in New markup command definition, except that where the latter returns a single stencil, the former returns a list of stencils.

In a similar vein, interpret-markup-list is used instead of interpret-markup for converting a markup list into a list of stencils.

In the following example, a \paragraph markup list command is defined, which returns a list of justified lines, the first one being indented. The indent width is taken from the props argument.

#(define-markup-list-command (paragraph layout props args) (markup-list?)
   #:properties ((par-indent 2))
   (interpret-markup-list layout props
     #{\markuplist \justified-lines { \hspace #par-indent #args } #}))

The version using just Scheme is more complex:

#(define-markup-list-command (paragraph layout props args) (markup-list?)
   #:properties ((par-indent 2))
   (interpret-markup-list layout props
     (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
                                             args))))

Besides the usual layout and props arguments, the paragraph markup list command takes a markup list argument, named args. The predicate for markup lists is markup-list?.

First, the function gets the indent width, a property here named par-indent, from the property list props. If the property is not found, the default value is 2. Then, a list of justified lines is made using the built-in markup list command \justified-lines, which is related to the make-justified-lines-markup-list function. A horizontal space is added at the beginning using \hspace (or the make-hspace-markup function). Finally, the markup list is interpreted using the interpret-markup-list function.

This new markup list command can be used as follows:

\markuplist {
  \paragraph {
    The art of music typography is called \italic {(plate) engraving.}
    The term derives from the traditional process of music printing.
    Just a few decades ago, sheet music was made by cutting and stamping
    the music into a zinc or pewter plate in mirror image.
  }
  \override-lines #'(par-indent . 4) \paragraph {
    The plate would be inked, the depressions caused by the cutting
    and stamping would hold ink.  An image was formed by pressing paper
    to the plate.  The stamping and cutting was completely done by
    hand.
  }
}

2.6.1 Context evaluation

Contexts can be modified during interpretation with Scheme code. In a LilyPond code block, the syntax for this is:

\applyContext function

In Scheme code, the syntax is:

(make-apply-context function)

function should be a Scheme function that takes a single argument: the context in which the \applyContext command is being called. The function can access as well as override/set grob properties and context properties. Any actions taken by the function that depend on the state of the context are limited to the state of the context when the function is called. Also, changes effected by a call to \applyContext remain in effect until they are directly modified again, or reverted, even if the initial conditions that they depended on have changed.

The following Scheme functions are useful when using \applyContext:

ly:context-property

look up a context property value

ly:context-set-property!

set a context property

ly:context-grob-definition

ly:assoc-get

look up a grob property value

ly:context-pushpop-property

do a \temporary \override or a \revert on a grob property

The following example looks up the current fontSize value, and then doubles it:

doubleFontSize =
\applyContext
  #(lambda (context)
     (let ((fontSize (ly:context-property context 'fontSize)))
       (ly:context-set-property! context 'fontSize (+ fontSize 6))))

{
  \set fontSize = -3
  b'4
  \doubleFontSize
  b'
}

The following example looks up the current colors of the NoteHead, Stem, and Beam grobs, and then changes each to a less saturated shade.

desaturate =
\applyContext
  #(lambda (context)
     (define (desaturate-grob grob)
       (let* ((grob-def (ly:context-grob-definition context grob))
              (color (ly:assoc-get 'color grob-def black))
              (new-color (map (lambda (x) (min 1 (/ (1+ x) 2))) color)))
         (ly:context-pushpop-property context grob 'color new-color)))
     (for-each desaturate-grob '(NoteHead Stem Beam)))

\relative {
  \time 3/4
  g'8[ g] \desaturate g[ g] \desaturate g[ g]
  \override NoteHead.color = #darkred
  \override Stem.color = #darkred
  \override Beam.color = #darkred
  g[ g] \desaturate g[ g] \desaturate g[ g]
}

This also could be implemented as a music function, in order to restrict the modifications to a single music block. Notice how ly:context-pushpop-property is used both as a \temporary \override and as a \revert:

desaturate =
#(define-music-function
   (music) (ly:music?)
   #{
     \applyContext
     #(lambda (context)
        (define (desaturate-grob grob)
          (let* ((grob-def (ly:context-grob-definition context grob))
                 (color (ly:assoc-get 'color grob-def black))
                 (new-color (map (lambda (x) (min 1 (/ (1+ x) 2))) color)))
            (ly:context-pushpop-property context grob 'color new-color)))
        (for-each desaturate-grob '(NoteHead Stem Beam)))
     #music
     \applyContext
     #(lambda (context)
        (define (revert-color grob)
          (ly:context-pushpop-property context grob 'color))
        (for-each revert-color '(NoteHead Stem Beam)))
   #})

\relative {
  \override NoteHead.color = #darkblue
  \override Stem.color = #darkblue
  \override Beam.color = #darkblue
  g'8 a b c
  \desaturate { d c b a }
  g b d b g2
}

2.6.2 Running a function on all layout objects

The most versatile way of tuning an object is \applyOutput which works by inserting an event into the specified context (ApplyOutputEvent). Its syntax is either

\applyOutput Context proc

or

\applyOutput Context.Grob proc

where proc is a Scheme function, taking three arguments.

When interpreted, the function proc is called for every layout object (with grob name Grob if specified) found in the context Context at the current time step, with the following arguments:

• the layout object itself,
• the context where the layout object was created, and
• the context where \applyOutput is processed.

In addition, the cause of the layout object, i.e., the music expression or object that was responsible for creating it, is in the object property cause. For example, for a note head, this is a NoteHead event, and for a stem object, this is a Stem object.

Here is a function to use for \applyOutput; it blanks note-heads on the center-line and next to it:

#(define (blanker grob grob-origin context)
   (if (< (abs (ly:grob-property grob 'staff-position)) 2)
       (set! (ly:grob-property grob 'transparent) #t)))

\relative {
  a'4 e8 <<\applyOutput Voice.NoteHead #blanker a c d>> b2
}

To have function interpreted at the Score or Staff level use these forms

\applyOutput Score…
\applyOutput Staff…