Iris — Eyes That Follow

Glowing eyes that track you — via webcam, pointer, or manual control. Smooth bilinear gaze blending across 16 pre-generated frames, with a pygame desktop viewer, a drop-in Next.js component, and a Lively Wallpaper pack for Windows.

Live demo: eyes-that-follow.vercel.app

Features

• 16 eye states — 11 gaze directions, 2 blink frames, 3 expressions (squint, wide, drowsy)
• Smooth gaze blending — continuous bilinear interpolation across the gaze grid (PNG and ASCII)
• Webcam tracking — MediaPipe face detection maps your position to gaze (user-tracker/)
• Pointer tracking — viewport-wide mouse follow with reactive behaviors (web-tracker/)
• Dual render modes — ASCII glyph rasterization or WebP PNG frames, with crossfade on switch
• Autonomous behavior — auto-blink, idle drowsy, click → wide, shake → chase → squint
• Canvas bloom — additive glow pass with hue-shifted red styling (web)
• Lively Wallpaper — interactive desktop wallpaper for Windows with cursor or webcam tracking (lively-wallpaper/)

Project structure

iris/
├── user-tracker/       Pygame desktop viewer (PNG, ASCII, webcam tracking)
├── web-tracker/        Next.js <Eyes /> component (pointer tracking)
├── lively-wallpaper/   Lively Wallpaper HTML pack (Windows desktop)
├── output/             Shared PNG + ANSI assets
├── registry.json       shadcn registry (GitHub + Vercel /r/ mirror)
├── CONTEXT.md          Agent/developer project state
├── PLAN-PRD.md         Product requirements
└── AGENTS.md           Instructions for AI coding agents

Quick start

Web demo (fastest)

Visit eyes-that-follow.vercel.app or run locally:

cd web-tracker
npm install
npm run sync-assets   # output/ → public/ (ANSI + WebP)
npm run dev           # http://localhost:3000

Move your cursor, click the eyes, or shake the pointer fast. Toggle ASCII/PNG in the demo UI.

Desktop viewer (webcam)

download.mp4

cd user-tracker
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt
python app.py                 # PNG mode (default)
python app.py --ascii         # ASCII mode
python app.py --track         # PNG + webcam tracking
python app.py --ascii --track # ASCII + tracking

Press T to toggle manual / tracking mode.

Lively Wallpaper (Windows)

Download Iris.zip from GitHub Releases or build it:

cd lively-wallpaper
npm install
node scripts/vendor-mediapipe.mjs   # MediaPipe BlazeFace (first time / after dep update)
node scripts/package.mjs            # writes dist/Iris.zip

In Lively: + Add Wallpaper → Browse, select Iris.zip. Enable Follow the cursor or Follow the webcam in Customise (mutually exclusive). For webcam, use the on-screen setup panel — hide desktop icons first (right-click desktop → View) so you can click Allow on the permission prompt. See lively-wallpaper/README.md for settings and troubleshooting.

Web component

import { Eyes } from "@/components/Eyes";

<Eyes
  mode="ascii"
  trackArea="window"
  trackPointer={true}
  autoBlink={true}
  glow={1}
  onTelemetry={(t) => console.log(t.gazeState)}
/>

See web-tracker/README.md for behaviors (idle drowsy, click wide, shake squint), props, bloom, and architecture.

Install in your project (shadcn registry)

One command copies the component, lib/iris/ stack, and all assets into any Next.js / shadcn project:

npx shadcn@latest init -d   # once, in the consumer project
npx shadcn@latest add Crisiswastaken/iris/eyes

Optional duotone tint filter (install eyes first):

npx shadcn@latest add Crisiswastaken/iris/eyes-tint

URL fallback (optional — run npm run registry:build in web-tracker/ before deploy):

npx shadcn@latest add https://eyes-that-follow.vercel.app/r/eyes.json

After install:

import { Eyes } from "@/components/eyes";

<Eyes mode="ascii" trackArea="window" onTelemetry={(t) => console.log(t.gazeState)} />

Assets land in public/ansi/ and public/eyes/. Rebuild the registry after changing distributable code: cd web-tracker && npm run registry:build.

Requirements

Component	Python	Other
user-tracker/	3.10+	Webcam for tracking (optional)
web-tracker/	—	Node.js 20+
lively-wallpaper/	—	Node.js 20+ (build only); Lively Wallpaper to run; webcam optional

Desktop deps: pygame, Pillow, OpenCV, MediaPipe, NumPy

MediaPipe model downloads automatically on first run.

Regenerating assets

PNG assets live in output/. To rebuild ANSI frames for ASCII mode:

cd user-tracker
python scripts/convert_assets.py   # requires ascii-view binary (see script header)

cd ../web-tracker
npm run sync-assets

cd ../lively-wallpaper
node scripts/build-assets.mjs      # optional — assets are committed
npm install                        # only for vendor-mediapipe
node scripts/vendor-mediapipe.mjs  # MediaPipe for webcam tracking
node scripts/package.mjs           # rebuild dist/Iris.zip

Tests

# Desktop viewer
cd user-tracker && python -m unittest discover -s tests -v

# Web component
cd web-tracker && npm test

Deploy (web-tracker)

The live site runs on Vercel. From web-tracker/:

npm run sync-assets
npm run build
npx vercel --prod

Project root for Vercel is web-tracker/. Analytics are enabled via @vercel/analytics.

Documentation

Doc	Purpose
CONTEXT.md	Current project state and architecture
PLAN-PRD.md	Goals, phases, acceptance criteria
AGENTS.md	Instructions for AI coding agents
CONTRIBUTING.md	How to contribute
lively-wallpaper/README.md	Lively Wallpaper install and build

License

MIT — see LICENSE for details.