RTTTL (Ring Tone Text Transfer Language) parser and player stream. More...

#include <RTTTLOutput.h>

Inheritance diagram for RTTTLOutput< T >:

Public Member Functions
	RTTTLOutput ()=default

	RTTTLOutput (SoundGenerator< T > &generator)

	RTTTLOutput (SoundGenerator< T > &generator, AudioOutput &out)

	RTTTLOutput (SoundGenerator< T > &generator, AudioStream &out)

	RTTTLOutput (SoundGenerator< T > &generator, Print &out)

virtual void	addNotifyAudioChange (AudioInfoSupport &bi)
	Adds target to be notified about audio changes.

virtual AudioInfo	audioInfo () override
	provides the actual input AudioInfo

virtual AudioInfo	audioInfoOut ()

virtual int	availableForWrite () override

virtual bool	begin ()

bool	begin () override
	Start the RTTTL stream: we start with parsing the title and defaults.

virtual bool	begin (AudioInfo info)

virtual void	clearNotifyAudioChange ()
	Deletes all change notify subscriptions.

virtual void	end ()

virtual void	flush ()

int	getDefaultBpm () const

int	getDefaultDuration () const

int	getDefaultOctave () const

const char *	getTitle ()

virtual bool	isDeletable ()
	If true we need to release the related memory in the destructor.

bool	isNotifyActive ()
	Checks if the automatic AudioInfo update is active.

virtual	operator bool ()

virtual bool	removeNotifyAudioChange (AudioInfoSupport &bi)
	Removes a target in order not to be notified about audio changes.

virtual void	setAudioInfo (AudioInfo newInfo) override
	Defines the input AudioInfo.

void	setGenerator (SoundGenerator< T > &generator)

void	setNoteCallback (std::function< void(float freqHz, int durationMs, int midiNote, void *ref)> cb)

void	setNotifyActive (bool flag)
	Deactivate/Reactivate automatic AudioInfo updates: (default is active)

void	setOutput (AudioOutput &out)

void	setOutput (AudioStream &out)

void	setOutput (Print &out)
	Defines/Changes the output target (Print)

void	setRamp (uint8_t upPercent=20, uint8_t downPercent=30)
	Defines the ramp up and down percentages for note playback (default: 20% up, 30% down)

void	setReference (void *ref)
	Provide reference for callback.

void	setTransposeOctaves (int8_t octaves)

size_t	write (const uint8_t *data, size_t len) override
	Writes RTTTL data to the parser and plays the notes.

virtual size_t	write (uint8_t ch) override

virtual void	writeSilence (size_t len)

Protected Member Functions
int	find_byte (const uint8_t *haystack, size_t haystack_len, uint8_t needle)

char	next_char (bool convertToLower=true)

void	notifyAudioChange (AudioInfo info)

void	parse_defaults ()

void	parse_notes ()

int	parse_num ()

void	parse_title ()

void	play_note (float freq, int msec, int midi=-1)

float	transpose (float frequency, int8_t octaves)

Protected Attributes
int	_timeout = 10

AudioInfo	cfg

bool	is_active = false

bool	is_notify_active = true

bool	is_start = true

char	m_actual = 0

int	m_bpm = 120

int	m_duration = 4

float	m_msec_semi = 750

MusicalNotes	m_notes

int	m_octave = 4

char	m_prec = 0

uint8_t	m_ramp_downPercent = 30

uint8_t	m_ramp_upPercent = 20

Str	m_title {40}

int8_t	m_tranpose_octaves = 0

std::function< void(float, int, int, void *)>	noteCallback

Vector< AudioInfoSupport * >	notify_vector

SoundGenerator< T > *	p_generator = nullptr

Print *	p_print = nullptr

void *	reference = nullptr

RingBuffer< uint8_t >	ring_buffer {0}

SingleBuffer< uint8_t >	tmp {MAX_SINGLE_CHARS}

int	tmpPos = 0

Detailed Description

template<class T = int16_t>
class audio_tools::RTTTLOutput< T >

RTTTL (Ring Tone Text Transfer Language) parser and player stream.

RTTTLOutput<T> parses RTTTL text provided via its write() method and generates audio by driving a provided SoundGenerator<T>. It writes the generated PCM bytes to a Print-compatible output (typically an AudioStream or AudioOutput that implements Print).

