X11 Animated Background

Warning

THIS PROJECT IS EXPERIMENTAL

Warning

If you are using a picom compositor, using the egl backend is highly recommended

Warning

Performance kinda sucks on GPUs without hwdec support

---

Table of Contents

1. Introduction
2. Features
3. Usage
4. Prerequisites
   • Hardware
   • Dependencies
   • Video Readers
   • Optional Dependencies
5. Build
   • Setup
   • Build Instructions
   • Installation
6. Meson Options
7. Contributing
8. License

---

Introduction

xab (X11 Animated Background) is an overkill animated wallpaper setter for X11 that strives to be as feature complete as possible

Supported file formats

Any format supported by ffmpeg

Features

• Compatible with modern compositors (e.g. picom)
• Multimonitor support (optional dependencies required)
• Can render lowres pixel art videos without them being blurry
• Custom shader support

Usage

# example:
xab bg.mp4 --monitor=0 pixel_bg.gif --monitor=1 --pixelated=1

global options:

Option	Description	Default
-v=0|1, --vsync=0|1	synchronize framerate to monitor framerate	1
--hw_accel=yes|no|auto	use hardware acceleration for video decoding (hardware needs to support it)	auto
--ipc=1|0	enable IPC for xab	0

per video/monitor options:

Option	Description	Default
-p=0|1, --pixelated=0|1	use point instead of bilinear filtering for rendering the background	0 (bilinear)
-M=n, --monitor=n	which monitor to use (optional dependencies required)	-1 (fullscreen)
-x, --offset_x=n	offset wallpaper x coordinate	0
-y, --offset_y=n	offset wallpaper y coordinate	0

Prerequisites

Hardware requirements

Anything that supports OpenGL 3.3+

Dependencies

Assuming you already have the building tools installed (e.g. gcc, meson, ninja, etc.), you still need:

• xcb
• xcb-util
• xproto
• libGL
• libEGL
• video reader dependencies

for video reading, you must have one of the following:

• mpv video reader (default):
  • libmpv
• ffmpeg video reader:
  • libavutil
  • libavcodec
  • libavformat
  • libavfilter
  • libswscale

Debian distributions (e.g. Ubuntu) with apt

sudo apt-get install libxcb1-dev libxcb-util0-dev x11proto-dev \
    libgl1-mesa-dev libegl1-mesa-dev

# mpv video reader:
sudo apt-get install libmpv-dev

# ffmpeg video reader:
sudo apt-get install libavcodec-dev libavformat-dev libavfilter-dev \
    libavutil-dev libswresample-dev libswscale-dev

Video readers

If you use a video reader other than the default (mpv), you need to change the 'video_reader' option in Meson to match the chosen video reader's option. see meson options for more details

currently there are two options:

• [default] mpv - this is the recommended video reader, it uses libmpv to read the video

• ffmpeg - my home made video reader - do not expect ANYTHING to work, memory leaks may occur and xab may crash, using --hw_accel=no is currently reccomended

no vlc support is planned until vlc 4.x is released

Optional dependencies

for multi-monitor support you must have:

• cglm version >= 0.8.4
• xcb-randr version >= 1.5

Optional dependencies on Debian distributions with apt

# xcb-randr
sudo apt-get install libxcb-randr-dev

# cglm
sudo apt-get install libcglm-dev

TODO: fedora and arch

Build

Setup

meson setup build

To build

meson compile -C build

Built binary can be found in build/xab

---

To install

# (sudo)
meson install -C build

This will install xab at /usr/local/bin (probably)

---

Meson options

To see the full list of the meson options, run meson configure build

# enable verbose logging
meson configure build -Dlog=verbose

# change video reader
meson configure build -Dvideo_reader=ffmpeg

# disable BCE files
meson configure build -Dnobce=true

# disable PCH
meson configure build -Dnopch=true

# disable ANSII colored logging
meson configure build -Dansii_log=false

---

features that you probably don't care about

• Binary C embed for shader files so you can run your lil executable from anywhere
• PCH for slightly faster build times
• an overkill shader cache system
• fancy colored logging
• a cool mouse light shader

Profiling

im not gonna fully document this so ummm deal with it

xab uses tracy for profiling:

meson setup tbuild --buildtype=debugoptimized \
    -Dlog=trace -Dopengl_debug_callback=disabled -Dtracy_enable=true
meson compile -C tbuild

to build the profiler, cd to ./subprojects/tracy-x.xx.x/ then run

# tracy only supports cmake to actually build the profiler so deal with it
cmake -B profiler/build -S profiler -DCMAKE_BUILD_TYPE=Release -DLEGACY=true
cd profiler/build
make -j$(nproc)

profiler binary should be found at profiler/build/tracy-profiler
for more information go to wolfpld/tracy and read the docs

Testing

currently, xab has only tests for some components of the ffmpeg video reader, more comprehensive test for *all of the compenents of xab are (probably) on their way at some point

to run the tests:

meson configure build -Dtests=true
meson test -C build

Contributing

yes

License

xab is licensed under the MIT license