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.
Badge for your README
Markdown
[](/listings/sandwichfarm--hyprlax)HTML
<a href="/listings/sandwichfarm--hyprlax"><img src="/api/listings/sandwichfarm--hyprlax/badge.svg" alt="findsafeskills safety rating" /></a>Install
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)
- # hyprlax
- Dynamic parallax wallpaper engine with multi-compositor support for Linux.
- <p align="center">
- <a href="https://deepwiki.com/sandwichfarm/hyprlax"><img src="https://img.shields.io/badge/DeepWiki-blue" alt="DeepWiki"></a>
- <img src="https://img.shields.io/badge/Wayland-Native-green" alt="Wayland Native">
- <img src="https://img.shields.io/badge/GPU-Accelerated-orange" alt="GPU Accelerated">
- <img src="https://img.shields.io/badge/Multi--Compositor-Support-purple" alt="Multi-Compositor">
- </p>
- <p align="center">
- <img src="/assets/hyprlax-demo.gif" alt="hyprlax parallax wallpaper animation demo" width="80%">
- </p>
- ## Features
- - 🎬 **Buttery smooth animations** - GPU-accelerated rendering with configurable FPS
- - 🖼️ **Parallax effect** - Wallpaper shifts as you switch workspaces
- - 🌌 **Multi-layer parallax** - Create depth with multiple layers moving at different speeds
- - 🔍 **Depth-of-field blur** - Realistic depth perception with per-layer blur effects
- - 🖥️ **Multi-compositor support** - Works with Hyprland, Sway, River, Niri, and more
- - ⚡ **Lightweight** - Native client using appropriate protocols for each platform
- - 🎨 **Customizable** - Per-layer easing functions, delays, and animation parameters
- - 🔄 **Seamless transitions** - Interrupts and chains animations smoothly
- - 🎮 **Dynamic layer management** - Add, remove, and modify layers at runtime via IPC
- ## Supported Compositors
- ### Wayland Compositors
- | Compositor | Workspace Model | Special Features | Status |
- |------------|----------------|------------------|---------|
- | **Hyprland** | Linear workspaces | Full IPC, blur effects, animations | ✅ Full Support |
- | **Niri** | Scrollable workspaces | Smooth scrolling | ⚡ Experimental |
- | **River** | Tag-based system | Tag workspace model | ⚡ Experimental |
- | **Sway** | i3-compatible workspaces | i3 IPC protocol | ⚡ Experimental |
- | **Generic Wayland** | Basic workspaces | Any wlr-layer-shell compositor | ⚡ Experimental |
- ## Installation
- ### Quick Install
- The easiest (but also least secure) method to install hyprlax is with the one-liner:
- ```bash
- 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
- ```
- The next easiest (and more secure) method is to checkout the source and run the install script:
- ```bash
- 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)
- ## Quick Start
- ### Basic Usage
- ```bash
- # Single wallpaper (auto-detects compositor)
- hyprlax ~/Pictures/wallpaper.jpg
- # Multi-layer parallax
- hyprlax --layer background.jpg:0.3:1.0:expo:0:1.0:3.0 \
- --layer foreground.png:1.0:0.7
- # Using TOML config
- hyprlax --config ~/.config/hyprlax/hyprlax.toml
- # Force specific compositor
- HYPRLAX_COMPOSITOR=sway hyprlax ~/Pictures/wallpaper.jpg
- ```
- ### Key Options
- - `-s, --shift` - Pixels to shift per workspace (default: 150)
- - `-d, --duration` - Animation duration in seconds (default: 1.0)
- - `-e, --easing` - Animation curve: linear, sine, expo, elastic, etc.
- - `--input` - Parallax inputs (e.g., `workspace,cursor:0.3`)
- - `-p, --platform` - Platform backend: `wayland` or `auto` (default: auto)
- - `-C, --compositor` - Compositor: `hyprland`, `sway`, `generic`, `auto` (default: auto)
- - `--layer` - Add layer: `image:shift:opacity[:blur]`
- - `--config` - Load from config file
- **Full documentation:** [Configuration Overview](docs/configuration/README.md)
- ### Migrating from legacy .conf
- Legacy `.conf` files are deprecated. Convert once to TOML for full feature support and better validation:
- ```bash
- # Interactive (prompts):
- hyprlax ctl convert-config ~/.config/hyprlax/parallax.conf ~/.config/hyprlax/hyprlax.toml
- # Non-interactive:
- hyprlax ctl convert-config ~/.config/hyprlax/parallax.conf ~/.config/hyprlax/hyprlax.toml --yes
- # If you start hyprlax with a legacy path, it will warn and print a suggested convert command
- hyprlax --config ~/.config/hyprlax/parallax.conf
- ```
- ## Generate Parallax Backgrounds with an Agent Skill
- The [parallax-backgrounds skill](skills/parallax-backgrounds/SKILL.md) guides an image-capable
- agent through generating aligned layers, reconstructing scenery hidden by foreground objects,
- and exporting transparency and borders that remain convincing during movement.
- Install with the [skills CLI](https://skills.sh/docs/cli) (requires Node.js/npm):
- ```bash
- npx skills add sandwichfarm/hyprlax --skill parallax-backgrounds
- ```
- Choose your agent when prompted, or target Codex explicitly:
- ```bash
- npx skills add sandwichfarm/hyprlax --skill parallax-backgrounds --agent codex
- ```
- Add `--global` for installation across projects. To install from a local checkout, including
- an unmerged branch, run this from the repository root:
- ```bash
- npx skills add . --skill parallax-backgrounds
- ```
- Example request: “Use the parallax-backgrounds skill to create a three-layer forest wallpaper
- for hyprlax at 1920×1080, with cursor movement of ±80 px horizontally and ±40 px vertically.”
- The skill includes generation prompts, motion/occlusion checks, a hyprlax configuration example,
- and an optional PNG inspection helper (Python 3 + Pillow). Actual image creation requires the
- agent to have an image-generation/editing capability; installing the skill does not supply one.
- ## Compositor Configuration
- > **Important:** For `exec-once` commands to work, hyprlax must be installed system-wide (`/usr/local/bin`).
- > If installed to `~/.local/bin`, use the full path: `~/.local/bin/hyprlax`
- ### Hyprland
- Add to `~/.config/hypr/hyprland.conf`:
- ```bash
- exec-once = pkill hyprlax; hyprlax ~/Pictures/wallpaper.jpg
- # If installed to ~/.local/bin:
- # exec-once = pkill hyprlax; ~/.local/bin/hyprlax ~/Pictures/wallpaper.jpg
- ```
- ### Sway/i3
- Add to `~/.config/sway/config` or `~/.config/i3/config`:
- ```bash
- exec_always pkill hyprlax; hyprlax ~/Pictures/wallpaper.jpg
- ```
- ### River
- Add to your River init script:
- ```bash
- riverctl spawn "pkill hyprlax; hyprlax ~/Pictures/wallpaper.jpg"
- ```
- ### Other Compositors
- See [Compatibility](docs/getting-started/compatibility.md) for specifics.
- ## Runtime Control
- Control layers and settings at runtime using the integrated `ctl` subcommand:
- 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": ... }`.
- ### Layer Management
- ```bash
- # Add a new layer
- hyprlax ctl add /path/to/image.png 1.5 0.8 10
- # Modify layer properties
- # Note: x and y are UV pan offsets (normalized texture coordinates)
- # Typical range is -0.10 .. 0.10 (1.00 = full texture width/height)
- hyprlax ctl modify 1 opacity 0.5
- hyprlax ctl modify 1 x 0.05
- hyprlax ctl modify 1 y -0.02
- # Remove a layer
- hyprlax ctl remove 1
- # List all layers
- hyprlax ctl list
- # Clear all layers
- hyprlax ctl clear
- ```
- ### Runtime Settings
- ```bash
- # Change FPS (canonical key; alias `fps` also works)
- hyprlax ctl set render.fps 120
- # Change animation duration / easing (aliases: duration/easing)
- hyprlax ctl set animation.duration 2.0
- hyprlax ctl set animation.easing elastic
- # Query current settings
- hyprlax ctl get render.fps
- hyprlax ctl get animation.duration
- # Get daemon status
- hyprlax ctl status
- ```
- **Full guide:** [IPC Overview](docs/guides/ipc-overview.md) and [IPC Commands](docs/reference/ipc-commands.md)
- ## Documentation
- ### 📚 User Guides
- - [Installation](docs/getting-started/installation.md) - Detailed installation instructions
- - [Configuration](docs/configuration/README.md) - All configuration options
- - [Environment Variables](docs/reference/environment-vars.md) - ENV mapping and precedence
- - [Compatibility](docs/getting-started/compatibility.md) - Compositor-specific features
- - [Multi-Layer Parallax](docs/guides/multi-layer.md) - Creating depth with layers
- - [Animation](docs/guides/animation.md) - Easing functions and timing
- - [Examples](docs/guides/examples.md) - Ready-to-run scenes
- - [Performance](docs/guides/performance.md) - Optimization tips
- - [Troubleshooting](docs/guides/troubleshooting.md) - Common issues and solutions
- ### 🔧 Developer Guides
- - [Architecture](docs/development/architecture.md) - Modular design and components
- - [Development](docs/development/README.md) - Building and contributing
- - [Adding Compositors](docs/development/architecture.md) - Extending compositor support
- ### ❓ Help
- - [Troubleshooting](docs/guides/troubleshooting.md) - Common issues and solutions
- - [Dynamic Layers](docs/guides/ipc-overview.md) - Runtime layer control via IPC
- ## Changelog
- See [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes in each release.
- ## Development
- ### Architecture
- hyprlax uses a modular architecture with clear separation of concerns:
- - **Platform abstraction** - Wayland backend with modular design
- - **Compositor adapters** - Specific compositor implementations
- - **Renderer abstraction** - OpenGL ES 2.0 rendering
- - **Core engine** - Animation and configuration management
- See [Architecture Documentation](docs/development/architecture.md) for details.
- ### Testing
- 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.
- #### Running Tests
- ```bash
- # Run all tests
- make test
- # Run tests with memory leak detection
- make memcheck
- # Run individual test suites
- ./tests/test_blur
- ./tests/test_config
- ./tests/test_animation
- ```
- ### Code Quality Tools
- ```bash
- # Run linter to check for issues
- make lint
- # Auto-fix formatting issues
- make lint-fix
- # Setup git hooks for automatic pre-commit checks
- ./scripts/setup-hooks.sh
- ```
- ## Contributing
- Pull requests are welcome! Please read [RELEASE.md](RELEASE.md) for the release process.
- See [Development Guide](docs/development/README.md) for:
- - Building from source
- - Project architecture
- - Adding new features
- - Code style guidelines
- ## License
- MIT
- ## Roadmap
- - [x] Multi-compositor support (Wayland)
- - [x] Dynamic layer loading/unloading
- - [ ] Multi-monitor support
- - [ ] Video wallpaper support
- - [ ] Integration with wallpaper managers
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.