A.12.3 Graphical markup

\arrow-head axis (integer) dir (direction) filled (boolean) ¶

Print an arrow head along axis in direction dir.

Fill the head if filled is set to #t.

\markup {
  \fontsize #5 {
    \general-align #Y #DOWN {
      \arrow-head #Y #UP ##t
      \arrow-head #Y #DOWN ##f
      \hspace #2
      \arrow-head #X #RIGHT ##f
      \arrow-head #X #LEFT ##f
    }
  }
}

\beam width (number) slope (number) thickness (number) ¶

Draw a beam with given width, slope, and thickness.

\markup {
  \beam #5 #1 #2
}

\bracket arg (markup) ¶

Draw vertical brackets around arg.

\markup {
  \bracket {
    \note {2.} #UP
  }
}

\circle arg (markup) ¶

Draw a circle around arg.

Use properties thickness, circle-padding, and font-size to set the line thickness and padding around the markup.

\markup {
  \circle {
    Hi
  }
}

Used properties:

• circle-padding (0.2)
• font-size (0)
• thickness (1)

\draw-circle radius (number) thickness (number) filled (boolean) ¶

Draw a circle with given radius and thickness.

Fill the circle if filled is set to #t.

\markup {
  \draw-circle #2 #0.5 ##f
  \hspace #2
  \draw-circle #2 #0 ##t
}

\draw-dashed-line dest (pair of numbers) ¶

Draw a dashed line along vector dest.

Properties on and off give the length of a dash and the space between two dashes, respectively; phase shortens the first dash by the given amount.

If the full-length property is set to #t (which is the default), the value of property off (and on under some boundary conditions) gets adjusted so that there is neither whitespace at the end of the line nor the last dash truncated.

\markup {
  \override #'((on . 0.3) (off . 0.5))
  \draw-dashed-line #'(6 . 2)

  \draw-dashed-line #'(6 . 2)

  \override #'(full-length . #f)
  \draw-dashed-line #'(6 . 2)

  \override #'(phase . 0.5)
  \draw-dashed-line #'(6 . 2)

  \override #'((full-length . #f) (phase . 0.5))
  \draw-dashed-line #'(6 . 2)
}

Used properties:

