{"id":19858512,"url":"https://github.com/matjam/smoothpaper","last_synced_at":"2025-09-07T11:37:59.824Z","repository":{"id":227951053,"uuid":"772722511","full_name":"matjam/smoothpaper","owner":"matjam","description":"Smoothly transitioning wallpaper daemon for X11 Window Managers","archived":false,"fork":false,"pushed_at":"2024-03-20T05:56:49.000Z","size":87,"stargazers_count":4,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-11T14:26:21.066Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matjam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2024-03-15T18:58:46.000Z","updated_at":"2024-12-07T11:02:07.000Z","dependencies_parsed_at":"2024-03-20T06:35:16.954Z","dependency_job_id":null,"html_url":"https://github.com/matjam/smoothpaper","commit_stats":null,"previous_names":["matjam/smoothpaper"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matjam%2Fsmoothpaper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matjam%2Fsmoothpaper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matjam%2Fsmoothpaper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matjam%2Fsmoothpaper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matjam","download_url":"https://codeload.github.com/matjam/smoothpaper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241255130,"owners_count":19934815,"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":[],"created_at":"2024-11-12T14:23:44.642Z","updated_at":"2025-09-07T11:37:59.781Z","avatar_url":"https://github.com/matjam.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Smoothpaper\n\nSmoothly transitioning wallpaper daemon for X11 Window Mangers and Wayland\nCompositors.\n\nhttps://github.com/matjam/smoothpaper/assets/578676/152657d8-e321-4aa9-8e3c-8d3c2eb1fcad\n\nSmoothpaper is an OpenGL based wallpaper slideshow daemon designed to work with\nX11 Window Managers, such as Qtile, i3, Openbox, etc, as well as Wayland\nCompositors such as Hyprland. There are many implementations of this kind of\nutility, and arguably its already well served by the existing tools, but I\nswitch between X11 and Wayland a fair bit due to compatibility issues, so I\nwanted something I could just use in both environments.\n\nIt currently can't set the desktop wallpaper of any DE that sets its own\nwallpaper (like Gnome, KDE, etc), as those applications open their own Window to\nrender the desktop icons to and have their own mangement of the wallpaper. KDE\nand Gnome both have extensions or built-in configuration for doing what I do in\nsmoothpaper, so I don't see much value in implementing that.\n\nIts been tested with i3, Hyprland and Sway. Most tiling window managers should\nbe fine, but I noticed issues with Openbox, which I will look at. But for now\nthings work ok.\n\nIn my travels from Windows/Mac to using tiling window managers on Linux, I was\nfrustrated with the lack of any way to have a set of wallpapers that transition\nsmoothly while I work. I was using feh and nitrogen to set wallpapers, but the\ntransitions were jarring. I wanted smooth fading between the wallpapers, and\ncouldn't find a program that did this for X11 (I am aware there are programs\nthat do this for Wayland), so I wrote one. And then, I decided that I could add\nWayland support so I did that too.\n\nBecause I'm using OpenGL to do the transitions, I can use a Texture that is\nstored on the GPU and the transitions are done by changing the alpha value of\nthe texture, so the transitions are very smooth and use very little CPU.\n\n## 2.0 Release\n\nSo, I was pretty annoyed at how difficult adding certain features was to the C++\nversion of the application, so I rewrote it in Go using cgo. This took a couple\nof days, but I think it was worth it as I now have a clean backend that made it\neasy to implement Wayland support.\n\nThe program has less exotic dependencies; standard OpenGL, X11 and Wayland\nlibraries you most likely already have installed.\n\nSo, many of the items on the todo list are much closer now to actually getting\ndone. If you want a feature, let me know!\n\nNote one major change is I do not support running in the background. This is the\none thing thats super hard in Go, but I don't think its necessary as you can\nstart it and background it just fine with `\u0026` and most Window Managers allow you\nto start things with `exec` for example, in `i3`. If it really annoys you, let\nme know and I'll spend some time on it; its not impossible just irksome.\n\n## Features\n\n- Smoothly transition between wallpapers with fading\n- Set wallpapers from one or more directories\n- Scaling of images to fit the screen\n- Randomly select wallpapers\n- Set the time between transitions\n- Set the speed of fade transitions\n- Uses SFML for smooth transitions\n- Uses very little CPU when idle\n- Can be run as a daemon with the `-b` flag\n- Set a specific wallpaper immediately via command line without waiting for the\n  next transition\n- Add cli commands to control the program\n\n## Known Issues\n\nPlease check the Issues in Github for all issues. Major ones are:\n\n- Currently does not necessarily exit when the compositor or x11 shuts down. You\n  might need to issue a `smoothpaper stop` before you start it in case there's a\n  stale one running in the background. Your other option is to not use -b; if\n  the parent process dies in that case it should remove the daemon.\n\n### TODO\n\n- Dynamically change the wallpapers directory (currently you have to restart the\n  program to change the directory)\n- Set the wallpaper for all screens in a multi-monitor setup\n- Add a task bar icon to control the program\n- More cool transitions?\n\nIf you have any feature requests, please open an issue.\n\n## Limitations\n\n- Does not work on multi-monitor setups as it currently finds the first screen\n  and sets the wallpaper for that screen only. Should be easy to fix, but I\n  don't have a multi-monitor setup to test with.\n- Any X11 Window Manager that renders to the desktop will have problems. I think\n  its because I am creating a layer just above the bottom layer or something\n  like that.\n- Wayland works, but I don't know how stable it is. Appreciate any feedback if\n  you have issues.\n\n## Installation\n\n### Arch Linux\n\nSmoothpaper is available in the AUR as `smoothpaper`. You can install it with\nyour favorite AUR helper, such as `yay`:\n\n```bash\nyay -S smoothpaper\n```\n\nPlease make sure you raise any issues installing the AUR package in this\nrepository, not the AUR, so I can track them.\n\n### Other Distributions\n\nI don't have packages for other distributions yet. If you would like to package\nsmoothpaper for your distribution, please let me know and I can help you with\nthat.\n\n## Building\n\nYou will need to install g 1.24.1 to build this project. Go is included in the\nArch repositories, and you can also just download a tarball and shove it in your\npath from https://go.dev/doc/install.\n\nAdditionally, you will need to install gcc, cmake, and make, as well as the X11\ndevelopment libraries and any OpenGL lib like mesa that you need. On\nUbuntu/Debian, you can install these with the following command:\n\n```bash\nsudo apt install build-essential cmake libx11-dev libxrandr-dev libxinerama-dev \\\n                 libxcursor-dev libxext-dev libgl-dev\n```\n\n(I'm unsure if the above is correct, I'll check but if you get build failures,\ncheck the output and let me know in a new issue and I'll update the docs)\n\nOn Arch Linux, you can install these with the following command:\n\n```bash\nsudo pacman -S base-devel go mesa glad libxrender libva wayland egl-wayland\n```\n\nYou should then be able to do\n\n```bash\ngo install ./...\n```\n\nThis will output the `smoothpaper` binary in your `~/go/bin` folder. You can add\nthat to your path. If it complains about missing dependencies etc, let me know\nand I'll figure out what I am missing from the documentation.\n\n## Installation\n\nCopy `smoothpaper` anywhere in your path, or run from the build directory.\n\nCopy the `smoothpaper.toml` file to `~/.config/smoothpaper/smoothpaper.toml` and\nedit it to your liking, or use `smoothpaper -i` to install the default config\nand edit that.\n\n# Usage\n\nSimply run the `smoothpaper` binary. It will read the configuration file and set\nthe wallpaper for the first screen it finds. It will then transition to the next\nwallpaper after the delay specified in the configuration file.\n\nSmoothpaper supports daemonizing with the `-b` flag. This will run the program\nin the background and will not print any output to the terminal after the\ninitial message. Logs will be written to\n`~/.local/share/smoothpaper/smoothpaper.log`, and will be rotated when the log\nfile reaches 1MB in size, with 3 backups.\n\n```bash\nsmoothpaper -b\n```\n\n## Configuration\n\nThe program looks for a configuration file in\n`~/.config/smoothpaper/smoothpaper.toml`. An example configuration file is\nbelow:\n\n```toml\n# smoothpaper configuration file\n\n# path your wallpapers are stored in\nwallpapers = \"~/Pictures\"\n# alternatively, you can specify a list of directories to search for wallpapers\n# wallpapers = [\"~/Pictures/wallpapers\", \"~/Downloads/wide_walls\"]\n\n# whether the files should be shuffled or not. If you do not shuffle, the files will be\n# displayed in the order they are found which is dependent on the filesystem. I'm not\n# sure why you'd want to do this, but it's an option.\nshuffle = true\n\n# the mode to scale the images. Options are\n#\n#   \"vertical\": scales the image to fit vertically; on widescreens this might result in\n#               bars on the side if the wallpaper has a less wide aspect ratio. On other\n#               displays this might mean cropping the sides if the wallpaper has a wider\n#               aspect ratio than the screen.\n#\n# \"horizontal\": scales the image to fit horizintally; on widescreens this might result in\n#               cropping the top and bottom of the image. On a 4:3 or 16:9 screen this might\n#               result in bars on the top and bottom if the aspect ratio of the wallpaper\n#               is wider than your screen.\n#\n#  \"stretched\": will stretch the image in both directions to fit your screen. This means\n#               that if the image does not match your screen's aspect ratio, it will be\n#               distorted.\n#\n#     \"center\": will center the image on the screen. This means that if the image does not match\n#               your screen's aspect ratio, it will be cropped on the sides or top and bottom.\n#               depending on the mode you choose, or it might just be centered with bars on the sides\n#               or top and bottom.\nscale_mode = \"horizontal\"\n\n# the speed at which the images fade in and out, in seconds.\nfade_speed = 5\n\n# the delay between images, in seconds. Must be an integer.\ndelay = 300\n\n# frames per second for the opengl renderer. This is the maximum number of frames per second\n# that will be rendered. Lowering this value will reduce CPU usage, but may cause the animation\n# to be less smooth.\nframerate_limit = 60\n\n# whether to display debug information or not.\ndebug = false\n```\n\n## CLI\n\nRunning `smoothpaper` by itself will output some help. You can control a running\nsmoothpaper daemon by using the following commands:\n\n- `smoothpaper next` - switch to the next wallpaper\n- `smoothpaper load \u003cfilename\u003e` - switch to the given wallpaper. You must give\n  an absolute path.\n- `smoothpaper status` - returns the currently shown wallpaper and the status of\n  the daemon, in JSON format.\n- `smoothpaper stop` - exits the daemon.\n\nThe following switches are supported for the `smoothpaper` command:\n\n```\n  -c, --config arg     Path to config file\n  -i, --installconfig  Install a default config file\n  -d, --debug          Enable debug logging\n  -h, --help           Print usage\n  -v, --version        Print version\n```\n\nThey should be mostly self explanatory; the `--installconfig` flag will install\nconfig to `$HOME/.config/smoothpaper/smoothpaper.toml`.\n\nUse the `--help` or look at the man pages for more detailed information.\n\n# Support\n\nPlease use the github Issues to report any bugs or feature requests. I'm happy\nto accept pull requests for new features or bug fixes, and in fact prefer that.\nI'm a go programmer by trade, so I have no excuses.\n\nYou can also find me as `matjammer` on Discord. One server I frequent is the\nHyprland Cathedral https://hyprland.org/\n\n## Contributing\n\nIf you would like to contribute to smoothpaper, please open a pull request. I'm\nhappy to accept any contributions, and will work with you to get your changes\nmerged. I am a Go programmer by trade, but the C code that I'm integrating with\nis entirely alien to me so its quite likely I've missed something. LLMs are\nhelpful in this regard, but they do make mistakes.\n\n## Thanks\n\n- vee on libera.chat for beta testing and feature requests\n- @strongleong for suggesting being able to control the daemon via a cli tool\n  (in progress!)\n\n## License\n\nThis program is licensed under the MIT License. See the LICENSE file for more\ninformation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatjam%2Fsmoothpaper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatjam%2Fsmoothpaper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatjam%2Fsmoothpaper/lists"}