README.md

caelestia-lib

A shared C++ library for Caelestia.

Modules

Module	Contains
config	Basic access to ~/.config/caelestia/config.json + paths
ipc	CLI to shell requests over a local socket + QML module
media	Image/video colour analysis
record	Screen recorder lifecycle and state
scheme	Material 3 scheme generation
screenshot	Wayland screen capture via ext-image-copy-capture
theme	Apply schemes to apps
utils	File and blob caches, component registry, Hyprland socket
wallpaper	Current wallpaper state and wallpaper-driven schemes

Dependencies

• qt6-base
• ffmpeg
• wayland (wayland-client + wayland-scanner)
• wayland-protocols >= 1.37

Installation

cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr
cmake --build build
sudo cmake --install build

The ipc module also installs a Caelestia.Ipc QML module exposing the server side. The QML module is on by default and can be disabled with -DBUILD_QML=OFF. The install location is controlled by INSTALL_QMLDIR.

Important

The theme module has 2 targets which require access to sudo. A sudoers file is installed by default and allows passwordless access to the helpers. This can be disabled with -DINSTALL_SUDOERS=OFF, or the location of the sudoers directory can be changed with -DSUDOERS_DIR=....

Testing

cmake -B build -G Ninja -DBUILD_TESTING=ON
cmake --build build
ctest --test-dir build -j4

Usage

This library is designed to be consumed via CMake's find_package like so:

find_package(caelestia REQUIRED)
caelestia_setup()
target_link_libraries(myapp PRIVATE caelestia::caelestia)

An optional caelestia_setup_warnings() macro is available for enabling strict warnings (Qt cast disables + strict build warnings).