wl-overlay

name: wl-overlay description: | Fullscreen Wayland overlays for screen recordings via gtk4-layer-shell. MUST be invoked before any work involving: charly check wl overlay commands, recording overlays, title cards, lower-thirds, countdowns, or fade transitions.

WL Overlay -- Wayland Desktop Overlays for Recording

Overview

charly check wl overlay creates and manages fullscreen Wayland overlays using the layer-shell protocol via gtk4-layer-shell. Overlays render directly in the compositor, appearing natively in screen recordings without post-production editing. Supports true alpha transparency — desktop content is visible through semi-transparent overlays.

Architecture

Three components work together:

1. wl-overlay layer — installs gtk4-layer-shell, gtk4, python3-gobject RPMs + charly-overlay Python daemon/client
2. charly check wl overlay Go commands — CLI that resolves the container and invokes charly-overlay inside it
3. charly-overlay daemon — GTK4 application managing multiple named overlay windows via Unix socket IPC

The daemon starts on-demand in a tmux session (charly-overlay-daemon) when the first show command is issued. It persists until hide --all or the tmux session is killed.

Quick Reference

Overlay Types

Text (Title Card)

Full-screen semi-transparent overlay with centered text. Use for intro/outro title cards.

charly check wl overlay show myimage --type text \
  --text "Building a REST API" \
  --bg "rgba(0,0,0,0.7)" \
  --font-size 64 --name title

Lower-Third

Bottom-anchored bar with name and optional subtitle. Use for speaker identification.

charly check wl overlay show myimage --type lower-third \
  --text "Andreas Trawoeger" \
  --subtitle "Developer" --name speaker

Watermark

Corner-anchored persistent text at low opacity. Use for draft/preview markers.

charly check wl overlay show myimage --type watermark \
  --text "DRAFT" --position bottom-right \
  --color red --opacity 0.5 --name wm

Default opacity is 0.3. Positions: top-left, top-right, bottom-left, bottom-right, top, bottom.

Countdown

Full-screen animated countdown that auto-hides on completion. Use before recording starts.

charly check wl overlay show myimage --type countdown --seconds 5 --name cd

Highlight

Transparent overlay with a colored rectangle at specified coordinates. Use to draw attention to a screen region.

charly check wl overlay show myimage --type highlight \
  --region "430,290,510,50" \
  --color "rgba(255,0,0,0.4)" --name hl

Region format: X,Y,Width,Height in pixels.

Fade

Full-screen solid color overlay. Use for transitions (fade to black, fade to white).

charly check wl overlay show myimage --type fade --color black --name outro

Duration Auto-Hide

Any overlay (except countdown, which has built-in auto-hide) can auto-remove after a duration:

charly check wl overlay show myimage --type text --text "INTRO" --duration 5s --name intro

Supported formats: 5s, 1.5m, 500ms, or bare seconds (5).

Recording Workflow

Overlays compose naturally with charly check record:

# Title card
charly check wl overlay show myimage --type text --text "Building a REST API" \
  --bg "rgba(0,0,0,0.9)" --font-size 64 --name title

# Start recording
charly check record start myimage -n demo -m desktop

# Fade out title after 3s
sleep 3
charly check wl overlay hide myimage --name title

# Lower-third speaker ID
charly check wl overlay show myimage --type lower-third \
  --text "Andreas Trawoeger" --subtitle "Developer" --name speaker

# ... record content ...

# Fade to black for ending
charly check wl overlay show myimage --type fade --color black --name outro
sleep 2

# Stop recording
charly check record stop myimage -n demo -o demo.mp4
charly check wl overlay hide myimage --all

Compositor Compatibility

All overlay types work on all wlroots-based compositors:

Key Technical Details

• True RGBA transparency: enabled by window { background: none; } CSS at daemon startup. Without this, GTK4 on Wayland creates opaque surfaces
• Cairo-drawn backgrounds: backgrounds are painted via Gtk.DrawingArea + Cairo, not CSS. GTK4 CSS background-color with rgba() does not composite correctly on layer-shell windows
• Layer: uses Gtk4LayerShell.Layer.OVERLAY (highest z-order, above waybar/swaync)
• Keyboard: KeyboardMode.NONE — overlays never capture input
• Exclusive zone: -1 — overlays don't push other windows
• Python interpreter: uses /usr/bin/python3 (system Python with PyGObject), not pixi's Python

Selkies-Desktop Capture Latency

On selkies-desktop, pixelflux-screenshot captures from the H.264 WebSocket stream. In controller mode (no browser client connected), the frame rate is very low — screenshots may take 15-30 seconds to reflect overlay changes. This does NOT affect recordings — charly check record captures at 30fps, so overlays appear immediately in recorded video.

IPC Protocol

Socket: /tmp/charly-overlay.sock (Unix domain, JSON-line)

{"action":"show","type":"text","text":"Hello","name":"intro","bg":"rgba(0,0,0,0.7)"}
{"action":"hide","name":"intro"}
{"action":"hide_all"}
{"action":"list"}
{"action":"status"}

Show Command Flags

Requirements

• Container must include wl-overlay layer (gtk4-layer-shell + python3-gobject)
• Container must have a running Wayland compositor (sway, labwc)
• Container must have tmux layer (for daemon hosting)
• Included in sway-desktop and selkies-desktop metalayers

Cross-References

• /charly-check:wl — Compositor-agnostic desktop automation (screenshots, input, windows)
• /charly-check:record — Terminal and desktop recording (overlays compose with recording workflow)
• /charly-check:cdp — Chrome DevTools Protocol (DOM-level interaction)
• /charly-selkies:wl-overlay-layer — Layer reference (RPM packages, dependencies)
• /charly-selkies:sway-desktop — Desktop metalayer (includes wl-overlay)
• /charly-selkies:selkies-desktop-layer — Desktop metalayer (includes wl-overlay)

Source: charly/wl_overlay.go (Go commands), candy/wl-overlay/charly-overlay (Python daemon/client).