lilypond: Save score to LilyPond file

In tabr: Music Notation Syntax, Manipulation, Analysis and Transcription in R

Save score to LilyPond file

Description

Write a score to a LilyPond format (.ly) text file for later use by LilyPond or subsequent editing outside of R.

Usage

lilypond(
  score,
  file,
  key = "c",
  time = "4/4",
  tempo = "2 = 60",
  header = NULL,
  paper = NULL,
  string_names = NULL,
  endbar = "|.",
  midi = TRUE,
  colors = NULL,
  crop_png = TRUE,
  simplify = TRUE
)

Arguments

score	a score object.
file	character, LilyPond output file ending in .ly. May include an absolute or relative path.
key	character, key signature, e.g., c, b_, f#m, etc.
time	character, defaults to "4/4".
tempo	character, defaults to "2 = 60". Set to NA or NULL to suppress metronome mark in output. If suppressed and midi = TRUE, an error is thrown.
header	a named list of arguments passed to the header of the LilyPond file. See details.
paper	a named list of arguments for the LilyPond file page layout. See details.
string_names	label strings at beginning of tab staff. NULL (default) for non-standard tunings only, TRUE or FALSE for force on or off completely.
endbar	character, the global end bar.
midi	logical, add midi inclusion specification to LilyPond file.
colors	a named list of LilyPond element color overrides. See details.
crop_png	logical, alter template for cropped height. See details.
simplify	logical, uses simplify_phrase() to convert to simpler, more efficient LilyPond syntax.

Details

This function only writes a LilyPond file to disk. It does not require a LilyPond installation. It checks for the version number of an installation, but LilyPond is not required to be found.

This function can be used directly but is commonly used by ⁠render_*⁠ functions, which call this function internally to create the LilyPond file and then call LilyPond to render that file to sheet music.

Value

nothing returned; a file is written.

Header options

All header list elements are character strings. The options for header include the following.

• title

• subtitle

• composer

• album

• arranger

• instrument

• meter

• opus

• piece

• poet

• copyright

• tagline

Paper options

All paper list elements are numeric except page_numbers and print_first_page_number, which are logical. page_numbers = FALSE suppresses all page numbering. When page_numbers = TRUE, you can set print_first_page_number = FALSE to suppress printing of only the first page number. first_page_number is the number of the first page, defaulting to 1, and determines all subsequent page numbers. These arguments correspond to LilyPond paper block variables.

The options for paper include the following and have the following default values if not provided.

• textheight = 220

• linewidth = 150

• indent = 0

• fontsize = 10

• page_numbers = TRUE

• print_first_page_number = TRUE

• first_page_number = 1

PNG-related options

By default crop_png = TRUE. This alters the template so that when the LilyPond output file is created, it contains specifications for cropping the image to the content when that file is rendered by LilyPond to png. The image will have its width and height automatically cropped rather than retain the standard page dimensions. This only applies to png outputs made from the LilyPond file, not pdf. The argument is also ignored if explicitly providing textheight to paper. You may still provide linewidth to paper if you find you need to increase it beyond the default 150mm, generally as a result of using a large fontsize. Various ⁠render_*⁠ functions that wrap lilypond make use of this argument as well.

Color options

You can provide a named list of global color overrides for various sheet music elements with the colors argument of lilypond or one of the associated rendering functions.

By default, everything is black. Overrides are only inserted into the generated LilyPond file if given. Values are character; either the hex color or a named R color. The named list options include the following.

• color

• background

• staff

• time

• key

• clef

• bar

• beam

• head

• stem

• accidental

• slur

• tabhead

• lyrics

color is a global font color for the entire score. It affects staff elements and header elements. It does not affect everything, e.g., page numbers. background controls the background color of the entire page. Do not use this if making a transparent background png with the transparent argument available in the various ⁠render_*⁠ functions. The other options are also global but override color. You can change the color of elements broadly with color and then change the color of specific elements using the other options.

There are currently some limitations. Specifically, if you provide any background color override, most header elements will not display.

See Also

tab(), render_chordchart(), midily()

Examples

## Not run: 
x <- phrase("c ec'g' ec'g'", "4 4 2", "5 432 432")
x <- track(x)
x <- score(x)
outfile <- file.path(tempdir(), "out.ly")
lilypond(x, outfile, midi = FALSE)

## End(Not run)

tabr documentation built on Aug. 8, 2025, 7:30 p.m.