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.


Extending LilyPond v2.25.14 (development-branch).