An animated ASCII eye. The eye is drawn by C++ programs; a small Python layer (standard library only) lets scripts and shell commands set its state: idle, working, success, warning or error.
| Part | File | What it does |
|---|---|---|
| Terminal eye | eye.cpp |
The eye animation inside a terminal window |
| Desktop eye (Windows) | eye_widget.cpp |
A small borderless eye in a corner of the screen. It follows the mouse, blinks and reacts to Oculi states |
| Event layer | oculi.py |
Python API, command runner and the state file that connects Python to the desktop eye |
| Tests | test_oculi.py, test_bridge.py, test_runner.py |
unittest, no extra packages |
Only the desktop eye reacts to states. The terminal eye is a stand-alone animation and ignores them.
- Moving iris with fine fibres, breathing pupil, glint and soft reflection
- Natural gaze and random blinks
- Grayscale mode and green mode
- Five states that any Python code or shell command can set
- No dependencies: C++ standard library and Win32 for the eyes, Python standard library for the event layer
- A C++ compiler such as
g++(MinGW on Windows, GCC or Clang on Linux/macOS) - Terminal eye: a terminal with 256-color support (Windows 10 or newer, or a modern Linux/macOS terminal), at least 61 columns x 23 rows
- Desktop eye: Windows
- Event layer and command runner: Python 3.8 or newer (developed and tested with 3.12)
git clone https://github.com/hasheramin5-cyber/Oculi.git
cd Oculi
Or click Code > Download ZIP on GitHub, extract it and open a terminal in that folder.
g++ eye.cpp -o eye
| System | Command |
|---|---|
| Windows Command Prompt | eye or eye green |
| Windows PowerShell | .\eye or .\eye green |
| Linux / macOS | ./eye or ./eye green |
Add green for the green version. Press Ctrl+C to quit.
A small, borderless, transparent eye made of text characters. It sits in the bottom-right corner of the screen, stays on top of all windows, looks at the mouse pointer and blinks.
g++ eye_widget.cpp -o eye_widget -mwindows -lgdi32 -luser32
eye_widget
| Option | What it does |
|---|---|
--music |
Real-time music-reactive mode (reacts to system audio) |
gray |
Black and white instead of green |
box |
Adds a dark backing, helpful on bright windows |
3 to 8 |
Size (3 is smallest, 4 is default) |
Options can be combined, for example eye_widget --music 3 gray box.
- Drag with the left mouse button to move it.
- Right-click the eye to close it, or run
taskkill /IM eye_widget.exe /F. - Start with Windows: press Win + R, run
shell:startup, and create a shortcut toeye_widget.exein that folder. Delete the shortcut to stop it.
| State | Meaning | Desktop eye |
|---|---|---|
idle |
Nothing happening (the default) | Normal eye |
working |
Something is running | Iris rotates faster |
success |
Finished without errors | Green glow and one blink, fading out; goes back to idle after 3 seconds |
warning |
Needs attention | Slow amber pulse |
error |
Something failed | Faster red pulse |
idle, working, warning and error stay until the next event.
import oculi
oculi.send(source="training", state="working")
oculi.send(source="training", state="success")
oculi.current_state() # "success" (reports "idle" again 3 seconds later)
oculi.state_of("training") # "success"
oculi.send("build", "fire") # raises oculi.InvalidStateErrorsend(source, state) validates the input, remembers the event and updates the state file. It returns an Event(source, state, timestamp). An unknown state raises InvalidStateError (a ValueError); an empty source raises ValueError. Source names are lower-cased. A failure to write the state file never raises.
| Function | Returns |
|---|---|
current_state() |
The state that is in effect, "idle" if there are no events |
current_event() |
The most recent Event, or None |
state_of(source) |
The latest state reported by one source, or None |
sources() |
The latest event of every source that has reported |
events() |
The most recent events (up to 100), oldest first |
visual() |
The intended look for the current state |
reset() |
Forgets all events and publishes idle |
Several sources can report at the same time. The most recent event wins; there is no priority between sources.
The command runner reports the outcome of any command without changing the command:
python -m oculi run --source training -- python train.py
python -m oculi run --source tests -- pytest -q
python -m oculi run --source build -- g++ eye.cpp -o eye
workingis sent before the command starts.- The command runs with your stdin, stdout and stderr, so its output and prompts are untouched. Arguments are passed through exactly as written.
- Exit code
0sendssuccess; any other exit code sendserror. - Oculi exits with the command's own exit code.
--source and the -- before the command are required. Only the first -- is used by Oculi, so later ones belong to your command.
| Exit code | When |
|---|---|
| the command's own | The command ran and finished |
127 |
The command was not found (error is sent) |
126 |
The command could not be executed because of permissions (error is sent) |
130 |
Interrupted with Ctrl+C (error is sent) |
128 + N |
The command was killed by signal N (Linux/macOS) |
2 |
Wrong usage, for example a missing --source; the command is not run |
python -m oculi finds oculi.py in the current folder. To use it from another folder, add the repository folder to PYTHONPATH (Command Prompt: set PYTHONPATH=C:\path\to\Oculi).
send() publishes every event to one text file, and the desktop eye reads it about every 200 ms. No sockets or servers are involved.
%LOCALAPPDATA%\Oculi\state.txt
working 1760000000.123456 training
The single line is <state> <timestamp> <source>; the timestamp is seconds since 1970 and spaces in a source name become _. The file is written to a temporary file first and then moved into place, so the eye never reads a half-written line.
Set the OCULI_STATE_FILE environment variable to use another path (an empty value turns the bridge off). The desktop eye reads the same variable, so set it for both processes.
A native C++ / Win32 real-time audio visualization mode for the Desktop Eye (eye_widget). When enabled, the eye dynamically reacts to any active Windows system audio (Spotify, YouTube, media players, games) via WASAPI loopback capture without requiring external drivers or virtual audio cables.
Music mode is optional and disabled by default.
- Enable Music Mode:
eye_widget --music
- Normal Mode (Music Disabled):
eye_widget
- Combine with Other Widget Options:
eye_widget --music 3 gray box
Music states reflect audio dynamics and are distinct from Oculi's five task notification states (idle, working, success, warning, error):
| Music State | Trigger Condition | Intended Behavior |
|---|---|---|
Dormant |
Silence or sub-threshold audio | Resting baseline with natural slow breathing |
Listening |
Low or ambient sound without strong rhythm | Attentive state; pupil adjusts to ambient volume |
Groove |
Sustained rhythmic beat and bassline | Rhythmic pupil dilation and iris modulation in sync with music |
Impact |
Beat drop, snare hit, or transient energy peak | Specular glint flare, rapid pupil contraction or expansion |
Audio analysis maps frequency and transient features onto specific visual elements of the eye:
| Audio Feature | Target Visual Element | Visual Response |
|---|---|---|
| Bass (20–250 Hz) | Pupil radius ( |
Natural, smooth pupil dilation and bass pump |
| Mid frequencies (250–2500 Hz) | Iris fibers & rotation | Modulates harmonic fiber ripples and spin speed |
| Treble (2500–16000 Hz) | Iris boundary / edge | Sharpens collarette and illuminates iris perimeter |
| RMS Volume | Overall brightness | Gentle intensity modulation without blowing out highlights |
| Beat Detection | Transient pulse | Crisp brightness pulse and immediate pupil onset |
| Impact State | Specular glint & reflection | Flares highlight radius and sharp secondary reflection |
| Groove State | Synchronized rhythm | Cohesive rhythmic modulation locked to tempo |
| Dormant State | Resting baseline | Returns to natural breathing animation during silence |
Oculi's five core notification states (idle, working, success, warning, error) take strict priority over music mode:
- Notification Recognition: When a task triggers
warning(amber pulse),error(fast red pulse), orsuccess(green glow), the state's signature hue and pulse override the visual styling. The internal geometry continues reacting smoothly to audio dynamics beneath the notification tint. - Working State: A
workingevent enforces fast iris rotation regardless of audio tempo. - Idle State: When no task notification is active (
idle), the eye fully expresses music states and beat pulses.
- Capture: Windows Audio Session API (WASAPI) loopback capture (
audio_capture.h,audio_capture.cpp) captures system audio directly from the default render endpoint on a dedicated background thread without requiring external drivers or virtual audio cables. - Analysis: Real-time digital signal processing (
audio_analysis.h,audio_analysis.cpp) runs an in-place 1024-point Cooley-Tukey Radix-2 FFT with Hann windowing. - Frequency Band Separation: Isolates bass (20 to 250 Hz), mid frequencies (250 to 2500 Hz), treble (2500 to 16000 Hz), and normalized RMS volume.
- Beat and Transient Detection: Analyzes spectral flux across low-frequency bins with adaptive thresholding to register rhythmic onsets.
- Smoothing: Asymmetrical attack/decay ballistic filters eliminate visual jitter while preserving crisp reaction to drum hits and transient onsets.
- Thread Safety & Non-Blocking: Analysis runs decoupled from rendering; the renderer queries an atomic or mutex-protected snapshot of smoothed features in sub-microsecond time.
- Graceful Fallback: If WASAPI loopback fails to initialize (e.g. no audio output device is present or enabled),
eye_widgetgracefully disables music capture and continues running in normal desktop mode without crashing.
- Operating System: Windows 10 or Windows 11.
- Audio Output: An active audio render device (speakers, headphones).
- Build Tools: CMake 3.15+ and a C++17 compiler (such as MSYS2 UCRT64 GCC, MinGW-w64, or MSVC).
cmake -B build
cmake --build buildRun the unit tests:
build\test_audio.exeRun the live interactive WASAPI capture test (inspect real-time FFT bands and states in console):
build\test_live_wasapi.exe 5| Issue | Solution |
|---|---|
Eye does not react to music / stays in Dormant |
Ensure sound is actively playing through your default Windows playback device. Check Windows Sound Settings to verify the device is set as default. |
| No audio playback device connected | Oculi detects missing audio endpoints gracefully and falls back to normal mode. Plug in headphones or speakers to enable audio loopback. |
| Inspecting real-time audio detection | Run build\test_live_wasapi.exe in a terminal while playing music to observe live volume bars, frequency bands, beat triggers, and state classifications. |
- WASAPI loopback capture is a Windows-only platform capability.
- Music mode is integrated into the Windows desktop eye widget (
eye_widget). The standalone terminal eye (eye.cpp) remains a lightweight ASCII animation without audio dependencies.
python -m unittest -v test_oculi test_bridge test_runner
The tests use a temporary state file and never touch %LOCALAPPDATA%.
- No priority between sources. The latest event wins, so a command that finishes can overwrite the state of another that is still running.
- A stuck
workingstate. If a runner is killed forcibly (for exampletaskkill /F) or the computer restarts mid-run, the file keeps its last state until the next event. Reset it withpython -c "import oculi; oculi.send('manual', 'idle')". - Only the desktop eye reacts to states. It is Windows only; the terminal eye does not read the state file.
| Problem | Fix |
|---|---|
'g++' is not recognized |
Install MinGW (or another compiler) and add its bin folder to your PATH, then reopen the terminal. |
eye is not recognized in PowerShell |
Use .\eye instead of eye. |
No module named oculi |
Run the command from the repository folder, or set PYTHONPATH (see section 5). |
Permission denied when building eye_widget |
The old one is still running. Close it with taskkill /IM eye_widget.exe /F, then build again. |
| Terminal eye is garbled or cut off | Use Windows Terminal or the VS Code terminal, and make the window at least 61x23. |
| Desktop eye is hard to see or too big | Use eye_widget box, or a smaller size such as eye_widget 3. |
Every frame is calculated from math, not from stored images. Each cell of a character grid gets a brightness value that becomes a character (from . to @) and a colour. The terminal eye writes the frame with ANSI escape codes; the desktop eye draws the same characters into a transparent, always-on-top window. The Python layer only decides which state the eye should show; the C++ code draws it.
This project is licensed under the MIT License.
