Phrase helpers

This section covers helper functions related to phrases. These functions assist with improving readability, organization, and limiting the amount of typing required to specify phrases where possible.


Briefly, there are some convenient aliases for tabr functions that are used often. These aliases have short function names to help keep the music notation R syntax a more concise if desired. These include:

The most common conflicts to watch out for are using tabr with shiny where p is a function and if you use purrr to help wrangle some of your more complex tablature, it has its own transpose function. Pay attention to package load order and/or use explicit names spaces if working with these packages loaded. The recommended approach is to stick with phrase in apps where users will not see your code anyway and stick with tp for transposition in general.

Duplicate and glue

The previous section on phrases presented an opportunity to introduce dup for duplicating or repeating strings and glue for joining them together. These were used on strings passed to phrase but work on any character string.

To recap, dup, short for duplicate, is a simple wrapper around rep that maintains the phrase class when passed a phrase object and space-delimitation when collapsing the repeated input. glue is a simple wrapper around paste that similarly maintains space-delimitation. It can be passed an arbitrary number of input simple character strings or phrase objects. The phrase class is applied to the output as long as at least one input passed to glue is a phrase object. It is the responsibility of the user to ensure that in such a case a simple character string also represents valid phrase content so that the output phrase is valid.

glue("c3 d3 e3", "f3 g3 a3")
#> [1] "c3 d3 e3 f3 g3 a3"
dup("c3 d3 e3", 2)
#> [1] "c3 d3 e3 c3 d3 e3"


The rest function is a simple wrapper around rep much like dup. It is useful when you need to propagate a number of rests, perhaps not all of equal duration. It accepts two vectorized arguments. The first is the duration of the rest. The second is the number of times to repeat it.

For example, say a score has multiple tracks. During a certain period in the score, one track goes silent and needs to be carried over with a sequence of rests. Perhaps the instrument dropped out in the middle of a measure and returns in the middle of another, with several full measures in between. This can easily be notated using dup and glue, but it could be more convenient with rest, or at least offer more interpretable code if you prefer.

In this example, using rest is compared with writing out the full notes string as well as using some combinations of dup and glue. It is a matter of preference which approach you take and dependent on the content being repeated and pasted together. Note that using the terminal in-string multiplicative expansion operator, *, in cases of many adjacent single-element repetitions, is by far the best option as far as shortening code is concerned. If this method is preferred, it essentially removes any edge case preference there may have been for rest.

"r8 r8 r8 r1 r1 r1 r1 r1 r1 r1 r1 r1 r1 r4."
#> [1] "r8 r8 r8 r1 r1 r1 r1 r1 r1 r1 r1 r1 r1 r4."
glue(dup("r8", 3), dup("r1", 10), "r4.")
#> [1] "r8 r8 r8 r1 r1 r1 r1 r1 r1 r1 r1 r1 r1 r4."
rest(c(8, 1, "4."), c(3, 10, 1))
#> [1] "r8 r8 r8 r1 r1 r1 r1 r1 r1 r1 r1 r1 r1 r4."
"r8*3 r1*10 r4."
#> [1] "r8*3 r1*10 r4."


Tied notes were introduced momentarily in the previous section on phrases. The example given showed that ties are denoted by appending the pitch letter of the note with ~ and this will create a tie in the output from this note to the next one.

This can be frustrating to type and to read when done for six-string chords for example. tie can make this more bearable. Chords receive further discussion in subsequent sections. They were only shown very briefly at the end of the last section so that space-delimited time and simultaneous notes could be demonstrated clearly. For now, this is enough to appreciate this example of tie.

em <- "e,a,dgbe'"
#> [1] "e,~a,~d~g~b~e'~"

Hammer on/pull off

There is a simple helper function, hp, for hammer ons and pull offs, or for slurs in general. Like several other helpers it is a wrapper around paste. It ensures slurs come in an even number so there is always a starting and stopping point and accepts several input styles.

hp("16 16")
#> [1] "16( 16)"
hp("16", "16")
#> [1] "16( 16)"
hp(16, 16, 8, "2.")
#> [1] "16( 16) 8( 2.)"

It is particularly useful for long runs of similar repeated hammer ons and/or pull offs that would be frustrating to type out directly.

hp(dup("16 8", 8))
#> [1] "16( 8) 16( 8) 16( 8) 16( 8) 16( 8) 16( 8) 16( 8) 16( 8)"


In the last section there was an example showing a sequence of notes followed by the same sequence transposed one octave up. At the time, it was written out twice. Here, the same sequence is reproduced using transpose. Transposing up one octave is done by specifying an increase of 12 semitones or half steps. Note that transpose drops the unnecessary 3s for the third octave, the central octave in LilyPond. They are dropped from note2 here

