improve examples (add info, fix typos, format with clang-format)

examples/1_simple_play/1_simple_play.ino

@@ -1,8 +1,8 @@
 /**
- * Play a simple melody directly hardcoded in the sketch.
- * 
- * You can observe the difference between the blocking play(..) method,
- * which block the sketch for the entire duration of the melody, and
+ * Play a simple melody hard-coded in the sketch.
+ *
+ * You can observe the difference between the blocking play(..),
+ * which blocks the sketch for the entire duration of the melody, and
  * playAsync(..) which returns immediately.
  */
 #include <melody_player.h>
@@ -15,27 +15,32 @@ MelodyPlayer player(buzzerPin, HIGH);
 
 void setup() {
   Serial.begin(115200);
-  while(!Serial);
+  while (!Serial)
+    ;
 
   Serial.println();
-  Serial.println("Melody Player - Simple Play (blocking vs non-blocking play");
-  
+  Serial.println("Melody Player - Simple play (blocking vs non-blocking play");
+
   Serial.println("Loading melody...");
-  String notes[] = { "C4", "G3", "G3", "A3", "G3", "SILENCE", "B3", "C4" };
-  // Load and play a correct melody
-  Melody melody = MelodyFactory.load("Nice Melody", 175, notes, 8);
-
+  const int nNotes = 8;
+  String notes[nNotes] = { "C4", "G3", "G3", "A3", "G3", "SILENCE", "B3", "C4" };
+  const int timeUnit = 175;
+  // create a melody
+  Melody melody = MelodyFactory.load("Nice Melody", timeUnit, notes, nNotes);
+
+  // get basic info about the melody
   Serial.println(String(" Title:") + melody.getTitle());
   Serial.println(String(" Time unit:") + melody.getTimeUnit());
-  Serial.print("Play in blocking mode...");
+
+  Serial.print("Start playing in blocking mode... ");
   player.play(melody);
-  Serial.println("The end!");
+  Serial.println("Melody ends!");
 
   delay(1000);
 
-  Serial.print("Play in non-blocking mode...");
+  Serial.print("Start playing in non-blocking mode...");
   player.playAsync(melody);
-  Serial.println(" not the end!");
+  Serial.println(" Melody is playing!");
 }
 
 void loop() {}

examples/2_control_melody/2_control_melody.ino

@@ -1,8 +1,6 @@
 /**
  * A melody can be played, paused or stopped.
- * 
- * To stop or pause a melody, it must be played with
- * playAsync(..) method.
+ * To stop or pause a melody, it must be started with playAsync(..) method.
  */
 #include <melody_player.h>
 #include <melody_factory.h>
