{"id":49389722,"url":"https://github.com/25thr/blinkd","last_synced_at":"2026-04-28T12:02:24.932Z","repository":{"id":313278627,"uuid":"1050372113","full_name":"25thr/blinkd","owner":"25thr","description":"Real-time blink detection engine turning blinks into actions for games, accessibility, and next-gen interfaces.","archived":false,"fork":false,"pushed_at":"2025-12-14T18:18:35.000Z","size":571,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-19T16:24:53.727Z","etag":null,"topics":["assistive-technology","computer-vision","eye-tracking","game-engine","godot","opencv","unity3d","unreal-engine","video-game"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/25thr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-04T10:40:30.000Z","updated_at":"2025-12-14T18:18:38.000Z","dependencies_parsed_at":"2025-09-05T02:38:30.976Z","dependency_job_id":null,"html_url":"https://github.com/25thr/blinkd","commit_stats":null,"previous_names":["0x48piraj/blinkd","25thr/blinkd"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/25thr/blinkd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/25thr%2Fblinkd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/25thr%2Fblinkd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/25thr%2Fblinkd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/25thr%2Fblinkd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/25thr","download_url":"https://codeload.github.com/25thr/blinkd/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/25thr%2Fblinkd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32379629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T11:25:28.583Z","status":"ssl_error","status_checked_at":"2026-04-28T11:25:05.435Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assistive-technology","computer-vision","eye-tracking","game-engine","godot","opencv","unity3d","unreal-engine","video-game"],"created_at":"2026-04-28T12:02:23.942Z","updated_at":"2026-04-28T12:02:24.926Z","avatar_url":"https://github.com/25thr.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg align=\"left\" style=\"width:260px\" src=\"https://github.com/0x48piraj/blinkd/blob/master/docs/assets/blinkd_logo.png\" width=\"288px\"\u003e\n\n**Real-time blink detection engine turning blinks into actions for games, accessibility, and next-gen interfaces.**\n\n`blinkd` is essentially a **low-level, hardware-agnostic, eye-blink input layer**, like a **\"blink driver\"** for real-time interactions.\n\n**Note for builders**\n\n*`blinkd` is a low-level input system. It does one thing well: turn eyelid signals into clean events. Designed to be real-time and input-source neutral. If you're building with it, you're building from the metal up.*\n\n### Get Ollo SDK\n\nFor production-grade eye-tracking, the **[Ollo SDK](https://ollosdk.com/)** offers a complete, high-performance solution with:\n\n* **Plug-and-play tracking** for reliable detection out of the box\n* **Low-latency, high-performance pipelines** with platform-specific optimizations\n* **High-reliability blink and eye tracking** for demanding applications\n* **Native bindings** for popular game engines: Unity, Unreal, and Godot 3/4\n* **C++ API with asynchronous pipelines** for flexible integration\n* **Cross-platform packaging** for Windows, macOS and Linux\n* **Secure on-device processing** to protect user data\n* **GPU acceleration** for maximum performance\n\n\u003e **[![Beta Free](https://img.shields.io/badge/Beta-Free-brightgreen)](https://ollosdk.com/) Exciting news:** As of now, the Beta version of **[Ollo SDK](https://ollosdk.com/)** is [available](https://ollosdk.com/) for **evaluation use at no cost**.\n\n\u003e Get early access and be among the first to supercharge your game dev projects with cutting-edge eye tracking!\n\n**[Ollo SDK](https://ollosdk.com/)** delivers a full computer-vision pipeline with ML-based eye tracking, enabling robust, production-ready solutions while keeping integration seamless.\n\nThis could become foundational tech for:\n\n* **Games**\n* **Accessibility**\n* **AR/VR**\n* **Biometric interfaces** _(fatigue detection, attentiveness)_\n* **Expression-based UI** _(hands-free UI control)_\n\nWe're building a **real-time eye input system**, which:\n\n1. Ingests camera data\n2. Processes it into a clean binary event stream (`BLINK`, `LONG_BLINK`, `WINK_LEFT`, etc.)\n3. Exposes that stream via standard IPC (UDP, shared memory)\n4. Can be extended as a **system input driver**\n\n## Features\n\nThe C implementation which is language-agnostic comes with,\n\n- **Simple**: Not super accurate by design\n- Works out-of-the-box\n- **Real-time detector**: EMA-based adaptive thresholds + hysteresis + refractory\n- Handles **one or two eyes**: Emits `BLINK`, `LONG_BLINK`, `DOUBLE_BLINK`, `WINK_LEFT`, `WINK_RIGHT`\n- **IPC built-in**: UDP JSON events for game engines (Unreal Engine, Godot, Unity), plus an _optional POSIX shared-memory ring buffer_ for high-rate pipelines\n- **O(1)** per sample: No external deps for the core\n\n## Usage\n\nFor developers interested in seeing **Blinkd** in action with **Godot 4**, we provide a minimal demo in a separate repository: [**blinkd-godot-demo**](https://github.com/25thr/blinkd-godot-demo).\n\nThis demo showcases a single scene where blink events drive gameplay.\n\n* **3D sphere flashes** when a blink is detected\n* **UI label updates** with blink count and timing\n* Serves as a **reference for integrating Blinkd** into your own Godot projects\n* Lightweight and easy to run\n\nDemonstrates **real-time blink-driven input** without complex camera setups.\n\n## Architecture\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/0x48piraj/blinkd/blob/master/docs/assets/blinkd_process_pipeline.png\" alt=\"Architecture diagram\"\u003e\n\u003c/p\u003e\n\n## Blinkd vs Ollo SDK\n\n| Feature | Blinkd | Ollo SDK |\n|--------|------------|------------|\n| Core detector | EMA + FSM | Native landmark pipeline |\n| Accuracy | ⭐⭐☆☆☆ | ⭐⭐⭐⭐⭐ |\n| EAR input | external only | Baked-in |\n| Head pose | ❌ | Advanced head-pose correction algorithms |\n| Eye landmarks | ❌ | 6 / 468 / 478 landmark sets |\n| Backends | ❌ | Enterprise + Dlib (as fallback) |\n| FPS | 30-60 (depends on source) | 60-120 (optimized) |\n| Game engines support | via UDP | native bindings |\n| IPC | UDP + POSIX shm | Direct API events |\n| Intended for | Hobbyists, testing | Game development, VR/AR, interactive real-time experiences |\n\n### Feeding\n\nProvide _openness_ in `[0..1]` per eye at ~120-240 Hz. Map any upstream signal to that range, e.g.:\n\n- **Eye Aspect Ratio (EAR)**: normalize per-user to `[0..1]`\n- **Iris/eyelid distance** or **segmentation % open**\n- **IR camera \"eye open probability\"** from a ML model\n- The detector handles baseline drift and noise adaptively.\n\n### IPC for engines\n\n* **UDP JSON** (zero dependencies):\n  `{\"t_ms\":123456,\"type\":\"blink\",\"dur_ms\":132,\"flags\":3}`\n\nWe can also expose a local WebSocket API _(to be implemented)_,\n\n```bash\nws://localhost:8765\n```\n\n#### Shared-memory IPC support (POSIX only)\n\n* It creates a named shared memory region (`/blinkdring`) that both producer (camera pipeline) and consumer (game engine or monitor tool) can map.\n* Each slot is a `BlinkdSample` (timestamp + two openness floats).\n* The ring uses simple head/tail pointers with `__sync_synchronize()` memory barrier.\n* You can push samples at 200 Hz safely from one process and consume from another with minimal overhead.\n\n**Usage example (producer):**\n\n```c\nBlinkShm* shm = blink_shm_open(\"/blinkdring\", 4096);\nwhile(1){\n  float L = 0.9f, R = 0.8f;\n  uint32_t t = (uint32_t)(clock()*1000/CLOCKS_PER_SEC);\n  blink_shm_push(shm, t, L, R);\n  usleep(5000);\n}\nblink_shm_close(shm);\n```\n\nThe consumer (another process) can map the same `/blinkdring` and read in a loop.\n\n### Tuning\n\nThe `blinkd` SDK provides several configuration options to fine-tune blink detection based on camera quality, user behavior, or latency tolerance. You can adjust sensitivity, detection timing, and noise rejection using the tuning API.\n\n### Default behavior\n\nWhen you create a `BlinkdHandle` via `blinkd_create()`, it initializes with **default balanced parameters**:\n\n```c\nblinkd_set_thresholds(h, 2.5f, 1.5f);  // close_k, open_k\nblinkd_set_timing(h, 40, 400, 800, 300, 60); // min, long, max, dbl_gap, refractory\n```\n\n#### Thresholds\n\nThese control how tightly the system defines a \"closed\" or \"open\" eye, relative to baseline noise:\n\n```c\nvoid blinkd_set_thresholds(BlinkdHandle* h, float close_k, float open_k);\n```\n\n* `close_k`: How many deviations below baseline to consider \"closed\"\n* `open_k`: How many deviations below baseline to consider \"open\"\n\nLower values increase sensitivity; higher values are more conservative.\n\n#### Timing\n\n```c\nvoid blinkd_set_timing(BlinkdHandle* h,\n    uint32_t min_blink_ms,\n    uint32_t long_blink_ms,\n    uint32_t max_blink_ms,\n    uint32_t double_gap_ms,\n    uint32_t refractory_ms);\n```\n\n* `min_blink_ms`: Minimum duration to count as a blink\n* `long_blink_ms`: Threshold for long blinks\n* `max_blink_ms`: Max duration before ignoring as noise\n* `double_gap_ms`: Time window for detecting double blinks\n* `refractory_ms`: Cooldown time after a blink before accepting another\n\n#### EMA\n\n```c\nvoid blinkd_set_ema_alpha(BlinkdHandle* h, float alpha);       // default: 0.01\nvoid blinkd_set_noise_alpha(BlinkdHandle* h, float alpha);     // default: 0.02\n```\n\nThese control how quickly the algorithm adapts to baseline changes or noise. Smaller = smoother, but slower.\n\n#### Wink detection\n\n```c\nvoid blinkd_set_wink_min(BlinkdHandle* h, uint32_t wink_min_ms);\n```\n\nThis sets the **minimum duration** for a one-eye blink to qualify as a wink.\n\n#### Presets\n\nTo simplify tuning, you can use one of the built-in presets:\n\n```c\nvoid blinkd_set_preset(BlinkdHandle* h, BlinkdPreset preset);\n```\n\nAvailable presets:\n\n* `BLINKD_PRESET_LOW`: For noisy input (e.g. low-res cams, shaky face)\n* `BLINKD_PRESET_HIGH`: For clean input, fast detection\n* `BLINKD_PRESET_BALANCED` *(default)*: Safe middle ground\n\n### Example: Custom configuration\n\n```c\nBlinkdHandle* h = blinkd_create(init_open);\nblinkd_set_thresholds(h, 2.8f, 1.4f);\nblinkd_set_timing(h, 50, 300, 750, 250, 50);\nblinkd_set_ema_alpha(h, 0.02f);\nblinkd_set_noise_alpha(h, 0.03f);\nblinkd_set_wink_min(h, 70);\n```\n\n## Build \u0026 run\n\n```bash\ncmake --build . --config Release\n# Stream samples via stdin (time_ms openL openR), broadcast to localhost:7777\n./blinkdctl\n```\n\nClients (apps, game engines, etc.) can easily consume them.\n\n## Limitations\n\n**Blinkd** focuses on being tiny and dependency-free.\n\n- No advanced processing pipeline or fallbacks\n- No advanced head-pose correction techniques, smoothing filters and algorithms\n- No customer support\n\n**All of these features are available in the [Ollo SDK](https://ollosdk.com/).**\n\n## Upgrading to Ollo SDK\n\nIf you outgrow the basic EAR-only detector, **[Ollo SDK](https://ollosdk.com/)** offers better performance and seamless migration from the Blinkd SDK, letting you scale to production with **minimal changes**.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F25thr%2Fblinkd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F25thr%2Fblinkd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F25thr%2Fblinkd/lists"}