Template parameter T

T: sample type used by the SoundGenerator (e.g. int16_t).

Usage:

Construct with a SoundGenerator<T>&. Optionally call a setOutput(...) overload to attach an AudioStream, AudioOutput or raw Print target.
Call begin() to reset internal parse state (typically called by the surrounding audio pipeline when starting a stream).
Write an RTTTL string by calling write(const uint8_t* data, size_t len). RTTTLOutput will buffer the incoming bytes and parse the title, defaults and notes. Notes are rendered immediately via play_note().

RTTTL semantics implemented:

Default values parsed from the RTTTL header: duration (d=), octave (o=) and tempo in BPM (b=). Default BPM is 120 if not provided.
Tempo (bpm) is converted to milliseconds-per-whole-note using ms_per_whole = 240000.0 / bpm (i.e. 60s * 4 * 1000 ms / bpm). The duration field in RTTTL (1,2,4,8,16,...) divides the whole-note length.
Dotted durations are supported (multiplied by 1.5). Rests ('p' or 'r') are supported and produce silence by setting frequency to 0.0.

Important implementation notes / expectations:

The attached SoundGenerator<T> must implement at least:
- setFrequency(float hz)
- readBytes(void* buffer, size_t byteCount) These are used by play_note() to generate PCM frames.
The output target must be a Print (or derived) pointer; attaching an AudioStream or AudioOutput via setOutput will register for audio format notifications and forward generated bytes to that target.
If b=0 is parsed, the implementation falls back to a fixed m_msec_semi = 750.0 (legacy/fallback behavior). Consider validating or rejecting b=0 RTTTL if that is undesired.

Edge cases & behavior:

