Get a free upgrade to WaveStack Modulate for iOS with code MODULATELAUNCH Free upgrade: MODULATELAUNCH

EYESY Simulator

Desktop EYESY simulator and emulator for macOS and Windows

EYESY Simulator desktop app showing a video synth mode rendering with knob controls and audio source selector

EYESY Simulator v1.0.0

EYESY Simulator is a native desktop app for developing and previewing Critter & Guitari EYESY video synthesizer modes without the hardware.

This project is not affiliated with Critter & Guitari. I built this to aid my own mode development.

Downloads

PlatformFile
macOS (Apple Silicon)EYESY Simulator-1.0.0-arm64.dmg
Windows (x64)EYESY Simulator Setup 1.0.0.exe

How to develop EYESY modes without the hardware

EYESY Simulator runs real EYESY Python and pygame scripts on your computer and renders the visuals in real time. You write the mode on your laptop, turn the five knobs on screen, feed it simulated audio, and copy it to the device when it works as you want. It works as an EYESY emulator for writing and testing a mode, which is the part of the job that needs no video output or signal chain.

Getting going takes four steps:

  1. Download and install for your platform.
  2. Launch the app and select the folder that holds your mode folders.
  3. Pick a mode from the dropdown and hit Start.
  4. Adjust knobs and audio settings while it runs.

Each mode is a folder with a main.py inside it, so point the app at the directory above those folders rather than at one of them. Existing modes to load are in the EYESY Modes GitHub repo and on Patch Storage.

What an EYESY mode looks like

A mode defines draw(screen, etc), which is called thirty times a second, and optionally setup(screen, etc), which runs once before the first frame. This is a complete working mode:

import pygame

def setup(screen, etc):
    pass

def draw(screen, etc):
    screen.fill(etc.color_picker_bg(etc.knob5))

    radius = int(etc.knob1 * 300) + 10
    x = int(etc.knob2 * etc.xres)
    y = int(etc.knob3 * etc.yres)
    color = etc.color_picker(etc.knob4)

    pygame.draw.circle(screen, color, (x, y), radius)

Drop that in a folder, load the folder, and it runs. Writing EYESY Modes is the full reference for the etc object, with worked examples for audio, MIDI, colour and trails.

What the simulator supports

Modes get the same etc object they get on the device, and the simulator supports the parts of it listed below.

Knobs. etc.knob1 through etc.knob5 are each a float from 0.0 to 1.0, set by five on-screen knobs.

Audio. etc.audio_in carries 100 samples per frame in 16-bit range, matching the hardware’s buffer size, with etc.audio_left, etc.audio_right and etc.audio_in_r alongside it. etc.audio_peak and etc.audio_peak_r give a level normalised to 0.0 to 1.0, and etc.audio_trig goes true when that level passes 0.3. You can feed it silence, a sine, white noise, a beat, internet radio, or your own audio file.

MIDI. The simulator supports etc.midi_note_new, etc.midi_note, etc.midi_velocity, etc.midi_notes for all 128 note numbers, and etc.midi_clk, so a mode driven by note events can be built and tested here.

Colour. etc.color_picker, etc.color_picker_bg and etc.color_picker_fg each take a value from 0.0 to 1.0 and return an RGB tuple, so modes written for the EYESY OS 3 shared palette run without errors. etc.bg_color and etc.fg_color are there too.

Canvas. etc.xres and etc.yres report 1280 by 720, the EYESY’s native resolution, and the window keeps 16:9 whatever size you make it. etc.frame_count counts frames, etc.fps reports 30, and setting etc.auto_clear = False stops the screen being wiped between frames, which is how trails are made. Surface.set_alpha is not implemented, so the usual trick of fading an old frame under a transparent black surface raises an error here. Clear the screen on a timer while developing and try the fade on the device.

Drawing. The pygame drawing functions circle, rect, line, lines, polygon, ellipse and arc all work, as do Surface.fill, blit, image loading, transform.scale, rotate, flip and font rendering.

No Python install. A Python 3.11 runtime is bundled with the app.

Simulator vs real EYESY hardware

The simulator matches the EYESY’s drawing surface and control layout, and differs from the hardware in the ways shown here.

