release

lib/Melody Player/README.md

@@ -0,0 +1,104 @@
+# Melody Player
+
+[![arduino-library-badge](https://www.ardu-badge.com/badge/Melody%20Player.svg)](https://www.ardu-badge.com/Melody%20Player) ![Compile Library Examples](https://github.com/fabianoriccardi/melody-player/actions/workflows/LibraryBuild.yml/badge.svg)
+
+Melody Player is an Arduino library to play melodies on buzzers on ESP8266 and ESP32 in a non-blocking manner. Melodies can be written directly in code or loaded from file. It supports Ring Tone Text Transfer Language (RTTTL) format and a custom format developed specifically to enjoy all the benefits of this library.
+
+## Motivation
+
+Arduino cores provide tone() function to emit a PWM signal, and it is often used to play beeps on a buzzer. Modulating the PWM frequency, you can play sounds at a given frequency, i.e., you can play a note, and it is relatively easy to play a monophonic melody. However, the Arduino ecosystem lacks of a structured and easy way to accomplish this task (i.e., each developer have to write bloating code for it). So, I started to write a simple snippet to asynchronously play sequences of notes on a buzzer without bloating user-code with long parsing and playback methods. Moreover, since ESP8266 and ESP32 cores provide a file system for the embedded flash melody, I wanted a melody format easy to remember, human-readable and editable with a simple text editor. From this context Melody Player was born, improved, and extended over time.
+
+## Features
+
+* Non-blocking playback
+* Support RTTTL format (allow reuse of ringtones popular on old mobile phones)
+* Support custom format to allow finer control of frequencies
+* For ESP8266 and ESP32
+* Load melodies from file (support both LittleFS and SPIFFS file systems)
+* Control the melody playback through trivial *play*, *pause*, *stop* methods
+* Support multiple playing buzzers
+* *Migration* and *duplication* of melodies among buzzers
+
+## Installation
+
+You can find Melody Player on Arduino and PlatformIO library registries. You can install it through  Arduino IDE, or you can use the respective command-line tools running:
+
+    arduino-cli lib install "Melody Player"
+
+or:
+
+    pio lib install "fabianoriccardi/Melody Player"
+
+## Usage
+
+Here a quick overview of the main methods to use this library. Initialize MelodyPlayer by specifying the pin where the buzzer is attached to:
+
+    MelodyPlayer player(4);
+
+Load the RTTTL melody from file (remember to initialize the file system before this call):
+
+    Melody melody = MelodyFactory.loadRtttlFile("/the-anthem.rtttl");
+
+Check if the melody is loaded correctly:
+
+    if(!melody) {
+        Serial.println("Cannot play this melody");
+    }
+
+Play it using blocking or non-blocking methods:
+
+    player.play(melody);
+
+or
+
+    player.playAsync(melody);
+
+In case of non-blocking playback, you can check if the melody is running:
+
+    if(player.isPlaying()){
+        Serial.println("Playing...");
+    }
+
+and pause/continue to play/stop the melody through:
+
+    player.pause();
+    player.play();
+    player.stop();
+
+## Details about the custom format
+
+You can write a melody in a text file, accordingly to the following specifications:
+
+    title={Name of the melody}
+    timeUnit={Base time in millisecond}
+    length={Array length}
+    format={This value can be "integer" or "string", and it specifies how the tone frequency is represented in the following array}
+    {Array composed by pair <frequency; duration> and spit by '|' (pipe character)}
+
+where:
+
+* *frequency* can be either an integer number or a string, depending on what specified in "format" parameter. If format type is "string", it represents a note in English convention e.g. E5, F1
+* *duration* is an integer expressed in "timeUnits"
+
+A small pause is automatically added between 2 consecutive pairs. You can add comments using '#' at the begin of the line.
+
+Example 1: this melody codifies 2 "beeps" using the "string" codification:
+
+    title=Beep
+    timeUnit=200
+    length=1
+    format=string
+    G7,3|SILENCE,1|G7,3
+
+Example 2: the same melody using the "integer" codification:
+
+    title=Beep
+    timeUnit=200
+    length=1
+    format=integer
+    3136,3|0,1|3136,3
+
+## Useful links
+
+* <https://panuworld.net/nuukiaworld/download/nokix/rtttl.htm>: RTTTL specification
+* <https://adamonsoon.github.io/rtttl-play/>: Test and listen RTTTL melodies