Luasynth is a small audio framework, written in Lua, emphasizing
clean, modular, declarative code. For a taste, read the source of its
panning effect (
effects/pan.lua) or delay (
Both are very short.
The plan: allow sound generators (oscillator, noise generator, sampler...) and effects (gain, distortion, reverb, delay...) to be written, chained together, and embedded in a host program. It's like a miniature version of the VST or LV2 plugin interfaces.
Why use Lua? Unlike other high-level languages, it's extremely simple to embed and LuaJIT provides excellent performance for this type of thing.
Installing and using
By itself, Luasynth doesn't do very much. It only comes with a basic demo app for generating or processing audio offline, via the command line. To use that, install LuaJIT. You'll probably also want SoX to convert into and out of the raw, 32-bit, floating-point audio format Luasynth uses.
Here's an example:
sox input.wav -tf32 -c2 -r44100 -q - \ | ./luasynth delay -len 83 -feedback 90 \ | ./luasynth amp -gain -6 \ | sox -tf32 -c2 -r44100 -q - -b16 delayed.wav
This adds a delay to
input.wav, reduces the volume by 6 dB, and
writes the output to
-tf32 -c2 -r44100 options to
SoX tell it to handle the format Luasynth uses, while
the output file back to 16-bit, the resolution of CD-quality audio.
In this example, we're using
luasynth twice. The first usage
./luasynth delay -len 83 -feedback 90
delay unit with the
len knob (length of time to
delay) set to 83 milliseconds and
feedback (amount of feedback) set
to 90%. The second usage
./luasynth amp -gain -6
amp unit and sets the
gain knob, which is in
decibels, to -6. For a full list of available units, run
./luasynth help units, and for help on an individual one, run
./luasynth help <unit name>.
The sample rate is assumed to be 44100 Hz by default, but can be
changed by setting the environment variable
RATE. For example, to
work at 48KHz, type
export RATE=48000 in the shell followed by
similar commands to those above.
Moon-Noise, a random noise generator, provides a small example of embedding Luasynth (in another Lua program in this case). You can also embed Luasynth in a C application using Lua's C API.
Luasynth's command-line driver (main.lua, which you're calling if you
./luasynth as above) requires LuaJIT for binary I/O to work.
However, the audio units themselves will run (albeit slower) in
There's no complete documentation of the API yet, sorry, but it's very
simple, and the tests in
spec/wrap_spec.lua do describe how most of
Luasynth uses Busted for testing. To run tests:
The specs cover most, if not all, of Luasynth's API, including graceful error handling in case the API is misused. Audio units themselves are not currently tested. I'm not aware of an easy way to test that, for example, a sine-wave generator or lowpass filter is working as expected, but I'm open to suggestions.
History and design
I started writing "Synth" way back in 2005. At the time, I was using OpenBSD as my home operating system, which I admit is a pretty unusual choice. There was next to no audio software available for OpenBSD, and I wanted to create a little toolbox for the basic stuff.
In Synth, all audio units are command-line programs, piped together to generate or process sound, like this:
square -freq 1000 -len 5000 \ | filter -type bandpass -center 2000 -q 10 \ | pan -angle -20 \ | fmt -16 \ | <some command to play or save the audio>
Luasynth comes with a command-line driver app that can be used similarly:
./luasynth osc -oscType square -freq 1000 -length 5 \ | ./luasynth filter -filtType Bandpass -center 2000 -q 10 \ | ./luasynth pan -angle 20 \ | <command to convert, play or save... "fmt" is not included>
Both pipelines generate 5 seconds of a square wave, bandpass filter it, and pan it about halfway to the right.
But Truesynth and Luasynth are both embeddable. Audio units do not parse command-line arguments or handle file I/O directly. Instead, they define parameters ("knobs" in Luasynth) that the host application can set, and methods the host application can call to process or generate audio. The command-line interface is therefore just one possible host application.
From 2009 to 2010, while a member of the experimental noise band Extremities, I used Truesynth as part of my rig to improvise and play live shows. The host application created a software feedback loop which passed through several Truesynth effects, whose parameters were controlled by the orientation, rotation and button state of a joystick.
Luasynth was one of my projects while attending the Winter 2013 batch of Hacker School. Hacker School is awesome.