Sweets

Subscription

Follow wallpaper changes and hand rendering to another program

For developers

This page is for people writing programs that integrate with sweetbg, such as custom wallpaper renderers. You don't need it to set or change wallpapers. See Commands instead.

Programs can subscribe to wallpaper changes over the control socket, $XDG_RUNTIME_DIR/sweetbg.sock. A renderer can also claim an output and draw its own background there. Normal sweetbg commands work as before.

The daemon never launches a renderer. To notice daemon starts and restarts, watch the socket for creation, replacement, and permission changes. Permissions are set once the listener is ready.

Framing

Every message has an 8-byte header, followed by the payload:

BytesField
0Version, 1
1Message type
2–3Reserved, 0
4–7Payload length, little-endian u32
  • Payloads are at most 4096 bytes.
  • All integers are little-endian u32.
  • Names and paths are raw bytes with no NUL terminator. Paths are absolute.

Messages

TypeDirectionPayload
10 subscribeclient → sweetbgEmpty
11 outputsweetbg → clientrevision, generation, fit, name_length, path_length, name, path
12 donesweetbg → clientrevision
13 claimclient → sweetbgrevision, name
14 releaseclient → sweetbgName, or empty for all
15 acksweetbg → clientrevision, accepted (0 or 1), name

Up to four subscriptions are accepted at once. No heartbeat or polling is needed.

Snapshots

After subscribing, sweetbg sends one 11 message per output, then a 12 message to finish the snapshot. It sends a new snapshot whenever the wallpaper state changes.

  • Stage outputs until 12 arrives. An output missing from the snapshot is gone.
  • A newer revision replaces an unfinished snapshot.
  • Revisions only mean something within one connection.
  • Intermediate snapshots may be skipped. No image data is sent.

fit values:

ValueFit
0cover
1contain
2center
3tile
4span
0xffffffffUnsupported, oversized, or blurred

An empty path means the output has no image.

Claiming an output

Prepare your buffer first, then send 13 with the current revision and the output name. Wait for the 15 ack before sending another claim.

An output can only be claimed when it shows a cover image, blur is 0, and the compositor supports viewporter. Stale or conflicting claims are rejected.

Once a claim is accepted, sweetbg replaces its wallpaper with a transparent 1×1 surface and frees the full-size buffer. Your program can then show its own background-layer surface. Wallpaper commands keep updating the assignment and sending snapshots.

Sweetbg takes the output back and redraws the latest wallpaper when:

  • you send 14 for that output, or an empty 14 for all outputs,
  • the connection closes,
  • the image is cleared, the fit changes to anything but cover, or blur is enabled.

An invalid message closes that subscription. Validate every field and bound your own queued work.

Socket IO is nonblocking, with fixed-size buffers per subscriber. A slow reader can't block wallpaper commands or the compositor.

On this page