Your emoji, sticker and GIF library — one keystroke away from any application.
简体中文 · English
GIFManager keeps the pictures you send a hundred times a day — reaction GIFs, stickers, plain emoji, the odd one-line snippet — in a library on your own disk. Hit the global hotkey, click a card, and it is on the clipboard of whatever you were typing into, ready to paste or already pasted.
Nothing to sign up for. The library is a SQLite database next to your files, and the sending path makes no network request at all.
A library you arrange. Image groups hold pictures and text groups hold snippets; the two never mix, so the right-hand column is never ambiguous. Import from files or from a whole folder, recursively — anything that is not a GIF yet gets converted on the way in (ffmpeg for animated sources, Pillow for stills), so a folder of PNGs becomes a GIF library without a second tool. Search the open group as you type. Sort by import time, name, or how often you actually send a sticker: that last one is measured, not guessed, and the counter goes up on every send.
Sending that stays on the keyboard. The hotkey takes a lone key (F10) or a combination
(Ctrl+Alt+F8). A bare key is allowed on purpose — a tray utility whose only shortcut demands
a modifier is harder to use, not safer. A click puts the image on the clipboard as image data
or as its file path, which is the form QQ and WeChat accept directly; which one is a setting.
Turn on auto-paste and the paste keystroke goes back to the window you came from, so the whole
interaction is hotkey → click → already in the chat. The tray icon shows, hides and quits the
app. On Windows, launching it again says one is already running; on Linux, where the shortcut
belongs to the compositor, it passes --toggle, --show, --hide or --quit to the running
copy instead.
Editing a whole library at once. Edit mode turns the grid into a selection surface: click to toggle a card, drag to paint over several, select all or none, then delete or move the lot together. Cards can also be dragged into an order by hand. Text stickers cover the things you send that are a sentence rather than a picture, with separate limits for one-line and multi-line stickers.
Quiet by default. Dark and light themes apply the moment you pick one — no restart, no confirmation dialog. HarmonyOS Sans SC ships with the app in six weights, so the grid and its dialogs measure the same on every machine instead of inheriting whatever the host installed. The palette stays low contrast: base surfaces sit a few percent apart and only the selected card is bright, because a window you open dozens of times a day has no business shouting. Frameless, remembers the last group and the window geometry, can stay on top, can start with the system.
Fast past a thousand stickers. Frames decode on a worker pool, never on the thread that draws, and are cached under a pixel budget. Only the animations on screen play; everything else holds a still frame. The decode queue is newest-first and drops requests you have already scrolled past, so a fast flick through a big group does not leave the visible row waiting behind rows you left.
Playback needs a native decoder. make native builds the Rust one from native/, and passing
--install to scripts/build-native.* copies it into resources/ so a packaged build can carry
it. The C helper compiled from resources/gifdec.c is the other route. Without either, GIF cards
show their first frame and stay still.
| Windows | Linux | macOS | |
|---|---|---|---|
| Interface (Qt Quick) | ✅ | ✅ | |
| Frameless window, rounded corners | ✅ DWM | ✅ | |
| Global hotkey | ✅ RegisterHotKey |
✅ X11 · Wayland: bind it in the compositor | ❌ not implemented |
| Clipboard send + auto-paste | ✅ SendInput |
xdotool · Wayland forbids synthetic input |
|
| Tray icon | ✅ | ✅ needs a StatusNotifier host | |
| Start with the system | ✅ registry | ✅ XDG autostart | |
| Second launch is blocked | ✅ mutex | ✅ socket | ❌ a second copy starts |
Second launch forwards --toggle |
❌ | ✅ | ❌ |
The shipped build has only been run on Windows and on Arch + niri (Wayland). Two things bite on
Wayland. The compositor owns global shortcuts, so the application cannot register one: bind a key
to gifmanager --toggle instead, and packaging/niri-binds.kdl has a working example. That
binding is what the second-launch command channel exists for, and why the channel is Linux-only.
The other trap is the desktop entry, which has to be installed as gifmanager.desktop because
the XDG portal looks the application up by that name before it hands out an app id;
scripts/install-desktop-entry.sh does it.
The macOS backend exists but has never been executed — not by CI, not by hand — so treat it as unproven, not supported. Its Carbon hotkey backend says out loud that it is not implemented instead of pretending. With no single-instance backend there, a second launch simply starts a second copy.
Releases are built by hand from .github/workflows/build.yml and attached to the release page.
| Platform | File | How |
|---|---|---|
| Windows | GIFManager-Setup-<version>.exe |
Inno Setup installer, per-user by default |
| Windows | GIFManager-<version>-win64.zip |
Portable: unpack and run, data stays beside the executable |
| Debian/Ubuntu | gifmanager_<version>_amd64.deb |
sudo apt install ./gifmanager_*.deb |
| Any Linux | GIFManager-<version>-linux-x86_64.AppImage |
chmod +x, then run |
| Any Linux | GIFManager-<version>-linux-x86_64.bin |
Self-extracting installer, --help for options |
| Arch | gifmanager-<version>-1-x86_64.pkg.tar.zst |
sudo pacman -U |
| Flatpak | GIFManager-<version>-x86_64.flatpak |
flatpak install ./GIFManager-*.flatpak — experimental, built only on request |
From source it is a venv, one requirements file and an entry point:
git clone https://github.com/LwoSnow/GIFManager.git
cd GIFManager
python -m venv .venv
# Windows: py -3.12 -m venv .venv (3.12, not whatever `python` is)
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python -m gifmanagerContributors want requirements-dev.txt instead; it pulls in the requirements file and adds
PyInstaller. pip install -e . installs the gifmanager and gifmanager-qml commands; without
it, run the interface with python -m gifmanager or apps/gifmanager_qml.py.
Use 3.12 for the virtual environment even though the package needs only 3.10: Pillow's pinned
wheel is built for 3.12 specifically, and a 3.14 interpreter from PATH fails with an _imaging
import error that never mentions the version. PySide6 itself ships a 3.10+ wheel, so it is the
Pillow pin that decides this. make env checks it first and tells you the fix.
python -m gifmanager and gifmanager-qml both start the QML interface. The plain gifmanager
command starts the older Qt Widgets shell, which is kept around for comparison and is not what
releases run.
Playback is the one optional part: make native (or scripts/build-native.ps1 on Windows,
scripts/build-native.sh elsewhere) builds the Rust decoder. Without it the app still opens and
browses; GIF cards just stay on their first frame.
emoji.db, the emojis/<group>/ files and settings.json sit together in one directory. Which
directory depends on how you started the program:
| How you run it | Windows | Linux | macOS |
|---|---|---|---|
| From source | %APPDATA%\GIFManager |
~/.local/share/GIFManager |
~/Library/Application Support/GIFManager |
| Packaged build | data\ beside the executable |
data/ beside the executable |
data/ beside the executable |
A packaged build keeps the library next to its executable, and falls back to the per-user directory
in the row above when that place is read-only — an AppImage mount, a system-wide install. The
Windows installer defaults to %LOCALAPPDATA%\Programs\GIFManager, so its library lands in
…\GIFManager\data. Logs never move: %LOCALAPPDATA%\GIFManager\logs on Windows,
~/.cache/GIFManager/logs on Linux, ~/Library/Logs/GIFManager on macOS.
GIFMANAGER_DATA_DIR overrides the library directory and leaves the logs where they are, which is
how you keep two profiles apart or run from a USB stick. A library in the per-user directory
survives uninstalling; one in the install folder goes when you delete the folder.
make build-qml # PyInstaller onedir bundle in dist/GIFManagerThat is the QML front-end. make build builds the retired Qt Widgets bundle from a spec that
excludes Qt Quick, so it produces a working program without the interface this repository
documents.
The release workflow runs only when you trigger it: an installer on every push is noise, and one
run costs the better part of an hour. It reads the version from gifmanager/__init__.py, so an
artifact can never carry a number the code does not, and it builds one bundle per platform and
wraps that bundle into every format in the table above. Ticking create_release publishes a
draft release with all of them.
Pushing this working directory is not the same as publishing it: it holds a virtual environment,
Rust build output, PyInstaller output and a few stray test files, about 1.1 GB of things nobody
needs. make-archive.bat builds a clean zip from tracked files and drops the six things that do
not belong in an upload. Upload the contents of the zip.
make check # environment, layering, style, translations, batch files, unit tests
make smoke # the offscreen smoke suite; needs Qt installed
make run-qml # run the interface from sourcePass your interpreter explicitly if the venv is not active: make check PYTHON=.venv/Scripts/python.exe
on Windows, PYTHON=.venv/bin/python elsewhere.
make check is not decoration, and every check refuses one specific class of mistake:
| Check | It refuses |
|---|---|
tools/check_environment.py |
a Pillow that cannot import; warns when the interpreter is not the 3.12 the wheels were verified on |
tools/check_layers.py |
a core module importing Qt, or front-end logic leaking downwards |
tools/check_style.py |
lines over 100 columns, tabs, trailing whitespace, a comment block with no Chinese in it |
tools/sync_language_keys.py |
a translation table missing a key another table has |
tools/check_batch_encoding.py |
a .bat that is not ASCII with CRLF endings |
make test |
a broken import or a lost row; 125 unit and integration tests, Qt offscreen |
CI runs the layering, style, translation and unit checks plus tests/smoke_qml.py before
anything is packaged. make probe-services is separate because it needs a real desktop: the
offscreen platform has no tray and no hotkey to register.
make is GNU Make; on Windows it needs MSYS2 or Git Bash, because the recipes use POSIX shell
syntax (QT_QPA_PLATFORM=offscreen python …), which cmd.exe cannot run. Every target is one
command in the Makefile you can run yourself; check and smoke just run the others in a row.
docs/ holds the longer pieces: the layering and how the QML front-end is put together
(ARCHITECTURE.md, QML_FRONTEND.md), platform setup and troubleshooting (RUNNING.md), and
what is still missing (COMPLETION_CHECKLIST.md).
The interface speaks English and Simplified Chinese, switched at runtime under Settings →
General → Language. Translations are plain tables in resources/language/; to add one, copy
en_US.json to <locale>.json, translate the values and never the keys, then run
python tools/sync_language_keys.py. The file name is the locale the settings page offers, so a
new file is selectable immediately.
CONTRIBUTING.md has the comment, commit and pull-request conventions.
MIT — see LICENSE. Use it, fork it, ship it.
HarmonyOS Sans SC ships in resources/fonts/ in six weights, redistributed under its own font
licence; the licence text is not bundled, so add it before republishing the fonts in a fork. The
component set follows the ideas in SWB-QML-UI (MIT) and
shadcn's look, ported to QML rather than linked, because PySide6 ships no Qt CMake package. The
interaction details — press feedback, interruptible motion, contrast as state, optical type —
come from Apple's Designing Fluid Interfaces and Emil Kowalski's writing on interface polish.
LwoSnow Sunroin9

