tone_player.h

Go to the documentation of this file.

//   Copyright 2016-2023 Jean-Francois Poilpret
//
//   Licensed under the Apache License, Version 2.0 (the "License");
//   you may not use this file except in compliance with the License.
//   You may obtain a copy of the License at
//
//       http://www.apache.org/licenses/LICENSE-2.0
//
//   Unless required by applicable law or agreed to in writing, software
//   distributed under the License is distributed on an "AS IS" BASIS,
//   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//   See the License for the specific language governing permissions and
//   limitations under the License.
 
 
#ifndef TONE_PLAYER_HH
#define TONE_PLAYER_HH
 
#include "../eeprom.h"
#include "../flash.h"
#include "tones.h"
 
namespace devices::audio
{
    // Forward declaration
    template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY> class AbstractTonePlayer;
 
    namespace SpecialTone
    {
        static constexpr const Tone END = Tone::USER0;
 
        static constexpr const Tone REPEAT_START = Tone::USER1;
 
        static constexpr const Tone REPEAT_END = Tone::USER2;
 
        static constexpr const Tone TIE = Tone::USER3;
 
        static constexpr const Tone SLUR = TIE;
    }
 
    enum class Duration : uint8_t
    {
        // Common names for notes durations
        WHOLE = 32,
        HALF = 16,
        QUARTER = 8,
        EIGHTH = 4,
        SIXTEENTH = 2,
 
        // Synonyms for some notes durations
        SEMI_BREVE = WHOLE,
        MINIM = HALF,
        CROTCHET = QUARTER,
        QUAVER = EIGHTH,
        SEMI_QUAVER = SIXTEENTH,
    };
 
    static constexpr Duration dotted(Duration d)
    {
        return Duration(uint8_t(d) + uint8_t(d) / 2);
    }
 
    static constexpr Duration triplet(Duration d)
    {
        return Duration(uint8_t(d) * 2 / 3);
    }
 
    class TonePlay
    {
    public:
        TonePlay(const TonePlay&) = default;
        TonePlay& operator=(const TonePlay&) = default;
 
        TonePlay() = default;
 
        constexpr TonePlay(Tone tone, Duration duration) : tone_{tone}, duration_{duration} {}
 
        constexpr TonePlay(Tone tone, uint8_t value = 0) : tone_{tone}, repeats_{value} {}
 
    private:
        Duration duration() const
        {
            return duration_;
        }
        bool is_tone() const
        {
            return tone_ > Tone::SILENCE;
        }
        bool is_pause() const
        {
            return tone_ == Tone::SILENCE;
        }
        bool is_end() const
        {
            return tone_ == SpecialTone::END;
        }
        bool is_repeat_start() const
        {
            return tone_ == SpecialTone::REPEAT_START;
        }
        bool is_repeat_end() const
        {
            return tone_ == SpecialTone::REPEAT_END;
        }
        uint8_t repeat_count() const
        {
            return repeats_;
        }
        bool is_tie() const
        {
            return tone_ == SpecialTone::TIE;
        }
        uint8_t num_ties() const
        {
            return ties_;
        }
 
        template<board::Timer NTIMER, board::PWMPin OUTPUT>
        void generate_tone(ToneGenerator<NTIMER, OUTPUT>& generator) const
        {
            generator.start_tone(tone_);
        }
 
        Tone tone_;
        union
        {
            Duration duration_;
            uint8_t repeats_;
            uint8_t ties_;
        };
 
        template<board::Timer, board::PWMPin, typename> friend class AbstractTonePlayer;
    };
 
