This section covers lilypond and tab for writing LilyPond files and engraving to sheet music with LilyPond, respectively. Examples of the various pieces of song metadata that can be passed to to these functions are provided.

The examples focus on tab because this generates the tablature whereas lilypond only creates the LilyPond file that tab renders. tab is a wrapper around lilypond. The two functions have identical arguments, as tab merely passes them along to lilypond internally, except for one. tab has keep_ly = FALSE by default, which removes the .ly file created by lilypond following rendering of the file to pdf or png. To keep the LilyPond file, set this to TRUE. All other arguments are the same for both functions so they are really lilypond arguments.

Here are the lilypond arguments:

#> function (score, file, key = "c", time = "4/4", tempo = "2 = 60", 
#>     header = NULL, string_names = NULL, paper = NULL, endbar = TRUE, 
#>     midi = TRUE, path = NULL) 

By now you have seen many calls to tab in order to show full examples in early tutorial sections. With sufficient coverage of phrases, tracks and scores, and the progression through them, now it is time to go into detail on all the render time arguments that can be supplied that apply to the entire piece of tablature and any metadata or general song information associated with it.

Score metadata

These are the most critical components that can be supplied to lilypond. These are the three arguments immediately after the input score and output file. While they have default values, they will almost invariably need to be changed for just about any song. key specifies the key signature, e.g. key ="dm". Key changes in the middle of a song are not supported, but you can always edit the LilyPond file by hand to make highly customized changes. time gives the time signature, defaulting to common time, or 4/4 time. tempo provides the song tempo, defaulting to tempo = "2 = 60". Note that key takes the tabr consistent key signature notation whereas time and tempo take literal LilyPond strings. Look up options for these strings if you are not familiar with them in LilyPond.

Throughout this tutorial section, the guitar and bass example from the section on tracks and scores is reused. The chord chart and chord sequence are retained to provide the most complete illustration of a rendered score. For completeness, here is what you have so far.

voice1 <- rp(p("c5 d5 e5 f5 g5", "1 2 4 4 1", "1*5"), 2)

notes <- "c e g c' e' c' g e g b d' g' f a c' f' c e g e c"
strings <- "5 4 3 2 1 2 3 4 4 3 2 1 4 3 2 1 5 4 3 4 5"
voice2 <- rp(p(notes, "8*20 2", strings), 2)

bass <- rp(p("c2e2*4 g1*2 f1*2 c2e2*3", "4*10 2", "32*4 4*4 32*3"), 2)

t1 <- track(voice1, voice = 1)
t2 <- track(voice2, voice = 2)
t3 <- track(bass, tuning = "bass", music_staff = "bass_8")

chords <- chord_set(c(c = "x32o1o", g = "355433", f = "133211"))
chord_seq <- rep(setNames(c(1, 2, 2, 1), names(chords)[c(1:3, 1)]), 3)
#>              c              g              f 
#> "x;3;2;o;1;o;" "3;5;5;4;3;3;" "1;3;3;2;1;1;"
#> c g f c c g f c c g f c 
#> 1 2 2 1 1 2 2 1 1 2 2 1

song <- trackbind(t1, t2, t3, tabstaff = c(1, 1, 2)) %>% score(chords, chord_seq)
#> # A tibble: 3 x 7
#>   phrase       tuning         voice staff    ms_transpose ms_key tabstaff
#>   <list>       <chr>          <int> <chr>           <int> <chr>     <int>
#> 1 <S3: phrase> e, a, d g b e'     1 treble_8            0 <NA>          1
#> 2 <S3: phrase> e, a, d g b e'     2 treble_8            0 <NA>          1
#> 3 <S3: phrase> e,, a,, d, g,      1 bass_8              0 <NA>          2

