Skip to contents

Save score to LilyPond file

Source: R/lilypond.R
lilypond.Rd

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.

Value

nothing returned; a file is written.

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.

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

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

if (FALSE) { # \dontrun{
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)
} # }