From 0da79a45eb28ac9bdd68ff52c1bdf2075143c7c0 Mon Sep 17 00:00:00 2001 From: VallierDev <24893073+VallierDev@users.noreply.github.com> Date: Thu, 15 Oct 2026 10:56:54 +0800 Subject: [PATCH] Record VM acceptance results and add guarded synthetic audio fixture --- AGENTS.md | 6 ++-- README.en.md | 6 ++-- README.md | 84 ++++++++++++++++++++++++---------------------------- 3 files changed, 44 insertions(+), 52 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 12f4796..430d8f9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -104,11 +104,11 @@ viewer does not reconnect them automatically. |---|---| | `~/.config/uuremote/config.json` | user_id, device_id, client_id, system_id, machine_guid, token, csrf; optional `sign_key`, `ffmpeg_root`. `$UU_CONFIG` overrides the path | | `~/.config/uuremote/host_settings.json` | persisted 安全 settings: auto_lock, keep_mute, mute_permanent | -| `UU_DESKTOP_BACKEND` | `auto` (default) / `x11` / `wayland` / `portal` / `none` (headless: no display; desktop offers ignored; tool peers get a nominal 1920x1080 screen + Allow permissions, which the port-mapping viewer requires) | +| `UU_DESKTOP_BACKEND` | `auto` (default) / `x11` / `wayland` / `portal` / `kms` (experimental feature) / `none` (headless: no display; desktop offers ignored; tool peers get a nominal 1920x1080 screen + Allow permissions, which the port-mapping viewer requires) | | `UU_INPUT_BACKEND` | `auto` (uinput on Wayland/portal when `/dev/uinput` is accessible, udev `uaccess` rule in README) / `uinput` / `native`. X11 keeps XTest (held-key autorepeat handling) | | `UU_TERMINAL_SHORTCUTS=0` | disable Ctrl+V → Ctrl+Shift+V in focused X11 terminals (Mac Cmd and Ctrl both arrive as VK_LCONTROL) | | `contrib/virtual-desktop/` | Xvfb + session (`UU_VIRTUAL_SESSION`, `UU_VIRTUAL_BUS=user|private`) for monitorless hosts; serve it with `DISPLAY=:99` | -| `UU_VIDEO_ENCODER=cpu` | force libx264 instead of NVENC | +| `UU_VIDEO_ENCODER` | `cpu`: libx264; `vaapi`: explicit Intel/AMD; unset: NVENC→CPU | | `UU_FFMPEG_ROOT` | FFmpeg prefix (`bin/ffmpeg`, libs in `lib/x86_64-linux-gnu`) | | `UU_AUDIO=0`, `UU_AUDIO_SOURCE` | disable sound / choose the Pulse source (default `@DEFAULT_MONITOR@`) | | `UU_LOGIN_WINDOW=0` | don't auto-open the login window | @@ -282,7 +282,7 @@ User-bus headless setup and the official Mac checklist: [virtual desktop accepta prototype; `UU_KMS_DEVICE=/dev/dri/card0`. Requires libdrm headers and deliberately granted `cap_sys_admin+ep`, plus card-node access. It is never automatically selected or granted privileges. Read the [KMS limitations, permission risk and revocation steps](docs/validation/kms.md) before use. -Lock/greeter and Intel/AMD hardware acceptance are unverified. Use uinput for input; clipboard +The VM GDM greeter capture was solid black (failed visual acceptance); lock/greeter support and Intel/AMD hardware remain unverified. Use uinput for input; clipboard is unavailable without a desktop session. No default release behavior changes. For headless desktop offers, [official error evidence remains incomplete](docs/validation/headless-error-evidence.md); the existing offer behavior is retained. diff --git a/README.en.md b/README.en.md index b4a0a6f..b7b69ae 100644 --- a/README.en.md +++ b/README.en.md @@ -200,10 +200,10 @@ Common environment variables: | Variable | Purpose | |---|---| | `UU_CONFIG` | Config file path (default `~/.config/uuremote/config.json`) | -| `UU_DESKTOP_BACKEND` | `auto` / `x11` / `wayland` / `portal` / `none` (headless) | +| `UU_DESKTOP_BACKEND` | `auto` / `x11` / `wayland` / `portal` / `kms` (experimental feature) / `none` (headless) | | `UU_INPUT_BACKEND` | `auto` (default: uinput on Wayland when accessible) / `uinput` / `native` | | `UU_TERMINAL_SHORTCUTS=0` | Disable the Ctrl+V paste rewrite in terminal windows | -| `UU_VIDEO_ENCODER=cpu` | Force CPU encoding | +| `UU_VIDEO_ENCODER` | `cpu`: libx264; `vaapi`: opt-in Intel/AMD; unset: existing NVENC→CPU | | `UU_FFMPEG_ROOT` | Use FFmpeg from this prefix | | `UU_AUDIO=0` | Disable sound; `UU_AUDIO_SOURCE` picks the PulseAudio source | | `UU_LOGIN_WINDOW=0` | Do not open the login window automatically when credentials are missing | @@ -320,7 +320,7 @@ User-bus headless setup and the official Mac checklist: [virtual desktop accepta prototype; `UU_KMS_DEVICE=/dev/dri/card0`. Requires libdrm headers and deliberately granted `cap_sys_admin+ep`, plus card-node access. It is never automatically selected or granted privileges. Read the [KMS limitations, permission risk and revocation steps](docs/validation/kms.md) before use. -Lock/greeter and Intel/AMD hardware acceptance are unverified. Use uinput for input; clipboard +The VM GDM greeter capture was solid black (failed visual acceptance); lock/greeter support and Intel/AMD hardware remain unverified. Use uinput for input; clipboard is unavailable without a desktop session. No default release behavior changes. For headless desktop offers, [official error evidence remains incomplete](docs/validation/headless-error-evidence.md); the existing offer behavior is retained. diff --git a/README.md b/README.md index 7c113f2..083eb2a 100644 --- a/README.md +++ b/README.md @@ -190,10 +190,10 @@ systemctl --user restart uuremote-native.service | 变量 | 作用 | |---|---| | `UU_CONFIG` | 配置文件路径(默认 `~/.config/uuremote/config.json`) | -| `UU_DESKTOP_BACKEND` | `auto` / `x11` / `wayland` / `portal` / `none`(无头模式) | +| `UU_DESKTOP_BACKEND` | `auto` / `x11` / `wayland` / `portal` / `kms`(实验性特性) / `none`(无头模式) | | `UU_INPUT_BACKEND` | `auto`(默认,Wayland 下可用时用 uinput)/ `uinput` / `native` | | `UU_TERMINAL_SHORTCUTS=0` | 关闭终端窗口里的 Ctrl+V 粘贴转换 | -| `UU_VIDEO_ENCODER=cpu` | 强制使用 CPU 编码 | +| `UU_VIDEO_ENCODER` | `cpu` 强制 CPU;`vaapi` 显式启用 Intel/AMD 硬编;未设置时保留 NVENC→CPU | | `UU_FFMPEG_ROOT` | 使用指定目录下的 FFmpeg | | `UU_AUDIO=0` | 关闭声音转发;`UU_AUDIO_SOURCE` 指定 PulseAudio 采集源 | | `UU_LOGIN_WINDOW=0` | 凭证缺失时不自动弹出登录窗口 | @@ -245,33 +245,29 @@ flowchart LR - [webrtc-rs](https://github.com/webrtc-rs/webrtc)、FFmpeg、GTK 等开源项目。 - 本项目的大部分代码在 Claude 和 Codex 的协助下完成。 -### VAAPI (opt-in / 显式启用) +### VAAPI 硬件编码(显式启用) -`UU_VIDEO_ENCODER=vaapi` selects Intel/AMD H.264 VAAPI; `UU_VAAPI_DEVICE` defaults to -`/dev/dri/renderD128` (render-node permissions required). No automatic VAAPI selection. -Both FFmpeg process and `--features inproc-av` upload NV12 frames to a VAAPI frame pool. -VBR uses the viewer bitrate preset and CQ-derived minimum QP, no B-frames, async depth 1, -AUD and the existing GOP/VFR timing. Unsupported device/driver/initialization falls back to libx264 -with a warning. Intel/AMD hardware acceptance is still required (未实机验证). +设置 `UU_VIDEO_ENCODER=vaapi` 使用 Intel/AMD H.264 VAAPI;`UU_VAAPI_DEVICE` 默认 +`/dev/dri/renderD128`,运行用户需要 render 节点权限。不会自动选择 VAAPI;设备或驱动初始化 +失败会明确警告并回退 libx264。外部 FFmpeg 和 `--features inproc-av` 均先转 NV12 再上传硬件帧。 +VBR 使用控制端码率预设及 CQ 对应的最小 QP,无 B 帧、async depth=1,并保留现有 GOP/VFR 规则。 +Intel/AMD 硬编**未实机验证**,不能把 virtio 的 CPU 回退测试当作硬编验收。 -### Virtual audio / 虚拟声卡 +### 静音运行与虚拟声卡 -The viewer's 静音运行 switch creates `uu-remote-sink` with `pactl module-null-sink`, -moves streams from the original default output and captures `uu-remote-sink.monitor`. -New output goes to this sink; streams explicitly pinned to other outputs are untouched. -The last desktop session restores the previous default output and unloads the module. -`mute_permanent` retains the physical mute policy, but still releases the virtual sink. -A private recovery record beside the config and a process lock recover crash leftovers on startup. -PulseAudio and PipeWire-pulse use the same `pactl` interface (install `pulseaudio-utils` on Debian, -`libpulse` on Arch). When routing is unavailable, the existing mute/monitor path remains. -Changing the switch restarts only the scoped audio encoder; normal non-muted capture is unchanged. -`virtual-audio-probe` temporarily routes output for five seconds and restores it (local diagnostic). +控制端开启「静音运行」后,程序用 `pactl module-null-sink` 创建 `uu-remote-sink`,保存原默认输出, +迁移其播放流并采集 `uu-remote-sink.monitor`。新播放也走虚拟输出;其他输出上的流不迁移。 +最后一个桌面连接结束后恢复原默认输出并卸载模块;`mute_permanent` 仍保留原物理静音策略。 +恢复记录保存在配置旁,权限 0600;进程锁避免重复实例抢占,异常退出后下次启动会恢复遗留路由。 +PulseAudio 和 PipeWire-pulse 都使用该接口(Debian 安装 `pulseaudio-utils`,Arch 安装 `libpulse`)。 +路由失败时保留原静音/monitor 方案。开关变化仅重启当前音频编码器,未开启时采集方式保持不变。 +本地诊断命令 `virtual-audio-probe` 会临时切换输出五秒并恢复。 -### Virtual desktop user bus +### 虚拟桌面的用户总线 -The supervisor imports DISPLAY and XAUTHORITY into the linger user bus, waits for authenticated -X11 readiness, and keeps its cleanup trap alive. The sample drop-in uses `%t/uu-virtual-99.Xauthority`. -Use a dedicated headless account. See the [setup and official Mac acceptance checklist](contrib/virtual-desktop/ACCEPTANCE.md). +默认 `UU_VIRTUAL_BUS=user`:监督脚本将 DISPLAY/XAUTHORITY 导入 linger 用户总线,等待经过认证的 +X11 就绪后通知 systemd;退出时清理 Xvfb。示例主机 drop-in 使用 `%t/uu-virtual-99.Xauthority`。 +请使用没有真实图形会话的专用账号;参见[设置与官方 Mac 验收清单](contrib/virtual-desktop/ACCEPTANCE.md)。 ### Arch Linux / Omarchy @@ -282,27 +278,23 @@ cargo test --locked --features wayland cargo build --release --features wayland ``` -Omarchy uses Hyprland: run in its user session, select `UU_DESKTOP_BACKEND=wayland`, -and retain `WAYLAND_DISPLAY` / `XDG_RUNTIME_DIR`. This requires wlr-screencopy and the -virtual input protocols supported by Hyprland; other compositors may need `--features wayland,portal`. -For uinput, load `uinput` and apply the uaccess rule above; seat ACLs require an active login. -For unattended accounts, explicitly restrict `/dev/uinput` access to a dedicated group. -This permission can inject into the whole seat, including lock/greeter screens. -`UU_INPUT_BACKEND=uinput` requests kernel devices; verify startup actually reports uinput. -Optional VAAPI: `intel-media-driver` (modern Intel) or `libva-mesa-driver` (AMD), `libva-utils` -for `vainfo`. Optional KMS: `libdrm`. Virtual Xfce: `xorg-server-xvfb xorg-xauth xorg-xdpyinfo -xfce4-session xfce4-panel xfdesktop xfwm4 gnome-terminal`. -Rolling Arch FFmpeg may be newer than supported `inproc-av` (FFmpeg 6.x); use the default process -pipeline or build against a separate FFmpeg 6 prefix. Do not downgrade the system FFmpeg. -User-bus headless setup and the official Mac checklist: [virtual desktop acceptance](contrib/virtual-desktop/ACCEPTANCE.md). +Omarchy 使用 Hyprland:在其用户会话中运行,设置 `UU_DESKTOP_BACKEND=wayland`,保留 +`WAYLAND_DISPLAY` 和 `XDG_RUNTIME_DIR`。其他合成器可能需要 `--features wayland,portal`。 +uinput 需加载内核模块并应用上文 uaccess 规则;无人登录账号需要专用组的受限授权。 +该权限能向整个 seat(包括锁屏/登录界面)注入输入。设置 `UU_INPUT_BACKEND=uinput` 后, +仍须确认启动日志实际选择了 uinput。 -### Experimental KMS / 实验后端 +VAAPI 可选包:Intel 新显卡用 `intel-media-driver`,AMD 用 `libva-mesa-driver`,`libva-utils` 提供 +`vainfo`。KMS 依赖 `libdrm`。虚拟 Xfce 依赖 `xorg-server-xvfb xorg-xauth xorg-xdpyinfo +xfce4-session xfce4-panel xfdesktop xfwm4 gnome-terminal`。 +滚动 Arch 的 FFmpeg 可能超出 `inproc-av` 支持的 6.x;请使用默认进程方案或独立的 FFmpeg 6 前缀, +不要降级系统 FFmpeg。当前 Arch/Hyprland VM 验证结果见[开发验证记录](docs/validation/v017-results.md)。 -`--features kms` plus explicit `UU_DESKTOP_BACKEND=kms` enables a limited linear-framebuffer -prototype; `UU_KMS_DEVICE=/dev/dri/card0`. Requires libdrm headers and deliberately granted -`cap_sys_admin+ep`, plus card-node access. It is never automatically selected or granted privileges. -Read the [KMS limitations, permission risk and revocation steps](docs/validation/kms.md) before use. -Lock/greeter and Intel/AMD hardware acceptance are unverified. Use uinput for input; clipboard -is unavailable without a desktop session. No default release behavior changes. -For headless desktop offers, [official error evidence remains incomplete](docs/validation/headless-error-evidence.md); -the existing offer behavior is retained. +### 实验性 KMS 截屏 + +编译 `--features kms` 后显式设置 `UU_DESKTOP_BACKEND=kms`;`UU_KMS_DEVICE` 默认 +`/dev/dri/card0`。需要 libdrm、card 节点访问权及主动授予的 `cap_sys_admin+ep`。 +程序不会自动启用或授权;此 capability 权限很大,先阅读[限制、安全风险及撤销步骤](docs/validation/kms.md)。 +当前仅为线性帧缓冲原型:VM 的 GDM 截图仍是黑屏,**没有通过登录界面视觉验收**,不承诺锁屏可用。 +键鼠需 uinput;没有桌面会话时不提供剪贴板。 +无头桌面错误码的[官方证据仍不足](docs/validation/headless-error-evidence.md),因此保持原有 offer 行为。