This low-level API defines an abstract player of melodies (defined as a sequence of tones and durations). More...

#include <fastarduino/devices/tone_player.h>

Inheritance diagram for devices::audio::AbstractTonePlayer< NTIMER, OUTPUT, TONEPLAY >:

Protected Types
using	TONE_PLAY = TONEPLAY
	The type that holds unit of information of a melody. More...

using	GENERATOR = ToneGenerator< NTIMER, OUTPUT >
	The type of `ToneGenerator` to use as constructor's argument. More...

Protected Member Functions
	AbstractTonePlayer (GENERATOR &tone_generator)
	Create a new tone player, based on an existing `ToneGenerator`. More...

void	set_min_duration (uint16_t min_duration)
	Set the duration, in milliseconds, of a 32nd note. More...

uint16_t	get_min_duration () const
	Get the duration, in milliseconds, of a 32nd note. More...

void	prepare_sram (const TONE_PLAY *melody)
	Prepare playing of `melody`, which should be stored in SRAM. More...

void	prepare_eeprom (const TONE_PLAY *melody)
	Prepare playing of `melody`, which should be stored in EEPROM. More...

void	prepare_flash (const TONE_PLAY *melody)
	Prepare playing of `melody`, which should be stored in Flash. More...

uint16_t	start_next_note ()
	Ask this player to start playing the next note of the melody. More...

uint16_t	stop_current_note ()
	Ask this player to stop playing the current note of the melody. More...

bool	is_finished () const
	Indicate if the currently played melody is finished. More...

Detailed Description

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>
class devices::audio::AbstractTonePlayer< NTIMER, OUTPUT, TONEPLAY >

This low-level API defines an abstract player of melodies (defined as a sequence of tones and durations).

You should normally not need to use it directly in programs, but rather use specific implementations instead:

TonePlay: a simple player, playing melodies in a synchronous way (blocking until the whole melody is played until end)
AsyncTonePlay: a player that can play melodies asynchronously, when used with a Timer ISR.

Melodies are defined as sequence of unit information, which can be either:

TonePlays: easy to write in source code but not efficient in size of generated code
QTonePlays: requires more effort in source code, but reduces generated code size Which types is used is defined as the TONEPLAY template parameter.

With this API, played melodies can be stored on 3 possible locations:

in SRAM: this is useful when you get the melody from another support e.g. an external flash device
in Flash: this is the mostly used way as flash s the more abundant storage in AVR MCU
in EEPROM: this can be useful for short melodies, when you do not want to waste precious SRAM and Flash Each play API has 3 distinct methods, one for each storage strategy.

Template Parameters

NTIMER	the AVR timer to use for the underlying Timer
OUTPUT	the `board::PWMPin` connected to the buzzer; this must be the pin OCnA, where n is the AVR Timer number
TONEPLAY	the type used to store melody data, `QTonePlay` by default

See also: TonePlay; QTonePlay; TonePlayer; AsyncTonePlayer

Definition at line 464 of file tone_player.h.

Member Typedef Documentation

◆ TONE_PLAY

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

using devices::audio::AbstractTonePlayer< NTIMER, OUTPUT, TONEPLAY >::TONE_PLAY = TONEPLAY

protected

The type that holds unit of information of a melody.

Definition at line 473 of file tone_player.h.

◆ GENERATOR

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

using devices::audio::AbstractTonePlayer< NTIMER, OUTPUT, TONEPLAY >::GENERATOR = ToneGenerator<NTIMER, OUTPUT>

protected

The type of ToneGenerator to use as constructor's argument.

Definition at line 475 of file tone_player.h.

Constructor & Destructor Documentation

◆ AbstractTonePlayer()

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

devices::audio::AbstractTonePlayer< NTIMER, OUTPUT, TONEPLAY >::AbstractTonePlayer ( GENERATOR & tone_generator )

inlineexplicitprotected