@@ -16,14 +14,15 @@ int state = 0;
 
 void setup() {
   Serial.begin(115200);
-  while(!Serial);
+  while (!Serial)
+    ;
 
   Serial.println();
-  Serial.println("Melody Player - Control Melody");
-  
+  Serial.println("Melody Player - Control melody");
+
   Serial.println("Loading melody...");
   String notes[] = { "C4", "G3", "G3", "A3", "G3", "SILENCE", "B3", "C4" };
-  // Load and play a correct melody
+  // Create a melody
   Melody melody = MelodyFactory.load("Nice Melody", 250, notes, 8);
 
   player.playAsync(melody);
@@ -32,33 +31,35 @@ void setup() {
 }
 
 void loop() {
-  if(millis() - startPlay > 1000 && state == 0) {
+  if (millis() - startPlay > 1000 && state == 0) {
     state++;
     // Stop after 1 second since playAync(..)
     player.stop();
-  } else if(millis() - startPlay > 2000 && state == 1) {
+  } else if (millis() - startPlay > 2000 && state == 1) {
     state++;
     // The melody was stopped, hence it starts from the begin.
     player.playAsync();
-  }else if(!player.isPlaying() && state == 2) {
+    // Let it play until the end
+  } else if (!player.isPlaying() && state == 2) {
     state++;
-
+
+    // A small delay before restarting the melody
     delay(1000);
-    
-    // The melody has reached the end, it is automatically stopped.
-    // Hence the melody start to be played from the begin.
+
+    // The melody has reached the end and it is automatically stopped,
+    // hence the melody restarts from the begin
     player.playAsync();
     startPlay = millis();
-  } else if(millis() - startPlay > 1400 && state == 3){
+  } else if (millis() - startPlay > 1400 && state == 3) {
     state++;
     // Pause after 1.5s
     player.pause();
-  }else if(millis() - startPlay > 2000 && state == 4) {
+  } else if (millis() - startPlay > 2000 && state == 4) {
     state++;
-    // Continue to playing from where it was stopped.
+    // Continue to playing from where it was paused
     player.playAsync();
   }
-  
-  Serial.println(String("Playing: ") + player.isPlaying() ? "true" : "false");
-  delay(25);
+
+  Serial.println(String("Playing: ") + (player.isPlaying() ? "true" : "false"));
+  delay(50);
 }

examples/3_load_melody_from_file/3_load_melody_from_file.ino

@@ -1,57 +1,56 @@
 /**
  * Melody Player library can load melodies from file.
- * On ESP8266/ESP32 there is an integrated flash memory (sometimes referred as SPIFFS),s
- * which can read and write files like a traditional file system.
- * 
- * Remember to upload the "data" folder on the MCU through ESPxx Sketch Data Upload plugin.
- * On ESP8266:
- * https://github.com/esp8266/arduino-esp8266fs-plugin
- * On ESP32:
- * https://github.com/me-no-dev/arduino-esp32fs-plugin
+ * On ESP8266 and ESP32 there is an embedded portion of flash memory to store files and folders. It
+ * uses a file system, usually LittleFS or SPIFFS. You can upload files through specific plugins.
+ * For more info, look at:
+ * - On ESP8266: https://github.com/esp8266/arduino-esp8266fs-plugin
+ * - On ESP32: https://github.com/me-no-dev/arduino-esp32fs-plugin
  */
 #include <melody_player.h>
 #include <melody_factory.h>
 
 int buzzerPin = 4;
 
-// This file do not exist
+// This file does not exist
 String missingMelodyFilePath = "missing.mel";
 String melodyFilePath = "/jingle.mel";
 
 MelodyPlayer player(buzzerPin);
 
 void setup() {
   Serial.begin(115200);
-  while(!Serial);
+  while (!Serial)
+    ;
 
   Serial.println();
-  Serial.println("Melody Player - Load Melody from File");
-  
+  Serial.println("Melody Player - Load melody from file");
+
   // Remember to init the filesystem before loading a melody
   SPIFFS.begin();
 
-  Serial.println("Loading melody...");
+  Serial.println(String("Loading melody ") + missingMelodyFilePath + "...");
   Melody missingMelody = MelodyFactory.load(missingMelodyFilePath);
   // Check if the melody was successfully loaded
-  if(!missingMelody){
-    Serial.println(missingMelodyFilePath + " is really missing, trying to load another one....");
+  if (!missingMelody) {
+    Serial.println(missingMelodyFilePath + " not found, try to load another one...");
   }
 
-  // Load and play a correct melody
+  // Load and play an existing melody
+  Serial.println(String("Loading melody ") + melodyFilePath + "...");
   Melody melody = MelodyFactory.load(melodyFilePath);
-  if(melody){
+  if (melody) {
     Serial.println(melodyFilePath + " loaded!");
   } else {
     Serial.println("error");
-    while(1) delay(1000);
+    while (1) delay(1000);
   }
   Serial.println(String(" Title: ") + melody.getTitle());
   Serial.println(String(" Time unit: ") + melody.getTimeUnit() + " milliseconds");
   Serial.println(String(" Number of notes: ") + melody.getLength());
-  
-  Serial.print("Play in blocking mode...");
+
+  Serial.print("Start playing in blocking mode... ");
   player.play(melody);
-  Serial.println("The end!");
+  Serial.println("Melody ends!");
 }
 
 void loop() {}

examples/4_load_rtttl_melody/4_load_rtttl_melody.ino

@@ -1,5 +1,5 @@
 /**
- * Load an RTTTL melody from file and then from RAM.
+ * Load an RTTTL melody from hardcoded literal string and from file.
  */
 #include <melody_player.h>
 #include <melody_factory.h>
@@ -8,39 +8,46 @@ int buzzerPin = 4;
 
 String melodyFilePath = "/pokemon.rtttl";
 
-const char melodyString[] = "Pokemon:d=16,o=5,b=112:32p,f,a#,c6,c#6,c6,c#6,d#6,2f6,a#,c6,8c#6,8f6,8d#6,32c#.6,32d#.6,32c#.6,8c6,8g#.,f,a#,c6,c#6,c6,c#6,d#6,2f6,8a#,c#6,8f6,a,d#6,4g#6";
+const char melodyString[] = "Pokemon:d=16,o=5,b=112:32p,f,a#,c6,c#6,c6,c#6,d#6,2f6,a#,c6,8c#6,8f6,"
+                            "8d#6,32c#.6,32d#.6,32c#.6,8c6,8g#.,f,a#,c6,c#6,c6,c#6,d#6,2f6,8a#,c#6,"
+                            "8f6,a,d#6,4g#6";
 
 MelodyPlayer player(buzzerPin);
 
 void setup() {
   Serial.begin(115200);
-  while(!Serial);
+  while (!Serial)
+    ;
 
   Serial.println();
-  Serial.println("Melody Player - Load RTTTL Melody");
-
+  Serial.println("Melody Player - Load RTTTL melody");
+
+  Serial.print("Loading hardcoded melody... ");
+  Melody melody2 = MelodyFactory.loadRtttlString(melodyString);
+  if (melody2) {
+    Serial.println("Done!");
+    Serial.print("Playing... ");
+    player.play(melody2);
+    Serial.println("Done!");
+  } else {
+    Serial.println("Error");
+  }
+
+  delay(1000);
+  Serial.println();
+
   // Remember to init the filesystem before loading a melody
   SPIFFS.begin();
-  
+
   Serial.print("Loading melody from file... ");
   Melody melody = MelodyFactory.loadRtttlFile(melodyFilePath);
-  if(!melody) {
+  if (!melody) {
     Serial.println("Error");
   } else {
     Serial.println("Done!");
+    Serial.print("Playing... ");
     player.play(melody);
-  }
-
-  delay(1000);
-  Serial.println();
-
-  Serial.print("Loading melody from RAM... ");
-  Melody melody2 = MelodyFactory.loadRtttlString(melodyString);
-  if(melody2){
     Serial.println("Done!");
-    player.play(melody2);  
-  } else {
-    Serial.println("Error");
   }
 }
 

examples/5_play_melodies_simultaneously/5_play_melodies_simultaneously.ino

@@ -1,12 +1,11 @@
 /**
- * Play 2 different melodies at the same time on 2 buzzers.
- * 
- * This works only with playAsync(), otherwise the melodies 
- * are played sequentially.
- * 
- * For more information about enabling multiple PWM output and
- * limitations of your board, check the wiki.
- * https://github.com/fabiuz7/melody-player-arduino/wiki
+ * Play multiple melodies at the same time on different buzzers.
+ *
+ * NOTE: This works only with playAsync().
+ *
+ * For more information on how to enable multiple PWM outputs and
+ * the limitations of your board, check the wiki.
+ * https://github.com/fabianoriccardi/melody-player/wiki
  */
 #include <melody_player.h>
 #include <melody_factory.h>
@@ -17,25 +16,35 @@ int buzzerPin2 = 5;
 MelodyPlayer player1(buzzerPin1);
 MelodyPlayer player2(buzzerPin2);
 
+bool end;
+
 void setup() {
   Serial.begin(115200);
-  while(!Serial);
+  while (!Serial)
+    ;
 
   Serial.println();
-  Serial.println("Melody Player - Play Melodies Simultaneouly");
-  
+  Serial.println("Melody Player - Play melodies simultaneouly");
+
   Serial.print("Loading melodies... ");
   String notes1[] = { "C4", "G3", "G3", "A3", "G3", "SILENCE", "B3", "C4" };
   Melody melody1 = MelodyFactory.load("Nice Melody", 250, notes1, 8);
   int notes2[] = { 500, 1000, 0, 2000 };
   Melody melody2 = MelodyFactory.load("Raw frequencies", 400, notes2, 4);
   Serial.println("Done!");
 
-  Serial.print("Playing... ");
+  Serial.print("Start playing... ");
   player1.playAsync(melody1);
   player2.playAsync(melody2);
-
-  Serial.println("The end!");
+  end = false;
 }
 
-void loop() {}
+void loop() {
+  if (!player1.isPlaying() && !player2.isPlaying()) {
+    if (!end) {
+      end = true;
+      Serial.println("The end!");
+    }
+  }
+  delay(10);
+}