Introduce sound playback "until playback complete" option (#231)

  - Add new event raised when a synthesized sound completes rendering on the speaker
  - Update SoundExpressions::play() functions to allow the use of this new event as an optional terminating condition
  - Fix output inversion bug in MicroBitAudio::isPlaying()

Author: finneyj

inc/SoundEmojiSynthesizer.h

@@ -27,6 +27,10 @@ DEALINGS IN THE SOFTWARE.
 
 #include "DataStream.h"
 
+#ifndef CONFIG_EMOJI_SYNTHESIZER_OUTPUT_BUFFER_DEPTH
+#define CONFIG_EMOJI_SYNTHESIZER_OUTPUT_BUFFER_DEPTH  3
+#endif
+
 #define EMOJI_SYNTHESIZER_SAMPLE_RATE         44100
 #define EMOJI_SYNTHESIZER_TONE_WIDTH          1024
 #define EMOJI_SYNTHESIZER_TONE_WIDTH_F        1024.0f
@@ -55,6 +59,8 @@ DEALINGS IN THE SOFTWARE.
 #define DEVICE_ID_SOUND_EMOJI_SYNTHESIZER_9 3019
 
 #define DEVICE_SOUND_EMOJI_SYNTHESIZER_EVT_DONE 1
+#define DEVICE_SOUND_EMOJI_SYNTHESIZER_EVT_PLAYBACK_COMPLETE 2
+
 
 namespace codal
 {
@@ -124,6 +130,7 @@ namespace codal
         float                   sampleRange;            // The maximum sample value that can be output.
         uint16_t                orMask;                 // A bitmask that is logically OR'd with each output sample.
         int                     bufferSize;             // The number of samples to create in a single buffer before scheduling it for playback
+        int                     playbackCompleteIn;     // The number of DMA buffers to generate befor next issuing a DEVICE_SOUND_EMOJI_SYNTHESIZER_EVT_PLAYBACK_COMPLETE event
 
         float                   frequency;              // The instantaneous frequency currently being generated within an effect.
         float                   volume;                 // The instantaneous volume currently being generated within an effect.

inc/SoundExpressions.h

@@ -48,21 +48,26 @@ namespace codal
 
         /**
          * Plays a sound encoded as a series of decimal encoded effects or specified by name.
-         * Blocks until the sound is complete.
+         * Blocks until the sound generation is complete, and the synthesizer is ready to accept new requests.
+         * @param sound a string representing the sound effect to play, in the form descripbed by parseSoundExperession().
+         * @param event the event to wait for - either DEVICE_SOUND_EMOJI_SYNTHESIZER_EVT_DONE (default) or DEVICE_SOUND_EMOJI_SYNTHESIZER_EVT_PLAYBACK_COMPLETE.
          */
-        void play(ManagedString sound);
+        void play(ManagedString sound, uint16_t event = DEVICE_SOUND_EMOJI_SYNTHESIZER_EVT_DONE);
 
         /**
          * Plays a sound encoded as a series of decimal encoded effects or specified by name.
          * Does not block.
+         * @param a string representing the sound effect to play, in the form descripbed by parseSoundExperession().
          */
         void playAsync(ManagedString sound);
 
         /**
-         * Plays a sound encoded as an array of one or more SoundEffect structures.
-         * Blocks until the sound is complete.
+         * Plays a sound encoded as a series of decimal encoded effects or specified by name.
+         * Blocks until the sound generation is complete, and the synthesizer is ready to accept new requests.
+         * @param sound a string representing the sound effect to play, in the form descripbed by parseSoundExperession().
+         * @param event the event to wait for - either DEVICE_SOUND_EMOJI_SYNTHESIZER_EVT_DONE (default) or DEVICE_SOUND_EMOJI_SYNTHESIZER_EVT_PLAYBACK_COMPLETE.
          */
-        void play(ManagedBuffer sound);
+        void play(ManagedBuffer sound, uint16_t event = DEVICE_SOUND_EMOJI_SYNTHESIZER_EVT_DONE);
 
         /**
          * Plays a sound encoded as an array of one or more SoundEffect structures.

source/MicroBitAudio.cpp

@@ -330,5 +330,5 @@ bool MicroBitAudio::isPlaying()
     uint32_t start = mixer.getSilenceStartTime();
     uint32_t end = mixer.getSilenceEndTime();
 
-    return ((start && t >= (start + CONFIG_AUDIO_MIXER_OUTPUT_LATENCY_US)) && (end == 0 || t < (end + CONFIG_AUDIO_MIXER_OUTPUT_LATENCY_US - 100)));
+    return !((start && t >= (start + CONFIG_AUDIO_MIXER_OUTPUT_LATENCY_US)) && (end == 0 || t < (end + CONFIG_AUDIO_MIXER_OUTPUT_LATENCY_US - 100)));
 }

source/SoundEmojiSynthesizer.cpp

@@ -42,6 +42,7 @@ SoundEmojiSynthesizer::SoundEmojiSynthesizer(uint16_t id, int sampleRate) : Coda
     this->position = 0.0f;
     this->effect = NULL;
     this->partialBuffer = NULL;
+    this->playbackCompleteIn = 0;
     this->buffer2 = ManagedBuffer(bufferSize);
 
     this->samplesToWrite = 0;
@@ -205,6 +206,15 @@ ManagedBuffer SoundEmojiSynthesizer::pull()
     // Issue a Pull Request so that we are always receiver driven, and we're done.
     downStream->pullRequest();
 
+    // Issue a deferred DEVICE_SOUND_EMOJI_SYNTHESIZER_EVT_PLAYBACK_COMPLETE event if requested.
+    if (playbackCompleteIn > 0)
+    {
+        playbackCompleteIn--;
+
+        if (playbackCompleteIn == 0)
+            Event(id, DEVICE_SOUND_EMOJI_SYNTHESIZER_EVT_PLAYBACK_COMPLETE);
+    }
+
     return output;
 }
 
@@ -237,6 +247,7 @@ ManagedBuffer SoundEmojiSynthesizer::fillOutputBuffer()
 
                     // Flip our status bit and fire the event
                     status &= ~EMOJI_SYNTHESIZER_STATUS_STOPPING;
+                    playbackCompleteIn = CONFIG_EMOJI_SYNTHESIZER_OUTPUT_BUFFER_DEPTH+2;
                     Event(id, DEVICE_SOUND_EMOJI_SYNTHESIZER_EVT_DONE);
                     lock.notify();
                 }

source/SoundExpressions.cpp

@@ -53,9 +53,9 @@ SoundExpressions::~SoundExpressions()
  * Plays a sound encoded as an array of one or more SoundEffect structures.
  * Blocks until the sound is complete.
  */
-void SoundExpressions::play(ManagedBuffer sound)
+void SoundExpressions::play(ManagedBuffer sound, uint16_t event)
 {
-    fiber_wake_on_event(synth.id, DEVICE_SOUND_EMOJI_SYNTHESIZER_EVT_DONE);
+    fiber_wake_on_event(synth.id, event);
     playAsync(sound);
     schedule();
 }
@@ -69,8 +69,8 @@ void SoundExpressions::playAsync(ManagedBuffer sound)
     synth.play(sound);
 }
 
-void SoundExpressions::play(ManagedString sound) {
-    fiber_wake_on_event(synth.id, DEVICE_SOUND_EMOJI_SYNTHESIZER_EVT_DONE);
+void SoundExpressions::play(ManagedString sound, uint16_t event) {
+    fiber_wake_on_event(synth.id, event);
     playAsync(sound);
     schedule();
 }