    template<board::Timer NTIMER, board::PWMPin OUTPUT> class QTonePlay
    {
    public:
        QTonePlay(const QTonePlay&) = default;
        QTonePlay& operator=(const QTonePlay&) = default;
 
        QTonePlay() = default;
 
        constexpr QTonePlay(Tone tone, Duration duration)
            : flags_{flags(tone)}, prescaler_{prescaler(tone)}, counter_{counter(tone)}, duration_{duration} {}
 
        constexpr QTonePlay(Tone tone, uint8_t value = 0)
            : flags_{flags(tone)}, prescaler_{prescaler(tone)}, counter_{counter(tone)}, repeats_{value} {}
 
    private:
        using CALC = timer::Calculator<NTIMER>;
        using TIMER = timer::Timer<NTIMER>;
        using PRESCALER = typename TIMER::PRESCALER;
        using COUNTER = typename TIMER::TYPE;
 
        Duration duration() const
        {
            return duration_;
        }
        bool is_tone() const
        {
            return flags_ == TONE;
        }
        bool is_pause() const
        {
            return flags_ == NONE;
        }
        bool is_end() const
        {
            return flags_ == END;
        }
        bool is_repeat_start() const
        {
            return flags_ == REPEAT_START;
        }
        bool is_repeat_end() const
        {
            return flags_ == REPEAT_END;
        }
        uint8_t repeat_count() const
        {
            return repeats_;
        }
        bool is_tie() const
        {
            return flags_ == TIE;
        }
        uint8_t num_ties() const
        {
            return ties_;
        }
 
        void generate_tone(ToneGenerator<NTIMER, OUTPUT>& generator) const
        {
            generator.start_tone(prescaler_, counter_);
        }
 
        // Flags meaning
        static constexpr uint8_t TONE = 0x00;
        static constexpr uint8_t NONE = 0x01;
        static constexpr uint8_t END = 0x02;
        static constexpr uint8_t REPEAT_START = 0x04;
        static constexpr uint8_t REPEAT_END = 0x08;
        static constexpr uint8_t TIE = 0x10;
 
        uint8_t flags_ = END;
        PRESCALER prescaler_;
        COUNTER counter_;
        union
        {
            Duration duration_;
            uint8_t repeats_;
            uint8_t ties_;
        };
 
        static constexpr uint32_t period(Tone tone)
        {
            return ONE_SECOND / 2 / uint16_t(tone);
        }
        static constexpr PRESCALER prescaler(Tone tone)
        {
            return (tone > Tone::SILENCE ? CALC::CTC_prescaler(period(tone)) : PRESCALER::NO_PRESCALING);
        }
        static constexpr COUNTER counter(Tone tone)
        {
            return (tone > Tone::SILENCE ? CALC::CTC_counter(prescaler(tone), period(tone)) : 0);
        }
        static constexpr uint8_t flags(Tone tone)
        {
            if (tone == Tone::SILENCE) return NONE;
            if (tone == SpecialTone::END) return END;
            if (tone == SpecialTone::REPEAT_START) return REPEAT_START;
            if (tone == SpecialTone::REPEAT_END) return REPEAT_END;
            if (tone == SpecialTone::TIE) return TIE;
            return TONE;
        }
 
        friend class AbstractTonePlayer<NTIMER, OUTPUT, QTonePlay<NTIMER, OUTPUT>>;
    };
 
    class Beat
    {
    public:
        explicit constexpr Beat(uint8_t bpm) : duration_{calculate_min_duration(bpm)} {}
 
        constexpr uint16_t duration() const
        {
            return duration_;
        }
 
    private:
        static constexpr uint16_t calculate_min_duration(uint8_t bpm)
        {
            // bpm defines the duration of a quarter note (in 4/4 mode)
            // We want the minimum duration allowed (for a 32nd note, since we allow dotted sixteenth)
            return (60U * 1000U / 8U) / bpm;
        }
 
        uint16_t duration_;
    };
 
    template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>
    class AbstractTonePlayer
    {
    protected:
        AbstractTonePlayer(const AbstractTonePlayer&) = delete;
        AbstractTonePlayer& operator=(const AbstractTonePlayer&) = delete;
 
        using TONE_PLAY = TONEPLAY;
        using GENERATOR = ToneGenerator<NTIMER, OUTPUT>;
 
        explicit AbstractTonePlayer(GENERATOR& tone_generator) : generator_{tone_generator} {}
 
        void set_min_duration(uint16_t min_duration)
        {
            t32_duration_ms_ = min_duration;
        }
 
