Package 'tabr'

Description

Helper functions for concatenating musical phrases and raw strings together as well as repetition.

Usage

pc(...)

pn(x, n = 1)

Arguments

Details

Note: When working with special tabr classes, you can simply use generics like c() and rep() as many custom methods exist for these classes. The additional respective helper functions, pc() and pn(), are more specifically for phrase objects and when you are still working with character strings, yet to be converted to a phrase object (numbers not yet in string form are allowed). See examples.

The functions pc() and pn() are based on base functions paste() and rep(), respectively, but are tailored for efficiency in creating musical phrases.

These functions respect and retain the phrase class when applied to phrases. They are aggressive for phrases and secondarily for noteworthy strings. Combining a phrase with a non-phrase string will assume compatibility and result in a new phrase object. If no phrase objects are present, the presence of any noteworthy string will in turn attempt to force conversion of all strings to noteworthy strings. The aggressiveness provides convenience, but is counter to expected coercion rules. It is up to the user to ensure all inputs can be forced into the more specific child class.

This is especially useful for repeated instances. This function applies to general slur notation as well. Multiple input formats are allowed. Total number of note durations must be even because all slurs require start and stop points.

Value

phrase on non-phrase character string, noteworthy string if applicable.

Examples

pc(8, "16-", "8^")
pn(1, 2)
x <- phrase("c ec'g' ec'g'", "4 4 2", "5 432 432")
y <- phrase("a", 1, 5)
pc(x, y)
pc(x, pn(y, 2))
pc(x, "r1") # add a simple rest instance
class(pc(x, y))
class(pn(y, 2))
class(pc(x, "r1"))
class(pn("r1", 2))
class(pc("r1", "r4"))

Description

A data frame containing categorized sets of articulations that can be used in phrase construction.

Usage

articulations

Format

A data frame with 3 column and 44 rows.

Description

Convert a noteworthy string to a tibble data frame and include additional derivative variables.

Usage

as_music_df(
  notes,
  info = NULL,
  key = NULL,
  scale = "diatonic",
  chords = c("root", "list", "character"),
  si_format = c("mmp_abb", "mmp", "ad_abb", "ad")
)

Arguments

Details

If info is provided or notes is a phrase object, the resulting data frame also contains note durations and other info variables. The duration column is always included in the output even as a vector of NAs when info = NULL. This makes it more explicit that a given music data frame was generated without any time information for the timesteps. Other note info columns are not included in this case.

For some derived column variables the root note (lowest pitch) in chord is used. This is done for pitch intervals and scale intervals between adjacent timesteps. This also occurs for scale degrees.

chord = "root" additionally collapses columns like semitone, octave, and frequency to the value for the root note so that all rows contain one numeric value. chord = "list" retains full information as list columns. chord = "character" collapses into strings so that values are readily visible when printing the table, but information is not stripped and can be recovered without recomputing from the original pitches.

Value

a tibble data frame

Examples

x <- "a, b, c d e f g# a r ac'e' a c' e' c' r r r a"
as_music_df(x, key = "c", scale = "major")
as_music_df(x, key = "am", scale = "harmonic_minor", si_format = "ad_abb")

a <- notate("8", "Start here.")
time <- paste(a, "8^*2 16-_ 4.. 16( 16)( 2) 2 4. t8- t8 t8- 8[accent]*4 1")
d1 <- as_music_df(x, time)
d1

# Go directly from music object to data frame
m1 <- as_music(x, time)
d2 <- as_music_df(m1)
identical(d1, d2)

# Go directly from phrase object to data frame
p1 <- phrase("a b cgc'", "4-+ 4[accent] 2", 5)
identical(as_music_df(as_music("a4-+;5 b[accent] cgc'2")), as_music_df(p1))

Description

Create an arpeggio from a chord.

Usage

chord_arpeggiate(
  chord,
  n = 0,
  by = c("note", "chord"),
  broken = FALSE,
  collapse = FALSE
)

Arguments

Details

This function is based on chord_invert. If n = 0 then chord is returned immediately; other arguments are ignored.

Value

character

Examples

chord_arpeggiate("ce_gb_", 2)
chord_arpeggiate("ce_gb_", -2)
chord_arpeggiate("ce_gb_", 2, by = "chord")
chord_arpeggiate("ce_gb_", 1, broken = TRUE, collapse = TRUE)

Description

Convert chords in a noteworthy string or vector to broken chords.

Usage

chord_break(notes)

Arguments

Value

character

Examples

chord_break("c e g ceg ceg")

Description

Function for creating new chord definition tables.

Usage

chord_def(fret, id, optional = NA, tuning = "standard", ...)

Arguments

Details

This function creates a tibble data frame containing information defining various attributes of chords. It is used to create the guitarChords dataset, but can be used to create other pre-defined chord collections. The tibble has only one row, providing all information for the defined chord. The user can decide which arguments to vectorize over when creating a chord collection. See examples.

This function uses a vector of fret integers (NA for muted string) to define a chord, in conjunction with a string tuning (defaults to standard tuning, six-string guitar). fret is from lowest to highest pitch strings, e.g., strings six through one.

The id is passed directly to the output. It represents the type of chord and should conform to accepted tabr notation. See id column in guitarChords for examples.

Note that the semitones column gives semitone intervals between chord notes. These count from zero as the lowest pitch based on the tuning of the instrument, e.g., zero is E2 with standard guitar tuning. To convert these semitone intervals to standard semitone values assigned to pitches, use e.g., pitch_semitones("e2") (40) if that is the lowest pitch and add that value to the instrument semitone interval values. This is the explanation, but doing this is not necessary. You can use chord_semitones() to compute semitones directly on pitches in a chord.

Value

a data frame

Examples

frets <- c(NA, 0, 2, 2, 1, 0)
chord_def(frets, "m")
chord_def(frets, "m", 6)

purrr::map_dfr(c(0, 2, 3), ~chord_def(frets + .x, "m"))

Description

This function inverts a single chord given as a character string. If n = 0, chord is returned immediately. Otherwise, the notes of the chord are inverted. If abs(n) is greater than the number of inversions (excluding root position), an error is thrown.

Usage

chord_invert(chord, n = 0, limit = FALSE)

Arguments

Details

Note that chord_invert() has no knowledge of whether a chord might be considered as in root position or some inversion already, as informed by a key signature, chord name or user's intent. This function simply inverts what it receives, treating any defined chord string as in root position.

Octave number applies to this function. Chords should always be defined by notes of increasing pitch. Remember that an unspecified octave number on a note is octave 3. When the chord is inverted, it moves up the scale. The lowest note is moved to the top of the chord, increasing its octave if necessary, to ensure that the note takes the lowest octave number while having the highest pitch. The second lowest note becomes the lowest. It's octave does not change. This pattern is repeated for higher order inversions. The opposite happens if n is negative.

The procedure ensures that the resulting inverted chord is still defined by notes of increasing pitch. However, if you construct an unusual chord that spans multiple octaves, the extra space will be condensed by inversion.

Value

character

Examples

chord_invert("ce_gb_", 3)

Description

Check if chords are major or minor where possible.

Usage

chord_is_major(notes)

chord_is_minor(notes)

Arguments

Details

These functions operate based only on ordered pitches. They do not recognize what a human might interpret and name an inverted chord with a root other than the lowest pitch. This imposes limitations on the utility of these functions, which scan the intervals for a minor or major third in a chord whose notes are sorted by pitch.

In several cases including single notes or no major or minor third interval present, NA is returned. TRUE or FALSE is only returned if such an interval is present. If more than one is present, it is based on the lowest in pitch. It prioritizes major/minor and minor/major adjacent intervals (recognizing a common triad). If these do not occur adjacent, the lowest third is selected. This is still imperfect, but a useful method. Second and higher unknown chord inversions are problematic.

Value

logical vector

Examples

x <- "c cg, ce ce_ ceg ce_gb g,ce g,ce_ e_,g,c e_,g,ce_ e_,g,c"
chord_is_major(x)
identical(chord_is_major(x), !chord_is_minor(x))

Description

Generate a chord set for a music score.

Usage

chord_set(x, id = NULL, n = 6)

Arguments

Details

The chord set list returned by chord_set() is only used for top center placement of a full set of chord fretboard diagrams for a music score. chord_set() returns a named list. The names are the chords and the list elements are strings defining string and fret fingering readable by LilyPond. Multiple chord positions can be defined for the same chord name. Instruments with a number of strings other than six are not currently supported.

When defining chords, you may also wish to define rests or silent rests for chords that are to be added to a score for placement above the staff in time, where no chord is to be played or explicitly written. Therefore, there are occasions where you may pass chord names and positions that happen to include entries r and/or s as NA as shown in the example. These two special cases are passed through by chord_set() but are ignored when the chord chart is generated.

Value

a named list.

Examples

chord_names <- c("e:m", "c", "d", "e:m", "d", "r", "s")
chord_position <- c("997x", "5553x", "7775x", "ooo22o", "232oxx", NA, NA)
chord_set(chord_position, chord_names)

Description

Rank, order and sort chords and notes by various definitions.

Usage

chord_rank(notes, pitch = c("min", "mean", "max"), ...)

chord_order(notes, pitch = c("min", "mean", "max"), ...)

chord_sort(notes, pitch = c("min", "mean", "max"), decreasing = FALSE, ...)

Arguments

Details

