Runs Critter & Guitari EYESY modes on your computer, so you can iterate on a mode quickly and upload it to the device once it works. The knobs and panel buttons are simulated with the keyboard.
Targets OS v3 — the eyesy object, Python 3. Modes written against v2's etc object will not run.
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python simulator.py examples/ink-rings/main.py
Any mode folder on disk works. Point it at the main.py:
.venv/bin/python simulator.py /path/to/your-mode/main.py
The window needs focus — click it first; it often opens behind the terminal.
Press 1 through 5 to pick a knob, or walk the row with ← and →. The up and down arrows turn it: a tap nudges, a held key sweeps.
Hold Shift and the five knobs stop where they are while the arrows keep turning the hardware underneath. A mode that reads eyesy.knob[i] while eyesy.key2_status is true gets that as a second page of controls — the device does this, and knobs 2 through 5 are free for it. Knob 1 under Shift is the engine's audio input gain.
One knob serves both pages, so letting Shift go hands the ordinary knob whatever position you just left it in. That is the device's behaviour, and it is why a second page suits settings you choose once.
| Key | Does |
|---|---|
1–5 |
select the active knob, the five on the middle row |
| ← → | select the knob to either side, wrapping at the ends |
| ↑ ↓ | turn the active knob: tap to nudge, hold to sweep |
| Shift | Shift button, middle left. Held, the five knobs freeze and the arrows turn a second page a mode can read |
A |
Audio In jack, back panel; press again to unplug |
O |
On Screen Display button, top left. Starts on; press to hide |
T |
Trigger button, bottom right. Tap to fire once; hold for a sweeping sine that keeps re-triggering |
P |
Persist button, top right. Stops the screen clearing between frames so drawing accumulates |
G |
Screenshot button; writes grab-N.png in the repo root |
Q |
Shift + Screenshot: stop a scene's knob sequence, or play it again from the top |
[ ] |
previous / next foreground palette |
- = |
previous / next background palette |
, . |
audio gain down / up |
| Esc | quit |
A puts whatever the Mac is playing on the jack, so a mode can be developed against real music. It goes through a Core Audio process tap, so nothing is installed and playback stays audible. Levels run low — raise the gain with . until the trigger indicator fires.
Use --signal system to come up already plugged in, or --signal synth for a tone that peaks twice a second.
A scene on the unit is a folder in /sdcard/Scenes holding the mode's name, knobs 1–5, Persist and the palettes, and optionally a knob sequence the unit loops once the scene is recalled. The unit records sequences by hand, 33 seconds at most. The loader checks nothing but the shape, so a sequence written here can run as long as you like.
.venv/bin/python simulator.py path/to/main.py --scene path/to/scene-folder
.venv/bin/python simulator.py path/to/main.py --scene scene.json
--scene recalls the scene after setup(), as the unit does at boot, and loops its sequence with the unit's own playback rule: each frame writes only the knobs whose value changed, so a knob the sequence holds still stays yours to turn.
A scene file describes a scene and its knob sequence in seconds. Each knob is held at a value, follows keyframes with easing, or rides waves around a centre; the loop has to end where it starts. scene.py build turns scene files into scene folders in the card's format:
.venv/bin/python scene.py build scene.json out/
.venv/bin/python scene.py show out/"My Scene"
The sequencer steps once per drawn frame, not once per 1/30 s, so a scene file carries the frame rate its mode really runs at on the unit, and the simulator plays it at that rate.
keyframes.py builds a scene file from knob settings picked out of a prospect library, with a hold and a tempo for each keyframe, speed limits per knob, and a veil for knobs that jump.
explore.py renders a mode headless on a virtual clock, so it sees the time it would see on the unit at that frame rate however fast the laptop draws:
| Command | Renders |
|---|---|
sweep MODE --knob N |
one knob through its travel, a few frames per setting |
grid MODE --knobs 1,3 |
two knobs against each other |
prospect MODE --count 72 |
an evenly spread library of settings, one frame each, plus library.json |
prospect MODE --stops 11 --keep 100 |
a pool of 1,331 settings, every three-knob combination of 10% stops, and the 100 frames that look least alike as library.json, each with a four-frame strip |
keep POOL --weights colour=0.1 |
keeps again from a rendered pool, with other weights or another count |
board LIBRARY p012=calm,p040=storm |
chosen library entries in order, as a storyboard |
film MODE SCENE --every 5 |
a scene sampled through its loop, and its motion second by second |
thumb MODE SCENE |
the 320x240 scene.jpg the unit's menus show |
Every frame is labelled with how much it moves and how bright it is, so a stall, a strobe or a dead patch shows as a number.
BSD 3-Clause. See LICENSE.
color_palettes.py and osd.py are Critter & Guitari's — see LICENSE-EYESY_OS.txt.
- Scenes:
--scenerecalls a scene folder or a scene file and loops its knob sequence the way the unit does, at the scene file's frame rate. scene.pybuilds scene files into the card's scene format.explore.pyrenders sweeps, prospect libraries, storyboards, filmstrips and thumbnails headless.keyframes.pybuilds a scene file from keyframes picked out of a prospect library.
- System audio capture on
A, through a Core Audio process tap. - Left and right walk the knob row, alongside the number keys.
- The On Screen Display starts visible.
- The background knob starts at zero, for black rather than mid grey.
Rewritten for EYESY OS v3 — eyesy object, Python 3.11, pygame 2.6.1 — and split into its own project.
Original harness, written for EYESY OS v2 and the etc object.