{"id":31885071,"url":"https://github.com/bcyran/timewall","last_synced_at":"2025-10-13T04:20:16.595Z","repository":{"id":62054392,"uuid":"535836233","full_name":"bcyran/timewall","owner":"bcyran","description":"Apple dynamic HEIF wallpapers on GNU/Linux.","archived":false,"fork":false,"pushed_at":"2025-10-01T17:05:33.000Z","size":767,"stargazers_count":83,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-10-10T13:41:38.840Z","etag":null,"topics":["dynamic-wallpaper","heif","wallpaper"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bcyran.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2022-09-12T20:17:57.000Z","updated_at":"2025-10-09T14:46:26.000Z","dependencies_parsed_at":"2023-11-19T09:27:11.818Z","dependency_job_id":"4290f14d-5e58-4245-a22d-34978d2bf54b","html_url":"https://github.com/bcyran/timewall","commit_stats":{"total_commits":173,"total_committers":3,"mean_commits":"57.666666666666664","dds":"0.19653179190751446","last_synced_commit":"791495c75b858546f7e56816f89f8244ee0d8ad9"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/bcyran/timewall","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcyran%2Ftimewall","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcyran%2Ftimewall/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcyran%2Ftimewall/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcyran%2Ftimewall/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bcyran","download_url":"https://codeload.github.com/bcyran/timewall/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcyran%2Ftimewall/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279013683,"owners_count":26085390,"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","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["dynamic-wallpaper","heif","wallpaper"],"created_at":"2025-10-13T04:20:13.785Z","updated_at":"2025-10-13T04:20:16.585Z","avatar_url":"https://github.com/bcyran.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# timewall\n\n[![CI](https://github.com/bcyran/timewall/actions/workflows/test.yml/badge.svg)](https://github.com/bcyran/timewall/actions/workflows/test.yml)\n[![test coverage](https://codecov.io/gh/bcyran/timewall/branch/master/graph/badge.svg?token=Z025ICENDQ)](https://codecov.io/gh/bcyran/timewall)\n[![license](https://img.shields.io/github/license/bcyran/timewall)](https://github.com/bcyran/timewall/blob/master/LICENSE)\n[![Crates.io](https://img.shields.io/crates/v/timewall)](https://crates.io/crates/timewall)\n\nApple dynamic HEIF wallpapers on GNU/Linux.\n\n![timewall_preview](https://user-images.githubusercontent.com/8322846/197593208-0e0b7901-2caf-43b0-b7fd-847c2cb49ff1.gif)\n\n\u003c/div\u003e\n\n---\n\nFeatures:\n- Support for original HEIF/HEIC dynamic wallpaper files used in MacOS.\n- Support for all schedule types: sun position based, time based, dark/light mode.\n- Automatic location using GeoClue 2 service.\n- Set wallpaper once and continuously (daemon mode).\n- Preview wallpaper changes.\n- Display wallpaper metadata.\n- Extract all images and metadata as XML.\n\n---\n\n## Installation\n### Repositories\n[![Packaging status](https://repology.org/badge/vertical-allrepos/timewall.svg)](https://repology.org/project/timewall/versions)\n\n### Prerequisites\n`timewall` depends on [`libheif`](https://github.com/strukturag/libheif) \u003e= 1.19.7 for HEIF support, make sure you have it installed.\nIf you're building it from source you may also need `libheif-dev`, depending on your distribution.\n\n### Binary\nYou can download tarball containing the latest prebuilt binary and shell completions from the [releases page](https://github.com/bcyran/timewall/releases).\nThe binary named `timewall` has to be placed in directory in your `$PATH`, e.g. `/usr/local/bin`.\n\n### Cargo\n```\ncargo install timewall\n```\n\n### Nix\nThis repository contains a flake exposing a Nix package, `nixpkgs` overlay and a Home Manager module.\nAdd `timewall` input to your `flake.nix`:\n```nix\ninputs.timewall.url = \"github:bcyran/timewall\";\n```\n#### Package\n```nix\nenvironment.systemPackages = [\n  inputs.timewall.packages.${pkgs.system}.timewall\n];\n```\n\n#### Overlay\n```nix\nnixpkgs.overlays = [\n  inputs.timewall.overlays.default\n]\nenvironment.systemPackages = [\n  pkgs.timewall\n];\n```\n\n#### Home Manager\n```nix\nservices.timewall = {\n  enable = true;\n  wallpaperPath = ./wallpaper.heif; # optional, can be set at runtime\n  config = {} # optional, see the configuration section\n}\n```\n\n## Usage\n\n\u003e [!IMPORTANT]\n\u003e If you intend to use sun position based wallpapers, `timewall` will need your approximate location.\n\u003e Please make sure GeoClue 2 service is available or manually configure your location.\n\u003e See [Configuration](#configuration).\n\n### Setting the wallpaper\n#### One-time mode\nTo set the wallpaper just run:\n```\ntimewall set path/to/wallpaper.heif\n```\nThis will set your wallpaper to the correct image, taking into account current time or sun position, depending on the wallpaper schedule.\nNote that wallpaper set like this will not update with time.\nYou can update it by repeating the command above, you can also shorten it to just `timewall set` - last used wallpaper is remembered.\n\nSee also: [where to find the dynamic wallpapers](#where-to-find-the-dynamic-wallpapers).\n\n#### Daemon mode\nYou probably don't want to update the wallpaper manually every time.\nTo do this automatically you can use the daemon mode:\n```\ntimewall set --daemon\n```\nThis command will run continuously and update your wallpaper as time passes.\nIt's a good idea to run it automatically at startup as a background process.\n\nAs you can see, the command above doesn't include the wallpaper to set.\nThis is because the daemon mode by default uses the last set wallpaper.\nIf you already ran `timewall set` manually, then daemon will use whatever wallpaper you set then.\nMoreover, if you ever want to change your wallpaper, it's enough to run `timewall set path/to/new/wall.heif`.\nThe daemon will pick up the change and update the new wallpaper from now on.\n\n#### Systemd service\nOne way to achieve this is using `systemd` service.\nWrite the following contents to `~/.config/systemd/user/timewall.service`:\n```systemd\n[Unit]\nDescription=Dynamic wallpapers daemon\n\n[Service]\nType=simple\nExecStart=timewall set --daemon\n\n[Install]\nWantedBy=default.target\n```\n\nAnd run:\n```\nsystemctl --user enable --now timewall.service\n```\nAfter this `timewall` should start automatically on boot and update your wallpaper during the day.\n\n### Previewing\nTo preview the wallpaper, run:\n```\ntimewall preview path/to/wallpaper.heif\n```\nThis will quickly cycle all images in the wallpaper to simulate changes throughout the day.\nPreview speed can be controlled by specifying the delay in milliseconds between consecutive wallpaper changes using the `--delay` option.\nYou can also infinitely loop the preview using `--repeat` option.\n\n### Unpacking\nTo unpack all images stored in the wallpaper, as well as its metadata in XML format, run:\n```\ntimewall unpack path/to/wallpaper.heif path/to/output/directory\n```\n\n### Reading metadata\nAll metadata known to `timewall` can be displayed using:\n```\ntimewall info path/to/wallpaper.heif\n```\n\n### Configuration\n`timewall` uses a config file at `$XDG_CONFIG_HOME/timewall/config.toml` (usually `~/.config/timewall/config.toml`).\nA default config will be written when you first run `timewall set`.\n\n#### Automatic location\nUsing sun position based wallpapers requires your approximate geographical location.\nBy default, the GeoClue 2 service is used to automatically determine your location, unless you configure it manually (see the next section).\nYou can disable GeoClue by setting `geoclue.enable` to `false`.\n\nIf GeoClue is enabled but cannot retrieve the location, such as when in offline mode, `timewall` will automatically use the last known location by default.\nTo disable this fallback behavior, set `geoclue.cache_fallback` to `false`.\n\nThe `geoclue.prefer` setting specifies whether GeoClue should be prioritized over manual location when both are available.\nThis can be useful if you prefer using automatic detection but want to fall back to manual configuration rather than encountering an error if GeoClue is unavailable (e.g. due to no internet connection).\n\nThe `geoclue.timeout` option specifies the maximum time (in milliseconds) that `timewall` will wait to obtain a location from GeoClue.\nIf this time period elapses, `timewall` will either fall back to manual location or fail, depending on the value of `geoclue.prefer`.\n```toml\n[geoclue]\nenable = true\ncache_fallback = true\nprefer = false\ntimeout = 1000\n```\n\n\u003e [!IMPORTANT]\n\u003e You might need to grant `timewall` access to location data in GeoClue configuration.\n\u003e\n\u003e `/etc/geoclue/geoclue.conf`:\n\u003e ```conf\n\u003e [timewall]\n\u003e allowed=true\n\u003e system=false\n\u003e users=\n\u003e ```\n\u003e On NixOS:\n\u003e ```nix\n\u003e services.geoclue2.appConfig.timewall = {\n\u003e   isAllowed = true;\n\u003e   isSystem = false;\n\u003e }\n\u003e ```\n\n#### Manual location\nGeographical location can be set manually in the `location` section.\nBy default, it is prioritized over automatic location from GeoClue.\n```toml\n[location]\nlat = 51.11\nlon = 17.02\n```\n`lat` and `lon` options define the latitude and longitude respectively.\n\n#### Custom wallpaper setting command\nIf the default wallpaper setting doesn't work in your case for some reason, or you just want to customize it, you can specify custom command to use.\nFor instance, to set the wallpaper using `feh`, you could add the following to your config file:\n```toml\n[setter]\ncommand = ['feh', '--bg-fill', '%f']\nquiet = true\noverlap = 0\n```\n`%f` is a placeholder which will be replaced with full absolute path to the image, which should be set as a wallpaper.\n\nThe command is NOT passed through shell.\nIf you want to use shell features like environment variable expansion or command chaining, you need to call it explicitly:\n```toml\n[setter]\ncommand = ['bash', '-c', 'command_1 %f \u0026\u0026 command_2 %f']\n```\n\nSee also: [Wallpaper setting commands](#wallpaper-setting-commands).\n\nBy default, the command's `stdout` and `stderr` outputs are suppressed.\nYou can change this behavior by setting `setter.quiet` to `false`.\n\nThe `setter.overlap` option defines the time (in milliseconds) between spawning a new command process and terminating the old one.\nThis is useful for setter commands that continue running after setting the wallpaper (e.g.: `swaybg`).\nThe overlap period allows the new process to load and set the wallpaper, ensuring a smooth transition.\n\n#### Daemon mode wallpaper update interval\n```toml\n[daemon]\nupdate_interval_seconds = 600\n```\n\n## Where to find the dynamic wallpapers\n- Original MacOS dynamic wallpapers.\n  If you have access to a computer running MacOS, you can just copy the dynamic wallpapers.\n  You can also find those files online with a bit of effort.\n  I'm not going to link any of them because of legal reasons.\n- [Dynamic Wallpaper Club](https://www.dynamicwallpaper.club/).\n  A lot of user-created wallpapers.\n  Unfortunately, many of them are of mediocre quality.\n  Only a handful makes use of the sun position schedule (which is the best part of the whole concept to me), and those which do, usually do it poorly.\n- [Jetson Creative](https://www.jetsoncreative.com/mojave).\n  Three free wallpapers and some bundles you can buy.\n- [mczachurski/wallpaper](https://github.com/mczachurski/wallpapper).\n  Two high quality custom made walls.\n\n## Wallpaper setting commands\nThis section contains useful commands for setting the wallpaper image in various desktop environments.\n`%f` is a placeholder for the image path.\n\n### Gnome\n```shell\n# Light mode wallpaper\ngsettings set org.gnome.desktop.background picture-uri file://%f\n\n# Dark mode wallpaper\ngsettings set org.gnome.desktop.background picture-uri-dark file://%f\n\n# Lockscreen background\ngsettings set org.gnome.desktop.screensaver picture-uri file://%f\n\n```\n\n### KDE Plasma\n```shell\n# Wallpaper\nplasma-apply-wallpaperimage %f\n\n# Lockscreen background\nkwriteconfig6 --file kscreenlockerrc --group Greeter --group Wallpaper --group org.kde.image --group General --key Image %f\n\n```\n`kwriteconfig6` assumes Plasma 6, use `kwriteconfig5` for Plasma 5.\n\n\n## Resources / credits\nThe following resources helped me in `timewall` development:\n- https://itnext.io/macos-mojave-dynamic-wallpaper-fd26b0698223\n- https://itnext.io/macos-mojave-dynamic-wallpapers-ii-f8b1e55c82f\n- https://itnext.io/macos-mojave-wallpaper-iii-c747c30935c4\n- https://github.com/mczachurski/wallpapper\n- https://git.spacesnek.rocks/johannes/heic-to-gnome-xml-wallpaper\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbcyran%2Ftimewall","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbcyran%2Ftimewall","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbcyran%2Ftimewall/lists"}