Repository files navigation

...an audio engine for Android, compatible with Android 4.1 and up, using either OpenSL or AAudio(when available) as the drivers for low latency audio performance.

MWEngine provides an architecture that allows you to work with audio within amusical context. It is easy tobuild upon the base classes and create your own noise generating mayhem. A few keywords describing theout-of-the-box possibilities are:

• tempo-based sequencing with support for alternative time signatures
• on-the-fly audio synthesis
• multi-channel audio output
• effect chains operating on individual input/output channels
• sample playback with real time pitch shifting
• live recording and processing from your device's inputs (e.g. microphone)
• bouncing output to WAV files, either live (during a performance) or "offline"

Though MWEngine was initially created before Oboe, its underlying audio drivers arethe same as Google Oboe uses, MWEngineand Oboe are merely different abstraction layers to solve the same problem.

Additionally, MWEngine provides a complete audio sequencing and processing environment with built-in effectswithout youneeding to write/know C(++) to use it.

The engine has been written for bothMikroWave andKosm to provide fast live audio synthesis.

While development on aforementioned apps has (practically) been discontinued, the engine itself has over the years been continuously updatedto be of use to third party app developers, such asTIZE - Beat Maker, Music MakerandAnother Flamenco Compás App.

Though the library is written in C++ (and can be used solely within this context), the library can be built using JNI(Java Native Interface) which makes its API expose itself to Java / Kotlin, while still executing in a native layer outside ofthe JVM. In other words : high performance of the engine is ensured by the native layer operations, whileease of development is ensured by delegating application logic / UI to the realm of the Android Java SDK.

Whether you intend to use MWEngine for its sample based playback or to leverage its built-in synthesizer andaudio processing, you are not required to write any additional C++ code. If you however intend to create your ownDSP or synthesis routines (which is fun to do!) you mustwrite them in C++,but can rely on SWIG for making them usable in Java.

It is important to note that when a Java object finalizes (i.e. all its references are broken and is garbage collected), thedestructors of the native objects are invoked, which can lead to unpredictable results if you happen to overlook this!As such, audio engine objects such as effects processors or events that are created on the Java side, must holdstrong references during their lifecycle.

Bug reports, feature requests, questions and discussions are welcome on the GitHub Issue Tracker, pleasedo not send e-mails through the development website. Please search before posting to avoid duplicates and limit to one issue per post.For usage / implementation related questions, first consultthe MWEngine Wiki.

When reporting a bug, please describe the expected behaviour and the actual result. When possible, for crashes attach stack traces and recordings for audio related glitches.

Vote on existing feature requests by using the Thumbs Up/Down reaction on the first post.

You will need the following development kits:

• Android SDK
• Android NDK to build the native layer code

And the following toolchains:

• Gradle to run all build commands
• CMake to build the native layer code
• SWIG to wrap the native layer code in Java classes

If you useAndroid Studio you can simply open the projectfolder and sync the project with thebuild.gradle file, after which you will be prompted in caseyou need to install any of the above (as Android Studio can resolve and install thedependencies for you).

Though depending on your platform, you might need to install SWIGmanually (as well as adding it to your path variables). SWIG is readily available frommost package managers such asbrew on macOS orapt-get on Linux).

This repository contains two modules:

• /mwengine/ which is the core MWEngine library (native code, Java API wrappers)
• /mwengine_example/ which contains an example Activity bundling the library into an Android app

Both are referenced in the root levelsettings.gradle file for a standard multi module setup.

The build configurations themselves are defined in:

• build.gradle (the usual setup, build and deploy toolchain for Android, per module)
• CMakeLists.txt (for the native layer code, solely in /mwengine module)

If you are uncomfortable with C development, you can ignore the makefile as all build commandsare executed through Gradle.

Upon checkout this repository does not include the Java API files (nl.igorski.mwengine.core-namespace) asthese are wrappers and generated by the build. In order to generate these files, you should run theassembletask of themwengine-module, e.g.:

:mwengine:assemble.

Upon completion, you can run usual debug/deploy targets for themwengine_example-module to start the example application.Using Android Studio you can easily debug native code of the library inside the example Activity using breakpoints.

While you could create your own custom app by cloning this repository and refactoring the example Activity toyour needs, it will be far easier to maintain and include future MWEngine updates when you build the core MWEnginelibrary as an Android Archive (.AAR) and reference the library within your project.

In order to do so, you run the following Gradle command:

:mwengine:assemble

Which will generate the library in both debug and release configurations, packaged as AAR files in:./mwengine/build/outputs/aar/.

Within Android Studio you can easily do this by importing the generated .aar file by navigating through:

File > Project structure > Dependencies

Add a newLibrary Dependency in theDeclared dependencies tab, selectJar DependencyIn theAdd Jar/Aar Dependency dialog, enter the path to your built AAR library/path/to/mwengine-release.aar

Your projectsbuild.gradle file will now contain the following line:

implementation files('/path/to/mwengine-release.aar')

In thebuild.gradle for your application, be sure to add the following entries under the defaultConfig and dependencies sections:

android {    defaultConfig {        // project specific custom stuff here...        ndk {            // these values must match the ABI's defined in mwengine/build.gradle            // to prevent UnsatisfiedLinkError when this app tries to serve an unsupported architecture            abiFilters "armeabi-v7a", "arm64-v8a", "x86_64"        }    }}dependencies {    implementation project(":mwengine-release")    // project specific custom stuff here...}

The contents of this repository should result in a stable library and exampleapplication. If you experience issues with the setup, consult theTroubleshooting Wiki page.

You can view the Wiki (which documents all of the engine's actors as well as a variety of real worlduse cases) here:

https://github.com/igorski/MWEngine/wiki

Note that you can also view the contents of the header files to get more details about the innerworkings of each class.

The library comes with unit tests (/src/main/cpp/tests/), written using the Googletest C++ testing framework.

To enable unit testing upon each build / during development:

• updatelocal.properties to include the line:enable_tests=true

Note:adb must be available in your global path settings and the attached device / emulatormust have the x86_64 CPU architecture (seeCMakeLists.txt).

The repository contains an example Activity that is ready to deploy onto any Android device/emulator supporting ARM-, ARMv7-,x86- architecture and running Android 4.1 or higher. The example will demonstrate how to quickly get a musicalsequence going using the library.

To install the demo: first build the library as described above, and then run the build script to deploy the .APK onto anattached device/emulator (note that older emulated devices can only operate at a sample rate of 8 kHz!).

MWEngine has received welcome contributions (either suggestions on improving the API or proposal of new features,solving of bugs, etc.) from the following developers :

• Andrey Stavrinov (@hypeastrum)
• Toufik Zitouni & Robert Avellar (Tize)
• Koert Gaaikema (@koertgaaikema)
• Matt Logan (@mattlogan)
• Thomas Flasche (@harthorst)
• Rickard Östergård (@rckrdstrgrd)
• Aran Arunakiri