• full-length (#t)
• phase (0)
• off (1)
• on (1)
• thickness (1)

\draw-dotted-line dest (pair of numbers) ¶

Draw a dotted line along vector dest.

Property off gives the space between two dots; its value gets adjusted so that the first and last dot exactly start and end the line, respectively. phase shifts all dots along the vector by the given amount.

\markup {
  \draw-dotted-line #'(5.1 . 2.3)
  \override #'((thickness . 2) (off . 0.2))
  \draw-dotted-line #'(5.1 . 2.3)
}

Used properties:

• phase (0)
• off (1)
• thickness (1)

\draw-hline ¶

Draw a horizontal line.

The property span-factor sets the length of the line as a multiple of the line-width property.

\markup {
  \column {
    \draw-hline
    \override #'(span-factor . 1/3)
    \draw-hline
  }
}

Used properties:

• span-factor (1)
• line-width
• thickness (1)

\draw-line dest (pair of numbers) ¶

Draw a line along vector dest.

\markup {
  \draw-line #'(4 . 4)
  \override #'(thickness . 5)
  \draw-line #'(-3 . 0)
}

Used properties:

• thickness (1)

\draw-squiggle-line sq-length (number) dest (pair of numbers) eq-end? (boolean) ¶

Draw a squiggled line along vector dest.

sq-length is the length of the first bow; this value gets always adjusted so that an integer number of squiggles is printed. If eq-end? is set to #t, the squiggled line ends with a bow in the same direction as the starting one.

The appearance of the squiggled line may be customized by overriding the thickness, angularity, height, and orientation properties.

\markup
  \column {
    \draw-squiggle-line #0.5 #'(6 . 0) ##t
    \override #'(orientation . -1)
    \draw-squiggle-line #0.5 #'(6 . 0) ##t
    \draw-squiggle-line #0.5 #'(6 . 0) ##f
    \override #'(height . 1)
    \draw-squiggle-line #0.5 #'(6 . 0) ##t
    \override #'(thickness . 5)
    \draw-squiggle-line #0.5 #'(6 . -2) ##t
    \override #'(angularity . 2)
    \draw-squiggle-line #0.5 #'(6 . 2) ##t
  }

Used properties:

• orientation (1)
• height (0.5)
• angularity (0)
• thickness (0.5)

\ellipse arg (markup) ¶

Draw an ellipse around arg.

Use properties thickness, x-padding, y-padding, and font-size to set the line thickness and padding around the markup.

This is the same as function \oval but with different padding defaults.

\markup {
  \ellipse {
    Hi
  }
}

Used properties:

• y-padding (0.2)
• x-padding (0.2)
• font-size (0)
• thickness (1)

\epsfile axis (number) size (number) file-name (string) ¶

Inline an image file-name, scaled along axis to size.

See \image for details on this command; calling

\markup \epsfile axis size file-name

is the same as

\markup
  \override #'(background-color . #f)
  \image axis size file-name

\filled-box xext (pair of numbers) yext (pair of numbers) blot (number) ¶

Draw a box of dimensions xext and yext, with rounded corners given by blot.

For example,

\filled-box #'(-.3 . 1.8) #'(-.3 . 1.8) #0

creates a box extending horizontally from -0.3 to 1.8 and vertically from -0.3 up to 1.8, with corners formed from a circle of diameter 0 (i.e., sharp corners).

\markup {
  \filled-box #'(0 . 4) #'(0 . 4) #0
  \filled-box #'(0 . 2) #'(-4 . 2) #0.4
  \combine
    \filled-box #'(1 . 8) #'(0 . 7) #0.2
    \with-color #white
      \filled-box #'(3.6 . 5.6) #'(3.5 . 5.5) #0.7
}

\hbracket arg (markup) ¶

Draw horizontal brackets around arg.

\markup {
  \hbracket {
    \line {
      one two three
    }
  }
}

\image axis (number) size (number) file-name (string) ¶

Inline an image file-name, scaled along axis to size.

The image format is determined based on the extension of file-name, which should be .png for a PNG image, or .eps for an EPS image (.PNG and .EPS are allowed as well).

EPS files are only supported in the PostScript backend – for all output formats –, and in the Cairo backend – when creating PostScript or EPS output.

If the image has transparency, it will appear over a colored background with the color specified by the background-color property, which defaults to "white".

To disable the colored background, set background-color to #f. For EPS images, this always works (where EPS images work in the first place). On the other hand, for PNG images, it works in the Cairo backend (which can output all supported formats), as well as in the SVG backend, but not in the PostScript backend, which is the default. See Advanced command-line options for LilyPond for how to activate the Cairo backend.

Use \withRelativeDir as a prefix to file-name if the file should be found relative to the input file.

Used properties:

• background-color ("white")

\oval arg (markup) ¶

Draw an oval around arg.

Use properties thickness, x-padding, y-padding, and font-size to set the line thickness and padding around the markup.

This is the same as function \ellipse but with different padding defaults.

\markup {
  \oval {
    Hi
  }
}

Used properties:

• y-padding (0.75)
• x-padding (0.75)
• font-size (0)
• thickness (1)

\parenthesize arg (markup) ¶

Draw parentheses around arg.

This is useful for parenthesizing a column containing several lines of text.

\markup {
  \parenthesize
  \column {
    foo
    bar
  }
  \override #'(angularity . 2)
  \parenthesize
  \column {
    bah
    baz
  }
}

Used properties:

• width (0.25)
• line-thickness (0.1)
• thickness (1)
• size (1)
• padding
• angularity (0)

\path thickness (number) commands (list) ¶

Draw a path with line thickness according to the directions given in commands.

commands is a list of lists where the car of each sublist is a drawing command and the cdr comprises the associated arguments for each command.

There are seven commands available to use in commands: moveto, rmoveto, lineto, rlineto, curveto, rcurveto, and closepath. Note that the commands that begin with ‘r’ are the relative variants of the other three commands. You may also use the standard SVG single-letter equivalents: moveto = M, lineto = L, curveto = C, closepath = Z. The relative commands are written lowercase: rmoveto = r, rlineto = l, rcurveto = c.

The commands moveto, rmoveto, lineto, and rlineto take 2 arguments, namely the X and Y coordinates of the destination point.

The commands curveto and rcurveto create cubic Bézier curves, and take 6 arguments; the first two are the X and Y coordinates for the first control point, the second two are the X and Y coordinates for the second control point, and the last two are the X and Y coordinates for the destination point.

The closepath command takes zero arguments and closes the current subpath in the active path.

Line-cap styles and line-join styles may be customized by overriding the line-cap-style and line-join-style properties, respectively. Available line-cap styles are butt, round, and square. Available line-join styles are miter, round, and bevel.

The property filled specifies whether or not the path is filled with color.

samplePath =
  #'((lineto -1 1)
     (lineto 1 1)
     (lineto 1 -1)
     (curveto -5 -5 -5 5 -1 0)
     (closepath))

\markup \scale #'(2 . 2) {
  \path #0.25 #samplePath

  \override #'(line-join-style . miter)
  \path #0.25 #samplePath

  \override #'(filled . #t)
  \path #0.25 #samplePath
}

Used properties:

