efflux

What is it ?

Efflux is an application that allows users to create music inside their browser. Efflux is a tracker and follows conventions familiar to those who have used anything from Ultimate Soundtracker to Renoise. All sounds are oscillator (or wave table) based and can be routed through an effects signal path, making Efflux a modular synthesis environment, where the synths are driven by the tracker.

Feature list

• Create custom waveforms for multiple synth instruments
• Tons of keyboard shortcuts to provide nice and easy arranging using cutting, copying and cloning of (sub)patterns
• State history that allows undo / redo of your actions
• Save songs locally to continue working on them later or export / import them between devices
• Save your favourite instrument presets to be reused
• Attach a MIDI controller and record them live during playback (Google Chrome only)
• Use the Tiny Player to play back Efflux songs embedded in your website or in demos.

Sounds cool, but I don't want to build from source, I just want to tinker with this!!

Of course, this was made to allow for instant composition, so let's cut the chatter! You can use the application right now from your web browser by visiting this link.

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. However, please search before posting to avoid duplicates, and limit to one issue per post.

Please vote on feature requests by using the Thumbs Up/Down reaction on the first post.

Project outline

All source code can be found in the ./src-folder and is written in ES6 following the ES2017 spec. Efflux is written using Vue.

• ./src/ contains all JavaScript sourcecode with main.js and efflux-application.vue being the application entry points
• ./src/assets contains all used fonts and images
• ./src/model contains factories and utilities to create an Efflux song (see "Efflux song model" below)
• ./src/services contains a variety of services used to integrate hardware interaction within the application
• ./src/workers contains all Workers (which will be inlined into the compiled output and loaded as Blobs)
• ./src/utils contains utilities for common operations or to orchestrate batch changes

Additional folders:

• ./design contains SVG icons that are combined into a webfont (currently done manually through Fontello)
• ./src/fixtures can be filled with separate JSON files containing Song data, these will be concatenated into a single file that can be requested via Ajax on the first application start to provide demo content (see fixtures-loader.js)

Application actors

The Vuex store is defined in ./src/store/ and its submodules in the ./src/store/modules/-folder. Each part of the application has its own module, these are:

• editor-module used to keep track of user interactions when editing patterns
• history-module used to keep track of song mutation history to provide undo/redo functionality
• instrument-module provides a store to save, load and edit instruments presets
• midi-module used to link MIDI hardware to the application (currently Google Chrome only)
• selection-module used to keep track of selections made in the pattern editor
• settings-module used to maintain persistent configurations
• song-module provides a store to save, load and edit songs

Efflux song model

The model of an Efflux song consists of the following actors (created via their respective factories):

• Song
• Patterns
• Events
• Instruments
• Modules

A song contains a list of PATTERNS. A Pattern contains a list of channels (one for each available track) and a descriptor for the amount of steps the pattern contains (e.g. 16, 32, 64, etc.).

Each channel inside a pattern contains AUDIO_EVENTS. These describe an action that should happen at a given step within a patterns channel. These can be note on/note off instructions or module parameter automations, or both. Each event references an INSTRUMENT that it will operate on (as not all events within a single pattern channel necessarily reference the same instrument to allow for more complex compositions).

As hinted above, a song also has INSTRUMENTS. There are an equal amount of instruments available as there are tracks (the pattern channels). By default each channel references its own instruments. As the instruments in Efflux are synthesizers, each INSTRUMENT has a list of INSTRUMENT_OSCILLATORS which can be individually tuned and configured for playback.

INSTRUMENTS also reference MODULES. A MODULE is basically an effects processor. Each instrument can have its output routed through multiple processors before its output is mixed into the master channel (by the AudioService).

Efflux song model and Vuex

In Vuex, the song is stored inside its own Vuex store module "song-module.js". The editors bind directly to this reactive model, but for audio playback, an additional Object structure (e.g. AudioEvent.seq) is used. This separates the data aspect (maintained by the Vuex store mutations) from the audio rendering.

The history module provides custom methods for saving and restoring individual actions for specific sections of a song. While Vuex makes it easy to simply save an entire song upon each mutation, this will consume a lot (!) of memory fast.

Audio rendering

The synthesizer itself renders its output by use of the Web Audio API's OscillatorNodes and PeriodicWave. All of this logic is determined by noteOn and noteOff events (similar to the MIDI spec) that is handled by the AudioService. The routing of audio paths, connecting of nodes and effect modules, recording, etc. is handled by the same service, see the ./services/audio/-folder.

When in doubt of how the audio output relates to the visual interface, remember that the Vuex song model defines what it should sound like (as in: defines the properties of the instruments) while the AudioService takes care of the actual sound rendering, outside of Vue.

Wiki

For more in-depth topics, you can consult the Wiki on GitHub.

Build instructions

You will need Node.js in order to run the build scripts and resolve the dependencies.

To build Efflux, first resolve all dependencies using NPM:

npm install

After which a development mode can be started (which conveniently opens your browser and points it to the correct location at http://localhost:8080) using the following Node command:

npm run serve

A minified and transpiled production build can be created using the following command:

npm run build

After which the build output is available in the ./dist/-folder.

Unit testing

Unit tests are run via Jest. You can run the tests by using:

npm run test

Unit tests go in the ./tests-folder. The file name for a unit test should equal the file it is testing, but contain the .spec-suffix, e.g. functions.js will have a test file functions.spec.js.