{"id":14128522,"url":"https://github.com/nwg-piotr/azote","last_synced_at":"2025-05-15T20:07:39.494Z","repository":{"id":34956710,"uuid":"190817206","full_name":"nwg-piotr/azote","owner":"nwg-piotr","description":"Wallpaper manager for wlroots-based compositors and some other WMs","archived":false,"fork":false,"pushed_at":"2025-04-27T13:39:13.000Z","size":49054,"stargazers_count":385,"open_issues_count":8,"forks_count":29,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-27T14:27:25.253Z","etag":null,"topics":["background","colour-manager","dwm","feh","i3","i3wm","openbox","sway","swaybg","swaywm","wallpaper-changer","wallpapers","wayfire"],"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/nwg-piotr.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,"zenodo":null},"funding":{"github":"nwg-piotr","liberapay":"nwg"}},"created_at":"2019-06-07T22:22:13.000Z","updated_at":"2025-04-27T13:37:58.000Z","dependencies_parsed_at":"2024-05-03T00:44:48.335Z","dependency_job_id":"086411d9-a561-49d7-af50-1bf69f673f9e","html_url":"https://github.com/nwg-piotr/azote","commit_stats":{"total_commits":576,"total_committers":22,"mean_commits":"26.181818181818183","dds":"0.10590277777777779","last_synced_commit":"826abb451cc7cef399cc9967ef0a06553c06497d"},"previous_names":[],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nwg-piotr%2Fazote","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nwg-piotr%2Fazote/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nwg-piotr%2Fazote/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nwg-piotr%2Fazote/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nwg-piotr","download_url":"https://codeload.github.com/nwg-piotr/azote/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414501,"owners_count":22067272,"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":["background","colour-manager","dwm","feh","i3","i3wm","openbox","sway","swaybg","swaywm","wallpaper-changer","wallpapers","wayfire"],"created_at":"2024-08-15T16:01:47.589Z","updated_at":"2025-05-15T20:07:34.432Z","avatar_url":"https://github.com/nwg-piotr.png","language":"Python","funding_links":["https://github.com/sponsors/nwg-piotr","https://liberapay.com/nwg"],"categories":["Wallpapers \u0026 Backgrounds","Python","Packages"],"sub_categories":["Dock Libraries","Background setting utilities and generators"],"readme":"\u003cimg src=\"https://github.com/nwg-piotr/azote/assets/20579136/6ee4b9aa-e73d-4c9f-9665-a86bd76c045b\" width=\"90\" style=\"margin-right:10px\" align=left alt=\"nwg-shell logo\"\u003e\n\u003cH1\u003eAzote\u003c/H1\u003e\u003cbr\u003e\n\nThis application is a part of the [nwg-shell](https://nwg-piotr.github.io/nwg-shell) project.\n\n**Azote** is a GTK+3 - based picture browser and background setter, as the frontend to the [swaybg](https://github.com/swaywm/swaybg) \n(sway/Wayland) and [feh](https://feh.finalrewind.org) (X windows) commands. The user interface is being developed with\nmulti-headed setups in mind. Azote also includes several colour management tools.\n\n[![Packaging status](https://repology.org/badge/vertical-allrepos/azote.svg)](https://repology.org/project/azote/versions)\n\nThe program, written primarily for sway, should work on all wlroots-based Wayland compositors, as well as on\nsome X11 window managers. GNOME is not supported.\n\nAzote relies on numerous external packages. Some of them determine if the program is capable of working in a certain\nenvironment (sway / another wlroots-based compositor / X11). It's **up to the packager** which of them come preinstalled.\nIt's recommendable to first run `azote` from terminal:\n\n- if one of missing packages disallows Azote to work at all (e.g. `python-xlib` or `feh` on X11, `wlr-randr` or \n`swaybg` on Wayfire), the program will display a message and terminate with exit code 1.\n\n- If a missing dependency just stops some feature from working, Azote will display a message and start normally.\n\n```text\n$ azote\npython-send2trash package not found - deleting pictures unavailable\nRunning on Wayland, but not sway\nAvailable screen height: 1030 px; measurement delay: 5 ms\n```\n\n\u003cimg src=\"https://user-images.githubusercontent.com/20579136/170864580-840e1c27-702d-40f4-a98c-a460826b805c.png\" width=640 alt=\"screenshot\"\u003e\u003cbr\u003e\n\n## Project assumptions\n\nThe most commonly used *desktop background browser and setter* is aimed at X windows, and does not work with \nwlroots-based composers. Since the `swaybg` command does everything we may need, it's enough to give it a GUI. \nIn order not to limit the program usage to the single environment, Azote is also capable of using feh \nwhen running on i3, Openbox or other X11 window managers.\n\n*The description below takes into account the current `master` branch. All the features may or may not be available in the\npackage already released for a certain Linux distribution. Some features rely on \n[optional dependencies](https://github.com/nwg-piotr/azote#dependencies-as-used-in-the-azote-aur-package).*\n\n### Main features:\n\n- works on wlroots;\n- uses own thumbnails, 240x135px by default;\n- flips wallpapers horizontally;\n- splits wallpapers between 2 or more displays;\n- scales and crops images to detected or user-defined display dimensions;\n- generates a colour palette on the basis of an image;\n- picks a colour from the screen;\n- allows to find and edit colour definitions in `.Xresources` and `alacritty.yml` files.\n\n## Usage\n\nSelect the folder your wallpapers are stored in. If it contains a lot of big pictures, it may take some time for\nAzote to create thumbnails. It's being performed once per folder, unless you clear the thumbnails folder.\n\nMost of the buttons seem to be self-explanatory, with a little help from their tooltip text. What may not be clear\nat first is the `Apply selected picture to all screens` button. It applies unchanged\nselected picture to all displays, regardless of whether they are currently connected/detected. It may be useful if you\noften connect and disconnect displays. A shortcut to this feature is just to double click a thumbnail. It'll always \nuse the 'fill' mode, however.\n\nAzote, as well as feh, saves a batch file to your home directory. It needs to be executed in order to set the wallpaper \non subsequent logins or reboot.\n\n### sway\n\nEdit your `~/.config/sway/config` file. Replace your current wallpaper settings, like:\n\n```bash\noutput * bg /usr/share/backgrounds/sway/Sway_Wallpaper_Blue_1920x1080.png fill\n```\n\nwith:\n\n```bash\nexec ~/.azotebg\n```\n\n### Hyprland\n\nAdd `exec-once = ~/.azotebg-hyprland` to your hyprland.conf. \n\nSince v1.12.0, we no longer use common ~/.azotebg file on sway and Hyprland, as they don't detect generic \ndisplay names the same way.\n\n### Wayfire\n\nIn `~/.config/wayfire.ini` set `autostart_wf_shell = false`, and replace `background = wf-background` with \n`background = ~/.azotebg`.\n\n**Important:** optional `wlr-randr` / `wlr-randr-git` and `swaybg` packages are necessary.\n\n### X window managers (i3, Openbox, dwm etc.)\n\nYou need to execute `~/.fehbg` from your window manager’s startup file.\nYou'll also need optional `feh` and `python-xlib` (or `python3-xlib`, depending on the distro) packages.\n\n**Important:** optional `python-xlib` and `feh` packages are necessary.\n\n**dwm note:**\n\nIf you start dwm from a script, it may look something like this:\n\n```bash\n# Statusbar loop\nwhile true; do\n   xsetroot -name \"$( date +\"%F %R\" )\"\n   sleep 1m    # Update time every minute\ndone \u0026\n\n# Autostart section\n~/.fehbg \u0026 \n\nexec dwm\n```\n\n### Dependencies (as used in the `azote` Arch package):\n\n- `python` (`python3`)\n- `python-setuptools`\n- `python-gobject`\n- `python-pillow`\n- `gtk3`\n- `python-cairo`\n- `python-send2trash`\n\n### Optional dependencies:\n\n- `python-pillow-jxl-plugin` | `python-pillow-jpegxl-plugin`: for JPEG XL support in Pillow\n- `imagemagick`: for screen color picker in every environment\n- `grim`, `slurp`: for screen color picker on sway / wlroots\n- `maim`, `slop`: for screen color picker on X11\n- `libappindicator-gtk3`: for tray status icon\n- `python-yaml`: for alacritty.yml toolbox\n- `swaybg`: for setting background on wlroots-based compositors other than sway\n- `feh`: for setting background on X11-based WMs\n- `python-xlib`: for checking outputs on X11-based WMs\n- `wlr-randr` (`wlr-randr-git`): for checking outputs on wlroots-based compositors other than sway\n\nPlease use assets from the [latest release](https://github.com/nwg-piotr/azote/releases/latest).\n\nSeeing Arch [PKGBUILD](https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=azote) may be informative.\n\n## ~/.config/azote/azoterc\n\n```json\n{\n  \"thumb_width\": \"240\",\n  \"columns\": \"3\",\n  \"color_icon_w\": \"100\",\n  \"color_icon_h\": \"50\",\n  \"clip_prev_size\": \"30\",\n  \"palette_quality\": \"10\",\n  \"tracking_interval_seconds\": \"5\",\n  \"screen_measurement_delay\": \"300\"\n}\n```\n\nAzote is being developed on the 1920 x 1080 box, and some graphics dimensions may not go well with other screens.\nThe runtime configuration file allows to redefine them:\n\n- `thumb_width` - thumbnail width; changing the value triggers thumbnails regeneration on startup;\n- `columns` - initial number of columns in thumbnails preview;\n- `color_icon_w`, `color_icon_h`, `clip_prev_size` - define dimensions of pictures which represent colors in the color \npalette view;\n- `palette_quality` - affects quality and time of generation of the colour palette on the basis of an image; the less - the\nbetter, but slower; default value is 10;\n- `tracking_interval_seconds` - determines how often the current wallpapers folder should be checked for file addition / \ndeletion;\n- `screen_measurement_delay` (ms) - introduced to resolve [#108](https://github.com/nwg-piotr/azote/issues/108).\nSince `Gdk.Screen.height` has been deprecated, there's no reasonable way to determine the screen dimensions. \nWe need to open a temporary window and measure its height to open the Azote window with maximum allowed vertical dimension.\nDifferent hardware and window managers need different time to accomplish the task. Increase the value if the (floating) \nwindow does not scale to the screen height. Decrease as much as possible to speed up launching Azote.\n\n## Command line arguments\n\n```text\n$ azote -h\n\nAzote wallpaper manager version 1.x.y\n\n[-h] | [--help]\t\t\t Print help\n[-l] | [--lang] \u003cln_LN\u003e \t Force a locale (de_DE, en_EN, fr_FR, pl_PL)\n[-c] | [--clear]\t\t Clear unused thumbnails\n[-a] | [--clear-all]\t\t Clear all thumbnails\n```\n\n## Troubleshooting\n\n### [sway] My outputs use random names, wallpapers get lost after restart\n\nTurn the \"Use generic display names\" preferences switch on (since v1.9.1).\nSee [#143](https://github.com/nwg-piotr/azote/issues/143).\n\n### No pictures in thumbnails / display preview\n\nAs well thumbnails, as displays preview inherit from the Gtk.Button class. In case you don't see images inside them,\nplease make sure that button images are turned on in the `~/.config/gtk-3.0/settings.ini` file:\n\n```bash\n[Settings]\n(...)\ngtk-button-images=1\n```\n\n### 'Open with...' feature doesn't work\n\n**Azote v1.2.0 and below** - no 'Open with' menu entry at all;\n\n**Azote v1.3.0 and above** - the only program listed is feh.\n\nThe `/usr/share/applications/mimeinfo.cache` is probably missing from your system. Regenerate it:\n\n```bash\n$ sudo update-desktop-database\n```\n\nSee https://specifications.freedesktop.org/desktop-entry-spec/0.9.5/ar01s07.html\n\n### Floating Azote window does not scale to the screen height\n\nSince `Gdk.Screen.height` has been deprecated, there's no reasonable way to determine the screen dimensions. \nWe need to open a temporary window (maximized or fullscreened on sway) and measure its height to open the Azote \nwindow with maximum allowed vertical dimension.\n\n*This does not apply to sway, where we measure the screen in another way.*\n\nIn `~/.config/azote/azoterc` you'll find the `\"screen_measurement_delay\": \"300\"` value. Different hardware \nand window managers need different time to open the temporary window. Increase the value if the (floating) \nwindow does not scale to the screen height. Decrease as much as possible to speed up launching Azote (and not to \nsee the black screen on sway). On my development machine the minimum value is 30 ms on sway and 5 ms on Wayfire.\n\n## X11 / feh notice\n\nYou'll be unable to select different modes\n*(\"scale\", \"max\", \"fill\", \"center\", \"tile\")* for certain displays. The list of modes varies from what you see in Sway \n*(\"stretch\", \"fit\", \"fill\", \"center\", \"tile\")*.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnwg-piotr%2Fazote","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnwg-piotr%2Fazote","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnwg-piotr%2Fazote/lists"}