{"id":44786498,"url":"https://github.com/suhoiyis/gui-for-linux-wallpaperengine","last_synced_at":"2026-04-01T23:02:56.353Z","repository":{"id":334402052,"uuid":"1138336302","full_name":"Suhoiyis/gui-for-linux-wallpaperengine","owner":"Suhoiyis","description":"gui for https://github.com/Almamu/linux-wallpaperengine","archived":false,"fork":false,"pushed_at":"2026-03-22T13:13:52.000Z","size":25550,"stargazers_count":0,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-22T18:32:54.207Z","etag":null,"topics":["gtk4","linux","python","wallpaper-app-gui-linux","wallpaper-engine"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Suhoiyis.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-20T14:44:21.000Z","updated_at":"2026-02-24T06:35:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Suhoiyis/gui-for-linux-wallpaperengine","commit_stats":null,"previous_names":["suhoiyis/gui-for-linux-wallpaperengine"],"tags_count":66,"template":false,"template_full_name":null,"purl":"pkg:github/Suhoiyis/gui-for-linux-wallpaperengine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Suhoiyis%2Fgui-for-linux-wallpaperengine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Suhoiyis%2Fgui-for-linux-wallpaperengine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Suhoiyis%2Fgui-for-linux-wallpaperengine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Suhoiyis%2Fgui-for-linux-wallpaperengine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Suhoiyis","download_url":"https://codeload.github.com/Suhoiyis/gui-for-linux-wallpaperengine/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Suhoiyis%2Fgui-for-linux-wallpaperengine/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292788,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gtk4","linux","python","wallpaper-app-gui-linux","wallpaper-engine"],"created_at":"2026-02-16T09:39:57.177Z","updated_at":"2026-04-01T23:02:56.341Z","avatar_url":"https://github.com/Suhoiyis.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cimg src=\"pic/icons/GUI_rounded.png\" alt=\"Logo\" width=\"128\" height=\"128\" style=\"border-radius: 20px;\"/\u003e\u003cbr\u003e\n  LINUX WALLPAPER ENGINE GUI\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003eA modern GTK4 graphical interface for managing and applying Steam Workshop live wallpapers on Linux.\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/Suhoiyis/gui-for-linux-wallpaperengine/releases/latest\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/v/release/Suhoiyis/gui-for-linux-wallpaperengine?color=success\u0026label=Release\u0026style=flat-square\" alt=\"Latest Release\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/Suhoiyis/gui-for-linux-wallpaperengine/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/Suhoiyis/gui-for-linux-wallpaperengine?style=flat-square\u0026color=blue\" alt=\"License\"\u003e\n  \u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Platform-Linux-lightgrey?style=flat-square\u0026logo=linux\" alt=\"Platform\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Python-3.10+-blue?style=flat-square\u0026logo=python\u0026logoColor=white\" alt=\"Python Version\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/GUI-GTK4-4A86CF?style=flat-square\u0026logo=gnome\u0026logoColor=white\" alt=\"GTK4\"\u003e\n\u003c/p\u003e\n\n\n\u003cp align=\"center\"\u003e\n    \u003cstrong\u003eEnglish\u003c/strong\u003e | \n    \u003ca href=\"README_ZH.md\"\u003e简体中文\u003c/a\u003e\n\u003cp\u003e\n\n\u003e [!NOTE]\n\u003e 🌐 Language Note: This English documentation was generated by AI and translating tools. While we strive for accuracy, some technical nuances might be lost. If you spot any linguistic errors, please feel free to  or submit a Pull Request. Your help is much appreciated!\n\n\u003e Built on [Almamu/linux-wallpaperengine](https://github.com/Almamu/linux-wallpaperengine) backend, optimized for GNOME / Wayland desktop environments.\n\n\u003e ## 🚀 Architecture Upgrade Announcement\n\u003e **We are rewriting the entire project in Rust!**\n\u003e ### ⚡ Performance Revolution\n\u003e- We are planning a major architecture upgrade — a complete core rewrite in Rust. By replacing the existing Python architecture, we will bring you:\n\u003e \n\u003e   - 🚀 Native-level Performance — Eliminate interpreter overhead, significantly faster execution\n\u003e   - 💾 Lower Resource Usage — Reduced memory footprint, lightweight operation\n\u003e   - 🔒 Enhanced Type Safety — Compile-time checks, fewer runtime errors\n\u003e   - 🛠️ Better Concurrency Support — Full utilization of multi-core processors\n\u003e \n\u003e - 📍 View Progress: Switch to [main-pre](https://github.com/Suhoiyis/gui-for-linux-wallpaperengine/tree/main-pre) branch for the latest development updates\n\u003e - 📥 Try Early Builds: Download the latest builds from [Pre-release](https://github.com/Suhoiyis/gui-for-linux-wallpaperengine/releases) (Assets)\n\u003e \n\u003e - ⚠️ Note: The Rust version is currently in development and may be unstable. Please continue using the stable version for production environments.\n\n\n\u003cdiv align=\"center\"\u003e\n  \u003ctable width=\"100%\"\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\"\u003e\u003cb\u003eDark Mode\u003c/b\u003e\u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\u003cb\u003eLight Mode\u003c/b\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003cimg src=\"docs/assets/main-ui.png\" width=\"400\" style=\"display: block;\"\u003e\n      \u003c/td\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003cimg src=\"docs/assets/light-theme.png\" width=\"400\" style=\"display: block;\"\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\u003c/div\u003e\n\n## ✨ Features\n\n### Core Features\n\n- 🎨 **Light/Dark Theme Adaptive**: Fully adapts to your system's light or dark theme with automatic accent color sync — no more unreadable text in light mode\n- 🖥️ **Multi-Monitor Support**: Set independent wallpapers for each display, with Link/Unlink mode for bulk or per-screen control\n- 📜 **Playback History**: Automatically tracks your last 30 played wallpapers with timestamps, thumbnails, and one-click replay\n- ✏️ **Nickname System**: Assign custom nicknames to wallpapers for easier identification; supports batch management and search integration\n- 🔍 **Search \u0026 Sort**: Real-time keyword search across titles, descriptions, and tags; sort by name, size, type, or folder ID\n- 📺 **System Tray**: Runs in background with quick actions — random switch, stop, show/hide window\n- ⌨️ **Command-Line Control**: Full CLI support for headless operation and remote control via single-instance architecture\n\n### Advanced Features\n\n- 🪟 **Compact Preview Mode**: A dedicated mini-window (300×700) designed for tiling window managers (Niri, Hyprland, Sway) with circular thumbnail navigation and keyboard shortcuts\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/compact_mode.png\" alt=\"Compact Preview Mode\" width=\"40%\"/\u003e\n  \u003cbr\u003e\n\u003c/p\u003e\n\n\n- 📊 **Performance Monitor**: Real-time CPU/memory tracking with 60-second sparkline charts, per-process breakdown (Frontend, Backend, Tray), and detailed thread lists\n\n    \u003cdetails\u003e\n      \u003csummary\u003eClick to view performance monitoring screenshots\u003c/summary\u003e\n      \u003cdiv align=\"center\"\u003e\n        \u003cbr\u003e\n        \u003cimg src=\"docs/assets/performance-monitor.png\" width=\"70%\" alt=\"Performance Monitor\"\u003e\n        \u003cp\u003e\u003cem\u003eReal-time CPU/memory tracing and process details\u003c/em\u003e\u003c/p\u003e\n      \u003c/div\u003e\n    \u003c/details\u003e\n\n- 📸 **Smart Screenshot**: Silent 4K capture via Xvfb virtual framebuffer, intelligent delay per wallpaper type, resource usage stats, and screenshot history (last 10 captures)\n- 🔄 **Timed Rotation**: Auto-switch wallpapers at configurable intervals; supports random mode and ordered cycling by title, size, type, or folder ID\n- ☰ **Hamburger Menu**: Global application menu with Playback History, Check for Updates, Welcome Guide, Restart, and Quit\n- 🎛️ **Wayland Advanced Tweaks**: Fine-grained control — pause only when active window is fullscreen, ignore specific app IDs (e.g., docks, bars)\n- 📋 **Log Management**: Filter logs by module (Controller/Engine/GUI), copy filtered output for bug reports\n- 🖼️ **GIF Smart Thumbnails**: Intelligent frame extraction (15th frame) to avoid blank/black preview images; supports transparent GIF rendering\n- 🔔 **Update Checker**: Automatic GitHub release checking with smart rate-limit handling and semantic version comparison\n\n## 🚀 Installation\n\n### 1. Install the Backend (Required)\nThis GUI acts as a controller and requires the core rendering engine to be installed on your system.\nFollow the build instructions for [Almamu/linux-wallpaperengine](https://github.com/Almamu/linux-wallpaperengine) and ensure the executable is in your system's PATH:\n\n```bash\nwhich linux-wallpaperengine  # Verify installation\n```\n(Arch Linux users can simply install it from the AUR: yay -S linux-wallpaperengine)\n\n### 2. Install the GUI\nHead over to the [Releases page](https://github.com/Suhoiyis/gui-for-linux-wallpaperengine/releases) to download the latest version, then choose your preferred method:\n\n#### Method A: Arch Linux Package (Recommended for Arch/Manjaro)\n\nWe have not yet published the application to the AUR (it is currently planned), but we now provide a pre-built .pkg.tar.zst package. Installing it with pacman will automatically handle all GUI dependencies.\n\n```Bash\n# Replace with the actual downloaded filename\nsudo pacman -U linux-wallpaperengine-gui-*-x86_64.pkg.tar.zst\n```\n\nOnce installed, you can launch it from your application menu.\n\n\n#### Method B: AppImage (Universal Linux)\nA portable, zero-config executable. It integrates directly with your desktop environment and system tray.\n\n```Bash\n# Make it executable\nchmod +x linux-wallpaperengine-gui-*-x86_64.AppImage\n\n# Run it\n./linux-wallpaperengine-gui-*-x86_64.AppImage\n```\n\n#### Method C: Run from Source\nIf you prefer running the Python script directly, please ensure you have the required dependencies:\n\n```Bash\n# Arch Linux\nsudo pacman -S python-gobject gtk4 libadwaita libayatana-appindicator\n# Ubuntu / Debian\nsudo apt install python3-gi gir1.2-gtk-4.0 gir1.2-adw-1 libayatana-appindicator3-1\n```\n\nThen clone the repository and run:\n\n```Bash\npython3 run_gui.py\n```\n\n## 📖 Basic Usage\n\n### Browse \u0026 Apply Wallpapers\n\n1. **Browse**: The app automatically scans your Steam Workshop wallpaper library on first launch\n2. **Apply**: Double-click a wallpaper card or click the **Apply** button in the sidebar\n3. **Random**: Click the 🎲 button in the toolbar or use the tray menu\n4. **Stop**: Click the ⏹ button in the toolbar\n5. **Multi-Monitor**: Select the target display from the top bar dropdown, then apply\n\n### Playback History\n\nAccess your recent wallpaper history via the **Hamburger Menu (☰) → Playback History**:\n\n- View the last 30 wallpapers with thumbnails, nicknames (italic), original IDs, and timestamps (MM-DD HH:MM)\n- One-click replay any previous wallpaper — the main window syncs automatically\n- Clear history or check capacity (current / 30)\n\n### Nickname Management\n\nGive your wallpapers meaningful names:\n\n- **Set a nickname**: Right-click a wallpaper → \"Set Nickname\", or click the ✏️ button in the sidebar\n- **Batch manage**: Settings → \"Manage Nicknames\" to view, edit, or delete all nicknames in a dialog\n- **Search integration**: The search box matches both nicknames and original titles\n- **Visual distinction**: Nicknames appear in *italic bold* in the grid view; the sidebar shows \"Nickname + Original Name (small gray text)\"\n\n### Compact Preview Mode\n\nA lightweight preview window designed for tiling WMs:\n\n- **Toggle**: Click the compact mode icon in the toolbar\n- **Navigate**: Use `←` `→` keys or the on-screen buttons to cycle through 5 circular thumbnails\n- **Quick actions**: Apply, Stop, Lucky (random), and Jump to current wallpaper\n- **Window rules**: You may need to configure your WM to float this window — see [Advanced Guide](docs/ADVANCED.md#compact-preview-mode)\n\n### Performance Monitoring\n\nClick the monitor icon in the top bar to open the Performance page:\n\n- **Overview cards**: Total CPU, Total Memory, Active Threads\n- **Sparkline charts**: 60-second history for CPU (color-coded: green \u003c 20%, orange \u003c 40%, red ≥ 40%) and Memory (blue)\n- **Process details**: Expand Frontend/Backend/Tray for individual metrics, thread names, and currently playing wallpapers\n\n  \u003cdetails\u003e\n  \u003csummary\u003eClick to expand the settings page screenshot\u003c/summary\u003e\n  \u003cbr\u003e\n  \u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"docs/assets/settings-page1.png\" width=\"32%\" alt=\"Settings page1\"\u003e\n    \u003cimg src=\"docs/assets/settings-page2.png\" width=\"32%\" alt=\"settings page2\"\u003e\n    \u003cimg src=\"docs/assets/settings-page3.png\" width=\"32%\" alt=\"settings page3\"\u003e\n    \u003cp\u003e\u003cem\u003eGeneral Settings / Audio / Advanced Tweaks\u003c/em\u003e\u003c/p\u003e\n  \u003c/div\u003e\n  \u003c/details\u003e\n\n## ⌨️ Command-Line Control\n\nAll commands are sent to the same running instance (single-instance architecture):\n\n| Command | Action |\n|---------|--------|\n| `--show` | Show the window |\n| `--hide` | Hide the window (process keeps running) |\n| `--toggle` | Toggle show/hide |\n| `--random` | Random wallpaper switch |\n| `--stop` | Stop current wallpaper |\n| `--apply-last` | Apply the last used wallpaper |\n| `--refresh` | Rescan wallpaper library |\n| `--quit` | Fully exit (GUI + all wallpaper processes) |\n\n**Example:** Autostart with Niri\n```bash\n# In your niri config.kdl\nspawn-at-startup \"python3\" \"/path/to/run_gui.py\" \"--hidden\"\n\nbinds {\n    Mod+W { spawn \"python3\" \"/path/to/run_gui.py\" \"--toggle\"; }\n    Mod+Shift+W { spawn \"python3\" \"/path/to/run_gui.py\" \"--random\"; }\n}\n```\n\n## ⚙️ Configuration\n\n**Location:** `~/.config/linux-wallpaperengine-gui/config.json`\n\nKey settings (all configurable via the GUI's Settings page):\n\n| Setting | Default | Description |\n|---------|---------|-------------|\n| `fps` | 30 | Frame rate limit (1–144) |\n| `volume` | 50 | Audio volume (0–100) |\n| `scaling` | `\"default\"` | Scaling mode: default / stretch / fit / fill |\n| `silence` | `true` | Mute audio |\n| `autoRotateEnabled` | `false` | Enable timed wallpaper rotation |\n| `rotateInterval` | 30 | Rotation interval in minutes |\n| `cycleOrder` | `\"random\"` | Cycle order: random / title / size / type / id |\n| `useXvfb` | `true` | Use Xvfb for silent screenshots |\n| `screenshotRes` | `\"3840x2160\"` | Screenshot resolution |\n\nFor the complete configuration reference, see [docs/ADVANCED.md](docs/ADVANCED.md#configuration-reference).\n\n## ⚠️ Known Limitations\n\n### Wallpaper Type Compatibility\n\n| Type | Status | Notes |\n|------|--------|-------|\n| **Video** | ✅ Fully supported | MP4/WebM recommended |\n| **Web** | ⚠️ Partial | Renders correctly, but **property adjustments are non-functional** (backend limitation) |\n| **Scene** | ⚠️ Limited | Complex particle systems / custom shaders may glitch or fail |\n\n### Wayland Limitations\n\n- ❌ **Mouse interaction disabled**: Cannot obtain global cursor position; click interactions and mouse trails do not work\n- ❌ **Web property injection limited**: CEF communication is restricted under Wayland's security model\n\nFor detailed compatibility information, see [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md).\n\n### Other Notes\n\n- **Memory growth**: Long-running Web wallpapers may slowly increase memory usage (upstream engine issue). Enable timed rotation to mitigate.\n- **Test environment**: Primarily tested on Arch Linux + Niri. Other environments may require adjustments.\n\n## ❓ FAQ\n\n### Why do Web wallpaper property adjustments not work?\n\nThe C++ backend uses CEF (Chromium Embedded Framework) for Web wallpapers. On Linux/Wayland, CEF's inter-process communication has compatibility issues that prevent JavaScript property injection from working reliably. Wallpapers will run with their default settings. As a workaround, you can manually edit the wallpaper's `project.json` or HTML source files.\n\n### How can I reduce memory usage?\n\n1. Avoid Web wallpapers (they use CEF/Chromium internally)\n2. Enable timed rotation (Settings → Automation) to periodically restart the backend\n3. Lower FPS (Settings → General)\n4. Disable audio processing (Settings → Advanced)\n\n### The compact preview window doesn't float in my tiling WM\n\nYou need to add a window rule in your WM configuration. See [docs/ADVANCED.md](docs/ADVANCED.md#compact-preview-mode) for Niri and Hyprland examples.\n\n### Why are screenshots slow (5–10 seconds)?\n\nIf Xvfb is installed, the app uses CPU software rendering to produce 4K screenshots silently (no popup window). This is slower but guarantees consistent quality regardless of your physical screen resolution or tiling WM layout. You can disable Xvfb mode in Settings → Advanced for faster (but windowed) screenshots.\n\n### System tray icon is not showing\n\n1. Verify `libayatana-appindicator` is installed\n2. GNOME users: Install the \"AppIndicator Support\" extension\n3. Waybar users: Ensure the `tray` module is configured\n4. i3/Sway users: You may need `waybar` or another status bar with tray support\n\n### How do I set different wallpapers for each monitor?\n\nSelect the target display from the top bar dropdown, then browse and apply a wallpaper. Repeat for each monitor. Use the 🔗 Link/Unlink button to toggle between applying to all screens (Same mode) or just the selected screen (Diff mode).\n\n### Can I use this with Flatpak or AppImage?\n\n**AppImage**: Fully supported since v0.10.4 with zero-config desktop integration. The app auto-creates `.desktop` shortcuts and self-heals if the file is moved.\n\n**Flatpak**: Not officially supported yet. File access and sandbox restrictions may affect functionality.\n\n### How do I report a bug?\n\n1. Go to Settings → Logs and click **Copy Logs**\n2. Open a [GitHub Issue](https://github.com/Suhoiyis/gui-for-linux-wallpaperengine/issues)\n3. Include: system info (`uname -a`), desktop environment, wallpaper ID/type, and the copied logs\n\n## 🏛️ Technical Architecture\n\n### Project Structure\n\n```\nsuw/\n├── py_GUI/                    # Main application package\n│   ├── core/                  # Core logic\n│   │   ├── controller.py      # WallpaperController — process management\n│   │   ├── config_manager.py  # ConfigManager — settings I/O with robust fallback\n│   │   ├── history.py         # HistoryManager — playback history (30 entries)\n│   │   └── nickname.py        # NicknameManager — alias persistence\n│   ├── ui/                    # User interface\n│   │   ├── app.py             # Main application window\n│   │   ├── components/        # Reusable components (navbar, sidebar, preview)\n│   │   └── pages/             # Page views (wallpapers, settings, performance)\n│   ├── utils/                 # Utilities\n│   │   ├── performance.py     # PerformanceMonitor — CPU/memory tracking\n│   │   └── logger.py          # Logging configuration\n│   └── const.py               # Constants, version, CSS styles\n├── run_gui.py                 # Entry point\n├── docs/                      # Documentation\n│   └── assets/                # Screenshots and images\n└── pic/icons/                 # Application icons\n```\n\n### Architecture Overview\n\n```\n┌──────────────────────────────────────────────────┐\n│                    GTK4 + Libadwaita             │\n│  ┌──────────┐  ┌──────────┐  ┌────────────────┐  │\n│  │ Wallpaper│  │ Settings │  │  Performance   │  │\n│  │   Page   │  │   Page   │  │    Monitor     │  │\n│  └────┬─────┘  └────┬─────┘  └───────┬────────┘  │\n│       │             │                │           │\n│  ┌────┴─────────────┴────────────────┴─────────┐ │\n│  │           WallpaperController               │ │\n│  │  ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ │\n│  │  │ Config   │ │ History  │ │  Nickname    │ │ │\n│  │  │ Manager  │ │ Manager  │ │  Manager     │ │ │\n│  │  └──────────┘ └──────────┘ └──────────────┘ │ │\n│  └──────────────────┬──────────────────────────┘ │\n│                     │ subprocess                 │\n│  ┌──────────────────┴───────────────────────────┐│\n│  │         linux-wallpaperengine (C++)          ││\n│  │         Rendering · Audio · Screenshot       ││\n│  └──────────────────────────────────────────────┘│\n│                                                  │\n│  ┌─────────────────────────────────────────────┐ │\n│  │         System Tray (libayatana)            │ │\n│  └─────────────────────────────────────────────┘ │\n└──────────────────────────────────────────────────┘\n```\n\n### Key Design Decisions\n\n- **Single-instance architecture**: All CLI commands route to the running GTK application via `Gio.Application`, avoiding process duplication\n- **Defensive configuration**: `ConfigManager.get()` handles `None` values and falsy-but-valid values (e.g., `volume=0`) correctly\n- **Theme variables**: All UI colors use GTK/Libadwaita named colors (`@window_bg_color`, `@theme_fg_color`, `@accent_bg_color`) for seamless theme adaptation\n- **Object pooling**: Compact mode thumbnails use object pooling to eliminate scroll jank\n\n## 📚 Documentation\n\n| Document | Description |\n|----------|-------------|\n| [CHANGELOG.md](CHANGELOG.md) | Version history and release notes |\n| [docs/ADVANCED.md](docs/ADVANCED.md) | Advanced features, configuration reference, and WM integration |\n| [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) | Wallpaper type compatibility, Wayland limitations, hardware requirements |\n| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common errors, backend log analysis, and fixes |\n\n## 🔧 Tech Stack\n\n- **Language**: Python 3.10+\n- **UI Framework**: PyGObject (GTK4 + Libadwaita)\n- **System Tray**: libayatana-appindicator\n- **Backend**: Almamu/linux-wallpaperengine (C++)\n- **Charts**: Cairo-based sparkline components\n\n## 🤝 Contributing\n\nContributions are welcome!\n\n- Feature requests and bug reports → [Open an Issue](https://github.com/Suhoiyis/gui-for-linux-wallpaperengine/issues)\n- Code contributions → Follow existing code style and submit a Pull Request\n- Documentation improvements are equally appreciated\n\n## 🙏 Acknowledgements\n\n\u003e Some UI design inspiration was drawn from [AzPepoze/linux-wallpaperengine-gui](https://github.com/AzPepoze/linux-wallpaperengine-gui).\n\u003e\n\u003e It is an excellent GUI project — we recommend checking it out.\n\n## 📄 License\n\nGPL-3.0 license\n\n---\n\n**Current Version**: v0.11.2\n\n**Last Updated**: 2026-02-22\n\n*A Vibe Coding experiment project*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuhoiyis%2Fgui-for-linux-wallpaperengine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsuhoiyis%2Fgui-for-linux-wallpaperengine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuhoiyis%2Fgui-for-linux-wallpaperengine/lists"}