This program is client-server application, where the server works as a daemon and regularly
executes a shell command, going through a playlist of files. If the command is something like
feh --bg-fill {}, and the playlist contains images, then it will result in a change of
desktop background after the next configured interval passes. Thus you can configure a list
of wallpapers, set the interval and then enjoy a new background picture every hour or so :)
wcd is mostly intended for users of lightweight desktop environments on Linux, like i3 or Awesome or Openbox or whatever. However, the program is cross-platform, and if you can change the wallpaper through some shell command on your system, you can use it.
The daemon and the client programs are combined in a single binary. With the command-line client you can trigger immediate wallpaper change, switch playlists, get current status etc. For example, you can bind a key shortcut in your window manager to force wallpaper change when you want it. Or maybe to switch between SFW and NSFW playlists, if the situation needs it :)
wcd uses Cargo, so first install the Rust compiler, and then run the following command to install the binary:
% cargo install --git https://github.com/netvl/wcd wcd
This command will install the binary to wherever your Cargo binaries directory is located
(usually it is ~/.cargo/bin), so in order to run them, you need to make sure that this
directory is added to your PATH.
While wcd does not use compiler features and therefore could theoretically be compiled with the stable Rust compiler, I use nightly Rust for development. I'll probably add a Travis configuration with multiple Rust versions in future to track this.
Note that wcd depends on nanomsg, so you need to have its libraries
available for the linker. Currently nanomsg-rs does not use pkg-config to find libraries,
so you need to make nanomsg shared library available in the library search path (PATH in
Windows, LD_LIBRARY_PATH in Linux, DYLD_LIBRARY_PATH in OS X). On Linux it usually means
installing the respective package with your package manager.
Both the daemon and the client use the same configuration file. By default it is assumed to be
~/.config/wcd/config.toml. Maybe in the future I'll change it to consider $XDG_CONFIG_DIR
or other platform-specific configuration directory, but for now the default is harcoded.
You can use -c command line option to choose another config file.
The configuration file is a TOML document. Here is an example:
[common]
endpoint = "ipc:///tmp/wcd.ipc"
[server]
default_playlist = "default"
watch = "1 minute"
# watch = "disabled"
[server.defaults]
mode = "random" # or "sequential"
change_every = "1 hour"
trigger_on_select = true
use_last_on_select = true
command = ["feh", "--bg-fill", "{}"]
[server.playlists.default]
files = ["~/downloads/pic.jpg", "/usr/share/whatever/picture.png"]
directories = ["~/pictures/wallpapers", "/mnt/storage/pictures"]
change_every = "2 hours"
[server.playlists.sfw]
directories = ["~/pictures/safe"]
mode = "sequential"
use_last_on_select = false[common] section contains a single option, endpoint, which is needed to set up the connection
between the daemon and the client. wcd uses nanomsg for client-server
communication, and so it supports all the transports as they are described
in its documentation (scroll to the bottom). Because
usually both the server and the client are located on the same machine, it makes sense to
use the ipc transport which maps to a UNIX socket. I haven't tested it on Windows so I can't say
whether ipc works there, but the tcp transport should work anywhere. Because the same
configuration file is shared by both the daemon and the client, this address needs to be configured
only once.
The [server] section contains global server configuration options.
default_playlistspecifies the playlist which will be used immediately after the daemon starts up. Afterwards the playlist can be changed to one of the other configured playlists with the client; more on it below.watchdefines the playlist refresh behavior. If you add new images to the directories configured for playlists, wcd will detect them and incorporate them into the respective playlists automatically. This option determines the interval between full directory rescans. Put"disabled"here to disable regular polls. Either way, you can always force a refresh with the client. In a future version I may add an inotify-based (or whatever cross-platform file watch library I will be able to find) watch.
[server.default] controls the default options for all playlists. Each option in this
section may be overridden inside a playlist. There is no way to configure default files
and directories, however.
modedetermines the way the playlist will be "executed". When wcd starts, it compiles a list of all appropriate files for each playlist. If this option is set to"random", then this list will be shuffled. Moreover, the reshuffle will occur after the playlist ends."sequential"means that the order of files will be fixed and equal to the order reported by the file system when directories are scanned.change_everysets the interval after which the next item in the playlist should be used. You can use any unit from nanoseconds up to days (including abbreviations likeus,micros,mins, etc., and either singular or plural form:secondorseconds), however, wcd's scheduler resolution is 1 second so intervals smaller than this are useless.trigger_on_selectdetermines whether the wallpaper should be changed if you has switched to this playlist from some other playlist. It works in conjuction withuse_last_on_selectoption, see below. If this option is set tofalse, then making this playlist current will not make wcd execute any commands (unless the interval for this playlist is smaller than the one for the previous playlist, and it has already passed since the last wallpaper switch). If set totrue, this option's behavior is determined by theuse_last_on_selectoption.use_last_on_selectis only considered iftrigger_on_selectistrue. If this option istrue, then the last used wallpaper will be restored after this playlist is selected. The timer, however, will be reset, so the next change will happen after the duration configured for this playlist. If this option isfalse, then the next image will be used, with the usual effect on the timer.commandsets up the command which should be executed to change the wallpaper. The command is a list of strings, where the first item is the command name and all other items are passed to the command as arguments. Each occurence of{}placeholder in options will be replaced with the image file name, however,{}only works as a whole argument:"-c={}"means-c={}, not-c=<file name>. It is an error for this option to be an empty list, as well as to have no placeholders among the arguments.
All of these options are optional for the defaults section. If they are absent here, they must
be configured for each playlist separately; it is an error if any of them, except
trigger_on_select and use_last_on_select, are not set at least in one place.
trigger_on_select and use_last_on_select, if absent, are assumed to be true.
Each of [server.playlists.<name>] section configures a playlist named <name>. These sections
may contain the same options as the [server.defaults] section (and if present, they will take preference
over the defaults), and also two additional options are available:
filesis a list of files which must be included into the playlist.directoriesis a list of directories which should be scanned for image files. Currently wcd determines whether a file is an image by extension, and it understandsjpg,jpegandpngextensions, both in lower, upper or mixed case. These directories will also be rescanned automatically if watch interval is configured or manually when requested through the client.
Paths specified in files or directories lists may start with ~/. These paths are resolved
against the home directory of the user running wcd.
The daemon should be started by invoking wcd daemon. It will be started in the foreground, so if you
want to start it as a service, you should use a service manager specific for your OS (e.g. systemd on Linux).
Other subcommands, like wcd status, belong to the client and allow to interact with the daemon. wcd --help
provides the entire list of subcommands with their descriptions, so they won't be covered here.
wcd understand a -v switch which can be passed zero, one or two times, with each passed option increasing the
verbosity of the daemon output. For client subcommands -v may also result in extra output except that of the
executed command. These options are useful for debugging.
In no particular order:
- Add support for persisting the state of the daemon between reloads.
- Add support for printing out wallpapers playlists and selecting a particular wallpaper.
- Create a web UI for controlling the daemon.
This program is licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.