Bring your lock screen to life.
Play videos and GIFs on the GNOME lock screen.
Features • Installation • Requirements • Tips • Known Issues • Troubleshooting • Support
Tip
Having trouble with the current version? You can try an older version of the extension though sticking with the latest version is highly recommended for better performance.
"Do one thing and do it well."
— Unix philosophy
Live Lock Screen focuses on a single goal: playing multimedia on the lock screen. It is designed to be simple, lightweight, and reliable.
If you're looking for more advanced lock screen or desktop customization, you may want to explore alternative extensions or check out some forks of this project.
| Feature | ||
|---|---|---|
| 🎬 | Video & GIF playback | Use any video or GIF as the lock screen background, played by MPV |
| 📁 | Playlists | Pick a folder instead of a single file. Play the videos in order, shuffled, or randomly, and start with the first, a random, or the last played video |
| 🌑 | Smooth transitions | Fades through black when switching videos, so you never see the next one loading. Disable this if you prefer abrupt switching. |
| 🎨 | Scaling modes | Cover, fit, or stretch |
| 🔲 | Transparency | Transparent GIFs and videos are shown over the default background |
| 🖥️ | Multi-monitor | Works across all your displays |
| 🌌 | Fade-in & blur | Configurable fade-in animation, blur radius, and brightness |
| 🔑 | Password prompt reactions | Pause, grayscale, or change the blur when the password prompt appears |
| ⏸️ | Smart pause | Reacts to the video ending, the screen turning off, suspend, and running on battery |
| ⏯️ | Media controls | Play, pause, and skip videos with media keys or any MPRIS client |
| 🔊 | Audio | Optional audio with volume control and smooth fade in/out |
| ⚡ | Playback profiles | Quality, Balanced, or Efficient, depending on your hardware |
| 🛠️ | Custom MPV arguments | Pass your own MPV options for full control |
Tip
Feeling adventurous? The experimental branch has the latest (possibly unstable) features.
1. Clone the repository
git clone https://github.com/nick-redwill/LiveLockScreen.git2. Copy it to your extensions folder
cp -r LiveLockScreen ~/.local/share/gnome-shell/extensions/live-lockscreen@nick-redwill3. Log out and back in, then enable the extension
gnome-extensions enable live-lockscreen@nick-redwill4. Open the extension preferences and pick a file or a folder 🎉
- GNOME Shell 46+
- MPV
| Distro | Command |
|---|---|
| Fedora | sudo dnf install mpv |
| Ubuntu / Debian | sudo apt install mpv |
| Arch | sudo pacman -S mpv |
Note
The GStreamer backend from older versions has been removed, MPV is now the only player.
Important
Some formats need extra codecs. Some distributions ship MPV without patented codecs such as H.264 and H.265/HEVC, which most MP4 and MKV videos use. Without them, those videos stay black or do not play at all.
Look for your distribution's guide on enabling multimedia codecs.
Keep the screen from turning off
GNOME turns the screen off on the lock screen. To prevent that use the Unblank lock screen extension. You can also choose what happens to the video when the screen turns off (ignore, pause, restart, or switch to the next video) under Events → Action on blank.
Playback profiles
Found under Performance:
| Profile | |
|---|---|
| Quality | Best image quality, higher GPU usage |
| Balanced | Same as Quality with cheaper scaling, a good choice for most laptops |
| Efficient | Lowest GPU usage. Experimental, may not work on every system and does not support transparency |
If the video does not show up or looks wrong with Efficient, switch to Balanced.
Media controls
Enable Media controls in the preferences to control the video with media keys or any MPRIS client (e.g. GSConnect).
If the default lock screen shows up instead of your video, check the logs while locking the screen:
journalctl -f -o cat /usr/bin/gnome-shell | grep LiveLockScreenCommon causes:
- MPV is not installed or not in your
PATH - The selected folder has no supported files. The preferences show the number of playable files and mark the source red if there are none
- Missing codecs, the video stays black or only some files play. Check if the file plays with
mpv /path/to/video, and see the codecs note under Requirements - The Efficient profile does not work on your system, try Balanced instead
- Broken custom MPV arguments, try clearing them
When reporting a bug, please include your GNOME Shell version, MPV version (mpv --version), and the log output.
If you enjoy this extension, consider supporting its development on GitHub Sponsors.
This project is developed with the assistance of AI tools. All changes are planned or approved by the author, and all AI-generated code is reviewed and tested before it is merged.
Released under the AGPL-3.0 license.