        uint16_t get_min_duration() const
        {
            return t32_duration_ms_;
        }
 
        void prepare_sram(const TONE_PLAY* melody)
        {
            prepare_(melody, load_sram);
        }
 
        void prepare_eeprom(const TONE_PLAY* melody)
        {
            prepare_(melody, load_eeprom);
        }
 
        void prepare_flash(const TONE_PLAY* melody)
        {
            prepare_(melody, load_flash);
        }
 
        uint16_t start_next_note()
        {
            return start_next_();
        }
 
        uint16_t stop_current_note()
        {
            return stop_current_();
        }
 
        bool is_finished() const
        {
            return (loader_ == nullptr);
        }
 
    private:
        static constexpr const uint16_t INTERTONE_DELAY_MS = 20;
 
        using LOAD_TONE = const TONE_PLAY* (*) (const TONE_PLAY* address, TONE_PLAY& holder);
 
        void prepare_(const TONE_PLAY* melody, LOAD_TONE load_tone)
        {
            loader_ = load_tone;
            current_play_ = melody;
            repeat_play_ = nullptr;
            repeat_times_ = 0;
            tie_notes_ = 0;
        }
 
        void reset_()
        {
            loader_ = nullptr;
            current_play_ = nullptr;
            repeat_play_ = nullptr;
            repeat_times_ = 0;
            tie_notes_ = 0;
        }
 
        uint16_t start_next_()
        {
            if (loader_ == nullptr) return 0;
 
            TONE_PLAY holder;
            const TONE_PLAY* current = loader_(current_play_, holder);
            if (current->is_end())
            {
                reset_();
                return 0;
            }
            uint16_t delay = 0;
            no_delay_ = true;
            if (current->is_repeat_start())
            {
                repeat_play_ = current_play_;
                repeat_times_ = -1;
            }
            else if (current->is_repeat_end())
            {
                if (repeat_play_)
                {
                    if (repeat_times_ == -1) repeat_times_ = current->repeat_count();
                    if (repeat_times_--)
                        current_play_ = repeat_play_;
                    else
                        repeat_play_ = nullptr;
                }
            }
            else if (current->is_tie())
            {
                tie_notes_ = current->num_ties();
            }
            else
            {
                if (current->is_tone()) current->generate_tone(generator_);
                if (tie_notes_)
                    --tie_notes_;
                else
                    no_delay_ = false;
                delay = duration(current->duration());
            }
            ++current_play_;
            return delay;
        }
 
        uint16_t stop_current_()
        {
            if (no_delay_)
                return 0;
            generator_.stop_tone();
            return INTERTONE_DELAY_MS;
        }
 
        uint16_t duration(Duration d) const
        {
            return uint8_t(d) * t32_duration_ms_;
        }
 
        static const TONE_PLAY* load_sram(const TONE_PLAY* address, TONE_PLAY& holder UNUSED)
        {
            return address;
        }
        static const TONE_PLAY* load_eeprom(const TONE_PLAY* address, TONE_PLAY& holder)
        {
            eeprom::EEPROM::read(address, holder);
            return &holder;
        }
        static const TONE_PLAY* load_flash(const TONE_PLAY* address, TONE_PLAY& holder)
        {
            flash::read_flash(address, holder);
            return &holder;
        }
 
        GENERATOR& generator_;
        LOAD_TONE loader_ = nullptr;
        uint16_t t32_duration_ms_ = 0U;
        const TONE_PLAY* current_play_ = nullptr;
        const TONE_PLAY* repeat_play_ = nullptr;
        int8_t repeat_times_ = 0;
        uint8_t tie_notes_ = 0;
        bool no_delay_ = false;
    };
 
    template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>
    class TonePlayer : public AbstractTonePlayer<NTIMER, OUTPUT, TONEPLAY>
    {
        using BASE = AbstractTonePlayer<NTIMER, OUTPUT, TONEPLAY>;
 
    public:
        using GENERATOR = typename BASE::GENERATOR;
        using TONE_PLAY = typename BASE::TONE_PLAY;
 
