##features

Uses GNOME's own org.gnome.desktop.background picture-uri setting as the wallpaper source.
Renders through a native GNOME Shell background overlay — normal windows sit on top of it like any wallpaper.
livedesk is a GTK4/Libadwaita app for picking videos, monitors, service mode, autostart, tray, and playback state.
Frames move through a memory-mapped file guarded by a seqlock header — D-Bus only carries coarse commands.
D-Bus controls for play, pause, mute, source switching, and frame-path lookup.
Creates a first-frame PNG fallback for GNOME surfaces that still need a normal still image.
Scripted Debian/RPM packages for x64 and arm64, plus Launchpad PPA source packaging.

##architecture

video file
  -> livedesk-daemon
  -> /run/user/<uid>/livedesk/<monitor>.frame
  -> GNOME Shell native background module
  -> Clutter actor in GNOME's background manager path
  -> Mutter compositor

No pixel data crosses D-Bus. The daemon writes RGBA frames to a memory-mapped file; the native Shell module polls it using a small seqlock header to avoid torn reads. D-Bus carries only coarse control: play, pause, mute, source changes, and frame-path lookup.

support status — the current native setup targets GNOME Shell 40-44 and has been tested on GNOME Shell 43.x. GNOME Shell 45+ changed its JavaScript module layout and needs a separate native overlay before it is treated as supported.

##install

Install the package, run livedesk-setup once, then log out and back in. After that, open livedesk and choose a video.

read before logging out — native setup changes how GNOME Shell loads JavaScript on the next login. Keep the Emergency Recovery commands available in case GNOME shows an unrecoverable error screen.

Ubuntu PPA

Good for Ubuntu and Ubuntu-based distributions.

# via PPA
sudo add-apt-repository ppa:tamkungz/stable
sudo apt update
sudo apt install livedesk
livedesk-setup
livedesk

APT Repository

Use this for Debian, Ubuntu, or other APT-based systems where you want the package repo directly.

# add the APT repo manually
curl -fsSL https://packages.tamkungz.me/gpg.key \
  | sudo gpg --dearmor -o /usr/share/keyrings/tamkungz-archive-keyring.gpg
echo "deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/tamkungz-archive-keyring.gpg] https://packages.tamkungz.me/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/tamkungz.list
sudo apt update
sudo apt install livedesk
livedesk-setup
livedesk

sudo rpm --import https://packages.tamkungz.me/gpg.key
sudo tee /etc/yum.repos.d/tamkungz.repo >/dev/null <<'EOF'
[tamkungz]
name=TamKungZ Packages
baseurl=https://packages.tamkungz.me/rpm/$basearch
enabled=1
gpgcheck=0
repo_gpgcheck=1
gpgkey=https://packages.tamkungz.me/gpg.key
EOF
sudo dnf install livedesk
livedesk-setup
livedesk

RPM repository metadata is signed. RPM packages also include detached .asc signatures in the package directory.

./install.sh
livedesk-setup
livedesk

Log out and back in once after livedesk-setup. The native setup installs a user-session GNOME Shell JavaScript overlay under ~/.local/share/livedesk/gnome-shell-js and writes ~/.config/environment.d/90-livedesk-gnome-shell.conf.

##requirements

To build from source. The *-dev packages compile the Rust daemon; the gstreamer1.0-* plugins provide runtime decoders.

sudo apt install cargo rustc pkg-config gjs gir1.2-gtk-4.0 gir1.2-adw-1 \
  gir1.2-gtk-3.0 gir1.2-ayatanaappindicator3-0.1 \
  libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libdbus-1-dev \
  libunwind-dev libglib2.0-bin \
  gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-libav \
  totem

totem supplies totem-video-thumbnailer, used for gallery thumbnails when present.
Plugin packages cover H.264, VP8, VP9, and AV1 decoding at runtime.
Missing gstreamer-1.0.pc or similar .pc files usually mean the runtime is installed but headers aren't.

fix for missing headers — sudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libunwind-dev

##emergency recovery

If GNOME shows Oh no! Something has gone wrong. after native setup, remove the native overlay from a TTY and restart the display manager.

# 1. Open a TTY:
Ctrl+Alt+F3

# 2. Log in with your normal username and password, then run:
rm -f ~/.config/environment.d/90-livedesk-gnome-shell.conf
rm -rf ~/.local/share/livedesk/gnome-shell-js
sudo systemctl restart gdm

# If your distro does not use GDM:
sudo reboot

Return to the graphical session with Ctrl+Alt+F1. On some systems it is Ctrl+Alt+F2 instead.

##usage

Open anytime with livedesk. Double-click a video thumbnail, or select a video and click Save and Apply.

Library gallery — browse the video library as thumbnails and apply a pick immediately.
Import & organize — open the library folder directly, or import files into it.
Per-monitor targeting — detects connected monitors and matches their resolution automatically.
Playback controls — mute, unmute, service mode, autostart, play / pause / stop / apply over D-Bus.
Tray helper — starts automatically when the session provides Ayatana/AppIndicator support.
Detailed logs — launch from a terminal to see every button/action, command, daemon call, and still-frame generation step.

video library	`~/Videos/Livedesk`
thumbnail cache	`~/.cache/livedesk/thumbnails`
still fallback cache	`~/.cache/livedesk/stills`
action log	`~/.cache/livedesk/livedesk.log`
config file	`~/.config/livedesk/config.json`

##development

livedesk/
├── app/                     GTK4/Libadwaita settings app
├── daemon/                  Rust + GStreamer decode daemon
├── native/gnome-shell/      GNOME Shell native background overlay
├── native/mutter/           roadmap for a future Mutter-native renderer
├── scripts/                 setup, uninstall, package, and Launchpad helpers
└── install.sh

manual daemon build

cd daemon
cargo +1.77 build --release --locked

D-Bus name: me.tamkungz.Livedesk
GTK app ID: me.tamkungz.LivedeskApp
Native overlay: ~/.local/share/livedesk/gnome-shell-js
Rust: 1.77, edition 2021
Config dir: ~/.config/livedesk
Runtime frame dir: $XDG_RUNTIME_DIR/livedesk