wlsunset

Automatically compute sunset/sunrise times based on the specified location

$ wlsunset -l [latitude] -L [longitude]

$ wlsunset -s [sunset_time] -S [sunrise_time]

$ wlsunset -T [high_temp] -t [low_temp]

$ wlsunset -d [n] -s [sunset_time] -S [sunrise_time]

$ wlsunset -g [gamma_value]

wlsunset [-l latitude longitude | -s HH:MM HH:MM] [-t day_temp night_temp] [-S seconds] [-T seconds] [-g gamma_value] [-d seconds] [-v] [--help] [--version]

-l, --location latitude longitude
    Specifies the geographical coordinates (decimal latitude and longitude) to use for calculating sunrise and sunset times. Example: -l 34.05 -118.25.

-s, --time-range HH:MM HH:MM
    Defines a fixed time range for the day-to-night transition, overriding location-based calculations. The first time is when night transition begins, the second when day transition begins. Example: -s 20:00 07:00.

-t, --temp day_temp night_temp
    Sets the color temperature in Kelvin for daytime and nighttime. Common values are 6500K for day and 4500K or lower for night. Default is typically 6500K and 4500K.

-S, --sunrise-offset seconds
    Adjusts the effective sunrise/sunset time by a given number of seconds. Positive values delay, negative values hasten the calculated times.

-T, --transition seconds
    Sets the duration in seconds for the smooth transition between day and night color temperatures. A longer duration results in a more gradual change.

-g, --gamma gamma_value
    Applies a gamma correction to the screen output. This is an advanced setting for fine-tuning display characteristics.

-d, --duration seconds
    Runs wlsunset for a specified duration in seconds and then exits. Useful for testing configurations without continuous operation.

-v, --verbose
    Enables verbose output, providing more detailed information about the command's operation and current state.

--help
    Displays a help message with command usage and options, then exits.

--version
    Displays the version information of wlsunset and exits.

wlsunset is a utility designed for the Wayland display server that dynamically adjusts your screen's color temperature throughout the day. Its primary purpose is to reduce eye strain, especially during evening and night hours, by shifting the display's color output from cooler (bluish) tones to warmer (reddish) tones. This change is often referred to as mimicking natural light cycles, promoting better sleep patterns by reducing exposure to blue light.

Similar to how `redshift` or `f.lux` operate on X11, wlsunset calculates sunrise and sunset times based on your geographical location (or a specified time range) and smoothly transitions the screen's color temperature between a 'day' and 'night' setting. It leverages the wlr-output-management protocol, making it compatible with Wayland compositors that support this standard, such as Sway, Hyprland, and others. The transition is gradual, making the shift nearly imperceptible, ensuring a comfortable viewing experience at all times of the day and night.

wlsunset is specifically designed for the Wayland display server and will not function on X11-based systems. It relies on your Wayland compositor supporting the wlr-output-management protocol for screen color temperature adjustments. Compatibility may vary with less common compositors. For location-based adjustments, it either requires explicit latitude/longitude input or access to a location service (like GeoClue) if not specified.

wlsunset communicates with Wayland compositors (e.g., Sway, Hyprland, river) that implement the wlr-output-management protocol. This protocol allows it to request and apply color temperature changes across all active outputs managed by the compositor. Ensure your compositor supports this protocol for wlsunset to function correctly.

To have wlsunset run automatically when your Wayland session starts, you typically add it to your compositor's configuration file (e.g., `exec wlsunset` in Sway's config) or configure it as a user service via systemd --user. This ensures continuous eye comfort adjustments without manual intervention.

If the -l (location) option is not provided, wlsunset may attempt to determine your geographical location automatically using services like GeoClue. If GeoClue is not available or configured, you must manually provide the latitude and longitude using the -l flag or specify a fixed time range with -s.

Born out of the growing adoption of Wayland as a modern display server, wlsunset was developed to fill a critical gap left by X11-specific screen temperature adjustment tools like Redshift. As Wayland's security and architecture differ significantly from X11, a native solution was required that could interact directly with Wayland compositors via protocols such as wlr-output-management. Its development aimed to provide Wayland users with the same eye comfort benefits previously enjoyed only by X11 users.

redshift(1), wayland(7), sway(1), hyprland(1)