Skip to content

IPC Overview

Hyprlax exposes a runtime IPC interface that allows you to control layers and settings without restarting the daemon. Use the integrated command hyprlax ctl for human-friendly control and scripting.

For the full command reference, see: reference/ipc-commands.md.

Typical Workflows

# Add a layer
hyprlax ctl add /path/to/img.png shift_multiplier=1.2 opacity=0.9 z=0

# Modify layer properties
hyprlax ctl modify 1 opacity 0.5
hyprlax ctl modify 1 shift_multiplier 0.8

# UV pan (normalized): shifts the sampled texture
# Typical range: -0.10 .. 0.10 (1.00 = full texture width/height)
hyprlax ctl modify 1 x 0.05
hyprlax ctl modify 1 y -0.02

# Z-order (ascending): lower z draws first (behind)
hyprlax ctl modify 1 z 10

# Blur amount
hyprlax ctl modify 1 blur 3.0

# Fit/align/content scale
hyprlax ctl modify 1 fit cover
hyprlax ctl modify 1 align.x 0.5
hyprlax ctl modify 1 align.y 0.5
hyprlax ctl modify 1 content_scale 1.2

# Overflow/tiling/margins
hyprlax ctl modify 1 overflow none
hyprlax ctl modify 1 tile.x true
hyprlax ctl modify 1 tile.y false
hyprlax ctl modify 1 margin_px.x 24
hyprlax ctl modify 1 margin_px.y 24

# Remove / list / clear
hyprlax ctl remove 1
hyprlax ctl list              # compact
hyprlax ctl list --long       # detailed
hyprlax ctl list --json       # JSON
hyprlax ctl list --filter path~=sunset  # filter by substring
hyprlax ctl list --filter id=2
hyprlax ctl list --filter hidden=true
hyprlax ctl clear

# Z-order convenience
hyprlax ctl front 3   # bring to front (highest z)
hyprlax ctl back  1   # send to back (lowest z)
hyprlax ctl up    2   # move forward by one step
hyprlax ctl down  2   # move backward by one step

Settings

# Canonical dotted keys (aliases like fps/shift/duration/easing are accepted):
hyprlax ctl set render.fps 120
hyprlax ctl set parallax.shift_pixels 200
hyprlax ctl set animation.duration 1.2
hyprlax ctl set animation.easing cubic

hyprlax ctl get render.fps
hyprlax ctl get animation.duration

Structured properties are also available (examples):

hyprlax ctl set parallax.input workspace,cursor:0.3
hyprlax ctl set parallax.sources.cursor.weight 0.5  # legacy, still accepted
hyprlax ctl set render.overflow none
hyprlax ctl set render.tile.x true
hyprlax ctl get render.margin_px.x

Configure sources with parallax.input (e.g., workspace,cursor:0.3). Legacy parallax.mode is removed.

Understanding x/y (UV Pan)

  • x and y are normalized UV offsets applied to the layer’s texture coordinates before parallax.
  • Values are in the texture domain: 1.0 corresponds to the full width/height of the texture.
  • Recommended range: -0.10 .. 0.10 for subtle panning without visible tiling/clamp artifacts.
  • Behavior with tiling:
  • When tiling is enabled (repeat), UVs wrap seamlessly.
  • With overflow=none/clamp, out-of-range UVs may be masked.

If you need pixel-accurate positioning in screen space, consider using per-pixel offsets when they are introduced (future addition).

Status & Reload

hyprlax ctl status           # add --json for machine-readable output
hyprlax ctl reload           # reload config (TOML only; legacy paths will print a conversion hint)