𓅃 Amun — a Breath–Computer Interface
Same acronym. No electrodes. Just air.
Pilot the falcon of Horus across the Egyptian sky using nothing but your breath. Soft breath glides · a hard exhale climbs · silence dives into gravity.
A ground-up reimagining of
CoffeeIsAllYouNeed/Invisible-Driver. The original was a Brain–Computer Interface — drive a car with EEG brain waves through an Arduino, electrodes and a clustering model. Amun keeps the exact acronym and changes the principle: here BCI means Breath–Computer Interface. The signal source becomes the microphone every device already has — no electrodes, no Arduino, fully offline.
Why this is "the same idea, but better"
| Invisible-Driver (original) | Amun (this repo) | |
|---|---|---|
| Principle | Brain waves (EEG) | Breath (acoustic) — and optionally brain, see below |
| Hardware | Arduino + BioAmp + gel electrodes | None — any microphone |
| Acronym | Brain–Computer Interface | Breath–Computer Interface |
| Game | drive a racing car | fly the falcon of Horus over Egypt |
| Dependencies | Python ML stack + serial | zero for the core game |
| Runs offline | partly | 100% offline |
The science still lives in Python — a real ingestion → preprocessing → features → classify → engine pipeline with k-means calibration — but the microphone moves
into the browser, so the whole thing runs with no third-party dependencies.
Quickstart
git clone https://github.com/Lord1Egypt/Amun
cd Amun
python -m amun # opens the game in your browser
Allow the microphone and breathe. No microphone? Press and hold SPACE.
Headless / no browser (great for a quick check or CI):
python -m amun --source sim --duration 5 --no-input
How the breath becomes flight
microphone ─▶ ingestion ─▶ preprocessing ─▶ features ─▶ classify ─▶ engine ─▶ render
(browser) loudness noise-floor + RMS / k-means falcon canvas
frames EMA smoothing ZCR anchors physics
- Silence → no thrust → gravity → the falcon dives.
- Soft breath → partial thrust → the falcon glides level.
- Hard exhale → full thrust → the falcon climbs.
Deep dive: docs/ARCHITECTURE.md ·
docs/SIGNAL_PIPELINE.md ·
docs/CALIBRATION.md.
Optional hardware (it works without any)
Amun is "the hidden one" — it accepts any invisible signal, but always falls back to the microphone if no hardware is present.
| Tier | Input | What you need |
|---|---|---|
| 0 · default | breath via browser mic | nothing |
| 1 · DIY | the Amun Amulet — breath sensor + OLED + RGB + buzzer | Arduino/ESP32 + parts |
| 2 · Brain | a NeuroSky MindWave (real EEG attention) | the headset |
amun --source serial --serial-port /dev/rfcomm0 # Amun Amulet (breath)
amun --source neurosky --serial-port /dev/rfcomm0 # NeuroSky (brain)
# if the device isn't found, Amun automatically uses the browser mic
Tier 2 brings the original "control with your mind" idea back as a bonus — so Amun
is a superset of Invisible-Driver. Full build, BOM and wiring:
docs/HARDWARE.md.
Project layout
src/amun/ engine · ingestion · preprocessing · features · classify · calibrate · server · thinkgear
src/amun/templates/ the browser game (Web Audio mic + canvas renderer)
model/ your calibration profile (JSON)
tools/ sample data · demo-gif · banner/logo · Gemini asset gen · test runner
tests/ pytest suite (engine · features · classify · websocket · server · thinkgear)
notebooks/ breath-signal exploration + honest clustering metric
docs/ architecture & guides hardware/ Amun Amulet sketch + BOM
Tests
pip install -e ".[dev]"
python tools/test_all.py # data + calibration + headless run + pytest (exit 0)
See TESTING.md. Everything runs with no microphone and no hardware.
Honesty note
All performance/quality numbers (e.g. the calibration silhouette score) are measured on bundled, reproducible data — never invented. Your own calibration produces a score for your microphone and breathing.
Status
Live build log: CHECKPOINTS.md.
License
MIT © 2026 Mohamed Mounir (Lord1Egypt)
Metadata
Release files for amun-bci 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| amun_bci-1.0.0.tar.gz | 38.7 kB | Without provenance | Details for amun_bci-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| amun_bci-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for amun_bci-1.0.0-py3-none-any.whl |
Total release size: 73.6 kB
Release files / amun_bci-1.0.0.tar.gz
| Download URL | amun_bci-1.0.0.tar.gz |
|---|---|
| Size | 38.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
21ce49fa826f4d292a52a5703467860d02b080522c4481d71de49528f2879dc7
|
|
BLAKE2b-256 checksum How to use checksums |
96c1f2f0c389d8da4028034e0e5190ddda5bdffdf0122353f12e6905a60e948b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.13
|
Release files / amun_bci-1.0.0-py3-none-any.whl
| Download URL | amun_bci-1.0.0-py3-none-any.whl |
|---|---|
| Size | 34.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
223b0077a131151468caf09588b7018a1afa4b2e911c79e5b076533a8bf1a34a
|
|
BLAKE2b-256 checksum How to use checksums |
7a1e5d6caed95a9ec589b62e9a68be0654376f856d56b16199e1d7ecb850c255
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.13
|
Security for amun-bci 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.