Open-source desktop overlay engine for Windows.
Place local GIFs, APNGs, WebM videos, static images, sprites, frame animations, spritesheets, and HUD-style 2D assets directly on your desktop.
Website | Microsoft Store | Releases | itch.io | Demo Video
OpenAnima is a lightweight Windows desktop app for running local 2D visual assets as independent overlay windows. It is built for desktop pets, animated GIF overlays, APNG animations, WebM video overlays, pixel-art characters, sticker-like images, sprite animations, small HUD widgets, and experimental desktop customization.
Each overlay can be moved, scaled, hidden, locked, made click-through, kept on top, and restored on the next launch. OpenAnima stores its runtime state locally and does not require an online service.
OpenAnima v1.1.0 adds multi-monitor overlay support so GIFs, APNGs, WebM videos, and other desktop overlays can be moved across multiple displays. Monitor selection is available in the main UI and overlays restore safely with fallback placement when display layouts change.
OpenAnima is not only a GIF player. It is a small desktop overlay engine with an asset library, metadata setup workflow, active overlay inspector, diagnostics, recovery tools, and support for multiple 2D asset formats.
The package version is defined in openanima_app/version.py and exposed as:
import openanima_app
print(openanima_app.__version__)
- Multiple independent transparent desktop overlay windows.
- Drag, scale, opacity, and animation speed controls.
- Lock, click-through, always-on-top, show/hide, and remove controls.
- Local asset library with import workflows for files, folders, and asset packs.
- Asset pack selection from the Library page.
- Single asset import, asset folder import, folder-based asset pack import, and
.zipasset pack import. - Asset analyzer and setup dialog for configuring metadata-driven assets.
- Manual type override when automatic detection needs correction.
- Inspector controls for selected overlays.
- Optional per-overlay actions for opening files, folders, URLs, or applications.
- Ctrl + double click overlay action trigger.
- Optional movement settings with velocity, screen-edge bounce, gravity, and friction.
- Persistent sessions saved to
config.json. - UI state persistence for control panel visibility, window geometry, and last selected page.
- Multi-monitor overlay support with cross-display dragging and monitor selection in the main UI.
- Safer overlay placement and fallback behavior when display layouts change.
- Overlay state persistence for visibility, actions, movement settings, selected animation, and composite UI runtime values.
- Safer config loading with schema versioning, atomic writes, and corrupt-config backup.
- Recovery tools for hidden, locked, click-through, or off-screen overlays.
- System tray recovery actions.
- File logging in
logs/openanima.log. - Diagnostics page for packaged builds.
- PyInstaller packaging support.
| Asset type | Status | Notes |
|---|---|---|
| GIF | Supported | Animated with Qt movie playback. |
| Static images | Supported | .png, .jpg, .jpeg, and .webp. Transparent PNGs work well. |
| APNG | Supported with fallback | APNG frames are decoded when available; unreadable animation falls back safely. |
| WebM | Supported | Playback uses Qt Multimedia. Codec and alpha behavior depend on the system backend. |
| Frame folders | Supported | Ordered image frames with optional asset.json metadata. |
| Sprite strips | Supported | Single-row or single-column sprite strips with frame settings, crop, preview, and export tools. |
| Spritesheets | Supported with metadata | Named animations are configured in asset.json. |
| Composite UI / HUD | Supported with metadata | Layered image assets with runtime value sliders. |
Example frame-folder asset:
Idle/
idle_01.png
idle_02.png
idle_03.png
asset.jsonExample asset.json:
{
"type": "frame_animation",
"name": "Idle",
"fps": 12
}- Open the Control Panel.
- Go to Library.
- Choose an asset pack or stay in Root assets.
- Click Import Asset, Import Asset Folder, or Import Asset Pack.
Select an asset pack, review thumbnails, and click Add to Desktop.
- Review the detected type in the Asset Setup dialog.
- Confirm the metadata or choose a manual type.
The setup dialog runs before assets enter the library. Supports APNG, sprite strips, spritesheets, frame folders, and static images.
Sprite strip assets have additional configuration for frame count, FPS, crop, and loop settings.
Composite UI assets have a layer builder with runtime value sliders for health bars, status indicators, and HUD elements.
- Select the imported asset and click Add to Desktop.
- Go to Desktop.
- Select the active overlay.
- Use the Inspector to edit scale, opacity, speed, visibility, click-through, always-on-top, actions, and movement settings.
Select an overlay to adjust scale, opacity, speed, lock state, click-through, always-on-top, actions, and movement.
OpenAnima includes an experimental Local API for same-machine automation. It is intended for streamer tools, VTuber setups, OBS helper scripts, scene switching, and desktop automation utilities that need to control local overlays.
Safety defaults: the Local API is disabled by default, binds only to 127.0.0.1, and every modifying POST request requires X-OpenAnima-Token. External tools should prefer persistent_id for stable overlay targeting; runtime_id is session-only, and api_alias is an optional friendly name.
PowerShell setup:
$base = "http://127.0.0.1:8765"
$token = "YOUR_TOKEN"
$headers = @{ "X-OpenAnima-Token" = $token }Test status:
Invoke-RestMethod -Uri "$base/api/status" -Method GetList overlays:
Invoke-RestMethod -Uri "$base/api/overlays/all" -Method GetSpawn an overlay:
$body = @{ asset_path = "C:/path/to/asset.gif"; x = 200; y = 200; scale = 1.0; opacity = 1.0 } | ConvertTo-Json
$overlay = Invoke-RestMethod -Uri "$base/api/overlays/spawn" -Method Post -Headers $headers -ContentType "application/json" -Body $body
$id = $overlay.idUpdate an overlay:
$body = @{ x = 300; y = 400; scale = 1.25; opacity = 0.8; visible = $true } | ConvertTo-Json
Invoke-RestMethod -Uri "$base/api/overlays/$id/update" -Method Post -Headers $headers -ContentType "application/json" -Body $bodySave a scene:
$body = @{ name = "coding_scene" } | ConvertTo-Json
Invoke-RestMethod -Uri "$base/api/scenes/save" -Method Post -Headers $headers -ContentType "application/json" -Body $bodyInspect recent events:
Invoke-RestMethod -Uri "$base/api/events/recent" -Method GetFull Local API documentation and scripts are in Local API examples and reference.
If port 8765 is already in use, OpenAnima falls back to another local port. Use the URL shown on the Local API page.
Known limitations:
- The API is experimental and may change before a stable automation contract is declared.
- There is no WebSocket endpoint yet. Use
GET /api/events/recentfor the current in-memory event buffer. - Some assets require the interactive Asset Setup workflow;
POST /api/assets/importmay return501 interactive_setup_required.
Add animated pets, mascots, pixel characters, ghosts, cats, robots, or small visual toys that live directly on your desktop.
Place health bars, mana bars, stamina bars, counters, status indicators, or ambient UI elements above your normal workspace.
Use animated overlays while recording demos, tutorials, project videos, devlogs, or lightweight streams.
Prototype small animated widgets like focus timers, break reminders, ambient indicators, or visual notes.
Download the Windows build from the GitHub Releases page:
https://github.com/Ertugrulmutlu/OpenAnima/releasesRun:
OpenAnima.exeOn first launch, OpenAnima creates local runtime files beside the executable or source checkout:
assets/
config.json
logs/Requirements:
- Windows
- Python 3.11 or newer recommended
- Dependencies from
requirements.txt
pip install -r requirements.txt
python main.pyFrom the repository root, run:
python -m pytest -vIf you use uv, the command is:
uv run pytest -vUsing python -m pytest from the repo root ensures openanima_app is importable without needing a separate src layout.
Configure the asset folder, startup behavior, and recovery actions for hidden, locked, or off-screen overlays.
Diagnostics shows runtime paths, version info, and recent warnings. Available in packaged builds.
See CHANGELOG.md for release history and RELEASE_NOTES_v1.1.0.md for details about v1.1.
- If OpenAnima fails to launch from source, confirm you are using Python 3.11+ and that
requirements.txtis installed. - If overlays are not visible, check that the desktop is not in a locked or high-DPI scaling mode that hides transparent windows.
- If WebM playback fails, the issue is often the local Qt Multimedia backend or missing system codecs.
- If an overlay is off-screen after a monitor change, use the recovery actions on the Settings or Diagnostics page to center overlays and restore visible windows.
- For Local API errors, confirm the app is bound to
127.0.0.1andX-OpenAnima-Tokenis included in modifying requests.
Contributions are welcome. To get started:
pip install -r requirements.txt
python -m pytest -vCreate issues for bugs or feature requests, and open pull requests for small, focused changes.
- Keep changes targeted to one improvement at a time.
- Include a short description and motivation in the PR.
- Update
CHANGELOG.mdwhen introducing user-visible features or fixes.
OpenAnima is released under the MIT License. See LICENSE.
OpenAnima uses PyInstaller and OpenAnima.spec.
pyinstaller OpenAnima.specExpected release output for a folder-style PyInstaller build:
dist/OpenAnima/OpenAnima.exeThe current spec is configured with icon.ico:
icon=['icon.ico']Depending on the PyInstaller mode produced by the spec, local builds may also emit a single executable at:
dist/OpenAnima.exeRuntime files such as config.json, assets/, and logs/ are created or used next to the running application.
OpenAnima/
├── main.py Application entry point
├── OpenAnima.spec PyInstaller build configuration
├── requirements.txt Python dependencies
├── README.md Project documentation
├── CHANGELOG.md Release history
├── LICENSE MIT license
├── NOTICE.md Asset and rights notice
├── docs/ Website and release materials
├── assets/ Local sample/runtime asset folder
├── tests/ Automated tests
└── openanima_app/
├── app.py Application startup and tray wiring
├── version.py Package version
├── assets/ Asset models, metadata, detection, import, scan, thumbnails
├── overlay/ Overlay windows, flags, menus, movement, serialization
├── rendering/ GIF/APNG/video/frame/sprite/composite rendering helpers
├── runtime/ Paths, logging, config, session, recovery, state, actions
└── ui/
├── asset_setup/ Asset setup dialog and preview helpers
└── control_panel/ Library, Desktop, Editor, Settings, Diagnostics, About pagesOpenAnima stores session state in:
config.jsonSaved state includes:
- asset root
- active overlays
- asset paths and types
- position
- scale
- opacity
- speed
- lock state
- click-through state
- always-on-top state
- visibility
- selected spritesheet animation
- composite UI runtime values
- per-overlay actions
- movement settings
- selected page and control panel UI state
Config saves are atomic. If config.json is corrupted, OpenAnima backs it up as:
config.corrupt.YYYYMMDD_HHMMSS.jsonThe app then starts with safe defaults. Missing saved assets are skipped without preventing valid overlays from loading.
Before publishing a v1 release, run this checklist on a clean Windows machine or clean test folder:
- Launch
OpenAnima.exe. - Confirm the Control Panel opens without a terminal.
- Import a static PNG or JPG and add it to the desktop.
- Import a GIF and confirm it animates.
- Import an APNG and confirm it displays or falls back safely.
- Import a WebM and confirm playback starts when system codecs support it.
- Import a frame-folder animation.
- Import or configure a sprite strip.
- Import or configure a spritesheet with at least one named animation.
- Import or configure a composite UI asset and move a runtime value slider.
- Move, scale, change opacity, and change speed on an overlay.
- Toggle lock, click-through, always-on-top, visible, and hidden states.
- Configure and trigger an overlay action.
- Enable movement settings and test velocity, bounce, gravity, and friction.
- Restart the app and confirm valid overlays restore from
config.json. - Confirm missing saved assets are skipped without crashing.
- Use recovery actions: center all, show all, unlock all, disable click-through.
- Confirm
logs/openanima.logis created and Diagnostics shows useful paths. - Build with
pyinstaller OpenAnima.specand run the packaged executable.
- v1 is focused on 2D overlays for Windows.
- 3D model support is not included in v1.
- APNG playback depends on available decoding support and may fall back.
- WebM playback depends on Qt Multimedia, installed codecs, and backend behavior.
- Transparent WebM alpha is backend-dependent and may not be preserved.
- Sprite strips and spritesheets may require manual metadata or crop correction.
- Composite UI assets may require manual layer alignment.
- Third-party asset packs vary in structure and may need cleanup.
- Cross-platform behavior is not a v1 guarantee.
Reliable 2D overlay engine for Windows, including Library, Desktop, Inspector, Settings, Diagnostics, asset packs, APNG/WebM support, config recovery, and PyInstaller packaging.
Polish and distribution work, including cleaner first-run flow, better examples, issue-driven fixes, stronger asset setup UX, and release packaging improvements.
Richer desktop assets, more creator workflows, reusable presets, and possible experiments with 3D desktop objects.
OpenAnima itself is the desktop overlay engine. Sample, demo, or third-party assets included in screenshots, tests, local asset folders, or demos may belong to their original creators.
Only include, redistribute, or publish assets that you have the rights to use. See NOTICE.md for the repository notice.
Built by Ertugrul Mutlu.
OpenAnima is released under the MIT License. See LICENSE.