wallpaperctl/readme.md

172 lines
5.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Wallpaperctl
A light weight script to automatically set and rotate through computer desktop wallpaper. Desktop wallpaper rotation
is based upon a set duration (default, 1 minute). Wallpaper is randomly selected and defaults to look for wallpaper
from the user's home directory under "Pictures/wallpaper/" (e.g. "/home/adam/Pictures/wallpaper").
- [Installation](#installation)
- [Assumptions](#assumptions)
- [Dependency Requirements](#dependency-requirements)
- [Setup](#setup)
- [Configuration](#configuration)
- [Custom Settings](#custom-settings)
- [Change Wallpaper Directory](#change-wallpaper-directory)
- [Change Wallpaper Duration](#change-wallpaper-duration)
- [Reference](#reference)
- [Wallpaper Options](#wallpaper-options)
- [External Links](#external-links)
**Note:** Verified to work on Arch Linux with GNOME v3.14 to v43.
## Installation
### Assumptions
- Have experienced working knowledge within a CLI (command-line interface)
- Understanding of Linux operating system
- Installed all required dependencies as stated in [Dependency Requirements](#dependency-requirements) section
- Installation is done via Linux CLI
- Steps prefixed with a "$" (dollar sign) represents the CLI prompt
- Steps prefixed with a "#" (number sign) represents the CLI prompt with
elevated user permissions (e.g. root)
- The text after the "$" or "#" is to be entered at the CLI
- The installation instructions are an example of installation and configuration
### Dependency Requirements
- BASH v5+
- Git v2+
- GNOME v3.14+
### Setup
1. Clone the project.
```console
$ git clone https://gitlab.com/adouglas/wallpaperctl.git
```
1. Change to project directory.
```console
$ cd wallpaperctl
```
1. Install Systemd unit files.
```console
# cp etc/systemd/user/wallpaperctl.* /etc/systemd/user/
```
1. Install script file.
```console
# cp usr/local/bin/wallpaperctl /usr/local/bin/
```
1. Reload the systemd configuration.
```console
# systemctl daemon-reload
```
1. Set execute permission.
```console
# chmod +x /usr/local/bin/wallpaperctl
```
## Configuration
1. Enable the Systemd timer.
```console
$ systemctl --user enable wallpaperctl.timer
```
1. Verify the timer is enabled.
```console
$ systemctl --user list-unit-files
wallpaperctl.service disabled
wallpaperctl.timer enabled
2 unit files listed.
```
1. Start the Systemd timer.
```console
$ systemctl --user start wallpaperctl.timer
```
1. Verify the timer has been started.
```console
$ systemctl --user list-timers
NEXT LEFT LAST PASSED UNIT ACTIVATES
Thu 2016-03-10 18:49:00 CST 1s left Thu 2016-03-10 18:48:56 CST 1s ago wallpaperctl.timer wallpaperctl.service
1 timers listed.
Pass --all to see loaded but inactive timers, too.
```
## Custom Settings
### Change Wallpaper Directory
This alteration will set the location of where wallpapers are stored.
1. Create the required directories.
```bash
$ mkdir ~/.config/systemd ~/.config/systemd/user
```
2. Create the configuration file. Replace "username" with applicable value.
```bash
$ nano ~/.config/systemd/user/wallpaperctl.conf
```
WALLPAPER_DIR=/home/username/Pictures/wallpaper
### Change Wallpaper Duration
This alteration will set the duration of how long the wallpaper is displayed for until a new wallpaper is set.
1. Create the required directories.
```console
$ mkdir -p ~/.config/systemd/user
```
1. Create the configuration file.
```console
$ nano ~/.config/systemd/user/wallpaperctl.timer
```
1. Change the OnCalendar value as desired.
Refer to [ArchLinux: systemd/Timers](https://wiki.archlinux.org/index.php/Systemd/Timers#Realtime_timer) for further
details. The below example changes the duration interval from 1 minute to 5 minutes.
```
[Unit]
Description=Wallpaperctl - Systemd GNOME wallpaper changer
[Timer]
OnCalendar=*:0/5
Persistent=true
Unit=wallpaperctl.service
[Install]
WantedBy=wallpaperctl.service
```
## Reference
### Wallpaper Options
Desktop wallpaper can be displayed in the following ways (org.gnome.desktop.background.picture-options).
**Note:** Not applicable at this time. Here for future use.
- none
- wallpaper
- centered
- scaled
- stretched
- zoom
- spanned
Acceptable display setting values are sourced from:
```console
$ gsettings describe org.gnome.desktop.background picture-options
```
```console
Determines how the image set by wallpaper_filename is rendered. Possible values are “none”, “wallpaper”, “centered”, “scaled”, “stretched”, “zoom”, “spanned”.
```
## External Links
* [Gsettings with cron - Stack Overflow](https://stackoverflow.com/questions/10374520/gsettings-with-cron)
* [Rotate GNOME 3s wallpaper with systemd user units and timers - Major Hayden](https://major.io/2015/02/11/rotate-gnome-3s-wallpaper-systemd-user-units-timers/)
* [systemd/Timers - ArchWiki](https://wiki.archlinux.org/index.php/Systemd/Timers)
* [systemd/User - ArchWiki](https://wiki.archlinux.org/index.php/Systemd/User)