wl-mirror(1)

📦
version 0.18.5 · 8 versions
, in alpine 3.24, arch rolling

💅 wl-mirror(1) — the mirror client that ate 💅

okay so first things first: this is the manual page for wl-mirror, living in the General Commands Manual section (section 1, iykyk), and it's genuinely one of those little tools that just works. It's a simple Wayland output mirror client. That's the whole vibe. 🪞✨

🎀 NAME 🎀

wl-mirror — a simple Wayland output mirror client. no cap, that's literally it, and it's iconic for it.

🌸 SYNOPSIS 🌸

wl-mirror [-h,-V,-v,-c,-i,-f,-s S,-b B,-t T,-r R,-S] <output>

yes bestie, <output> is the positional argument and it's a whole mood. keep reading. 💖

✨ OPTIONS ✨

  • -h, --help — show the help message and dip. 🫶
  • -V, --version — show version info and exit. classic.
  • -v, --verbose — turn on debug logging.
  • --no-verbose — turn debug logging off again (the toggle of the above, obvi). 🦋
  • -c, --show-cursor — show the cursor on the mirrored surface. this one's enabled by default, so you're already slaying.
  • --no-show-cursor — hide the cursor on the mirrored surface.
  • -i, --invert-colors — invert colors on the mirrored surface. chaos mode, highkey aesthetic. 🌈
  • --no-invert-colors — un-invert them, back to normal colors.
  • -f, --freeze — freeze the current image on the screen. 🧊
  • --unfreeze — unfreeze it, the image moves again.
  • --toggle-freeze — toggle that freezing on/off. one flag, three vibes.
  • -F, --fullscreen — open as a fullscreen window, or make the current window fullscreen in stream mode. main character energy fr.
  • --no-fullscreen — open as a regular window (enabled by default), or exit fullscreen in stream mode.
  • --fullscreen-output O — set a different output to fullscreen on (the default is the current output). this one implies --fullscreen.
  • --no-fullscreen-output — set the target fullscreen output back to the current window output. this one implies --no-fullscreen.
  • -s f, --scaling fit — scale to fit and, if necessary, add letterboxing. enabled by default 💅
  • -s c, --scaling cover — scale to cover and, if necessary, crop the image.
  • -s e, --scaling exact — use exact multiple scaling and, if necessary, add letterboxing.
  • -s l, --scaling linear — use linear scaling. enabled by default ✨
  • -s n, --scaling nearest — use nearest-neighbor scaling.
  • -b B, --backend B — use a specific screen capture backend. go read BACKENDS, bestie.
  • -t T, --transform T — apply a custom transform (rotation and flipping). see TRANSFORMS.
  • -r R, --region R — capture a custom screen region R. see REGIONS.
  • -S, --stream — accept a stream of additional options on stdin. see STREAM MODE 🦋
  • --title T — set a custom title T for the mirror window. this title can contain placeholders, so go look at TITLE PLACEHOLDERS.

🔥 BACKENDS 🔥

  • auto — automatically try backends in order of backend efficiency and use the first one that works (enabled by default). the next backend gets selected automatically when the current backend fails to capture a frame 10 times in a row. persistence, honestly. 💀