Partial RTTTL inputs: write() appends to an internal ring buffer and parsing continues as bytes arrive. The parser expects the standard RTTTL format: "name:defaults:notes" and will parse title and defaults on first write() after begin().
Unknown note letters are skipped.
Accidentals (#) that bump past B roll the octave up by one.

Example RTTTL string: "Entertainer:d=4,o=5,b=120:8d6,8d6,8d6"

Public API (selected):

RTTTLOutput(SoundGenerator<T>& p_generator)
void setOutput(Print& out)
void setOutput(AudioStream& out)
void setOutput(AudioOutput& out)
bool begin()
size_t write(const uint8_t* data, size_t len) override
void setNoteCallback(std::function<void(float,int,int)>)

Note callback details:

Use setNoteCallback(cb) to register a callback that will be invoked for every parsed note or rest. The callback signature is void(float frequencyHz, int durationMs, int midiNote).
frequencyHz: frequency in Hz (0.0 for rests)
durationMs: duration in milliseconds computed from bpm and duration
midiNote: MIDI note number (0-127) for notes, or -1 for rests/unknown
The callback is invoked from play_note() before audio generation begins. If you require the callback after playback, you should wrap setNoteCallback and buffer events or change ordering.
MIDI mapping: if the library's MusicalNotes helper doesn't expose a toMidi(...) helper, the midiNote may be computed using the standard formula: midi = 12*(octave + 1) + semitoneIndex where semitoneIndex is the note's index within the 12 semitones (C=0, C#=1, ..., B=11).

Known limitations:

No explicit error reporting for malformed RTTTL. Parser silently skips invalid tokens.
The fallback for bpm==0 may be surprising; consider using the default bpm instead.

Author: Phil Schatzmann

Copyright: GPLv3

Constructor & Destructor Documentation

◆ RTTTLOutput() [1/5]

template<class T = int16_t>

RTTTLOutput ( )

default

◆ RTTTLOutput() [2/5]

template<class T = int16_t>

RTTTLOutput ( SoundGenerator< T > & generator )

inline

◆ RTTTLOutput() [3/5]

template<class T = int16_t>

RTTTLOutput	(	SoundGenerator< T > &	generator,
		AudioStream &	out
	)

inline

◆ RTTTLOutput() [4/5]

template<class T = int16_t>

RTTTLOutput	(	SoundGenerator< T > &	generator,
		AudioOutput &	out
	)

inline

◆ RTTTLOutput() [5/5]

template<class T = int16_t>

RTTTLOutput	(	SoundGenerator< T > &	generator,
		Print &	out
	)

inline

Member Function Documentation

◆ addNotifyAudioChange()

virtual void addNotifyAudioChange ( AudioInfoSupport & bi )

inlinevirtualinherited

Adds target to be notified about audio changes.

Reimplemented in CodecNOP, EncodedAudioOutput, EncodedAudioStream, AACDecoderFDK, DecoderBasic, CodecChain, MP3DecoderHelix, MP3DecoderMAD, OggContainerDecoder, RTSPClient< TcpClient, UdpSocket >, Pipeline, and Pipeline::ModifyingStreamAdapter.

◆ audioInfo()

virtual AudioInfo audioInfo ( )

inlineoverridevirtualinherited

provides the actual input AudioInfo

Implements AudioInfoSupport.

Reimplemented in AdapterPrintToAudioOutput, EncodedAudioOutput, and AdapterAudioStreamToAudioOutput.

◆ audioInfoOut()

virtual AudioInfo audioInfoOut ( )

inlinevirtualinherited

provides the actual output AudioInfo: this is usually the same as audioInfo() unless we use a transforming stream

Reimplemented in PureDataStream, PWMAudioOutput, ChannelFormatConverterStreamT< T >, ChannelFormatConverterStream, NumberFormatConverterStreamT< TFrom, TTo >, NumberFormatConverterStream, FormatConverterStream, Pipeline, ResampleStream, and ResampleStreamT< TInterpolator >.

◆ availableForWrite()

virtual int availableForWrite ( )

inlineoverridevirtualinherited

Reimplemented from Print.

Reimplemented in AudioESP32ULP, RTSPOutput< Platform >, EncodedAudioOutput, AudioServerEx, AudioSyncWriter, AdapterAudioStreamToAudioOutput, CsvOutput< T >, MemoryOutput, and PWMAudioOutput.

◆ begin() [1/3]

template<class T = int16_t>

virtual bool begin ( )

inlinevirtual

Reimplemented from AudioOutput.

◆ begin() [2/3]

template<class T = int16_t>

bool begin ( )

inlineoverridevirtual

Start the RTTTL stream: we start with parsing the title and defaults.

Returns: True if initialization was successful.

Reimplemented from AudioOutput.

◆ begin() [3/3]

template<class T = int16_t>

virtual bool begin ( AudioInfo info )

inlinevirtual

Reimplemented from AudioOutput.

◆ clearNotifyAudioChange()

virtual void clearNotifyAudioChange ( )

inlinevirtualinherited

Deletes all change notify subscriptions.

Reimplemented in RTSPClient< TcpClient, UdpSocket >.

◆ end()

virtual void end ( )

inlinevirtualinherited

Reimplemented in AudioESP32ULP, AudioServerEx, AudioSyncWriter, RTSPOutput< Platform >, PitchShiftOutput< T, BufferT >, MetaDataOutput, EncodedAudioOutput, OggContainerOutput, AdapterAudioStreamToAudioOutput, MetaDataFilter, and PWMAudioOutput.

◆ find_byte()

template<class T = int16_t>

int find_byte	(	const uint8_t *	haystack,
		size_t	haystack_len,
		uint8_t	needle
	)

inlineprotected

◆ flush()

virtual void flush ( )

inlinevirtualinherited

Reimplemented from Print.

Reimplemented in MultiOutput, and HexDumpOutput.

◆ getDefaultBpm()

template<class T = int16_t>

int getDefaultBpm ( ) const

inline

Returns the default bpm parsed from the RTTTL string

◆ getDefaultDuration()

template<class T = int16_t>

int getDefaultDuration ( ) const

inline

Returns the default duration parsed from the RTTTL string

◆ getDefaultOctave()

template<class T = int16_t>

int getDefaultOctave ( ) const

inline

Returns the default octave parsed from the RTTTL string

◆ getTitle()

template<class T = int16_t>

const char * getTitle ( )

inline

Returns the parsed title of the RTTTL ringtone

◆ isDeletable()

virtual bool isDeletable ( )

inlinevirtualinherited

If true we need to release the related memory in the destructor.

Reimplemented in AdapterPrintToAudioOutput, and AdapterAudioStreamToAudioOutput.

◆ isNotifyActive()

bool isNotifyActive ( )

inlineinherited

Checks if the automatic AudioInfo update is active.

◆ next_char()

template<class T = int16_t>

char next_char ( bool convertToLower = true )

inlineprotected

◆ notifyAudioChange()

void notifyAudioChange ( AudioInfo info )

inlineprotectedinherited

◆ operator bool()

virtual operator bool ( )

inlinevirtualinherited

Reimplemented in RTSPOutput< Platform >, EncodedAudioOutput, and AdapterAudioStreamToAudioOutput.

◆ parse_defaults()

template<class T = int16_t>

void parse_defaults ( )

inlineprotected

◆ parse_notes()

template<class T = int16_t>

void parse_notes ( )

inlineprotected

◆ parse_num()

template<class T = int16_t>

int parse_num ( )

inlineprotected

◆ parse_title()

template<class T = int16_t>

void parse_title ( )

inlineprotected

◆ play_note()

template<class T = int16_t>

void play_note	(	float	freq,
		int	msec,
		int	midi = `-1`
	)

inlineprotected

◆ removeNotifyAudioChange()

virtual bool removeNotifyAudioChange ( AudioInfoSupport & bi )

inlinevirtualinherited

Removes a target in order not to be notified about audio changes.

Reimplemented in RTSPClient< TcpClient, UdpSocket >.

◆ setAudioInfo()

virtual void setAudioInfo ( AudioInfo info )

inlineoverridevirtualinherited

Defines the input AudioInfo.

Implements AudioInfoSupport.

Reimplemented in ChannelsSelectOutput, AdapterPrintToAudioOutput, MultiOutput, AdapterAudioStreamToAudioOutput, CsvOutput< T >, PWMAudioOutput, and EncodedAudioOutput.

◆ setGenerator()

template<class T = int16_t>

void setGenerator ( SoundGenerator< T > & generator )

inline

Defines the Generator that is used to generate the sound

◆ setNoteCallback()

template<class T = int16_t>

void setNoteCallback ( std::function< void(float freqHz, int durationMs, int midiNote, void *ref)> cb )

inline

Set an optional callback to be invoked for each parsed note/rest. Callback signature: void(float frequencyHz, int durationMs, int midiNote)

frequencyHz: 0.0 for rests
durationMs: computed duration in milliseconds
midiNote: MIDI note number (0-127)

◆ setNotifyActive()

void setNotifyActive ( bool flag )

inlineinherited

Deactivate/Reactivate automatic AudioInfo updates: (default is active)

◆ setOutput() [1/3]

template<class T = int16_t>

void setOutput ( AudioOutput & out )

inline

Defines/Changes the output target (AudioOutput) and register for audio info

◆ setOutput() [2/3]

template<class T = int16_t>

void setOutput ( AudioStream & out )

inline

Defines/Changes the output target (AudioStream) and register for audio info

◆ setOutput() [3/3]

template<class T = int16_t>

void setOutput ( Print & out )

inline

Defines/Changes the output target (Print)

◆ setRamp()

template<class T = int16_t>

void setRamp	(	uint8_t	upPercent = `20`,
		uint8_t	downPercent = `30`
	)

inline

Defines the ramp up and down percentages for note playback (default: 20% up, 30% down)

◆ setReference()

template<class T = int16_t>

void setReference ( void * ref )

inline

Provide reference for callback.

◆ setTransposeOctaves()

template<class T = int16_t>

void setTransposeOctaves ( int8_t octaves )

inline

transpose all notes by the specified number of octaves e.g. -2 = 2 octaves down

◆ transpose()

template<class T = int16_t>

float transpose	(	float	frequency,
		int8_t	octaves
	)

inlineprotected

◆ write() [1/2]

template<class T = int16_t>

size_t write	(	const uint8_t *	data,
		size_t	len
	)

inlineoverridevirtual

Writes RTTTL data to the parser and plays the notes.

Implements AudioOutput.

◆ write() [2/2]

virtual size_t write ( uint8_t ch )

inlineoverridevirtualinherited

Reimplemented in MetaDataOutput, and MultiOutput.

◆ writeSilence()

virtual void writeSilence ( size_t len )

inlinevirtualinherited

Writes n 0 values (= silence)

Parameters

len

Member Data Documentation

◆ _timeout

int _timeout = 10

protectedinherited

◆ cfg

AudioInfo cfg

protectedinherited

◆ is_active

bool is_active = false

protectedinherited

◆ is_notify_active

bool is_notify_active = true

protectedinherited

◆ is_start

template<class T = int16_t>

bool is_start = true

protected

◆ m_actual

template<class T = int16_t>

char m_actual = 0

protected

◆ m_bpm

template<class T = int16_t>

int m_bpm = 120

protected

◆ m_duration

template<class T = int16_t>

int m_duration = 4

protected

◆ m_msec_semi

template<class T = int16_t>

float m_msec_semi = 750

protected

◆ m_notes

template<class T = int16_t>

MusicalNotes m_notes

protected

◆ m_octave

template<class T = int16_t>

int m_octave = 4

protected

◆ m_prec

template<class T = int16_t>

char m_prec = 0

protected

◆ m_ramp_downPercent

template<class T = int16_t>

uint8_t m_ramp_downPercent = 30

protected

◆ m_ramp_upPercent

template<class T = int16_t>

uint8_t m_ramp_upPercent = 20

protected

◆ m_title

template<class T = int16_t>

Str m_title {40}

protected

◆ m_tranpose_octaves

template<class T = int16_t>

int8_t m_tranpose_octaves = 0

protected

◆ noteCallback

template<class T = int16_t>

std::function<void(float, int, int, void*)> noteCallback

protected

◆ notify_vector

Vector<AudioInfoSupport*> notify_vector

protectedinherited

◆ p_generator

template<class T = int16_t>

SoundGenerator<T>* p_generator = nullptr

protected

◆ p_print

template<class T = int16_t>

Print* p_print = nullptr

protected

◆ reference

template<class T = int16_t>

void* reference = nullptr

protected

◆ ring_buffer

template<class T = int16_t>

RingBuffer<uint8_t> ring_buffer {0}

protected

◆ tmp

SingleBuffer<uint8_t> tmp {MAX_SINGLE_CHARS}

protectedinherited

◆ tmpPos

int tmpPos = 0

protectedinherited

The documentation for this class was generated from the following file:

src/AudioTools/CoreAudio/RTTTLOutput.h

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ RTTTLOutput() [1/5]

◆ RTTTLOutput() [2/5]

◆ RTTTLOutput() [3/5]

◆ RTTTLOutput() [4/5]

◆ RTTTLOutput() [5/5]

Member Function Documentation

◆ addNotifyAudioChange()

◆ audioInfo()

◆ audioInfoOut()

◆ availableForWrite()

◆ begin() [1/3]

◆ begin() [2/3]

◆ begin() [3/3]

◆ clearNotifyAudioChange()

◆ end()

◆ find_byte()

◆ flush()

◆ getDefaultBpm()

◆ getDefaultDuration()

◆ getDefaultOctave()

◆ getTitle()

◆ isDeletable()

◆ isNotifyActive()

◆ next_char()

◆ notifyAudioChange()

◆ operator bool()

◆ parse_defaults()

◆ parse_notes()

◆ parse_num()

◆ parse_title()

◆ play_note()

◆ removeNotifyAudioChange()

◆ setAudioInfo()

◆ setGenerator()

◆ setNoteCallback()

◆ setNotifyActive()

◆ setOutput() [1/3]

◆ setOutput() [2/3]

◆ setOutput() [3/3]

◆ setRamp()

◆ setReference()

◆ setTransposeOctaves()

◆ transpose()

◆ write() [1/2]

◆ write() [2/2]

◆ writeSilence()

Member Data Documentation

◆ _timeout

◆ cfg

◆ is_active

◆ is_notify_active

◆ is_start

◆ m_actual

◆ m_bpm

◆ m_duration

◆ m_msec_semi

◆ m_notes

◆ m_octave

◆ m_prec

◆ m_ramp_downPercent

◆ m_ramp_upPercent

◆ m_title

◆ m_tranpose_octaves

◆ noteCallback

◆ notify_vector

◆ p_generator

◆ p_print

◆ reference

◆ ring_buffer

◆ tmp

◆ tmpPos