Skip to content
Back to search

hyprlax

buttery smooth parallax wallpaper daemon for wayland compositors

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sandwichfarm--hyprlax/badge.svg)](/listings/sandwichfarm--hyprlax)

HTML

<a href="/listings/sandwichfarm--hyprlax"><img src="/api/listings/sandwichfarm--hyprlax/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Quick Install

The easiest (but also least secure) method to install hyprlax is with the one-liner:

curl -sSL https://hyprlax.com/install.sh | bash

The next easiest (and more secure) method is to checkout the source and run the install script:

git clone https://github.com/sandwichfarm/hyprlax.git
cd hyprlax
./install.sh        # Interactive installation (prompts for location)

Installation Options

The installer will prompt you to choose between:

1. **System-wide** (`/usr/local/bin`) - **RECOMMENDED** - Works with compositor autostart (`exec-once`) - Available to all users - Requires sudo

2. **User-specific** (`~/.local/bin`) - Only for current user - May require full path in `exec-once` commands - No sudo required

You can also specify the location directly: - **System-wide**: `./install.sh --system` - **User-specific**: `./install.sh --user`

Other Methods

- **From release**: Download from [releases page](https://github.com/sandwichfarm/hyprlax/releases) - **Manual build**: See [building from source](docs/development/building.md)

Dependencies

Wayland

- Wayland, wayland-protocols, Mesa (EGL/GLES)

Full dependency list: [installation guide](docs/getting-started/installation.md#dependencies)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 335 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # hyprlax
  2. Dynamic parallax wallpaper engine with multi-compositor support for Linux.
  3. <p align="center">
  4. <a href="https://deepwiki.com/sandwichfarm/hyprlax"><img src="https://img.shields.io/badge/DeepWiki-blue" alt="DeepWiki"></a>
  5. <img src="https://img.shields.io/badge/Wayland-Native-green" alt="Wayland Native">
  6. <img src="https://img.shields.io/badge/GPU-Accelerated-orange" alt="GPU Accelerated">
  7. <img src="https://img.shields.io/badge/Multi--Compositor-Support-purple" alt="Multi-Compositor">
  8. </p>
  9. <p align="center">
  10. <img src="/assets/hyprlax-demo.gif" alt="hyprlax parallax wallpaper animation demo" width="80%">
  11. </p>
  12. ## Features
  13. - 🎬 **Buttery smooth animations** - GPU-accelerated rendering with configurable FPS
  14. - 🖼️ **Parallax effect** - Wallpaper shifts as you switch workspaces
  15. - 🌌 **Multi-layer parallax** - Create depth with multiple layers moving at different speeds
  16. - 🔍 **Depth-of-field blur** - Realistic depth perception with per-layer blur effects
  17. - 🖥️ **Multi-compositor support** - Works with Hyprland, Sway, River, Niri, and more
  18. - ⚡ **Lightweight** - Native client using appropriate protocols for each platform
  19. - 🎨 **Customizable** - Per-layer easing functions, delays, and animation parameters
  20. - 🔄 **Seamless transitions** - Interrupts and chains animations smoothly
  21. - 🎮 **Dynamic layer management** - Add, remove, and modify layers at runtime via IPC
  22. ## Supported Compositors
  23. ### Wayland Compositors
  24. | Compositor | Workspace Model | Special Features | Status |
  25. |------------|----------------|------------------|---------|
  26. | **Hyprland** | Linear workspaces | Full IPC, blur effects, animations | ✅ Full Support |
  27. | **Niri** | Scrollable workspaces | Smooth scrolling | ⚡ Experimental |
  28. | **River** | Tag-based system | Tag workspace model | ⚡ Experimental |
  29. | **Sway** | i3-compatible workspaces | i3 IPC protocol | ⚡ Experimental |
  30. | **Generic Wayland** | Basic workspaces | Any wlr-layer-shell compositor | ⚡ Experimental |
  31. ## Installation
  32. ### Quick Install
  33. The easiest (but also least secure) method to install hyprlax is with the one-liner:
  34. ```bash
  35. curl -sSL https://hyprlax.com/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 47 on GitHub
  36. ```
  37. The next easiest (and more secure) method is to checkout the source and run the install script:
  38. ```bash
  39. git clone https://github.com/sandwichfarm/hyprlax.git
  40. cd hyprlax
  41. ./install.sh # Interactive installation (prompts for location)
  42. ```
  43. ### Installation Options
  44. The installer will prompt you to choose between:
  45. 1. **System-wide** (`/usr/local/bin`) - **RECOMMENDED**
  46. - Works with compositor autostart (`exec-once`)
  47. - Available to all users
  48. - Requires sudo
  49. 2. **User-specific** (`~/.local/bin`)
  50. - Only for current user
  51. - May require full path in `exec-once` commands
  52. - No sudo required
  53. You can also specify the location directly:
  54. - **System-wide**: `./install.sh --system`
  55. - **User-specific**: `./install.sh --user`
  56. ### Other Methods
  57. - **From release**: Download from [releases page](https://github.com/sandwichfarm/hyprlax/releases)
  58. - **Manual build**: See [building from source](docs/development/building.md)
  59. ### Dependencies
  60. #### Wayland
  61. - Wayland, wayland-protocols, Mesa (EGL/GLES)
  62. Full dependency list: [installation guide](docs/getting-started/installation.md#dependencies)
  63. ## Quick Start
  64. ### Basic Usage
  65. ```bash
  66. # Single wallpaper (auto-detects compositor)
  67. hyprlax ~/Pictures/wallpaper.jpg
  68. # Multi-layer parallax
  69. hyprlax --layer background.jpg:0.3:1.0:expo:0:1.0:3.0 \
  70. --layer foreground.png:1.0:0.7
  71. # Using TOML config
  72. hyprlax --config ~/.config/hyprlax/hyprlax.toml
  73. # Force specific compositor
  74. HYPRLAX_COMPOSITOR=sway hyprlax ~/Pictures/wallpaper.jpg
  75. ```
  76. ### Key Options
  77. - `-s, --shift` - Pixels to shift per workspace (default: 150)
  78. - `-d, --duration` - Animation duration in seconds (default: 1.0)
  79. - `-e, --easing` - Animation curve: linear, sine, expo, elastic, etc.
  80. - `--input` - Parallax inputs (e.g., `workspace,cursor:0.3`)
  81. - `-p, --platform` - Platform backend: `wayland` or `auto` (default: auto)
  82. - `-C, --compositor` - Compositor: `hyprland`, `sway`, `generic`, `auto` (default: auto)
  83. - `--layer` - Add layer: `image:shift:opacity[:blur]`
  84. - `--config` - Load from config file
  85. **Full documentation:** [Configuration Overview](docs/configuration/README.md)
  86. ### Migrating from legacy .conf
  87. Legacy `.conf` files are deprecated. Convert once to TOML for full feature support and better validation:
  88. ```bash
  89. # Interactive (prompts):
  90. hyprlax ctl convert-config ~/.config/hyprlax/parallax.conf ~/.config/hyprlax/hyprlax.toml
  91. # Non-interactive:
  92. hyprlax ctl convert-config ~/.config/hyprlax/parallax.conf ~/.config/hyprlax/hyprlax.toml --yes
  93. # If you start hyprlax with a legacy path, it will warn and print a suggested convert command
  94. hyprlax --config ~/.config/hyprlax/parallax.conf
  95. ```
  96. ## Generate Parallax Backgrounds with an Agent Skill
  97. The [parallax-backgrounds skill](skills/parallax-backgrounds/SKILL.md) guides an image-capable
  98. agent through generating aligned layers, reconstructing scenery hidden by foreground objects,
  99. and exporting transparency and borders that remain convincing during movement.
  100. Install with the [skills CLI](https://skills.sh/docs/cli) (requires Node.js/npm):
  101. ```bash
  102. npx skills add sandwichfarm/hyprlax --skill parallax-backgrounds
  103. ```
  104. Choose your agent when prompted, or target Codex explicitly:
  105. ```bash
  106. npx skills add sandwichfarm/hyprlax --skill parallax-backgrounds --agent codex
  107. ```
  108. Add `--global` for installation across projects. To install from a local checkout, including
  109. an unmerged branch, run this from the repository root:
  110. ```bash
  111. npx skills add . --skill parallax-backgrounds
  112. ```
  113. Example request: “Use the parallax-backgrounds skill to create a three-layer forest wallpaper
  114. for hyprlax at 1920×1080, with cursor movement of ±80 px horizontally and ±40 px vertically.”
  115. The skill includes generation prompts, motion/occlusion checks, a hyprlax configuration example,
  116. and an optional PNG inspection helper (Python 3 + Pillow). Actual image creation requires the
  117. agent to have an image-generation/editing capability; installing the skill does not supply one.
  118. ## Compositor Configuration
  119. > **Important:** For `exec-once` commands to work, hyprlax must be installed system-wide (`/usr/local/bin`).
  120. > If installed to `~/.local/bin`, use the full path: `~/.local/bin/hyprlax`
  121. ### Hyprland
  122. Add to `~/.config/hypr/hyprland.conf`:
  123. ```bash
  124. exec-once = pkill hyprlax; hyprlax ~/Pictures/wallpaper.jpg
  125. # If installed to ~/.local/bin:
  126. # exec-once = pkill hyprlax; ~/.local/bin/hyprlax ~/Pictures/wallpaper.jpg
  127. ```
  128. ### Sway/i3
  129. Add to `~/.config/sway/config` or `~/.config/i3/config`:
  130. ```bash
  131. exec_always pkill hyprlax; hyprlax ~/Pictures/wallpaper.jpg
  132. ```
  133. ### River
  134. Add to your River init script:
  135. ```bash
  136. riverctl spawn "pkill hyprlax; hyprlax ~/Pictures/wallpaper.jpg"
  137. ```
  138. ### Other Compositors
  139. See [Compatibility](docs/getting-started/compatibility.md) for specifics.
  140. ## Runtime Control
  141. Control layers and settings at runtime using the integrated `ctl` subcommand:
  142. Tip: add `-j` or `--json` after `ctl` to get JSON output for any command. For `status` and `list`, this enables server-side structured JSON; for others, the client returns a simple wrapper like `{ "ok": true/false, "output"|"error": ... }`.
  143. ### Layer Management
  144. ```bash
  145. # Add a new layer
  146. hyprlax ctl add /path/to/image.png 1.5 0.8 10
  147. # Modify layer properties
  148. # Note: x and y are UV pan offsets (normalized texture coordinates)
  149. # Typical range is -0.10 .. 0.10 (1.00 = full texture width/height)
  150. hyprlax ctl modify 1 opacity 0.5
  151. hyprlax ctl modify 1 x 0.05
  152. hyprlax ctl modify 1 y -0.02
  153. # Remove a layer
  154. hyprlax ctl remove 1
  155. # List all layers
  156. hyprlax ctl list
  157. # Clear all layers
  158. hyprlax ctl clear
  159. ```
  160. ### Runtime Settings
  161. ```bash
  162. # Change FPS (canonical key; alias `fps` also works)
  163. hyprlax ctl set render.fps 120
  164. # Change animation duration / easing (aliases: duration/easing)
  165. hyprlax ctl set animation.duration 2.0
  166. hyprlax ctl set animation.easing elastic
  167. # Query current settings
  168. hyprlax ctl get render.fps
  169. hyprlax ctl get animation.duration
  170. # Get daemon status
  171. hyprlax ctl status
  172. ```
  173. **Full guide:** [IPC Overview](docs/guides/ipc-overview.md) and [IPC Commands](docs/reference/ipc-commands.md)
  174. ## Documentation
  175. ### 📚 User Guides
  176. - [Installation](docs/getting-started/installation.md) - Detailed installation instructions
  177. - [Configuration](docs/configuration/README.md) - All configuration options
  178. - [Environment Variables](docs/reference/environment-vars.md) - ENV mapping and precedence
  179. - [Compatibility](docs/getting-started/compatibility.md) - Compositor-specific features
  180. - [Multi-Layer Parallax](docs/guides/multi-layer.md) - Creating depth with layers
  181. - [Animation](docs/guides/animation.md) - Easing functions and timing
  182. - [Examples](docs/guides/examples.md) - Ready-to-run scenes
  183. - [Performance](docs/guides/performance.md) - Optimization tips
  184. - [Troubleshooting](docs/guides/troubleshooting.md) - Common issues and solutions
  185. ### 🔧 Developer Guides
  186. - [Architecture](docs/development/architecture.md) - Modular design and components
  187. - [Development](docs/development/README.md) - Building and contributing
  188. - [Adding Compositors](docs/development/architecture.md) - Extending compositor support
  189. ### ❓ Help
  190. - [Troubleshooting](docs/guides/troubleshooting.md) - Common issues and solutions
  191. - [Dynamic Layers](docs/guides/ipc-overview.md) - Runtime layer control via IPC
  192. ## Changelog
  193. See [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes in each release.
  194. ## Development
  195. ### Architecture
  196. hyprlax uses a modular architecture with clear separation of concerns:
  197. - **Platform abstraction** - Wayland backend with modular design
  198. - **Compositor adapters** - Specific compositor implementations
  199. - **Renderer abstraction** - OpenGL ES 2.0 rendering
  200. - **Core engine** - Animation and configuration management
  201. See [Architecture Documentation](docs/development/architecture.md) for details.
  202. ### Testing
  203. hyprlax uses the [Check](https://libcheck.github.io/check/) framework for unit testing. Tests cover core functionality including animations, configuration parsing, IPC, shaders, and more.
  204. #### Running Tests
  205. ```bash
  206. # Run all tests
  207. make test
  208. # Run tests with memory leak detection
  209. make memcheck
  210. # Run individual test suites
  211. ./tests/test_blur
  212. ./tests/test_config
  213. ./tests/test_animation
  214. ```
  215. ### Code Quality Tools
  216. ```bash
  217. # Run linter to check for issues
  218. make lint
  219. # Auto-fix formatting issues
  220. make lint-fix
  221. # Setup git hooks for automatic pre-commit checks
  222. ./scripts/setup-hooks.sh
  223. ```
  224. ## Contributing
  225. Pull requests are welcome! Please read [RELEASE.md](RELEASE.md) for the release process.
  226. See [Development Guide](docs/development/README.md) for:
  227. - Building from source
  228. - Project architecture
  229. - Adding new features
  230. - Code style guidelines
  231. ## License
  232. MIT
  233. ## Roadmap
  234. - [x] Multi-compositor support (Wayland)
  235. - [x] Dynamic layer loading/unloading
  236. - [ ] Multi-monitor support
  237. - [ ] Video wallpaper support
  238. - [ ] Integration with wallpaper managers

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.