# MugicSpatCon

Control spatialized audio live using the [IEM Plugin Suite](https://plugins.iem.at/), Korg NanoKontrol2, and [Mugic](https://mugicmotion.com/). Written in SuperCollider.

![Screenshot of MugicSpatCon's inflight interface](./ignore/img/screenshot-inflight.png)

## Contents

- [Description](#description)
- [Installation](#installation)
	- [Prerequisites](#prerequisites)
	- [Installing and updating MugicSpatCon](#installing-and-updating-mugicspatcon)
- [Starting MugicSpatCon](#starting-mugicspatcon)
- [Configuration](#configuration)
- [Usage](#usage)
	- [Chaotic repositioning algorithms](#chaotic-repositioning-algorithms)
- [Planned features](#planned-features)
- [Known issues](#known-issues)

## Description

MugicSpatCon is a SuperCollider extension that allows the user to control the spatialization of four mono audio streams in real-time using the Mugic Motion and Korg NanoKontrol2 controllers. Spatialization is done via the [IEM Plugin Suite](https://plugins.iem.at/) and can be configured to any number of outputs supported by the plugins, including binaural, quadrophonic, and octophonic. Mugic is used in a simple analog to the ambisonic position: turn Mugic clockwise and the position moves clockwise.

Each stream can be manually repositioned independently or in a group selection. Each stream also has its own gesture recording and playback which can be looped (in standard or pingpong mode) and its speed manipulated (from 1/4 speed to 4x). Gesture playback and manual position are summed, so a looping gesture can be moved around ambisonic space.

## Installation

### Prerequisites

MugicSpatCon uses the following software, which must be installed and configured on your system:

- [SuperCollider](https://supercollider.github.io/)
- [sc3-plugins](https://supercollider.github.io/sc3-plugins/)
- [VSTPlugin SuperCollider extension](https://git.iem.at/pd/vstplugin)
	- Download relevant release from [https://git.iem.at/pd/vstplugin/-/releases](https://git.iem.at/pd/vstplugin/-/releases)
	- Extract it and move the inner folder to `Platform.userExtensionDir`
		- (Typically `~/Library/Application Support/SuperCollider/Extensions/` on macOS and `~/.local/share/SuperCollider/Extensions/` on Linux)
- [IEM ambisonic plugin suite](https://plugins.iem.at/)

### Installing and updating MugicSpatCon

MugicSpatCon is available as a [Quark](https://doc.sccode.org/Guides/UsingQuarks.html) and can be installed, updated, and removed through the SuperCollider IDE via the `Language > Quarks` menu (search for `mugic-spat-con`). Make sure the above [dependencies](#prerequisites) are installed _before_ installing MugicSpatCon.

_Notes:_

* _Due to a [bug](https://github.com/supercollider/supercollider/issues/6589) in SuperCollider, the Quarks GUI window must be closed and re-opened after checking for updates._
* _The Quarks registry is being updated. In the meantime, run `Quarks.install("https://gitlab.com/daveriedstra/mugic-spat-con");` then `Language > Recompile Class Library`._

## Starting MugicSpatCon

- Open SuperCollider
- In the main editor window, type `MugicSpatCon().gui`
- Run the code by pressing `<Cmd / Ctrl> + <Enter>`

_(Save this code as a file for easy future access.)_

## Configuration

- **Mugic:**
    - Ensure the computer and Mugic are on the same WiFi network (either by connecting the computer to the network that Mugic creates by default or by connecting Mugic to the network that the computer is connected to).
    - Mugic can be configured through the MUGIC desktop app.
    - MugicSpatCon does not support USB connection to Mugic.
    - For more information, see [mugicmotion.com](https://www.mugicmotion.com/support/getting-started).
- **NanoKontrol2:**
    - MugicSpatCon will connect to the NanoKontrol2 MIDI inputs & outputs.
    - If necessary, set the NanoKontrol2 to CC mode by holding **SET**, **MARKER**, and **CYCLE** when connecting it to the computer.
- **Audio:**
    - Select the desired input and output devices from the MugicSpatCon pre-flight configuration menu.
    - To route audio from other apps (eg, a DAW or synthesis environment), use software such as [BlackHole](https://existential.audio/blackhole/). Choose BlackHole as the output device for the audio-generating software and as the input device in MugicSpatCon.
    - MugicSpatCon uses audio channels starting from 0.
    - MugicSpatCon uses two channels per input track. Inputs can be configured as mono or stereo when MugicSpatCon has started.
    - Linux users should manage the audio connections through JACK or PipeWire.
- **Speaker layout:**
    - For 2-channel output, a [binaural decoder](https://plugins.iem.at/docs/plugindescriptions/#binauraldecoder) is used.
    - Otherwise, the speaker layout is managed by the [IEM AllRADecoder VST](https://plugins.iem.at/docs/allradecoder/) (loaded once audio processing has started).
    - A [loudspeaker layout creation reference](loudspeaker-layout-creation-reference.md) is provided.
    - Default VST presets are supplied for **4, 8, and 16 channels** (eg `allradecoder-4-single.fxp`).
    - MugicSpatCon will remember each speaker layout configuration according to the number of channels.
    - Speaker layouts can be saved and loaded from the AllRADecoder VST.

![Screenshot of MugicSpatCon's preflight interface](./ignore/img/screenshot-preflight.png)

Press `Start` to start the ambisonic audio processing. Values set in the pre-flight configuration menu are remembered between sessions.

## Usage

![Screenshot of MugicSpatCon's inflight interface](./ignore/img/screenshot-inflight.png)

**VST GUI**: Each track is encoded via a [StereoEncoder VST](https://plugins.iem.at/docs/plugindescriptions/#stereoencoder) controlled by MugicSpatCon. Click `VST GUI` to show the VST for a single track, or `Show track VSTs` to open all of them.

**Label**: To the left of the `VST GUI` button is a scribble strip to label the track.

**Stereo input:** By default, only the left channel of the input is used. Check this box to use both channels and enable the Z-axis (roll) control.

**Controller axes**: These checkboxes selectively invert or ignore the movement data coming from Mugic on a given axis, per track.

**Channel strips**: Each track uses two of NanoKontrol2's channel strips, as represented in the GUI.

- The **knobs** control the track's [chaotic repositioning algorithm](#chaotic-repositioning-algorigthms). The left knob controls the range of movement and the right controls the rate. (Zero out the `range` knob to deactivate.)
- The **left slider and its buttons** are reserved for manual controls. The `S` / `M` / `R` buttons control [s]olo, [m]ute, and [r]epositioning, and the slider controls the channel's volume.
- The **right slider and its buttons** control the gesture recording and looping. The `S` / `M` / `R` buttons control [s]tart / [s]top of the loop playback, pingpong / [m]irror [m]ode, and [r]ecording of the gesture, and the slider controls the playback speed (1/4x to 4x). Right-click on the slider to return gesture playback rate to 1.

**Position data**: Below each channel strip is data about that channel's ambisonic position. Its **manual position** is given in degrees along the horizontal and vertical axes (not including the gesture loop positioning). The **gesture loop** duration in seconds is given above a knob representing the progress through the loop.

### Chaotic repositioning algorithms

MugicSpatCon offers a selection of repositioning algorithms, many of which are straightforward applications of SuperCollider classes:

- **White Noise:** Smoothed random repositioning using the [LFNoise2](https://doc.sccode.org/Classes/LFNoise2.html) UGen.
	- _NB: tends to stay near edges of range at very low rates._
- **Brownian Movement:** Smoothed brownian motion (random walk) using the [LFBrownNoise2](https://doc.sccode.org/Classes/LFBrownNoise2.html) Ugen.
	- _NB: tends to stay near edges of range at very low rates._
- **Lorenz Attractors:** Smooth strange attractor movement using the [LorenzL](https://doc.sccode.org/Classes/LorenzL.html) UGen (with random seeds and initial positions).
- **Feedback Sine:** Movement following sinusoidal feedback using the [FBSineC](https://doc.sccode.org/Classes/FBSineC.html) UGen (with random initial phase).
- **Onset (Coyote):** Random movement when onsets in the track's input audio are detected. Uses the [Coyote](https://doc.sccode.org/Classes/Coyote.html) UGen. With this algorithm, the rate input behaves like a sensitivity control. There is no smoothing on the position changes.

## Planned features

- Audio recording in ambisonic format

## Known issues

- _Linux only:_ Closing the AllRADecoder VST window crashes the plugin.
- _Linux only:_ Default four, eight, and sixteen channel AllRADecoder configurations are loaded with the incorrect ambisonic order.

_If you find any issues, please reach out or file a bug. Thanks!_
