Attention has been given to minimizing typing and keeping the R code short, particularly when the music is repetitive. However, this also needs to be extended to the tablature itself. Sheet music makes use of various styles of repeat notation to keep the number of pages for a song transcription from expanding needlessly.

tabr offers three functions for common ways to use repeats with LilyPond and in sheet music. The first is rp. (Unfortunately, both rep and repeat are already integral to R, but think of rp as “repeat” or even “repeat phrase”) This function is the only one that does not reduce the length of the guitar tablature. It only serves to shorten code. rp unfolds repeated sections of music so that in the output the music is explicitly written out on the staff however many times.

The other two functions are pct and volta. These functions do shorten the tablature output. pct is for percent repeat notation. It is useful for simple repetition of individual beats or of full measures or bars of music. volta is useful for repeating entire measures, optionally with alternate endings. volta is the standard approach when alternate section endings are present. All three functions operate similarly and share the same perspective on repeated sections of music even though some of their arguments as well as their results differ.

## Unfolded repeats

You have already seen how pn is used to repeat phrases and character strings n times. This helps keep R code shorter for repetitive music. However, this does nothing for the resulting LilyPond markup or the final sheet music output. It is strictly to limit repetitive typing and used more generally than for section repeats. rp achieves the same result. It does not shorten the music transcription. It is the simplest of the collection of repeat functions that apply LilyPond repeat tags around phrase objects.

Take the following phrase as an example.

p1 <- p("c e g c' e' c' g e", 8)
pn(p1, 2) # repeat n = 2 times
#> <Musical phrase>
#> <c>8 <e>8 <g>8 <c'>8 <e'>8 <c'>8 <g>8 <e>8 <c>8 <e>8 <g>8 <c'>8 <e'>8 <c'>8 <g>8 <e>8

rp(p1, 1) # repeat once (n = 1), or play twice (n + 1)
#> <Musical phrase>
#> \repeat unfold 2 { <c>8 <e>8 <g>8 <c'>8 <e'>8 <c'>8 <g>8 <e>8 }
#>


Note the difference in n and the results of pn vs. rp. Usually an argument like n refers to the total number of times, as it does in pn. But for tabr repeat functions, n always refers to the number of repeats added to the initial play, or one less than the total number of plays. Therefore, n always begins counting from one (the default), since there is no reason to use these repeat functions when not repeating anything.

pc(pn(p1, 2), rp(p1)) %>% track %>% score %>% tab("example17.pdf")

In the tablature output above, the first two measures pertaining to the use of pn are identical to the last two resulting from rp. Unfolding a repeated section is no different than writing it out fully. rp represents a shortening of LilyPond markup by applying the \repeat \unfold tag around the music. The 2 shown in the LilyPond markup output is the total number of plays, n + 1. Think of pn as a more general purpose helper function in tabr for pasting copies of strings together whereas rp might be used when you are thinking more specifically about meaningful, discrete section of music.

## Percent repeats

Like rp, pct does not remove measures of music in the tablature output. However, percent repeat symbols can shorten sheet music in so much as they may make measures of music smaller in size as a result of having nothing else to print in the measure but the repeat symbol itself. They can also make the transcription less messy or straining on the eyes particularly when the section being repeated with percent symbols is one that uses a lot of ink on the page.

The next example uses pct with the previous phrase and follows with a high ink measure using percent repeats for another four measures.

pct(p1, 3)
#> <Musical phrase>
#> \repeat percent 4 { <c>8 <e>8 <g>8 <c'>8 <e'>8 <c'>8 <g>8 <e>8 }
#>

p2 <- p("g,b,dgbg'*16", 16)
pc(pct(p1, 3), pct(p2, 3)) %>% track %>% score %>% tab("example18.pdf")

It is nice to not have to stare at those rapid bar chords in every measure. The earlier measures are also shorter as a result of not having to display all the notes.

## Volta repeats

Finally there is the volta repeat function. Unlike rp and pct, volta must be applied to whole measures of music. The endings also must be whole measures. It is also the only way to specify repeats with alternate endings, though not required. In either case, this type of repeat notation does remove entire measures of music from the output.

The examples below uses volta with the original phrase various endings. Here are the endings.

e1 <- p("f a c' f'", 4)
e2 <- p("c*8", 8)
e3 <- p("cegc'e'", 1)

### No alternate endings

