# [![BLS][logo]][website]

> simple, minimal lockscreen

Betterlockscreen allows you to cache images with different filters and locking your screen with blazing speed.

---

## Example

> lockscreen with blurred effect

```sh
betterlockscreen --lock blur
```

![scrot2](https://github.com/pavanjadhaw/betterlockscreen.demo/raw/master/scrots/scrot2.png 'scrot2.png')

> [Watch some of the features of betterlockscreen in action](https://www.youtube.com/watch?v=9Ng5FZwnn6M&feature=youtu.be)

## Table of Contents

- [about](#about)
- [how it works](#how-it-works)
- [requirements](#requirements)
- [installation](#installation)
- [usage](#usage)
- [background](#set-desktop-background-on-startup)
- [keybinding](#keybindings)
- [lockscreen on suspend](#lockscreen-when-suspendedsystemd-service)

### 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?

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.

### How it works

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.

### Requirements

> Note: Make sure your system has all dependencies satisfied

- [i3lock-color](https://github.com/PandorasFox/i3lock-color) - i3lock fork with additional features( >= 2.11-c )
- [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.

### Installation

> manual installation

```sh
git clone https://github.com/pavanjadhaw/betterlockscreen
cd betterlockscreen
cp betterlockscreen ~/.local/bin/
```

<p style="text-align: center">OR</p>

```sh
# or wget the script ~12KB
wget -O betterlockscreen https://git.io/fASUJ
chmod u+x betterlockscreen
cp betterlockscreen ~/.local/bin/
```

```sh
# Add betterlockscreen to PATH:
# (In your .bashrc, .zshrc etc)
export PATH="${PATH}:${HOME}/.local/bin/"
```

### Package Manager

#### Arch Linux

###### Installing dependencies(not required if using betterlockscreen aur package)

`pacman -S imagemagick feh xorg-xrandr xorg-xdpyinfo`

- i3lock-color - `trizen -S i3lock-color`

#### Aur package

`betterlockscreen` is available in the Arch User repos as `betterlockscreen` and `betterlockscreen-git`.

- betterlockscreen - `trizen -S betterlockscreen`
- betterlockscreen-git - `trizen -S betterlockscreen-git`

#### Debian and derivatives

UtkarshVerma was so kind to provide an installation script for debian based systems, ![check it out here](https://github.com/UtkarshVerma/installer-scripts).

### 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, or dimblur"] [-t "custom text"] [-s "lockscreen and suspend"]
					 [-r "resolution"] [-b "factor"]

betterlockscreen - faster and sweet looking lockscreen for linux systems.

required:
	-u, --update "path/to/img.jpg"	caches all required images

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

			Available effects:
				dim, blur or dimblur

	-t, --text "custom text"
			set custom lockscreen text
	-b, blur 0.0 - 1.0
			set blur range
	-r, --resolution res
			uses a custom resolution


Usage examples:
1. Updating image cache(required)
betterlockscreen -u ~/Pictures/Forests.png # caches given image
betterlockscreen -u ~/Pictures             # caches random image from ~/Pictures directory

2. Custom resolution and blur range
betterlockscreen -u path/to/directory -r 1920x1080 -b 0.5

3. Lockscreen
betterlockscreen -l dim                    # lockscreen with dim effect

4. Lockscreen with custom text
betterlockscreen -l dim -t "custom lockscreen text"

5. Set desktop background
betterlockscreen -w blur                   # set desktop background with blur effect
```

### Set desktop background on startup

Add this line to `.xinitrc`.

```sh
# set desktop background with custom effect
betterlockscreen -w dim

# Alternative (set last used background)
source ~/.fehbg
```

#### i3wm

Add this line to `~/.config/i3/config`

```sh
# set desktop background with custom effect
exec --no-startup-id betterlockscreen -w dim

# Alternative (set last used background)
exec --no-startup-id source ~/.fehbg
```

### Keybindings

#### i3wm

Add this line to your `~/.config/i3/config`

```sh
bindsym $mod+shift+x exec betterlockscreen -l dim
```

#### bspwm

Add this line to your `~/.config/sxhkd/sxhkdrc`

```sh
# lockscreen
alt + shift + x
    betterlockscreen -l dim
```

### Lockscreen when suspended(systemd service)

```sh
# move service file to proper dir (the aur package does this for you)
cp betterlockscreen@.service /etc/systemd/system/

# enable systemd service
systemctl enable betterlockscreen@$USER

# disable systemd service
systemctl disable betterlockscreen@$USER


# Note: Now you can call systemctl suspend to suspend your system
# and betterlockscreen service will be activated
# so when your system wakes your screen will be locked.
```

---

### Countributing

Thanks to all the amazing people for all your wonderful PRs, issues and ideas!

[![](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/images/0)](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/links/0)[![](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/images/1)](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/links/1)[![](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/images/2)](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/links/2)[![](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/images/3)](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/links/3)[![](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/images/4)](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/links/4)[![](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/images/5)](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/links/5)[![](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/images/6)](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/links/6)[![](https://sourcerer.io/fame/pavanjadhaw/pavanjadhaw/betterlockscreen/images/7)](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:

## License

Betterlockscreen is under [MIT](https://github.com/pavanjadhaw/betterlockscreen/blob/master/LICENSE) license.

## 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

[logo]: .github/hero.png
[website]: https://mdxjs.com