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:
| Bytes | Field |
|---|---|
| 0 | Version, 1 |
| 1 | Message type |
| 2–3 | Reserved, 0 |
| 4–7 | Payload 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
| Type | Direction | Payload |
|---|---|---|
10 subscribe | client → sweetbg | Empty |
11 output | sweetbg → client | revision, generation, fit, name_length, path_length, name, path |
12 done | sweetbg → client | revision |
13 claim | client → sweetbg | revision, name |
14 release | client → sweetbg | Name, or empty for all |
15 ack | sweetbg → client | revision, 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
12arrives. 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:
| Value | Fit |
|---|---|
0 | cover |
1 | contain |
2 | center |
3 | tile |
4 | span |
0xffffffff | Unsupported, 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
14for that output, or an empty14for 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.