Legacy Configuration Format¶

The original hyprlax configuration format using simple text files.

Note: For new configurations, we recommend using TOML format which supports more features.

File Format¶

Legacy configuration files use a simple line-based format:

# Comments start with #
# Commands are: layer, duration, shift, easing, fps, vsync, idle_poll_rate, scale

# Add layers (required for multi-layer mode)
layer <image_path> <shift> <opacity> [blur]

# Global settings (optional)
duration <seconds>
shift <pixels>
easing <type>
fps <rate>
vsync <0|1>
idle_poll_rate <hz>
scale <multiplier>

Commands¶

layer¶

Add an image layer to the parallax stack:

layer <image_path> <shift> <opacity> [blur]

Parameters: - image_path - Path to image file (required) - shift - Movement multiplier 0.0-2.0 (required) - opacity - Layer transparency 0.0-1.0 (required) - blur - Blur amount 0.0-10.0 (optional)

duration¶

Set animation duration in seconds:

duration 1.5

shift¶

Set base parallax shift in pixels:

shift 200

easing¶

Set animation easing function:

easing expo

Available: linear, cubic, quart, quint, sine, expo, circ, elastic, back, bounce

fps¶

Set target frame rate:

fps 60

vsync¶

Enable or disable vertical sync:

vsync 1

idle_poll_rate¶

Set idle polling rate in Hertz:

idle_poll_rate 2.0

scale¶

Uniform content scale multiplier (applied to layers emitted by converter):

scale 1.1

Example Configuration¶

~/.config/hyprlax/parallax.conf:

# Three-layer parallax wallpaper

# Background - slow movement, heavy blur
layer /home/user/walls/sky.jpg 0.3 1.0 3.0

# Midground - medium speed, light blur  
layer /home/user/walls/mountains.png 0.6 0.9 1.0

# Foreground - normal speed, no blur
layer /home/user/walls/trees.png 1.0 0.8 0.0

# Animation settings
duration 1.2
shift 250
easing expo
delay 0
fps 144

Shift Multiplier Guide¶

0.0 - Static (no movement)
0.1-0.3 - Very slow (far background)
0.4-0.6 - Slow (background)
0.7-0.9 - Medium (midground)
1.0 - Normal (standard parallax)
1.1-1.5 - Fast (foreground)
1.5-2.0 - Very fast (extreme foreground)

Blur Recommendations¶

0.0 - No blur (sharp, foreground elements)
0.5-1.5 - Subtle blur (midground elements)
2.0-3.0 - Moderate blur (background elements)
3.0-5.0 - Heavy blur (distant background)
5.0+ - Extreme blur (atmospheric effects)

Usage¶

With Config File¶

hyprlax --config ~/.config/hyprlax/parallax.conf

Override Settings¶

Command-line arguments override config file settings:

hyprlax --config parallax.conf --fps 30 --duration 2.0

Limitations¶

The legacy format cannot configure: - Per-layer content fitting - Cursor parallax modes - Per-axis shift multipliers - Layer alignment and margins - Input sensitivity settings - Parallax source weights

For these features, use TOML configuration.

Migration to TOML¶

See the Migration Guide for converting legacy configs to TOML format.