MUZUNGUMASCHIN — User Manual

Version: Early Access 0.9 Format: VST3 / AU Platform: Windows 10/11, macOS 11+

[Concept and Philosophy](#1-concept-and-philosophy)
[Installation](#2-installation)
[User Interface — Overview](#3-user-interface--overview)
[Title Bar](#4-title-bar)
[Panel 1 — Polygon Display](#5-panel-1--polygon-display)
[Polygon Canvas](#6-polygon-canvas)
[Mode Row](#7-mode-row)
[Layer Strip](#8-layer-strip)
[Panel 3 — Inspector](#9-panel-3--inspector)
[Step Sequencer](#10-step-sequencer)
[Patch Editor](#11-patch-editor)
[MIDI Routing](#12-midi-routing)
[INFO Mode](#13-info-mode)
[Tips and Workflow](#14-tips-and-workflow)
[Glossary](#15-glossary)

1. Concept and Philosophy

MUZUNGUMASCHIN is built on a physical thesis:

Rhythm and harmony are the same phenomenon — at different time scales.

A triangle on the time circle creates a triplet rhythm. The same triangle on the pitch circle creates an augmented triad. Speed up a 3:2 polyrhythm far enough and it becomes a perfect fifth (702 cents).

Each layer in MUZUNGUMASCHIN is a polygon: its corners (vertices) are notes, distributed evenly or unevenly around a circle. A rotating line triggers notes as it passes each vertex.

The Four Approaches

Mode	Description
POLYRHYTHM	All 8 layers share one cycle. A layer with 3 vertices fires 3×, a layer with 7 fires 7× per cycle.
POLYMETER	Each layer has its own 16th-note grid. Euclidean patterns (K pulses in N steps).
Polygon Mapping	Polygon shape → chord type (triangle = augmented, square = dim7, etc.)
Euclidean	Bjorklund algorithm: K pulses distributed evenly across N steps.

2. Installation

Windows (VST3)

Copy MuzunguMaschin.vst3 to your VST3 folder:

- Default: C:\Program Files\Common Files\VST3\ - Reaper: Any folder registered in Reaper preferences

Restart DAW → search for "MUZUNGUMASCHIN"
Load as a MIDI effect on an instrument track (or MIDI bus)

macOS (AU / VST3)

AU: ~/Library/Audio/Plug-Ins/Components/
VST3: ~/Library/Audio/Plug-Ins/VST3/

MIDI Routing

MUZUNGUMASCHIN is a MIDI generator: it sends MIDI notes to the host DAW. Notes must be routed to an instrument. In Reaper: plugin on a track → MIDI output routed to instrument on another track.

3. User Interface — Overview

┌─────────────────────────────────────────────────────────────────────┐
│  [MZ]  MUZUNGUMASCHIN   [FILE] [INFO] [⚙] [↩]   [PATCHEDIT]  ...  │  ← Title Bar (56px)
├──────────────────────────────────┬────────────────┬─────────────────┤
│                                  │                │                 │
│        PANEL 1                   │    PANEL 2     │    PANEL 3      │
│   (Polygon Display)              │  (2nd Display  │  (Inspector /   │
│                                  │   optional)    │   PATCH)        │
│   [Polygon Canvas]               │                │                 │
│                                  │                │                 │
│   [Mode Row]                     │                │                 │
│   [Layer Strip: 8 cards]         │                │                 │
├──────────────────────────────────┴────────────────┴─────────────────┤
│  ● SYNC  BPM 120.0  4/4  1:1:000                        ▶ PLAY      │  ← Footer
└─────────────────────────────────────────────────────────────────────┘

The three panels are separated by draggable dividers that can be freely resized.

4. Title Bar

[MZ-Logo]  MUZUNGUMASCHIN  [FILE] [INFO] [⚙] [↩]  [PATCHEDIT]   [½][1×][2×][M]  [CTRL][SEQ]

Element	Function
MZ Logo	Hexagon logo
FILE	Load/save patch, default preset, export
INFO	Toggle hover help (blue underline when active)
⚙	Settings
↩	Undo
PATCHEDIT	Edit node graph (only when DAW is stopped)
½ / 1× / 2×	Cycle length: ½ bar, 1 bar (default), 2 bars
M	Custom cycle length (e.g. 3:4 or 1.5)
CTRL	Controller automation curve editor
SEQ	Open step sequencer window

Cycle Length

The cycle determines how long the rotating line takes for one full revolution:

½: Half bar → line rotates 2× per bar
1×: One bar (default, recommended for 4/4)
2×: Two bars → line rotates once every 2 bars
M: Custom ratio — e.g. 3:4 = three quarter notes, 1.5 = one and a half bars

The cycle length is calculated from the DAW time signature: in 6/8, one bar = 3 PPQ.

5. Panel 1 — Polygon Display

The main panel consists of three areas from top to bottom:

┌─────────────────────────────────────┐
│  [Node Header]  Name  CLONE  SLAVE  │  ← Header (28px)
├─────────────────────────────────────┤
│                                     │
│         [Polygon Canvas]            │  ← Visualization
│                                     │
├─────────────────────────────────────┤
│  [POLYRHYTHM] [POLYMETER]           │  ← Mode Row (72px)
│  SWING  SCAT  VEL  GATE  PROB  RSD  │
├─────────────────────────────────────┤
│  [1][2][3][4][5][6][7][8]           │  ← Layer Strip (140px)
└─────────────────────────────────────┘

6. Polygon Canvas

The canvas shows 8 concentric rings. Each ring corresponds to one layer.

         ·  ·  ·
      ·           ·
    ·     Layer 1   ·      ← Ring 1 (inner)
   ·   △ (Triangle)  ·
    ·               ·      ← Rotating line
      ·           ·           starts at 12 o'clock
         ·  ·  ·

Elements

Element	Description
Rings	8 concentric circles = 8 layers
Polygon corners (vertices)	Note positions — colored dots on the ring
Polygon edges	Lines connecting active vertices
Rotating line	Moves clockwise, one revolution = one cycle
Vertex glow	Brief flash on note-on
Small dots	Rest positions (inactive steps in Euclidean pattern)

Mouse Interaction

Action	Function
Left-click on empty spot	Add new vertex
Left-click on vertex	Select vertex
Drag on vertex	Move vertex (change phase)
Double-click on vertex	Delete vertex
Right-click on vertex	Context menu (note, velocity, gate...)
Scroll	Zoom canvas
Drag on ring	Select layer

CTRL Mode (Curve Editor)

When CTRL is active, the canvas shows a curve editor instead of polygon corners:

Drag control points to move them
Double-click on curve = add point
Double-click on point = remove point
∞ button in the side strip = Seamless Loop (curve interpolates smoothly from end to beginning)

7. Mode Row

[POLYRHYTHM ●] [POLYMETER]    SWING ○   SCAT ○   VEL ○   GATE ○   PROB ○   [RSD]

POLYRHYTHM / POLYMETER

Mode	Description
POLYRHYTHM	All layers share one cycle. A layer with N vertices fires exactly N× per cycle. Rhythmic ratios emerge directly from geometry.
POLYMETER	Each layer has its own 16th-note subdivision. The Euclidean algorithm distributes K pulses across N steps evenly.

Scatter Knobs

All scatter knobs have two functions:

Rotate: Set scatter intensity (0 = no effect)
Click without dragging: New random sequence (reseed)

Knob	Color	Function
SCAT	Green	Position scatter: shift vertices around their base position
VEL	Orange	Velocity scatter: each note gets a different attack strength
GATE	Purple	Gate scatter: each note gets a different duration
PROB	Cyan	Probability scatter: each note has a different trigger probability

RSD — Pattern Reseed

Generates a new random Euclidean pattern for the active layer (keeps K/N ratio).

SWING

Delays even beats (0 = no swing, 1 = maximum shuffle).

8. Layer Strip

The layer strip shows all 8 layers as cards. The active layer has an orange border.

┌──────┐ ┌──────┐ ┌──────┐ ... ┌──────┐
│  1   │ │  2   │ │  3   │     │  8   │
│ [M][S│ │ [M][S│ │ [M][S│     │ [M][S│
│ N-·N+│ │ N-·N+│ │ N-·N+│     │ N-·N+│
│ K-·K+│ │ K-·K+│ │ K-·K+│     │ K-·K+│
│ REP○ │ │ REP○ │ │ REP○ │     │ REP○ │
└──────┘ └──────┘ └──────┘     └──────┘

Element	Function
Number / Name	Layer number or custom name
M	Mute — silence the layer
S	Solo — hear only this layer (right-click = clear all solos)
N− / N+	Remove / add vertices (1 to 16)
K− / K+	Remove / add pulses (Euclidean, 0 to N)
REP	Repulsor strength: vertices repel each other → more even distribution

Rename Layer

Double-click on a layer card opens a text input. The name replaces the number.

Layer Color

Right-click on a layer card opens a context menu with 16 color choices.

9. Panel 3 — Inspector

The inspector shows parameters for the currently selected vertex or layer.

Vertex Parameters

Parameter	Description
Phase	Position on the ring (0.0–1.0, corresponding to 0°–360°)
Note	MIDI note (0–127, default = layer note)
Velocity	Attack strength (0–127, 0 = layer default)
Gate	Duration as fraction of step length (0.0–2.0)
Probability	Trigger probability (0.0–1.0)
Jitter	Random timing deviation in phase units
Nudge	Fixed timing offset (forward/backward)
Active	Enable/disable vertex

Layer Parameters (no vertex selected)

Parameter	Description
Steps (N)	Number of vertices
Pulses (K)	Number of active vertices (Euclidean)
Velocity	Default attack strength for all vertices
Gate	Default duration
Note	Base MIDI note
MIDI Channel	Channel 1–16
Rotation (ROT)	Overall polygon rotation (phase offset)
Euclidean Rotation (EUC)	Cyclic rotation of the Euclidean mask (POLYMETER): same E(K,N) shape, different starting offset. Son Clave / Rumba Clave / Bossa Nova are rotations of each other.
SNAP TO BALANCE	Button: moves active vertex phases via gradient descent until the polygon's centroid hits the center (perfectly balanced). First active vertex stays as anchor.
MOS Generator (g)	Generator value [0..1] for Well-Formed scales. Iterating `(i·g) mod 1` and sorting produces an MOS polygon with at most two step sizes (Myhill property). Default `g = log₂(3/2) ≈ 0.585` (perfect fifth) → diatonic family.
L:s Ratio (r)	Morphs the long-vs-short step ratio of the MOS polygon without changing the L/s pattern. `r = 1` → equal-step (regular polygon). Higher `r` → MOS unevenness increases. (XronoMorph's r-slider concept.)
GEN MOS	Button: regenerate vertex positions using current N, g, and r. Pattern label shows the L/s structure (e.g. "5L + 2s" for diatonic, "2L + 3s" for pentatonic).

Balance Visualization

When a layer is selected, the polygon canvas shows the layer's balance vector as an arrow from the center: B = Σ exp(2πi·φ_k) over active vertices. The magnitude |B|/K is shown as a 0..1 score next to the arrow. When the polygon is perfectly balanced (|B| ≈ 0), the arrow disappears and a BALANCED badge lights up at the center in the layer's color.

Balance is the principle behind many ethnomusicologically beautiful rhythms (bell patterns, son clave, aksak): not perfectly even (boring), not random (formless), but in equilibrium. See Milne, Bulger, Herff & Sethares (2015), "Perfect Balance: A Novel Principle for the Construction of Musical Scales and Meters."

MOS / Well-Formed Scales (Carey & Clampitt 1989)

A scale is well-formed (or "MOS" — Moment of Symmetry, Erv Wilson) when it is generated by iterating a single interval g modulo the period and the result has exactly two distinct step sizes (the Myhill property). Examples:

Configuration	Pattern	Name
N=5, g=0.585	2L + 3s	Pentatonic
N=7, g=0.585	5L + 2s	Diatonic
N=12, g=0.585	5L + 7s	Chromatic
N=13, g=0.789	various	Bohlen-Pierce family

The same construction works for rhythms — Aksak (Balkan), sub-Saharan African additive meters are MOS rhythms with L=3, s=2.

10. Step Sequencer

Open via the SEQ button in the title bar. Opens in its own free-floating window.

     [Position][Velocity][Gate][Probability][Jitter][Nudge][CTRL]   ← Tab bar
     ┌──────────────────────────────────────────────────────────────┐
L 1  │ SN │ DAW │ POLY │ 1/16 │ Q │     Layer Name    │            │
     ├────┴─────┴──────┴──────┴───┴──────────────────────────────── ┤
     │  ▓  ▓  ░  ▓  ░  ░  ▓  ░  ▓  ▓  ░  ░  ▓  ░  ░  ░   ← Notes │
     ├──────────────────────────────────────────────────────────────┤
L 2  │ SN │ DAW │ POLY │ 1/8  │ Q │     Layer Name    │            │
     ├──────────────────────────────────────────────────────────────┤
     │  ▓  ░  ▓  ░  ▓  ░  ▓  ░                                     │
     └──────────────────────────────────────────────────────────────┘

Tab Bar

Tab	Grid Display
Position	Vertex phase positions (horizontal line)
Velocity	Attack strengths as bars
Gate	Gate lengths as bars
Probability	Trigger probabilities as bars
Jitter	Timing scatter as bars
Nudge	Timing offset (center = 0)
CTRL	Controller curves

Side Strip (per layer)

Button	Function
SN	Snap: vertices snap to grid divisions when dragging
∞ (CTRL tab)	Seamless Loop: curve interpolates smoothly from end to start
DAW	Grid mode: DAW grid (1/16, 1/8, 1/4, etc.)
POLY	Grid mode: polygonal grid (N × subdivision)
1/16 (DAW)	Select grid division
Q	Quantize: snap all vertices to nearest grid division
÷N (POLY)	Display subdivision count
−/+ (POLY)	Decrease/increase subdivision

Grid Interaction

Action	Function
Left-click on empty spot	Add vertex
Drag on vertex	Move vertex (change phase)
Drag on value bar	Change value (velocity/gate/prob etc.)
Double-click on vertex	Delete vertex
Scroll	Zoom (horizontal)
Shift + Scroll	Scroll

11. Patch Editor

Open via the PATCHEDIT button (only when DAW is stopped).

The patch editor shows the node graph: nodes are connected with Bezier cables.

Node Types

Category	Nodes
Generator	PolygonNode (main sequencer)
MIDI	MIDI Out, MIDI In, MIDI Merge, MIDI Split, MIDI Filter, MIDI Monitor
Transform	Transpose, Velocity Map, Math, Mixer
Controller	LFO, Envelope, Sample & Hold, Quantize, Random
Converter	MIDI↔Controller, Pulse↔Controller, Rhythm↔MIDI
FUNK!	Funk Send, Funk Receive, Funk Bind
DAW	DAW Param Out (automatable parameter in DAW)

Adding Nodes

⊕ ADD NODE menu bar → select category
Right-click in canvas → context menu

Connections

Drag from an output port to an input port → cable
Click on cable → delete
Port colors: Orange = Rhythm, Yellow = Pulse, Cyan = Harmony, Green = Controller, White = MIDI

12. MIDI Routing

In Reaper

Load plugin on an empty track (no instrument needed)
Track MIDI output → route to instrument track
In the plugin: each layer sends on its own MIDI channel (default: layer 1 = channel 1)

MIDI Channels

Each of the 8 layers has its own MIDI channel (configurable in the Inspector). This allows different instruments to be played from a single plugin.

DAW PARAM OUT

The DawParamOutNode exports internal values as automatable DAW parameters. These appear in Reaper under "Parameters" and can be controlled with automation curves.

13. INFO Mode

Click INFO in the title bar to activate hover help mode (blue underline appears).

In INFO mode, hovering over any control shows a tooltip with a detailed description. The tooltip follows the mouse cursor.

Deactivate INFO: click INFO again.

14. Tips and Workflow

Getting Started: First Sound in 2 Minutes

Load plugin, start DAW (press Play)
In the layer strip: Layer 1 is active by default (3 vertices = triplet)
Route MIDI to an instrument → hear the first notes
Press N+ → add a vertex → rhythm changes
Activate second layer (click Layer 2 in layer strip) → set N to a different number → polyrhythm!

Polyrhythm Basics

Set Layer 1 to N=3 and Layer 2 to N=4 → 3-against-4 polyrhythm. Both complete one cycle, but at different speeds within the cycle.

Creating Euclidean Patterns

Switch to POLYMETER mode
Select a layer, set N to e.g. 16
Set K to e.g. 5 → 5-in-16 Euclidean pattern (similar to Shiko)

Adding Life with Scatter

Turn up the VEL knob slightly → each note gets a slightly different attack
GATE knob → varies note length
Click a scatter knob → new random sequence at same scatter intensity

Swing

SWING knob at 0.5–0.7 → classic shuffle. Works in both modes.

Rhythm-Harmony Connection

Layer with 3 vertices (equidistant) = pure triplet rhythm → same triangle on pitch circle = augmented triad
7 vertices = 7-against-1 rhythm → same heptagon on pitch circle approaches a Pythagorean scale
This is the core of MUZUNGUMASCHIN: speed up the rhythm → hear the harmony

15. Glossary

Term	Meaning
Vertex	A point on the polygon ring = one note in the sequencer
Phase	Position on the ring (0.0 = 12 o'clock, 0.5 = 6 o'clock, 1.0 = 12 o'clock)
Cycle	One complete revolution of the rotating line
Euclidean	Bjorklund algorithm: K pulses evenly distributed across N steps
Gate	Note duration (1.0 = full step duration)
Probability	Chance that a note is triggered (1.0 = always)
Jitter	Random timing deviation around the note position
Nudge	Fixed timing offset (positive = forward, negative = backward)
Repulsor	Repulsion force between vertices → more even distribution
FUNK!	Wireless modulation system: streams from one node to another
PPQ	Pulses Per Quarter Note — DAW internal time unit
Scatter	Random variation of a parameter (velocity, gate, prob, position)
Reseed	Generate new random sequence at the same scatter value

MUZUNGUMASCHIN Early Access — Feedback: ohrbyte@gmail.com