Kwiq Live Wallpaper

Activation

Kwiq's Live Wallpaper can be activated in two ways:

1. From the Android wallpaper picker: go to Settings > Wallpaper > Live Wallpapers and choose "Kwiq Live Wallpaper".
2. From Kwiq's settings hub: open Kwiq Settings, go to "Wallpaper", and tap "Activate Live Wallpaper".

Once activated, you can configure each slot individually, choose images from the gallery or online providers, and adjust the slideshow and overlay settings.

The 4 Slots

Kwiq has 4 wallpaper slots that adapt to the device context:

Kwiq automatically selects the right slot based on the theme (light/dark) and the device orientation (portrait/landscape).

Smart fallback: if a slot is empty, the system tries, in this order:

1. Same theme, opposite orientation
2. Opposite theme, same orientation
3. Opposite theme, opposite orientation

This guarantees there is never a blank wallpaper, even if you have only configured a single slot.

Slideshow

Each slot can hold multiple images that form a looping slideshow. Key features:

• Per-image timing: each wallpaper can have its own display duration, from 5 seconds to 1 hour, set per wallpaper.
• Transition: a smooth 220ms crossfade between images.
• Manual advance: at any time, you can manually skip to the next image from the wallpaper shortcut in the Quick Tools.
• Automatic loop: the slideshow loops forever, restarting from the beginning when it reaches the end.

Image Providers

Kwiq offers 12 sources to fetch wallpapers directly from the app. Anime-focused providers (Waifu.im and Safebooru, plus Wallhaven with its Anime category) are grouped under an expandable "Anime" submenu for quicker access. Each provider has its own filter options:

Anime-focused providers (Waifu.im, Safebooru, and a Wallhaven shortcut pre-set to the Anime category) are grouped under an expandable Anime submenu in the provider selector for quick access.

API Keys

Unsplash, Pixabay, and Pexels require you to create an account and get your own API keys. Here is how to get each one:

Unsplash

1. Go to https://unsplash.com/developers
2. Create an account or log in to Unsplash.
3. Register an application under "Your Apps" > "New Application".
4. Copy the generated "Access Key".
5. Paste it into Kwiq Settings > "API Keys" > "Unsplash".

Pixabay

1. Go to https://pixabay.com/api/docs/
2. Create an account or log in to Pixabay.
3. Copy your API key from "API Key" on the documentation page.
4. Paste it into Kwiq Settings > "API Keys" > "Pixabay".

Pexels

1. Go to https://www.pexels.com/api/
2. Create an account or log in to Pexels.
3. Request a free API key.
4. Copy the provided key.
5. Paste it into Kwiq Settings > "API Keys" > "Pexels".

Wallhaven and Waifu.im do not require an API key, but offer advanced filters like category, purity (SFW/Sketchy/NSFW), sorting, and NSFW mode. The remaining providers (Safebooru, Wikimedia Commons, Openverse, Picsum Photos, LoremFlickr) are also free and keyless.

Battery Liquid Indicator

Turn the Live Wallpaper lock screen into a subtle, elegant battery gauge:

• Activation: in Kwiq Settings > Wallpaper > "Battery Liquid".
• Fill type: opaque or transparent.

Dynamic colors: the liquid color changes with the battery level:

• Red: ≤ 5%
• Orange: ≤ 10%
• Yellow: ≤ 20%
• Blue: while charging

• Caffeine effect: when Caffeine is active, "steam" waves appear over the liquid (available colors: Coffee, CoffeeMilk, Milk, or the accent color).
• Bubbles: appear while the device is charging.

Preset System

Presets let you save and restore complete wallpaper setups: all 4 slots with their images, per-wallpaper settings, and crop preferences.

Folder structure:

Available operations:

1. Save preset: copies the wallpapers from the active slots into the preset directory.
2. Apply preset: copies the preset files into the active slots, preserving all per-wallpaper settings.
3. Save current as preset: same logic as Save, but marks the preset as active.
4. Rename / Delete: manage existing presets.
5. Export as ZIP: packages the whole preset for sharing.
6. Import from ZIP: restores a preset from a ZIP file.
7. Share: sends the preset via Bluetooth, email, etc.

The active preset is tracked automatically: applying a preset makes it the "active" one. You can see which preset is active in the wallpaper settings.

Wallpaper Metadata

Every wallpaper has its own settings: sequence position, overlay opacity, display duration, pan offset, and zoom level — so each image remembers its configuration for the slideshow.

Static Wallpaper

Kwiq also offers a traditional static wallpaper picker for anyone who prefers not to use the Live Wallpaper:

• Access: from the Kwiq wallpaper hub (Settings > Wallpaper > "Choose Static").
• Targets: Home screen, Lock screen, or both.
• Adjustments: crop, zoom, and pan (drag) to position the image perfectly before applying.
• Sources: the device gallery or any configured online provider.

Backup and Restore

Wallpaper settings are included in Kwiq's backup system:

• What is saved: wallpaper presets and battery liquid preferences.
• What is NOT saved: the images themselves (they are already in the Kwiq/Wallpapers/ folder in storage and remain visible to the user).
• Format: a .kwiqbkp file.
• Restore: importing a backup automatically restores presets and settings.

Web Wallpaper

Kwiq supports web wallpapers — animated themes made with HTML, CSS and JavaScript, in the style of Wallpaper Engine for desktop. They run in the background using an invisible WebView and can react to audio, touch and custom settings.

How to import

1. Package your files (index.html + assets) into a .zip file.
2. In the app, open the wallpaper panel and tap "Import Web Wallpaper (ZIP)".
3. Select the ZIP file — Kwiq extracts and registers it automatically.
4. Assign the web wallpaper to a slot in the wallpaper settings.

You can also import via MCP (web_wallpaper_import) or the Kwiq Dashboard (POST /api/web-wallpapers/import).

Custom properties

Web wallpapers can expose controls that appear in the Kwiq interface as sliders, colors, buttons and selectors. Simply register the properties via window.wallpaperRegisterProperties() in JavaScript and include the properties section in project.json.

Audio reaction (FFT)

Kwiq captures the device audio spectrum (32 FFT bins) and makes it available to the web wallpaper via window.wallpaperRegisterAudioListener(). Use the data to create visualizations, reactive waves, pulses and any effect synchronized with music or surrounding sounds.

Available JavaScript APIs

• window.wallpaperRegisterProperties(properties[]) — registers custom properties
• window.wallpaperPropertyListener — object to receive property changes
• window.wallpaperRegisterAudioListener(callback) — receives real-time 32-bin FFT array
• window.wallpaperRegisterPauseListener(callback) — notifies when the wallpaper enters/exits pause

File structure

The wallpaper is stored in Kwiq/Wallpapers/{name}/ with the following structure:

Kwiq/Wallpapers/MyWallpaper/
  index.html      (required)
  project.json    (Wallpaper Engine manifest — optional)
  web.json        (Kwiq manifest — auto-generated)
  assets/         (auxiliary files — CSS, JS, images)

Management

• List: wallpaper panel, MCP (web_wallpaper_list) or Dashboard
• Assign to slot: MCP (web_wallpaper_assign) or Dashboard
• Remove: MCP (web_wallpaper_delete) or Dashboard — removes from all slots and deletes the files