diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 248 |
1 files changed, 130 insertions, 118 deletions
@@ -6,6 +6,8 @@ <a href="https://github.com/pavanjadhaw/betterlockscreen/releases"><img alt="GitHub release (latest by date)" src="https://img.shields.io/github/v/release/pavanjadhaw/betterlockscreen?label=Stable&style=for-the-badge"></a> <a href="https://github.com/pavanjadhaw/betterlockscreen/actions/workflows/main.yml?query=branch%3Amaster"><img alt="GitHub Workflow Status (master)" src="https://img.shields.io/github/workflow/status/pavanjadhaw/betterlockscreen/Main/master?label=master&style=for-the-badge"></a> <a href="https://github.com/pavanjadhaw/betterlockscreen/actions/workflows/main.yml?query=branch%3Anext"><img alt="GitHub Workflow Status (next)" src="https://img.shields.io/github/workflow/status/pavanjadhaw/betterlockscreen/Main/next?label=next&style=for-the-badge"></a> + <a href="https://github.com/pavanjadhaw/betterlockscreen/milestone/²"><img alt="GitHub milestone" src="https://img.shields.io/github/milestones/progress/pavanjadhaw/betterlockscreen/2?style=for-the-badge"></a> + <a href="https://github.com/pavanjadhaw/betterlockscreen/compare/v4.0.0...next"><img alt="GitHub commits since latest release (by date) for a branch" src="https://img.shields.io/github/commits-since/pavanjadhaw/betterlockscreen/v4.0.0/next?style=for-the-badge"></a> <a href="https://github.com/pavanjadhaw/betterlockscreen/blob/master/LICENSE"><img src="https://img.shields.io/github/license/pavanjadhaw/betterlockscreen.svg?style=for-the-badge"></a> </div> @@ -23,97 +25,100 @@ ## Table of Contents -- [about](#about) -- [how it works](#how-it-works) -- [requirements](#requirements) -- [installation](#installation) -- [configuration](#configuration) -- [usage](#usage) -- [background](#set-desktop-background-on-startup) -- [keybinding](#keybindings) -- [lockscreen on suspend](#lockscreen-when-suspendedsystemd-service) +- [About](#about) +- [How it works](#how-it-works) +- [System Requirements](#system-requirements) +- [Installation](#installation) +- [Configuration](#configuration) +- [Usage](#usage) +- [Background](#background) +- [Keybinding](#keybindings) +- [Lockscreen on sleep/suspend with systemd](#systemd) -### About +## About -Most of i3lock wrapper scripts out there takes an image, adds some effect and locks the screen -adding effects, overall experience doesn't feel natural given delay of 2-3 seconds. -Who would like a delay of 2-3 seconds while locking screen? +Most of i3lock wrapper-scripts out there take an image, add some effect(s) then lock with the modified image as locker-background. Overall experience doesn't feel natural given delay of 2-3 seconds. -So betterlockscreen was my attempt to solve this problem, as we dont need to change lockscreen background frequently -this script caches images with effect so overall experience is simple and as fast as native i3lock. +> Who would like a delay of 2-3 seconds while locking screen? -### How it works +So Betterlockscreen was my attempt to solve this problem, as we dont need to change lockscreen background frequently this script caches images with effect so overall experience is simple and as fast as native i3lock. -The script takes image adds various effects and caches those images in special directory and then uses those -images as lockscreen background depending on argument provided by user. +## How it works -### Requirements +The script takes a directory or image, adds various effects and caches the images in special directory. Those cached images will be used as locker-background depending on configuration provided by user. -> Note: Make sure your system has all dependencies satisfied - -- [i3lock-color](https://github.com/Raymo111/i3lock-color) - i3lock fork with additional features(`>= 2.13.c.3`) -- [imagemagick](https://www.imagemagick.org/script/index.php) - To apply effects to images -- [xdpyinfo](https://www.x.org/archive/X11R7.7/doc/man/man1/xdpyinfo.1.xhtml), [xrandr](https://www.x.org/wiki/Projects/XRandR/), [bc](https://www.gnu.org/software/bc/) and [feh](https://feh.finalrewind.org/) - To find screen resolution, set custom blur level and wallpaper handling. +## System Requirements -### Installation +* [i3lock-color](https://github.com/Raymo111/i3lock-color) `>= 2.13.c.3` +* [ImageMagick](https://imagemagick.org/) +* xdpyinfo, xrandr, xrdb and xset from [X.Org](https://www.x.org/) +* (Optional) [Dunst](https://dunst-project.org/) +* (Optional) [feh](https://feh.finalrewind.org/) for wallpaper-functionality -> manual installation +> Note: Make sure your system has all dependencies satisfied -```sh -git clone https://github.com/pavanjadhaw/betterlockscreen -cd betterlockscreen -cp betterlockscreen ~/.local/bin/ -``` +## Installation +### Package Manager -<p style="text-align: center">OR</p> +<a href="https://repology.org/project/betterlockscreen"> + <img src="https://repology.org/badge/vertical-allrepos/betterlockscreen.svg" alt="Packaging status" align="right"> +</a> -```sh -# or wget the script ~12KB -wget -O betterlockscreen https://git.io/fASUJ -chmod u+x betterlockscreen -cp betterlockscreen ~/.local/bin/ -``` +Betterlockscreen is available via package manager on some linux-distributions, if you miss your favorite one you can follow along with our [installation-script](#installation-script) or [manual-installation](#manual-installation). -```sh -# Add betterlockscreen to PATH: -# (In your .bashrc, .zshrc etc) -export PATH="${PATH}:${HOME}/.local/bin/" -``` +If you are using **Arch Linux**, you can install the AUR package +[betterlockscreen](https://aur.archlinux.org/packages/betterlockscreen/) to get the latest +version, or [betterlockscreen-git](https://aur.archlinux.org/packages/betterlockscreen-git/) for the most up-to-date (unstable) changes. -### Package Manager +If you are using **Gentoo Linux**, you can install `betterlockscreen` from Gentoo's [GURU overlay](https://wiki.gentoo.org/wiki/Project:GURU) using `emerge x11-misc/betterlockscreen`. -#### Arch Linux +If you are using **NixOS**, [betterlockscreen](https://search.nixos.org/packages?query=betterlockscreen) is available in both the [stable](https://github.com/NixOS/nixpkgs/blob/nixos-21.05/pkgs/misc/screensavers/betterlockscreen/default.nix) and [unstable](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/misc/screensavers/betterlockscreen/default.nix) channels and can be installed using `nix-env -iA nixos.betterlockscreen`. -###### Installing dependencies(not required if using betterlockscreen aur package) +If you are using **Void Linux**, you can install [betterlockscreen](https://github.com/void-linux/void-packages/blob/master/srcpkgs/betterlockscreen/template) using `xbps-install -S betterlockscreen`. -`pacman -S imagemagick feh xorg-xrandr xorg-xdpyinfo` +### Installation Script -- i3lock-color - `trizen -S i3lock-color` +We have created an automatic [install-script](https://github.com/pavanjadhaw/betterlockscreen/blob/master/install.sh) for Betterlockscreen. The script is very simple and takes three parameters: + * `<install-mode>`: (string) 'user' installs to '~/.local/bin/', 'system' installs to '/usr/local/bin' + * `[<version>]`: (string) defaults to 'latest' which will determinate the latest tag from git or specified branch/tag + * `[<systemd-service>]`: (boolean) defaults to 'false' - Whether to copy and enable system-service. -#### Aur package +For system-installation: +```sh +wget https://git.io/JZyxV -O - -q | bash -- system +``` -`betterlockscreen` is available in the Arch User repos as `betterlockscreen` and `betterlockscreen-git`. +For user-installation: +```sh +wget https://git.io/JZyxV -O - -q | bash -- user +``` -- betterlockscreen - `trizen -S betterlockscreen` -- betterlockscreen-git - `trizen -S betterlockscreen-git` +Please note: The [git.io](https://git.io/)-URL is just a short-url for the [master/install.sh](https://raw.githubusercontent.com/pavanjadhaw/betterlockscreen/master/install.sh). -#### Debian and derivatives +### Manual Installation -UtkarshVerma was so kind to provide an installation script for debian based systems, . +Ỳou can download the latest release [here](https://github.com/pavanjadhaw/betterlockscreen/releases), please ensure to fullfill the [system-requirements](#system-requirements)! -#### Void Linux +You will need to copy "betterlockscreen" to you desired binary-directory, if you want to use the systemd-service you will need to copy the service-file from "system/" to the desired location on your system. -##### xbps repository +Example (Ubuntu): +```sh +wget https://github.com/pavanjadhaw/betterlockscreen/archive/refs/heads/master.zip +unzip master.zip -`betterlockscreen` is available in official Void's repository as `betterlockscreen`. +cd betterlockscreen-master/ +chmod u+x betterlockscreen +cp betterlockscreen /usr/local/bin/ -Installing using `xbps` (will automatically install all required dependencies): `xbps-install -S betterlockscreen` +cp system/betterlockscreen@.service /usr/lib/systemd/system/ +systemctl enable betterlockscreen@$USER +``` -### Configuration +## Configuration -You can customise various colors for betterlockscreen, copy config file from examples directory to `~/.config/betterlockscreenrc` and edit it accordingly. +You can customize betterlockscreen for your needs, copy the config file from the examples-directory to `~/.config/betterlockscreenrc` and edit it accordingly. -If configuration file is not found then default configurations will be used. +If no configuration-file is found, then the default configurations (which is equal to the example but currently hardcoded) will be used. If you have installed betterlockscreen from AUR package, then you can copy default config from docs @@ -121,63 +126,79 @@ If you have installed betterlockscreen from AUR package, then you can copy defau cp /usr/share/doc/betterlockscreen/examples/betterlockscreenrc ~/.config ``` -### Usage +## Usage Run `betterlockscreen` and point it to either a directory (`betterlockscreen -u "path/to/dir"`) or an image (`betterlockscreen -u "/path/to/img.jpg"`) and that's all. `betterlockscreen` will change update its cache with image you provided. ```sh -usage: betterlockscreen [-u "path/to/img.jpg"] [-l "dim, blur or dimblur"] - [-w "dim, blur, pixel or dimblur"] [-t "custom text"] [-s "lockscreen and suspend"] - [-r "resolution"] [-b "factor"] [--off <timeout>] +Usage: betterlockscreen [-u <PATH>] [-l <EFFECT>] [-w <EFFECT>] + + -u --update <PATH> + Update lock screen image -betterlockscreen - faster and sweet looking lockscreen for linux systems. + -l --lock <EFFECT> + Lock screen with cached image -required: - -u, --update "path/to/img.jpg" caches all required images + -w --wall <EFFECT> + Set wallpaper with cached image -usage: - -l, --lock effect-name - locks with provided effect - -w, --wall effect-name - set desktop background with provided effect - -s, --suspend effect-name - lockscreen and suspend +Additional arguments: - Available effects: - dim, blur, pixel or dimblur + --display <N> + Set display to draw loginbox - -t, --text "custom text" - set custom lockscreen text - -b, blur 0.0 - 1.0 - set blur range - -r, --resolution res - uses a custom resolution - --off, --off <timeout> - sets custom monitor timeout (<timeout> in seconds) + --span + Scale image to span multiple displays + --off <N> + Turn display off after N minutes -Usage examples: -1. Updating image cache(required) -betterlockscreen -u ~/Pictures/Forests.png # caches given image -betterlockscreen -u ~/Pictures # caches random image from ~/Pictures directory + --fx <EFFECT,EFFECT,EFFECT> + List of effects to apply -2. Custom resolution and blur range -betterlockscreen -u path/to/directory -r 1920x1080 -b 0.5 + -- <ARGS> + Pass following arguments to i3lock -3. Lockscreen -betterlockscreen -l dim # lockscreen with dim effect +Effects arguments: -4. Lockscreen with custom text -betterlockscreen -l pixel -t "custom lockscreen text" + --dim <N> + Dim image N percent (0-100) -5. Set desktop background -betterlockscreen -w blur # set desktop background with blur effect + --blur <N> + Blur image N amount (0.0-1.0) -6. Lockscreeen with custom monitor off timeout -betterlockscreen --off 5 -l blur # set monitor off lockscreen timeout (5 seconds) + --pixel <N,N> + Pixelate image with N shrink and N grow (unsupported) + + --color <HEX> + Solid color background with HEX ``` -### Set desktop background on startup + +#### Examples +1. Update image cache with random image +`betterlockscreen -u ~/Wallpapers` + +2. Update image cache with only dim and pixel effects +`betterlockscreen -u ~/Wallpapers/image.png --fx dim,pixel` + +3. Update image cache with random image, multiple monitors, login on 1, spanning +`betterlockscreen -u ~/Wallpapers/Dual/ --display 1 --span` + +4. Update image cache with solid background only (ignore errors) +`betterlockscreen -u . --fx color --color 5833ff` + +5. Update image cache with different background images +`betterlockscreen -u ~/Wallpapers/image1.png -u ~/Wallpapers/image2.png` + +6. Lock screen with blur effect +`betterlockscreen --lock blur` + +7. Lock screen with multiple monitors, spanning +`betterlockscreen -l dimblur --display 1 --span` + + +## Background Add this line to `.xinitrc`. @@ -189,7 +210,7 @@ betterlockscreen -w dim source ~/.fehbg ``` -#### i3wm +### i3wm Add this line to `~/.config/i3/config` @@ -201,11 +222,11 @@ exec --no-startup-id betterlockscreen -w dim exec --no-startup-id source ~/.fehbg ``` -### Keybindings +## Keybindings To lockscreen using keyboard shortcut -#### i3wm +### i3wm Add this line to your `~/.config/i3/config` @@ -213,7 +234,7 @@ Add this line to your `~/.config/i3/config` bindsym $mod+shift+x exec betterlockscreen -l dim ``` -#### bspwm +### bspwm Add this line to your `~/.config/sxhkd/sxhkdrc` @@ -223,7 +244,8 @@ alt + shift + x betterlockscreen -l dim ``` -### Lockscreen when suspended(systemd service) +<h2 id="systemd">Systemd-Service: Lockscreen after sleep/suspend</h2> + ```sh # move service file to proper dir (the aur package does this for you) cp betterlockscreen@.service /usr/lib/systemd/system/ @@ -247,26 +269,16 @@ Resources and more informations: --- -### Countributing +## Countributing -Thanks to all the amazing people for all your wonderful PRs, issues and ideas! - -[](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/links/0)[](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/links/1)[](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/links/2)[](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/links/3)[](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/links/4)[](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/links/5)[](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/links/6)[](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/links/7) - -## How can I support developers? - -- Star our GitHub repo :star: -- Create pull requests, submit bugs, suggest new features or documentation updates :wrench: +Please see [CONTRIBUTING.md](CONTRIBUTING.md). ## License Betterlockscreen is under [MIT](https://github.com/pavanjadhaw/betterlockscreen/blob/master/LICENSE) license. -## Feel free to use and distribute +### Feel free to use and distribute - Hat tip to anyone who's code was used - Thanks to those who contributed to make it better - Inspiration - [r/unixporn](https://www.reddit.com/r/unixporn) - -[logo]: .github/hero.png -[website]: https://mdxjs.com |