GitHub - tuxx/fancylock: Screenlock utility to play videos or show images for linux.

⚠️ ARCHIVED

This repository is no longer maintained.

No further updates or support will be provided.

FancyLock is a visually appealing screen locker for Linux that plays videos or images in the background while locked. It's designed to be both secure and aesthetically pleasing.

Features

• Play videos or images as lock screen backgrounds
• Support for multiple monitors
• PAM authentication for secure login
• Customizable settings
• Embedded version metadata (-v)

Installation

Option 1: Install from latest release (Recommended)

# Download the latest release
curl -L -o fancylock.tar.gz https://github.com/tuxx/fancylock/releases/latest/download/fancylock-linux-amd64.tar.gz

# Extract it
tar -xzvf fancylock.tar.gz

# Make it executable
chmod +x fancylock-linux-amd64

# Add a pam.d file for fancylock:
sudo curl -L -o /etc/pam.d/fancylock https://raw.githubusercontent.com/tuxx/fancylock/refs/heads/master/pam.d/fancylock

# Optional: install system-wide
sudo mv fancylock-linux-amd64 /usr/local/bin/fancylock

# Create config directory
mkdir -p ~/.config/fancylock

# Create default config file
cat > ~/.config/fancylock/config.json << 'EOF'
{
  "media_dir": "$HOME/Videos",
  "supported_extensions": [".mp4", ".mkv", ".mov", ".avi", ".webm"],
  "pam_service": "fancylock",
  "include_images": true,
  "image_display_time": 30,
  "pre_lock_command": "",
  "post_lock_command": "",
  "lock_pause_media": false,
  "unlock_unpause_media": false
}
EOF

Option 2: Install via AUR (Arch Linux)

This installs the latest precompiled release from GitHub.

Option 3: Build from source

Prerequisites

• Go 1.21 or higher
• X11 development libraries
• mpv (for video/image playback)
• PAM development libraries
• make and git

Installing dependencies

sudo apt install -y golang make libx11-dev libpam0g-dev mpv git

sudo pacman -S go make libx11 pam mpv git

Building the application

# Clone the repository
git clone https://github.com/tuxx/fancylock.git
cd fancylock

# Build for all supported architectures (amd64, arm64, arm)
make

# Optionally package them into .tar.gz files in ./dist
make package

# Build a native binary for your current system (puts it in ./bin/)
make native

# View embedded version info
./bin/fancylock-native --version

# Optional: install the native build system-wide
sudo make install

Makefile Targets

How to Use

Basic Usage

Run FancyLock without arguments to display help:

Lock your screen immediately:

fancylock -l
# or
fancylock --lock

Check version info:

fancylock -v
# or
fancylock --version

Command-line Options

Configuration

FancyLock looks for a configuration file at ~/.config/fancylock/config.json. If it doesn't exist, a default one will be created.

You can specify a different configuration file using:

fancylock -c /path/to/config.json
# or
fancylock --config /path/to/config.json

Sample Configuration

{
  "media_dir": "/home/user/Videos",
  "supported_extensions": [".mp4", ".mkv", ".mov", ".avi", ".webm"],
  "pam_service": "fancylock",
  "include_images": true,
  "image_display_time": 30,
  "pre_lock_command": "pypr hide mywindow",
  "post_lock_command": "pypr show mywindow",
  "lock_pause_media": false,
  "unlock_unpause_media": false
}

Configuration Options

• media_dir: Directory containing videos/images to display while locked
• supported_extensions: File extensions to look for in the media directory
• pam_service: PAM service name for authentication
• include_images: Whether to include images along with videos
• image_display_time: How long to display each image in seconds
• pre_lock_command: Execute this command before locking the screen
• post_lock_command: Execute this command after unlocking the screen
• lock_pause_media: Whether to pause all media players when locking the screen
• unlock_unpause_media: Whether to unpause all media players when unlocking the screen

Current Status

What's Working

• ✅ X11 screen locking with PAM authentication
• ✅ Basic hyprland support
• ✅ Multi-monitor support with correct video positioning
• ✅ Video and image playback during lock screen
• ✅ Password entry with visual feedback (dots)
• ✅ Keyboard and pointer grabbing to prevent bypass
• ✅ Failed password attempt limiting
• ✅ Embedded version metadata via -v
• ✅ MPRIS media control (pause/unpause)

What Needs Improvement

• ⚠️ Error handling in some edge cases
• ⚠️ Memory optimization for long-running sessions
• ⚠️ Better handling of system sleep/wake events
• ⚠️ Auto-creation of default config file (if none exists)

Future Implementations

• 🚧 Clock display in center of the screen
• 🚧 Configurable UI theme and appearance
• 🚧 More interactive lock screen elements
• 🚧 Systemd integration
• 🚧 Auto-generation of default config file

Developer Setup

If you want to contribute to FancyLock development:

# Clone the repository
git clone https://github.com/tuxx/fancylock.git
cd fancylock

# Set up the Git hooks (required for all developers)
./.githooks/setup-hooks.sh

# Build the application
go build -o fancylock

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues to improve the application.

Before contributing:

1. Run .githooks/setup-hooks.sh if applicable
2. Follow the coding style used in the codebase
3. Fork the repo
4. Push your changes and submit a Pull Request
5. Bother Tuxx if it sits too long 🙂

Acknowledgements

• xgb - X Go Binding
• PAM - Go wrapper for PAM
• mpv - Video player