THE PALACE FIELD GUIDE

Know your collection.
Know your engine.

Connect local files and optional endpoints, organize media, compose layers, and follow the path from a wallpaper slot to the platform renderer. Controls and output depend on the current platform capabilities.

01 · INSTALL

Your first launch, step by step.

Choose a platform. The package, first launch and final wallpaper action change together.

Windows macOS Linux Android iOS / iPadOS Web

02 · PERMISSIONS

Only the access you need.

File access, notifications and background behavior are separate choices. Start with the action you want to perform.

Windows macOS Linux Android iOS / iPadOS Web

Browse, organize and edit

Media

Categories

Nature

Art

Space

Find and organize media

Use the gallery search and filters, open a category to browse its members, and add chosen media to favorites or personal albums. Categories group media; albums are your personal collections; folders refer to device files. Two endpoints can have categories with the same name. Their endpoint labels identify which collection you are opening.

Wallpaper editor

Open an item to adjust composition and fit, background color, transforms and effects. Use the available layer tools for media, text, shapes and supported animated content. Save reusable compositions in the scenes/mosaic area. Preview the target layout before applying, particularly with multiple displays or different screen aspect ratios.

Image, GIF, video, shader and other media support depends on the renderer and device. A valid endpoint does not add a codec or renderer the platform lacks. Export controls show the formats available for the current composition.

Displays and targets

Select the display, space or mobile wallpaper target offered by your platform. Fit preserves the full image with space around it; fill may crop it. Use span only where the target configuration supports it.

Editor modes and layers

Layers

text

media

mirror

solid

Auto color

JPG

Make room
for inspiration.

Apply Home

Fill · Text layer 01 / 05

Layer

Center

Fit

Fill

Stretch

Tile

Edge clamp

Mirrored

Incoming

Feather 0.00

Scale 1.00

Blur 0.00

Darken 0.00

Saturation 1.00

Sliders 3D

Scale

Zoom 100.0%

Position

X 0px

Y 0px

Rotation

Roll (Z) 0°

1. Open a media item for Media mode, a timer’s editor for Timer mode, or a saved composition in Scene mode.
2. Use the left layer panel to add, select, reorder, hide, or lock layers. Primary and secondary selections give the foreground and background their own controls.
3. Choose Type and Source, then use the tabs available for that layer: Style, Transform, Effects, Color, or Text.
4. Set layer opacity and blending. Use global effects to finish the combined output.

Choose a layer for the job

Media contains images, GIFs, or video. Mirror links to another layer rather than importing a second copy. Solid supplies a color or shape; Text adds typography. Groups organize content and Scenes reuse compositions. Shader, web, particle, Lottie, widget, audio visualizer, and application layers depend on their renderer and platform capabilities.

Masks and live updates

Masks appear separately from visible layers. An effect can reference a mask to restrict where it applies; the mask itself is not painted as a visible layer.

Enable live updates in Editor settings. Edits are sent to selected applied slots that already contain the same media. Other slots keep their content. Native live engine updates are available on Android and desktop; iOS saves an image and Web previews or exports.

The layer vocabulary

Choose a content layer, then decide its fit and effects. Advanced layer types exist in the model; their runtime and output support varies.

Show modes, effects, and transitions

Layer

Center

Fit

Fill

Stretch

Tile

Edge clamp

Mirrored

Incoming

Feather 0.00

Scale 1.00

Center

Fit

Fill

Stretch

Tile

Edge Clamp

Mirror Fill

Center keeps the native image size. Fit preserves the whole image with room around it. Fill covers the frame and may crop. Stretch changes proportions. Tile repeats the image. Edge Clamp extends edge pixels, while Mirror Fill reflects them into the surround.

The scale and feather controls adjust tile size or the generated surround. Outpainting is an incoming placeholder, not a working AI generation feature.

Layer

Blur 12.00

Vignette 0.40

Selected layer

Transform moves, scales, rotates, and flips a layer. Effects include brightness, contrast, saturation, gamma, sharpness, hue, blur, darken, vignette, sepia, grayscale, invert, kaleidoscope, and noise. Appearance sets opacity and Normal, Additive, Multiply, or Screen blending. Use depth and motion controls where the active layer and renderer support them.

Crossfade Slide Blur

Choose Fade, Crossfade, Slide, Scale, Zoom, Rotate, Blur, Flip, or None. Set duration and easing in target configuration. Effect interpolation smooths supported effect changes. Supported space gesture feeds can drive progress; otherwise switches run with timed progress.

Location slots and target configuration

Media Location

Tap to choose one · Ctrl+click or long-press to pick several

All spaces

Space 1

Space 2

