FrontEngine
About
FrontEngine is a lightweight and flexible framework designed to simplify automation and visualization tasks.
It provides an intuitive interface and supports multiple media formats for interactive demonstrations.
Features
-
GIFs & Animations
(GIFs may take time to load)
-
Video
-
Website
-
YouTube Showcase
Watch on YouTube
Desktop pet
Spawn an animated sprite that lives on your desktop, from the Pet tab.
- Sprites — pick a single GIF/WebP/PNG, or a pet pack folder whose file
names map to states:
walk,idle,sleep,climb,fall,drag(missing states fall back towalk). - Behaviour — walk on the floor with gravity (throw it and it bounces), wander freely, or chase the cursor. Floor pets can climb screen edges and stand on the top edge of other windows.
- Life — mood, fullness and an affection level that persist between runs; the pet grows as it levels up, chats in speech bubbles, naps while you are away, and warns you about a low battery.
- Interaction — drag it around, right-click to clone/feed/set a reminder, and drop a file onto it: an image or pet pack becomes its new look, anything else is eaten. What it eats matters — an archive is a feast, music cheers it up more than it fills, a document is a modest meal, and a binary is too hard to chew.
- Tag — with two or more pets on screen, tick Play tag with each other and one becomes "it": it walks toward its nearest neighbour while the others run the other way, and catching someone passes the tag on.
- React to audio — the pet pulses to your speakers' output level. It reads
only the Windows output meter (WASAPI
IAudioMeterInformation); no audio is captured or recorded. Peaks are smoothed with an RMS window and a fast-attack/slow-decay envelope so the pulse breathes instead of flickering. On multi-monitor setups each pet follows the audio endpoint that matches its own screen, falling back to the default output device.
Audio features are Windows-only and degrade to "no pulse" elsewhere.
Focus
Two overlays for when the screen is competing with your work, both on the Focus tab:
- Dim background windows — everything except the window you are working in is shaded, at an adjustable strength. Off Windows, where the active window cannot be identified without a native binding, it shades the whole screen.
- Cover a distraction — mask a strip of the screen: the taskbar, a notification corner, an edge, or all of it.
Both pass clicks through, so what they cover still works — it just stops pulling your eye.
Wallpaper
Play a folder of images and animations beneath every window, from the Wallpaper tab:
- A playlist per monitor — each screen points at its own folder, changes on its own timer, and can be shuffled or read recursively.
- React to audio — the wallpaper can pulse with your speakers' output level, using the same meter-only reading as the pet (no audio is captured).
Widgets
Four desktop widgets on the Widgets tab:
- Audio spectrum — bars or a ring, log-spaced bands, smoothed with a
fast-attack/slow-decay follower and peak markers that drift down.
Unlike the pet and the wallpaper, which read only the output meter, a spectrum needs the actual samples to compute frequencies — so this one captures the system output stream. The samples are analysed in memory, never written to disk or sent anywhere, and capture stops the moment you stop the spectrum. Windows only.
- Now playing — the current track from Windows' media controls when the
optional
winsdkbindings are installed; otherwise the name of the app that is actually making sound. - System monitor — CPU, memory and disk as small sparklines. An average hides a stall; a line does not.
- Sticky notes — editable cards that float above every window and keep their text, colour and position between sessions.
Tools
Measuring and capture tools on the Tools tab:
- Colour picker / pixel ruler / protractor — click to sample or measure;
the result is copied straight to the clipboard as
#rrggbb,rgb(...),hsl(...)or a CSS custom property. - Region capture — drag out an area; it lands on the clipboard and can be saved to a file.
- Pin a window — keep another program's window on top, or fade it, while you work against it. Only stacking and opacity are touched, never window content. Windows only.
- Camera — your webcam in a circle, rounded box or rectangle, shown locally and never recorded.
Rules
Things that decide for themselves, from the Settings menu:
- Smart pause — stand the overlays down while a fullscreen app is running, while the machine is on battery, or while a named app has focus.
- App profiles — apply a saved preset when you switch to a given app.
- Reminders — every N minutes, or once a day at a set time, shown as a toast that closes itself.
The control center also carries a quality tier (high / balanced / saver) that caps every overlay's refresh rate and drops its render resolution.
Community content
-
Steam Workshop — subscribed items are picked up from Steam's own
steamapps/workshop/contentfolder: presets are imported and pet packs are listed with their paths, from Presets → Import Workshop content. Publishing to the Workshop needs the Steamworks SDK and is not built in. -
Plugins — a
plugins/folder can add its own tabs, either through aFRONTENGINE_TABSmapping or aregister(registry)hook.A plugin is Python and runs with the same privileges as FrontEngine — it cannot be sandboxed. Loading is off by default (Settings → Load plugins), every load is logged, and one broken plugin is skipped rather than stopping the app. Only install plugins you trust.
Install
-
System Requirements
- Python 3.10+
- Windows 10/11 is the primary target; macOS and Linux are supported but may need extra OS dependencies.
-
From PyPI
pip install frontengine
-
Pre-built binaries
Development
- Requires Python 3.10+.
- Install the dev toolchain:
pip install -r dev_requirements.txt pip install -e .
- Run the unit smoke tests:
python ./tests/unit_test/start/start_front_engine.py python ./tests/unit_test/start/extend_front_engine.py
- Contributions and pull requests are welcome!
Continuous Integration & Release
This repository ships two GitHub Actions workflows:
| Workflow | Trigger | Purpose |
|---|---|---|
CI (.github/workflows/ci.yml) |
Push / PR to main or dev, daily cron |
Matrix smoke test across Python 3.10 / 3.11 / 3.12 on Windows |
Release (.github/workflows/release.yml) |
A pull request is merged into main (or manual dispatch) |
Auto-bumps the version in stable.toml/pyproject.toml, commits the bump back to main, swaps stable.toml → pyproject.toml, builds sdist + wheel, uploads to PyPI as frontengine via twine, creates a GitHub release tagged v<version> |
Publishing only happens on merge to main — pushing to dev runs CI but
never publishes. On merge, the workflow automatically bumps the patch
segment of the version (configurable via manual dispatch: patch / minor
/ major), commits the bump back to main with [skip ci], then builds,
uploads, and releases under the new version. Both the PyPI upload and the
GitHub release see the bumped version, not the previous one.
Cutting a new release
- Merge a pull request into
main— the patch version bumps automatically. - That's it. PyPI publish and GitHub release happen in one workflow run.
For a minor or major bump, trigger the workflow manually via Actions →
Release → Run workflow and pick the bump segment. That path also works
when you need to re-run a failed publish without a new merge.
Required repository secrets
| Secret | Used by | Contents |
|---|---|---|
PYPI_API_TOKEN |
release.yml |
A PyPI API token scoped to the frontengine project |
The workflow uses __token__ as the twine username, so only the token itself
needs to be stored.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file frontengine-1.0.37.tar.gz.
File metadata
- Download URL: frontengine-1.0.37.tar.gz
- Upload date:
- Size: 251.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.12.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a54e2a90f551f25ab712953d36ca197f190b780c938b5502916cf7077702019a
|
|
| MD5 |
9c180f17db9d9df042b2955609e71aa1
|
|
| BLAKE2b-256 |
2f2a606fbce8b8aaf864df47470eee7009f1287e27d05f8a856846ff6d7f5aec
|
File details
Details for the file frontengine-1.0.37-py3-none-any.whl.
File metadata
- Download URL: frontengine-1.0.37-py3-none-any.whl
- Upload date:
- Size: 330.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.12.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4ff600c5b1c84e8334cf6b579ce03851e45244f4bcc13b6b137626a0387b205a
|
|
| MD5 |
9adda1b65089076e7ad2c597d7bcc234
|
|
| BLAKE2b-256 |
aeea2972fbf4a3053f1fd0001e6fc31e6da3117898d029257040acc3512b60f5
|
