render_music: Render sheet music snippet with LilyPond

Description

Render a sheet music/tablature snippet from a music object with LilyPond.

Usage

render_music(
  music,
  file,
  clef = "treble",
  tab = FALSE,
  tuning = "standard",
  string_names = NULL,
  header = NULL,
  paper = NULL,
  midi = FALSE,
  colors = NULL,
  transparent = FALSE,
  res = 150,
  keep_ly = FALSE,
  simplify = TRUE
)
render_music_tc(
  music,
  file,
  header = NULL,
  paper = NULL,
  midi = FALSE,
  colors = NULL,
  transparent = FALSE,
  res = 150,
  keep_ly = FALSE,
  simplify = TRUE
)
render_music_bc(
  music,
  file,
  header = NULL,
  paper = NULL,
  midi = FALSE,
  colors = NULL,
  transparent = FALSE,
  res = 150,
  keep_ly = FALSE,
  simplify = TRUE
)
render_music_tab(
  music,
  file,
  clef = NA,
  tuning = "standard",
  string_names = NULL,
  header = NULL,
  paper = NULL,
  midi = FALSE,
  colors = NULL,
  transparent = FALSE,
  res = 150,
  keep_ly = FALSE,
  simplify = TRUE
)
render_music_guitar(
  music,
  file,
  tuning = "standard",
  string_names = NULL,
  header = NULL,
  paper = NULL,
  midi = FALSE,
  colors = NULL,
  transparent = FALSE,
  res = 150,
  keep_ly = FALSE,
  simplify = TRUE
)
render_music_bass(
  music,
  file,
  tuning = "bass",
  string_names = NULL,
  header = NULL,
  paper = NULL,
  midi = FALSE,
  colors = NULL,
  transparent = FALSE,
  res = 150,
  keep_ly = FALSE,
  simplify = TRUE
)

Value

nothing returned; a file is written.

Arguments

music: a music object.
file: character, output file ending in .pdf or .png.
clef: character, include a music staff with the given clef. NA to suppress. See track() for details.
tab: logical, include tablature staff. NA to suppress. See track().
tuning: character, string tuning, only applies to tablature. See track().
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.
header: a named list of arguments passed to the header of the LilyPond file. See lilypond() details.
paper: a named list of arguments for the LilyPond file page layout. See lilypond() details.
midi: logical, also output an corresponding MIDI file.
colors: a named list of LilyPond element color global overrides. 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.

Details

These functions allow you to render short, simple snippets of sheet music directly from a music object. This is useful when you do not need to build up from phrases to tracks to a full score. They treat music objects as a single voice for a single track. This simplifies the possible output but is very convenient when this is all you need.

These functions abstract the following pipeline,

music |> phrase() |> track() |> score() |> render_*()

for this simple edge case and directly expose the most relevant arguments.

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

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 = 20
page_numbers = FALSE
print_first_page_number = TRUE
first_page_number = 1

textheight = 150 is the default, but for music snippet rendering, a value must be provided explicitly via paper when rendering to png. Otherwise for png outputs the height is cropped automatically rather than remaining a full page. See lilypond() for details.

Passing arguments to header can completely or partially prevent cropping in both directions, which must then be done manually with linewidth and textheight. This is all based on underlying LilyPond behavior.

If music contains lyrics and there are rests in the note sequence, note-lyric alignment is maintained automatically when these functions remove the lyric timesteps corresponding to the rests prior to sending to LilyPond. LilyPond skips rests when engraving lyrics and expects a shortened lyrics sequence in comparison to how tabr matches by timestep including rests. This is in contrast to track(), for which you have to shorten the lyrics object yourself prior to combining with a phrase object that has rests.

Examples

Run this code

x <- "a,4;5*5 b,- c cgc'e'~ cgc'e'1 e'4;2 c';3 g;4 c;5 ce'1;51"
x <- as_music(x)

y <- "a,,4;3*5 b,,- c, c,g,c~ c,g,c1 c4;1 g,;2 c,;3 g,;2 c,c1;31"
y <- as_music(y)

z <- as_music("a,4 b, r c~ c2 d", lyrics = as_lyrics("A2 B2 . C3 . D3"))

if (FALSE) {
if(tabr_options()$lilypond != ""){ # requires LilyPond installation
  outfile <- file.path(tempdir(), "out.pdf")
  render_music(x, outfile)

  outfile <- file.path(tempdir(), "out.png")
  render_music(x, outfile, "treble_8", tab = TRUE)

  render_music_tc(x, outfile)
  render_music_bc(x, outfile)

  render_music_tab(x, outfile)
  render_music_guitar(x, outfile)
  render_music_bass(y, outfile)

  # lyrics example
  render_music_guitar(z, outfile)
}
}