Initial commit
This commit is contained in:
commit
611383544b
91 files changed
+12958
No files matched your search
@@ -0,0 +1,76 @@
|
||||
# Architecture
|
||||
|
||||
`uur` is a compatibility layer, not a repackaged Windows application. The
|
||||
official client remains in an isolated per-user Wine prefix. A small PE hook
|
||||
adapts stable Windows APIs at runtime; the Rust host owns policy, desktop
|
||||
integration, and process lifetime.
|
||||
|
||||
```text
|
||||
UU Remote / Wine
|
||||
└─ PE ABI adapter (SendInput, GDI/DXGI capture entry points)
|
||||
└─ authenticated loopback protocol + private frame transport
|
||||
└─ Rust session supervisor
|
||||
├─ capture source: xdg ScreenCast → PipeWire
|
||||
├─ input sink (capability-selected)
|
||||
├─ xdg RemoteDesktop
|
||||
├─ Linux uinput
|
||||
└─ X11 XTest
|
||||
└─ native services
|
||||
├─ authenticated terminal proxy → Linux PTY
|
||||
├─ authenticated Quick Launch proxy → XDG applications
|
||||
├─ wallpaper metadata synchronizer
|
||||
└─ desktop suspend/idle inhibitor
|
||||
```
|
||||
|
||||
## Capability negotiation
|
||||
|
||||
No runtime branch checks a desktop or distribution name. The order is based on
|
||||
available interfaces:
|
||||
|
||||
1. On Wayland, try a combined RemoteDesktop + ScreenCast portal session. This
|
||||
is the preferred unprivileged path and uses one consent session for video
|
||||
and input.
|
||||
2. If the compositor exposes ScreenCast but not RemoteDesktop, keep portal
|
||||
capture and inject through `/dev/uinput`. This covers compositors whose
|
||||
portal currently implements capture only.
|
||||
3. On X11, use XTest. Wine already sees the real X11 desktop, so an additional
|
||||
portal capture is unnecessary.
|
||||
4. XTest remains a final partial fallback for XWayland windows.
|
||||
|
||||
Portal implementations are selected by `xdg-desktop-portal`, not by uur. This
|
||||
keeps compositor-specific policy in the component designed to own it.
|
||||
|
||||
## Adapter boundary
|
||||
|
||||
The PE DLL is intentionally small C code because it must obey the Windows ABI.
|
||||
It intercepts API imports and dynamic `GetProcAddress` resolution; it does not
|
||||
search for product-version-specific instruction bytes or patch official
|
||||
binaries. Everything above that ABI boundary is Rust.
|
||||
|
||||
Capture follows the same pattern as `wemeet-wayland-screenshare`: intercept a
|
||||
stable capture boundary, obtain real compositor frames through PipeWire, and
|
||||
substitute those frames before the proprietary application consumes them.
|
||||
The implementation supports GDI today and keeps DXGI behind the same adapter
|
||||
surface.
|
||||
|
||||
## Lifetime and isolation
|
||||
|
||||
`uur run` is the only supervisor. It creates each native helper in a dedicated
|
||||
process group and records the supervisor PID plus Linux process start time.
|
||||
When the UU UI exits, or when `uur stop` sends SIGTERM to that exact supervisor,
|
||||
RAII cleanup terminates only those helper groups and the one managed Wine
|
||||
prefix. There are no permanent daemons, global `pkill` calls, or required
|
||||
systemd units.
|
||||
|
||||
Frame data lives in `$XDG_RUNTIME_DIR/uur/frames.v1` with mode 0600. The path is
|
||||
passed through the adapter configuration, so users and concurrent sessions do
|
||||
not share a global `/dev/shm` object.
|
||||
|
||||
## Extension seams
|
||||
|
||||
- `InputBackend`: portal, uinput, XTest, and future libei transports.
|
||||
- capture helper protocol: producer-independent triple-buffer transport.
|
||||
- PE adapter: API-level UU integration isolated from Linux backends.
|
||||
- session supervisor: process lifetime independent of init system.
|
||||
- packaging stage: one filesystem layout consumed by AUR, deb, rpm, Arch, and
|
||||
portable tarball builders.
|
||||
@@ -0,0 +1,49 @@
|
||||
# Capture frame protocol
|
||||
|
||||
How frames travel from the compositor (via PipeWire) into the client's
|
||||
capture calls. Two producers/consumers, one shared file, no locks.
|
||||
|
||||
```text
|
||||
xdg-desktop-portal ScreenCast
|
||||
│ (portal-consented session; per-monitor)
|
||||
▼
|
||||
uur-pw-capture (C) ── PipeWire stream, BGRx, SHM buffers
|
||||
│ writes slots, seqlock per slot
|
||||
▼
|
||||
$XDG_RUNTIME_DIR/uur/frames.v1 (mode 0600, 64-byte header + 3 slots)
|
||||
│ mapped read-only by the PE hook through its configured Wine Z: path
|
||||
▼
|
||||
uur-hook.dll ── intercepts static/dynamic gdi32!BitBlt/StretchBlt calls;
|
||||
scales the newest stable snapshot into the destination DIB
|
||||
```
|
||||
|
||||
## Shared file layout
|
||||
|
||||
All integers little-endian. Total size = 64 + 3 × (8 + stride × height).
|
||||
|
||||
| offset | type | field |
|
||||
| --- | --- | --- |
|
||||
| 0 | u32 | magic `0x46525555` ("UURF") |
|
||||
| 4 | u32 | protocol version = 1 |
|
||||
| 8 | u32 | frame width (px) |
|
||||
| 12 | u32 | frame height (px) |
|
||||
| 16 | u32 | stride (bytes per row) |
|
||||
| 20 | u32 | format: 1 = BGRx (32 bits per pixel) |
|
||||
| 24 | u64 | total frames written (monotonic counter) |
|
||||
| 32..64 | — | reserved, zero |
|
||||
|
||||
Slot *i* (i = 0, 1, 2) at offset `64 + i × (8 + stride × height)`:
|
||||
|
||||
| offset | type | field |
|
||||
| --- | --- | --- |
|
||||
| 0 | u64 | sequence: `2×n − 1` while slot n is being written, `2×n` when slot n is stable |
|
||||
| 8 | bytes | frame, `stride × height`, rows top-to-bottom, pixels BGRx |
|
||||
|
||||
Writer picks slots round-robin (`n mod 3`), bumps the counter, publishes
|
||||
the odd sequence (release), copies the frame, then publishes the even
|
||||
sequence (release). The reader is a classic seqlock read: load the
|
||||
sequence, copy, re-load; retry while the value changed or is odd. No
|
||||
mutexes; a torn read is detected, never observed.
|
||||
|
||||
The transport path is created per user and passed to the Wine adapter through
|
||||
the managed prefix configuration. It is never a global shared-memory name.
|
||||
@@ -0,0 +1,113 @@
|
||||
# Package installation
|
||||
|
||||
Choose the package format native to the system. Every format installs the same
|
||||
Rust supervisor, Wine adapters, PipeWire helper, desktop entry, icon, and
|
||||
uinput integration files. `sudo`, `doas`, or another privilege frontend may be
|
||||
needed for system-wide package installation.
|
||||
|
||||
## Arch Linux
|
||||
|
||||
```bash
|
||||
# AUR
|
||||
paru -S uur
|
||||
|
||||
# Downloaded release package
|
||||
sudo pacman -U ./uur-0.1.0-1-x86_64.pkg.tar.zst
|
||||
```
|
||||
|
||||
## Debian, Ubuntu, and derivatives
|
||||
|
||||
```bash
|
||||
sudo apt install ./uur_0.1.0_amd64.deb
|
||||
```
|
||||
|
||||
The same release artifact covers Debian, Ubuntu, Linux Mint, Pop!_OS, KDE neon,
|
||||
Zorin OS, elementary OS, Kali Linux, MX Linux, TUXEDO OS, and compatible
|
||||
derivatives.
|
||||
|
||||
## Fedora, RHEL, and openSUSE families
|
||||
|
||||
```bash
|
||||
sudo dnf install ./uur-0.1.0-1.x86_64.rpm
|
||||
|
||||
# openSUSE
|
||||
sudo zypper install ./uur-0.1.0-1.x86_64.rpm
|
||||
```
|
||||
|
||||
This format also covers Fedora derivatives and RPM systems whose repositories
|
||||
provide the declared Wine, GLib, PipeWire, and portal dependencies.
|
||||
|
||||
## Portable archive
|
||||
|
||||
The portable archive targets conventional glibc/FHS systems:
|
||||
|
||||
```bash
|
||||
sudo tar --zstd -C / -xf ./uur-0.1.0-linux-x86_64.tar.zst
|
||||
```
|
||||
|
||||
## Nix and NixOS
|
||||
|
||||
```bash
|
||||
nix build
|
||||
nix run . -- doctor
|
||||
```
|
||||
|
||||
The flake includes a package, application, development shell, lock file, and
|
||||
NixOS module. See [Nix and NixOS](nix.md).
|
||||
|
||||
## Alpine Linux and musl
|
||||
|
||||
`packaging/alpine/APKBUILD` builds an x86_64 musl package from a tagged source
|
||||
archive. The container recipe runs the same Rust, MinGW, and PipeWire builds:
|
||||
|
||||
```bash
|
||||
docker build -f packaging/alpine/Dockerfile .
|
||||
```
|
||||
|
||||
Alpine edge provides native x86_64 Wine, PulseAudio/ALSA Wine drivers,
|
||||
PipeWire, desktop portals, Rust, and the MinGW-w64 toolchain.
|
||||
|
||||
```bash
|
||||
cd packaging/alpine
|
||||
abuild checksum
|
||||
abuild -r
|
||||
sudo apk add ~/packages/*/x86_64/uur-*.apk
|
||||
```
|
||||
|
||||
## Other package ecosystems
|
||||
|
||||
Gentoo, Funtoo, Void Linux, Slackware, Solus, Clear Linux, ALT Linux, Exherbo,
|
||||
Mageia, OpenMandriva, PCLinuxOS, Venom Linux, and other FHS/glibc systems can
|
||||
install the portable release archive or build from source. Their native recipe
|
||||
can call `packaging/stage.sh` after the three standard builds; the staged tree
|
||||
is shared with pacman, deb, rpm, APK, and the portable archive.
|
||||
|
||||
GNU Guix can wrap the same source build and staged tree. Flatpak and Snap need
|
||||
manifests granting Wine execution, session D-Bus, PipeWire, and input access.
|
||||
|
||||
## Source installation for one user
|
||||
|
||||
```bash
|
||||
cargo build --release --locked
|
||||
./hook/build.sh
|
||||
./capture/build.sh
|
||||
./scripts/install-user.sh
|
||||
```
|
||||
|
||||
This installs under `~/.local` by default. It requires Rust, a native C
|
||||
compiler, PipeWire development files, `pkg-config`, and the MinGW-w64 x86_64
|
||||
toolchain.
|
||||
|
||||
## Required first run
|
||||
|
||||
Package installation does not implicitly accept NetEase's EULA or download the
|
||||
official client. Complete the setup explicitly:
|
||||
|
||||
```bash
|
||||
uur doctor
|
||||
uur setup --accept-eula
|
||||
uur run
|
||||
```
|
||||
|
||||
See [Platform support and usage](platform-support.md) for desktop-session and
|
||||
portal requirements.
|
||||
@@ -0,0 +1,35 @@
|
||||
# Feature parity
|
||||
|
||||
| Capability | Status | Linux route |
|
||||
| --- | --- | --- |
|
||||
| Control other devices | available | Official UU UI and decoder under Wine |
|
||||
| Receive remote video | available | Official UU UI under Wine |
|
||||
| Share X11 desktop | available | Wine X11 capture |
|
||||
| Share Wayland desktop | available | ScreenCast portal → PipeWire → GDI adapter |
|
||||
| Mouse and keyboard | implemented | RemoteDesktop portal → uinput → XTest capability order |
|
||||
| X11 multi-monitor | Wine integration | Native Wine/XRandR display topology |
|
||||
| Wayland monitor/window selection | available | Persistent portal source selection |
|
||||
| Wayland virtual source | available when advertised | `uur display source virtual` → ScreenCast Virtual source |
|
||||
| Independent Wayland multi-screen switching | in progress | Multiple PipeWire streams → UU display topology adapter |
|
||||
| Clipboard and phone IME text | planned | RemoteDesktop Clipboard portal, then X11 fallback |
|
||||
| Speaker and microphone audio | available through Wine | PulseAudio, pipewire-pulse, or ALSA selected from live capabilities |
|
||||
| System-audio loopback and remote mute | Wine integration | WASAPI → winepulse/winealsa |
|
||||
| Native tray | Wine baseline | Official tray, with StatusNotifierItem as the native route |
|
||||
| Terminal | available | ConPTY/mux ABI adapters → authenticated native Rust PTY/login shell |
|
||||
| Quick Launch | implemented | Windows app inventory adapter → XDG desktop catalog → `gio launch` |
|
||||
| Desktop wallpaper | available | Capability providers → Wine desktop metadata |
|
||||
| Prevent suspend/idle | available | Inhibit portal, scoped to `uur run` |
|
||||
| System proxy | available | Standard proxy environment → Wine WinINet settings |
|
||||
| Login autostart | available | User-controlled XDG autostart entry |
|
||||
| Wake-on-LAN host setup | available | Physical-interface discovery → ethtool/NetworkManager configuration |
|
||||
| Wake button in UU cloud UI | planned | Stable server capability API integration |
|
||||
| VA-API capability | detected | DRM render nodes + `vainfo` |
|
||||
| Vulkan Video capability | detected | Vulkan device and `VK_KHR_video_queue` |
|
||||
| NVENC/NVDEC capability | detected | NVIDIA encode/decode driver libraries |
|
||||
| Native hardware encode/decode data path | in progress | A common frame/codec interface feeds VA-API, Vulkan Video, and NVENC/NVDEC |
|
||||
| Gamepad | Wine baseline | Wine HID/XInput for the controller UI; native host injection is planned |
|
||||
| Resolution, orientation, HiDPI, zoom | partial | Portal stream geometry and Wine display settings |
|
||||
| Privacy screen | planned | Compositor output policy and virtual display routing |
|
||||
| Lock, reboot, shutdown, task manager | planned | logind/Polkit and desktop-native actions |
|
||||
| Unattended login screen | compositor-dependent | Display-manager or compositor remote-desktop session |
|
||||
| Upstream update detection | available | Official feed + API-contract CI probe |
|
||||
@@ -0,0 +1,159 @@
|
||||
# Native service adapters
|
||||
|
||||
UU Remote exposes features beyond screen control. On Linux, those features
|
||||
must operate on the host user account and network namespace, not on Wine's
|
||||
emulated Windows environment.
|
||||
|
||||
## Design boundary
|
||||
|
||||
```text
|
||||
UU feature protocol under Wine
|
||||
│
|
||||
▼
|
||||
small Win64 ABI proxy
|
||||
│ authenticated loopback, bounded frames
|
||||
▼
|
||||
Rust native service owned by `uur run`
|
||||
│
|
||||
├─ PTY and login shell
|
||||
├─ XDG user directories and file portals
|
||||
└─ host TCP/UDP sockets
|
||||
```
|
||||
|
||||
Proxies translate only the Windows process or stdio boundary expected by UU.
|
||||
They do not implement Linux policy. Native services are children of the uur
|
||||
supervisor and cannot outlive the managed session.
|
||||
|
||||
## Terminal
|
||||
|
||||
Status: implemented.
|
||||
|
||||
UU's server uses `conpty_bridge.exe`, `uuyc-mux.exe`, and WTS session queries.
|
||||
At session startup, uur installs narrow Win64 adapters at those documented
|
||||
process and API boundaries. The ConPTY adapter forwards stdio and resize
|
||||
frames; the mux adapter preserves UU's named-session lifecycle; the WTS shim
|
||||
supplies an active unlocked Wine session. UU's private visible-attach IPC is
|
||||
delegated to the retained original helper while shell I/O remains native.
|
||||
|
||||
The Rust service:
|
||||
|
||||
- binds an ephemeral IPv4 loopback port;
|
||||
- generates a new 256-bit token for every `uur run`;
|
||||
- accepts at most four concurrent terminal sessions;
|
||||
- validates a fixed-size handshake and caps frames at 64 KiB;
|
||||
- opens a real PTY and starts `$SHELL -l` in `$HOME`;
|
||||
- forwards terminal resize events with `TIOCSWINSZ`;
|
||||
- sends a hangup and reaps the shell when the UU terminal closes;
|
||||
- never logs commands, input, output, or environment contents.
|
||||
|
||||
The mode-0600 runtime configuration is removed during session shutdown. The
|
||||
listener, proxy configuration, PTYs, and shells share the main uur lifecycle.
|
||||
|
||||
Implementation files:
|
||||
|
||||
- `src/terminal.rs`
|
||||
- `hook/terminal-proxy.c`
|
||||
- `hook/terminal-protocol.h`
|
||||
- `tests/terminal-smoke.sh`
|
||||
|
||||
The smoke test starts the Rust service, runs the Win64 proxy under Wine, sends a
|
||||
command through it, and requires a marker emitted by the native Linux shell.
|
||||
|
||||
## Quick Launch
|
||||
|
||||
Status: implemented.
|
||||
|
||||
UU discovers launchable Windows applications through the standard Uninstall
|
||||
registry. Before starting the server, uur exports the current XDG desktop
|
||||
application catalog into a private registry namespace. Each item targets a
|
||||
small Win64 launcher stored in the managed prefix.
|
||||
|
||||
The launcher cannot execute an arbitrary command. It reads its immutable
|
||||
desktop ID, authenticates to a per-run loopback endpoint, and asks the Rust
|
||||
service to launch that ID only if it is still present in the freshly scanned
|
||||
catalog. The host uses `gio launch` with `gtk-launch` as a fallback, so normal
|
||||
desktop activation also covers applications installed through integration
|
||||
layers that publish `.desktop` entries.
|
||||
|
||||
The runtime token is mode 0600 and removed with the main session. A bounded
|
||||
catalog prevents an untrusted application directory from causing unbounded
|
||||
registry or prefix growth.
|
||||
|
||||
## Desktop integration services
|
||||
|
||||
The same lifecycle owns wallpaper synchronization and suspend/idle inhibition.
|
||||
Proxy settings are imported before Wine starts. Login autostart is explicitly
|
||||
controlled with `uur autostart`; no permanent root daemon is used.
|
||||
|
||||
## File transfer
|
||||
|
||||
Status: UU's existing Wine-visible filesystem remains available; native path
|
||||
integration is not implemented yet.
|
||||
|
||||
This means transfers can use paths under the managed prefix or Wine's `Z:`
|
||||
mapping. A future native adapter should preserve UU's existing transfer
|
||||
protocol while changing only filesystem access:
|
||||
|
||||
### Receiving
|
||||
|
||||
1. Receive into a mode-0700 staging directory under the user's XDG data or
|
||||
runtime directory.
|
||||
2. Reject absolute paths, parent traversal, device names, symlinks, sparse-file
|
||||
amplification, and declared-size mismatches.
|
||||
3. Keep partial files hidden and enforce per-file and per-session quotas.
|
||||
4. After the final size and digest are known, atomically publish into the XDG
|
||||
Downloads directory with collision-safe names.
|
||||
5. Optionally notify the desktop through the standard notification portal.
|
||||
|
||||
### Sending
|
||||
|
||||
1. Obtain files from an explicit CLI argument, drag-and-drop request, or the
|
||||
FileChooser portal.
|
||||
2. Open and retain file descriptors before acknowledging the request, avoiding
|
||||
path replacement races.
|
||||
3. Expose only selected files through a private staging view; never expose the
|
||||
entire home directory by default.
|
||||
4. Stream from descriptors with bounded memory and cancellation support.
|
||||
|
||||
The native adapter should not attempt to translate every Windows path into a
|
||||
POSIX path. Explicitly selected files and well-defined staging directories are
|
||||
safer and work in sandboxed environments.
|
||||
|
||||
## Port mapping
|
||||
|
||||
Status: design complete; protocol attachment to UU is not implemented yet.
|
||||
|
||||
The data plane should use host sockets directly so mapped services refer to the
|
||||
Linux network namespace. The native broker will:
|
||||
|
||||
- support TCP first, then UDP after session and timeout semantics are proven;
|
||||
- bind loopback by default;
|
||||
- require explicit configuration before binding a LAN or wildcard address;
|
||||
- reject privileged ports unless a separately configured capability permits
|
||||
them;
|
||||
- enforce destination allowlists, connection limits, idle timeouts, and byte
|
||||
quotas;
|
||||
- resolve names through the host resolver without exposing arbitrary proxy
|
||||
environment variables to Wine;
|
||||
- close every listener and connection when `uur run` ends.
|
||||
|
||||
The remaining reverse-engineering task is the stable control-plane boundary
|
||||
between UU's `PortMappingModule` and its tunnel implementation. The adapter
|
||||
attaches at an API or helper-process boundary.
|
||||
|
||||
## Clipboard and phone text
|
||||
|
||||
Clipboard access belongs to the active desktop session. The preferred Wayland
|
||||
route is the Clipboard interface attached to the existing RemoteDesktop portal
|
||||
session. X11 uses normal selection ownership. Text payloads require strict size
|
||||
limits and must not be written to logs.
|
||||
|
||||
## Security invariants
|
||||
|
||||
- Every service authenticates its Wine-side proxy with a per-run random token.
|
||||
- Runtime endpoints bind only to loopback or use private Unix descriptors.
|
||||
- Payload lengths and concurrent sessions are bounded before allocation.
|
||||
- Native services run as the logged-in user; no root daemon handles content.
|
||||
- User content is absent from diagnostics.
|
||||
- Session shutdown revokes tokens, removes runtime files, closes listeners, and
|
||||
reaps child processes.
|
||||
+49
@@ -0,0 +1,49 @@
|
||||
# Nix and NixOS
|
||||
|
||||
The repository exports an x86_64 Linux package, an app, a development shell,
|
||||
and a NixOS module. The lock file pins NixOS/nixpkgs 26.05.
|
||||
|
||||
## Build or run from a checkout
|
||||
|
||||
```bash
|
||||
nix build
|
||||
nix run . -- doctor
|
||||
nix run . -- setup --accept-eula
|
||||
nix run . -- run
|
||||
```
|
||||
|
||||
The derivation builds the Rust supervisor, the musl/glibc-independent source
|
||||
components, the PipeWire helper, and all MinGW Win64 adapters. Runtime tools
|
||||
are wrapped into `PATH`; the UU client and Wine prefix remain in the user's XDG
|
||||
data directory.
|
||||
|
||||
## NixOS module
|
||||
|
||||
Add this repository as a flake input and import its module:
|
||||
|
||||
```nix
|
||||
{
|
||||
inputs.uur.url = "github:panxuc/uur";
|
||||
|
||||
outputs = { self, nixpkgs, uur, ... }: {
|
||||
nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
|
||||
system = "x86_64-linux";
|
||||
modules = [
|
||||
uur.nixosModules.default
|
||||
({ ... }: {
|
||||
programs.uur.enable = true;
|
||||
})
|
||||
];
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
The module installs the package, loads `uinput`, and registers uur's udev rule.
|
||||
The selected desktop still supplies its matching xdg-desktop-portal backend.
|
||||
|
||||
Override the package when following a fork or local build:
|
||||
|
||||
```nix
|
||||
programs.uur.package = inputs.uur.packages.x86_64-linux.uur;
|
||||
```
|
||||
@@ -0,0 +1,278 @@
|
||||
# Platform support and usage
|
||||
|
||||
`uur` selects Linux integrations by observable capability. Distribution and
|
||||
desktop names below help users install the right dependencies. `uur doctor`
|
||||
reports the active login session.
|
||||
|
||||
The current release target is Linux x86_64. Wine must be able to run the
|
||||
official 64-bit UU Remote client.
|
||||
|
||||
## Runtime dependency axes
|
||||
|
||||
| Capability | Preferred route | Alternatives |
|
||||
| --- | --- | --- |
|
||||
| Wayland video | ScreenCast portal + PipeWire | Portal virtual/window sources |
|
||||
| X11 video | Wine X11 capture | ScreenCast portal when explicitly selected |
|
||||
| Wayland input | RemoteDesktop portal | uinput; XTest for XWayland windows |
|
||||
| X11 input | XTest | uinput |
|
||||
| Audio | PulseAudio protocol | pipewire-pulse; ALSA |
|
||||
| Wine windows | X11/XWayland | Wine Wayland driver |
|
||||
| Application launch | `gio launch` | `gtk-launch` |
|
||||
| Suspend inhibition | Inhibit portal | Session continues without an inhibitor |
|
||||
| WOL persistence | NetworkManager + ethtool | ethtool runtime state |
|
||||
| Hardware inventory | DRM + VA-API/Vulkan Video | NVENC/NVDEC; software codec |
|
||||
|
||||
Common portal packages include `xdg-desktop-portal-gnome`,
|
||||
`xdg-desktop-portal-kde`, `xdg-desktop-portal-hyprland`,
|
||||
`xdg-desktop-portal-wlr`, `xdg-desktop-portal-lxqt`,
|
||||
`xdg-desktop-portal-xapp`, `xdg-desktop-portal-gtk`, and compositor-specific
|
||||
implementations. The active interfaces determine the selected path.
|
||||
|
||||
## Install by distribution family
|
||||
|
||||
### Arch package family
|
||||
|
||||
This includes Arch Linux and distributions that consume Arch packages or the
|
||||
AUR, such as EndeavourOS, CachyOS, Manjaro, Garuda Linux, Artix Linux, and
|
||||
Arch-based development systems. Init-system choice does not affect uur; it
|
||||
does not require a persistent systemd service.
|
||||
|
||||
From AUR:
|
||||
|
||||
```bash
|
||||
paru -S uur
|
||||
```
|
||||
|
||||
From a downloaded Arch package:
|
||||
|
||||
```bash
|
||||
sudo pacman -U ./uur-0.1.0-1-x86_64.pkg.tar.zst
|
||||
```
|
||||
|
||||
Install the portal backend supplied or recommended by the selected desktop.
|
||||
On a capture-only Wayland portal, ensure the active user can open
|
||||
`/dev/uinput`; the package installs a udev rule and a module-load entry.
|
||||
|
||||
### Debian package family
|
||||
|
||||
The deb artifact is intended for current Debian, Ubuntu, Linux Mint, Pop!_OS,
|
||||
Zorin OS, elementary OS, KDE neon, TUXEDO OS, Kali Linux, MX Linux, and other
|
||||
compatible derivatives:
|
||||
|
||||
```bash
|
||||
sudo apt install ./uur_0.1.0_amd64.deb
|
||||
```
|
||||
|
||||
The package manager resolves Wine, PipeWire, and the portal frontend. Install
|
||||
the session's portal backend separately when the distribution does not pull it
|
||||
in with the desktop environment.
|
||||
|
||||
### RPM package family
|
||||
|
||||
The rpm artifact targets current Fedora and distributions with compatible RPM
|
||||
dependency names. Install it with the native frontend:
|
||||
|
||||
```bash
|
||||
# Fedora and compatible systems
|
||||
sudo dnf install ./uur-0.1.0-1.x86_64.rpm
|
||||
|
||||
# openSUSE family
|
||||
sudo zypper install ./uur-0.1.0-1.x86_64.rpm
|
||||
```
|
||||
|
||||
RHEL, CentOS Stream, Rocky Linux, AlmaLinux, Oracle Linux, Nobara, Ultramarine,
|
||||
openSUSE Tumbleweed, and openSUSE Leap can use the RPM when its dependency names
|
||||
resolve, with the portable or source build covering other package layouts.
|
||||
|
||||
### Other conventional distributions
|
||||
|
||||
Gentoo, Funtoo, Void Linux, Slackware, Solus, Clear Linux, Mageia, OpenMandriva,
|
||||
PCLinuxOS, and similar mutable/FHS systems can use the portable archive when
|
||||
they provide compatible glibc, Wine, PipeWire, and portal libraries:
|
||||
|
||||
```bash
|
||||
sudo tar --zstd -C / -xf ./uur-0.1.0-linux-x86_64.tar.zst
|
||||
```
|
||||
|
||||
Alternatively, build and install for one user:
|
||||
|
||||
```bash
|
||||
cargo build --release --locked
|
||||
./hook/build.sh
|
||||
./capture/build.sh
|
||||
./scripts/install-user.sh
|
||||
```
|
||||
|
||||
The source build needs Rust, a native C compiler, PipeWire development files,
|
||||
`pkg-config`, and the MinGW-w64 x86_64 compiler and binutils. Package names are
|
||||
distribution-specific; uur does not invoke a package manager itself.
|
||||
|
||||
### Immutable, declarative, and musl systems
|
||||
|
||||
NixOS uses the repository flake and NixOS module described in [Nix and
|
||||
NixOS](nix.md). The module installs the package, udev integration, and `uinput`
|
||||
kernel module declaratively.
|
||||
|
||||
Alpine edge uses `packaging/alpine/APKBUILD` or the included musl container
|
||||
build. GNU Guix can package the same staged layout. Flatpak and Snap require
|
||||
host input, Wine, and portal permissions that are best expressed as dedicated
|
||||
manifests.
|
||||
|
||||
## Select the desktop integration path
|
||||
|
||||
### X11 session
|
||||
|
||||
Requirements: `DISPLAY`, Wine's X11 driver, and the XTest extension.
|
||||
|
||||
This path applies to full desktops and standalone window managers alike. Common
|
||||
examples include Xorg sessions of GNOME, Plasma, Cinnamon, MATE, Xfce, LXQt,
|
||||
LXDE, Budgie, Deepin, Pantheon, Trinity, and UKUI, plus i3, bspwm, awesome,
|
||||
Openbox, Fluxbox, IceWM, dwm, qtile, herbstluftwm, spectrwm, and FVWM.
|
||||
|
||||
Wine captures the X11 desktop directly and uur injects input with XTest. A
|
||||
ScreenCast portal is not required for this path.
|
||||
|
||||
### Wayland session with ScreenCast and RemoteDesktop portals
|
||||
|
||||
Requirements: a working session D-Bus, PipeWire, the xdg-desktop-portal
|
||||
frontend, and a backend exposing both `ScreenCast` and `RemoteDesktop`.
|
||||
|
||||
Where those interfaces are available, uur creates one combined session for
|
||||
capture and input. This is the preferred unprivileged route. Examples can
|
||||
include current GNOME Shell, KDE Plasma, niri with its recommended portal
|
||||
configuration, COSMIC, and other sessions whose selected portal backend
|
||||
advertises both interfaces. Interface availability—not the desktop name—makes
|
||||
the final decision.
|
||||
|
||||
### Wayland session with a capture-only portal
|
||||
|
||||
Requirements: ScreenCast/PipeWire plus writable `/dev/uinput` for full desktop
|
||||
input. XTest remains only a partial fallback for XWayland surfaces.
|
||||
|
||||
This route commonly applies to compositors using Hyprland or wlroots-oriented
|
||||
portal backends, including Hyprland, Sway, Wayfire, river, labwc, dwl, Waybox,
|
||||
and other wlroots-based sessions. It may also apply to a desktop whose portal
|
||||
installation is incomplete or whose selected backend omits RemoteDesktop.
|
||||
|
||||
Install the compositor's ScreenCast portal and enable uinput access. A
|
||||
`portals.conf` selects the backend when several are installed.
|
||||
|
||||
### Wine window backend
|
||||
|
||||
The UU user interface still needs a Wine display driver:
|
||||
|
||||
- Existing X11 and most Wayland desktop sessions normally use Wine through
|
||||
X11 or XWayland.
|
||||
- Compositors without built-in XWayland can use an external XWayland manager;
|
||||
niri, for example, integrates xwayland-satellite in current releases.
|
||||
- Wine builds with a usable native Wayland driver may run without XWayland,
|
||||
but that combination must still pass UU WebView2 and window-management tests.
|
||||
|
||||
This choice is independent from desktop capture. A client window can use
|
||||
XWayland while the controlled desktop is captured through the Wayland portal.
|
||||
|
||||
### Audio servers
|
||||
|
||||
Wine's PulseAudio driver is selected for both a native PulseAudio daemon and
|
||||
the `pipewire-pulse` compatibility server. A native PipeWire session without
|
||||
PulseAudio compatibility uses Wine's ALSA driver. `uur doctor` prints the live
|
||||
choice; this is independent from PipeWire's Wayland video role.
|
||||
|
||||
### Displays and virtual sources
|
||||
|
||||
```bash
|
||||
uur display status
|
||||
uur display source monitor
|
||||
uur display source window
|
||||
uur display source virtual
|
||||
```
|
||||
|
||||
The command clears the old restore token so the next Portal session can create
|
||||
or select the requested source. X11 exposes its XRandR topology to Wine.
|
||||
Wayland currently carries one selected stream; independent multi-stream
|
||||
switching is the next display-topology adapter.
|
||||
|
||||
## First run and normal use
|
||||
|
||||
After installing any package format:
|
||||
|
||||
```bash
|
||||
uur doctor
|
||||
uur setup --accept-eula
|
||||
uur run
|
||||
```
|
||||
|
||||
Optional host integration is managed explicitly:
|
||||
|
||||
```bash
|
||||
uur autostart enable
|
||||
uur autostart status
|
||||
uur wol status
|
||||
sudo uur wol enable --interface enp3s0
|
||||
```
|
||||
|
||||
The WOL command configures the real Linux adapter; it requires `ethtool`, and
|
||||
persists the setting through an active NetworkManager wired profile when one
|
||||
exists. The adapter name above is only an example—omit it for automatic
|
||||
physical-interface selection.
|
||||
|
||||
The package installs `uur.desktop` as the canonical application-menu entry.
|
||||
During setup, an existing Wine-generated Linux desktop entry for the official
|
||||
client is converted into a hidden compatibility alias whose command is also
|
||||
`uur run`. This keeps already pinned Dock, panel, or launcher favorites working
|
||||
without showing a duplicate application in new searches.
|
||||
|
||||
The `.lnk` file inside the Wine prefix remains available for diagnosis. Normal
|
||||
desktop integration launches `uur.desktop` or `uur run` so all helpers share
|
||||
the same lifetime.
|
||||
|
||||
The first Wayland run may show a portal chooser. Select the monitor to expose
|
||||
to remote controllers. A successful persistent portal grant is reused where
|
||||
the backend supports restore tokens.
|
||||
|
||||
UU Quick Launch is populated from visible XDG desktop entries every time
|
||||
`uur run` starts. This includes conventional packages and any containerized or
|
||||
portable application that publishes a valid `.desktop` entry. Application
|
||||
activation uses the desktop entry itself, so uur does not maintain a command
|
||||
translation table.
|
||||
|
||||
Stop only the managed session and its Wine prefix with:
|
||||
|
||||
```bash
|
||||
uur stop
|
||||
```
|
||||
|
||||
Useful input-backend overrides for diagnosis are:
|
||||
|
||||
```bash
|
||||
UUR_INPUT_BACKEND=portal uur run
|
||||
UUR_INPUT_BACKEND=uinput uur run
|
||||
UUR_INPUT_BACKEND=xtest uur run
|
||||
```
|
||||
|
||||
An override is a diagnostic tool, not a desktop-specific configuration. The
|
||||
default `auto` mode should be used after troubleshooting.
|
||||
|
||||
## Reading `uur doctor`
|
||||
|
||||
- `portal ScreenCast`: required to capture a Wayland desktop.
|
||||
- `portal RemoteDesktop`: preferred unprivileged Wayland input route.
|
||||
- `uinput (/dev/uinput)`: full-desktop fallback when RemoteDesktop is absent.
|
||||
- `DISPLAY`: required for Wine/X11 or Wine/XWayland and for XTest fallback.
|
||||
- `WAYLAND_DISPLAY`: identifies the active Wayland session.
|
||||
- `PipeWire`: required for the Wayland frame transport.
|
||||
|
||||
If both Wayland input routes are unavailable, XTest controls XWayland windows.
|
||||
|
||||
## Session model
|
||||
|
||||
Portal sessions operate in the logged-in desktop seat. Display-manager access
|
||||
uses a display-manager remote session, while headless operation uses a portal
|
||||
virtual source or a provisioned virtual display. `uur doctor` reports the
|
||||
active backend capabilities.
|
||||
|
||||
Relevant upstream documentation:
|
||||
|
||||
- [xdg-desktop-portal backend selection](https://flatpak.github.io/xdg-desktop-portal/docs/portals.conf.html)
|
||||
- [RemoteDesktop portal](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.RemoteDesktop.html)
|
||||
- [ScreenCast portal](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.ScreenCast.html)
|
||||
@@ -0,0 +1,43 @@
|
||||
# Upstream adaptation
|
||||
|
||||
UU Remote and uur have independent release lifecycles. The AUR package
|
||||
contains only uur, so a new proprietary client does not automatically require
|
||||
a package rebuild.
|
||||
|
||||
## Compatibility contract
|
||||
|
||||
The adapter depends on named operating-system APIs, not a table of UU versions,
|
||||
hashes, RVAs, or instruction patches:
|
||||
|
||||
- `wevtapi!EvtOpenPublisherMetadata` loads the compatibility shim;
|
||||
- `USER32!SendInput` is routed to the native input bridge;
|
||||
- GDI or DXGI desktop-capture entry points are routed to the frame adapter;
|
||||
- dynamic `GetProcAddress` resolution is intercepted as well as static imports.
|
||||
|
||||
`scripts/probe-upstream.sh` verifies those contracts across every PE file in
|
||||
an installed client tree. If an installer cannot be extracted directly, the
|
||||
probe installs it in a disposable Wine prefix and examines the result.
|
||||
|
||||
## Automation
|
||||
|
||||
The daily `upstream-watch` workflow:
|
||||
|
||||
1. resolves NetEase's official HTTPS release URL;
|
||||
2. verifies the Authenticode signature;
|
||||
3. extracts or installs the client in an ephemeral environment;
|
||||
4. runs the static API-contract probe;
|
||||
5. opens or updates a tracking issue with the result.
|
||||
|
||||
Static success means the generic adapter still has a viable attachment point;
|
||||
it is not presented as full runtime proof. A release candidate must also pass
|
||||
the Wine input round-trip and changing-frame canary before it is promoted.
|
||||
|
||||
Project releases build all package formats from the same source and publish
|
||||
immutable artifacts and checksums. A new proprietary client version alone does
|
||||
not cause a meaningless uur package rebuild.
|
||||
|
||||
## When a contract changes
|
||||
|
||||
Compatibility changes add a stable API adapter or transport behind the existing
|
||||
Rust traits. Capability probes select the route whose prerequisite API is
|
||||
available.
|
||||
@@ -0,0 +1,31 @@
|
||||
# Video and display backends
|
||||
|
||||
## Frame sources
|
||||
|
||||
- X11 sessions expose the XRandR monitor topology directly to Wine.
|
||||
- Wayland monitor and window sources use ScreenCast/PipeWire.
|
||||
- `uur display source virtual` requests the portal's Virtual source type and
|
||||
stores its restore token.
|
||||
- A multi-stream compositor will combine or expose several PipeWire nodes to
|
||||
UU's display topology for independent Wayland screen switching.
|
||||
|
||||
## Codec capabilities
|
||||
|
||||
`uur doctor` inventories the native acceleration APIs independently:
|
||||
|
||||
- DRM render nodes are the common device boundary;
|
||||
- VA-API covers Intel, AMD, and supported third-party drivers;
|
||||
- Vulkan Video is recognized through `VK_KHR_video_queue`;
|
||||
- NVENC and NVDEC are recognized through NVIDIA's encode/decode libraries;
|
||||
- software H.264 remains available through UU's current Windows path.
|
||||
|
||||
The native codec data path will consume the same BGRx frame transport used by
|
||||
the current capture adapter. A backend receives frame descriptors, negotiated
|
||||
color metadata, dimensions, and target latency; it returns encoded access units
|
||||
through one common interface. Codec selection can then prefer a verified
|
||||
hardware route and fall back to software without changing capture, display, or
|
||||
UU protocol code.
|
||||
|
||||
HDR requires a 10-bit frame format, color primaries, transfer function, and
|
||||
mastering metadata across the portal, PipeWire, encoder, and UU transport. The
|
||||
current BGRx transport is SDR.
|
||||
@@ -0,0 +1,30 @@
|
||||
# UU Windows feature map
|
||||
|
||||
The current UU server advertises these capability families. The Linux route is
|
||||
organized by host subsystem so each backend can evolve independently.
|
||||
|
||||
| UU capability family | Linux integration |
|
||||
| --- | --- |
|
||||
| Desktop, window, and emulator capture | X11/Wine or portal/PipeWire frame source |
|
||||
| Monitor, second screen, virtual display | XRandR topology or portal monitor/window/virtual sources |
|
||||
| Resolution, orientation, HiDPI, zoom | Display topology and stream geometry adapters |
|
||||
| 90/144 fps, true color, chroma, HDR | Frame format and encoder capability negotiation |
|
||||
| Keyboard, mouse, smart/virtual mouse | RemoteDesktop portal, uinput, XTest |
|
||||
| Touch, pen, gamepad | uinput tablet and future multitouch/gamepad devices |
|
||||
| Speaker, microphone, remote mute | Wine WASAPI over PulseAudio, pipewire-pulse, or ALSA |
|
||||
| Clipboard and phone text input | Portal clipboard and X11 selections |
|
||||
| File transfer v1-v4 | Wine-visible paths now; native XDG staging next |
|
||||
| Terminal and multiple sessions | Native PTY with ConPTY and mux ABI adapters |
|
||||
| Port mapping | Native host socket broker |
|
||||
| Quick Launch and remote application list | XDG desktop catalog and authenticated launcher |
|
||||
| Wallpaper and privacy wallpaper | Desktop wallpaper providers and capture routing |
|
||||
| Privacy screen | Compositor output policy or a dedicated virtual output |
|
||||
| Wake-on-LAN | Physical NIC configuration and UU capability reporting |
|
||||
| Lock, reboot, shutdown, task manager | logind/Polkit and desktop-native actions |
|
||||
| Auto unlock and login-screen access | Display-manager remote session integration |
|
||||
| Controlled update | Official release feed and compatibility probes |
|
||||
|
||||
The [App Store release history](https://apps.apple.com/hk/app/uu%E8%BF%9C%E7%A8%8B-%E8%BF%9C%E7%A8%8B%E5%8A%9E%E5%85%AC-%E6%B8%B8%E6%88%8F%E4%B8%B2%E6%B5%81/id1642306791?platform=mac)
|
||||
also confirms multi-session terminal support, view-only mode, automatic unlock,
|
||||
and remote terminal access on current Apple clients. The server capability
|
||||
table is broader and is the implementation map used by uur.
|
||||
Reference in new issue
Block a user