Preview Screenshot

Render lockscreen preview PNG with custom time, weather, battery, and now-playing mock data

Use veila-curtain preview mode to render a lockscreen screenshot without actually locking your session

Preview mode follows the normal widget enabled state from your config by default. Weather stays hidden when [weather].enabled = false or when all three weather visual parts are disabled, unless you explicitly force preview weather with weather-specific preview flags such as --preview-weather-location, --preview-weather-temperature, or --preview-weather-condition.

Basic Usage

veila-curtain \
  --config="$HOME/.config/veila/config.toml" \
  --preview-png=/tmp/veila-preview.png \
  --preview-size=1920x1080

This renders the configured scene directly to a PNG. It does not need a real session lock, a running daemon, or a live MPRIS track

Both CLI styles work for value-taking flags:

--preview-png=/tmp/veila-preview.png
--preview-png /tmp/veila-preview.png

# same applies to other preview flags such as --preview-size, --preview-title, etc.

Preview Flags

Flag	What it does
`--config <path>`	Uses a specific Veila config file for the preview render
`--preview-png <path>`	Required for preview mode. Screenshot PNG path
`--preview-size <width>x<height>`	Sets the output image size, for example `1920x1080`
`--preview-time <HH:MM>`	Overrides the clock time in the screenshot
`--preview-username <text>`	Overrides the displayed username label
`--preview-weather-location <text>`	Overrides the displayed weather location label
`--preview-weather-condition <name>`	Overrides the weather icon. (`rain`, `snow`, `clear-day`, etc.)
`--preview-weather-temperature <celsius>`	Overrides the weather temperature in Celsius
`--preview-battery-percent <0-100>`	Overrides the battery percentage
`--preview-battery-charging <bool>`	Overrides the battery charging state with `true` or `false`
`--preview-title <text>`	Overrides the now playing track title
`--preview-artist <text>`	Overrides the now playing artist text
`--preview-artwork <path>`	Overrides the now playing artwork image
`--preview-hide-widgets`	Hides weather, battery, now playing and keyboard label together
`--preview-hide-weather`	Hides only the weather widget
`--preview-hide-battery`	Hides only the battery widget
`--preview-hide-now-playing`	Hides only the now playing widget
`--preview-hide-keyboard-label`	Hides only the sample keyboard layout label such as `EN`
`--force-emergency-ui`	Renders the built-in emergency unlock prompt instead of the configured scene

Hide Flag Behavior

--preview-hide-widgets is the blanket option
--preview-hide-weather, --preview-hide-battery, --preview-hide-now-playing, and --preview-hide-keyboard-label are narrower overrides
If --preview-hide-widgets is set, it wins over the per-widget hide flags

Grid

The preview grid draws a temporary alignment overlay on screenshot output. It is useful when tuning widget positions, backdrop sizes, and spacing because you can see exact pixel intervals without guessing from the finished image.

The grid is preview-only. It appears in preview PNG output and does not render on the live lockscreen.

[visuals.grid]
enabled = true
cell_size = 40
color = "#FFFFFF14"
major_every = 4
major_color = "#FFFFFF26"

Key	What it does	Default
`enabled`	Show or hide the grid overlay.	`false`
`cell_size`	Minor grid cell size in pixels.	`40`
`color`	Minor grid line color, including alpha.	`"#FFFFFF14"`
`major_every`	Draw a stronger line every N cells.	`4`
`major_color`	Major grid line color, including alpha.	`"#FFFFFF26"`

Examples

Clean Theme Showcase

Show the wallpaper, layer, typography, and input styling with no extra widgets:

veila-curtain \
  --config="$HOME/.config/veila/config.toml" \
  --preview-png=/tmp/veila-clean.png \
  --preview-size=1920x1080 \
  --preview-hide-widgets \
  --preview-time=08:54

Screenshot with mocked weather, battery, and now playing data:

veila-curtain \
  --config="$HOME/.config/veila/config.toml" \
  --preview-png=/tmp/veila-widgets.png \
  --preview-size=1920x1080 \
  --preview-time=21:54 \
  --preview-weather-location="Tokyo" \
  --preview-weather-condition=rain \
  --preview-weather-temperature=7 \
  --preview-battery-percent=84 \
  --preview-title="Born To Be Yours" \
  --preview-artist="Kygo, Imagine Dragons" \
  --preview-artwork="$HOME/Pictures/kygo.jpg"