Skip to content
Wallpaper Server Wallpaper Server Docs

Web Gallery

Wallpaper Server serves a browser interface from the same process and embedded assets as the API. The gallery uses the same index, filters and deterministic sorting as GET /api/wallpapers, so browser and automation results stay consistent.

Opening the interface

Section titled “Opening the interface”
http://localhost:8519/

The operational server overview lives at /server, and editable configuration lives at /settings.

Section titled “What the gallery does”
  • Search filenames and indexed metadata such as format, dimensions, brightness, orientation, aspect ratio and dominant colour. Space-separated terms combine with AND semantics.
  • Filter by brightness, orientation, aspect ratio, dominant colour, format and optional minimum/maximum dimensions.
  • Sort by date added, filename, file size, resolution or brightness in either direction.
  • Paginate predictably with first/last, neighbouring page links and a selectable page size. Search, filters, sorting and page state are reflected in the URL, so browser back/forward and copied links work as expected.
  • Preview and inspect a wallpaper without leaving the current result page, then download the original or open it full size.
  • Upload one or several images with drag-and-drop validation and progress feedback (see Uploading and managing).
  • Delete a wallpaper behind a keyboard-accessible confirmation dialog.
  • Use it on mobile through the responsive filter drawer and compact controls.

Thumbnails use native lazy loading, and the interface supports light/dark appearance, visible keyboard focus and reduced-motion preferences.

Search and filter behaviour

Section titled “Search and filter behaviour”

Every search term and explicit filter must match the same wallpaper. For example, dark landscape png finds PNG files whose indexed metadata also says dark and landscape. jpg and jpeg are aliases, and blue also matches the classifier’s broader cool colour category.

Changing a search, filter, sort or page-size control refreshes only the result region. The full-page URL is still updated to a canonical gallery URL, rather than exposing the internal /fragments/gallery endpoint in browser history.

Server overview

Section titled “Server overview”

Open /server to see the running version, uptime, platform, process ID, listen address, wallpaper count and source-size total, library composition, configured folders, storage paths and accepted extensions. The page also provides a manual index refresh action and links to settings and the API description.

Empty and stale states

Section titled “Empty and stale states”
  • If no wallpaper matches every active condition, clear an active filter or use a broader search.
  • If the configured folders contain no supported images, upload a wallpaper or add files on disk and refresh the index.
  • Files added directly to a wallpaper folder are visible after POST /api/refresh, the WebUI Refresh index action, or a server restart.
Section titled “Related”