README.md
1**DrumThumper**
2==========
3Oboe playback sample app.
4
5## Abstract
6**DrumThumper** is a "Drum Pad" app which demonstrates best-practices for low-latency audio playback using the Android **Oboe** API.
7**DrumThumper** consists of a set of trigger pad widgets and an optional UI for controlling the level and stereo placement of each of the virtual drums.
8The audio samples are stored in application resources as WAV data. This is parsed and loaded (by routines in **parselib**) into memory blocks.
9The audio samples are mixed and played by routines in **iolib**.
10
11**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).
12
13## Scope
14**DrumThumper** is designed with the following goals in mind:
15* To demonstrate the most efficient means of playing audio with the lowest possible latency.
16* To demonstrate how to play multiple sources of audio mixed into a single Oboe stream.
17* To demonstrate the life-cycle of an Oboe audio stream and it's relationship to the application lifecycle.
18* To demonstrate the correct handling of playback errors and output device connection/disconnection.
19
20Secondarily, **DrumThumper** demonstrates:
21* Using Android "assets" for audio data.
22* The mechanism for calling native (C/C++) audio functionality from a Kotlin/Java app.
23* A mechanism for sharing binary data between a Kotlin/Java app with the native (C/C++) layer.
24* A mechanism for parsing/loading one type (WAV) of audio data.
25* How to control the relative levels (gain) of audio sources mixed into an output stream.
26* How to locate a mono data source in a stereo output stream.
27* How to use the Oboe resampler to resample source audio to the device playback rate, and therefore not incur this overhead at playback time.
28
29To keep things simple, **DrumThumper** specifically does not:
30* Does not support audio samples in other than 16-bit, mono PCM Samples. It does not support Stereo or different PCM formats.
31* Does not support non-WAV audio data (such as AIFF).
32* Does not support compressed audio data.
33
34**DrumThumper** now supports different sample rates for the source samples.
35
36If one wanted to extend **DrumThumper** to support Stereo samples:
37* The SampleSource class would need to be extended to understand Stereo SampleBuffer objects, it currently assumes Mono.
38* The OneShotSampleSource.mixAudio() method would need to have separate mixing logic for Stereo and Mono SampleSource.
39
40## DrumThumper project structure
41### Kotlin App Layer
42Contains classes for the application logic and defines the methods for accessing the native data and player functionality.
43
44### Native (C++) layer
45Contains the implementation of the `native` (JNI) methods defined in the `DrumPlayer` (Kotlin) class.
46
47### Dependent Libraries
48* **iolib**
49Classes for playing audio data.
50
51* **parselib**
52Classes for parsing and loading audio data from WAV resources.
53
54## App
55* DrumPlayer.kt
56The Kotlin class which provides the audio playback functionality by interfacing with the native (C++) libraries.
57
58* DrumThumperActivity.kt
59The main application logic.
60
61* TriggerPad.kt
62An Android View subclass which implements the "trigger pad" UI widgets
63
64## Native-interface (JNI)
65* DrumPlayerJNI.cpp
66 This is where all the access to the native functionality is implemented.
67