notes1 <- "c3 b2 c3 d3 e3 e3 d3 c3 b2 c3 c3 c4"
notes2 <- "c4 b c4 d4 e4 e4 d4 c4 b c4 c4 c5"
transpose(notes1, 12) == notes2
#> [1] TRUE

Transposing down is done with negative integers. The default (n = 0) returns the input, x, with no transposition. The alias tp can be used to limit typing. Examples are shown below.

transpose("a_3 b_4 c5", 0)
#> [1] "a_3 b_4 c5"
tp("a_3 b_4 c5", -1)
#> [1] "g a4 b4"
tp("a_3 b_4 c5", 1)
#> [1] "a b4 c#5"
tp("a#3 b4 c#5", 11)
#> [1] "a4 a#5 c6"
tp("a#3 b4 c#5", 12)
#> [1] "a#4 b5 c#6"
tp("a#3 b4 c#5", 13)
#> [1] "b4 c6 d6"

If no other information is passed to transpose, positive n will sharpen naturals. Negative n will flatten naturals. This is not ideal because it may not fit a key signature. A standard key signature is composed of notes that may include flats or sharps but not both. To avoid simply defaulting to one or the other based on direction of transposition, specify they key signature with key to be formal, e.g. key = "dm", or just specify "flat" or "sharp"" because this is really all that is needed.

Since notes can be arbitrarily short, even a single note, there is no reason for transpose to attempt to guess the original or new key from the notes present and degree of transposition. notes may easily include accidentals anyhow. transpose works with either integer or tick style octave numbering as shown below and the the output style can be forced either way.

tp("a3 b4 c5", 2, key = "f")
#> [1] "b d_5 d5"
tp("a3 b4 c5", 2, key = "g", style = "tick")
#> [1] "b c#'' d''"
tp("a b' c''", 2, key = "flat")
#> [1] "b d_'' d''"
tp("a, b c'", 2, key = "sharp", style = "integer")
#> [1] "b2 c#4 d4"

The key of F has one flat (B flat) and the key of G has one sharp (F sharp). Transposing the above notes up by a whole step (two semitones or half steps) results in a new note sequence that includes either a D flat or C sharp for the second note. This pitch does not occur (except as an accidental) in either of those keys.

Nevertheless, because F is a key with some number of sharps and G is a key with some number of flats, transpositions resulting in any non-natural notes are represented as flats and sharps, respectively. The key of C major and its relative A minor have only natural notes. Setting key "c" or key = "am" results in the default behavior, falling back on sharp notes for transposing up and flat notes for transposing down.


An important feature is the tuplet. This will evenly fit a sequence of notes into a number of beats not otherwise permitted by the time signature. The most common and default tuplet returned by tuplet is the triplet. There is also an alias function, triplet for this. The triplet fits three equally spaced notes into two beats that would normally be taken up by two of those notes, meaning each note in the triplet lasts for two thirds the normal duration. The examples below show the equivalence of default tuplet settings and triplet as well as other specifications for tuplet and the ability to specify multiple consecutive tuplets of a fixed pattern with a single call to tuplet.

x <- "c4 d4 e4"
tuplet(x, 8)
#> \tuplet 3/2 4 { <c'>8 <d'> <e'> }
triplet(x, 8)  # equivalent
#> \tuplet 3/2 4 { <c'>8 <d'> <e'> }
tuplet(dup(x, 2), 8, a = 6, b = 4)  # 6 notes per 4 beats
#> \tuplet 6/4 2 { <c'>8 <d'> <e'> <c'> <d'> <e'> }
tuplet(dup(x, 4), 8)  # multiple tuplets, one call
#> \tuplet 3/2 4 { <c'>8 <d'> <e'> <c'> <d'> <e'> <c'> <d'> <e'> <c'> <d'> <e'> }

Like phrase, these functions accept a string number argument, which is critical as usual (try engraving the final phrase below without explicit string numbers and see the mess you get). This example includes some rests.

p1 <- glue(triplet("c4 r e4", 8, "4 3 3"), tuplet("f4 g4 a4 b4 c5 b4", 8, "3 2 2 1 1 1", 
    6, 4), tuplet("a4 r f4 g4 r e4 f4 e4 d4 e4 d4 c4", 16, "2 2 3 2 3*7 4"), 
    tuplet("b a g f e", 16, "4 4 5*3", 5, 4))
track(glue(p1, p("d c", "8 4.", "6 6"))) %>% score %>% tab("ex12.pdf")

This concludes the section on helper functions associated with phrases and note sequences. The next section goes into deeper detail on chord specification and the various use of chords in tabr.