There are three options for comparing the relative pitch position of chords provided: comparison of the lowest or root note of each chord, the highest pitch note, or taking the mean of all notes in a chord.

Value

integer for rank and order, character for sort

Examples

x <- "a2 c a2 ceg ce_g cea"
chord_rank(x, "min")
chord_rank(x, "max")
chord_rank(x, "mean")

chord_order(x)
chord_order(x, "mean")
chord_sort(x, "mean")

Description

Filter or slice chords to extract individual notes.

Usage

chord_root(notes)

chord_top(notes)

chord_slice(notes, index)

Arguments

Details

These functions extract notes from chords such as the root note, the highest pitch, specific position among the notes by pitch, or trim chords to simplify them. They operate based only on ordered pitches.

For chord_slice(), any entry that is empty after slicing is dropped. An error is thrown is index is completely out of bounds for all chords.

Value

a noteworthy string

Examples

x <- "a_2 c#eg# e_gc egc,cc'"
chord_root(x)
chord_top(x)
identical(chord_slice(x, 1), chord_root(x))
chord_slice(x, 2)
chord_slice(x, 4)
chord_slice(x, 3:5)

Description

Helper functions for chord mapping.

Usage

gc_info(
  name,
  root_octave = NULL,
  root_fret = NULL,
  min_fret = NULL,
  bass_string = NULL,
  open = NULL,
  key = "c",
  ignore_octave = TRUE
)

gc_fretboard(
  name,
  root_octave = NULL,
  root_fret = NULL,
  min_fret = NULL,
  bass_string = NULL,
  open = NULL,
  key = "c",
  ignore_octave = TRUE
)

gc_notes_to_fb(
  notes,
  root_octave = NULL,
  root_fret = NULL,
  min_fret = NULL,
  bass_string = NULL,
  open = NULL
)

gc_notes(
  name,
  root_octave = NULL,
  root_fret = NULL,
  min_fret = NULL,
  bass_string = NULL,
  open = NULL,
  key = "c",
  ignore_octave = TRUE
)

gc_is_known(notes)

gc_name_split(name)

gc_name_root(name)

gc_name_mod(name)

Arguments

Details

These functions assist with mapping between different information that define chords.

For gc_is_known(), a check is done against chords in the guitarChords dataset. A simple noteworthy string is permitted, but any single-note entry will automatically yield a FALSE result.

