Cheerlights is a system to synchronise lighting colours across the globe---this simple tool changes the wallpaper image according to the current cheerlights colour, from a directory you specify.

It's written in pure ruby, requires nothing other than the standard library, and comes bundled with some simple coloured wallpapers in the appropriate colours.


Download from the CheerPaper git page.


To use cheerpaper, simply call it with a directory full of images:

$ cheerpaper -d ~/.wallpapers/


The directory should contain images whose name starts with a colour. CheerPaper will look through this directory for an image starting with the current colour (if there's more than one, it will randomly select one), and set it as the wallpaper. Cheerlights don't publish a formal API per se, but they do mention that the supported colours are:

red, green, blue, cyan, white, warmwhite, purple, magenta, yellow, orange

The download comes with a sample directory full of various coloured backgrounds. CheerPaper doesn't actually care what the colours are (it simply seeks filenames), and will avoid setting the wallpaper if you decide not to use a certain colour.

Help Reference

A full list of options is below:

% cheerpaper -h
Usage: cheerpaper [options]
    -d, --directory DIR              The directory in which to find wallpaper images
    -e, --extensions EXT1,EXT2,EXT3  Define file extensions to seek within the directory
    -c, --command CMD                The wallpaper-setting command.  Use %s as a placeholder for the filename (shell-escaped)
    -i, --interval INT               How often, in seconds, to poll the server
    -u, --url URL                    The URL to poll for colour
    -P, --pid [FILE]                 The PID filepath, omit argument to avoid using pid file
    -o, --once                       Run once, do not poll server
    -n, --no-daemonise               Do not daemonise process
    -l, --log FILE                   Set the log file (default is stdout)
    -p, --proxy PROXY                Set the proxy, will read from the environment otherwise
    -v, --verbose                    Verbose mode
    -k, --there-can-be-only-one      Only allow one instance (kill if a pid file is found)