{"id":37118750,"url":"https://github.com/lordofscripts/go-carousel","last_synced_at":"2026-01-14T13:52:00.127Z","repository":{"id":311229338,"uuid":"1040295452","full_name":"lordofscripts/go-carousel","owner":"lordofscripts","description":"A desktop wallpaper carousel for the Linux desktop. Schedule your favorite wallpapers with ease.","archived":false,"fork":false,"pushed_at":"2025-08-22T21:59:38.000Z","size":3087,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-23T00:06:08.524Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lordofscripts.png","metadata":{"files":{"readme":"docs/README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"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},"funding":{"github":"lordofscripts","patreon":null,"open_collective":null,"ko_fi":"lostinwriting","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"lostinwriting","custom":null}},"created_at":"2025-08-18T18:52:37.000Z","updated_at":"2025-08-22T21:59:41.000Z","dependencies_parsed_at":"2025-08-23T00:06:24.841Z","dependency_job_id":"9349d234-5143-4552-88c0-7e6355ceaab1","html_url":"https://github.com/lordofscripts/go-carousel","commit_stats":null,"previous_names":["lordofscripts/go-carousel"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/lordofscripts/go-carousel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lordofscripts%2Fgo-carousel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lordofscripts%2Fgo-carousel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lordofscripts%2Fgo-carousel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lordofscripts%2Fgo-carousel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lordofscripts","download_url":"https://codeload.github.com/lordofscripts/go-carousel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lordofscripts%2Fgo-carousel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28422360,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T13:30:50.153Z","status":"ssl_error","status_checked_at":"2026-01-14T13:29:08.907Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":[],"created_at":"2026-01-14T13:51:59.431Z","updated_at":"2026-01-14T13:52:00.111Z","avatar_url":"https://github.com/lordofscripts.png","language":"Go","funding_links":["https://github.com/sponsors/lordofscripts","https://ko-fi.com/lostinwriting","https://buymeacoffee.com/lostinwriting","https://www.buymeacoffee.com/lostinwriting"],"categories":[],"sub_categories":[],"readme":"# Go Carousel\n\nA desktop wallpaper carousel for Linux \u0026 Windows desktops. Schedule your favorite \nwallpapers with ease and work with enjoyment (almost) regardless of your\ndesktop manager.\n\n[![Latest Version](https://img.shields.io/github/release/lordofscripts/go-carousel.svg?style=flat-square)](https://github.com/lordofscripts/go-carousel/releases)\n[![Go Report](https://goreportcard.com/badge/github.com/lordofscripts/go-carousel)](https://goreportcard.com/report/github.com/lordofscripts/go-carousel)\n[![Codecov](https://img.shields.io/codecov/c/github/lordofscripts/go-carousel/main.svg?style=flat-square)](https://codecov.io/gh/lordofscripts/go-carousel)\n[![Support](https://img.shields.io/static/v1?label=Support\u0026message=%E2%9D%A4\u0026logo=GitHub)](https://github.com/sponsors/lordofscripts)\n[![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/intent/tweet?text=Scheduled+Desktop+Wallpaper+Carousel\u0026url=https://github.com/lordofscripts/go-carousel\u0026hashtags=go,golang)\n\n\u003cp align=\"center\" width=\"100%\"\u003e\n    \u003cimg width=\"33%\" src=\"./assets/gopher-carousel-680.png\"\u003e\n\u003c/p\u003e\n\n**Go Carousel*  is a free application to make your Linux desktop more enjoyable. However,\nneither this nor derivative works can be used for [commercial purposes](./LICENSE.md).\n\nIf you are like me, you spend a lot of time working at the computer. A single desktop\nwallpaper is boring. This makes it fun by letting you define categories, and carousels\nof categories. With a simple command-line interface (CLI) you can change it to your\nhearts contempt (almost) regardless of the Linux window manager you use.\n\nSupported Window Managers:\n\n- Gnome (43..48)\n- Cinnamon\n- XFCE v4\n- LXDE\n- Micro$osf Windows\n\nYou can automate it further by:\n\n* Defining a series of CRON jobs that would change your wallpaper accordingly\n* Run it as a task\n\n### History\n\n Back in 2024 I wrote a shell script to switch the desktop wallpaper on my *Raspberry Pi 2* running the LXDE desktop manager.\n I could do it via the CLI or via a desktop shortcut.\n\n I moved to my old laptop where I used Debian 12 (Bookworm). Around\n May 2024 I wrote a rudimentary Bash shell script to do the same\n I could do on my Pi. Little by little I added more features like\n a rudimentary authorization, locking, categories and notifications\n using `notify-send`.\n\n On August 2025 I upgraded my old laptop to **Debian 13* (Trixie)\n to take advantage of Gnome 48. I decided to overhaul my old\n Bash shell script into a full-blown *Go* application. I prefer\n compiled languages to scripts and interpreted languages.\n\n And so, the tool is now written in pure Go (v1.24.1 or better). I\n changed the old configuration file for a JSON file that would\n allow me to add the extra features the Go version now sports.\n\n|     | Show your support   |\n| --- | :---: | \n| [ ![AllMyLinks](./assets/allmylinks.png)](https://allmylinks.com/lordofscripts)      | visit \u003cbr\u003e Lord of Scripts\u0026trade; \u003cbr\u003e on [AllMyLinks.com](https://allmylinks.com/lordofscripts)                  |\n| [ ![Buy me a coffee](./assets/buymecoffee.jpg)](https://allmylinks.com/lordofscripts)|  buy Lord of Scripts\u0026trade; \u003cbr\u003e a Capuccino on \u003cbr\u003e[BuyMeACoffee.com](https://www.buymeacoffee.com/lostinwriting)| \n\n## Features\n\n* A simple CLI interface\n* A single, portable JSON configuration file (`~/.config/coralys/goCarousel.json`)\n* Supports multiple window managers: Gnome, Cinnamon, LXDE, XFCE \u0026 Windows.\n* Desktop notifications (ensure your server is properly configured)\n* The notion of files (wallpaper), categories and carousels (collection of categories)\n* You can select a specific wallpaper file\n* You can let it pick a random wallpaper from a selected category\n* You can let it pick a random wallpaper from a random category from a chosen carousel\n* You can have *private categories* that are autorized by the presence of a H/W key\n* Can run as an *angel* (not quite a *daemon*) so that it uses\nthe built-in scheduler instead of depending on CRON.\n* Notifications are now more universal (DBus, LibNotify, etc.)\n\n\u003cp align=\"center\" width=\"33%\"\u003e\n    \u003cimg width=\"10%\" src=\"https://github.com/lordofscripts/lordofscripts/raw/main/diamond_sponsor.png\"\u003e\n    \u003cimg width=\"10%\" src=\"https://github.com/lordofscripts/lordofscripts/raw/main/diamond_sponsor.png\"\u003e\n    \u003cimg width=\"10%\" src=\"https://github.com/lordofscripts/lordofscripts/raw/main/diamond_sponsor.png\"\u003e\n\u003c/p\u003e\n\n*Become a Diamond sponsor and get your logo \u0026 link listed here 3-5 slots*\n\n### Proposed Wallpaper structure\n\nMost desktops nowadays have a directory called `Pictures` and all Linux desktops seem\nto have adopted that Windows thing as well. I put all my desktop wallpapers in a\nsubdirectory `Pictures/Wallpapers` or at least general wallpapers.\n\nThen under that directory I create multiple directories, one for each category. For\nexample:\n\n```\n    · ~/Pictures\n        · Wallpapers\n            · Aviation\n            · Nature                        \n            · Anime\n            · Writing\n            · Misc\n            · Personal\n```\n\nSo, you see this setup has several categories: `Aviation, Anime, Misc, Nature, Writing`\nand `Personal`. That's how I classify my wallpapers, by category so that its is easy\nto pick them depending on the mood or time of day. In each category you can put a\nsmall (hidden) icon file `.category_icon.png` of size 100x100 which is used by the\nNotification system when a wallpaper from that category is chosen.\n\nFor the sake of an example, I have a `Personal` category that is protected by a hardware\nkey. If that category is in a carousel and it picks a file from there, it will only be\nset as wallpaper if the *authorization* is successful (I use a simple scheme just for fun).\n\n## Installation\n\n**Go Carousel** is written in pure **GO** (v1.24.3).\n\n```\n    go install github.com/lordofscripts/go-carousel@latest\n```\n\nThen let it create the default *configuration file* that you will need\nto edit to define your own **Categories \u0026 Carousels** and optionally\nyour **Protection Keys**.\n\n```\n    goCarousel -init\n```\n\nThe configuration file is in `~/.config/coralys/goCarousel.json` on\nLinux and MacOS and in `C:\\Users\\YOUR_NAME\\AppData\\Roaming\\coralys\\goCarousel.json`\nfor Windows environments.\n\n## Usage\n\nNote that you need a valid configuration file for this application to do\nits job. *It is not sufficient to have the directory structure in place*.\n\n`goCarousel --help` gets you all you need to know to make advantage of it.\n\n`goCarousel -init` creates a default configuration file. You must edit it to\n\n`goCarousel -ident` tells you which Desktop Manager it has detected. If it is\none of the supported managers, you are good to go, else expect errors.\n\n### Control options\n\n`goCarousel -lock` locks the application so that further calls do NOT change\nthe current wallpaper. This is good if you want to ensure scheduler entries\ndo not change the wallpaper in blackout periods.\n\n`goCarousel -unlock` reverts what `-lock` does. After this `goCarousel` will\nbe able to change wallpapers again.\n\n`goCarousel -status` gives the the current lock status.\n\n### Change Wallpaper\n\nThe following commands should be successful provided there is no *Lock*.\n\n`goCarousel -F PATH-TO-FILE` changes the wallpaper to the specifc file.\nNOTE that if it is in a protected category, it will by-pass authorization\nbecause it assumes that is what you wish.\n\n`goCarousel -C CATEGORY` picks a random file from the selected *Category* \nprovided that category is **defined** in the configuration file. A category\nmay have an icon for use in notifications. By default categories are **not**\nprotected (do not require authorization). If you want the category to be\nprotected (like the `Personal` category above), you must specify that in\nthe configuration file.\n\n`goCarousel -G GROUP` selects that *Group/Carousel* and selects a random\ncategory from that group. A group contains one or more Categories, all of\nthem defined in the configuration file. Then from the selected category,\nit picks a random wallpaper. You can define multiple Carousels therein.\n\n`goCarousel -any` picks a random wallpaper from the general directory\ndefined in the configuration file.\n\n`goCarousel -default` reverts to the default wallpaper defined in the\nconfiguration file. In my window manager (X11 or Wayland) I defined a\nshortcut so that when I press the `Pause` key on my keyboard, it invokes\nthis command.\n\n### Scheduler options\n\nThe application has its own scheduler.\n\n`goCarousel -verify` goes through the scheduler entries in the configuraition\nfile and tells you which ones are correct. It checks they fulfill the\nstandard CRON job notation.\n\n`goCarousel -task` examines the schedules defined in the configuration file,\nand checks if any of those are due (just like CRON does). If anything is\ndue, it performs the desired action:\n\n```\n    {\n      \"title\": \"Fun Time\",\n      \"action\": \"ActChosenCarousel\",\n      \"argument\": \"Private\",\n      \"cron_tab\": \"*/10 13-14 * * 1-5\"\n    },\n```\n\nThis Scheduled task is named `Fun Time` and is considered due every\n10 minutes between 13-14 hours (1 PM to 2 PM) from Monday through\nFriday. When due it sets the wallpaper (*conditioned by the authorization*)\nto one from the `Private` **carousel**.\n\n![](./assets/goCarousel_schedule.png)\n\nTogether with `-task` you can use the `-next` option which will enumerate\neach of the registered tasks and when would be the next time they would run.\n\nThe following are valid **Task** actions. All tasks need a Task schedule (CRON\nnotation):\n\n* `ActChosenCarousel` (carousel name as argument) Pick from *Carousel*\n* `ActDefaultWallpaper` (no argument) Pick default wallpaper\n* `ActLockCarousel` (no argument) *Locks* carousel\n* `ActUnlockCarousel` (no argument) *Unocks* carousel\n* `ActChosenCategory` (category name as argument) Pick from chosen *Category*\n* `ActChosenFile` (wallpaper file as argument) Pick that specific wallpaper.\n\n`goCarousel -daemon MINUTES` A great option to run the carousel if you just want to \nlet it do its thing without needing user CRON entries. Provided you have\nentered scheduling information in the `schedules` section of the JSON \nconfiguration file, the application will run in daemon mode.\n\nWhile in daemon mode, it will not return until the specified amount of \n*Minutes*  have elapsed. During that time, it will perform any task from\nthe `schedules` section as they become due. Note that the configuration\nfile has options for the daemon in the `angel` section. There you can\nspecify the Actions that will be done upon entering and exit that mode.\n\n## Configuration\n\nThe configuration file is formatted as JSON in the `~/.config/coralys/goCarousel.json`\nfile.\n\nIf you read this document properly, you should know you can generate a sample\nversion similar to [this](./goCarousel_sample.json).\n\n### CRON Scheduling\n\nIf you will be running `goCarousel` from as a CRON job, then a bunch of information\nwill not be available to the process. The application will have to dig the information\nby querying processes (not yet implemented). As a last resort, it will use the \n`assume_session` option in the `options` section of the configuration file. This\nvalue must be one of: `gnome, xfce4, lxde, cinnamon`.\n\n### Desktop Notifications\n\n![](./assets/goCarousel_cron.png)\n\nIf you want desktop notifications every time the wallpaper is changed, then enable\nthem  by setting `notify` to `true` in the `options` section of the configuration\nfile. Please ensure that your system has a properly setup notifications system.\n\n### Protected Categories\n\n```\n    \"Anime\": {\n      \"protected\": true,\n      \"key_name\": \"MMC_Card\",\n      \"directory\": \"/home/lordofscripts/Pictures/Wallpapers/Anime\"\n    }\n```\n\nProtected **Categories** are used when you have wallpapers that may not look\nvery professional in your environment. For example Anime on the workplace, etc.\nFor that, you set the `protected` attribute to `true` in the corresponding\ncategory and you must also set the `key_name` attribute of that same category.\nThe value of the key name must be one of those listed as JSON *key* in the\n`key_devices` section of the configuration file.\n\n```\n  \"key_devices\": {\n    \"MMC_Card\": \"058f:6335 E0FD-1813 5844bef71c16299cc5d73334153544be\",\n    \"USB-Maxell\": \"058f:6387 MAXELL_RED 5844bef71c16299cc5d73334153544be\"\n  }\n```\n\nThe matching key has a value with three fields separated by a *space*.\nThe 1st is a `vendorId:productId` pair, every USB or MMC card has it.\nThe 2nd is the device's *volume label* and the 3rd is an MD5 sum/hash\nof a file named `goCarousel.png` found on the root directory of that\ndevice. For that `goCarousel` must find the mounting point. But in\ngeneral this simple scheme works well and does not need to be cryptographically\nsecure.\n\nDo you need the MD5 file hash of your chosen object? It is easy without\ninstalling anything that isn't already on your computer:\n\nOn **Windows** use **PowerShell**: `Get-FileHash E:\\goCarousel.png -Algorithm MD5`\n\nOn **Linux** use any terminal window and type: `md5sum /path/to/goCarousel.png`\n \n## Sponsors\n\n*Become a sponsor and get your name listed here!*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flordofscripts%2Fgo-carousel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flordofscripts%2Fgo-carousel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flordofscripts%2Fgo-carousel/lists"}