Render sheet music with LilyPond

Source: R/lp_render.R

Render sheet music/tablature from a music score with LilyPond.

tab(
  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,
  transparent = FALSE,
  res = 150,
  keep_ly = FALSE,
  simplify = TRUE,
  details = FALSE
)

render_tab(
  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,
  transparent = FALSE,
  res = 150,
  keep_ly = FALSE,
  simplify = TRUE,
  details = FALSE
)

render_score(
  score,
  file,
  key = "c",
  time = "4/4",
  tempo = "2 = 60",
  header = NULL,
  paper = NULL,
  endbar = "|.",
  colors = NULL,
  crop_png = TRUE,
  transparent = FALSE,
  res = 150,
  keep_ly = FALSE,
  simplify = TRUE,
  details = FALSE
)

render_midi(score, file, key = "c", time = "4/4", tempo = "2 = 60")

Arguments

score

a score object.

file

character, output file ending in .pdf or .png for sheet music or tablature for score(). May include an absolute or relative path. For render_midi(), a file ending in .mid.

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 NULL to suppress display of the time signature in the output.

header

a named list of arguments passed to the header of the LilyPond file. See lilypond() for details.

paper

a named list of arguments for the LilyPond file page layout. See lilypond() for 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, output midi file in addition to sheet music.

colors

a named list of LilyPond element color overrides. See lilypond() for details.

crop_png

logical, see lilypond() for details.

transparent

logical, transparent background, png only.

res

numeric, resolution, png only. transparent = TRUE may fail when res exceeds ~150.

keep_ly

logical, keep the intermediary LilyPond file.

simplify

logical, uses simplify_phrase() to convert to simpler, more efficient LilyPond syntax for the LilyPond file before rendering it.

details

logical, set to TRUE to print LilyPond log output to console. Windows only.

Value

nothing returned; a file is written.

Details

Generate a pdf or png of a music score using the LilyPond music engraving program. Output format is inferred from file extension. This function is a wrapper around lilypond(), the function that creates the LilyPond (.ly) file.

render_score() renders score() to pdf or png. render_midi() renders a MIDI file based on score(). This is still done via LilyPond. The sheet music is created automatically in the process behind the scenes but is deleted and only the MIDI output is retained.

tab() or render_tab() (equivalent) produces both the sheet music and the MIDI file output by default and includes other arguments such as the tablature-relevant argument string_names. This is the all-purpose function. Also use this when you intend to create both a sheet music document and a MIDI file.

Remember that whether a track contains a tablature staff, standard music staff, or both, is defined in each individual track object contained in score(). It is the contents you have assembled inscore() that dictate what render function you should use. render_tab() is general and always works, but render_score() would not be the best choice when a tablature staff is present unless you accept the default string naming convention.

render_midi() is different from midily() and miditab(), whose purpose is to create sheet music from an existing MIDI file using a LilyPond command line utility.

For Windows users, add the path to the LilyPond executable to the system path variable. For example, if the file is at C:/lilypond-2.24.2/bin/lilypond.exe, then add C:/lilypond-2.24.2/bin to the system path.

Examples

if(tabr_options()$lilypond != ""){
  x <- phrase("c ec'g' ec'g'", "4 4 2", "5 432 432")
  x <- track(x)
  x <- score(x)
  outfile <- file.path(tempdir(), "out.pdf")
  tab(x, outfile) # requires LilyPond installation
}