This time, when rendering the song, use settings for the three arguments discussed above. Given what is written, it doesn’t make sense to change them all. For example, this won’t fit well as a waltz (time = “3/4”). But for illustration purposes, pretend the song is actually in the key of D minor (F major). This key has one flat, B, so this will force the B note in the G chord to be annotated as an accidental. Change the time to 2/2 just for the sake of changing it, which won’t really be any different from 4/4 except you will see a line through the common time symbol. Finally, change the tempo to 4 = 120, which is also equivalent to the default, but will show up in the output slightly differently as well.

lilypond(song, "ex32.ly", "dm", "2/2", "4 = 120")
tab(song, "ex32.pdf", "dm", "2/2", "4 = 120")

Notice how the key change alone, which added room for a single flat symbol to be squeezed into the start of the treble and bass clef staves, was enough to push everything to the point of wrapping around onto a second entire line compared to the earlier tutorial section where it all fit on one line. This is because it was a really tight fit to in the previous examples and there was not enough room for LilyPond to continue fitting everything on one line with this slight widening created by the key change. LilyPond generates sheet music with a somewhat responsive layout engraver. It won’t leave everything on line one jam packaged and push a single measure to the line two. This will return to fitting on one line in a moment when we revert the key change.

Ouput file and path

The output file specified with file ends in pdf in every example. However, you can switch to png output simply by specifying a file name with that extension. file can specify just the file named or the path to the file. The path may be relative or absolute. Optionally, the path to the output file can be passed separately to path, which otherwise defaults to NULL.

Song information

The next important argument to lilypond is header. header takes a named list of character strings that are used to fill in general song information such as the title and composer. All previous examples were blank above the tabs because none of this information was ever provided. Below an example is given that uses all available arguments. You can use any subset of these. There is no requirement to supply them all. This example just shows what is available. Several of these would likely not be used in most cases.

header <- list(title = "Song title", composer = "Words and music by the composer", 
    performer = "Song performer", album = "Album title", subtitle = "Subtitle", 
    arranger = "Arranged by tab arranger", copyright = "2018 <Record Label>", 
    instrument = "guitar and bass", tagline = "A tagline", meter = "meter tag", 
    opus = "opus tag", piece = "piece tag", poet = "poet tag")

tab(song, "ex33.pdf", header = header)

The copyright and tagline are cutoff in the above image, but in your pdf you will see these if you scroll to the bottom of the rendered page.

Other settings

MIDI files

You have probably noticed by now that every time a pdf if rendered, an accompanying MIDI file is also generated. This can be turned off with midi = FALSE. This specification goes into the LilyPond file itself via lilypond. Therefore, no MIDI output will be created even if you create the LilyPond file with lilypond but convert that to pdf with LilyPond outside of R.

One thing to note about MIDI files is that tabr will unfold any repeats that occur in a song due to calls to rp, pct or volta. This allows the MIDI file to play everything the proper number of times rather than ending prematurely by not being able to read repeat notation.

Also, tabr is a package aimed at creating guitar tablature. It is not concerned with MIDI or audio signals and audio data in general. Any MIDI functionality is considered to be an extra feature and does not receive priority development or support. At this time, there is no way to make other alterations to the MIDI file internals. MIDI output can be toggled on or off as mentioned. And without you having to do anything, MIDI output will respect repeat notation in the rendered LilyPond file. MIDI output will also automatically be transposed to match a transposition that is applied to a music staff (under reasonable and simplified conditions).

String names

The string_names argument defaults to NULL. This means that standard tuning is never specified alongside the lines of a tab staff at the beginning of the tablature. However, any other tuning will be explicitly noted so the reader is aware of the alternate tuning of any applicable track. This can also be set to TRUE to force all tunings to be explicit including standard guitar tuning or FALSE to suppress them all (though it is unclear what value there is in the FALSE setting).

Paper settings

There is some nominal level of control over the paper layout via paper. Like header, this is a named list. The defaults are fine so you probably do not need to alter most of these values. There are six options, all numeric except for page_numbers, which is logical.

If you pass any values for some of these in a named list to paper, any not passed will retain their built in defaults. You do not have to supply them all when using paper.

For more detail on these settings and others further above, see the help documentation, ?lilypond.