Waytermirror

Real-time Wayland screen mirroring to a terminal or native window using Unicode braille characters, half‑blocks, ASCII, sixels, kitty graphics, framebuffer, KMS direct rendering, native GUI window, or hybrid rendering. Includes bidirectional input forwarding, audio streaming (PipeWire), zooming, focus-follow, and optional NVIDIA CUDA acceleration (server-side).

Waytermirror

What it is

A client/server application:
- Server runs on the Wayland host (captures screen & audio, performs rendering, injects input).
- Client runs locally (receives frames, displays them, captures input, sends it to server).
Rendering modes:
- Terminal-based: braille, half-blocks, ASCII, hybrid (auto-select per cell)
- Pixel-based: sixels, kitty graphics, framebuffer (/dev/fb0), KMS direct rendering, native Wayland window (GUI)
Color modes: 16, 256, truecolor (24‑bit). (applies to terminal-based renderers only)
Optional CUDA acceleration for server-side Unicode rendering (NVIDIA only).
Hardware-accelerated H.265/HEVC encoding for pixel-based renderers with automatic hardware detection (NVENC, QuickSync, VAAPI, AMF, VideoToolbox).
Native GUI mode: Client creates a Wayland window for a native application experience (no terminal required).

Demonstration

https://github.com/user-attachments/assets/089d1c60-c502-4422-892c-fb83e392149a

How it works (short)

Screen capture: wlr-screencopy/PipeWire → frame buffer → renderer (CPU/CUDA)
Unicode renderers (braille/blocks/ascii/hybrid): ANSI escape sequences → LZ4 → TCP → client terminal
Pixel renderers (sixel/kitty/framebuffer/KMS/GUI): RGB24 → H.265 encoder (hardware-accelerated) → TCP → client decoder → display
Input: Client libinput capture → TCP → server → virtual pointer/keyboard (Wayland) on host
Audio: System audio (server→client) and microphone (client→server) via PipeWire with optional Opus compression
Hardware encoder priority: NVENC (NVIDIA) → QuickSync (Intel) → VAAPI (Intel/AMD) → AMF (AMD) → VideoToolbox (macOS) → software fallback (x265)
Hardware decoder priority: CUDA (NVIDIA) → VAAPI (Intel/AMD) → QuickSync (Intel) → VDPAU (NVIDIA Legacy) → VideoToolbox (macOS) → multi-threaded software fallback

Quickstart

Build (CPU-only)

git clone https://github.com/cyber-wojtek/waytermirror.git
cd waytermirror
meson setup builddir
meson compile -C builddir -j$(nproc)

This produces waytermirror_server and waytermirror_client.

Run the server on your Wayland desktop:
```
./waytermirror_server
```
Run the client:
- Terminal mode (default - works anywhere):
```
./waytermirror_client -H <host>
```
- Native GUI window (best experience):
```
./waytermirror_client -H <host> -R gui
```
- Framebuffer mode (TTY/console - requires root/video group):
```
sudo ./waytermirror_client -H <host> -R framebuffer
```
- KMS direct rendering (TTY/console - requires root/video group):
```
sudo ./waytermirror_client -H <host> -R kms
```

Tip: Run ./waytermirror_client --help or ./waytermirror_server --help to see all available flags and defaults.

Build & install

Prerequisites

Core: gcc/g++, make, wayland, wayland-protocols, libinput, pipewire, lz4, rapidjson, systemd, argparse, libsixel, libpng, opus, libudev, libdrm, gbm
Video encoding: FFmpeg (libavcodec, libavutil, libswscale, libavformat) for H.265/HEVC encoding/decoding with hardware acceleration support
Optional: NVIDIA CUDA toolkit for GPU rendering (nvcc) — see NVIDIA CUDA Toolkit

Arch Linux-based

sudo pacman -S base-devel git gcc wayland wayland-protocols libinput pipewire lz4 rapidjson systemd argparse libsixel libpng ffmpeg opus libdrm mesa meson
# Optional for CUDA:
sudo pacman -S cuda

Debian-based

sudo apt install build-essential git gcc libwayland-dev wayland-protocols libinput-dev libpipewire-0.3-dev liblz4-dev rapidjson-dev libsystemd-dev pkg-config meson libargparse-dev libsixel-dev libpng-dev libavcodec-dev libavutil-dev libswscale-dev libavformat-dev libopus-dev libudev-dev libdrm-dev libgbm-dev
# For CUDA: install NVIDIA CUDA toolkit from https://developer.nvidia.com/cuda-toolkit

Building

CPU-only (default):

meson setup builddir
meson compile -C builddir -j$(nproc)

CUDA-enabled (if you have nvcc and CUDA libs):

meson setup builddir -Dnvidia_cuda=true
meson compile -C builddir -j$(nproc)

The provided PKGBUILD auto-detects nvcc. Override with WAYTERMIRROR_CUDA=1 or WAYTERMIRROR_NO_CUDA.

Artifacts

waytermirror_server
waytermirror_client

Packaging (Arch)

AUR: Install directly from the waytermirror-git AUR package:
```
yay -S waytermirror-git
# or
paru -S waytermirror-git
```

Manual build: Use the included PKGBUILD with makepkg:

mkdir -p waytermirror
cd waytermirror
wget https://github.com/cyber-wojtek/waytermirror/raw/refs/heads/main/PKGBUILD
makepkg -si

Runtime requirements

Audio: PipeWire (for system audio streaming and microphone capture).
Input: Access to input devices (user must be in the input group or run with sufficient privileges to read /dev/input/*).
GUI mode: Running Wayland compositor with xdg-shell support.
Framebuffer/KMS modes: Root access or proper permissions for /dev/fb0 and /dev/dri/card*.
Hardware video encoding (server): Supported encoders auto-detected at runtime:
- NVIDIA: NVENC (most performant, lowest latency)
- Intel: QuickSync Video or VAAPI
- AMD: AMF (Windows/Linux) or VAAPI (Linux)
- Apple: VideoToolbox (macOS)
- Software fallback: libx265 (very slow, not recommended for real-time)
Hardware video decoding (cl

Waytermirror

Install / Use

README

Waytermirror

Table of contents

What it is

Demonstration

How it works (short)

Quickstart

Build & install

Prerequisites

Arch Linux-based

Debian-based

Building

Artifacts

Packaging (Arch)

Runtime requirements