        explicit TonePlayer(GENERATOR& tone_generator) : BASE{tone_generator} {}
 
        void play_sram(const TONE_PLAY* melody, const Beat& beat)
        {
            this->set_min_duration(beat.duration());
            this->prepare_sram(melody);
            play_();
        }
 
        void play_eeprom(const TONE_PLAY* melody, const Beat& beat)
        {
            this->set_min_duration(beat.duration());
            this->prepare_eeprom(melody);
            play_();
        }
 
        void play_flash(const TONE_PLAY* melody, const Beat& beat)
        {
            this->set_min_duration(beat.duration());
            this->prepare_flash(melody);
            play_();
        }
 
        void stop()
        {
            stop_ = true;
        }
 
        bool is_playing() const
        {
            return !stop_;
        }
 
    private:
        void play_()
        {
            stop_ = false;
            while (!stop_)
            {
                uint16_t delay = this->start_next_note();
                if (delay) time::delay_ms(delay);
                delay = this->stop_current_note();
                if (delay) time::delay_ms(delay);
                if (this->is_finished())
                    stop_ = true;
            }
        }
 
        volatile bool stop_ = true;
    };
 
    template<board::Timer NTIMER, board::PWMPin OUTPUT, typename TONEPLAY = QTonePlay<NTIMER, OUTPUT>>
    class AsyncTonePlayer : public AbstractTonePlayer<NTIMER, OUTPUT, TONEPLAY>
    {
        using BASE = AbstractTonePlayer<NTIMER, OUTPUT, TONEPLAY>;
        using THIS = AsyncTonePlayer<NTIMER, OUTPUT, TONEPLAY>;
 
    public:
        using GENERATOR = typename BASE::GENERATOR;
        using TONE_PLAY = typename BASE::TONE_PLAY;
 
        explicit AsyncTonePlayer(GENERATOR& tone_generator) : BASE{tone_generator} {}
 
        uint16_t get_min_duration() const
        {
            return BASE::get_min_duration();
        }
 
        void play_sram(const TONE_PLAY* melody, const Beat& beat)
        {
            status_ = Status::NOT_STARTED;
            this->set_min_duration(beat.duration());
            this->prepare_sram(melody);
            next_time_ = 0;
            status_ = Status::STARTED;
        }
 
        void play_eeprom(const TONE_PLAY* melody, const Beat& beat)
        {
            status_ = Status::NOT_STARTED;
            this->set_min_duration(beat.duration());
            this->prepare_eeprom(melody);
            next_time_ = 0;
            status_ = Status::STARTED;
        }
 
        void play_flash(const TONE_PLAY* melody, const Beat& beat)
        {
            status_ = Status::NOT_STARTED;
            this->set_min_duration(beat.duration());
            this->prepare_flash(melody);
            next_time_ = 0;
            status_ = Status::STARTED;
        }
 
        void stop()
        {
            status_ = Status::NOT_STARTED;
            this->stop_current_note();
        }
 
        bool is_playing() const
        {
            return status_ != Status::NOT_STARTED;
        }
 
        void update(uint32_t rtt_millis)
        {
            if ((status_ != Status::NOT_STARTED) && (rtt_millis >= next_time_))
            {
                uint16_t delay;
                Status next;
                if (status_ == Status::PLAYING_NOTE)
                {
                    delay = this->stop_current_note();
                    next = Status::PLAYING_INTERNOTE;
                }
                else
                {
                    delay = this->start_next_note();
                    next = Status::PLAYING_NOTE;
                }
                
                if (this->is_finished())
                    status_ = Status::NOT_STARTED;
                else
                {
                    next_time_ = rtt_millis + delay;
                    status_ = next;
                }
            }
        }
 
    private:
        enum class Status : uint8_t
        {
            NOT_STARTED = 0,
            STARTED,
            PLAYING_NOTE,
            PLAYING_INTERNOTE
        };
 
        Status status_ = Status::NOT_STARTED;
        uint32_t next_time_ = 0UL;
    };
}
 
#endif /* TONE_PLAYER_HH */