Space 3

Lock

All displays

Home

Display 2

Lock

All spaces Selected targets · Span off · Gyro off

1. Open the location sheet from the editor and choose Displays or Spaces. Pick a concrete destination or a group offered by your device.
2. Choose Span for a shared canvas across supported outputs, Parallax for viewport movement, or Gyro for sensor-driven movement where available.
3. Configure transition behavior and playback/performance options offered by the renderer, then apply to the selected destination.

Displays address physical screens. Spaces address virtual desktops or supported mobile launcher pages. Home and Lock are distinct destinations where native application is supported. All Displays and All Spaces expand into concrete destinations, including lock where applicable; they are selection groups rather than an extra independent screen.

Target configuration belongs to the destination, not the media’s show mode. Each slot keeps its own span, parallax, gyro, transition, and supported playback settings. Group toggles affect only compatible slots. Gyro also requires sensor availability. Mobile launcher spaces do not span; Home can support parallax while Lock does not.

Screensaver rendering is unfinished and gated by experimental and behavior settings. Its presence in a picker is not a guarantee of working output.

06 · PLATFORMS

One creative model.
Different system boundaries.

Media, layers and target configuration are shared concepts. The operating system decides how a finished scene can reach your screen.

Windows macOS Linux Android iOS / iPadOS Web

Native desktop window

Windows 10 / 11

C++ · OpenGL desktop renderer

A live desktop and the Windows lock screen are separate outputs. Do not expect the desktop’s animated scene to run on the OS lock screen.

Native desktop window

10.15 deployment target

Swift · Metal; static fallback where needed

macOS does not let the live desktop Metal window draw over the lock shield. Lock media is staged for a separate fallback; screensaver integration is experimental.

Desktop/compositor surface

x64 · desktop-dependent

C++ · OpenGL / EGL · X11 or layer-shell Wayland

Wayland support is compositor-dependent. A generic Wayland session is not a promise of live wallpaper support. The app falls back between available backends; some sessions still cannot host the surface.

Android WallpaperService

API 24 build minimum

Kotlin · OpenGL live-wallpaper service

Home parallax and launcher-page Spaces depend on the launcher. Mobile Spaces never span. A force-stopped app cannot be treated like an always-running service; reopen it and review battery settings if rotation stops.

Export to Photos

15.0 dependency baseline

Swift · image-save fallback

The native bridge saves an image to Photos. It cannot programmatically replace the system wallpaper; real-time native style updates are not implemented there. The desktop renderer’s feature set must not be implied for iOS.

Browser canvas / exported file

Modern browser · WebGL2

Dart / JS · WebGL2 export renderer

Public JSON and media must satisfy browser CORS and codec requirements. The browser renderer explicitly has no native wallpaper surface or workspace layout. Native timer defaults are not exposed as a system service.

07 · UNDER THE HOOD

Follow one wallpaper through Palace.

Select a stage. The visual follows the same chain used by the library, editor, slot manager and render pipeline.

Media

The island Collection: Nature · source: remote media

COLLECT

The library resolves a media source.

Categories, albums, local folders and remote URLs lead to a media item. Cached metadata is separate from downloaded media.

Render job

Media + Layer stack + Target config

Compositor → UNI → native renderer / export

Windows · OpenGL desktop

RENDER

The platform receives a render job.

The compositor combines media, style and target configuration. UNI carries native commands; each platform supplies its own renderer or export fallback.

Add and manage endpoints

An endpoint is a public JSON index named sources.json. It lists categories, each referencing one or more JSON media lists. The actual media is hosted online.

1. Open Settings → Sources → the source manager.
2. Add the full endpoint URL, including its path and any required query string. A display name is optional.
3. Use Test to validate the endpoint and Refresh/Sync to load its categories.
4. Open the category bearing that endpoint’s label.

Palace fetches only configured endpoints and the files they reference. The words “live” and “review” in an endpoint’s name or URL have no special meaning. Add both URLs explicitly if you want both collections.

Refresh and offline behavior

Refresh reads the latest index and media files. Large collections load in chunks. The previous complete category remains available if a replacement fails. A deliberately empty category removes remote membership; a broken request does not.

Disable an endpoint to hide its categories without making it a fallback. Remove it to detach its remote categories. Personal collections and copies remain yours. Refresh failures, advertised media counts and loaded counts describe different things; inspect the error before treating a category as empty.

Endpoint format

{
  "schemaVersion": 1,
  "name": "My collection",
  "categories": [
    {
      "id": "nature",
      "name": "Nature",
      "files": [
        {
          "url": "categories/nature.json"
        }
      ]
    }
  ]
}

