README.md

---
title: Theremini
emoji: 🎛️
colorFrom: purple
colorTo: indigo
sdk: static
pinned: false
short_description: Play Reachy Mini like a theremin.
tags:
 - reachy_mini
 - reachy_mini_python_app
 - music
 - theremin
---

## Overview

Theremini turns Reachy Mini into a music instrument. The robot's head roll sets the pitch, head vertical translation maps to the amplitude, and the right antenna selects the current instrument (FluidSynth GM programs). The runtime now exposes a lightweight dashboard at `http://localhost:8095/index.html` (theremin's `custom_app_url`) so you can monitor pitch, amplitude, pose ranges, and curate the instrument rotation without keeping a terminal HUD visible.

When the app starts, Reachy performs a short guided motion (center the head, oscillate the roll, sweep the antenna) so musicians immediately hear how gestures map to sound before the motors are relaxed.

## Debug mode

For latency benchmarking without manual gestures, launch `python main.py --debug`. The robot will loop through a small roll sine sweep followed by a two-second pause, while the console prints motion commands and corresponding sound-trigger times so you can compare movement-to-audio delays on the CM4.

## Controls

| Control            | Range                     | Target             |
|--------------------|---------------------------|--------------------|
| Head roll          | -60° … +60°               | MIDI notes 48–84   |
| Head Z translation | -30 mm … +5 mm            | Amplitude 0–100 %  |
| Right antenna      | -π/3 … +π/3 radians       | Instrument program |

## Dashboard controls

- The top HUD mirrors the old terminal bars for note/pitch/amplitude, but now in the browser.
- The “Program slots” grid refreshes live to show the currently active instrument order.
- A circular “instrument wheel” highlights each preset and the current antenna angle, so performers see exactly which slot is active.
- The “Live instrument set” card lets you search the full FluidSynth GM bank and build up to eight presets (order defines how the antenna scrolls). Changes are saved via the same `/api/config` endpoint the web UI hits, so advanced users can script their own configs too.