Render sheet music with LilyPond

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

Usage

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
}