initial: DESIGN.md

DESIGN.md

@@ -0,0 +1,26 @@
+# Lockstep - Android music player
+
+Imagine as a runner that instead of you adapting the pace to the music, the music adapts its pace to you. When running with music, Lockstep feels your rhythm and adapts your own playlist to your running pace.
+
+We are designing the prototype of an Android app with the minimum viable feature set to demonstrate the concept. The playing song will be adapted to the user's running pace as detected by the accelerometer.
+
+For MVP 1, there will be a Playlist with multiple songs that plays back in an order such that the next song chosen by Lockstep closely matches its original rhythm (BPM) to the running pace.
+
+Frameworks: from Java, we will use oboe and a newly designed JNI library, called libpasada, as dependencies.
+
+libpasada will implement:
+* signal processing of the accelerometer time signal, turning it into a running pace time signal (an indication of frequency over time),
+* song analysis to a rhythm sequence time signal (an indication of frequency over time),
+* synthesis of the playback frequency spectrum over time, from the song's rhythm sequence time signal and the running pace time signal,
+* synthesis of the audio playback time signal from the playback frequency spectrum,
+* sampling rate conversion (running pace is in accelerometer fps, everything else must be done in audio fps),
+* buffering as necessary to feed oboe in real-time with audio frames.
+
+libpasada is implemented in C++ and may use additional libraries or frameworks as necessary to succinctly express the signal processing goals in C++.
+
+libpasada is independently testable from Android NDK tools, meaning it includes a C++ testing framework and CMake files which allow standalone building with a toolchain separate from Android NDK.
+
+For libpasada, assume that there will be an implementation. Only implement stubs necessary to control the music. Assume that mp3 files are provided by the user for their playlist, and transfer open file descriptors to C++ via JNI. Assume there is a feedback loop in C++ that receives raw accelerometer data and will adjust playback accordingly in real-time.
+
+For managing song metadata, there is a library called jukebox. It is a separate Android library, resides in a separate git repo, and is checked as a submodule into the project. It fetches metadata from the user's Spotify account and stores it in local SQLite.
+