Complete Guide to gm

Pitches

The pitches argument in Line() represents a musical line’s pitch contents.

pitches must be a list, whose members can be

1. single pitch notations, like "C4", to represent the pitch contents of notes,

2. single MIDI note numbers, like 60 or "60", also to represent the pitch contents of notes,

3. single NAs to represent the pitch contents of rests, and

4. vectors of pitch notations and MIDI note numbers, like c("C4", "61"), to represent the pitch contents of chords.

A pitch notation consists of

1. a tone name (from A to G),
2. an optional accidental (-, --, # or ##), and
3. a number identifying the pitch’s octave (from 0 to 9).

A MIDI note number is a number between 12 and 127.

See a conversion table of pitch notations and MIDI note numbers.

An advantage of MIDI note numbers is that they are easy to operate. For example, we have the following four MIDI note numbers:

pitches <- c(60, 62, 64, 65)

We can transpose them up by a fifth easily:

pitches + 7
#> [1] 67 69 71 72

However, this advantage comes at a cost: MIDI note numbers are always ambiguous. For example, the following three pitches are all equivalent to MIDI note number 73:

gm interprets MIDI note numbers based on keys and neighbor pitches. In the following example, MIDI note number 73 is interpreted as C5 sharp in the first measure, but as D5 flat in the second measure, for these two measures have different keys.

l <- Line(list(73, 73), list(2, 2))
m <- Music() + Meter(2, 4) + Key(7, bar = 1) + Key(-7, bar = 2) + l
show(m)

gm is not perfect in interpreting MIDI note numbers, so if you want it to be precise, use pitch notations.

Durations

The durations argument in Line() represents a musical line’s durational contents.

durations must be a list, whose members can be

1. single duration notations or their abbreviations, like "quarter" or just "q",

2. single duration values, like 1, which is equivalent to "quarter", and

3. Duration objects returned by tuplet(), which is used to create complex tuplets.

The most basic duration notations consist of only duration types. The duration types (and their abbreviations) defined in gm are:

• "maxima" or "m"

• "long" or "l"

• "breve" or "b"

• "whole" or "w"

• "half" or "h"

• "quarter" or "q"

• "eighth" or "8"

• "16th" or "16"

• "32nd" or "32"

• "64th" or "64"

• "128th" or "128"

• "256th" or "256"

• "512th" or "512"

• "1024th" or "1024"

For example, the following musical line consists of a whole rest, a quarter rest, and a 32nd rest:

m <- Music() + Meter(6, 4) + Line(list(NA, NA, NA), list("w", "q", "32"))
show(m)

The duration type or its abbreviation can be followed by zero to four dots, in a duration notation, as in the following example:

l <- Line(rep(list(NA), 5), list("q", "q.", "q..", "q...", "q...."))
m <- Music() + Meter(9, 4) + l
show(m)

You can also append what we call “tupler” notations in gm to a duration notation to represent a tuplet:

l <- Line(rep(list(NA), 3), list("q/3", "q/3", "q/3"))
m <- Music() + Meter(1, 4) + l
show(m)

In the above example, we use "q/3" to represent a triplet. You can read "q/3" as “divide a quarter note into three parts, and take one of them”. We will talk more about tuplets in the next section.

To sum up, a duration notation consists of

1. a duration type or its abbreviation,
2. zero to four dots, and
3. zero or more tupler notations.

You get a duration value when convert a duration notation to value. For example, 1 is equivalent to "quarter", and 1.5 to "quarter.".

However, the duration notations that can be converted to duration values must NOT contain tupler notation. For example, if you convert "q/3" to value, you get 1/3, but this in gm is not a valid duration value. We put this restriction to avoid ambiguity. For example, value 1/3 can be "q/3", "half/6", or two tied "eighth/3"s.

Also note that you can NOT use characters to represent duration values. For example, you can use duration value 1 to represent quarter note, but not "1", which is invalid in gm. This is also to avoid ambiguity. For example, we can use "eighth" to represent eighth note, whose abbreviation is "8". if "8" was a duration value, it would represent breve note, there would be a conflict. So keep "8" to only eighth note, and 8 to breve note.

Tuplets

Duration notations can’t represent some complex tuplets.

For example, how to represent the first tuplet in the following score:

This tuplet can read as “divide a quarter note into three parts, take two of them”. We can’t express “take two” in any duration notation. This is where we need tuplet() and Tupler(). Let’s look at an example.

We can express duration notation "quarter/3" with tuplet() and Tupler() as:

t <- tuplet("quarter", Tupler(3, unit = "eighth", take = "eighth"))

This code can read as: divide a quarter note (tuplet("quarter", ...)) into there parts (Tupler(3, ...)), each part is an eighth note (unit = "eighth"), and we take one part (take = "eighth").

Print it and we can see it is just equivalent to "quarter/3":

t
#> quarter / 3

Modify the code and we can represent the aforementioned tuplet:

tuplet("quarter", Tupler(3, unit = "eighth", take = "quarter"))
#> quarter / 3 * (quarter / eighth)

The difference is that this time we take two parts or units.

To sum up, we use tuplet() to create complex tuplets, and Tupler() to specify how to divide a duration into parts and what to take from these parts.

We can go further with these two functions.

For example, we can change unit in the above example:

t <- tuplet("quarter", Tupler(3, unit = "quarter", take = "quarter"))
t
#> quarter / 3 * (quarter / quarter)

The score looks like this:

m <- Music() + Meter(1, 4) + Line(list(NA, NA, NA), list(t, t, t))
show(m)

This may seem strange to you, but it’s syntactically valid.

We can even create complex nested tuplets like in the following score:

The first three tuplets can be represented by:

t <- tuplet(
  "half",
  Tupler(3, unit = "quarter", take = "half"),
  Tupler(3, unit = "quarter", take = "quarter")
)

t
#> half / 3 * (half / quarter) / 3

Note that there are two Tupler objects in the above code.

Create this score:

l <- Line(rep(list(NA), 4), list(t, t, t, tuplet("half/3")))
m <- Music() + Meter(2, 4) + l
show(m)

Yes, there is something wrong with this score. MuseScore (which gm uses internally) has some bugs, so it can’t convert MusicXML (which gm uses to represent musical scores internally) containing nested tuplets to score correctly. So if there are nested tuplets in your Music object, you can export it to MusicXML file with export(), and open the file with other notation software like Finale. Below is a correct score generated in Finale:

Note that in Line() objects, tuplets must form tuplet groups, or you will get an error. For example,

# try to create a `Line` object which consists of only one tuplet
Line(list(NA), list("q/3"))
#> Error: Tuplets in `durations` must form complete groups.
#> 
#> * The tuplet group containing `durations[[1]]` is incomplete.

Also note that tuplet groups must NOT cross barline. For example,

l <- Line(list(NA, NA, NA), list("h/3", "h/3", "h/3"))
m <- Music() + Meter(1, 4) + l
show(m)
#> Error: Any tuplet group in any Line of the Music must not cross barline.
#> 
#> * In Line 1, the tuplet group starting at position 1 crosses barline.

Tie

Sometimes you may want to tie together some notes, you can do this by specifying the argument tie in Line().

l <- Line(
  pitches = list(c("C5", "E5"), c("C5", "E5"), c("C5", "E5"), c("C5", "E5")),
  durations = list("quarter", "quarter", "quarter", "quarter"),
  tie = list(c(1, 1), c(2, 2), 3)
)

m <- Music() + Meter(4, 4) + l
show(m)

In tie = list(c(1, 1), c(2, 2), 3) in the above example,

1. c(1, 1) means we add a tie to the first note of the first chord to connect it with the first note of the second chord. Note that to tie two adjacent notes, we only specify the position of the first note.

2. Similarly, c(2, 2) means we add a tie to the second note of the second chord to connect it with the second note of the third chord.

3. 3 means we add ties to the whole third chord to connect it with the fourth chord.

However, don’t bother to split a cross-bar note and tie resulted notes together, gm takes care of this kind of situations, like in the following example:

m <- Music() + Meter(1, 4) + Line(list("C5"), list(4))
show(m)

The C5 whole note is automatically split into four tied quarter notes, because the time signature is 1/4.

bar and offset

With these two arguments in Line(), you can easily insert a Line object at other positions rather than the first beat of the first measure.

For example, below is an ordinary Line object:

l <- Line(list("C5", "D5", "E5"), list(1, 1, 1))
m <- Music() + Meter(4, 4) + l
show(m)

We can insert it into the third measure after the second beat:

l <- Line(list("C5", "D5", "E5"), list(1, 1, 1), bar = 3, offset = 2)
m <- Music() + Meter(4, 4) + l
show(m)

Multiple Line Objects

We can add multiple Line objects to a Music object in different ways.

For example, below is a Music object that consists of only one Line object:

l1 <- Line(rep(list("E5"), 8), rep(list(0.5), 8), name = "a")
m <- Music() + Meter(4, 4) + l1
show(m)

The Line object is named “a” with argument name.

Below is another Line object named “b”:

Line(list("C4", "G4"), list(2, 2), name = "b")

We can add Line “b” as another part:

l2 <- Line(list("C4", "G4"), list(2, 2), name = "b")
show(m + l2)

Line “b” is appended at the end by default. We can make Line “b” come before Line “a”, by specifying argument to and after:

l2 <- Line(list("C4", "G4"), list(2, 2), name = "b", to = "a", after = FALSE)
m <- m + l2
show(m)

to = "a" means we add Line “b” with Line “a” as a reference.

The Music object contains two Line objects now. Let’s introduce a third Line object named “c”:

Line(list("A4", "B4", "C5"), rep(list("w/3"), 3), name = "c")

We can add it to Line “a” as another voice:

l3 <- Line(
  pitches = list("A4", "B4", "C5"),
  durations = rep(list("w/3"), 3),
  name = "c",
  to = "a",
  as = "voice"
)

m <- m + l3
show(m)

Finally, below is a fourth Line, let’s add it to Line “b” as another staff:

l4 <- Line(list("E3"), list(4), to = "b", as = "staff", name = "d")
m <- m + l4
show(m)

We can print this Music to check its structure:

m
#> Music
#> 
#> Line 1
#> 
#> * as part 1 staff 1 voice 1
#> * of length 2
#> * of pitches C4, G4
#> * of durations 2, 2
#> * of name "b"
#> 
#> Line 2
#> 
#> * as part 1 staff 2 voice 1
#> * of length 1
#> * of pitch E3
#> * of duration 4
#> * of name "d"
#> 
#> Line 3
#> 
#> * as part 2 staff 1 voice 1
#> * of length 8
#> * of pitches E5, E5, E5, E5, E5, E5, E5, E5
#> * of durations 1/2, 1/2, 1/2, 1/2, 1/2, 1/2, 1/2, 1/2
#> * of name "a"
#> 
#> Line 4
#> 
#> * as part 2 staff 1 voice 2
#> * of length 3
#> * of pitches A4, B4, C5
#> * of durations 4/3, 4/3, 4/3
#> * of name "c"
#> 
#> Meter 4/4

The Music contains four Lines now, which have different states. In summary, there are two parts, the first part contains two staffs, which are Line “b” and Line “d”, and the second part contains one staff which has two voices, which are Line “a” and Line “c”.

With these arguments in Line() we have so far introduced, you can create quite complex musical scores easily.

R Package tabr

At the time of writing, the author knows only tabr that has similar purposes and similar level of functionality to gm, among other R music packages.

However, there are some noticeable differences.

First, besides music generation, tabr also provides functions for music analysis and manipulation. gm is only for music generation.

Second, as for music generation, tabr is more about music notation. For example, tabr can generate guitar tabs and add more music notation symbols to score than gm can. gm is more about music creation at a higher level.

Third, gm embeds generated music in R Markdown documents and R Jupyter Notebooks, while tabr exports it.

Fourth, gm uses R’s basic data structures such as vector and list to represent music, while tabr uses strings.

Last, gm’s language is simpler than tabr’s, it is more straightforward to add components such as musical lines in gm. This and the above difference make gm more suitable for music programming.

Python Library music21

music21 is a mature and famous Python library which provides abundant tools for music generation and analysis. For its music generation functionality, music21 can generate more professional musical scores than gm can, and also works in Python Jupyter Notebooks.

However, the advantage of gm is still that its language is far simpler and more intuitive.

For example, in music21, it’s cumbersome to define notes and add them to musical lines:

from music21 import *

note1 = note.Note("C4")
note2 = note.Note("F#4")
note3 = note.Note("B-2")

stream1 = stream.Stream()

stream1.append(note1)
stream1.append(note2)
stream1.append(note3)

Also, creation of complex and nested tuplets is not straightforward. See Complex and Tuplets.

And sometimes users have to be concerned about musical score structures when they only want to express music structures at a higher level.

Summary

In summary, gm is a good tool for expression of high-level music structures and communication of generated music. It’s not yet for professional level music notation.