Skip to contents

Render sheet music snippet with LilyPond

Source: R/snippet.R
render_music.Rd

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
)

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.

Value

nothing returned; a file is written.

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.

See also

plot_music(), phrase(), track(), score(), lilypond(), tab()

Examples

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