Animation Guide¶

Master the animation system to create smooth, natural parallax effects.

Parallax Inputs¶

Hyprlax combines one or more input sources to drive layer movement: - workspace: driven by workspace changes (original behavior) - cursor: driven by smoothed cursor motion - window: tracks the active window center (implemented for Hyprland; other compositors ignore it gracefully until native support is added)

Configure sources via CLI or TOML:

# CLI examples
hyprlax --input workspace                      # workspace only
hyprlax --input workspace,cursor:0.3           # workspace + cursor blend

# TOML (preferred)
[global.parallax]
input = ["workspace", "cursor:0.3"]

[global.parallax.invert.cursor]
x = true  # invert X for increased depth feeling
y = false

[global.input.cursor]
sensitivity_x = 1.0
sensitivity_y = 0.25
deadzone_px = 3
ema_alpha = 0.25

Use parallax.input (or --input on CLI) to select sources and optional weights.

Per-Layer Axis Control¶

Fine-tune depth with per-axis multipliers on each layer:

[[global.layers]]
path = "images/foreground.png"
shift_multiplier = { x = 1.0, y = 0.0 }  # disable Y parallax for this layer
opacity = 1.0

This is useful to keep a subject anchored vertically (e.g., ensuring the bottom of a foreground element never rises above the screen), while still allowing the background to subtly move in Y for a bokeh-like feel.

Animation Basics¶

Hyprlax animates wallpaper movement when you switch workspaces. The animation system controls: - How fast the transition happens (duration) - The acceleration curve (easing) - When the animation starts (delay) - How smooth it appears (frame rate)

Easing Functions¶

Easing functions control the acceleration and deceleration of animations, making them feel more natural.

Available Easing Types¶

Type	Description	Best For
`linear`	Constant speed	Mechanical, robotic feel
`quad`	Gentle acceleration (x²)	Subtle, soft movements
`cubic`	Moderate acceleration (x³)	Balanced, natural feel
`quart`	Strong acceleration (x⁴)	Emphatic movements
`quint`	Very strong acceleration (x⁵)	Dramatic effects
`sine`	Smooth sine wave curve	Very natural, organic
`expo`	Exponential ease-out	Snappy, modern
`circ`	Circular function curve	Unique, slightly bouncy
`back`	Slight overshoot at end	Playful, energetic
`elastic`	Bouncy spring effect	Fun, attention-grabbing
`snap`	Custom snappy curve	Extra responsive feel

Visualizing Easing Curves¶

Linear:         ────────────────
                ╱
               ╱
              ╱

Expo Out:      ──╱
                ╱
               ╱
              ╱

Elastic:       ─┐ ╱─╱─
                └╱
               ╱

Back:          ───╱──┐
                 ╱    └─
                ╱

Animation Parameters¶

Duration¶

Controls how long the animation takes to complete.

# Fast transition (0.3 seconds)
hyprlax -d 0.3 wallpaper.jpg

# Slow, dramatic (2 seconds)
hyprlax -d 2.0 wallpaper.jpg

# Default (1 second)
hyprlax wallpaper.jpg

Recommendations: - 0.2-0.4s - Snappy, responsive - 0.5-0.8s - Balanced, comfortable - 1.0-1.5s - Smooth, relaxed - 1.5-2.0s - Slow, dramatic

Delay¶

Note: A global animation delay is not currently configurable from the CLI.

Frame Rate¶

Controls animation smoothness.

# High-end system (144 FPS)
hyprlax --fps 144 wallpaper.jpg

# Power saving (30 FPS)
hyprlax --fps 30 wallpaper.jpg

# Cinematic (24 FPS)
hyprlax --fps 24 wallpaper.jpg

Performance guide: - 144+ FPS: High-end gaming monitors - 60 FPS: Standard smooth animation - 30 FPS: Power efficient, still smooth - 24 FPS: Cinematic, may feel less responsive

Multi-Layer Parameters¶

When adding layers via CLI, use:

--layer image:shift:opacity[:blur]

Examples:

--layer bg.jpg:0.3:1.0:3.0   # slow, heavily blurred background
--layer mg.png:0.6:0.8:1.5   # midground with light blur
--layer fg.png:1.0:0.7       # foreground, no blur

Animation Presets¶

Smooth and Relaxed¶

hyprlax -d 1.5 -e sine -s 200 wallpaper.jpg

Perfect for: Calm, professional environments

Snappy and Responsive¶

hyprlax -d 0.3 -e expo -s 150 wallpaper.jpg

Perfect for: Gaming setups, high-energy workflows

Playful and Bouncy¶

hyprlax -d 0.8 -e elastic -s 180 wallpaper.jpg

Perfect for: Creative workspaces, fun themes

Dramatic and Cinematic¶

hyprlax -d 2.0 -e quint -s 300 wallpaper.jpg

Perfect for: Showcases, presentations

Advanced Animation Techniques¶

Acceleration Profiles¶

Combine easing with duration for different feels:

# Quick start, slow finish
hyprlax -e expo -d 1.2 wallpaper.jpg

# Slow start, quick finish  
hyprlax -e sine -d 0.8 wallpaper.jpg

# Uniform speed
hyprlax -e linear -d 1.0 wallpaper.jpg

Workspace-Aware Animation¶

Adjust shift amount based on workspace count:

# 10 workspaces, small shifts
hyprlax -s 100 wallpaper.jpg

# 4 workspaces, large shifts
hyprlax -s 400 wallpaper.jpg

Multi-Layer Choreography¶

Create complex animations with careful timing:

# Wave effect – vary speeds and blur per layer
hyprlax --layer l1.png:0.3:1.0:2.0 \
        --layer l2.png:0.5:0.9:1.5 \
        --layer l3.png:0.7:0.8:1.0 \
        --layer l4.png:0.9:0.7:0.5 \
        --layer l5.png:1.1:0.6

Performance Considerations¶

Animation Smoothness¶

Factors affecting smoothness: 1. Frame rate - Higher is smoother but uses more GPU 2. Layer count - More layers = more processing 3. Blur amount - Blur effects are computationally expensive 4. Image resolution - Higher resolution = more pixels to process

Optimization Tips¶

For smooth animations on lower-end systems:

# Reduce FPS
hyprlax --fps 30 wallpaper.jpg

# Avoid enabling vsync (default is off)

# Use simpler easing
hyprlax -e linear wallpaper.jpg

# Shorter duration
hyprlax -d 0.5 wallpaper.jpg

Troubleshooting Animation Issues¶

Stuttering¶

Lower FPS: --fps 30
Try toggling vsync: add or remove --vsync (default is off)
Use fewer layers
Reduce blur amounts

Tearing¶

Enable vsync: add --vsync
Match monitor refresh rate: --fps 60 (for 60Hz display)

Delayed Response¶

Global delay configuration is not available; reduce duration instead
Use shorter duration: -d 0.3
Try snappier easing: -e expo

Too Fast/Slow¶

Adjust duration: -d 1.5 (slower) or -d 0.5 (faster)
Change easing function for different feel
Modify shift amount: -s 250 (more dramatic)

Next Steps¶

See multi-layer guide for complex animations
Check examples for real-world configurations
Review troubleshooting for common issues