Skip to main content
Amun — a Breath–Computer Interface

𓅃 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.

Amun gameplay

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)

Amun

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)

Source distribution for amun-bci 1.0.0
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)

Table of built distributions (wheels) for amun-bci 1.0.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page