Zirkonium 3.4.

5
===============

ZKM | Hertz-Lab 2015-2019

System Requirements: macOS 10.10 (Yosemite) or higher

Install: simply drag this folder into Applications

Main Contents
-------------

* Zirkonium3:
- sound spatialization server
- trajectory editor
- event sequencer

* SpeakerSetup: tool to create speaker setup files

* ZirkVideoPlayer: video playback tool

- sync to Zirkonium3 using OSC (Open Sound Control)
- sync to MIDI Clock or Time Code

Syncing
-------

### MIDI

The Zirkonium3 playback transport can be synced to external software or MIDI

devices which send MIDI Time Code (MTC) or Clock messages:

1. In Zirkonium3: File -> Project Settings -> Sync Settings

A. choose MIDI Time Code or MIDI Clock
B. set MTC offset depending on the software or device (ex: Logic +1 hour)
2. In external software:
A. enable sending MIDI Time Code or MIDI Clock
B. enable sending to the "Zirkonium3" virtual MIDI port (steps may vary)
3. For external hardware or software which cannot send to virtual ports:
A. Connect MIDI ports using the macOS Audio MIDI Setup application, the IAC
Driver dummy interface can be used as a "go between" if needed
B. Connect MIDI ports using 3rd party software such as MIDI Patchbay

### OSC

Zirkonium3 playback can be synced via OSC (Open Sound Control) messages.
Additionally, external software can also control the position of IDs in real
time.

From other (possibly custom) software to Zirkonium3:

1. Enable the OSC Receiver in Preferences and configure your software to send to
the current port.
2. Send OSC control messages conforming to the message specification as outlined
in Preferences -> Network -> OSC Receiver.

ZirkPad
-------

The companion ZirkPad control application is also available for iOS devices:
 https://itunes.apple.com/mk/app/zirkpad/id1125327605?mt=8

Connect the computer running Zirkonium3 and the iOS device:

1. Connect the computer and the iOS device to the same WiFi network
2. Open ZirkPad on the iOS device
2. In Zirkonium3:
A. Preferences -> Network -> OSC Receiver: Enable
B. Preferences -> Network -> OSC Senders: add a new sender with the IP address
and port (default 50001) displayed by ZirkPad (if not one already), also
enable ZirkPad message sending for live ID & speaker levels
C. Project Network settings -> ZirkPad: Press Initialize
3. Repeat step 2C when opening a new project in Zirkonium3

After initialization, ZirkPad should display the current Zirkonium IDs and
speaker layout. Initialize again in order to update ZirkPad if you make changes
to the project in Zirkonium3 on the computer.

Drag the ID and Group positions and pinch/zoom to adjust the span.

Recording Trajectories
----------------------

Zirkonium3 can record live mouse movements & OSC position messages into event
trajectory paths.

### Mouse Movements

In Zirkonium3:

1. Select the IDs and/or Groups you want to record in the ID and Group tables.
2. Turn on the Record button and start Zirkonium3 playback.
3. Click and drag on the Dome View to create paths.
4. Stop Zirkonium3 playback and events will be created from the recorded paths
for each ID or Group.

### OSC

From ZirkPad to Zirkonium3:

1. Once ZirkPad is connected and initialized, turn on the Record button.

2. Start Zirkonium3 playback and move IDs on ZirkPad. Live paths will be drawn
on the dome view.
3. Stop Zirkonium3 playback and events will be created from the recorded paths
for each ID or Group.

From other (possibly custom) software to Zirkonium3:

1. Enable the OSC Receiver in Preferences and configure your software to send to
the current port.
2. Turn on the Record button and start Zirkonium3 playback.
3. Send ID or Group /start, /pan, and /end messages sets:
/start/xy iff ID x y ... start recording ID path at pos, -1 to 1
/pan/xy iff ID x y ... move ID to pos, -1 to 1
/end/xy iff ID x y ... stop recording ID path at pos, -1 to 1
/group/pan/xy sff name x y ... start recording Group path at pos, -1 to 1
/group/start/xy sff name x y ... move Group to pos, -1 to 1
/group/end/xy sff name x y ... stop recording Group path at pos, -1 to 1
4. Stop Zirkonium3 playback and events will be created from the recorded paths
for each ID or Group.

Note: Recording currently uses cartesian positions only, range -1 to 1, and span
is dropped. ID indices are 1 to n and Group names are their respective label
strings, ie "Group-1".

A message set for a single event trajectory would look like this:

/start/xy 1 0 0
/pan/xy 1 0.2 0.2
/pan/xy 1 0.5 0.2
/pan/xy 1 0.3 0.5
/pan/xy 1 0.6 0.8
/end/xy 1 0.1 0.7

Zirkonium3 also automatically splits events based on the recorded timestamps, so

you can also start a trajectory and simply send pan movements. Any long pauses
between movements will separate the trajectories into their respective events
over time.

Syncing ZirkVideoPlayer
-----------------------

To sync the playback transport in Zirkonium3 to ZirkVideoPlayer using OSC:

1. In ZirkVideoPlayer: Preferences -> Control -> OSC and enable OSC

2. In Zirkonium3: Preferences -> Network -> OSC Senders
A. add a new sender with the IP address (127.0.0.1 for same computer) and port
(default 50001) used by ZirkVideoPlayer
B. check the sender's Transport column in the table to enable message sending

Known Issues
------------

* The Dome, Motion, & Event Views are not rendered at full resolution on
high-DPI "retina" screens
* HRTF mode is CPU intensive with many IDs, try increasing the audio buffer
size if there are noticeable stutters
* The PDF manual has not been updated for Zirkonium 3.4
* The SpeakerSetup tool can set negative speaker elevations, however
Zirkonium3's VBAP algorithm does not currently support this

### No Audio Input

macOS 10.14 introduced privacy controls for applications uses microphone input.
Make sure Zirkonium3 has been granted access to the microphone:

1. Goto System Preferences -> Security & Privacy -> Privacy

2. Select Microphone and check Zirkonium3

If Zirkonium3 is not listed, you may need to re-run it to trigger the Privacy
popup. If this does not work, you can reset the Microphone access settings using
a command in the Terminal application:

tccutil reset Microphone

Restart Zirkonium3 and the Privacy popup should appear. Click Ok.
Bug Reports & Mailing List
--------------------------

Join the zirkonium-list mailing list for information on new releases, support,
and general discussion. Sign up via:

http://mailer.zkm.de/mailman/listinfo/zirkonium-list

Once a member, send emails and bug reports to: zirkonium-list@zkm.de

### Debug Output

When sending a bug report, it is often helpful to include any errors Zirkonium3
prints to the console, especially if there is a crash. Run Zirkonium3 by
invoking the application executable within the macOS app bundle. This will also
launch a Terminal window which shows Zirkonium3's console output:

1. In Finder:
A. Right-click on Zirkonium3.app
B. Choose "Show Package Contents"
C. Navigate to Contents/MacOS and double-click Zirkonium3
2. In Terminal, run the executable directly:

/path/to/Zirkonium3.app/Contents/MacOS/Zirkonium3