X11 Animated Background

Warning

THIS PROJECT IS HIGHLY EXPERIMENTAL

Warning

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

---

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

---

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
-M=n, --monitor=n	which monitor to use (optional dependencies required)	-1 (fullscreen)
-v=0|1, --vsync=0|1	synchronize framerate to monitor framerate	1

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)
--hw_accel=yes|no|auto	use hardware acceleration for video decoding (hardware needs to support it)	auto

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
• libepoxy
• libGL
• libEGL
• video reader dependencies

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

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

Debian distributions (e.g. Ubuntu) with apt

sudo apt-get install libepoxy-dev 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] libmpv (mpv) - this is the recommended video reader, it uses libmpv to read the video

• ffmpeg - i made this video reader for educational purposes, this is an ffmpeg-based video reader, it is way less performant compared to the the other options, this is my fault because i suck at ffmpeg, also many of the features are not implemented (yet?) like frame timing, frame dropping and hardware acceleration

i am also planning to add libVLC support

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 -nobce=true

# disable PCH
meson configure build -nopch=true

# disable ANSII colored logging
meson configure build -Denable_ansii_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 -Denable_opengl_debug_callback=disabled -Dtracy_enable=true
meson compile -C tbuild