gc_info() returns a tibble data frame containing complete information for the subset of predefined guitar chords specified by name and key. Any accidentals present in the chord root of name (but not in the chord modifier, e.g., m7_5 or m7#5) are converted according to key if necessary. gc_notes() and gc_fretboard() are wrappers around gc_info(), which return noteworthy strings of chord notes and a named vector of LilyPond fretboard diagram data, respectively. Note that although the input to these functions can contain multiple chord names, whether as a vector or as a single space-delimited string, the result is not intended to be of equal length. These functions filter guitarChords. The result is the set of all chords matched by the supplied input filters.

gc_name_split() splits a vector or space-delimited set of chord names into a tibble data frame containing separate chord root and chord modifier columns. gc_name_root() and gc_name_mod() are wrappers around this.

Value

various, see details regarding each function.

Examples

gc_is_known("a b_,fb_d'f'")

gc_name_root("a aM b_,m7#5")
gc_name_mod("a aM b_,m7#5")

gc_info("a") # a major chord, not a single note
gc_info("ceg a#m7_5") # only second entry is a guitar chord
gc_info("ceg a#m7_5", key = "f")

gc_info("a,m c d f,")
gc_fretboard("a,m c d f,", root_fret = 0:3)
gc_notes_to_fb("a,eac'e' cgc'e'g'")

x <- gc_notes("a, b,", root_fret = 0:2)
summary(x)

Description

These functions construct basic chord string notation from root notes.

Usage

chord_min(notes, key = "c", octaves = "tick")

chord_maj(notes, key = "c", octaves = "tick")

chord_min7(notes, key = "c", octaves = "tick")

chord_dom7(notes, key = "c", octaves = "tick")

chord_7s5(notes, key = "c", octaves = "tick")

chord_maj7(notes, key = "c", octaves = "tick")

chord_min6(notes, key = "c", octaves = "tick")

chord_maj6(notes, key = "c", octaves = "tick")

chord_dim(notes, key = "c", octaves = "tick")

chord_dim7(notes, key = "c", octaves = "tick")

chord_m7b5(notes, key = "c", octaves = "tick")

chord_aug(notes, key = "c", octaves = "tick")

chord_5(notes, key = "c", octaves = "tick")

chord_sus2(notes, key = "c", octaves = "tick")

chord_sus4(notes, key = "c", octaves = "tick")

chord_dom9(notes, key = "c", octaves = "tick")

chord_7s9(notes, key = "c", octaves = "tick")

chord_maj9(notes, key = "c", octaves = "tick")

chord_add9(notes, key = "c", octaves = "tick")

chord_min9(notes, key = "c", octaves = "tick")

chord_madd9(notes, key = "c", octaves = "tick")

chord_min11(notes, key = "c", octaves = "tick")

chord_7s11(notes, key = "c", octaves = "tick")

chord_maj7s11(notes, key = "c", octaves = "tick")

chord_11(notes, key = "c", octaves = "tick")

chord_maj11(notes, key = "c", octaves = "tick")

chord_13(notes, key = "c", octaves = "tick")

chord_min13(notes, key = "c", octaves = "tick")

chord_maj13(notes, key = "c", octaves = "tick")

xm(notes, key = "c", octaves = "tick")

xM(notes, key = "c", octaves = "tick")

xm7(notes, key = "c", octaves = "tick")

x7(notes, key = "c", octaves = "tick")

x7s5(notes, key = "c", octaves = "tick")

xM7(notes, key = "c", octaves = "tick")

xm6(notes, key = "c", octaves = "tick")

xM6(notes, key = "c", octaves = "tick")

xdim(notes, key = "c", octaves = "tick")

xdim7(notes, key = "c", octaves = "tick")

xm7b5(notes, key = "c", octaves = "tick")

xaug(notes, key = "c", octaves = "tick")

x5(notes, key = "c", octaves = "tick")

xs2(notes, key = "c", octaves = "tick")

xs4(notes, key = "c", octaves = "tick")

x9(notes, key = "c", octaves = "tick")

x7s9(notes, key = "c", octaves = "tick")

xM9(notes, key = "c", octaves = "tick")

xadd9(notes, key = "c", octaves = "tick")

xm9(notes, key = "c", octaves = "tick")

xma9(notes, key = "c", octaves = "tick")

xm11(notes, key = "c", octaves = "tick")

x7s11(notes, key = "c", octaves = "tick")

xM7s11(notes, key = "c", octaves = "tick")

x_11(notes, key = "c", octaves = "tick")

xM11(notes, key = "c", octaves = "tick")

x_13(notes, key = "c", octaves = "tick")

xm13(notes, key = "c", octaves = "tick")

xM13(notes, key = "c", octaves = "tick")

Arguments

Details

Providing a key signature is used only to ensure flats or sharps for accidentals. An additional set of aliases with efficient names, of the form ⁠x*⁠ where * is a chord modifier abbreviation, is provided to complement the set of ⁠chord_*⁠ functions.

These functions create standard chords, not the multi-octave spanning types of chords commonly played on guitar.

Value

character

See Also

transpose()

Examples

chord_min("d")
chord_maj("d")
xM("d")
xm("c f g")
xm("c, f, g,", key = "e_")

Description

Double bracket indexing and assignment. See tabr-methods() for more details on methods for tabr classes.

Usage

## S3 method for class 'noteworthy'
x[[i]]

## S3 method for class 'noteinfo'
x[[i]]

## S3 method for class 'music'
x[[i]]

## S3 method for class 'lyrics'
x[[i]]

## S3 replacement method for class 'noteworthy'
x[[i]] <- value

## S3 replacement method for class 'noteinfo'
x[[i]] <- value

## S3 replacement method for class 'music'
x[[i]] <- value

## S3 replacement method for class 'lyrics'
x[[i]] <- value

Arguments

See Also

tabr-methods(), note-metadata()

Examples

# noteworthy class examples
x <- as_noteworthy("a, b, c ce_g")
x[[3]]
x[[2]] <- paste0(transpose(x[2], 1), "~")
x

# noteinfo class examples
x <- as_noteinfo(c("4-", "t8(", "t8)", "t8x"))
x[[3]]
x[[3]] <- c("t8]")
x

# music class examples
x <- as_music("c,~4 c,1 c'e_'g'4-.*2")
x[[3]]
x[[3]] <- "c'e'g'8"
x

Description

Construct a dyad given one note, an interval, and a direction.

Usage

dyad(
  notes,
  interval,
  reverse = FALSE,
  octaves = c("tick", "integer"),
  accidentals = c("flat", "sharp"),
  key = NULL
)

Arguments

Details

The interval may be specified by semitones of by common interval name or abbreviation. See examples. For a complete list of valid interval names and abbreviations see mainIntervals(). key enforces the use of sharps or flats. This function is based on transpose(). notes and interval may be vectors, but must be equal length. Recycling occurs only if one argument is scalar.

Value

character

See Also

mainIntervals()

Examples

dyad("a", 4)
x <- c("minor third", "m3", "augmented second", "A2")
dyad("a", x)
dyad("c'", x, reverse = TRUE)

x <- c("M3", "m3", "m3", "M3", "M3", "m3", "m3")
dyad(letters[c(3:7, 1, 2)], x)

x <- c("P1", "m3", "M3", "P4", "P5", "P8", "M9")
dyad("c", x)
dyad("c", x, reverse = TRUE)
dyad("d e", "m3")

Description

Obtain frequency ratios data frame.

Usage

freq_ratio(x, ...)

Arguments

Details

This generic function returns a data frame of frequency ratios from a vector or list of frequencies, a noteworthy object, or a music object. For frequency inputs, a list can be used to represent multiple timesteps. Octave numbering and accidentals are inferred from noteworthy and music objects, but can be specified for frequency. See examples.

By default ratios are returned for all combinations of intervals in each chord (ratios = "all"). ratios = "root" filters the result to only include chord ratios with respect to the root note of each chord. ratios = "range" filters to only the chord ratio between the root and highest note.

Value

a tibble data frame

Examples

x <- as_music("c4 e_ g ce_g")
(fr <- freq_ratio(x))

x <- music_notes(x)
identical(fr, freq_ratio(x))

x <- chord_freq(x)
identical(fr, freq_ratio(x))

freq_ratio(x, accidentals = "sharp")

freq_ratio(x, ratios = "root")

freq_ratio(x, ratios = "range")

Description

A data frame containing information for many predefined guitar chords.

Usage

guitarChords

Format

A data frame with 12 columns and 3,967 rows

Description

Helper function for generating hammer on and pull off syntax.

Usage

hp(...)

Arguments

Details

This is especially useful for repeated instances. This function applies to general slur notation as well. Multiple input formats are allowed. Total number of note durations must be even because all slurs require start and stop points.

Value

character.

Examples

hp(16, 16)
hp("16 16")
hp("16 8 16", "8 16 8")

Description

Convert named intervals to numbers of semitones. For a complete list of valid interval names and abbreviations see mainIntervals(). interval may be a vector.

Usage

interval_semitones(interval)

Arguments

Value

integer

See Also

mainIntervals()

Examples

x <- c("minor third", "m3", "augmented second", "A2")
y <- c("P1", "m2", "M2", "m3", "M3", "P4", "TT", "P5")
interval_semitones(x)
interval_semitones(y)

Description

Helper functions for musical intervals defined by two notes.

Usage

pitch_interval(notes1, notes2, use_root = TRUE)

pitch_diff(notes, use_root = TRUE, n = 1, trim = FALSE)

scale_interval(
  notes1,
  notes2,
  use_root = TRUE,
  format = c("mmp_abb", "mmp", "ad_abb", "ad")
)

scale_diff(
  notes,
  use_root = TRUE,
  n = 1,
  trim = FALSE,
  format = c("mmp_abb", "mmp", "ad_abb", "ad")
)

tuning_intervals(tuning = "standard")

Arguments

Details

Numeric intervals are directional. pitch_interval() returns the signed number of semitones defining the distance between two notes. Named scale intervals are names only. Use pitch for direction.

scale_interval() returns a character string that provides the named main interval, simple or compound, defined by the two notes. This function returns NA for any uncommon out of range large interval not listed as a named interval in mainIntervals().

pitch_interval() and scale_interval() compute intervals element-wise between two noteworthy strings. pitch_diff() and scale_diff() work similarly but compute lagged intervals on the elements in notes.

Value

a musical interval, integer or character depending on the function.

See Also

mainIntervals()

Examples

pitch_interval("b", "c4")
pitch_interval("c, e_, g_, a,", "e_, g_, a, c")
pitch_interval("c r", "dfa d")
pitch_interval("c r", "dfa d", use_root = FALSE)
scale_interval("c", "e_")
scale_interval("ceg", "egd'")

x <- "a, b, c d e f g# ac'e' a c' e'"
pitch_diff(x)
pitch_diff(x, use_root = FALSE)
scale_diff(x)
scale_diff(x, n = 2, trim = TRUE, use_root = FALSE)

# Lagged intervals respect rest timesteps.
# All timestep position including rests are retained.
# But the lag-n difference skips rest entries.
x <- "a, c r r r r g"
pitch_diff(x)
scale_diff(x)
pitch_diff(x, n = 2)
scale_diff(x, n = 2)
pitch_diff(x, n = 2, trim = TRUE)
scale_diff(x, n = 2, trim = TRUE)

Description

Check if notes and chords are diatonic in a given key.

Usage

is_diatonic(notes, key = "c")

Arguments

Details

This function is a wrapper around is_in_scale(). To check if individual notes are in a scale, see note_in_scale().

Value

logical

See Also

is_in_scale()

Examples

is_diatonic("ceg ace ce_g", "c")
is_diatonic(c("r", "d", "dfa", "df#a"), "d")

Description

Helper functions for key signature information.

Usage

keys(type = c("all", "sharp", "flat"))

key_is_natural(key)

key_is_sharp(key)

key_is_flat(key)

key_n_sharps(key)

key_n_flats(key)

key_is_major(key)

key_is_minor(key)

Arguments

Details

The keys() function returns a vector of valid key signature IDs. These IDs are how key signatures are specified throughout tabr, including in the other helper functions here via key. Like the other functions here, key_is_sharp() and key_is_flat() are for key signatures, not single pitches whose sharp or flat status is always self-evident from their notation. Major and minor keys are also self-evident from their notation, but key_is_major() and key_is_minor() can still be useful when programming.

Value

character vector.

Examples

keys()
key_is_natural(c("c", "am", "c#"))
x <- c("a", "e_")
key_is_sharp(x)
key_is_flat(x)
key_n_sharps(x)
key_n_flats(x)

Description

Write a score to a LilyPond format (.ly) text file for later use by LilyPond or subsequent editing outside of R.

Usage

lilypond(
  score,
  file,
  key = "c",
  time = "4/4",
  tempo = "2 = 60",
  header = NULL,
  paper = NULL,
  string_names = NULL,
  endbar = "|.",
  midi = TRUE,
  colors = NULL,
  crop_png = TRUE,
  simplify = TRUE
)

Arguments

Details

This function only writes a LilyPond file to disk. It does not require a LilyPond installation. It checks for the version number of an installation, but LilyPond is not required to be found.

This function can be used directly but is commonly used by ⁠render_*⁠ functions, which call this function internally to create the LilyPond file and then call LilyPond to render that file to sheet music.

Value

nothing returned; a file is written.

Header options

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

Paper options

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 = 10

• page_numbers = TRUE

• print_first_page_number = TRUE

• first_page_number = 1

PNG-related options

By default crop_png = TRUE. This alters the template so that when the LilyPond output file is created, it contains specifications for cropping the image to the content when that file is rendered by LilyPond to png. The image will have its width and height automatically cropped rather than retain the standard page dimensions. This only applies to png outputs made from the LilyPond file, not pdf. The argument is also ignored if explicitly providing textheight to paper. You may still provide linewidth to paper if you find you need to increase it beyond the default 150mm, generally as a result of using a large fontsize. Various ⁠render_*⁠ functions that wrap lilypond make use of this argument as well.

Color options

You can provide a named list of global color overrides for various sheet music elements with the colors argument of lilypond or one of the associated rendering functions.

By default, everything is black. Overrides are only inserted into the generated LilyPond file if given. Values are character; either the hex color or a named R color. The named list options include the following.

• color

• background

• staff

• time

• key

• clef

• bar

• beam

• head

• stem

• accidental

• slur

• tabhead

• lyrics

color is a global font color for the entire score. It affects staff elements and header elements. It does not affect everything, e.g., page numbers. background controls the background color of the entire page. Do not use this if making a transparent background png with the transparent argument available in the various ⁠render_*⁠ functions. The other options are also global but override color. You can change the color of elements broadly with color and then change the color of specific elements using the other options.

There are currently some limitations. Specifically, if you provide any background color override, most header elements will not display.

See Also

tab(), render_chordchart(), midily()

Examples

x <- phrase("c ec'g' ec'g'", "4 4 2", "5 432 432")
x <- track(x)
x <- score(x)
outfile <- file.path(tempdir(), "out.ly")
lilypond(x, outfile)

Description

Details about local LilyPond installation and package API.

Usage

lilypond_root()

lilypond_version()

tabr_lilypond_api()

Details

Version information and installation directory are returned if the installation can be found. The LilyPond API references the currently loaded version of tabr.

Value

a message or system standard output.

Examples

lilypond_root()
lilypond_version()
tabr_lilypond_api()

Description

Obtain LilyPond quasi-chord notation.

Usage

lp_chord_id(root, chord, exact = FALSE, ...)

lp_chord_mod(root, chord, exact = FALSE, ...)

Arguments

Details

These functions take a tabr syntax representation of a chord name and convert it to quasi-LilyPond syntax; "quasi" because the result still uses ⁠_⁠ for flats and ⁠#⁠ for sharps, whereas LilyPond itself uses es and is (mostly). This is the format used by tabr functions involved in communicating with LilyPond for music transcription, and they make these final conversions on the fly. This can be overridden with exact = TRUE.

Value

character

Examples

lp_chord_id("a a a", "m M m7_5")
lp_chord_mod("a a a", "m M m7_5")
lp_chord_id("a a a", "m M m7_5", exact = TRUE)
lp_chord_mod("a a a", "m M m7_5", exact = TRUE)

Description

Functions for creating and checking lyrics objects.

Usage

lyrical(x)

as_lyrics(x, format = NULL)

is_lyrics(x)

lyrics_template(x, format = NULL)

Arguments

Details

The lyrics class is a simple class for arranging lyrics text by timestep. Its structure and behavior aligns with that of the classes noteworthy, noteinfo and music.

lyrical() is a trivial function that returns a scalar logical result essentially for any object that inherits from character, though this check may become more specific in the future.

as_lyrics() can be used to coerce to the lyrics class. Coercion will fail if the string is not lyrical. The lyrics class has its own print() and summary() methods.

When format = NULL, the timestep delimiter format is inferred from the lyrical string input.

Value

depends on the function

Examples

# space-delimited lyrics; use periods for timesteps with no lyric
x <- "These are the ly- rics . . . to this song"
is_lyrics(x)
lyrical(x)
as_lyrics(x)

# character vector; empty, period or NA for no lyric
x <- c("These", "are", "the", "ly-", "rics",
       "", ".", NA, "to", "this", "song") #
as_lyrics(x)

# generate empty lyrics object from noteworthy, noteinfo or music object
notes <- as_noteworthy("c d e d c r*3 e g c'")
x <- lyrics_template(notes)
x

x[1:5] <- strsplit("These are the ly- rics", " ")[[1]]
x[9:11] <- c("to", "this", "song")
x

summary(x)

attributes(x)

Description

A data frame containing descriptions of the main intervals, simple and compound.

Usage

mainIntervals

Format

A data frame with 5 columns and 26 rows

Description

Convert a MIDI file (.mid) to a LilyPond format (.ly) text file.

Usage

midily(
  midi_file,
  file,
  key = "c",
  absolute = FALSE,
  quantize = NULL,
  explicit = FALSE,
  start_quant = NULL,
  allow_tuplet = c("4*2/3", "8*2/3", "16*2/3"),
  details = FALSE,
  lyric = FALSE
)

Arguments

Details

Under development/testing. See warning and details below.

This function is a wrapper around the midi2ly() command line utility provided by LilyPond. It inherits all the limitations thereof. LilyPond is not intended to be used to produce meaningful sheet music from arbitrary MIDI files. While lilypond() converts R code score() objects to LilyPond markup directly, MIDI conversion to LilyPond markup by midily() requires LilyPond.

WARNING: Even though the purpose of the command line utility is to convert an existing MIDI file to a LilyPond file, it nevertheless generates a LilyPond file that specifies inclusion of MIDI output. This means when you subsequently process the LilyPond file with LilyPond or if you use miditab() to go straight from your MIDI file to pdf output, the command line tool will also produce a MIDI file output. It will overwrite your original MIDI file if it has the same file name and location!

allow_tuplets = NULL to disallow all tuplets. Fourth, eighth and sixteenth note triplets are allowed. The format is a character vector where each element is duration*numerator/denominator, no spaces. See default argument.

On Windows systems, it may be necessary to specify a path in tabr_options() to both midi2ly and python if they are not already added to the system PATH variable.

Value

nothing returned; a file is written.

See Also

miditab(), tab(), lilypond()

Examples

## Not run: 
if(tabr_options()$midi2ly != ""){
  midi <- system.file("example.mid", package = "tabr")
  outfile <- file.path(tempdir(), "out.ly")
  midily(midi, outfile) # requires LilyPond installation
}

## End(Not run)

Description

Convert a MIDI file to sheet music/guitar tablature.

Usage

miditab(midi_file, file, keep_ly = FALSE, details = FALSE, ...)

Arguments

Details

Under development/testing. See warning and details below.

Convert a MIDI file to a pdf or png music score using the LilyPond music engraving program. Output format is inferred from file extension. This function is a wrapper around midily(), the function that converts the MIDI file to a LilyPond (.ly) file using a LilyPond command line utility.

WARNING: Even though the purpose of the command line utility is to convert an existing MIDI file to a LilyPond file, it nevertheless generates a LilyPond file that specifies inclusion of MIDI output. This means when you subsequently process the LilyPond file with LilyPond or if you use miditab() to go straight from your MIDI file to pdf output, the command line tool will also produce a MIDI file output. It will overwrite your original MIDI file if it has the same file name and location!

On Windows systems, it may be necessary to specify a path in tabr_options() to both midi2ly and python if they are not already added to the system PATH variable.

Value

nothing returned; a file is written.

See Also

midily(), tab(), lilypond()

Examples

## Not run: 
if(tabr_options()$midi2ly != ""){
  midi <- system.file("example.mid", package = "tabr")
  outfile <- file.path(tempdir(), "out.pdf")
  miditab(midi, outfile, details = FALSE) # requires LilyPond installation
}

## End(Not run)

Description

Helper functions for working with musical modes.

Usage

modes(mode = c("all", "major", "minor"))

is_mode(notes, ignore_octave = FALSE)

mode_rotate(notes, n = 0, ignore_octave = FALSE)

mode_modern(
  mode = "ionian",
  key = "c",
  collapse = FALSE,
  ignore_octave = FALSE
)

mode_ionian(key = "c", collapse = FALSE, ignore_octave = FALSE)

mode_dorian(key = "c", collapse = FALSE, ignore_octave = FALSE)

mode_phrygian(key = "c", collapse = FALSE, ignore_octave = FALSE)

mode_lydian(key = "c", collapse = FALSE, ignore_octave = FALSE)

mode_mixolydian(key = "c", collapse = FALSE, ignore_octave = FALSE)

mode_aeolian(key = "c", collapse = FALSE, ignore_octave = FALSE)

mode_locrian(key = "c", collapse = FALSE, ignore_octave = FALSE)

Arguments

Details

For valid key signatures, see keys().

Modern modes based on major scales are available by key signature using the ⁠mode_*⁠ functions. The seven modes can be listed with modes. Noteworthy strings of proper length can be checked to match against a mode with is_mode(). Modes can be rotated with mode_rotate(), a wrapper around note_rotate().

Value

character

See Also

keys(), scale-helpers()

Examples

modes()
mode_dorian("c")
mode_modern("dorian", "c")
mode_modern("dorian", "c", ignore_octave = TRUE)

identical(mode_rotate(mode_ionian("c"), 1), mode_dorian("d"))
identical(
  mode_rotate(mode_ionian("c", ignore_octave = TRUE), 1),
  mode_dorian("d", ignore_octave = TRUE)
)

x <- sapply(modes(), mode_modern, ignore_octave = TRUE)
setNames(data.frame(t(x)), as.roman(1:7))

Description

Check whether a string is comprised exclusively of valid syntax for music strings. A music object can be built from such a string. It combines a noteworthy string and a note info string.

Usage

musical(x)

as_music(
  notes,
  info = NULL,
  lyrics = NA,
  key = "c",
  time = "4/4",
  tempo = "2 = 60",
  accidentals = NULL,
  format = NULL,
  labels = NULL,
  at = seq_along(labels)
)

is_music(x)

music_split(x)

Arguments

Details

With note info strings, you are required to enter something at every timestep, even if it is only the duration. This makes sense because if you do not enter something, there is simply no indication of a timestep. A nice feature of music strings is that explicit timesteps are achieved just by having notes present, allowing you to leave out durations entirely when they repeat, inheriting them from the previous timestep where duration was given explicitly. There is no need to enter the same number across consecutive timesteps; the first will suffice and the rest are automatically filled in for you when the object is constructed.

musical() returns a scalar logical result indicating whether all timesteps contain exclusively valid entries.

as_music() can be used to coerce to the music class. Coercion will fail if the string is not musical. The music class has its own print() and summary() methods. music objects are primarily intended to represent an aggregation of a noteworthy object and a noteinfo. You can optionally fold in a lyrics object as well. However, for music data analysis, any operations will involve first splitting the object into its component parts. The value of this class is for the more efficient data entry it provides.

When accidentals or format are NULL, these settings are inferred from the musical string input. When mixed formats are present, flats are the default for accidentals.

Other attributes are attached to a music object. key uses the tabr syntax, e.g., "c", "b_", "f#m", etc. time and tempo use the LilyPond string format. For music programming and analysis, key, time and tempo can most likely be ignored. They are primarily relevant when rendering a music snippet directly from a music object with LilyPond. These additional attributes provide more complete context for the rendered sheet music.

If you plan to render music snippets from a music object that you are defining from a new character string, and the context you have in mind is a stringed and fretted instrument like guitar, you can specify string numbers at the end of each timestep with numbers following a semicolon delimiter. This would still precede any * timestep multiplier number. See examples.

Note that if you convert a music object to a phrase object, you are changing contexts. The phrase object is the simplest LilyPond-format music structure. Coercion with phrase() strips all attributes of a music object and retains only notes, note info and string numbers.

Value

depends on the function

See Also

music-helpers(), note-checks(), note-metadata(), note-summaries(), note-coerce()

Examples

# note durations inherit from previous timestep if missing
x <- "a#4-+ b_[staccato] c,x d''t8( e)( g_')- a4 c,e_,g, ce_g4. a~8 a1"
is_music(x)
musical(x)
x <- as_music(x)
is_music(x)
x

y <- lyrics_template(x)
y[3:8] <- strsplit("These are some song ly- rics", " ")[[1]]
y

x <- as_music(x, lyrics = y, accidentals = "sharp")
summary(x)

# Starting string = 5: use ';5'. Carries over until an explicit change.
x <- "a,4;5*5 b,4-+ c4[staccato] cgc'e'~4 cgc'e'1 e'4;2 c';3 g;4 c;5 ce'1;51"
x <- as_music_df(as_music(x))
x$string

Description

Helper functions for accessing music object values and attributes.

Usage

music_notes(x)

music_info(x)

music_strings(x)

music_key(x)

music_time(x)

music_tempo(x)

music_lyrics(x)

Arguments

Details

Note that while lyrics always shows as an attribute even when NA, strings is completely absent as a value if it was not part of the object construction from a new character string.

Value

depends on the function

See Also

music(), note-checks(), note-metadata(), note-summaries(), note-coerce()

Examples

# Starting string = 5: use ';5'. Carries over until an explicit change.
x <- "a,4;5*5 b,4- c4 cgc'e'~4 cgc'e'1 e'4;2 c';3 g;4 c;5 ce'1;51"
x <- as_music(x)

y <- lyrics_template(x)
y[3:8] <- strsplit("These are some song ly- rics", " ")[[1]]
y

x <- as_music(x, lyrics = y)

attributes(x)

music_split(x)

music_notes(x)
music_info(x)
music_key(x)
music_time(x)
music_tempo(x)
music_lyrics(x)
music_strings(x)

Description

These functions assist with summarizing temporal data for music objects.

Usage

n_measures(x)

n_beats(x, unit = 4)

steps_per_measure(x)

bpm(x, unit = 4, tempo = NULL)

seconds(x, tempo = NULL)

seconds_per_measure(x, tempo = NULL)

seconds_per_step(x, tempo = NULL)

steps_start_time(x, tempo = NULL)

Arguments

Details

These functions also work with the simpler noteinfo class, though some functions require you to provide additional arguments.

Functions that deal with real time require a known tempo, which music objects have. The simpler note info object does not contain this information. You can provide a value to the tempo argument of such functions. This overrides the tempo of x if a music object. But the reason to use tempo is to provide one when x is a note info object. By default tempo = NULL, in which case it will derive the value from the music object or return an error for note info objects.

n_measures() gives the total number of measures covered by all timesteps. Functions providing the number of beats and beats per minute both take a unit, defaulting to 4 for quarter note beats. The unit can be any even beat, triplet beat, dotted, or double dotted beat, from "t32" up to 1.

The number of timesteps starting in each measure is obtained with steps_per_measure().

Value

depends on function

Examples

a <- notate("t8x", "Start here")
notes <- "a, b, c d e f g# a r ac'e' a c' e' c' r*3 ac'e'~ ac'e'"
info <- paste(a, "t8x t8-. 16 4.. 16- 16 2^ 2 4. 8( 4)( 4) 8*4 1 1")
info <- as_noteinfo(info)
x <- as_music(notes, info)

n_measures(info) # fraction indicates incomplete final measure
n_measures(x)

n_beats(x)
n_beats(x, 1)
n_beats(x, "t16")

bpm(x)
bpm(x, "t8")

seconds(x)
seconds(info, "4 = 120")
seconds(info, "2 = 60")
seconds(x, "4 = 100")

steps_per_measure(x)
seconds_per_measure(x)
seconds_per_step(x)
steps_start_time(x)

Description

Annotate a music staff, vertically aligned above or below the music staff at a specific note/time.

Usage

notate(x, text, position = "top")

Arguments

Details

This function binds text annotation in LilyPond syntax to a note's associated info entry. Technically, the syntax is a hybrid form, but is later updated safely and unambiguously to LilyPond syntax with respect to the rest of the note info substring when it is fed to phrase() for musical phrase assembly.

Value

a character string.

Examples

notate("8", "Solo")
phrase("c'~ c' d' e'", pc(notate(8, "First solo"), "8 8 4."), "5 5 5 5")

Description

Convert a noteworthy string to a list of noteworthy n-grams.

Usage

note_ngram(notes, n = 2, tally = FALSE, rests = FALSE)

Arguments

Value

list of noteworthy objects or a tibble

Examples

x <- as_noteworthy("c r ceg dfa ceg dfa")
note_ngram(x)
(x <- note_ngram(x, tally = TRUE))
x$ngram <- as.character(x$ngram)
x

Description

Helper functions for indexing and moving notes within noteworthy strings.

Usage

note_slice(notes, ...)

note_sort(notes, decreasing = FALSE)

note_rotate(notes, n = 0)

note_shift(notes, n = 0)

note_arpeggiate(notes, n = 0, step = 12)

Arguments

Details

note_slice() subsets the timesteps of a noteworthy string by integer index or logical vector of length equal to the number of timesteps.

note_sort() sorts the timesteps of a noteworthy string by pitch. When a tie exists by root note, the next note in chords are compared, if they exist. For example, ⁠a,⁠ sorts lower than ⁠a,ce⁠.

note_rotate() simply rotates anything space-delimited or vectorized in place. It allows chords. Octave numbering is ignored if present.

For note_shift() the entire sequence is shifted up or down in pitch, as if inverting a broken chord. If notes contains chords, they are broken into successive notes. Then all notes are ordered by pitch. Finally shifting occurs.

Instead of a moving window, note_arpeggiate() grows its sequence from the original set of timesteps by repeating the entire sequence n times (n must be positive). Each repeated sequence contributing to the arpeggio is offset by step semitones from the original. step can be negative. It defaults to 12, increasing all notes by one octave.

Value

character

Examples

x <- "bd'f#' a c'e'g' b ba c'g' gd'g'd''"
note_sort(x)
note_sort(x, decreasing = TRUE)

x <- "e_2 a_, c#f#a#"
note_slice(x, 2:3)
note_slice(x, c(FALSE, TRUE, TRUE))

note_rotate(x, 1)

note_shift("c e g", 1)
note_shift("c e g", -4)

note_arpeggiate("c e g ceg", 3)
note_arpeggiate("c e g", 3, step = -12)
note_arpeggiate("g e c", 3, step = -12)
note_arpeggiate("c e_ g_ a", 3, step = 3)
note_arpeggiate("c a g_ e_", 3, step = -3)

Description

The simplest functions for inspecting noteworthy strings to see if their notes have certain properties.

Usage

note_is_accidental(notes)

note_is_natural(notes)

note_is_flat(notes)

note_is_sharp(notes)

note_has_accidental(notes)

note_has_natural(notes)

note_has_flat(notes)

note_has_sharp(notes)

Arguments

Details

Note that these functions are the weakest in terms of checking noteworthiness. They are simple regular expression-based wrappers. They are often used internally by more complex functions without wasting computational overhead on performing input validity checks, but they are exported from the package for user convenience. Their results will only make sense on strings that you define in accordance with noteworthy string rules.

The ⁠note_is_*⁠ functions return a logical vector with length equal to the number of timesteps in notes. The ⁠note_has_*⁠ functions summarize these to a single logical value.

Value

logical

See Also

note-metadata(), note-summaries(), note-coerce(), valid-notes()

Examples

x <- "r a_2 a a#' s"
note_has_accidental(x)
note_has_natural(x)
note_has_flat(x)
note_has_sharp(x)
note_is_accidental(x)
note_is_natural(x)
note_is_flat(x)
note_is_sharp(x)
note_has_tick(x)
note_has_integer(x)
note_is_tick(x)
note_is_integer(x)
note_has_rest(x)
note_is_rest(x)

Description

Helper functions for setting formatting attributes of noteworthy strings including representation of timesteps, octaves and accidentals.

Usage

naturalize(notes, type = c("both", "flat", "sharp"))

sharpen_flat(notes)

flatten_sharp(notes)

note_set_key(notes, key = "c")

as_tick_octaves(notes)

as_integer_octaves(notes)

as_space_time(x)

as_vector_time(x)

pretty_notes(notes, ignore_octave = TRUE)

Arguments

Details

For sharpen_flat() and flatten_sharp(), sharpening flats and flattening sharps refer to inverting their respective notation, not to raising or lowering a flatted or sharped note by one semitone. For the latter, use naturalize(), which removes flat and/or sharp notation from a string. note_set_key() is used for coercing a noteworthy string to a specific and consistent notation for accidentals based on a key signature. This is a wrapper around sharpen_flat() and flatten_sharp(). as_tick_octaves(), as_integer_octaves(), as_space_time() and as_vector_time() similarly affect octave and timestep format. For simultaneous control over the representation of timesteps, octave numbering and accidentals, all three are available as arguments to as_noteworthy().

Value

character

A note on generic functions

as_space_time() and as_vector_time() are generic since they apply clearly to and are useful for not only noteworthy strings, but also note info and music objects. If x is still a simple character string, these functions attempt to guess which of the three it is. It is recommended to set the class before using these functions.

There are many package functions that operate on noteworthy strings that could in concept work on music objects, but the expectation is that sound and time/info are disentangled. The music class is convenient for data entry, e.g., for transcription purposes, but it is not sensible to perform data analysis with quantities like pitch and time tightly bound together. This would only lead to repetitive deconstructions and reconstructions of music class objects. Most functions that operate on noteworthy strings or note info strings strictly apply to one or the other. Generic functions are reserved for only the most fundamental and generally applicable metadata retrieval and format coercion.

See Also

note-checks(), note-metadata(), note-summaries(), valid-notes()

Examples

x <- "e_2 a_, b_, c#f#a# c#'f#'a#''"
note_set_key(x, "f")
note_set_key(x, "g")
as_tick_octaves(x)
as_integer_octaves(x)
y <- as_vector_time(x)
is_vector_time(y)
is_space_time(as_space_time(y))

naturalize(x)
naturalize(x, "sharp")
sharpen_flat(x)
flatten_sharp(x)
pretty_notes(x)

Description

Helper functions to check the equivalence of two noteworthy strings, and other related functions.

Usage

note_is_equal(notes1, notes2, ignore_octave = TRUE)

note_is_identical(notes1, notes2, ignore_octave = TRUE)

pitch_is_equal(notes1, notes2)

pitch_is_identical(notes1, notes2)

octave_is_equal(notes1, notes2)

octave_is_identical(notes1, notes2, single_octave = FALSE)

Arguments

Details

Noteworthy strings may contain notes, pitches and chords. Noteworthy strings are equal if they sound the same. This means that if one string contains Eb (e_) and the other contains D# (d#) then the two strings may be equal, but they are not identical.

pitch_is_equal() and pitch_is_identical() perform these respective tests of equivalence on both notes and chords. These are the strictest functions in terms of equivalent sound because pitch includes the octave number.

note_is_equal() and note_is_identical() are similar but include a default argument ignore_octave = TRUE, focusing only on the notes and chords. This allows an even more relaxed definition of equivalence. Setting this argument to FALSE is the same as calling the ⁠pitch_is_*⁠ variant.

Chords can be checked the same as notes. Every timestep in the sequence is checked pairwise between note1 and note2.

These functions will return TRUE or FALSE for every timestep in a sequence. If the two noteworthy strings do not contain the same number of notes at a specific step, such as a single note compared to a chord, this yields a FALSE value, even in a case of an octave dyad with octave number ignored. If the two sequences have unequal length NA is returned. These are bare minimum requirements for equivalence. See examples.

octave_is_equal() and octave_is_identical() allow much weaker forms of equivalence in that they ignore notes completely. These functions are only concerned with comparing the octave numbers spanned by any pitches present at each timestep. When checking for equality, octave_is_equal() only looks at the octave number associated with the first note at each step, e.g., only the root note of a chord. octave_is_identical() compares all octaves spanned at a given timestep.

It does not matter when comparing two chords that they may be comprised of a different numbers of notes. If the set of unique octaves spanned by one chord is identical to the set spanned by the other, they are considered to have identical octave coverage. For example, a1b2c3 is identical to d1e1f2g3. To be equal, it only matters that the two chords begin with x1, where x is any note. Alternatively, for octave_is_identical() only, setting single_octave = TRUE additionally requires that all notes from both chords being compared at a given timestep share a single octave.

Value

logical

Examples

x <- "b_2 ce_g"
y <- "b_ cd#g"
note_is_equal(x, y)
note_is_identical(x, y)

x <- "b_2 ce_g"
y <- "b_2 cd#g"
pitch_is_equal(x, y)
pitch_is_identical(x, y)

# same number of same notes, same order: unequal sequence length
x <- "b_2 ce_g b_"
y <- "b_2 ce_gb_"
note_is_equal(x, y)

# same number of same notes, order, equal length: unequal number per timestep
x <- "b_2 ce_g b_"
y <- "b_2 ce_ gb_"
note_is_equal(x, y)

x <- "a1 b_2 a1b2c3 a1b4 g1a1b1"
y <- "a_2 g#2 d1e1f2g3 a1b2b4 d1e1"
octave_is_equal(x, y)
octave_is_identical(x, y)
octave_is_identical(x, y, single_octave = TRUE)

Description

Relational operators for comparing two noteworthy class objects.

Usage

## S3 method for class 'noteworthy'
e1 == e2

## S3 method for class 'noteworthy'
e1 != e2

## S3 method for class 'noteworthy'
e1 < e2

## S3 method for class 'noteworthy'
e1 <= e2

## S3 method for class 'noteworthy'
e1 > e2

## S3 method for class 'noteworthy'
e1 >= e2

Arguments

Details

Equality is assessed in the same manner as used for note_sort() when sorting pitches. What matters is the underlying semitone value associated with each pitch, not the string notation such as flat vs. sharp (see pitch_is_identical()). When comparing chords, or a chord vs. a single note, comparison favors the root. Comparison is made of the respective lowest pitches, then proceeds to the next pitch if equal.

For these operators, the objects on the left and right side of the operator must both be noteworthy or an error is returned.

The examples include a chord with its pitches entered out of pitch order. This does not affect the results because pitches within chords are sorted before note to note comparisons at each timestep are done between e1 and e2.

Value

logical vector

Examples

x <- as_noteworthy("f# a d'f#'a' d'f#'a'")
y <- as_noteworthy("g_ b f#'a'd' d'd''")
x == y
x != y
x < y
x > y
x <= y
x >= y

Description

Inspect basic metadata for noteworthy strings.

Usage

n_steps(x)

n_notes(notes)

n_chords(notes)

n_octaves(notes)

chord_size(notes)

octave_type(notes)

accidental_type(x)

time_format(x)

is_space_time(x)

is_vector_time(x)

note_is_tick(notes)

note_is_integer(notes)

note_has_tick(notes)

note_has_integer(notes)

note_is_rest(notes)

note_has_rest(notes)

Arguments

Details

These functions inspect the basic metadata of noteworthy strings. For functions that perform basic checks on strings, see note-checks().

The ⁠n_*⁠ functions give summary totals of the number of timesteps, number of individual note (non-chord) timesteps, number of chord time steps, and the number of distinct octaves present across timesteps.

Functions pertaining to type or format of a noteworthy string provide information on how a particular string is defined, e.g. time_format. Note that the result pertains to true noteworthy-class objects. If inspecting a standard character string, the result pertains to post-conversion to the noteworthy class and does not necessarily reflect what is found in notes verbatim. See examples.

Value

varies by function

A note on generic functions

n_steps() and the three time format functions are generic since they apply clearly to and are useful for not only noteworthy strings, but also note info, music, and lyrics objects. If x is still a simple character string, these functions attempt to guess if it is noteworthy, note info, or music. Lyrics content is arbitrary so is never considered for a simple character string. Best practice is to set the class before using these functions anyway.

There are many package functions that operate on noteworthy strings that could in concept also work on music objects, but the expectation is that sound and time/info are disentangled for analysis. The music class is convenient and relatively efficient data entry, e.g., for transcription purposes, but it is not sensible to perform data analysis with quantities like pitch and time tightly bound together in a single string. This would only lead to repetitive deconstructions and reconstructions of music class objects.

The music class is intended to be a transient class such as during data import, data entry, or data export. Most functions that operate on noteworthy strings or note info strings strictly apply to one or the other. Generic functions are reserved for only the most fundamental and generally applicable metadata retrieval and format coercion.

See Also

tabr-methods(), note-checks(), note-summaries(), note-coerce(), valid-notes()

Examples

x <- "e_2 a_, c#f#a#"
n_steps(x)
n_notes(x)
n_chords(x)
n_octaves(x)
chord_size(x)

# Type is mixed in `x` but is inferred under default conversion rules.
# These check `x` once validated and coerced to 'noteworthy' class.
octave_type(x)
accidental_type(x)
# The default is tick octaves and flats
as_noteworthy(x)

time_format(x)
is_space_time(x)
is_vector_time(x)

Description

Basic summary functions for noteworthy strings.

Usage

tally_notes(notes, rests = FALSE)

tally_pitches(notes, rests = FALSE)

octaves(notes)

tally_octaves(notes)

distinct_notes(notes, rests = FALSE)

distinct_pitches(notes, rests = FALSE)

distinct_octaves(notes)

pitch_range(notes)

semitone_range(notes)

semitone_span(notes)

octave_range(notes)

octave_span(notes)

Arguments

Details

These functions provide basic summaries of noteworthy strings.

Returned object depends on the nature of the function. It can be integers, logical, character. Results can be a vector of equal length of a single value summary.

Use the ⁠tally_*⁠ and ⁠distinct_*⁠ functions specifically for summaries of unique elements.

distinct_notes() and distinct_pitches() filter a noteworthy string to its unique elements, respectively. These functions return another noteworthy string.

⁠*_span⁠ functions are just the size of a range, e.g., semitone_range() and semitone_span().

Value

varies by function

See Also

note-checks(), note-metadata(), note-coerce(), valid-notes()

Examples

x <- "r s e_2 a_, c#f#a#"
tally_notes(x)
tally_pitches(x)
octaves(x)
tally_octaves(x)
distinct_notes(x)
distinct_pitches(x)
distinct_octaves(x)

pitch_range(x)
semitone_range(x)
semitone_span(x)
octave_range(x)
octave_span(x)

Description

Functions for working with note info strings.

Usage

info_duration(x)

info_slur_on(x)

info_slur_off(x)

info_slide(x)

info_bend(x)

info_dotted(x)

info_single_dotted(x)

info_double_dotted(x)

info_annotation(x)

info_articulation(x)

Arguments

Details

If x is a phrase object, there are some parsing limitations such as tuplets and repeats.

Value

character

See Also

valid-noteinfo()

Examples

a <- notate("t8x", "Start here")
notes <- "a, b, c d e f g# a r ac'e' a c' e' c' r*3 ac'e'~ ac'e'"
info <- paste(a, "t8x t8-. 16 4.. 16- 16 2^ 2 4. 8( 4)( 4) 8*4 1 1")
x <- as_music(notes, info)

data.frame(
  duration = info_duration(x),
  slur_on = info_slur_on(x),
  slur_off = info_slur_off(x),
  slide = info_slide(x),
  bend = info_bend(x),
  dotted = info_dotted(x),
  dotted1 = info_single_dotted(x),
  dotted2 = info_double_dotted(x),
  annotation = info_annotation(x),
  articulation = info_articulation(x)
)

Description

Create a musical phrase from character strings that define notes, note metadata, and optionally explicit strings fretted. The latter can be used to ensure proper tablature layout.

Usage

phrase(notes, info = NULL, string = NULL, bar = NULL)

p(notes, info = NULL, string = NULL, bar = NULL)

Arguments

Details

A phrase object combines a valid string of notes with a corresponding valid string of note info. The only required note info is time, but other information can be included as well. You do not need to input an existing noteworthy class object and noteinfo class object, but both inputs must be valid and thus coercible to these classes. This is similar to how the music class works. The difference with phrase objects is that they are used to create LilyPond syntax analogous to what a music object contains.

Note that if you convert a music object to a phrase object, you are changing contexts. The phrase object is the simplest LilyPond-format music structure. Coercion with phrase() strips all attributes of a music object and retains only notes, note info and string numbers.

See the help documentation on noteworthy, noteinfo, and music classes for an understanding of the input data structures. The function p() is a convenient shorthand wrapper for phrase().

If a string is provided to bar, it is interpreted as LilyPond bar notation. E.g., bar = "|" adds the LilyPond syntax ⁠\bar "|"⁠ to the end of a phrase. If only a bar check is desired, use bar = TRUE. FALSE is treated as NULL for completeness.

Value

a phrase.

See Also

valid-notes(), valid-noteinfo(), music()

Examples

phrase("c ec'g' ec'g'", "4- 4 2") # no string arg (not recommended for tabs)
phrase("c ec4g4 ec4g4", "4 4 2") # same as above
phrase("c b, c", "4. 8( 8)", "5 5 5") # direction implies hammer on
phrase("b2 c d", "4( 4)- 2", "5 5 5") # hammer and slide

phrase("c ec'g' ec'g'", "1 1 1", "5 432 432")
p("c ec'g' ec'g'", 1, "5 4 4") # same as above


n <- "a, b, c d e f g e f g a~ a"
i <- "8- 8 8 8-. t8( t8)( t8) t16( t16)( t16) 8 1"
m <- as_music(n, i)

x <- p(n, i)
x
identical(x, p(m))

x <- "a,4;5*5 b,4- c4 cgc'e'~4 cgc'e'1 e'4;2 c';3 g;4 c;5 ce'1;51"
p(x)
identical(p(x), p(as_music(x)))

x <- p("a b", 2, bar = "|.")
x2 <- pc(p("a b", 2), '\\bar "|."')
identical(x, x2)

Description

These helper functions add some validation checks for phrase and candidate phrase objects.

Usage

as_phrase(phrase)

phrasey(phrase)

notify(phrase)

phrase_notes(phrase, collapse = TRUE)

phrase_info(phrase, collapse = TRUE, annotations = TRUE)

phrase_strings(phrase, collapse = FALSE)

notable(phrase)

Arguments

Details

Use these functions with some caution. They are not intended for strictness and perfection. phrasey() checks whether an object is weakly phrase-like and returns TRUE or FALSE. It can be used to safeguard against the most obvious cases of phrase() not containing valid phrase syntax when programming. However, it may also be limiting. Use wear sensible.

as_phrase() coerces an object to a phrase object if possible. This function performs an internal phrasey() check.

notify() attempts to decompose a phrase object back to its original input vectors consisting of notes, note info, and optionally, instrument string numbering. If successful, it returns a tibble data frame with columns: notes, info, string.

Unless decomposing very simple phrases, this function is likely to reveal limitations. Complex phrase objects constructed originally with phrase() can be challenging to deconstruct in a one to one manner. Information may be lost, garbled, or the function may fail. For example, this function is not advanced enough to unravel repeat notation or tuplets.

notable() returns TRUE or FALSE regarding whether a phrase can be converted back to character string inputs, not necessarily with complete correctness, but without simple failure.It checks for phrasiness. Then it tries to call notify() and returns FALSE gracefully if that call throws an exception.

Value

see details for each function's purpose and return value.

Examples

# Create a list of phrase objects
p1 <- phrase("c ec'g' ec'g'", "4 4 2") # no string numbers (not recommended)
p2 <- phrase("c ec4g4 ec4g4", "4 4 2") # same as above
p3 <- phrase("c b, c", "4. 8( 8)", "5 5 5") # direction implies hammer on
p4 <- phrase("b2 c d", "4( 4)- 2", "5 5 5") # hammer and slide
p5 <- phrase("c ec'g'~ ec'g'", 1, "5 432 432") # tied chord
x <- list(p1, p2, p3, p4, p5)

# Check if phrases and strings are phrasey
sapply(x, phrasey)
sapply(as.character(x), phrasey, USE.NAMES = FALSE)

# Coerce character string representation to phrase and compare with original
y <- lapply(as.character(x), as_phrase)
identical(x, y)

# Check if notable
sapply(x, notable)
notable(p("a b c", 1))
notable("a b x") # note: not constructible as a phrase in the first place

# Notify phrases
d <- do.call(rbind, lapply(x, notify))
d

# Wrappers around notify extract components, default to collapsed strings
phrase_notes(p5)
phrase_info(p5)
phrase_strings(p5)

# If phrase decomposition works well, coercion is one to one
x2 <- lapply(x,
  function(x) p(phrase_notes(x), phrase_info(x), phrase_strings(x))
)
identical(x, x2)

Description

Convert between pitches, chords, semitones and frequencies.

Usage

pitch_freq(notes, a4 = 440)

pitch_semitones(notes)

chord_freq(notes, a4 = 440)

chord_semitones(notes)

freq_pitch(
  freq,
  octaves = c("tick", "integer"),
  accidentals = c("flat", "sharp"),
  collapse = FALSE,
  a4 = 440
)

freq_semitones(freq, a4 = 440)

semitone_pitch(
  semitones,
  octaves = c("tick", "integer"),
  accidentals = c("flat", "sharp"),
  collapse = FALSE
)

semitone_freq(semitones, a4 = 440)

Arguments

Details

Frequencies are in Hertz. Values are based on the 12-tone equal-tempered scale. When converting an arbitrary frequency to pitch, it is rounded to the nearest pitch. pitch_freq() and pitch_semitones() strictly accept single notes in noteworthy strings and return numeric vectors. chord_freq() and chord_semitones() accept any noteworthy string and always return a list. These are provided so that all functions are type-safe. See examples.

Value

integer, numeric or noteworthy vector

Examples

x <- "a e4 a4 e5 a5"
y <- pitch_freq(x)
y

freq_semitones(y)
freq_pitch(y)

identical(as_noteworthy(x), freq_pitch(y, "integer", collapse = TRUE))

s <- pitch_semitones(x)
s
semitone_pitch(s)

x <- "a, a,c#e"
chord_semitones(x)
chord_freq(x)

Description

Create a noteworthy string of a sequence of consecutive pitches.

Usage

pitch_seq(x, y, key = NULL, scale = NULL, format = c("space", "vector"))

Arguments

Details

Note that all pitches resulting from the defined sequence must be in the semitone range 0-131 or an error is thrown.

If not using a chromatic sequence and x (or y if also a pitch) is not part of the key signature or scale, the sequence is internally bound. See examples.

Format of accidentals in the result is prioritized by the scale and key, the key when no scale is given, then x (and y if also a pitch), and finally defaults to flats if ambiguous.

Value

noteworthy

Examples

# chromatic sequence (default)
pitch_seq("a,", 13)
pitch_seq("c5", -2)
pitch_seq("c", "b")

# diatonic sequence
pitch_seq("c", 8, key = "c")
pitch_seq("c", 8, "am")
pitch_seq("c#,", "a#'", "am")

# combine with alternative scale
pitch_seq("a", 8, "am", "harmonic minor")

Description

Create a fretboard diagram for a single chord or a general progression.

Usage

plot_fretboard(
  string,
  fret,
  labels = NULL,
  mute = FALSE,
  label_size = 10,
  label_color = "white",
  point_size = 10,
  point_color = "black",
  point_fill = "black",
  group = NULL,
  horizontal = FALSE,
  left_handed = FALSE,
  fret_range = NULL,
  fret_labels = NULL,
  fret_offset = FALSE,
  accidentals = c("flat", "sharp"),
  tuning = "standard",
  show_tuning = FALSE,
  asp = NULL,
  base_size = 20
)

plot_chord(
  chord,
  labels = NULL,
  label_size = 10,
  label_color = "white",
  point_size = 10,
  point_color = "black",
  point_fill = "black",
  group = NULL,
  horizontal = FALSE,
  left_handed = FALSE,
  fret_range = NULL,
  fret_labels = NULL,
  fret_offset = FALSE,
  accidentals = c("flat", "sharp"),
  tuning = "standard",
  show_tuning = FALSE,
  asp = NULL,
  base_size = 20
)

Arguments

Details

These functions are under development and subject to change. They each return a ggplot object.

Use plot_chord() to create a fretboard diagram of a specific chord. plot_chord() accepts a character string in simple fretboard format, e.g., chord = "xo221o". Zero is allowed in place of "o". This only works when no spaces or semicolons are detected. The function checks for spaces first, then semicolons, to split fret numbers. Do not mix formats. For example, you can use chord = "xo221o", chord = "x 8 10 10 9 8" or chord = "x;8;10;10;9;8". Trailing delimiters are ignored (LilyPond format: "x;8;10;10;9;8;"). If there are fewer fret values than there are strings on the instrument, as inferred from tuning, then muted strings, x, are inferred for the remaining lower-pitch strings.

plot_fretboard() produces a more general fretboard diagram plot. It is intended for scales, arpeggios and other patterns along the fretboard. For this function, provide vectors of string and fret numbers. mute is available but not as applicable for this function; it is a pass-through from plot_chord(). For single chord diagrams, use plot_chord(). The letter "o" is also allowed in fret for open strings and will display below the lowest fret plotted. The number 0 is treated with the intent of displaying the corresponding position on the instrument neck.

Number of strings is derived from tuning. See tunings() for pre-defined tunings and examples of explicit tunings. tuning affects point labels when labels = "notes".

Providing fret_labels overrides the default (minimal) fret numbering behavior for the fret axis. These are only intended to be integers. The vector of integers given is sorted and subset if needed to the range of frets that appear in the plot. See example.

Value

a ggplot object

Examples

# General patterns: scale shifting exercise
string <- c(6, 6, 6, 5, 5, 5, 4, 4, 4, 4, 4, 3, 3, 3, 2, 2, 2, 1, 1, 1)
fret <- "2 4 5 2 4 5 2 4 6 7 9 6 7 9 7 9 10 7 9 10" # string input accepted
plot_fretboard(string, fret, labels = "notes", fret_offset = TRUE)
plot_fretboard(string, fret, fret_labels = c(3, 5, 7, 9, 12), show_tuning = TRUE)

# open and muted strings on shifted general fretboard layout
# try to use plot_chord() if more suitable
plot_fretboard("6 5 4 3", "o 9 10 12", mute = 2, show_tuning = TRUE)

# Single chord diagrams
# open chord
idx <- c(1, 1, 2, 2, 2, 1)
fill <- c("white", "black")[idx]
lab_col <- c("black", "white")[idx]
plot_chord("xo221o", "notes", label_color = lab_col, point_fill = fill)

# moveable chord
plot_chord("355433", horizontal = TRUE, show_tuning = TRUE)

# leading x inferred; same as plot_chord("xxo321")
plot_chord("o231", fret_labels = 3)
plot_chord("10 12 13 11", show_tuning = TRUE)
plot_chord("o x 10 12 13 11", fret_range = c(9, 14), fret_labels = c(9, 12))

Description

These functions are wrappers around the ⁠render_music*⁠ functions. They abstract the process of rendering a sheet music snippet to png and loading the rendered image back into R to be displayed as a plot in an open graphics device or inserted into an R Markdown code chunk.

Usage

plot_music(
  music,
  clef = "treble",
  tab = FALSE,
  tuning = "standard",
  string_names = NULL,
  header = NULL,
  paper = NULL,
  colors = NULL,
  transparent = FALSE,
  res = 300
)

plot_music_tc(
  music,
  header = NULL,
  paper = NULL,
  colors = NULL,
  transparent = FALSE,
  res = 300
)

plot_music_bc(
  music,
  header = NULL,
  paper = NULL,
  colors = NULL,
  transparent = FALSE,
  res = 300
)

plot_music_tab(
  music,
  clef = NA,
  tuning = "standard",
  string_names = NULL,
  header = NULL,
  paper = NULL,
  colors = NULL,
  transparent = FALSE,
  res = 300
)

plot_music_guitar(
  music,
  tuning = "standard",
  string_names = NULL,
  header = NULL,
  paper = NULL,
  colors = NULL,
  transparent = FALSE,
  res = 300
)

plot_music_bass(
  music,
  tuning = "bass",
  string_names = FALSE,
  header = NULL,
  paper = NULL,
  colors = NULL,
  transparent = FALSE,
  res = 300
)

Arguments

Details

While these functions abstract away the details of the process, this is not the same as making the plot completely in R. R is only displaying the intermediary png file. LilyPond is required to engrave the sheet music.

For R Markdown you can alternatively render the png using the corresponding ⁠render_music*⁠ function and then place it in the document explicitly using knitr::include_graphics(). See render_music() for more details.

Value

a plot

See Also

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

Examples

x <- "a,4;5*5 b,4- c4 cgc'e'~4 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,,4- c,4 c,g,c~4 c,g,c1 c4;1 g,;2 c,;3 g,;2 c,c1;31"
y <- as_music(y)

## Not run: 
if(tabr_options()$lilypond != ""){ # requires LilyPond installation
  plot_music(x)
  plot_music(x, "treble_8", tab = TRUE)

  plot_music_tc(x)
  plot_music_bc(x)

  plot_music_tab(x)
  plot_music_guitar(x)
  plot_music_bass(y)
}

## End(Not run)

Description

Convert between frequency ratios and logarithmic cents

Usage

ratio_to_cents(x, y = NULL)

cents_to_ratio(x)

Arguments

Value

numeric

Examples

ratio_to_cents(c(0.5, 1, 1.5, 2))
cents_to_ratio(c(-1200, 0, 701.955, 1200))

Description

Read MIDI file into a data frame and inspect the music data with supporting functions.

Usage

read_midi(file, ticks_per_qtr = 480)

midi_metadata(x)

midi_notes(x, channel = NULL, track = NULL, noteworthy = TRUE)

midi_time(x)

midi_key(x)

ticks_to_duration(x, ticks_per_qtr = 480)

duration_to_ticks(x, ticks_per_qtr = 480)

Arguments

Details

The read_midi() function wraps around tuneR::readMidi() by Uwe Ligges and Johanna Mielke. midi_notes() is a work in progress, but converts MIDI data to noteworthy strings and note info formats. This makes it easy to analyze, transform and edit the music data as well as render it to sheet music and a new MIDI file.

read_midi() does not parse the ticks per quarter note from the MIDI file input at this time. It must be specified with ticks_per_qtr.

Value

a tibble data frame

Examples

ticks_to_duration(c(120, 160))
ticks_to_duration(c(128, 192, 512), ticks_per_qtr = 384)
duration_to_ticks(c("t8", "8", "8.", "8.."))
duration_to_ticks(c("t8 8 8. 8.."), ticks_per_qtr = 384)

file <- system.file("example2.mid", package = "tabr")
if(require("tuneR")){
  x <- read_midi(file, ticks_per_qtr = 384)
  midi_metadata(x)
  midi_time(x)
  midi_key(x)
  midi_notes(x, channel = 0, noteworthy = FALSE)

  (x <- midi_notes(x, channel = 0))
  (x <- as_music(x$pitch, x$duration))

  # requires LilyPond installation
  if(tabr_options()$lilypond != ""){
    out <- file.path(tempdir(), "out.pdf")
    phrase(x) |> track_bc() |> score() |> tab(out, details = FALSE)
  }
}

Description

Render a standalone chord chart of chord fretboard diagrams with LilyPond for a set of chords.

Usage

render_chordchart(
  chords,
  file,
  size = 1.2,
  header = NULL,
  paper = NULL,
  colors = NULL,
  crop_png = TRUE,
  transparent = FALSE,
  res = 150,
  keep_ly = FALSE,
  details = FALSE
)

Arguments

Details

This function uses a generates a LilyPond template for displaying only a fretboard diagram chart. It then passes the file to LilyPond for rendering. To plot specific fretboard diagrams in R using ggplot and with greater control, use plot_fretboard().

The options for paper include the following and have the following default values if not provided.

• textheight = 220

• linewidth = 150

• indent = 0

• fontsize = 10

• page_numbers = FALSE

• print_first_page_number = TRUE

• first_page_number = 1

fontsize only controls the global font size. If you want to scale the size of the fretboard diagrams up or down use the the size argument rather than this paper value.

Note that chord chart output must fit on a single page. If the full set of chord diagrams does not fit on one page then diagrams will be clipped in the rendered output. Use size to keep the output to one page or make multiple sheets separately.

Value

writes files to disk

See Also

plot_fretboard(), lilypond(), tab()

Examples

suppressPackageStartupMessages(library(dplyr))

chords <- filter(
  guitarChords, root %in% c("c", "f") & id %in% c("7", "M7", "m7") &
  !grepl("#", notes) & root_fret <= 12) |>
  arrange(root, id)
chords <- setNames(chords$fretboard, chords$lp_name)
head(chords)

# requires LilyPond installation
if(tabr_options()$lilypond != ""){
  outfile <- file.path(tempdir(), "out.pdf")
  hdr <- list(
    title = "Dominant 7th, major 7th and minor 7th chords",
    subtitle = "C and F root"
  )
  render_chordchart(chords, outfile, 2, hdr, list(textheight = 175))
}

Description

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

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.

Value

nothing returned; a file is written.

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"))

## Not run: 
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)
}

## End(Not run)

Description

Create a repeat section in LilyPond readable format.

Usage

rp(phrase, n = 1)

pct(phrase, n = 1, counter = FALSE, step = 1, reset = TRUE)

volta(phrase, n = 1, endings = NULL, silent = FALSE)

Arguments