迢辰andXuc Pan a5e2aa44cd fix(capture): map the DMA-BUF frames niri actually sends (#26)
* fix(capture): map the DMA-BUF frames niri actually sends

`uur run` reported "No Wayland frames arrived within 120 seconds" on a
session where the portal handshake succeeded. The session log showed the
stream never leaving negotiation:

    portal session ready (video node 73)
    stream state: connecting
    stream state: paused
    stream state: error - no more input formats
    stream state: unconnected

Three separate defects in `uur-pw-capture`:

1. The format filter omitted `modifier`. niri marks that property
   MANDATORY (SPA flags 0x18), and SPA filtering fails unless both sides
   carry a mandatory property -- which surfaces as "no more input
   formats". The filter now advertises LINEAR, the layout the frame
   protocol already assumes.

2. `on_process` only handled `data != NULL` and `SPA_DATA_MemFd`. niri
   delivers SPA_DATA_DmaBuf planes, which carry an fd and no pointer, so
   every frame was dropped in silence. Since the session negotiates
   LINEAR, that fd is directly mappable without GBM/EGL; the helper now
   mmaps it. A non-linear modifier is refused instead of publishing
   garbage.

3. DMA-BUF producers leave `chunk->size` and `maxsize` at 1. Both the
   mapping length and the row count were derived from those, so the mmap
   covered one byte and `rows` came out zero -- publishing an all-black
   frame. Both now use the negotiated stride and height.

Verified on niri 26.04 with Wine 11.19: the stream reaches `streaming`,
~60 fps (1195 frames in 20 s), and the published frame decodes to the
real desktop rather than black.

* fix(capture): validate DMA-BUFs and recover interrupted screen streams

Use immutable transport files across geometry changes and remap Wine readers safely. Bound stream recovery and preserve portal stop-sharing intent. Refs #29.

* fix(capture): watch Mutter layout changes and support older build headers

* fix(capture): keep display changes outside the failure retry budget

* fix(capture): honor portal stop signals during GNOME recovery

Subscribe before starting on the portal-owned D-Bus connection and accept the real Session.Closed dictionary body. Correlate Mutter's close-before-MonitorsChanged ordering without restarting an explicit Stop Sharing session.

Verified in a private GNOME 51.1 namespace with real GBM DMA-BUF, 100/125 percent scaling, portrait and landscape, and native Stop Sharing. Existing 48 tests and strict clippy pass. Real Wine GDI reader captured 120 final-run frames across four layout changes with no hook fallbacks. No test scripts added.

---------

Co-authored-by: Xuc Pan <[email protected]>
2026-10-15 16:57:34 +08:00
2026-09-05 21:30:26 +08:00
2026-10-13 15:31:16 +08:00
2026-10-13 15:31:16 +08:00
2026-09-05 13:04:29 +08:00
2026-10-13 15:31:16 +08:00
2026-10-13 15:31:16 +08:00
2026-09-05 13:04:29 +08:00
2026-09-05 13:04:29 +08:00
2026-09-05 13:04:29 +08:00
2026-10-13 15:31:16 +08:00
2026-10-13 15:31:16 +08:00

UU Remote icon

uur

A native Linux compatibility layer for the official NetEase UU Remote client.

Linux x86_64 X11 and Wayland Rust MIT license

English · 简体中文

Important

uur does not redistribute UU Remote. It downloads the official Windows installer from NetEase after the user explicitly accepts the upstream EULA.

✨ Highlights

Capability Linux integration
Control other computers Official UU interface and media stack under Wine
Allow this Linux computer to be controlled ScreenCast portal/PipeWire capture and native Linux input
X11 and Wayland Capability detection instead of distribution or desktop allowlists
Clean lifecycle Bridges start with UU and stop with its managed Wine prefix
Native tools Linux PTY terminal, wallpaper, Quick Launch, proxy, and sleep inhibition
Upstream resilience API-level runtime adapters; no version/RVA patch matrix
Distribution Arch/pacman, deb, rpm, portable tar.zst, and an AUR recipe

🚀 First run

After installing any package, run these commands in this order:

# 1. Inspect the current Wine, portal, PipeWire, and input capabilities.
uur doctor

# 2. Accept NetEase's EULA, download the official client, and create the prefix.
uur setup --accept-eula

# 3. Start capture, input, the managed Wine services, and the UU interface.
uur run

uur setup without --accept-eula intentionally stops after printing the official EULA URL. It does not install the proprietary client.

Many capabilities remain untested; runtime testing so far covers Arch Linux, KDE Plasma, and Wayland.

After setup, UU Remote is also available from the application menu. The menu entry launches the complete uur run session.

📦 Installation

Download the newest package for the system from the GitHub Releases page. Native recipes and release artifacts share one version and filesystem layout.

Arch Linux

Install a downloaded release package with pacman:

sudo pacman -U ./dist/uur-0.1.5-1-x86_64.pkg.tar.zst

AUR

After the package is available from AUR:

paru -S uur

Debian and Ubuntu package family

sudo apt install ./uur_0.1.5_amd64.deb

Fedora and compatible RPM systems

sudo dnf install ./uur-0.1.5-1.x86_64.rpm

On systems with different RPM dependency names, install the dependencies manually or use the portable archive.

Portable archive

sudo tar --zstd -C / -xf ./uur-0.1.5-linux-x86_64.tar.zst

Nix and NixOS

nix build
nix run . -- doctor

The flake also exports nixosModules.default; see Nix and NixOS.

Alpine Linux

Alpine edge can build the native musl package layout with:

docker build -f packaging/alpine/Dockerfile .

An APKBUILD is included under packaging/alpine/.

User installation from source

cargo build --release --locked
./hook/build.sh
./capture/build.sh
./scripts/install-user.sh

The source build requires Rust, a C compiler, PipeWire development files, pkg-config, and the MinGW-w64 x86_64 toolchain.

Gentoo, Void Linux, Slackware, Solus, ALT Linux, Exherbo, Clear Linux, Mageia, OpenMandriva, PCLinuxOS, Venom Linux, Guix System, and other package ecosystems can use the portable archive or the shared packaging/stage.sh source layout.

See Platform support and usage for distribution families, portal choices, X11/Wayland sessions, standalone window managers, immutable systems, and libc boundaries.

🧭 Daily use

uur run                 # Start or show the managed UU session
uur doctor              # Read-only environment diagnostics
uur upstream check      # Check the official NetEase release feed
uur autostart enable    # Optional: start after graphical login
uur autostart disable   # Remove the managed login entry
uur wol status          # Inspect the physical wired adapter's WOL state
uur display status      # Monitor, window, or portal virtual source
uur display source virtual
uur display outputs     # Native Wayland output names
uur stop                # Stop only uur's helpers and Wine prefix
uur uninstall --purge --dry-run  # Preview complete user-data cleanup
uur uninstall --purge   # Confirm cleanup before removing the system package

If UU was started from the desktop, choose Quit from the launcher's application actions. When running from a terminal, use uur stop or press Ctrl+C.

On niri, uur provides a native tray and an explicitly enabled direct capture path: uur display backend wayland --output DP-1 (use your output name). This uses uinput and captures the chosen monitor without a portal dialog. Return to system-consented capture with uur display backend portal.

Package removal alone preserves the Wine prefix and account data. See complete removal for the user-cleanup and package-manager steps.

Diagnostic input overrides:

UUR_INPUT_BACKEND=portal uur run
UUR_INPUT_BACKEND=uinput uur run
UUR_INPUT_BACKEND=xtest uur run

Use the default auto mode after troubleshooting.

🖥️ Desktop integration

  • A Wayland session with both RemoteDesktop and ScreenCast portals uses one combined, unprivileged session for input and video.
  • A Wayland session with only ScreenCast uses PipeWire for video and uinput for full-desktop input.
  • An X11 session uses Wine's native X11 capture and XTest input.
  • XTest under XWayland is only a partial fallback and is not advertised as full Wayland desktop control.

Run uur doctor instead of inferring support from a desktop or distribution name.

🧩 Native Linux features

Screen capture, keyboard, pointer, lifecycle management, wallpaper metadata, native terminal, Quick Launch, proxy synchronization, suspend inhibition, and host WOL configuration are implemented. Quick Launch exposes the XDG application catalog through UU and resolves each request back to gio launch; it never accepts an arbitrary command from Wine. Other UU features require native Linux service adapters rather than being left inside the Wine prefix:

Feature Direction
Terminal Authenticated UU transport → native PTY and the user's login shell
Quick Launch UU application inventory → authenticated XDG desktop activation
Wake-on-LAN setup uur wol → real wired interface and NetworkManager profile
Received files Validated staging → the user's XDG Downloads directory
Sending files File portal or explicit CLI selection → bounded native staging
Port mapping Policy-controlled native TCP/UDP broker; loopback by default
Clipboard and phone text RemoteDesktop Clipboard portal with X11 fallback

The protocol, security boundaries, lifecycle, and implementation phases are in Native service adapters.

🔬 How it works

Official UU Remote client (managed Wine prefix)
        │
        ├─ Windows API adapter ── authenticated input/control protocol
        │
        └─ GDI/DXGI capture boundary ◄── private triple-buffer frame transport
                                              ▲
Linux supervisor ── ScreenCast portal ── PipeWire
        │
        └─ RemoteDesktop portal / uinput / XTest

The Windows ABI adapter is small C code. Session policy, desktop integration, capability selection, and lifecycle management are implemented in Rust.

🛠️ Troubleshooting

Start with:

uur doctor

Session logs are stored at:

${XDG_STATE_HOME:-$HOME/.local/state}/uur/session.log

For Wine diagnostics only:

WINEDEBUG=+loaddll uur run

Normal runs suppress Wine's non-actionable fixme output.

📚 Documentation

🙏 Credits

The project learned from GuoWQ222/uu-remote-for-linux, lachlanchen/uu-remote-ubuntu-bridge.

NetEase UU Remote is proprietary software of NetEase. uur is an unofficial compatibility project and is not affiliated with NetEase.

Languages
Rust 59%
C 36%
Shell 4.3%
Nix 0.6%
Dockerfile 0.1%