{"id":13840004,"url":"https://github.com/Almamu/linux-wallpaperengine","last_synced_at":"2025-07-11T07:31:56.513Z","repository":{"id":37259262,"uuid":"146309233","full_name":"Almamu/linux-wallpaperengine","owner":"Almamu","description":"Wallpaper Engine backgrounds for Linux!","archived":false,"fork":false,"pushed_at":"2024-11-08T09:24:25.000Z","size":11949,"stargazers_count":1729,"open_issues_count":74,"forks_count":61,"subscribers_count":25,"default_branch":"main","last_synced_at":"2024-11-20T21:12:03.697Z","etag":null,"topics":["linux","opengl","wallpaper-app","wallpaper-engine"],"latest_commit_sha":null,"homepage":"","language":"C++","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/Almamu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"Almamu"}},"created_at":"2018-08-27T14:30:29.000Z","updated_at":"2024-11-20T20:25:56.000Z","dependencies_parsed_at":"2023-12-14T02:53:30.854Z","dependency_job_id":"13f5dd29-1101-4b2d-9ea6-274368e89a63","html_url":"https://github.com/Almamu/linux-wallpaperengine","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Almamu%2Flinux-wallpaperengine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Almamu%2Flinux-wallpaperengine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Almamu%2Flinux-wallpaperengine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Almamu%2Flinux-wallpaperengine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Almamu","download_url":"https://codeload.github.com/Almamu/linux-wallpaperengine/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225705136,"owners_count":17511229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["linux","opengl","wallpaper-app","wallpaper-engine"],"created_at":"2024-08-04T17:00:40.316Z","updated_at":"2025-07-11T07:31:56.506Z","avatar_url":"https://github.com/Almamu.png","language":"C++","funding_links":["https://github.com/sponsors/Almamu"],"categories":["linux","C++","C++ (225)","Index","Customizations"],"sub_categories":["System Customization","Linux"],"readme":"\u003cp align=\"center\"\u003e\n\t\u003ca href=\"https://github.com/Almamu/linux-wallpaperengine/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/Almamu/linux-wallpaperengine\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/Almamu/linux-wallpaperengine/actions?query=branch%3Amain\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/Almamu/linux-wallpaperengine/cmake.yml?branch=main\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/Almamu/linux-wallpaperengine/pulse\"\u003e\u003cimg src=\"https://img.shields.io/tokei/lines/github/Almamu/linux-wallpaperengine\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://www.codefactor.io/repository/github/almamu/linux-wallpaperengine\"\u003e\u003cimg src=\"https://img.shields.io/codefactor/grade/github/Almamu/linux-wallpaperengine\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/Almamu/linux-wallpaperengine/graphs/commit-activity\"\u003e\u003cimg src=\"https://img.shields.io/github/commit-activity/m/Almamu/linux-wallpaperengine\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/Almamu/linux-wallpaperengine/graphs/contributors\"\u003e\u003cimg src=\"https://img.shields.io/github/contributors/Almamu/linux-wallpaperengine\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/Almamu/linux-wallpaperengine/issues\"\u003e\u003cimg src=\"https://img.shields.io/github/issues-raw/Almamu/linux-wallpaperengine\" /\u003e\u003c/a\u003e\n\t\u003ca href=\"https://github.com/Almamu/linux-wallpaperengine/issues?q=is%3Aissue+is%3Aopen+label%3A%22help%20wanted%22\"\u003e\u003cimg src=\"https://img.shields.io/github/issues/Almamu/linux-wallpaperengine/help%20wanted?color=green\" alt=\"help wanted\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://wpengine.alma.mu/\"\u003e\u003cimg src=\"https://img.shields.io/badge/showcase_gallery-blue\" alt=\"Compatibility gallery\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# 🖼️ Linux Wallpaper Engine\n\nBring **Wallpaper Engine**-style live wallpapers to Linux! This project allows you to run animated wallpapers from Steam’s Wallpaper Engine right on your desktop.\n\n\u003e ⚠️ This is an educational project that evolved into a functional OpenGL-based wallpaper engine for Linux. Expect some limitations and quirks!\n\n---\n\n## 📦 System Requirements\n\nTo compile and run this, you'll need:\n\n- OpenGL 3.3 support\n- CMake\n- LZ4, Zlib\n- SDL2\n- FFmpeg\n- X11 or Wayland\n- Xrandr (for X11)\n- GLFW3, GLEW, GLUT, GLM\n- MPV\n- PulseAudio\n- FFTW3\n\nInstall the required dependencies on Ubuntu/Debian-based systems:\n\n### Ubuntu 22.04\n```bash\nsudo apt-get update\nsudo apt-get install build-essential cmake libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libgl-dev libglew-dev freeglut3-dev libsdl2-dev liblz4-dev libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libxxf86vm-dev libglm-dev libglfw3-dev libmpv-dev mpv libmpv1 libpulse-dev libpulse0 libfftw3-dev\n```\n\n### Ubuntu 24.04\n```bash\nsudo apt-get update\nsudo apt-get install build-essential cmake libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libgl-dev libglew-dev freeglut3-dev libsdl2-dev liblz4-dev libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libxxf86vm-dev libglm-dev libglfw3-dev libmpv-dev mpv libmpv2 libpulse-dev libpulse0 libfftw3-dev\n```\n\n---\n\n## 🐧 Arch Linux Users\n\nYou can install this directly from the AUR using your favorite AUR helper:\n\n```bash\nyay -S linux-wallpaperengine-git\n```\n\n\u003e This installs the latest development version.\n\n**Note:** You’ll still need assets from the official Wallpaper Engine (via Steam). See below for details.\n\n---\n\n## 🚀 Getting Started\n\n### 1. Get Wallpaper Engine Assets\n\nYou **must own and install Wallpaper Engine** via Steam. This provides the required assets used by many backgrounds.\n\nGood news: **you usually don’t need to copy anything manually.** The app will automatically look in these common install paths:\n\n```\n~/.steam/steam/steamapps/common\n~/.local/share/Steam/steamapps/common\n~/.var/app/com.valvesoftware.Steam/.local/share/Steam/steamapps/common\n~/snap/steam/common/.local/share/Steam/steamapps/common\n```\n\n\u003e ✅ If Wallpaper Engine is installed in one of these paths, the assets will be detected automatically!\n\n---\n\n#### ❗ If Assets Aren’t Found Automatically\n\nYou can copy the `assets` folder manually:\n\n1. In Steam, right-click **Wallpaper Engine** → **Manage** → **Browse local files**\n2. Copy the `assets` folder\n3. Paste it into the same folder where the `linux-wallpaperengine` binary is located\n\n---\n\n### 2. Build from Source\n\nClone the repo:\n\n```bash\ngit clone --recurse-submodules https://github.com/Almamu/linux-wallpaperengine.git\ncd linux-wallpaperengine\n```\n\nBuild it:\n\n```bash\nmkdir build \u0026\u0026 cd build\ncmake ..\nmake\n```\n\nOnce the build process is finished, this should create a new `output` folder containing the app and all the required\nsupport files to run.\n\n\u003e ✅ Remember: Place the `assets` folder next to the built binary if it isn’t detected automatically.\n\n---\n\n## 🧪 Usage\n\nBasic syntax:\n\n```bash\n./linux-wallpaperengine [options] \u003cbackground_id or path\u003e\n```\n\nYou can use either:\n- A Steam Workshop ID (e.g. `1845706469`)\n- A path to a background folder\n\n---\n\n### 🔧 Common Options\n\n| Option | Description |\n|--------|-------------|\n| `--silent` | Mute background audio |\n| `--volume \u003cval\u003e` | Set audio volume |\n| `--noautomute` | Don't mute when other apps play audio |\n| `--no-audio-processing` | Disable audio reactive features |\n| `--fps \u003cval\u003e` | Limit frame rate |\n| `--window \u003cXxYxWxH\u003e` | Run in windowed mode with custom size/position |\n| `--screen-root \u003cscreen\u003e` | Set as background for specific screen |\n| `--bg \u003cid/path\u003e` | Assign a background to a specific screen (use after `--screen-root`) |\n| `--scaling \u003cmode\u003e` | Wallpaper scaling: `stretch`, `fit`, `fill`, or `default` |\n| `--clamping \u003cmode\u003e` | Set texture clamping: `clamp`, `border`, `repeat` |\n| `--assets-dir \u003cpath\u003e` | Set custom path for assets |\n| `--screenshot \u003cfile\u003e` | Save screenshot (PNG, JPEG, BMP) |\n| `--list-properties` | Show customizable properties of a wallpaper |\n| `--set-property name=value` | Override a specific property |\n| `--disable-mouse` | Disable mouse interaction |\n| `--disable-parallax` | Disable parallax effect on backgrounds that support it |\n| `--no-fullscreen-pause` | Prevent pausing while fullscreen apps are running |\n\n---\n\n### 💡 Examples\n\n#### Run a background by ID\n```bash\n./linux-wallpaperengine 1845706469\n```\n\n#### Run a background from a folder\n```bash\n./linux-wallpaperengine ~/backgrounds/1845706469/\n```\n\n#### Assign backgrounds to screens with scaling\n```bash\n./linux-wallpaperengine \\\n  --scaling stretch --screen-root eDP-1 --bg 2667198601 \\\n  --scaling fill --screen-root HDMI-1 --bg 2667198602\n```\n\n#### Run in a window\n```bash\n./linux-wallpaperengine --window 0x0x1280x720 1845706469\n```\n\n#### Limit FPS to save power\n```bash\n./linux-wallpaperengine --fps 30 1845706469\n```\n\n#### Take a screenshot\n```bash\n./linux-wallpaperengine --screenshot ~/wallpaper.png 1845706469\n```\n\nThis can be useful as output for pywal or other color systems that use images as basis to generate a set of colors\nto apply to your system.\n\n#### View and change properties\n```bash\n./linux-wallpaperengine --list-properties 2370927443\n```\n\nThe output includes all the relevant information for each of the different properties:\n```\nbarcount - slider\n\tDescription: Bar Count\n\tValue: 64\n\tMinimum value: 16\n\tMaximum value: 64\n\tStep: 1\n\nbloom - boolean\n\tDescription: Bloom\n\tValue: 0\nfrequency - combolist\n\tDescription: Frequency\n\tValue: 2\n\t\tPosible values:\n\t\t16 -\u003e 1\n\t\t32 -\u003e 2\n\t\t64 -\u003e 3\n\nowl - boolean\n\tDescription: Owl\n\tValue: 0\nrain - boolean\n\tDescription: Rain\n\tValue: 1\nschemecolor - color\n\tDescription: ui_browse_properties_scheme_color\n\tR: 0.14902 G: 0.23137 B: 0.4 A: 1\nvisualizer - boolean\n\tDescription: \u003chr\u003eAdd Visualizer\u003chr\u003e\n\tValue: 1\nvisualizercolor - color\n\tDescription: Bar Color\n\tR: 0.12549 G: 0.215686 B: 0.352941 A: 1\nvisualizeropacity - slider\n\tDescription: Bar Opacity\n\tValue: 1\n\tMinimum value: 0\n\tMaximum value: 1\n\tStep: 0.1\n\nvisualizerwidth - slider\n\tDescription: Bar Spacing\n\tValue: 0.25\n\tMinimum value: 0\n\tMaximum value: 0.5\n\tStep: 0.01\n```\n\nAny of these values can be modified with the --set-property switch. Say you want to enable the bloom in this background, you would do so like this:\n```\n./linux-wallpaperengine --set-property bloom=1 2370927443\n```\n\n---\n\n## 🧪 Wayland \u0026 X11 Support\n\n- **Wayland**: Works with compositors that support `wlr-layer-shell-unstable`.\n- **X11**: Requires XRandr. Use `--screen-root \u003cscreen_name\u003e` (as shown in `xrandr`).\n\n\u003e ⚠ For X11 users: Currently doesn't work if a compositor or desktop environment (e.g. GNOME, KDE, Nautilus) is drawing the background.\n\n---\n\n## 🌈 Example Backgrounds\n\n![example1](docs/images/example.gif)\n![example2](docs/images/example2.gif)\n\nWant to see more examples of backgrounds that work? Head over to the [project's website](https://wpengine.alma.mu/#showcase)\n\n## 🪲 Common issues\n### Black screen when setting as screen's background\nThis can be caused by a few different things depending on your environment and setup.\n\n### X11\nCommon symptom of a compositor drawing to the background which prevents Wallpaper Engine from being properly visible.\nThe only solution currently is disabling the compositor so Wallpaper Engine can properly draw on the screen\n\n### NVIDIA\nSome users have had issues with GLFW initialization and other OpenGL errors. These are generally something that's\nworth reporting in the issues. Sometimes adding this variable when running Wallpaper Engine helps and/or solves\nthe issue:\n```bash\n__GL_THREADED_OPTIMIZATIONS=0 linux-wallpaperengine\n```\n\nWe'll be looking at improving this in the future, but for now it can be a useful workaround.\n\n---\n\n## 🙏 Special Thanks\n\n- [RePKG](https://github.com/notscuffed/repkg) – for texture flag insights\n- [RenderDoc](https://github.com/baldurk/renderdoc) – the best OpenGL debugger out there!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAlmamu%2Flinux-wallpaperengine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAlmamu%2Flinux-wallpaperengine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAlmamu%2Flinux-wallpaperengine/lists"}