xwinwrap

Run a video using mpv

$ xwinwrap -b -nf -ov -- [mpv] --wid [wid] --loop --no-audio --no-resume-playback --panscan=[1.0] [path/to/video.mp4]

$ xwinwrap -b -nf -fs -ov -- [mpv] --wid [wid] --loop --no-audio --no-resume-playback --panscan=[1.0] [path/to/video.mp4]

$ xwinwrap -b -nf -ov -o 0.8 --- [mpv] --wid [wid] --loop --no-audio --no-resume-playback --panscan=[1.0] [path/to/video.mp4]

$ xwinwrap -g 1600x900+1920 -b -nf -ov -- [mpv] --wid [wid] --loop --no-audio --no-resume-playback --panscan=[1.0] [path/to/video.mkv]

xwinwrap [OPTIONS] -- COMMAND [ARGS...]

-g WIDTHxHEIGHT+X+Y
    Sets the geometry (size and position) of the xwinwrap window.

-ni
    No Input. Prevents keyboard and mouse input from being passed to the wrapped window.

-nf
    No Focus. Prevents the wrapped window from gaining focus when clicked or tabbed to.

-b
    Below. Places the xwinwrap window below all other windows, making it suitable for a desktop background.

-fs
    Fullscreen. Makes the xwinwrap window cover the entire entire screen.

-s SCREEN_ID
    Screen ID. Specifies the X screen on which the window should be displayed in multi-monitor setups.

-o OPACITY
    Opacity. Sets the opacity of the window, a floating-point value between 0.0 (fully transparent) and 1.0 (fully opaque).

-ov
    Overlay. Forces the window to be an overlay, staying on top of other windows.

-sh
    Shared Memory. Attempts to use shared memory for rendering, which may improve performance with some applications.

-d
    Desktop. Forces the window to be treated as a desktop window (i.e., root window). This is the default behavior if not otherwise specified.

-nd
    No Desktop. Forces the window not to be treated as a desktop window.

--
    Command Separator. This crucial argument separates xwinwrap's own options from the command and its arguments that should be executed and wrapped inside the created window.

xwinwrap is a command-line utility for the X Window System that allows you to embed any running application's window as your desktop background, or as a child of another window. Its primary use case is creating animated wallpapers by wrapping a video player (like mpv) or a web browser displaying a GIF/video.

It works by creating a new X window, setting its properties (like position, size, and Z-order), and then providing its Window ID (WID) to another command. The other command is expected to render its output into this specified WID. This enables dynamic and interactive backgrounds, going beyond static images.

xwinwrap directly interacts with the X Window System and might exhibit varying behavior or compatibility issues across different desktop environments (DEs) or window managers (WMs). It can be resource-intensive depending on the wrapped application and its content (e.g., high-resolution video). Furthermore, it relies on the wrapped application being able to render to a specified X Window ID, which is not supported by all applications. It's also an older utility, and its active development status may vary depending on the distribution.

When xwinwrap creates its window, it substitutes the special string %WID in the wrapped command with the actual Window ID (WID) of the newly created window. The wrapped application (e.g., mpv) must support an option to render into a specific WID. For mpv, this is typically done using the --wid option.

Example:
xwinwrap -ni -nf -b -fs -- mpv --loop-file=inf --no-audio --no-input-default-bindings --wid=%WID /path/to/your/video.mp4

This command runs mpv in an infinite loop, without audio, without default input bindings, and renders it into the background window created by xwinwrap. The -ni -nf -b -fs options ensure it behaves correctly as a background.

xwinwrap emerged as a solution for users seeking dynamic and animated desktop backgrounds in traditional X11 environments, particularly before such features became more common or integrated into modern desktop environments like GNOME or KDE. Its development focused on providing a lightweight wrapper to leverage existing media players or rendering tools for this specific purpose, rather than building a full-fledged animated wallpaper engine from scratch.

mpv(1), feh(1), xsetroot(1), xrandr(1)