MWEngine is..

...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 a musical context. It is easy to build upon the base classes and create your own noise generating mayhem. A few keywords describing the out-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"

How does this relate/compare to Google Oboe ?

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

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

What apps are using MWEngine ?

The engine has been written for both MikroWave and Kosm to provide fast live audio synthesis.

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

C++ ??? What about Java / Kotlin ?

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 of the JVM. In other words : high performance of the engine is ensured by the native layer operations, while ease 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 and audio processing, you are not required to write any additional C++ code. If you however intend to create your own DSP or synthesis routines (which is fun to do!) you must write them in C++, but can rely on SWIG for making them usable in Java.

A note on garbage collection and SWIG

It is important to note that when a Java object finalizes (i.e. all its references are broken and is garbage collected), the destructors 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 hold strong references during their lifecycle.

The Issue Tracker is your point of contact

Bug reports, feature requests, questions and discussions are welcome on the GitHub Issue Tracker, please do 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 consult the 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.

Development setup

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 use Android Studio you can simply open the project folder and sync the project with the build.gradle file, after which you will be prompted in case you need to install any of the above (as Android Studio can resolve and install the dependencies for you).

Though depending on your platform, you might need to install SWIG manually (as well as adding it to your path variables). SWIG is readily available from most package managers such as brew on macOS or apt-get on Linux).

Build configurations

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 level settings.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 commands are executed through Gradle.

Building the project

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

:mwengine:assemble.

Upon completion, you can run usual debug/deploy targets for the mwengine_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.

Building MWEngine as a standalone AAR library

While you could create your own custom app by cloning this repository and refactoring the example Activity to your needs, it will be far easier to maintain and include future MWEngine updates when you build the core MWEngine library 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/.

Importing the MWEngine AAR library inside your custom project

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

File > Project structure > Dependencies

Add a new Library Dependency in the Declared dependencies tab, select Jar Dependency In the Add Jar/Aar Dependency dialog, enter the path to your built AAR library /path/to/mwengine-release.aar

Your projects build.gradle file will now contain the following line:

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

In the build.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...
}

FAQ / Troubleshooting

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

Documentation

You can view the Wiki (which documents all of the engine's actors as well as a variety of real world use 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 inner workings of each class.

Unit tests

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:

• update local.properties to include the line: enable_tests=true

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

Demo

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 musical sequence 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 an attached device/emulator (note that older emulated devices can only operate at a sample rate of 8 kHz!).

Contributors

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