Zirkonium Spatialization Server

ZKM | Hertz-lab

Dr. Chikashi Miyama 2015-2017 (version 1)
Dan Wilcox 2018-2019 (version 2 update)

Overview

This software is the rendering server for 3D sound spatialization that ZKM | Hertz-Lab employs for its 3D surround audio system, the Klangdom (Sound Dome).

The software is programmed in PureData, an open source visual programming language by Miller Puckette.

This engine is embedded in Zirkonium3, a toolkit for spatial composition and performance, employing libpd.

Dependencies

To open the patch files, you will need Pure Data.

The server uses customized versions of the following spatilization external objects:

• VBAP (Vector-Based Amplitude Panning) by Ville Pukki: http://legacy.spa.aalto.fi/research/cat/vbap/
• HOA (Higher-Order Ambisonics) from the Hoa library by the CICM: http://hoalibrary.mshparisnord.fr/en
• earplug~ realtime binaural filter (used for HRTF modeling) by Pei Xiang: https://puredata.info/downloads/earplug

See the README files in the individual external directories for details.

Build

The source files for the [zirkhoa], [zirkhrtf~], and [zirkvbap] external libraries are included in the externals directory and can be built using the main Makefile or the Makefiles in the individual external directories.

Make sure you have git and a copy of Pure Data installed to your system.

Compile with:

make

Each external will be built and the compiled object and it's help file will be copied into the main directory.

On macOS, the externals are built for multiple architectures by default: 64 bit Intel (x86_64) and Apple Silicon (arm64). To override, set the arch Makefile variables:

make arch="x86_64 i386"

To clean temporary build files but keep the compiled externals:

make clean

To remove the compiled externals:

make clobber

Control Messages

Receiving:

• transport
  • start
  • stop
  • time float (position offset in seconds, 0 start)
  • poll bool (0 or 1, send poll messages on audio blocks?)
  • refresh float (fps, set poll block size based on desired fps)
• samplerate rate
• layout
  • dimension positions (dimension: 2 or 3, forwards to zirk_ids)
    • 2D: 2 azimuth1 azimuth2 ...
    • 3D: 3 azimuth1 elevation1 azimuth2 elevation2 ...
  • transform bool: (0 or 1, apply rotate or flip transforms?)
  • rotate float: (rotate speaker positions in degrees)
  • flip bool: (0 or 1, speaker position vertical flip)
• input (channel 1 - n or "all")
  • channel float (rms gain 0-1)
  • channel db float (db gain -100 - +12)
  • channel gain float (alias for db message)
• sourcefile (id 1 - n or "all")
  • id float (rms gain 0 - 1)
  • id db float (db gain -100 - +12)
  • id gain float (alias for db message)
  • id open filepath
  • id open filepath offset (optional sample offset, see [readsf~])
  • id start (requires "open" message first)
  • id stop
• id (id 1 - n or "all", 0 is test id)
  • id float (rms gain 0 - 2)
  • id db float (db gain -100 - +12)
  • id gain float (alias for db message)
  • id on bool (0 or 1)
  • id input input (zirk_input # or symbol, 0 or "none" disables input)
  • id position x y z (spherical cartesian position, -1 to 1, 0 center)
  • id span span (0 - 1)
  • id mute bool (0 or 1)
  • id muted bool (alias for "mute")
  • id algorithm algo ("VBAP", "vbap", "HOA", or "hoa")
  • id optim optim (HOA optimization: "basic", "maxre", or "inphase")
  • id directoutput output (zirk_speaker # or symbol, 0 or "none" disables output)
  • id directout output (alias for "directoutput")
  • id layout dimension positions (dimension: 2 or 3)
    • 2D: 2 azimuth1 azimuth2 ...
    • 3D: 3 azimuth1 elevation1 azimuth2 elevation2 ...
  • id vbap speed ms (default 25)
  • id hoa speed ms (default 25)
  • id hrtf bool (bypass to HRTF?, 0 or 1)
  • id hrtf speed ms (default 25)
  • id report level bool (0 or 1, output pre-level db?)
  • id report current bool (0 or 1, output current vbap speaker set?)
  • 0 noise float (test sound noise type: 0 - pink, 1 - white)
• speaker (id 1 - n or "all")
  • id float (rms gain 0 - 1)
  • id db float (db gain -100 - +12)
  • id gain float (alias for db message)
  • id on bool (enable DSP, 0 or 1)
  • id delay float (delay time in ms)
  • id phase bool (invert audio phase?, 0 or 1)
  • id output output (zirk_output # or symbol)
  • id record open filepath
  • id record open -bytes 3 filepath (forces 24 bit output, see [writesf~])
  • id record start (requires "open" message first)
  • id record stop
  • id report level bool (0 or 1)
• output (channel 1 - n or "all")
  • channel float (rms gain 0 - 1)
  • channel db float (-100 - +12)
  • channel gain float (alias for "db" message)
• hrtf (stereo output)
  • float (rms gain 0 - 1)
  • db float (-100 - +12)
  • gain float (alias for "db" message)
  • on bool (0 or 1, forwards to all zirk_ids)
  • output 1 channel (hardware output # for left, default 1)
  • output 2 channel (hardware output # for right, default 2)
  • record open filepath
  • record start (requires "open" message first)
  • record stop
  • report level bool (0 or 1)

Sending:

• poll
• time time in seconds
• level
  • id id float (db -100 to +12)
  • speaker id float (db -100 to +12)
• vbap
  • set (speaker layout set)
    • 2D pair: set speaker1 speaker2
    • 3D triplet: set speaker1 speaker2 speaker3
  • current id set (current speaker set)

Messaging

• #zirk-in: server receive (input)
• #zirk-out: server send (ouput)
• audio signals:
  • zirk_input#: hardware input channel, ie. zirk_input1, zirk_input2, ...
  • zirk_sf#-#: sourcefile & audio channel, ie. zirk_sf1-1, zirk_sf1-2, zirk_sf2-4, ...
  • zirk_speaker#: virtual speaker, ie. zirk_speaker1, zirk_speaker2, ...
  • zirk_output#: hardware output channel, ie. zirk_output1, zirk_output2, ...
  • zirk_hrtf1 & zirk_hrtf2: hrtf hardware output channels (left & right)

Contribution

If you find a bug, please file it as an issue.