Setup Guide

Install KAOS

Up and running in under 5 minutes. Everything stays inside the KAOS folder — nothing installed system-wide.

Installation Steps

Download and unzip

Download KAOS.zip from this page. Unzip it — you'll get a KAOS folder.

Right-click → Open

Inside the KAOS folder, right-click KAOS.command and choose Open. This is required the first time only to clear macOS's Gatekeeper warning. A terminal window will open.

First-run setup (~2 minutes, automatic)

The installer will:

Install Python 3.11 via Homebrew (if not already present)
Create a self-contained Python environment inside the KAOS folder
Install all dependencies (Flask, MediaPipe, OpenCV, MIDO)
Download the hand landmark model (~7.5MB)

Everything stays inside the KAOS folder — nothing is installed system-wide.

Enable the IAC Driver (one-time)

When prompted, Audio MIDI Setup will open automatically. Follow these steps:

Go to Window → Show MIDI Studio
Double-click IAC Driver
Check Device is online
Confirm Bus 1 exists → click Apply → close

This creates the virtual MIDI port that KAOS uses to send CC to your DAW.

Open your browser

KAOS opens automatically at http://127.0.0.1:5050 — the control dashboard. Keep the terminal window open in the background (it's the server).

Position your webcam

Mount your webcam above your keyboard pointing straight down, approximately 40–60cm above the keys. Your whole hand should be visible in the camera preview.

Calibrate

Hold your hand in its natural resting position and click Set MIN. Then raise it to its highest playing position and click Set MAX. The green calibration bar confirms you're mapped to the full 0–127 range.

Connect your DAW

Logic Pro: set a MIDI track's input to IAC Driver Bus 1. Ableton: Preferences → MIDI → enable IAC Driver Bus 1 as a control input. KAOS will now send MIDI CC to any parameter you assign it to.

After first run

Double-clicking KAOS.command from then on launches instantly — no install step, no waiting.

To quit: click Mute in the dashboard and close the terminal, or double-click Quit KAOS.command.

Troubleshooting

Problem	Fix
"KAOS.command cannot be opened"	Right-click → Open instead of double-clicking
Homebrew not found	Install Homebrew first at brew.sh, then run `KAOS.command` again
No MIDI in DAW	Check IAC Driver is set to Device is online in Audio MIDI Setup
Camera not detected	System Settings → Privacy → Camera → enable Terminal
Port 5050 already in use	Quit any previous KAOS instance, or double-click `Quit KAOS.command`