Merge remote-tracking branch 'origin/master' into playstore_prep

Merge conflict apparently.

2 files changed, 27 insertions, 3 deletions

diff --git a/samples/drumthumper/README.md b/samples/drumthumper/README.md
index 972231e9..3307b4cf 100644
--- a/samples/drumthumper/README.md
+++ b/samples/drumthumper/README.md
@@ -10,6 +10,26 @@ The audio samples are mixed and played by routines in **iolib**.
 
 **DrumThumper** is written in a combination of Kotlin for the UI and JNI/C++ for the player components (to demonstrate accessing native code from a Kotlin or Java application).
 
+## Scope
+**DrumThumper** is designed with the following goals in mind:
+* To demonstrate the most efficient means of playing audio with the lowest possible latency.
+* To demonstrate how to play multiple sources of audio mixed into a single Oboe stream.
+* To demonstrate the life-cycle of an Oboe audio stream and it's relationship to the application lifecycle.
+* To demonstrate the correct handling of playback errors and output device connection/disconnection.
+
+Secondarily, **DrumThumper** demonstrates:
+* Using Android "assets" for audio data.
+* The mechanism for calling native (C/C++) audio functionality from a Kotlin/Java app.
+* A mechanism for sharing binary data between a Kotlin/Java app with the native (C/C++) layer.
+* A mechanism for parsing/loading one type (WAV) of audio data.
+* How to control the relative levels (gain) of audio sources mixed into an output stream.
+* How to locate a mono data source in a stereo output stream.
+
+To keep things simple, **DrumThumper** specifically does not:
+* Does not provide support audio samples in other than 16-bit, 44.1K, mono PCM Samples. It does not support Stereo, different samples rates or different PCM formats.
+* Does not provide support for non-WAV audio data (such as AIFF).
+* Does not provide support for compressed audio data.
+
 ## DrumThumper project structure
 ### Kotlin App Layer
 Contains classes for the application logic and defines the methods for accessing the native data and player functionality.
diff --git a/samples/drumthumper/src/main/java/com/plausibleaudio/drumthumper/DrumPlayer.kt b/samples/drumthumper/src/main/java/com/plausibleaudio/drumthumper/DrumPlayer.kt
index 9b90ccb1..cbcf3233 100644
--- a/samples/drumthumper/src/main/java/com/plausibleaudio/drumthumper/DrumPlayer.kt
+++ b/samples/drumthumper/src/main/java/com/plausibleaudio/drumthumper/DrumPlayer.kt
@@ -22,8 +22,12 @@ import java.io.IOException
 class DrumPlayer {
     companion object {
         // Sample attributes
-        val NUM_CHANNELS: Int = 2       // Stereo Playback, set to 1 for Mono playback
-        val SAMPLE_RATE: Int = 44100    // All the input samples are 44.1K
+        val NUM_CHANNELS: Int = 2       // The number of channels in the player Stream.
+                                        // Stereo Playback, set to 1 for Mono playback
+                                        // This IS NOT the channel format of the source samples
+                                        // (which must be mono).
+        val SAMPLE_RATE: Int = 44100    // All the input samples are assumed to BE 44.1K
+                                        // All the input samples are assumed to be mono.
 
         // Sample Buffer IDs
         val BASSDRUM: Int = 0
@@ -35,7 +39,7 @@ class DrumPlayer {
         val HIHATOPEN: Int = 6
         val HIHATCLOSED: Int = 7
 
-        // Pan position for each drum sample
+        // initial pan position for each drum sample
         val PAN_BASSDRUM: Float = 0f         // Dead Center
         val PAN_SNAREDRUM: Float = 0.25f     // A little Right
         val PAN_CRASHCYMBAL: Float = -0.75f  // Mostly Left