Omahub
← All plugins
T

Live Wallpaper

by tenzin

Add seamless video wallpapers by dropping a video into the current theme's background folder, then selecting it in Style > Background.

GitHub

Security review

Review recommended · 2 findings

Deterministic scan — not a security guarantee

Low
Risk level
Low
Analyzed commit
7f7d893
Scanned
1 month ago

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
7f7d893
Reviewed
1 month ago

The plugin is a legitimate video wallpaper service with thorough input validation, path allowlisting, secure directory creation, and process timeouts. The deterministic scan's 'obfuscation' findings are false positives: the flagged snippets are sed substitution patterns and a backup file, not obfuscated code. No credential theft, persistence, or destructive behavior was found.

  • The .orig file is a backup of the script and is not executed; it is safe to ignore.
  • The sed pattern flagged by the scanner is a normal substitution for menu configuration, not obfuscation.
  • The plugin modifies the user's menu config file (omarchy-menu.jsonc) as documented, which is expected behavior.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/yesheytenzin/live-wallpaper --enable
Appearance #Hyprland #media

Omarchy Live Wallpaper

Play fast, muted, looping video wallpapers through Omarchy's familiar Style → Background picker. The plugin keeps the stock background service and adds video support without starting another Quickshell process.

Quick start

  1. Copy an MP4, MKV, WebM, MOV, or M4V file into your current theme's folder:

    ~/.config/omarchy/backgrounds/<theme-name>/

  2. Open Style → Background.

  3. Select the video's generated preview.

Playback starts automatically with no shell restart. To stop the video, open the picker again and select a normal image. You can also double-click an empty part of the desktop to open the picker.

Features

  • Lists images and videos together from the active theme's wallpaper folders
  • Supports MP4, MKV, WebM, MOV, and M4V
  • Starts cached videos in about 100 ms using persistent Qt multimedia surfaces
  • Keeps one warm, muted, looping player per connected monitor
  • Reveals video only after the first valid frame, preventing black flashes
  • Generates picker previews with Omarchy's existing ffmpeg installation
  • Keeps a static poster as the lock-screen and transition fallback
  • Stops playback when a static wallpaper or another theme is selected
  • Resumes the selected video after the Omarchy shell restarts
  • Preserves desktop double-click behavior through the video/input surface

Demo videos

Select and apply a video wallpaper

Select and apply a video wallpaper

Watch the full 1080p video

Add wallpaper files and select a video

Add wallpaper files and select a video

Watch the full 1080p video

Both demonstrations show the plugin running on Omarchy.

Install

omarchy plugin add https://github.com/yesheytenzin/live-wallpaper.git --enable

No additional packages or privileged installation steps are required. Playback uses Qt Multimedia from Omarchy's existing Qt runtime, and previews use the existing ffmpeg command. The plugin does not start another Quickshell process.

Use

Place videos beside image wallpapers in either location:

  • ~/.config/omarchy/backgrounds/<theme-slug>/
  • <theme>/backgrounds/

Open Style → Background or double-click an empty part of the desktop. Video entries use a generated frame in the picker and start moving after selection.

Menu integration

Enabling the plugin updates the style.background action in ~/.config/omarchy/extensions/omarchy-menu.jsonc. The stock Background name, icon, and aliases are preserved; only its picker action changes.

Disabling or removing the plugin through Omarchy unloads the service and removes the menu override. It can also be removed manually without disabling playback:

~/.config/omarchy/plugins/tenzin.live-wallpaper/live-wallpaper.sh --unwire-menu

Update

omarchy plugin update tenzin.live-wallpaper

Remove

Standard removal performs complete cleanup before deleting the plugin. It stops playback, restores the last static wallpaper, deletes generated state/cache, and removes the Style → Background integration:

omarchy plugin remove tenzin.live-wallpaper

Development

PLUGIN_DIR="$HOME/.config/omarchy/plugins/tenzin.live-wallpaper"
omarchy plugin validate "$PLUGIN_DIR"
/usr/lib/qt6/bin/qmllint -I "${OMARCHY_PATH:-/usr/share/omarchy}/shell" "$PLUGIN_DIR/Service.qml"
bash -n "$PLUGIN_DIR/live-wallpaper.sh"

The repository root is the plugin folder:

  • manifest.json declares the standalone service entry point
  • Service.qml owns persistent players, IPC, desktop input, and resume
  • live-wallpaper.sh owns media discovery, ffmpeg previews, state, and cleanup

Runtime state is stored under ~/.local/state/omarchy/live-wallpaper/; generated previews are stored under ~/.cache/omarchy/live-wallpaper/.

License

Licensed under the MIT License. See LICENSE.