EYESY SimulatorEYESY hardware
Canvas1280×7201280×720
Knobs5 on screen, 0.0 to 1.05 physical
AudioSimulated: silence, sine, noise, beat, internet radio, or your own fileLive audio input
Colour paletteApproximatedThe device’s own
Surface alphaset_alpha not implementedSupported
PerformanceRuns at your computer’s speedConsiderably more constrained

The EYESY hardware may be much more resource constrained than your development computer, and the simulator does not attempt to simulate those limits, so you may get a better frame rate in development than you will on the EYESY itself. If you are building anything complex, test early and often on real hardware; I learned this from experience.

Why a mode works in the simulator but not on the EYESY

Most of these failures come from one of the causes below. The first two are one-line fixes, and the third is the performance difference described above.

  • Bare globals. Read controls as etc.knob1 through etc.knob5, never as a bare knob1. Some tools accept the bare name and the hardware does not.
  • A missing import. import pygame has to be at the top of main.py.
  • Performance. A mode that holds thirty frames a second on a laptop can drop frames on the device. There is no way to find this out except on hardware.

System requirements

  • macOS: Apple Silicon (M1/M2/M3/M4), macOS 10.15+. There is no Intel build.
  • Windows: 64-bit, Windows 10+

Version history

  • 1.0.0 (February 2026) was the first native desktop release for macOS and Windows, with a bundled Python 3.11 runtime, five knobs, simulated audio sources and pygame drawing support.

Source

Source for the native app is at stuart78/Eyesy-native. The original web-based simulator, which ran EYESY scripts in a browser over a WebSocket at 30 FPS, is still available but the native app is the recommended way to work now. Neither repository carries a licence file at the moment, so the code is published but not formally licensed for reuse.

Common questions

Can I use the EYESY without the hardware?

Yes, for writing and testing modes. EYESY Simulator runs real EYESY Python and pygame scripts on macOS or Windows and renders the visuals in real time, so you can develop modes with no EYESY connected. You still need the hardware to perform with live audio and video output.

Is the EYESY Simulator free?

Yes. It is a free download for macOS and Windows. The source for the native app and the older web version is published on GitHub.

Do modes built in the simulator run on real EYESY hardware?

Yes. Modes written and tested in the simulator are compatible with real EYESY hardware, as long as they use etc.knob1 through etc.knob5 rather than bare globals and include an import pygame line at the top.

Do I need to install Python to use it?

No. A Python 3.11 runtime is bundled with the app, so there is nothing to install separately.

Does the EYESY Simulator work on Intel Macs?

No. The macOS build is Apple Silicon only and requires an M1, M2, M3, or M4 Mac running macOS 10.15 or later. There is no Intel build. Windows users need 64-bit Windows 10 or later.

How is the simulator different from a real EYESY?

The simulator does not reproduce the hardware's performance limits. Your computer is likely faster than an EYESY, so a mode can run smoothly in the simulator and drop frames on the device. Audio is also simulated rather than live. Test complex modes on real hardware early.

Does the EYESY Simulator support MIDI in modes?

Yes. Modes can read etc.midi_note_new, etc.midi_note, etc.midi_velocity, etc.midi_notes for all 128 note numbers, and etc.midi_clk, so a mode driven by note events can be developed and tested in the simulator.

Does the simulator support the EYESY OS 3 colour palette?

Yes. etc.color_picker, etc.color_picker_bg and etc.color_picker_fg all work and return an RGB tuple for a value between 0.0 and 1.0, as do etc.bg_color and etc.fg_color. The palette is an approximation of the hardware's rather than a reproduction of it, so check final colours on the device.

How do I make trails or feedback in an EYESY mode?

Set etc.auto_clear = False in your setup function. The screen is then no longer wiped between frames, so each frame draws on top of the last, and you clear it yourself when you want to, on a timer or on etc.audio_trig. Fading the old frame by blitting a mostly transparent surface works on hardware but not in the simulator, which does not implement Surface.set_alpha.

Where do I put EYESY modes so the simulator finds them?

Each mode is a folder containing a main.py file. Point the app at the folder that holds those mode folders, and every mode inside it appears in the dropdown.

Pair with