wallpaperctl/readme.md

161 lines
4.5 KiB
Markdown
Raw Normal View History

2022-04-10 20:50:17 +00:00
# Wallpaperctl
2021-05-13 21:46:12 +00:00
2022-04-12 00:18:07 +00:00
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)
- [Available picture-options](#available-picture-options)
- [External Links](#external-links)
**Note:** Verified to work on Arch Linux with GNOME v3.14 to v42.
## 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.
2022-04-12 00:29:34 +00:00
```console
$ git clone https://gitlab.com/adouglas/wallpaperctl.git
```
2022-04-12 00:18:07 +00:00
1. Change to project directory.
2022-04-12 00:29:34 +00:00
```console
$ cd wallpaperctl
```
2022-04-12 00:18:07 +00:00
1. Install Systemd unit files.
2022-04-12 00:29:34 +00:00
```console
# cp etc/systemd/user/wallpaperctl.* /etc/systemd/user/
```
2022-04-12 00:18:07 +00:00
1. Install script file.
2022-04-12 00:29:34 +00:00
```console
# cp usr/local/bin/wallpaperctl /usr/local/bin/
```
2022-04-12 00:18:07 +00:00
1. Reload the systemd configuration.
2022-04-12 00:29:34 +00:00
```console
# systemctl daemon-reload
```
2022-04-12 00:18:07 +00:00
1. Set execute permission.
2022-04-12 00:29:34 +00:00
```console
# chmod +x /usr/local/bin/wallpaperctl
```
2022-04-12 00:18:07 +00:00
## Configuration
1. Enable the Systemd timer.
2022-04-12 00:29:34 +00:00
```console
$ systemctl --user enable wallpaperctl.timer
```
2022-04-12 00:18:07 +00:00
1. Verify the timer is enabled.
2022-04-12 00:29:34 +00:00
```console
$ systemctl --user list-unit-files
wallpaperctl.service disabled
wallpaperctl.timer enabled
2 unit files listed.
```
2022-04-12 00:18:07 +00:00
1. Start the Systemd timer.
2022-04-12 00:29:34 +00:00
```console
$ systemctl --user start wallpaperctl.timer
```
2022-04-12 00:18:07 +00:00
1. Verify the timer has been started.
2022-04-12 00:29:34 +00:00
```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.
```
2021-05-13 21:46:12 +00:00
2022-04-12 00:18:07 +00:00
## Custom Settings
2021-05-13 21:46:12 +00:00
2022-04-12 00:18:07 +00:00
### Change Wallpaper Directory
This alteration will set the location of where wallpapers are stored.
2021-05-13 21:46:12 +00:00
1. Create the required directories.
2022-04-12 00:29:34 +00:00
```bash
$ mkdir ~/.config/systemd ~/.config/systemd/user
```
2021-05-13 21:46:12 +00:00
2. Create the configuration file. Replace "username" with applicable value.
2022-04-12 00:29:34 +00:00
```bash
$ nano ~/.config/systemd/user/wallpaperctl.conf
```
2021-05-13 21:46:12 +00:00
WALLPAPER_DIR=/home/username/Pictures/wallpaper
2022-04-12 00:18:07 +00:00
### Change Wallpaper Duration
2021-05-13 21:46:12 +00:00
2022-04-12 00:18:07 +00:00
This alteration will set the duration of how long the wallpaper is displayed for until a new wallpaper is set.
2021-05-13 21:46:12 +00:00
1. Create the required directories.
2022-04-12 00:29:34 +00:00
```console
$ mkdir -p ~/.config/systemd/user
```
2022-04-12 00:18:07 +00:00
1. Create the configuration file.
2022-04-12 00:29:34 +00:00
```console
$ nano ~/.config/systemd/user/wallpaperctl.timer
```
2022-04-12 00:18:07 +00:00
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.
2021-05-13 21:46:12 +00:00
2022-04-12 00:29:34 +00:00
```
[Unit]
Description=Wallpaperctl - Systemd GNOME wallpaper changer
2021-05-13 21:46:12 +00:00
2022-04-12 00:29:34 +00:00
[Timer]
OnCalendar=*:0/5
Persistent=true
Unit=wallpaperctl.service
2021-05-13 21:46:12 +00:00
2022-04-12 00:29:34 +00:00
[Install]
WantedBy=wallpaperctl.service
```
2021-05-13 21:46:12 +00:00
2022-04-12 00:18:07 +00:00
## Reference
Not applicable at this time. Here for future use.
### Available picture-options
2021-05-13 21:46:12 +00:00
- none
- wallpaper
- centered
- scaled
- stretched
- zoom
- spanned
## External Links
* https://wiki.archlinux.org/index.php/Systemd/User
* https://wiki.archlinux.org/index.php/Systemd/Timers
* https://major.io/2015/02/11/rotate-gnome-3s-wallpaper-systemd-user-units-timers/
* https://stackoverflow.com/questions/10374520/gsettings-with-cron