Skip to content

Commit

Permalink
Update readme for migration to love-android
Browse files Browse the repository at this point in the history
Most significantly running Hexpress version from internal filesystem
is no longer supported.
  • Loading branch information
jmiskovic committed Mar 21, 2021
1 parent 55015a2 commit a633b75
Showing 1 changed file with 5 additions and 9 deletions.
14 changes: 5 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,9 @@ Free-form layout allows placing any number of circular zones that act as note tr

Hexpress runs on Android & desktop versions of LÖVE framework. LÖVE is an *awesome* framework for 2D games, which also makes it decent fit for implementing musical instruments.

LÖVE uses openal-soft library for cross-platform audio. It supports spatial audio, real-time effects (reverb, chorus, distortion, echo, flanger, modulator, compressor, equalizer), and sound capture. It's not meant for professional music applications, but so far it's proven to be effective for the needed scope. The released Hexpress app makes some modifications to LÖVE framework code. The framework code and Android building environment is currently not included in this repository because of maintainability problems. Please open an issue if this is of any interest.
LÖVE uses openal-soft library for cross-platform audio. It supports spatial audio, real-time effects (reverb, chorus, distortion, echo, flanger, modulator, compressor, equalizer), and sound capture. It's not meant for professional music applications, but so far it's proven to be effective for the needed scope. Recently the LÖVE Android port started using Oboe which enables low-latency audio across many devices.

The released Hexpress app makes some modifications to LÖVE framework code. The framework code and Android building environment is currently not included in this repository because of maintainability problems. It is almost identical to official [LÖVE for Android] app, with differences being app icon and name. Please open an issue if hosting app is of any interest. The code from this repo can be used with official [LÖVE for Android app](https://play.google.com/store/apps/details?id=org.love2d.android).

Hexpress supports any number of virtual instruments. Several instruments are provided in *patches* subdirectory. When application starts, a `selector.lua` module scans for patches and presents them to user for selection. For this purpose, patch contains `icon()` function that is called each frame by selector to render representation of patch to user. Once a patch is selected, it starts executing in place of selector module. The phone's *back* button unloads current patch and returns execution to selector.

Expand All @@ -38,8 +40,6 @@ The *stream* is then sent to *sampler* module to convert to audio output. Each s

The drawing of visuals is mostly done inside note layout modules (`hexpad.lua`, `fretboard.lua`, `freeform.lua`). They render iterate through grid of note layout to show positions of notes, with currently played notes being rendered with different color/size/animation. There are three level of granularity for customizing instrument visualizations. Easiest modification is just changing color scheme of note layout (for example `choir.lua`). More customization is possible by re-using grid layout but overriding drawing of individual cells (for example `analog.lua`). For complete control, note layout rendering is not used at all and rendering is re-implement inside the patch (this makes `strings.lua` look unique).

Aside from using built-in patches, Hexpress app can also open external project with different set of patches, or a completely changed codebase. Lua is interpreted language, so these changes don't require recompilation or app re-installation. The Hexpress app is almost identical to official LÖVE for Android app, with differences being app icon and name, expected location of interpreted code on internal storage, and tweaks for lower audio latency.


# Creating and modifying instruments

Expand All @@ -51,11 +51,6 @@ The lua script for patch has to be named same as patch directory. The script is

As mentioned, modified codebase doesn't require any code compilation or building of APK. The installed Hexpress app can load modified codebase instead of built-in codebase. This allows for tweaking of any settings, designing of new insturments, modifying visuals, changing sound samples, all by modifying files on your phone.

To run modified version on your phone, copy content of whole repository to internal device memory under directory `/sdcard/hexpress` and launch the app. The app will scan for project files in this directory and run those instead of default project bundled within the app. It's good idea to change the background color in selector.lua, to verify which version is currently running on device: `background = {l.rgba(0x003f20ff)}`

Please note: this automatic code-loading feature will prevent you from seeing the updates in official app. To switch back to official project, just delete or rename `hexpress` directory in device memory, or pull new version and update on phone.


# Unexplored ideas

Here are some promising ideas that I never got around to implementing.
Expand All @@ -70,4 +65,5 @@ Explore the musical theory concepts by implementing different note arrangements

Add an intelligent music assistant that automatically adds harmonic accompaniment to played melody, and suggests next melody note based on previous notes and learned model.

Implement the layered looper that would enable whole compositions inside the app. The looper would record note events and repeat them periodically. This looper could be combined with intelligent assistant - you would teach it to play something by repeating a pattern until it's well learned. The repetition in learning process would also serve to eliminate glitches/mistakes.
Make interactive tool for creating custom instruments. It could focus on stringed instruments (drag string endpoints around, shorter strings produce higher pitches), or it could support generic trigger pads with assigned sounds and pitches.

0 comments on commit a633b75

Please sign in to comment.