Incudine

Music/DSP programming environment for Common Lisp

Incudine is useful to design software synthesizers or sound plugins from scratch, exploiting the expressive power of Common Lisp, without the constraint to use pre-built unit generators. It is also a compositional tool that allows to produce high quality sounds controllable at the sample level, defining and redefining the digital signal processors and the musical structures on-the-fly.

Incudine introduces the Virtual UGen (VUG), a new mechanism for defining primitive unit generators by writing concise and reusable code. The definition of a VUG can contain lisp code, other nested VUGs or "real" unit generators (compiled VUGs), and it is re-arranged (i.e. after the inference of init- and performance-time actions) and compiled efficiently during the creation of a DSP. An ironic example in spaghetti.cudo includes the macro expansion of a "recipe processor".

Features

Realtime synthesis with sample-by-sample or block-by-block processing (without a realtime garbage collector but there are facilities for defining cons-free DSP).
Arbitrary precision. The sample type is double float but the unit generators and the DSP's don't require a particular type. In practice the init-time and performance-time functions of UGEN or DSP are arbitrary lisp functions regulated by the context (i.e. realtime audio).
Node tree for DSP instances and arbitrary actions.
Realtime sample accurate scheduling.
Optional recovery of audio cycles suspended during gc by processing the cached audio inputs and MIDI events. For example, it allows HD recording without losing audio inputs during gc if there aren't xruns.
Collection of useful re-definable virtual unit generators.
Collection of GEN routines to fill memory buffers.
Bounce to disk and bounce to memory buffer.
MIDI support via PortMidi and Jack MIDI.
MIDI File I/O support.
Open Sound Control support.
Stream socket support.
Serial I/O support.
Tempo change with arbitrary curves.
Import/Export a musical scale from/to scale file format.
MIDI tuning by sending a bulk tuning dump message with arbitrary checksum function or 128 single note tuning change messages (Exclusive Real Time).
Frequencies of a TUNING structure changed with the data received from a MIDI bulk tuning dump message.
Flexible voicer for voice management.
Score file format (rego file) with time-tagged lisp functions, lisp statements, lisp tags and arbitrary score statements.
The score file format supports the Org markup language.
Optional standalone executable.
Optional interface to interact with the sound editor Snd.
Optional cudere-clm package, the sound synthesis package CLM (Common Lisp Music) implemented in Incudine.
Optional interface to define a VUG for a LADSPA audio plugin.
Optional interface to define a VUG for a LV2 audio plugin.
Optional FluidSynth SoundFont synthesizer support.
Incudine is released under the GNU General Public License (GPL) version 2 or later.

Installation

The latest source code can be obtained via Git:

git clone git://git.code.sf.net/p/incudine/incudine

Mirror:

git clone git://github.com/titola/incudine.git

Requirements

Incudine works with SBCL, an implementation of ANSI Common Lisp with a high-performance native compiler.

Common Lisp packages:

ALEXANDRIA
BORDEAUX-THREADS
CFFI
SWAP-BYTES
[Optional] Linedit for incudine command

Foreign libraries:

Some Linux distributions provide separated devel packages necessary to compile Incudine, for example jack-audio-connection-kit-devel, portaudio-devel, etc.

Configuration

Put the incudine directory where ASDF finds your systems, for example:

mv incudine ${HOME}/common-lisp/

If you use Quicklisp:

mv incudine /path/to/quicklisp/local-projects/

Edit and copy the sample configuration file, with particular attention to the priorities *RT-PRIORITY*, *NRT-PRIORITY* and *RECEIVER-DEFAULT-PRIORITY*

cp /path/to/incudine/incudinerc-example ${HOME}/.incudinerc

If MMCSS (Multimedia Class Scheduler Service) is available on Windows, the realtime thread is associated with the "Pro Audio" task.

Here is a test:

(require :incudine)
(in-package :scratch)
(dsp! hello-world () (out (sine 440 .3)))
(rt-start)
;; You should hear an oscillation at 440 Hz.
(hello-world)
(free 0)
(rt-stop)
;; It writes a soundfile.
(bounce-to-disk ("/tmp/test.wav" :channels 1 :duration 1) (hello-world))

GNU Emacs and Texinfo are required to build the documentation:

cd doc/manual && make info html pdf

This builds the Info, HTML and PDF documentation from the Org and Texinfo sources.

If you want to create and install the incudine command:

cd src && sh install_executable

The options for the script install_executable are:

--prefix=PREFIX       install architecture-independent files in PREFIX
                      [/usr/local]
--bindir=DIR          user executables [PREFIX/bin]
--swank-loader=PATH   support for Swank server with path to swank-loader.lisp
--without-aclrepl     do not use Allegro CL-style Read-Eval-Print Loop.
--with-clm            use cudere-clm, the Incudine version of CLM
--with-linedit        support for Linedit, readline-style library in CL.
--with-fluidsynth     support for FluidSynth SoundFont synthesizer.
--with-ladspa         support for LADSPA plugins.
--with-lv2            support for LV2 plugins.
--with-snd            support for the sound editor Snd.
--with-module=NAME    load the module NAME before to create the executable.
--save-options=OPTS   further arguments for SAVE-LISP-AND-DIE.
--sbcl-options=OPTS   options for SBCL.
--before-save=FORM    read and evaluate FORM before to create the executable.

For example:

sh install_executable \
  --bindir=/computer/music \
  --swank-loader=/path/to/slime/swank-loader.lisp \
  --with-linedit \
  --with-clm \
  --with-snd \
  --with-ladspa \
  --with-lv2 \
  --with-fluidsynth \
  --with-module=series \
  --with-module=anaphora \
  --save-options=":compression t" \
  --before-save="(series::install :pkg :scratch :shadow nil)"

Note: the support for LV2 plugins requires Lilv, a LV2 host library. The option :compression t works if :sb-core-compression was enabled in SBCL at build-time.

There are two major modes for GNU Emacs: incudine-mode and incudine-rego-mode for editing lisp (cudo) and score (rego) files, respectively. If you want to install them, add the following lines to your .emacs file:

(push "/path/to/incudine/contrib/editors/emacs" load-path)
(require 'incudine)
;; org-babel source code block.
(require 'ob-incudine)

Documentation

Incudine Manual

Tutorials

Incudine home page

The source files are in incudine/doc/tutorials/ (text format) and incudine/doc/html/ (html format).