XSOverlay compatibility

AstralOverlay accepts XSOverlay-style notification messages over WebSocket and legacy UDP. This is notification compatibility, not an implementation of XSOverlay’s complete API.

Supported entry points

• WebSocket on localhost port 42070, with a required client query parameter.
• The SendNotification command and string-valued jsonData.
• Legacy UDP payloads on localhost port 42069.
• Shared notification text, source, timeout, opacity, and volume fields.

Limits

• Other WebSocket commands are silently ignored. Do not rely on window, theme, or status commands.
• Notifications share a single bounded queue, regardless of index.
• Card dimensions are based on content rather than a sender’s requested height.
• The current WebSocket receive loop processes text frames and close frames; it does not provide a general-purpose WebSocket service. Protocol keepalive and fragmented-message support should be verified for your client before long-running use.
• The parser accepts audioPath, icon, and useBase64Icon, but the current renderer does not load custom notification icons or audio files. It uses its own card presentation and bundled sound. Per-message volume is parsed; current playback uses the global notification-volume setting.

Running alongside XSOverlay

Both apps use the same default notification ports. If another app already occupies a port, AstralOverlay logs a warning and cannot listen on that port. The other transport can remain available if its own port is free. There is no automatic forwarding between the two apps.

Test integrations against the AstralOverlay release you intend to support.