Provides a music notation syntax and a collection of music programming functions for generating, manipulating, organizing and analyzing musical information in R. The music notation framework facilitates creating and analyzing music data in notation form. Music data can be viewed, manipulated and analyzed while in different forms of representation based around different data structures: strings and data frames. Each representation offers advantages over the other for different use cases. Music syntax can be entered directly and represented in character strings to minimize the formatting overhead of data entry by using simple data structures, for example when wanting to quickly enter and transcribe short pieces of music to sheet music or tablature. The package contains functions for directly performing various mathematical, logical and organizational operations and musical transformations on special object classes that facilitate working with music data and notation. The same music data can also be organized in tidy data frames, allowing for a more familiar and powerful approach to the analysis of large amounts of structured music data. Functions are available for mapping seamlessly between these data structures and their representations of musical information. The package also provides API wrapper functions for transcribing musical representations in R into guitar tablature ("tabs") and basic sheet music using the 'LilyPond' backend (< http://lilypond.org>). 'LilyPond' is open source music engraving software for generating high quality sheet music based on markup syntax. The package generates 'LilyPond' files from R code and can pass them to 'LilyPond' to be rendered into sheet music pdf files. The package offers nominal MIDI file output support in conjunction with rendering sheet music. The package can read MIDI files and attempts to structure the MIDI data to integrate as best as possible with the data structures and functionality found throughout the package.
Create guitar tablature ("tabs") from R code with tabr
. The tabr
package provides programmatic music notation and a wrapper around LilyPond for creating quality guitar tablature.
tabr
offers functions for describing and organizing musical structures and wraps around the LilyPond backend. LilyPond is an open source music engraving program for generating high quality sheet music based on markup syntax. tabr
generates files following the LilyPond markup syntax to be subsequently processed by LilyPond into sheet music.
A standalone LilyPond (.ly) file can be created or the package can make a system call to LilyPond directly to render the guitar tablature output (pdf or png). While LilyPond caters to sheet music in general, tabr
is focused on leveraging it specifically for creating quality guitar tablature.
The tabr
package offers the following:
Note that MIDI support and string/fret alternative input format support are not prioritized in ongoing tabr
development. These are considered tangential extra features in tabr
that fall outside the general scope and intent of the package.
You can install tabr from CRAN with:
install.packages("tabr")
You can install tabr from GitHub with:
devtools::install_github("leonawicz/tabr")
As a brief example, recreate the tablature shown in the image above (minus the R logo). Here are the steps.
phrase
or the shorthand alias p
.track
.score
.tab
.A phrase here does not require a strict definition. Think of it as the smallest piece of musical structure you intend to string together. The first argument to phrase
is a string describing notes of a specific pitch (or rests: "r"), separated in time by spaces. For chords, just remove spaces to indicate simultaneous notes. Integers are appended to indicate the octave number so that the pitch is unique. For example, a rest followed by a sequence of notes might be given by notes = "r a2 c3 f3 d3 a3 f3"
.
The second argument is a similar string giving note metadata. In this example there is nothing to add but the time durations. Whole notes taking up an entire measure of music are given by 1, half notes by 2, quarter notes 4, eighth notes 8, and so on. To specify a quarter note rest followed by a sequence of eighth notes, use info = "4 8 8 8 8 8 8"
(or shorten to just info = "4 8*6"
). This basic example does not require specifying additional note information such as dotted notes for different fractions of time, staccato notes, ties/slurs, slides, bends, hammer ons and pull offs, etc. These specifications are currently available in tabr
to varying degrees of development and are covered in the vignette tutorials.
The third argument, string
, is optional but generally important for guitar tablature. In similar format, it specifies the strings of the guitar on which notes are played. Providing this information fixes the fret-string combinations so that LilyPond does not have to guess what position on the neck of the guitar to play a specific note. An inability to specify this in various tablature notation software (or laziness by the user), is a common cause of inaccurate tabs scouring the internet, where even when the notes are correct they are written in the tab suggesting they be played in positions no one would sensibly use. Note that the x
shown below is just a placeholder indicating no need to specify a string for the quarter note rest.
The example below employs a couple shortcuts to further reduce typing. The first is to use the *
in-string expansion operator mentioned above to avoid typing a long series of eighth notes. Second, it drops explicit reference to octave number three since this central octave is the default octave in LilyPond. This applies to all but the first note below.
While explicit string numbers are not needed for this example, they are provided anyway for full context. Dropping the string
argument would further reduce typing.
Finally, specify some song metadata to reproduce the original staff: the key of D minor, common time, and the tempo.
If LilyPond is installed on your system (and added to your system PATH variable on Windows systems), tab
should call it successfully. Alternatively, on Windows, it can be added explicitly by calling tabr_options
. This option to specify the LilyPond path is still available on other systems. An example of this is commented out below. However, tabr
will do its best on package load to set these paths in tabr_options
for you if it can successfully detect a LilyPond installation in a standard file system location, so you may not have to do anything. Just check tabr_options()
after you load the package. If any of the paths are equal to the empty string ""
, then you need to set the paths. Otherwise you should be ready to run LilyPond from R.
library(tabr)# path <- "C:/Program Files (x86)/LilyPond/usr/bin/lilypond.exe"# tabr_options(lilypond = path) # may not be necessaryp("r a2 c f d a f", "4 8*6", "x 5 5 4 4 3 4") %>% track %>% score %>%tab(song, "phrase.pdf", key = "dm", time = "4/4", tempo = "4 = 120")
#> #### Engraving score to phrase.pdf ####
#> GNU LilyPond 2.18.2
#> Processing `./phrase.ly'
#> Parsing...
#> Interpreting music...
#> Preprocessing graphical objects...
#> Interpreting music...
#> MIDI output to `./phrase.mid'...
#> Finding the ideal number of pages...
#> Fitting music on 1 page...
#> Drawing systems...
#> Layout output to `./phrase.ps'...
#> Converting to `./phrase.pdf'...
#> Success: compilation successfully completed
See the pdf result embedded at the tabr website.
Note above that tabr
also exports the pipe %>%
operator. Even given the hierarchy of objects involved in the series of steps to move from a phrase to a rendered pdf, a short example like this does not even require a single assignment. While music can be quite complex and a full score will be much longer, tabr
strives to minimize the work while still forcing some sense of interpretable, organized structure. For long and complex music, it can require some effort and practice to ensure your approach to transcription in your R code is not opaque.
Why LilyPond? LilyPond is an exceptional sheet music engraving program. It produces professional, high quality output. It is open source. It offers an access point for a programmatic approach to music notation. It is developed and utilized by a large community. Most GUI-based applications are WYSIWYG and force a greater limitation on what you can do and what it will look like after you do it. On the other hand, I have zero interest in writing LilyPond files. tabr
has made it more enjoyable, a bit less ugly, and enables me to stick with LilyPond for its quality as I try to shield myself from its native input structures. I'm sure there are far more LilyPond users who don't mind it at all and have never heard of R; to each their own.
There is far more that LilyPond can do that tabr
does not tap into. Instead of listing a million things, this is just to highlight an example of a critical feature that still has limited functionality in both tabr
and in LilyPond itself: LilyPond's bend engraver. Rendering sheet music with quality string bend notation is quite difficult. This is an area that will benefit greatly from further development.
There is a rich collection of vignette tutorials available at the tabr website. Complete package reference and function documentation
tuplet
(and triplet
) to accept a phrase object as well as a character string of notes. Previously, only notes were accepted but this was too limiting. The argument name has changed to from notes
to x
and tuplet
will now check the class of x
and handle phrase objects accordingly.tuplet
.sf_phrase
(and sfp
) updated to allow returning early with only the notes string as opposed to the entire phrase object. This is useful if you just want a quick, cleaner string representation of what notes are mapped by string/fret combinations..onLoad
for non-Windows systems.tibble
package dependency. Using only dplyr
suffices.lintr
to Suggests field in DESCRIPTION per CRAN maintainer request regarding testthat
unit tests.lilypond
example from dontrun
tag.tempdir()
location for examples that write files.Adjustments to meet requirements for CRAN resubmission:
tempdir
.dontrun
tag around one last file-writing package example that was using lilypond
.lilypond
, tab
, midily
and miditab
to work with system calls that use absolute paths for output files instead of only working with relative paths..ly
) files and wrapping around system calls to Lilypond for rendering sheet music to pdf or png..mid
to .ly
and .mid
to tab output convenience functions.