RingTone

This library provides support for parsing and playing tunes in RTTTL format.

RTTTL conversion code based on https://github.com/end2endzone/NonBlockingRTTTL.

The parser is stream-based and allows random seeking where the stream supports it.

An RTTTL writer is also included to assist with editing/creation of RTTTL files.

API Documentation

namespace RingTone

Enums

enum Note

Note numbers, defined here for convenience.

Values:

enumerator MUTE
enumerator C
enumerator C_Sharp
enumerator D_Flat
enumerator D
enumerator D_Sharp
enumerator E_Flat
enumerator E
enumerator F
enumerator F_Sharp
enumerator G
enumerator G_Sharp
enumerator A_Flat
enumerator A
enumerator A_Sharp
enumerator B_Flat
enumerator B

Functions

template<unsigned octave, unsigned note>
static constexpr unsigned calculateFrequency()
unsigned charToNoteValue(char c)

Get the corresponding note number for a letter.

Note

To sharpen a note, add 1

Parameters

c

Returns

unsigned – Notes start at 1, 0 indicates error or pause/mute

unsigned getNoteFrequency(unsigned octave, unsigned note)

Convert a scale/note combination into frequency.

Parameters
  • octave

  • note

Returns

unsigned – Frequency, 0 if out of range

unsigned getClosestNote(unsigned frequency, unsigned &octave)

Convert a frequency into a scale/note combination into frequency.

Parameters
  • frequency

  • octave – Octave for the note

Returns

unsigned – The note number, 0 if out of range

const char *getNoteName(unsigned noteValue)

Get text for a given note number.

Variables

static unsigned noteFrequencyA4 = 440

Reference note frequency.

static constexpr float frequencyRoot = pow(2, 1.0 / 12)
struct NoteDef
#include <RingTone.h>
class Parser
#include <RingTone.h>

Base parser class.

Subclassed by RingTone::RtttlParser

Public Functions

virtual bool readNextNote(NoteDef &note) = 0

Fetch the next note for this tune.

Returns

bool – true on success, false if no more notes available

class Player
#include <RingTonePlayer.h>

Base class to support playback of tunes.

Note

This class doesn’t produce any sound. To do this provide set the onPrepareNote and onPlayNote callbacks, or override the prepareNote and playNote methods in an inherited class.

Public Functions

void begin(RingTone::Parser *parser)

Initialise player.

Note

We don’t own the parser, just take a reference

Parameters

parser – The source of ringtone data

void end()

Stop the player and un-reference parser.

bool start(unsigned delayMs = 0)

Start or continue playing the tune.

void stop()

Stop/pause playing the tune.

inline void resetPlayTime()

Stop playback and reset play time.

inline bool isStarted()

Determine if a tune is being played.

inline unsigned getSpeed() const

Get playback speed factor.

Returns

unsigned – 100 = normal speed, 50 = half speed, 200 = double speed, etc.

inline unsigned setSpeed(unsigned speed)

Set playback speed factor.

Returns

unsigned – New speed factor

inline unsigned adjustSpeed(int adjust)

Make a relative adjustment to playback speed.

Returns

unsigned – New speed factor

struct RtttlHeader
#include <RtttlParser.h>
class RtttlParser : public RingTone::Parser, private RingTone::RtttlParserState
#include <RtttlParser.h>

Class to parse RTTTL files RTTTL (RingTone Text Transfer Language) format.

See

See https://en.wikipedia.org/wiki/Ring_Tone_Transfer_Language

Public Functions

bool begin(IDataSourceStream *source)

Initialise the parser with the given stream.

void end()

Release the source stream.

bool nextTune()

Locate next tune and read header.

bool seekTune(unsigned index)

Find a tune by index, starting at #0.

inline unsigned getIndex()

Get the current tune index.

unsigned getCount()

Get the number of tunes in this file.

inline const String &getTitle()

Get the current tune title.

inline String getCaption()

Get a display caption for the current tune.

inline bool rewind()

Rewind to start of tune.

virtual bool readNextNote(RingTone::NoteDef &note)

Fetch the next note for this tune.

Parameters

note

Returns

bool – true on success, false if no more notes available

struct RtttlParserState
#include <RtttlParser.h>

Subclassed by RingTone::RtttlParser

class RtttlWriter
#include <RtttlWriter.h>
class RtttlJsonListStream : public IDataSourceStream

A forward-only stream for listing contents of a tune file.

Note

Tune files can be large so we only output one tune title at a time

Public Functions

inline RtttlJsonListStream(const String &name, RingTone::RtttlParser *parser)

Construct a list stream.

Parameters
  • name – Identifies this stream, will have .json appended

  • parser – Pre-initialised parser to obtain tunes from

inline virtual bool isValid() const override

Determine if the stream object contains valid data.

Note

Where inherited classes are initialised by constructor this method indicates whether that was successful or not (e.g. FileStream)

Returns

bool – true if valid, false if invalid

virtual uint16_t readMemoryBlock(char *data, int bufSize) override

Read a block of memory.

Todo:

Should IDataSourceStream::readMemoryBlock return same data type as its bufSize param?

Parameters
  • data – Pointer to the data to be read

  • bufSize – Quantity of chars to read

Returns

uint16_t – Quantity of chars read

virtual bool seek(int len) override

Move read cursor.

Parameters

len – Relative cursor adjustment

Returns

bool – True on success.

inline virtual bool isFinished() override

Check if all data has been read.

Returns

bool – True on success.

virtual String getName() const override

Returns name of the resource.

Note

Commonly used to obtain name of file

Returns

String

References

Used by

SoC support

  • esp32

  • esp32c3

  • esp32s2

  • esp32s3

  • esp8266

  • host

  • rp2040