An on-device blink companion for long screen days.
EyesRhythm uses your webcam to measure how often and how steadily you blink, and gently nudges you back to a healthy rhythm.
Download · Features · Build from source · Code guide · Changelog
Focused screen work lowers the spontaneous blink rate and makes blinking less complete and less regular. Over time this can contribute to dryness, fatigue, and blurred vision. It usually goes unnoticed until the eyes already hurt.
EyesRhythm runs quietly next to your work. It counts blinks with the built-in or USB webcam and turns rate and regularity into one score, the Ocular Rhythm Index (ORI). It also helps you build a steadier habit of about 15–20 blinks per minute.
- Private by design. Everything runs on your computer. No account, no cloud, no analytics. Camera frames are never uploaded or recorded.
- Free for macOS and Windows. Official installers are available at eyesrhythm.com and on the releases page.
Note
EyesRhythm is a wellness companion, not a medical device. It is not intended to diagnose, treat, cure, or prevent any disease. If you have persistent eye discomfort or changes in vision, see an eye-care professional.
| Ocular Rhythm Index | A 0–100 score that combines blink rate (70%) and blink regularity (30%). |
| Companion views | Pick an avatar (Atlas, Lumen, or Vesper) that mirrors your blinks, a camera preview (Lens), a live five-minute ORI graph (Trace), or a head-direction dial (Poise). |
| Poise | Shows which directions your head has turned today in 30° slices, so the neck and shoulders get regular changes of position. |
| Alerts | Always on. Choose a quiet orange pulse (Visual, the default) or a short tone (Sound) when ORI stays below your threshold. You can also turn on a click for every blink. |
| Practice | A guided two-minute session that paces your blinks and eye movement. |
| Reports | Daily, weekly, and monthly charts of ORI and screen time. |
| Smart camera use | 30 fps while you are in view, 1 fps when you look away, and the camera turns off when you leave the desk. |
| Multiple cameras | Use one webcam, or Hybrid mode to combine every desk camera. |
| Key | Action |
|---|---|
| B | Beep on every counted blink |
| A | Switch the alert between Visual and Sound |
| P | Start or stop Practice |
| D | Switch between the compact and full dashboard |
| W | Show or hide the Settings and Reports panel |
| C | Switch to or from the Lens camera preview |
Download the installer for your computer from eyesrhythm.com or the latest release.
- macOS: open the
.dmgand drag EyesRhythm into Applications. - Windows: run
EyesRhythm-Setup-<version>.exe. It installs for your user account only and does not need administrator rights.
Allow camera access when the system asks. On macOS you can change this later in System Settings → Privacy & Security → Camera.
- Python 3.10–3.12 (3.11 recommended)
- Node.js 18 or later (to build the interface)
- A webcam and camera permission for your terminal or Python
./for_mac/setup.sh # create the virtual environment, install dependencies, build the UI
./for_mac/run.sh # launch the desktop windowTo open EyesRhythm when you log in, run ./for_mac/install_autostart.sh. To turn that off, run ./for_mac/uninstall_autostart.sh. See for_mac/README.md for more, including how to build a standalone .app.
See for_windows/README.md. It covers running from source, building the portable app and installer on a Windows PC, and using the Build Windows app GitHub Actions workflow.
# Terminal 1: engine and local API
source EyeRhythm/bin/activate
python -m app.main --browser
# Terminal 2: React UI
cd frontend
npm install
npm run devOpen the URL Vite prints. It proxies /api and /ws to the Python server on 127.0.0.1:8742.
python -m unittest discover -s testsWebcam ─▶ MediaPipe Face Landmarker ─▶ blink detector ─▶ engine ─▶ local API ─▶ React UI
(blink_core/) (app/) (FastAPI, (frontend/)
WebSocket)
Regularity measures how even the gaps between blinks are:
CV = standard deviation of inter-blink gaps ÷ mean gap
Regularity = max(0, 100 − 100 × CV)
ORI = 70% rate score + 30% regularity
Daily totals, ORI history, and preferences are stored as JSON in ~/.eyerhythm_blinkcounter/. Nothing in that folder leaves your computer. See docs/CODE_GUIDE.md for the frame pipeline, file formats, and settings.
├── app/ Camera engine, local API, desktop window
├── blink_core/ Blink detection and screen-time tracking
├── frontend/ React + TypeScript + Vite interface
├── models/ MediaPipe Face Landmarker model
├── assets/ App icons and the Inter font
├── tests/ Unit tests
├── tools/ Developer utilities (signal analysis, screenshot capture)
├── docs/ Code guide
├── for_mac/ macOS and Linux setup, run, and build scripts
├── for_windows/ Windows launchers, freeze, and installer scripts
├── website/ Marketing site (Astro)
├── licenses/ Full texts of third-party licenses
├── EyeRhythm.spec PyInstaller configuration
└── run_app.py Entry point for packaged builds
The rate and regularity measures are informed by published work on blinking during screen use, including:
- Johnston PR, Rodriguez J, Lane KJ, Ousler G, Abelson MB. The interblink interval in normal and dry eye subjects. Clinical Ophthalmology. 2013;7:253–259. doi:10.2147/OPTH.S39104
- Cardona G, Argilés M, Pérez-Cabré E. Loss of blink regularity and its impact on ocular surface exposure. Diagnostics. 2023;13(14):2362. doi:10.3390/diagnostics13142362
- Wang MTM, Power B, Xue AL, Craig JP. Blink completeness and rate in dry eye disease: an investigator-masked, prospective registry-based, cross-sectional, prognostic study. Contact Lens and Anterior Eye. 2025;48:102369. doi:10.1016/j.clae.2025.102369
Bug reports and ideas are welcome. Please read CONTRIBUTING.md before opening an issue or pull request. To report a security issue, follow SECURITY.md instead of opening a public issue.
EyesRhythm’s source code is licensed under the PolyForm Noncommercial License 1.0.0. You may use, modify, and share it for any noncommercial purpose, provided you keep LICENSE, the required notice below, and THIRD_PARTY_NOTICES.md. Commercial use is not permitted under this license.
Required Notice: Copyright Pranay Soni (https://github.com/pranaycv)
Third-party components keep their own licenses. Packaged builds include LICENSE, THIRD_PARTY_NOTICES.md, and the full texts in licenses/.
| Component | License |
|---|---|
| MediaPipe and the Face Landmarker model | Apache 2.0 |
| OpenCV | Apache 2.0 |
| FFmpeg (inside the OpenCV wheel) | LGPLv2.1, shipped as a replaceable shared library |
| NumPy, Uvicorn, pywebview | BSD-3-Clause |
| FastAPI, Pydantic, React, Vite | MIT |
| Inter font | SIL Open Font License 1.1 |
| PyInstaller (build tool only) | GPL-2.0 with bootloader exception |
The Sound-mode alert tone (alert.mp3) is original to EyesRhythm. Practice quotations in quotes.json are limited to public-domain authors.
Questions and feedback: hello@eyesrhythm.com · Website: eyesrhythm.com