A multichannel audio panning application for JACK1).

                       Source: git://


The Spectacle Fashion Show in Amsterdam was looking for a 10 minute surround soundtrack, and here I was, together with Mhairi , An, Ivan and JACK…

andBeyond had 8 PA speakers available to fill a circular chapel (,, Even worse than the sound reflections there was the fact that the audience had to be seated along the outer walls. Only the models would able to appreciate the sweet-spot ;) - I had only one week to prepare the setup and the final no go for using ambisonics or WFS was that we could only get into the building the day before the show and there were also rehearsals taking place at the same time.

So instead of moving sound-sources in the space, simple panorama dial-knobs did the trick of mixing four live and two stereo tape-inputs to the eight speakers and it was quite sufficient to enchant the audience: Video of the Show, alas in bad quality and without the grand finale.

Free software for free drinks, lots of fun and a great show!

Thanks, I won't forget some of those truly amazing looks for quite a while. - Relax Max

Build Instructions

Apart from a C-compiler and gnu-make, you'll need the following prerequisite software development libraries:

  • glibc (libm, pthreads)
  • alsa
  • jack
  • liblo
  • opencv (optinal, only for oscpanctl)
cd /tmp
git clone git://
cd panjack/panjack/
cd ../oscpanctl/


PanJack implements a real-time surround-sound panorama mixer.

  • one or more audio input(s)
  • two or more audio outputs / speakers
  • control via OSC or MIDI.
  • (optional) bcf2000 fader/pan control.

Note: Jack-Transport needs to be rolling in order for panjack to process audio.

It creates jack-audio input and output ports and routes audio with a latency of 1 jack-cycle, applying a amplifications depending on faders and panorama-gain.

The panorama-gain settings can be adjusted manually for each output channel or be modified indirectly using built-in maths for 2D (angle, separation) or X/Y-distance panning. Furthermore there is built-in functionality to automate whirl/leslie-rotate effects.

panjack itself does not provide sequencer capabilities. Yet this feature can be archived easily by controlling panjack via OSC and any OSC-sequencer (eg. ardour LADSPA-osc automation - see below)


Panjack is solely configured via command line parameters:

panjack command line options:

  1. h help
  2. V show version
  3. v enable verbose/debug output
  4. P <num> number of input ports (default 4)
  5. p <num> number of output ports / speakers (default 8)
  6. o <num> OSC UDP-port number to listen to (default: no OSC)
  7. O <string> auto-connect outputs to JACK ports with this prefix
  8. I <string> auto-connect audio input ports to JACK ports with this prefix
  9. c <string> JACK client name (default: “panjack”)
  10. s <string> JACK server name to use

panjack-OSC comandset

OSC commands:

/panjack/xy    float, float       : signal source X, Y
/panjack/setup int, float, float  : speaker number, X-pos [0..1], Y-Pos [0..1]
/panjack/amp   int, float         : channel number, volume [0..1]
/panjack/quit                     : handy during development, possibly disastrous during live performances 

NOTE: The current OSC command only controls the first input channel.

BCF2000 - Fader

panjack uses ALSA-MIDI-Sequencer ports. Simply connect the BCF2000 midi port to panjack (fi. using qjackctl or aconnect). panjack parses (and sends) BFC2000 B-Control (default mode - preset no. 1, Manual) MIDI-CC events. The BCF faders/controls are mapped to the first eight panjack input channels:

  • Button 1: narrow/wide separation (on: sep=1.1, off: sep=7.0)
  • Button 2: toggle auto-rotate mode
  • pan-dial:
    • in auto-rotate: set speed - push: reverse direction
    • no-auto-rotate: set position (angle), auto-skip over 0↔360 deg. - push: enter narrow separation mode: dep on Button 1 sep=5.0, sep=0.0/single speaker only)
  • Fader: linear Volume adjust (0-127%)


Utility to control (send OSC commands to) panjack.

It is written using OpenCV for graphics, mouse, joystick and keyboard interaction and liblo (OSC).

  1. configure speaker position (panjack-matrix) : press key 1-9 to select speaker (red circle), right-click to set speaker position.
  2. (re)position sound source - left click to move the sound-source (yellow cross).
oscpanctl command line options:
 -h        help
 -V        show version
 -v        enable verbose/debug output
 -p <num>  number of output ports / speakers (default 4)
 -o <num>  OSC UDP-port number to send messages to (default: 5280)
 -i <num>  OSC UDP-port number to listen to (default: 49152)

Messages sent to the oscpanctl's OSC input port are processed (update position) and forwarded to the output. This allows to visualize and override automation-data.

oscpanctl reacts to keystrokes : r re-transmit speaker setup, q quit, b bypass/disable OSC transmissions, e enable OSC-TX and the numbers 0-9 to position speakers.

Development Notes

With the soundtrack and choreography changing until the last minute, panjack accordingly changed rapidly so the initially nice and clean code (based on jack-example-client.c) turned into a toolkit.

OscPanCtl was only used at the beginning for prototyping and the OscPanCtl code as well as the matrix.c maths has been somewhat neglected. I bought a Behringer BCF2000 few days before the performance and hooked it up via MIDI instead of OSC. During rehearsals some tracks and panorama settings were automated (ardour automation via OSC to panjack), but in the end we ended up to mixing it all live and resulted in some last minute assign feature to MIDI-event hacks. NTL, it runs stable and panjack worked brilliantly - thanks to JACK, freebob2) and debian gnu/linux - without a single dropout at 256 frames, 4ms latency during the whole two days!

more to come about:

  • Pure-data prototype - uses much more CPU (sqrt, pow for each channel and for each sample) - 60% CPU on a i686 1.6Ghz :(
  • oscpanctl - uses panjack's matrix.c - flexible speaker position-signal distance pragmatic openCV application.
  • Smooth transitions
  • midi - 360 degree dial-knob, circular speaker arrangement.
  • equal power vs. equal volume, speaker/channel separation.
  • Live setup:
    • FA-101 - 8 input channels ; 10 output channels (8 + 2 bass)
    • 4+4 panjack-outputs were combined and low-pass filtered to left+right bass speakers.
  • ardour automation - OSC_in/OSC_out LADSPA Plugins


  • make some compile time options run-time options
    1. smooth fades
    2. equal power vs. equal volume panning
  • optimize realtime-code - use SSE2.
  • dynamic/configurable MIDI ↔ control mapping.
  • update OSC commandset to control all input channels.
  • allow more than nine speakers in oscpanctl → select on 1st click rather than type number.
  • allow a single OscPanCtl instance to handle multiple input channels.
  • make jack-transport (process and exit) as well as osc-quit an option (or remove it).
  • add long-options to help/usage.
  • effect (delay, slap-back) integration
  • announce jack_port_latency
  • use jack-midi instead of ALSA-sequencer
  • OscPanCtl - unhardcode keyboard char map.
  • project
1) JACK: Jack Audio Connection Kit
2) freebob is also known as ffado
oss/panjack/start.txt · Last modified: 23.12.2011 21:26 (external edit)