Keep category IDs stable when renaming categories. Relative file URLs resolve beside the containing JSON document, and media may live on a different host. Counts and SHA-256 checksums are optional for hand-written files.

Your media and existing exports

Create and import collections

Use Sources → Add Category to create a category, import a category file or add a category URL. Add online media URLs or local media using the existing collection controls. Edit mode exposes import/export actions where available.

Export a category

Use a category’s Export action, or export all categories. The export contains category information and selected media. It is a portable editing/backup document; to host it, take each category’s items array as its media JSON file and create a separate sources.json index.

An export does not upload local files. Replace local paths with public media URLs after uploading those files yourself. Existing online URLs may be reused while they remain publicly accessible. Never publish internal cache files as your collection.

Backups and recovered collections

Use profile and collection exports before changing devices or clearing app data. During the endpoint migration, older categories whose ownership cannot be established are preserved as recovered local collections. Review those copies, keep personal media, and add any desired endpoint explicitly.

Timers and automation

1. Open the Time/Timer area and choose the categories, albums or folders to rotate.
2. Set the interval and ordering. Use sequential order for a playlist or shuffle for variety.
3. Choose the target displays/spaces available on your device.
4. Configure time/day rules or device triggers where offered, then start the timer.

Pause, resume, skip and stop act on the selected timer session. Check permissions and background/battery settings if mobile rotation stops. Desktop background behavior and full-screen handling depend on the configured options; do not assume video playback always pauses automatically.

Settings, storage and performance

Appearance controls theme, scale and gallery presentation. Navigation controls the layout and navigation style. Behavior controls available startup and background integrations. Sources manages endpoints, local data and profile import/export. Timer and Editor configure their respective workflows. About contains version and support information.

Preview quality, animation behavior and caching affect bandwidth, memory and battery use. Use lower preview settings for large collections or constrained devices. Clearing downloaded media or caches can require fetching files again; export personal collections before resetting app data.

Folder paths belong to the current device. Reconnect moved folders and confirm file permissions after importing a profile on another platform.

Host and share your collection

1. Upload media
   Your chosen host
2. Category JSON
   Public media URLs
3. sources.json
   Category file URLs
4. Host and share
   One endpoint URL
5. Palace
   Read and display

1. Put the media on the internet

Use your preferred host outside Palace. Each URL must return usable media without login, not a sharing page. Prefer stable HTTPS URLs. Avoid expiring download links. The URL does not have to end in a file extension if the server returns the correct media.

2. Create a category JSON file

Save a media array as categories/nature.json:

[
  {
    "url": "https://images.unsplash.com/photo-1441974231531-c6227db76b6e",
    "type": "image",
    "description": "Forest",
    "tags": [
      "forest"
    ]
  }
]

3. Create sources.json

Use the index in the Understanding Sources section. Reference your category file. Add more categories with distinct IDs; split large categories into several files listed in order.

Download index example · Download media example · Multiple categories/chunks · Index schema · Media schema

GitHub recipe

1. Create a public repository and add your JSON files, preserving the directory layout.
2. For modest media collections, add media files too; otherwise keep large media on an independent host and use absolute URLs.
3. Open sources.json, choose Raw, and copy the complete raw URL. Alternatively enable GitHub Pages and use the published project path.
4. Open the endpoint URL in a private browser window. Follow every file reference and check that each returns JSON rather than a GitHub HTML page.
5. Add that URL in Palace and refresh.

GitHub is not unlimited media storage. Check GitHub Pages limits before choosing it for a large/video-heavy collection. Git LFS pointer files are not playable media URLs.

Object storage recipe: R2 or S3-compatible hosting

1. Create storage with your provider, upload media and JSON, and configure public delivery through the provider’s supported URL/CDN settings.
2. Use HTTPS and correct content types: JSON for indexes, and the appropriate image/video type for media.
3. Configure CORS for Palace Web’s origin, or public anonymous access where appropriate. JSON, media and redirect destinations must all be accessible.
4. For videos, verify that the public delivery endpoint supports byte-range requests.
5. Paste the publicly served sources.json URL into Palace. Do not paste a storage console URL or provider credentials.

See R2 public buckets, R2 CORS, and S3 CORS. R2 development URLs have limits; use the documented production delivery setup for shared collections.

Update safely

Keep category IDs stable. Upload new media and category files first, then replace sources.json last. Prefer new filenames for changed files; retain old files while readers may still use the old index. If you provide a SHA-256 checksum, calculate it from the exact uploaded UTF-8 bytes. Refresh Palace to load the update.

Nested and shared collections