the current fallback order is:

  • extcopy-dmabuf (if compiled with libGBM)
  • screencopy-dmabuf (if compiled with libGBM)
  • export-dmabuf
  • extcopy-shm
  • screencopy-shm
  • export-dmabuf — use the wlr-export-dmabuf-unstable-v1 protocol to capture outputs (requires wlroots). this backend keeps the image data on the GPU and does not need expensive copies to the CPU and back. 🚀
  • screencopy-dmabuf — use the wlr-screencopy-unstable-v1 protocol to capture outputs (requires wlroots). this backend keeps the image data on the GPU and does not need expensive copies to the CPU and back. this backend requires wl-mirror to be compiled with support for allocating DMA-BUFs using libGBM.
  • screencopy-shm — use the wlr-screencopy-unstable-v1 protocol to capture outputs (requires wlroots). this backend passes the image data via shared memory on the CPU, but may have better compatibility with complex GPU driver configurations (e.g., multi GPU).
  • screencopy — automatically tries screencopy-dmabuf or screencopy-shm and uses the first one that works. fallback works the same as with auto.
  • extcopy-dmabuf — use the ext-image-copy-capture-v1 protocol to capture outputs. this backend keeps the image data on the GPU and does not need expensive copies to the CPU and back. this backend requires wl-mirror to be compiled with support for allocating DMA-BUFs using libGBM.
  • extcopy-shm — use the ext-image-copy-capture-v1 protocol to capture outputs. this backend passes the image data via shared memory on the CPU, but may have better compatibility with complex GPU driver configurations (e.g., multi GPU).
  • extcopy — automatically tries extcopy-dmabuf or extcopy-shm and uses the first one that works. fallback works the same as with auto. ✨

🦋 TRANSFORMS 🦋

okay so transforms are specified as a dash-separated list of flips followed by a rotation amount. flips are applied before rotations, and both flips and rotations are optional. custom transformations are applied after adjusting for the wayland output transform, so that if no custom transformations are applied, the mirrored surface is displayed right-side-up. periodt. 👑

  • normal — no transformation (this is the default transformation).
  • flipX, flipY — flip the X or Y coordinate of the image, i.e. flipX means the mirrored surface has left and right swapped. 🔄
  • 0cw, 90cw, 180cw, 270cw — apply a clockwise rotation.
  • 0ccw, 90ccw, 180ccw, 270ccw — apply a counter-clockwise rotation.

the following transformation options are provided for compatibility with sway-output(5) transforms:

  • flipped — same as flipX.
  • 0, 90, 180, 270 — same as 0cw, 90cw, 180cw, 270cw.

💜 REGIONS 💜

regions are specified in the format used by the slurp(1) utility:

'x,y widthxheight [output]'

in slurp(1) syntax, this would be specified as follows (the last part with %o is optional):

'%x,%y %wx%h %o'

when processing the region option, the region is translated into output coordinates, so when the output moves, the captured region moves with it. so it's lowkey clingy in the best way. 🫶 when a region is specified, the output positional argument is optional.

🌈 STREAM MODE 🌈

in stream mode, wl-mirror interprets lines on stdin as additional command line options. it's giving raccoon-with-a-keyboard and honestly? slay.

  • arguments can be quoted with single or double quotes, but every argument must be fully quoted. no half-quoting, bestie. 🙈
  • unquoted arguments are split on whitespace.
  • no escape sequences are implemented. none. zero. nope.

option lines on stdin are processed asynchronously, and can override all options and the captured output. stream mode is used by wl-present(1) to add interactive controls to wl-mirror. 💅

🎀 TITLE PLACEHOLDERS 🎀

the title string supports the following placeholders:

  • {width}, {height}: size of the mirrored area
  • {x}, {y}: offsets on the screen
  • {target_width}, {target_height}, {target_output}: info about the mirrored device

a few perhaps useful examples:

--title 'Wayland Mirror Output {target_output}'
--title '{target_output}:{width}x{height}+{x}+{y}'
--title 'resize set {width} {height} move position {x} {y}'

these are literally so useful, iykyk. ⭐

👑 AUTHORS 👑

maintained by Ferdinand Bachmann <ferdinand.bachmann@yrlf.at>. more information on wl-mirror can be found at <https://github.com/Ferdi265/wl-mirror>. go give it a star, it's the least you can do. 🫶

🌸 SEE ALSO 🌸

wl-present(1) slurp(1) sway-output(5)

that's the whole page bestie!! 🎀 this beauty is from the wl-mirror(1) manual, dated 2026-02-10 — go mirror some outputs and be iconic about it. 💖✨🦋

📦 where this page comes from