Quickstart

This packet shows you how to play tunes encoded in the RTTTL format with an Arduino.

You can get many RTTTL tunes on the web, e.g.:

Expressing the Same Tune in Several Different Ways (Encodings)

Tunes in Arduino sketches are frequently described (i.e., encoded) using two lists:
one list to describe the “pitch” of each note”, and another to give its “tempo” (to be precise,
1 divided by its duration).

For example, the first stanza of SuperMario Brothers Theme Song has
these pitches and tempos:

int pitches[] = {
  NOTE_E6, NOTE_E6, 0, NOTE_E6,
  0, NOTE_C6, NOTE_E6, 0,
  NOTE_G6, 0, 0,  0,
  NOTE_G5, 0, 0, 0,
  ..
};

int tempo[] = {
  12, 12, 12, 12,
  12, 12, 12, 12,
  12, 12, 12, 12,
  12, 12, 12, 12,
  ..
};

That stanza can be played by calling tone() for each corresponding pair in
the pitches[] and tempo[] arrays:

for (int i; i < numerOfNotes; i++) {
    tone(SPEAKER_PIN, pitches[i], 1000/tempo[i]);
}

That same tune can be encoded in many different ways. One way, developed by NOKIA for storing
telephone ringtones, is called the “Ring Tone Text Transfer Library”, or RTTTL (or even RTTL)
for short. In the RTTTL encoding, the tune shown above looks like this:

const char * mymario = "smb:d=4,o=5,b=180:"
                       "16e6,16e6,16p,16e6,"
                       "16p,16c6,16e6,16p,"
                       "16g6,16p,16p,16p,"
                       "16g5,16p,16p,16p,"

The RTTTL format is not only more compact than the simple tones/tempos lists, but also has the
advantages that

The RTTTL format in detail

An RTTTL encoded tune has three main parts:

Part Value (for Super Mario Brothers Theme Song)
The Title "smb:"
The Defaults "d=4,o=5,b=180:"
The “Song Data” "16e6,16e6,16p,16e6,16p,16c6,16e6,16p,16g6,16p,16p,16p,16g5,16p,16p,16p,"

The title is a string, which must be 10 characters or less, and cannot contain a :. In the above
case, the title is smb which is an abbreviation for “Super Mario Brothers”.

The defaults (which are all optional) can be used to abbreviate the songdata:

The song data consists of a series of comma-separated note descriptions, each of which has the following
format:

[duration] pitch [octave] [dot]

where:

duration
can have one of the values 1, 2, 4, 8, 16, or 32, depending on whether it is a
whole note, half-note, quarter-note, etc. It is optional because the duration of a particular
note might be the same as the default, in which case it doesn’t need to be specified.
pitch
is the pitch to be played, in lower case. The first value in the pitches array for “Super Mario Brothers”
is NOTE_E6, so in this case the corresponding RTTTL note is e. A sharp note has the extra notation #,
so for example NOTE_AS6 is a#6 in RTTTL. The letter p designates a pause.
octave
is the same as the scale at the end of each note in the pitches array.
Since the first note in the pitches above is NOTE_E6, the scale is 6.
The octave is optional if it is the same as the default octave.
dot
When present, a literal dot (.) signifies that the note should be played for 50% longer
than indicated by its duration.

With this format, the first note of the Super Mario Brothers tune is
designated in RTTTL simply by:

16e6

where 16 designates a sixteenth note (i.e., a note with 1/4th of the duration of a
quarter-note), and the pitch to be played is note E in the 6th octave,
which is 1319 Hz.

How to write your own RTTTL file

The biggest hurdle in converting the pitches[], tempo[] lists into an RTTTL file
is figuring out what note duration corresponds to a given pitch[i], tempo[i] pair.
It’s easy to see how NOTE_E6 corresponds to e6 in the songdata.

But how should the tempos be converted to quarter-notes, sixteenth-notes, etc.?
If we make the assumption that the “beat” given in the defaults section of an RTTTL
tune corresponds to the number of quarter-notes per minute, then the amount of time
to play a whole note is:

RTTTL:  time to play a whole note   = 4 * duration of a quarter note

                                    = 4 * 60 
                                      ------
                                       beat

The time to play any other “allowed” durations of notes would be

RTTTL:  time to play a half note    = 4 * 60
                                      ---------
                                      beat * 2

        time to play a quarter note = 4 * 60
                                      --------
                                      beat * 4

        time to play any note       = 4 * 60     // X = 1, 2, 4, 8, 16, or 32
                                      --------
                                      beat * X

The duration of any note in the pitches/tempo arrays is just

melody/tempo format: duration of any note =    1
                                            -------
                                             tempo

Equating these two expressions:

   1       4 * 60
------- = --------
 tempo    beat * X

Therefore,

beat = 240 * tempo
       -----------
            X

Solving this equation is tricky because beat and tempo must be integers, and X can only
take on one of a discreet set of values, 1, 2, 4, 8, 16, and 32. One way to solve the
problem is:

  1. Find the fastest note in the tempo array. In the case of Super Mario Brothers, that
    tempo value is 12.

  2. Assume that this fastest note is the fastest note that can be expressed in the RTTTL format,
    which is a thirtysecond-note, so X = 32.

Then:

beat = 240 * 12 = 90
       --------
         32

So if the beat is 90 quarter-notes per minute, then any element in the tempo array with a
value of 12 would be expressed as a “thirtysecond-note”, so the first note in the
Super Mario Brothers song would be expressed this way:

melody/tempo array format RTTTL format
melody[0] = NOTE_E6 “32e6”
tempo[0] = 12

In general, now that we know the beat, then the RTTTL value for any note in the tune can be
expressed as:

   X  =  4 * 60 * tempo
        ---------------
             90

But wait! X can only take on the values 1, 2, 4, 8, 16, and 32, and the tempo values are
integers. With these constraints:

X tempo
1 (whole note) 0.375 not an integer; not allowed
2 (half note) 0.75 not an integer; not allowed
4 (quarter note) 1.5 not an integer; not allowed
8 (eigth note) 3 OK
16 (sixteenth note) 6 OK
32 (thirtysecond note) 12 OK

Super Mario Brothers tune does not have any notes with a tempo of 3 or 6, but does have
notes with a tempo of 9, which is not one of the allowed values in the above table.
This tempo value can be expressed in RTTTL notation using the dot option to the
RTTTL string:

melody/tempo note Corresonding RTTTL note
melody[32] = NOTE_G5 32g5.
tempo[32] = 9

The bottom line is the RTTTL song data is not “magic”: it is easy to convert directly from
simple arrays of melody/tempo data to RTTTL data strings straightforwardly, as long as
you bear in mind the restrictions on the allowed values of X and the restrictions that
both beat and the tempo values must be integers.