Create a new tone player, based on an existing ToneGenerator.

Parameters

tone_generator the ToneGenerator used to actually produce tones.

Definition at line 482 of file tone_player.h.

Member Function Documentation

◆ set_min_duration()

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

void devices::audio::AbstractTonePlayer< NTIMER, OUTPUT, TONEPLAY >::set_min_duration ( uint16_t min_duration )

inlineprotected

Set the duration, in milliseconds, of a 32nd note.

This method must be called before any melody play.

See also: Beat; get_min_duration()

Definition at line 490 of file tone_player.h.

◆ get_min_duration()

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

uint16_t devices::audio::AbstractTonePlayer< NTIMER, OUTPUT, TONEPLAY >::get_min_duration ( ) const

inlineprotected

Get the duration, in milliseconds, of a 32nd note.

See also: set_min_duration()

Definition at line 499 of file tone_player.h.

◆ prepare_sram()

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

void devices::audio::AbstractTonePlayer< NTIMER, OUTPUT, TONEPLAY >::prepare_sram ( const TONE_PLAY * melody )

inlineprotected

Prepare playing of melody, which should be stored in SRAM.

Once preparation is done, actual melody playing is performed by sequenced calls to start_next_note() and stop_current_note().

Definition at line 509 of file tone_player.h.

◆ prepare_eeprom()

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

void devices::audio::AbstractTonePlayer< NTIMER, OUTPUT, TONEPLAY >::prepare_eeprom ( const TONE_PLAY * melody )

inlineprotected

Prepare playing of melody, which should be stored in EEPROM.

Once preparation is done, actual melody playing is performed by sequenced calls to start_next_note() and stop_current_note().

Definition at line 519 of file tone_player.h.

◆ prepare_flash()

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

void devices::audio::AbstractTonePlayer< NTIMER, OUTPUT, TONEPLAY >::prepare_flash ( const TONE_PLAY * melody )

inlineprotected

Prepare playing of melody, which should be stored in Flash.

Once preparation is done, actual melody playing is performed by sequenced calls to start_next_note() and stop_current_note().

Definition at line 529 of file tone_player.h.

◆ start_next_note()

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

uint16_t devices::audio::AbstractTonePlayer< NTIMER, OUTPUT, TONEPLAY >::start_next_note ( )

inlineprotected

Ask this player to start playing the next note of the melody.

Returns: the duration of the next note that just started playing; it is the responsibility of the caller to wait for that duration until calling stop_current_note().

Return values

0	if no wait is needed until next call to `stop_current_note()`; this may happen when the next melody note is not a true note but an instruction (e.g. repeat start/end), or when the melody is finished playing.

Definition at line 544 of file tone_player.h.

◆ stop_current_note()

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

uint16_t devices::audio::AbstractTonePlayer< NTIMER, OUTPUT, TONEPLAY >::stop_current_note ( )

inlineprotected

Ask this player to stop playing the current note of the melody.

Returns: the duration of inter note play (short silence between consecutive notes)

Return values

0	if there is no delay needed between the current note and the next one; this may also happen when the current note is not a true note but an instruction (e.g. repeat start/end), or when the melody is finished playing.

Definition at line 558 of file tone_player.h.

◆ is_finished()

template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>

bool devices::audio::AbstractTonePlayer< NTIMER, OUTPUT, TONEPLAY >::is_finished ( ) const

inlineprotected

Indicate if the currently played melody is finished.

Definition at line 566 of file tone_player.h.

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

fastarduino/devices/tone_player.h

Protected Types

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ TONE_PLAY

◆ GENERATOR

Constructor & Destructor Documentation

◆ AbstractTonePlayer()

Member Function Documentation

◆ set_min_duration()

◆ get_min_duration()

◆ prepare_sram()

◆ prepare_eeprom()

◆ prepare_flash()

◆ start_next_note()

◆ stop_current_note()

◆ is_finished()