update readme

README.md

@@ -2,46 +2,102 @@
 
 [![arduino-library-badge](https://www.ardu-badge.com/badge/Melody%20Player.svg)](https://www.ardu-badge.com/badge/Melody%20Player.svg) ![Compile Library Examples](https://github.com/fabiuz7/melody-player-arduino/actions/workflows/LibraryBuild.yml/badge.svg)
 
-Melody Player library allows playing melodies on buzzers on ESP8266 and ESP32 in a non-blocking manner. Melodies can be written directly in code or stored in a file. It supports Ring Tone Text Transfer Language (RTTTL) format and an alternative format developed specifically for this library.
+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.
 
-### Features
+## Motivation
 
-- Support to ESP8266 and ESP32
-- Support multiple playing buzzers
-- Support RTTTL format (allow reuse of old ringtones)
-- Support custom format to allow finer control of frequencies
-- Load melody from file (SPIFFS)
-- Non-blocking play
-- Control the melody advancement through traditional *play*, *pause*, *stop* methods
-- Dynamic *migration*/*duplication* of melodies among buzzers
+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.
 
-### Details about the custom format
+## Features
 
-You can write your melody on a simple file (extension .mel), accordingly to the following format:
+* 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, as integer number or as string accordingly to note codification in English convention (E5, F1)} {duration, an integer representing number of "timeUnit"s}>}, semicolon-separated}
-2 consecutive pairs there is a '|' (pipe character), and there is always a small pause.
+    {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 "note" codification:
+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 codifying explicitly the frequency reproduced by the buzzer:
+Example 2: the same melody using the "integer" codification:
 
     title=Beep
     timeUnit=200
     length=1
     format=integer
     3136,3|0,1|3136,3
 
-### Remarks
+## Useful links
 
-This library, targeting Arduino users, was designed to be as intuitive as possible, without giving up advanced features. i.e., I preferred to use simple *object* instead of more advanced constructs like *smart pointers* and *references*. 
+* <https://adamonsoon.github.io/rtttl-play/>: Test and listen RTTTL melodies