A category can contain its own media and child collections. Add parentIds containing the stable IDs of its parents. Multiple parents place the same collection in several locations. Distinct collections may use the same name: Art → Cars can contain illustrations while Subject → Cars contains photography. Parent links must reference categories in the same endpoint and must not form cycles.

{
  "schemaVersion": 1,
  "categories": [
    {"id": "art", "name": "Art", "kind": "group", "files": []},
    {"id": "car-art", "name": "Cars", "parentIds": ["art"], "files": [{"url": "car-art.json"}]}
  ]
}

Groups can have no direct media files. Their children hold the media. Existing flat endpoints continue to work. Try the nested example.

Browse collections in the media grid

Collection pages show child cards alongside direct media. Appearance → Collection contents can also include descendant media. The source selector expands collections and selects subtrees. A shared collection uses one identity, so overlapping selections do not duplicate its media.

The shuffled main grid samples collection cards from all hierarchy levels. Appearance controls their frequency. Ordered main grids show media; ordered collection pages show child cards first. Collection cards fit mosaic, staggered and regular layouts.

Local folder trees

Adding a folder indexes its accessible subfolders and direct media. Native directory grants and browser directory handles allow rescanning. Where directory handles are unavailable, directory import preserves relative paths and stores a local snapshot; re-import it to pick up filesystem changes. Empty folders can only be discovered when the browser exposes directory entries. Folder originals are stored separately from the thumbnail cache.

New sources start displaying validated media during sync. Existing source updates keep their previous media until validation completes. You can keep browsing while sync and metadata work run in the background.

Customize category cards

Endpoint names appear in Manage Sources. To style category cards, add categoryDefaults to sources.json. Each category can override fields using presentation.

"categoryDefaults": {"labelMode": "name", "badge": "★"}

"presentation": {"labelMode": "symbol", "symbol": "✦", "badge": "", "color": "#ffffff"}

labelMode can be name, symbol, or none. Thumbnail-only mode (none) removes the label and its shadow. An empty badge removes the corner marker. Omitted fields inherit the endpoint defaults. Optional font and color customize the label. Sync or refresh anywhere in Palace applies new categories, media, and appearance automatically; appearance edits reuse already-loaded media.

AI-agent prompt templates

Copy a template into your preferred AI coding agent. Replace bracketed inputs. The agent operates outside Palace and uses your chosen hosting provider.

Generate from media URLs

You are helping me create a public Palace endpoint outside the Palace app. Use schemaVersion 1. sources.json has name and categories; each category has stable id, name and files:[{url}]. Each referenced media file is a JSON array of {url,type,description,tags}. Optional file sha256 is the SHA-256 of the exact file bytes; do not invent hashes. URLs may be relative to their containing document. Do not use category names, live/review paths or item metadata to infer ownership. Media must be public without login. Do not invent or claim to verify URLs you did not fetch. Never put credentials in JSON. Return the exact file tree, complete JSON files, upload/update instructions, verification results and the full endpoint URL. Keep existing category IDs unchanged during updates.

My collection name: [NAME]. Public media URLs and intended categories: [URLS]. Group these URLs as requested and produce a small, valid endpoint.

Convert a Palace export

You are helping me create a public Palace endpoint outside the Palace app. Use schemaVersion 1. sources.json has name and categories; each category has stable id, name and files:[{url}]. Each referenced media file is a JSON array of {url,type,description,tags}. Optional file sha256 is the SHA-256 of the exact file bytes; do not invent hashes. URLs may be relative to their containing document. Do not use category names, live/review paths or item metadata to infer ownership. Media must be public without login. Do not invent or claim to verify URLs you did not fetch. Never put credentials in JSON. Return the exact file tree, complete JSON files, upload/update instructions, verification results and the full endpoint URL. Keep existing category IDs unchanged during updates.

My existing Palace export: [EXPORT]. Convert its category items into media arrays and a sources.json index. List all local paths separately for me to upload, and wait for public URL replacements before claiming the endpoint is ready.

Host on GitHub

You are helping me create a public Palace endpoint outside the Palace app. Use schemaVersion 1. sources.json has name and categories; each category has stable id, name and files:[{url}]. Each referenced media file is a JSON array of {url,type,description,tags}. Optional file sha256 is the SHA-256 of the exact file bytes; do not invent hashes. URLs may be relative to their containing document. Do not use category names, live/review paths or item metadata to infer ownership. Media must be public without login. Do not invent or claim to verify URLs you did not fetch. Never put credentials in JSON. Return the exact file tree, complete JSON files, upload/update instructions, verification results and the full endpoint URL. Keep existing category IDs unchanged during updates.

