FastArduino v1.10
C++ library to build fast but small Arduino/AVR projects
Loading...
Searching...
No Matches
devices::audio::AbstractTonePlayer< NTIMER, OUTPUT, TONEPLAY > Class Template Reference

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
NTIMERthe AVR timer to use for the underlying Timer
OUTPUTthe board::PWMPin connected to the buzzer; this must be the pin OCnA, where n is the AVR Timer number
TONEPLAYthe 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_generatorthe 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
0if 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
0if 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: