165 lines
9.0 KiB
Markdown
165 lines
9.0 KiB
Markdown
# Examples
|
|
|
|
## Premise
|
|
|
|
Each of these examples consists of common and boilerplate code, which is not Brickworks-related, and a specific part which actually implements the audio engine. The common code is copied/generated by an external tool called [Tibia](https://git.orastron.com/orastron/tibia), which you first need to [run as outlined below](#tibia).
|
|
|
|
Each subfolder contains an example, except the `common` folder, which contains a good deal of common code and common Tibia-related metadata. In order to build an example, once Tibia has generated common and boilerplate code, you can just `cd` to <code>*example*/*platform*</code> and use the following platform-specific instructions. Building for any platform requires a recent enough version of [GNU Make](https://www.gnu.org/software/make/) installed.
|
|
|
|
## Tibia
|
|
|
|
### Prerequisites
|
|
|
|
You need [Node.js](https://nodejs.org/en) and [npm](https://www.npmjs.com/) to be installed.
|
|
|
|
### Usage
|
|
|
|
Get [Tibia 0.1.0](https://git.orastron.com/orastron/tibia/releases/tag/v0.1.0), extract the `tibia` folder and place it in the same parent directory as the Brickworks folder. Then either `cd` to the `tibia` folder and `npm install dot`, or install the [dot npm package](https://www.npmjs.com/package/dot) globally and make sure that the `NODE_PATH` environment variable is corretly set to find it.
|
|
|
|
Now you can `cd` to the `examples` folder and run `./tibia_gen.sh` to copy/generate files for all examples, or otherwise run `./tibia_gen.sh common` to only copy/generate files in `examples/common` or <code>./tibia\_gen.sh *example*</code> to do the same for files in <code>examples/*example*</code>.
|
|
|
|
If you want to remove all files copied/generated by Tibia, and thus restore the `examples` directory as it would appear in the official repository, run `./tibia_clean.sh` from the `examples` directory.
|
|
|
|
## VST3
|
|
|
|
### Prerequisites
|
|
|
|
Windows (via [MSYS2/Mingw-w64](https://www.msys2.org/)), macOS, and Linux OSes are supported. Building tested with [GCC](https://gcc.gnu.org/), probably also works with [Clang](https://clang.llvm.org/).
|
|
|
|
You also need to download or clone the [VST3 C API](https://github.com/steinbergmedia/vst3_c_api) and place it in the same parent folder as the Brickworks folder, or otherwise edit `common/src/vars-pre.mk` and change `CFLAGS_EXTRA` to point to the correct directory, or invoke `make` with appropriate `CFLAGS` straight from the command line.
|
|
|
|
### Build
|
|
|
|
In order to build just type `make`. You'll find the resulting VST3 directory in <code>build/bw\_example\_*example*.vst3</code>.
|
|
|
|
### Installation
|
|
|
|
If all went fine, you can install for the current user (i.e., into the user VST3 folder) by invoking `make install-user` or for all users (i.e., into the system VST3 folder) by `make install`.
|
|
|
|
## LV2
|
|
|
|
### Prerequisites
|
|
|
|
Windows (via [MSYS2/Mingw-w64](https://www.msys2.org/)), macOS, and Linux OSes are supported. Building tested with [GCC](https://gcc.gnu.org/), probably also works with [Clang](https://clang.llvm.org/).
|
|
|
|
You also need to download/install [LV2](https://lv2plug.in/), so that either header files are found by the compiler in its default include path, or otherwise you could add an appropriate `CFLAGS_EXTRA` value to `common/src/vars-pre.mk`, or invoke `make` with appropriate `CFLAGS` straight from the command line.
|
|
|
|
### Build
|
|
|
|
In order to build just type `make`. You'll find the resulting LV2 bundle in <code>build/bw\_example\_*example*.lv2</code>.
|
|
|
|
### Installation
|
|
|
|
If all went fine, you can install for the current user (i.e., into the user LV2 folder) by invoking `make install-user` or for all users (i.e., into the system LV2 folder) by `make install`.
|
|
|
|
## Web
|
|
|
|
### Prerequisites
|
|
|
|
You need [Clang](https://clang.llvm.org/) with WebAssembly target support and [OpenSSL](https://www.openssl.org/) installed.
|
|
|
|
### Build
|
|
|
|
In order to build just type `make`. You'll find the resulting output directory in `build/web`.
|
|
|
|
### Running
|
|
|
|
The output files need to be served over HTTPS. A self-signed certificate is generated in the output directory (hence the OpenSSL requirement) to make it possible to run an HTTPS-enabled web server, e.g. `http-server -S`, directly on/from the output folder.
|
|
|
|
## Daisy Seed
|
|
|
|
### Prerequisites
|
|
|
|
Building and firmware upload was only tested on Linux. You need [arm-none-eabi-gcc](https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain) (for building) and [dfu-util](https://dfu-util.sourceforge.net/) (for firmware upload) installed.
|
|
|
|
You also need to clone/download [libDaisy](https://github.com/electro-smith/libDaisy) (beware that since version 7.0.0 you also need to clone submodules, see the [release notes](https://github.com/electro-smith/libDaisy/releases/tag/v7.0.0)), `cd` to it, and run `make`. You should either place it in the same folder as the Brickworks folder, or otherwise edit `common/src/vars-pre.mk` and change `LIBDAISY_DIR` to point to the correct directory.
|
|
|
|
### Build
|
|
|
|
In order to build just type `make`. You'll find the resulting output files in `build`.
|
|
|
|
### Firmware upload
|
|
|
|
To upload the firmware:
|
|
|
|
1. branch the board to the uploading machine via USB;
|
|
2. put the board in DFU mode by pressing BOOT, then RESET, then letting go of RESET and then of BOOT;
|
|
3. type `make program-dfu`.
|
|
|
|
Effect examples report output parameter values and CPU usage statistics via USB serial. You can read the output by, e.g., `screen /dev/ttyACM0`.
|
|
|
|
## Android
|
|
|
|
### Prerequisites
|
|
|
|
Android examples are built without the help of Android Studio or Gradle. You'll however need to have a recent enough JDK (we need `javac`), as well as to download the latest stable:
|
|
|
|
- Android SDK (https://developer.android.com/studio/index.html) \*;
|
|
- Android NDK (https://developer.android.com/ndk/downloads) \*;
|
|
- `.jar`s and `.aar`s (and you'll also need to manually extract the inner `classes.jar` from each `xxx.aar`, which are just ZIP files, and rename `classes.jar` to `xxx.jar`) for:
|
|
- AndroidX Core (https://mvnrepository.com/artifact/androidx.core/core);
|
|
- AndroidX Lifecycle Common (https://mvnrepository.com/artifact/androidx.lifecycle/lifecycle-common)
|
|
- AndroidX VersionedParcelable (https://mvnrepository.com/artifact/androidx.versionedparcelable/versionedparcelable)
|
|
- Kotlin Stdlib (https://mvnrepository.com/artifact/org.jetbrains.kotlin/kotlin-stdlib);
|
|
- Koltin Coroutines Core (https://mvnrepository.com/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core);
|
|
- Koltin Coroutines Core JVM (https://mvnrepository.com/artifact/org.jetbrains.kotlinx/kotlinx-coroutines-core-jvm);
|
|
- `miniaudio.h` library (http://miniaud.io/).
|
|
|
|
Then you'll probably also need to adjust paths and values in `common/src/vars-pre.mk`.
|
|
|
|
\* You can install both the needed parts of the Android SDK and the NDK by downloading the so-called "command line tools" (https://developer.android.com/studio#command-line-tools-only) and using the included `sdkmanager` program. In such case you need to install the following packages: "platforms;android-*latest*", "build-tools;*latest*", "platform-tools", and "ndk;*latest*".
|
|
|
|
### Build
|
|
|
|
In order to build just type `make`. You'll find the resulting `.apk` file in `build`.
|
|
|
|
### Installation
|
|
|
|
If all went fine, you can branch your device and install using `make install` or otherwise install manually.
|
|
|
|
### Usage
|
|
|
|
Effect examples process audio input signals, therefore they will require permission to use the capture device.
|
|
|
|
Synth examples use input MIDI and support hotplugging.
|
|
|
|
## iOS
|
|
|
|
### Prerequisites
|
|
|
|
iOS examples are not directly built by the supplied Makefiles. These rather generate the corresponding XCode projects and required files.
|
|
|
|
For this to work you need to have the latest [Xcode](https://developer.apple.com/xcode/) and [XcodeGen](https://github.com/yonaskolb/XcodeGen) installed, as well as a copy of the latest [`miniaudio.h`](http://miniaud.io/).
|
|
|
|
Finally, you might need to adjust header search path for miniaudio in `common/src/ios-make.json` and [run Tibia](#tibia).
|
|
|
|
### Build
|
|
|
|
Typing `make` will generate the required Xcode project in `build/gen`.
|
|
|
|
You'll need to open it and select a development team (click on the project root in the left side pane, then choose the "Signing & Capabilities" tab, and finally pick a "Team").
|
|
|
|
At this point you can build and run as with any other iOS app.
|
|
|
|
### Usage
|
|
|
|
Effect examples process audio input signals, therefore they will require permission to use the capture device.
|
|
|
|
Synth examples use input MIDI and support hotplugging.
|
|
|
|
## Command line program
|
|
|
|
### Prerequisites
|
|
|
|
Windows (via [MSYS2/Mingw-w64](https://www.msys2.org/)), macOS, and Linux OSes are supported. Building tested with [GCC](https://gcc.gnu.org/), probably also works with [Clang](https://clang.llvm.org/).
|
|
|
|
Depending on the specific example, you might need to download or clone [tinywav](https://github.com/mhroth/tinywav) and/or [midi-parser](https://github.com/abique/midi-parser) and place them in the same folder as the Brickworks folder, or otherwise edit `common/src/vars-pre.mk`
|
|
|
|
### Build
|
|
|
|
In order to build just type `make`. You'll find the resulting executable file in `build`.
|
|
|
|
### Usage
|
|
|
|
Just run the executable without arguments to get usage instructions.
|