My repository: [OWNER/REPO], branch: [BRANCH], directory: [PATH]. My media URLs/export: [INPUT]. Prepare the files and a GitHub Raw or Pages hosting walkthrough. Check current provider limits. If using connected tools to publish, show the concrete files and obtain any required publication authorization first.

Host on object storage

You are helping me create a public Palace endpoint outside the Palace app. Use schemaVersion 1. sources.json has name and categories; each category has stable id, name and files:[{url}]. Each referenced media file is a JSON array of {url,type,description,tags}. Optional file sha256 is the SHA-256 of the exact file bytes; do not invent hashes. URLs may be relative to their containing document. Do not use category names, live/review paths or item metadata to infer ownership. Media must be public without login. Do not invent or claim to verify URLs you did not fetch. Never put credentials in JSON. Return the exact file tree, complete JSON files, upload/update instructions, verification results and the full endpoint URL. Keep existing category IDs unchanged during updates.

Provider: [PROVIDER]. Public base URL: [PUBLIC_URL]. Collection: [INPUT]. Prepare upload paths, content types, public delivery/CORS instructions and a sources.json URL. Account setup and credentials belong outside Palace. Confirm browser and video range access where relevant.

Update a collection

You are helping me create a public Palace endpoint outside the Palace app. Use schemaVersion 1. sources.json has name and categories; each category has stable id, name and files:[{url}]. Each referenced media file is a JSON array of {url,type,description,tags}. Optional file sha256 is the SHA-256 of the exact file bytes; do not invent hashes. URLs may be relative to their containing document. Do not use category names, live/review paths or item metadata to infer ownership. Media must be public without login. Do not invent or claim to verify URLs you did not fetch. Never put credentials in JSON. Return the exact file tree, complete JSON files, upload/update instructions, verification results and the full endpoint URL. Keep existing category IDs unchanged during updates.

Existing endpoint/files: [INPUT]. Add/remove/rename instructions: [CHANGES]. Preserve IDs, write changed media files first and the manifest last. Explain cache behavior and retain a rollback copy.

Diagnose loading

You are helping me create a public Palace endpoint outside the Palace app. Use schemaVersion 1. sources.json has name and categories; each category has stable id, name and files:[{url}]. Each referenced media file is a JSON array of {url,type,description,tags}. Optional file sha256 is the SHA-256 of the exact file bytes; do not invent hashes. URLs may be relative to their containing document. Do not use category names, live/review paths or item metadata to infer ownership. Media must be public without login. Do not invent or claim to verify URLs you did not fetch. Never put credentials in JSON. Return the exact file tree, complete JSON files, upload/update instructions, verification results and the full endpoint URL. Keep existing category IDs unchanged during updates.

Endpoint: [URL]. Platform: [PLATFORM]. Symptom/error: [ERROR]. Inspect the index, every referenced JSON file, hashes/counts if supplied, media responses, redirects and browser CORS. Report the exact failing URL and concrete fix. Distinguish unavailable media from missing category membership.

Share an endpoint

Share the complete public sources.json URL with another person. They add it in their own Palace source manager. You can also publish the link on your website or repository.

Adding a source in Palace does not automatically submit it to a community service. A host account belongs to the hosting provider, not to the endpoint reader. Anyone with a public endpoint link can read its public media.

Troubleshooting and FAQ

No categories appear

Test the complete endpoint URL. It must return schemaVersion 1 JSON with a categories array. An HTML page, login page, older format or bad redirect is an error. Confirm the source is enabled and refresh it.

The wrong collection appears

Check the category’s source in Manage Sources. Cards can use a symbol badge supplied by the endpoint. Identical names from different endpoints are separate. Remove an unwanted endpoint in the source manager; Palace does not infer a review endpoint from a live URL.

Some media is missing

Check refresh errors and loaded counts, then inspect every file reference. A missing or invalid chunk leaves the previous complete category available. An inaccessible media URL may be listed correctly but fail to display. Test the URL without logging in.

It works on desktop but not in the browser

Check HTTPS, cross-origin access and redirects for JSON and media. Browser developer tools can reveal CORS failures. Supported codecs and local-folder access differ by platform.

Updates do not appear

Refresh explicitly. Check that you changed the published branch/path, uploaded dependent files before the index, updated supplied checksums, and that a CDN is not serving an older file.

Video or animation fails

Try the media URL directly, verify content type and byte-range support, and check platform codec/renderer availability. A link to a web player is not a direct video file.

Do I need an account?

No account is required to read a public endpoint. You manage hosting accounts independently if you want to publish a collection.

Where can I get help?

Include the Palace version, platform, endpoint URL if public, exact error and reproduction steps. Do not share private files or hosting credentials. Use the support links in About or the website footer.