tab: Render sheet music with LilyPond

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

Render sheet music with LilyPond

Description

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.

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.

Value

nothing returned; a file is written.

See Also

lilypond(), render_chordchart(), miditab()

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
}

tabr documentation built on Sept. 12, 2024, 6:18 a.m.