• filled (#f)
• line-join-style (round)
• line-cap-style (round)

\polygon points (list of number pairs) ¶

A polygon delimited by the list of points.

Property extroversion defines how the shape of the polygon is adapted to its thickness: if it is 0, the polygon is traced as-is. If it is -1, the outer side of the line is just on the given points. If set to 1, the line has its inner side on the points. The thickness property controls the thickness of the line; for filled polygons, this means the diameter of the blot.

regularPentagon =
  #'((1 . 0) (0.31 . 0.95) (-0.81 . 0.59)
     (-0.81 . -0.59) (0.31 . -0.95))

\markup \scale #'(2 . 2) {
  \polygon #'((-1 . -1) (0 . -3) (2 . 2) (1 . 2))
  \override #'(filled . #f)
    \override #'(thickness . 2)
      \combine
        \with-color #(universal-color 'blue)
          \polygon #regularPentagon
        \with-color #(universal-color 'vermillion)
          \override #'(extroversion . 1)
            \polygon #regularPentagon
}

Used properties:

• thickness (1)
• filled (#t)
• extroversion (0)

\postscript str (string) ¶

Insert str directly into the output as a PostScript command string.

This command is meant as a last resort. Almost all needs are better fulfilled by other markup commands (see, for example, \path and \draw-line). If you do use this command, keep the following points in mind:

• \postscript does not work in SVG output.
• Only a subset of the PostScript language is supported during the conversion from PostScript to PDF.
• There are no stability guarantees on the details of how LilyPond produces its own output (i.e., the context into which the PostScript code is inserted). They may change substantially across versions.
• LilyPond cannot understand the shape of the drawing, leading to suboptimal spacing. Usually, it is necessary to explicitly set up dimensions with a command like \with-dimensions.
• Depending on how you install LilyPond, the version of the PostScript interpreter (Ghostscript) can vary, and some of its features may be disabled.

str is processed with the following constraints.

• The string is embedded into the (intermediate) output file with the PostScript commands

  gsave currentpoint translate 0.1 setlinewidth
  

  before and

  grestore
  

  after it.

• After these preceding commands (i.e., currentpoint translate) the origin of the current transformation is the reference point of \postscript. Scale and rotation of the current transformation reflect the global staff line distance and (if applied) other transformation markup commands (e.g., \scale and \rotate) encapsulating the \postscript command.
• The current point is set to the coordinate (0, 0).
• If an unwanted line appears at the beginning of your PostScript code, you are probably missing a call to newpath.

ringsps = "
  0.15 setlinewidth
  0.9 0.6 moveto
  0.4 0.6 0.5 0 361 arc
  stroke
  1.0 0.6 0.5 0 361 arc
  stroke
  "

rings = \markup {
  \with-dimensions #'(-0.2 . 1.6) #'(0 . 1.2)
  \postscript #ringsps
}

\relative c'' {
  c2^\rings
  a2_\rings
}

\rounded-box arg (markup) ¶

Draw a box with rounded corners around arg.

This function looks at properties thickness, box-padding, and font-size to determine the line thickness and padding around the arg. The corner-radius property defines the radius of the round corners (default value is 1).

c4^\markup {
  \rounded-box {
    Overtura
  }
}
c,8. c16 c4 r

Note that the box does not horizontally displace its argument. Use markup commands like \left-align or \table to make LilyPond realign it.

\markup {
  \override #'(box-padding . 1.5)
  \column {
    "text"
    \rounded-box "text"
    \left-align \rounded-box "text"
  }
}

Used properties:

• box-padding (0.5)
• font-size (0)
• corner-radius (1)
• thickness (1)

\scale factor-pair (pair of numbers) arg (markup) ¶

Scale arg.

factor-pair is a pair of numbers representing the scaling factor of the X and Y axes. Negative values may be used to produce mirror images.

\markup {
  \line {
    \scale #'(2 . 1)
    stretched
    \scale #'(1 . -1)
    mirrored
  }
}

\triangle filled (boolean) ¶

Draw a triangle.

Fill the triangle if filled is set to #t.

The appearance can be controlled with properties extroversion, font-size, and thickness.

\markup {
  \triangle ##t
  \triangle ##f
  \override #'(font-size . 5)
  \override #'(thickness . 5) {
    \override #'(extroversion . 1)
    \triangle ##f
    \override #'(extroversion . -1)
    \triangle ##f
  }
}

Used properties:

• thickness (1)
• font-size (0)
• extroversion (0)

\with-url url (string) arg (markup) ¶

Add a link to URL url around arg.

This only works in the PDF backend.¹³

\markup {
  \with-url "https://lilypond.org/" {
    LilyPond ... \italic {
      music notation for everyone
    }
  }
}