RTTTLParser Library  1.0
RTTTL String parser and playing controls
Using the Library

Defining the object

The object definition requires no additional parameters.

setup()

The setup() function must invoke the begin() method. All other library initialization takes place at this time.

Sound output

To keep the parser library generic, sound output must be implemented in the application as the type of hardware used will dictate how the sound is produced.

The parser will translate the information from the RTTTL string into parameters that the application can use:

  • octave - generally in the valid range as is represented in the RTTTL string but no checking is done in the parser to enforce this.
  • note identifier - the notes are numbered according to the ISO standard numbering (C=0, C#=1, ..., A#=11) and can be used directly with the MD_MusicTable library to obtain note frequency or midi note numbers. The library will also translate the non-standard flat notes into the correct equivalent. Pause values are passed back as note -1 and need to be explicitly checked.
  • duration - the playing tempo and type of note, including dot notation, is converted into the number of milliseconds for the note or pause.

Application managed playback

The RTTLParser_Manual example demonstrates this use of the library.

In this mode the application has complete control over how the RTTTL file is processed.

A simplified flow for the application is:

  • setTune() is used initialize the library for the specified RTTTL string.
  • nextNote() is used to retrieve the next note in the sequence. In the case of a playable note, the application invokes the sound generation hardware. The application implements the logic required for the note or pause timing before processing the next note.
  • nextNote() returns true when the end of the RTTTL string is reached. Alternatively, the isEoln() method can be used to test for end of line being reached.

Library managed playback

The RTTLParser_Cback example demonstrates this use of the library.

In this mode the application provides the library with a callback that will manage the sound generation hardware. The library will manage duration timing for pauses (ie, the application is not aware of these) and will provide the callback with note on and note off events for the application to process.

The simplified flow for the application is:

  • setCallback() is used to register the callback function (can be done in setup()).
  • setTune() is used initialize the library for the specified RTTTL string.
  • run() is invoked every time through main program loop. This will run a Finite State Machine that manages the sequencing and timing of notes, and invokes the callback when required.
  • run() returns true when the end of the RTTTL string has been reached.

Parsing without playback

Parsing without playback is identical to an application managed playback without 'playing' the notes. The entire string can be scanned very fast when the note durations and pauses are ignored. Once the string has been parsed, it will need to be reset using setTune().

Parsing an RTTTL string is useful to gather information about the string, such as what octaves are being used, the range of notes, etc. These can then be used to modify subsequent playback (eg, shifting the octave range) to suit a particular sound output device.