When n = 1 repeat, volta simply adds the double bars around the section. With no other annotation in the sheet music, it is assumed that the section is repeated one time. When n is greater than one, annotation appears clarifying the number of times to play the section.

volta(p1)
#> <Musical phrase>
#> \repeat volta 2 { <c>8 <e>8 <g>8 <c'>8 <e'>8 <c'>8 <g>8 <e>8 | }
#>

volta(p1, 2)
#> <Musical phrase>
#> \repeat volta 3 { <c>8^"Play 3 times." <e>8 <g>8 <c'>8 <e'>8 <c'>8 <g>8 <e>8 | }
#>


For brevity, concatenate both of these. Note that the volta repeat bar at the beginning of a repeated section is omitted from the staff if it occurs at the start of the song.

pc(volta(p1), volta(p1, 2)) %>% track %>% score %>% tab("example19.pdf")

There are instances where you want to suppress this annotation. Specifically, if there are multiple tab staffs present, there is no need to print the same annotation above every staff other than the top one. Also, there is the edge case where notes in the section may already have annotations attached to them via notate, in which case the above annotation may get in the way. It can be suppressed in volta with silent = TRUE.

### Single alternate ending

When alternate endings are used with volta, the annotation above the staff is never included because the number of times the section is played is clear from the explicit endings numbering. Note that when the number of repeats exceeds the number of alternate endings, the initial alternate ending is reused first until the number of remaining repeats are covered by the alternate endings. The subsequent alternate endings are not recycled.

To be clear, the phrase passed to volta does not contain or represent its own implicit default ending. When used without alternate endings, there is no “ending”; it is just the phrase. When alternate endings are provided, they represent all endings. The first alternate is the “default” if you want to think of it this way.

volta(p1, 1, e1)
#> <Musical phrase>
#> \repeat volta 2 { <c>8 <e>8 <g>8 <c'>8 <e'>8 <c'>8 <g>8 <e>8 | }
#> \alternative {
#>   { <f>4 <a>4 <c'>4 <f'>4 | }
#> }

volta(p1, 2, e1)
#> <Musical phrase>
#> \repeat volta 3 { <c>8 <e>8 <g>8 <c'>8 <e'>8 <c'>8 <g>8 <e>8 | }
#> \alternative {
#>   { <f>4 <a>4 <c'>4 <f'>4 | }
#> }


As before, concatenate the above two examples. For the remaining examples using alternate endings, a single measure of a whole note C is added after repeated sections to separate them and provide a better sense of the context.

c1 <- p("c", 1)
pc(volta(p1, 1, e1), c1, volta(p1, 2, e1), c1) %>% track %>% score %>% tab("example20.pdf")

### Multiple alternate endings

Multiple alternate endings work similarly to single. The first ending is recycled if necessary. Subsequent endings are used once. If you want to use these subsequent ending more than once, just provide it accordingly. Clearly, there is no reason to provide more endings than the number of times the section is played. If extra endings are providing, LilyPond will issue a warning when rendering the document notifying that there are more alternates than repeats and that the excess have been ignored.

x1 <- volta(p1, 2, list(e1, e2, e3))
x2 <- volta(p1, 2, list(e1, e2))
x3 <- volta(p1, 2, e1)
x1
#> <Musical phrase>
#> \repeat volta 3 { <c>8 <e>8 <g>8 <c'>8 <e'>8 <c'>8 <g>8 <e>8 | }
#> \alternative {
#>   { <f>4 <a>4 <c'>4 <f'>4 | }
#>   { <c>8 <c>8 <c>8 <c>8 <c>8 <c>8 <c>8 <c>8 | }
#>   { <c e g c' e'>1 | }
#> }

x2
#> <Musical phrase>
#> \repeat volta 3 { <c>8 <e>8 <g>8 <c'>8 <e'>8 <c'>8 <g>8 <e>8 | }
#> \alternative {
#>   { <f>4 <a>4 <c'>4 <f'>4 | }
#>   { <c>8 <c>8 <c>8 <c>8 <c>8 <c>8 <c>8 <c>8 | }
#> }

x3
#> <Musical phrase>
#> \repeat volta 3 { <c>8 <e>8 <g>8 <c'>8 <e'>8 <c'>8 <g>8 <e>8 | }
#> \alternative {
#>   { <f>4 <a>4 <c'>4 <f'>4 | }
#> }

pc(x1, c1, x2, c1, x3, c1) %>% track %>% score %>% tab("example21.pdf")