---
url: https://live777.pages.dev/guide/wayland.md
---
# Wayland Compositor Source

live777 can act as a **headless Wayland display server**: ordinary GUI
applications render into it, and the composited desktop is H.264-encoded and
published as a WebRTC stream. No physical display, GPU, or X11/Wayland session
is required.

This is a stream *source*: build live777 with the `source-wayland` feature
(Linux only, not part of `source-all`) and give a stream a `wayland://` URL:

```bash
cargo build --release --bin live777 --features source-wayland
```

Linking needs the `libxkbcommon` shared library (e.g. `libxkbcommon-dev` on
Debian/Ubuntu); no other system dependencies.

## Configuration

```toml
# The stream is provisioned: it exists at startup and appears in the
# API/Dashboard even before any application connects.
[stream.desktop]
[[stream.desktop.sources]]
# wayland://<socket-name>?width=&height=&fps=&bitrate=&xwayland=&xdisplay=
# All parameters are optional (defaults: socket live777-desktop,
# 1280x720@30, 2 Mbps, xwayland=1, xdisplay auto-assigned).
url = "wayland://desktop-0?width=1920&height=1080&fps=30&bitrate=4000000"
```

The compositor creates the Wayland socket `$XDG_RUNTIME_DIR/desktop-0` at
startup, so **`XDG_RUNTIME_DIR` must be set** when live777 starts. Point any
Wayland application at the display by name:

```bash
export XDG_RUNTIME_DIR=/run/user/$(id -u)
live777 &                                  # serves the stream
WAYLAND_DISPLAY=desktop-0 my-application   # renders into the stream
```

Subscribers watch the stream like any other: `http://localhost:7777/` in a
browser, or any WHEP player. Until the first application connects, the stream
carries a moving test pattern, so the publish is alive immediately and
subscribing never has to wait for a client.

## X11 applications (XWayland)

X11 applications work too: with `xwayland=1` (the default) the compositor
spawns an **XWayland** server and acts as its X11 window manager. This needs
an `Xwayland` binary on `PATH` (e.g. the `xwayland`/`xorg-xwayland` package);
without one, X11 support is skipped with a warning and native Wayland clients
keep working.

The display number is picked automatically and logged at startup
(`XWayland ready, X11 clients use DISPLAY=:N`); pin it with `xdisplay=`:

```toml
url = "wayland://desktop-0?xdisplay=0"
```

```bash
DISPLAY=:0 xterm &      # renders into the same stream as Wayland clients
```

Window management is deliberately minimal — this is a virtual monitor, not a
desktop: windows keep the geometry they ask for (there is no pointer input to
move or resize them), fullscreen/maximize requests map to the full canvas, and
the last mapped window paints on top. X11 and Wayland clients can be mixed on
one stream; X11 windows paint above xdg toplevels, and override-redirect
windows (menus, tooltips) on top of everything.

X11 sockets live in `/tmp/.X11-unix/` (created if missing). To reach X11
clients inside a container, bind-mount it through (or share the network
namespace for the abstract socket):

```bash
docker run -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=:0 ...
```

Set `LIVE777_WAYLAND_XWAYLAND_LOG=1` to inherit XWayland's stderr instead of
discarding it (useful when an X11 client stays black).

## Remote input (keyboard & mouse)

With `input=1` on the wayland URL, viewers can drive the desktop: the browser
player sends JSON events over an `input` datachannel cable, and the
compositor injects them into the seat — pointer moves/buttons with hit-tested
focus, keys to the last-clicked window, wheel as wl\_pointer axis frames.

```toml
url = "wayland://desktop-0?input=1"
```

Watch and control in a browser with the standalone player
(`http://localhost:7777/tools/player.html?id=desktop-0&input`) — click the
video once to give it keyboard focus, then type and click as usual. Any WHEP
client can do the same with a datachannel labeled `input`; see
`web/player-core/input-capture.ts` for the wire format
(`{"t":"key"|"move"|"button"|"wheel", ...}`).

**Security**: off by default. When enabled, *every* subscriber of the stream
can control the desktop — combine with auth tokens and only enable where
remote control is intended.

## Desktop audio

With `audio=1` (the default) the stream also carries the desktop's sound:
live777 connects to **PipeWire** (the daemon socket at
`$XDG_RUNTIME_DIR/pipewire-0`), taps the monitor of an `Audio/Sink` node and
publishes it as an Opus track (48 kHz stereo, `audio_bitrate=` in bps,
default 64000). If no PipeWire daemon is reachable the stream stays
video-only with a warning.

In a headless container there is no audio server by default; run PipeWire
plus a session manager and a virtual sink:

```bash
pipewire & wireplumber & pipewire-pulse &
pw-cli create-node adapter '{ factory.name=support.null-audio-sink
  node.name="live777-out" media.class=Audio/Sink }'
# applications now play sound as usual (default sink) and it lands in the stream
```

With several sinks, pick the one to capture by name substring:
`audio_sink=live777-out`. A session manager (wireplumber) is required — it is
what links the capture stream to the sink's monitor ports.

## Running as a systemd service

System services have no `XDG_RUNTIME_DIR` by default. Give the service a
runtime directory and point both live777 and the applications at it:

```ini
[Service]
RuntimeDirectory=live777
Environment=XDG_RUNTIME_DIR=/run/live777
```

`RuntimeDirectory=live777` creates `/run/live777` owned by the service user;
clients then connect with `XDG_RUNTIME_DIR=/run/live777
WAYLAND_DISPLAY=desktop-0`.

## Current limitations

* **GPU clients need a working GPU/EGL driver on the host** — with one,
  `zwp_linux_dmabuf_v1` is advertised and GL clients (Qt Quick, browsers,
  mpv) render straight into the stream; without one the compositor
  falls back to CPU compositing and only SHM (wl\_shm) clients work. The DRM
  device defaults to `/dev/dri/renderD128` then `/dev/dri/card0`, overridable
  with `LIVE777_WAYLAND_DRM_DEVICE`. The same applies to X11 GL applications
  (XWayland glamor → DRI3 → dmabuf).
* **No input injection** — unless `input=1` is set on the wayland URL: then
  datachannel events (the `input` cable) inject into the seat with
  focus-follows-click; X11 windows raise+activate on click. Without it the
  desktop is view-only.
* **Audio needs PipeWire** — desktop sound is captured from a PipeWire
  sink monitor; without a daemon the stream is video-only.
* **Subsurfaces and xdg popups are not composited** — only xdg toplevels are
  drawn (popups are configured but skipped). X11 override-redirect windows
  *are* composited, so X11 menus/tooltips show up.
* **X11 window decorations are client-side only** — the built-in XWM draws no
  title bars, and there is no clipboard sync between X11 and Wayland clients.
* **Buffer scale ≠ 1 and buffer transforms are drawn as-is** (best effort).

## H.264 patent note

The encoder is OpenH264. H.264 is patent-encumbered in some jurisdictions:
Cisco's patent license covers only their *prebuilt* binaries — when you build
live777 from source, responsibility for codec patent licensing sits with
whoever distributes the binary.
