README.org

November 16, 2025 ยท View on GitHub

** Installation

You will need a system that has a working [[http://www.sbcl.org/][sbcl]] setup. In addition you will need to setup [[http://jackaudio.org/][JACK]] (for Linux), or [[https://github.com/PortMidi/portmidi/][PortMidi]] (for Windows, OSX or a Linux system running PulseAudio).

First get all Common Lisp components:

Using a common lisp with quicklisp installed, copy all the folders of the prerequsites into the local-projects subfolder of your local quicklisp installation folder (default is /quicklisp/local-projects).

** Usage

First start [[http://jackaudio.org/][JACK]], then sbcl and evaluate the following:

#+BEGIN_SRC lisp (ql:quickload "cm-incudine")

 (cm:rts)

#+END_SRC

The last command automatically changes into the =:cm= package, starts the incudine realtime thread, adds audio ports and MIDI ports to jack.

*** MIDI Output

To send realtime MIDI messages to your midi output you can use =output=, =events= or =sprout=. Before testing the following code make sure some MIDI synth (e.g. [[https://qsynth.sourceforge.io/][QSynth]]) is started and connected to the incudine midi-out port (e.g. using the [[https://qjackctl.sourceforge.io/][QjackCtl]] program).

#+BEGIN_SRC lisp (output (new midi))

 (events
  (loop for x below 10
     collect (new midi :time (* x 0.5) :keynum (between 60 71)))
  ,*rts-out*)

 (sprout
  (loop for x below 10
     collect (new midi :time (* x 0.5) :keynum (between 60 71))))

 (events
  (process
    repeat 5
    output (new midi :time (now) :keynum (between 60 71))
    wait 0.5)
  ,*rts-out*)

 (sprout
  (process
    repeat 5
    output (new midi :time (now) :keynum (between 60 71))
    wait 0.5))

#+END_SRC

*** FUDI output and input

Sending to [[https://en.wikipedia.org/wiki/Pure_Data][Pure Data]] requires to first start pd and open or create
a patch containing a =[netreceive 3012]= object. For testing
purposes a =[print]= object connected to the netreceive's left
outlet can be used. In this case watch the messages appearing in
pd's post window, when sending FUDI messages from cm to pd using
the code below.

#+BEGIN_SRC lisp
  (fudi-open-default :host "127.0.0.1" :port 3012 :direction :output)

  (sprout
   (process
     repeat 2
     output (new fudi :time (now) :message '(1 2 3 4))
     wait 1))

#+END_SRC

Receiving FUDI also works after opening the respective stream with 

#+BEGIN_SRC lisp
 (fudi-open-default :host "127.0.0.1" :port 3011 :direction :input)
#+END_SRC

#+RESULTS:
: #<FUDI:INPUT-STREAM :TCP "127.0.0.1" 3011>

Please refer to the common music docs for handling input events
and establishing receivers.

*** OSC output and input

Sending OSC messages is similar to sending FUDI messages except
that OSC requires argument type information in addition to the
message itself.

#+BEGIN_SRC lisp
 (osc-open-default :host "127.0.0.1" :port 3003 :direction :output)

 (sprout
  (process
    repeat 2
    output (new osc :time (now) :types "iiii" :message '(1 2 3 4))
    wait 1))
#+END_SRC

receiving OSC also works after opening the respective stream with 

#+BEGIN_SRC lisp
 (osc-open-default :host "127.0.0.1" :port 3004 :direction :input)
#+END_SRC

Please refer to the common music docs for handling input events
and establishing receivers.

*** Miscellaneous

The default time format is :sec but can also be set to :sample or :ms
with the function =set-time-format=.

The functions =at= and =now= are wrappers for the same incudine
functions which automatically translate from/to the current
time-format.

For other usage examples see the file =src/cm-incudine-examples.lisp=.

Orm Finnendahl 2017/18