Compare commits

...
4 Commits
Author SHA1 Message Date
VallierDevandClaude Opus 5.5 edd4c9250c Release v0.2.9: HEVC picture-boundary AUs (#48), VAAPI buffer (#47)
Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-18 16:33:33 +08:00
ca49232674 HEVC: split access units by picture boundaries; no -aud for hevc_vaapi (#48)
* HEVC: split access units by picture boundaries, and stop passing -aud to hevc_vaapi

hevc_vaapi with `-aud 1` writes an AUD only at IRAPs and drops every other picture from
the bitstream: a 90-frame 640x360 clip came out as 3 IDRs and no P-frames. The reader
splits access units on AUDs, so each "frame" became one IDR plus a whole GOP, and the
IRAP gate then rejected all of them - the H.265 path sent no video at all (measured
~12 kbit/s outbound against 4-6 Mbit/s for H.264).

HEVC now leaves AUD off and hevc_au_offsets() splits on RFC 7798 picture boundaries (an
AUD, or the first NAL after a VCL NAL that is non-VCL or starts a picture), which also
keeps multi-slice pictures in one unit and covers the libx265/NVENC shapes. Parameter
sets still repeat in-band ahead of every IDR, so no out-of-band sprop is needed.

The fixed-input probe hardcoded H.264 in three places (settings, output muxer, first-unit
check), which is why this path was never measurable; it now follows UU_VIDEO_CODEC.

Verified with desktop-video-probe (90-frame fixed input): hevc_vaapi and libx265 both
emit 90 frames, first unit an IRAP with its parameter sets.

Assisted-by: DeepSeek V4.1 Flash-1017

* HEVC: keep suffix SEI, filler and end markers with the preceding picture

RFC 7798 / H.265 7.4.2.4.4 lets only AUD, VPS/SPS/PPS, prefix SEI and types
41-44/48-55 open an access unit; trailing NALs stay with the picture. Verified on
an RTX 3090 with the fixed-input probe: hevc_nvenc and libx265 both yield 90/90
decodable units with an IRAP first.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

---------

Co-authored-by: VallierDev <[email protected]>
Co-authored-by: Claude Opus 5.5 <[email protected]>
2026-10-18 16:32:35 +08:00
NuoFang cb8253febf VAAPI: opt-in UU_VAAPI_BUFFER_MS for the VBV buffer (#47)
The 100-500 kbit default keeps NVENC keyframes inside the buffer, but VAAPI quantizes a
whole desktop keyframe when the buffer is that small: on a 2560x1440 H.264 VAAPI stream
capped at 30 Mbit/s the first IDR measured 59,910 bytes and the picture blurred once per
GOP before sharpening back.

UU_VAAPI_BUFFER_MS (10-1000 ms, VAAPI only) sizes the buffer as bitrate x ms/1000. With
250 ms on the same input the first IDR measured 142,397 bytes and the worst-frame Y-SSIM
over 180 static frames went from 0.9492 to 0.9933, with no rise in average bitrate.

Opt-in: unset, out of range or unparsable keeps the old buffer.

Assisted-by: DeepSeek V4.1 Flash-1017
2026-10-18 15:31:00 +08:00
VallierDevandClaude Opus 5.5 696cf10e33 docs: NAS Docker deployment guide; link it and the ghcr image from the READMEs
Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-18 11:52:36 +08:00
9 changed files with 324 additions and 86 deletions

No files matched your search

Generated
+1 -1
View File
@@ -2741,7 +2741,7 @@ checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
[[package]]
name = "uu-remote-linux"
version = "0.2.8"
version = "0.2.9"
dependencies = [
"async-trait",
"base64 0.22.1",
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "uu-remote-linux"
version = "0.2.8"
version = "0.2.9"
edition = "2021"
default-run = "uuremote-server"
authors = ["uu-remote-linux contributors"]
+20 -3
View File
@@ -10,6 +10,8 @@
> It now also ships an **experimental Linux viewer**, `uuremote-viewer`, that controls official Windows / Mac hosts or this
> project's host from Linux (desktop, file transfer, terminal, port mapping, remote assistance; see
> [below](#experimental-native-viewer-uuremote-viewer)).
> Desktop-less **Synology / NAS** boxes can run it in Docker: [deployment guide](docs/deploy-nas-docker.md#english), image
> [`ghcr.io/vallierdev/uu-remote-linux`](https://github.com/VallierDev/uu-remote-linux/pkgs/container/uu-remote-linux).
>
> This is a personal hobby project. **It is not affiliated with NetEase and is not an official client.**
> If NetEase considers this project infringing or inappropriate, please DM me on X
@@ -237,7 +239,8 @@ starts at boot without a login. The viewer's remote desktop keeps showing "conne
Log in once with `uuremote-server login --no-gui` (QR in the terminal).
**Synology / NAS (Docker)**: run headless mode in a container on a desktop-less NAS (file transfer, terminal, port
mapping): image `ghcr.io/vallierdev/uu-remote-linux`, see [docker/README.md](docker/README.md). Verified on Synology DSM 7.3 (x86_64).
mapping): image [`ghcr.io/vallierdev/uu-remote-linux`](https://github.com/VallierDev/uu-remote-linux/pkgs/container/uu-remote-linux),
see the [NAS deployment guide](docs/deploy-nas-docker.md#english). Verified on Synology DSM 7.3 (x86_64).
**Paste files from a Mac terminal**: when using Ghostty over UU's SSH port mapping,
the optional [Mac SSH paste companion](contrib/macos-ssh/README.md) uploads files
@@ -277,6 +280,7 @@ Common environment variables:
| `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`: libx264; `vaapi`: opt-in Intel/AMD; `nvenc`: force NVENC; unset: NVENC only when an NVIDIA driver is loaded, else CPU |
| `UU_VAAPI_BUFFER_MS` | VAAPI VBV buffer in ms (10-1000, VAAPI only); raise it when keyframes are squeezed into a blur at high resolution |
| `UU_FFMPEG_ROOT` | Use FFmpeg from this prefix |
| `UU_AUDIO=0` | Disable sound; `UU_AUDIO_SOURCE` picks the PulseAudio source |
| `UU_REMOTE_ASSIST=0` | Disable remote assistance (no guest assistance before sign-in either) |
@@ -349,8 +353,14 @@ capability lists; the official Mac viewer lists H265 first in its SDP). The firs
synthetic frame and announces encoder support with CodecNegotiation. `hevc_nvenc`, `libx265` and explicit
`UU_VIDEO_ENCODER=vaapi` (`hevc_vaapi`); hardware failure falls back to software HEVC, then to H.264.
`UU_VIDEO_CODEC=h264` forces H.264. 8-bit; true color 4:4:4 uses hevc_nvenc `rext` / libx265 `main444-8`.
Verified with the official Mac viewer on an RTX 3090 (hevc_nvenc, including 4:4:4); libx265, hevc_vaapi and
other viewers are not hardware-verified.
Verified with the official Mac viewer on an RTX 3090 (hevc_nvenc, including 4:4:4) and with the official Android
viewer on Intel Alder Lake-P (iHD): 2560x1440 fully hardware-encoded, 58 fps decoded at about 10 ms. libx265 is
still not verified against a real viewer.
HEVC access units are split on RFC 7798 picture boundaries instead of AUDs: `hevc_vaapi` with `-aud 1` writes an
AUD only at IRAPs and drops every other picture from the bitstream, so an AUD-based reader turns a whole GOP into
one "frame" and the IRAP gate then rejects all of them: the connection stalls at "transferring" while the host
sends about 12 kbit/s. `UU_VIDEO_CODEC=h265` selects H.265 explicitly for A/B diagnosis.
### VAAPI (opt-in / 显式启用)
@@ -363,6 +373,13 @@ with a warning. Accepted on Intel UHD 770 (iHD) with the default FFmpeg process
viewer (presets, fps, scaling, reconnect; no fallback, ~40% less CPU than libx264). AMD and the `inproc-av`
VAAPI path are not hardware-verified.
The default VAAPI VBV buffer (100-500 kbit) squeezes keyframes hard at high resolution: on a 2560x1440
H.264 VAAPI stream capped at 30 Mbit/s the first IDR measured 59,910 bytes and the picture blurred at
every GOP before sharpening back. `UU_VAAPI_BUFFER_MS=250` (buffer = bitrate cap x ms/1000) restored that
first IDR to 142,397 bytes and raised the worst-frame Y-SSIM from 0.9492 to 0.9933 without raising the
average bitrate. Off by default; unset or out of the 10-1000 ms range keeps the old buffer. Larger
keyframes can queue briefly on a weak link, so start at 250 ms.
### Virtual audio / 虚拟声卡
The viewer's 静音运行 switch creates the null sink `uu-remote-sink`,
+17 -3
View File
@@ -8,6 +8,7 @@
> 装上之后,就能用官方的 Mac / Windows / 手机客户端远程控制你的 Linux 电脑。
> 现在还附带一个**实验性 Linux 控制端** `uuremote-viewer`:在 Linux 上用 UU 账号远控官方 Windows / Mac 被控端或本项目主机
> (桌面、文件传输、终端、端口映射、远程协助,详见[下文](#实验性原生控制端uuremote-viewer))。
> 没有桌面的**群晖 / NAS** 也能用 Docker 部署:[部署指南](docs/deploy-nas-docker.md),镜像 [`ghcr.io/vallierdev/uu-remote-linux`](https://github.com/VallierDev/uu-remote-linux/pkgs/container/uu-remote-linux)。
>
> 这是个人兴趣项目,**与网易无关,也不是官方客户端**。如果网易认为本项目侵权或有不妥,
> 请在推特私信我 **[@ai_fengshou](https://x.com/ai_fengshou)**,我会第一时间自行下架。
@@ -209,8 +210,9 @@ install -Dm644 contrib/desktop/uu-remote-linux.desktop ~/.local/share/applicatio
再执行 `loginctl enable-linger $USER`,这样开机后不用登录,systemd 用户服务(以及 `XDG_RUNTIME_DIR`、用户 D-Bus)也会自动启动。
无头模式下控制端点「远程桌面」会一直显示正在连接,这是正常的。首次登录用 `uuremote-server login --no-gui` 在终端里扫码。
**群晖 / NAS(Docker)**:没有桌面的 NAS 可以用容器运行无头模式(文件传输、终端、端口映射),
镜像 `ghcr.io/vallierdev/uu-remote-linux`,步骤见 [docker/README.md](docker/README.md)。已在群晖 DSM 7.3(x86_64)上实测三项功能。
**群晖 / NAS(Docker)**:没有桌面的 NAS 可以用容器运行无头模式(文件传输、终端、端口映射)。
镜像 [`ghcr.io/vallierdev/uu-remote-linux`](https://github.com/VallierDev/uu-remote-linux/pkgs/container/uu-remote-linux),
**部署步骤见 [群晖 / NAS 部署指南](docs/deploy-nas-docker.md)**。已在群晖 DSM 7.3(x86_64)上实测三项功能。
**Mac 终端粘贴文件**:使用 Ghostty 通过 UU 端口映射连接 SSH 时,可安装
[Mac SSH 粘贴助手](contrib/macos-ssh/README.md)。在 Finder 复制文件后按 Command-V,
@@ -248,6 +250,7 @@ systemctl --user restart uuremote-native.service
| `UU_INPUT_BACKEND` | `auto`(默认,Wayland 下可用时用 uinput)/ `uinput` / `native` |
| `UU_TERMINAL_SHORTCUTS=0` | 关闭终端窗口里的 Ctrl+V 粘贴转换 |
| `UU_VIDEO_ENCODER` | `cpu` 强制 CPU;`vaapi` 显式启用 Intel/AMD 硬编;`nvenc` 强制 NVENC;未设置时检测到 NVIDIA 驱动才用 NVENC,否则用 CPU |
| `UU_VAAPI_BUFFER_MS` | VAAPI 的 VBV 缓冲(10–1000 ms,仅 `UU_VIDEO_ENCODER=vaapi` 时生效);高分辨率下关键帧被压糊时用它换稳定画质 |
| `UU_FFMPEG_ROOT` | 使用指定目录下的 FFmpeg |
| `UU_AUDIO=0` | 关闭声音转发;`UU_AUDIO_SOURCE` 指定 PulseAudio 采集源 |
| `UU_LOGIN_WINDOW=0` | 凭证缺失时不自动弹出登录窗口 |
@@ -311,7 +314,12 @@ flowchart LR
中优先列出 H.265)。首次桌面连接会用合成帧探测实际编码能力,并通过 CodecNegotiation 告知客户端。支持 `hevc_nvenc`、
`libx265`、显式 `UU_VIDEO_ENCODER=vaapi` 的 `hevc_vaapi`;硬件失败先回落软件 HEVC,再回落 H.264。
`UU_VIDEO_CODEC=h264` 强制使用 H.264。8-bit;真彩 4:4:4 使用 hevc_nvenc `rext` / libx265 `main444-8`。
已用官方 Mac 客户端在 RTX 3090(hevc_nvenc,含 4:4:4)实机验收;libx265、hevc_vaapi 及其他客户端尚未实机验证。
已用官方 Mac 客户端在 RTX 3090(hevc_nvenc,含 4:4:4)实机验收;`hevc_vaapi` 配官方 Android 客户端也已实机验收
(Intel Alder Lake-P / iHD,2560×1440 全程硬件编码,客户端 58 fps 解码、约 10 ms 延迟);`libx265` 仍未经控制端验收。
HEVC 的访问单元按 RFC 7798 的图片边界切分,不依赖 AUD:`hevc_vaapi` 带 `-aud 1` 时只在 IRAP 处写 AUD,并把其余
画面从码流里丢掉,读取端按 AUD 切分就会把整个 GOP 当成一帧,再被 IRAP 门控全部拒绝——对外表现为连接停在
「正在传输画面」,而主机侧只有约 12 kbit/s。`UU_VIDEO_CODEC=h265` 可显式选中 H.265,便于对照排查。
### VAAPI 硬件编码(显式启用)
@@ -321,6 +329,12 @@ flowchart LR
VBR 使用控制端码率预设及 CQ 对应的最小 QP,无 B 帧、async depth=1,并保留现有 GOP/VFR 规则。
Intel 核显(UHD 770,iHD 驱动)已实机验收:默认的外部 FFmpeg 管线用官方 Mac 控制端测试了各档画质、帧率、缩放和重连,全程硬件编码、无回退,CPU 占用比 libx264 低约 40%。**AMD 显卡和 `--features inproc-av` 管线的 VAAPI 尚未实机验证。**
高分辨率下 VAAPI 的默认 VBV 缓冲(100–500 kbit)会把关键帧压得过狠:2560×1440 H.264 VAAPI、30M
上限、静止画面上实测首个 IDR 只有 59,910 字节,画面每隔一个 GOP 糊一下再慢慢恢复。设
`UU_VAAPI_BUFFER_MS=250`(按 `码率上限 × 毫秒 / 1000` 放大 VBV)后首个 IDR 为 142,397 字节,
最低帧 Y-SSIM 从 0.9492 升到 0.9933,平均码率没有上升。默认不启用,未设置或超出 10–1000 ms
仍用原缓冲;代价是关键帧变大,弱网下可能出现瞬时排队,建议从 250 ms 试起。
### 静音运行与虚拟声卡
控制端开启「静音运行」后,程序创建虚拟输出 `uu-remote-sink`,保存原默认输出,
+1 -1
View File
@@ -1,7 +1,7 @@
# Unofficial UU Remote Linux host in a container, for NAS boxes (Synology DSM, etc.) without a desktop.
# Headless mode: file transfer, terminal and port mapping; no remote desktop. Uses the published release binary.
FROM ubuntu:24.04
ARG VERSION=v0.2.8
ARG VERSION=v0.2.9
LABEL org.opencontainers.image.source="https://github.com/VallierDev/uu-remote-linux" \
org.opencontainers.image.description="Unofficial UU Remote Linux host, headless (file transfer, terminal, port mapping)" \
org.opencontainers.image.licenses="GPL-3.0"
+6 -60
View File
@@ -1,63 +1,9 @@
# 群晖 / NAS 容器部署(无桌面)
# Docker(群晖 / NAS,无桌面)
**简体中文** | [English](#english)
本目录是 [`ghcr.io/vallierdev/uu-remote-linux`](https://github.com/VallierDev/uu-remote-linux/pkgs/container/uu-remote-linux) 镜像的构建文件。
**部署和使用步骤见 [docs/deploy-nas-docker.md](../docs/deploy-nas-docker.md)。**
在没有桌面的 NAS(群晖 DSM 等,x86_64)上,用容器运行本项目主机,供官方 UU 远程客户端使用:
This directory builds the `ghcr.io/vallierdev/uu-remote-linux` image; see
[docs/deploy-nas-docker.md](../docs/deploy-nas-docker.md#english) for deployment.
- **文件传输**:收发 `/data` 里的文件(把你的共享文件夹挂到 `/data`)。
- **终端**:进入容器内的 bash,当前目录为 `/data`。
- **端口映射**:在外网经 UU 访问家里局域网的服务(NAS 管理页、路由器、其他电脑……)。
不提供远程桌面(NAS 没有图形界面)。容器里运行的是 GitHub 发布包中的同一个 `uuremote-server`。
## 安装
在 NAS 上(SSH 登录后用 root 或 `sudo`),进入本目录:
```sh
mkdir -p config data && chmod 700 config
docker compose build # 或者直接使用 ghcr.io/vallierdev/uu-remote-linux 镜像
```
**首次登录**(只需一次):在你自己的终端里运行,用手机 UU 远程扫描终端里显示的二维码并确认。
二维码等同于登录凭据,不要截图或发给别人。
```sh
docker compose run --rm uu-remote login --no-gui
```
登录信息保存在 `config/config.json`(权限 0600),请妥善保管 `config` 目录。然后启动:
```sh
docker compose up -d
docker compose logs -f # 看到 availability=Some("ready") 即可在客户端设备列表里找到它
```
**群晖 Container Manager**:也可以在「项目」里新建项目,选本目录的 `compose.yaml`;首次登录仍需在 SSH 里执行上面的 `login` 命令。
## 说明
- `network_mode: host` 让 WebRTC 走直连;改用默认桥接网络也能用,但更常走中转,延迟更高。
- 把 `compose.yaml` 里的 `./data` 改成要开放的共享文件夹,例如 `/volume1/homes/你的用户名`。只挂需要远程访问的目录。
- 终端操作的是容器而不是 NAS 系统本身;需要操作 NAS 本机时请用 DSM 自带的 SSH。
- 升级:重新 `docker compose build --pull`(或拉取新镜像)后 `docker compose up -d`;`config` 保留即可免再登录。
---
## English
Run this project's host in a container on a desktop-less NAS (Synology DSM, x86_64) for the official UU Remote clients:
file transfer (`/data`), terminal (bash inside the container) and port mapping into your LAN. No remote desktop.
```sh
mkdir -p config data && chmod 700 config
docker compose build
docker compose run --rm uu-remote login --no-gui # scan the terminal QR with the UU mobile app (the QR is a credential)
docker compose up -d
docker compose logs -f # wait for availability=Some("ready")
```
Credentials are kept in `config/config.json`. Mount only the folders you want to reach as `/data`.
Host networking gives WebRTC direct paths; bridge networking works but relays more often.
**Unofficial project, not affiliated with NetEase.**
自行构建 / build locally: `docker compose build`(`Dockerfile` 从 GitHub 发布包安装 `uuremote-server`,可用 `--build-arg VERSION=vX.Y.Z` 指定版本)。
+133
View File
@@ -0,0 +1,133 @@
# 群晖 / NAS 部署指南(Docker,无桌面)
**简体中文** | [English](#english)
镜像:[`ghcr.io/vallierdev/uu-remote-linux`](https://github.com/VallierDev/uu-remote-linux/pkgs/container/uu-remote-linux)
(标签 `latest` 或具体版本如 `v0.2.8`)
把本项目主机跑在没有桌面的 NAS 上之后,就能在外面用官方 UU 远程客户端(手机 / Mac / Windows):
| 功能 | 说明 |
|---|---|
| 文件传输 | 收发 NAS 上的文件(只开放你挂进容器的文件夹) |
| 终端 | 打开容器里的命令行(bash) |
| 端口映射 | 经 UU 访问家里局域网的服务:NAS 管理页、路由器、其他电脑的 SSH / 远程桌面等 |
**不提供远程桌面**(NAS 没有图形界面,点「远程桌面」会一直显示正在连接,属正常)。
## 准备
- x86_64 的 NAS(群晖 DSM 7.2 及以上已安装「Container Manager」,或任意装了 Docker 的 Linux NAS)。ARM 机型暂不支持。
- 能 SSH 登录 NAS(群晖:控制面板 → 终端机和 SNMP → 启用 SSH),并有管理员权限(`sudo`)。
- 手机上的 UU 远程 App,用于扫码登录。
## 第一步:建目录和配置
SSH 登录 NAS,新建一个目录(下面以 `/volume1/docker/uu-remote` 为例):
```sh
sudo mkdir -p /volume1/docker/uu-remote/config
sudo chmod 700 /volume1/docker/uu-remote/config
cd /volume1/docker/uu-remote
```
新建 `compose.yaml`,内容如下。把 `/volume1/共享文件夹` 改成你想远程访问的文件夹(可以写多行挂多个):
```yaml
services:
uu-remote:
image: ghcr.io/vallierdev/uu-remote-linux:latest
container_name: uu-remote
network_mode: host # 让远程连接尽量走直连,速度更快
restart: unless-stopped
volumes:
- ./config:/config # 登录信息,请勿外传
- /volume1/共享文件夹:/data # 文件传输和终端看到的目录
```
## 第二步:扫码登录(只需一次)
```sh
sudo docker compose pull
sudo docker compose run --rm uu-remote login --no-gui
```
终端里会显示一个二维码:用手机 UU 远程扫码并确认。看到登录成功的提示后,按 `Ctrl+C` 退出(如果没有自动退出)。
> 二维码等同于你的登录凭据,**不要截图或发给别人**。登录信息保存在 `config/config.json`。
> 一定要用上面的 `docker compose run`(主机网络),这样设备在列表里显示的是 NAS 的名字;
> 若用普通 `docker run` 登录,设备名会是一串随机字符。
## 第三步:启动
```sh
sudo docker compose up -d
sudo docker compose logs -f
```
日志里出现 `availability=Some("ready")` 就说明上线了,按 `Ctrl+C` 退出日志查看(容器继续在后台运行)。
之后 NAS 开机会自动启动它。
**用群晖界面管理**:Container Manager → 项目 → 新增,路径选 `/volume1/docker/uu-remote`,会自动读取 `compose.yaml`。
首次登录仍需在 SSH 里执行第二步。
## 使用
打开官方 UU 远程客户端,在「我的设备」里找到你的 NAS(显示为 Windows 设备,这是正常的):
- **文件传输**:浏览、上传、下载 `/data` 里的文件。
- **终端**:进入容器的命令行,当前目录是 `/data`。注意这是容器而不是 NAS 系统本身。
- **端口映射**:例如目标填 `127.0.0.1`、端口 `5000`,就能在本地浏览器打开 NAS 的 DSM 管理页;
填局域网里其他设备的地址和端口(如 `192.168.1.10:22`)即可访问那台设备的服务。
## 更新
```sh
cd /volume1/docker/uu-remote
sudo docker compose pull && sudo docker compose up -d
```
`config` 目录保留即可,不用重新登录。
## 停用与移除
```sh
sudo docker compose down # 停止并删除容器
```
再在官方客户端的设备列表里删除这台设备;如需彻底清除登录信息,删除 `config` 目录。
## 常见问题
- **设备名是一串随机字符**:登录时没有用主机网络。删除 `config/config.json`,按第二步用 `docker compose run` 重新登录。
- **一直不上线**:`sudo docker compose logs --tail 100` 查看日志;确认 NAS 能访问外网。
- **连接慢、经常卡**:确认 `network_mode: host` 没有被去掉。
- **想要远程桌面**:NAS 上不支持;请在有桌面的 Linux 电脑上安装主机端(见主 README)。
安全提示:只挂需要远程访问的文件夹;端口映射可以访问 NAS 所在局域网,请保管好 UU 账号。
---
## English
Image: [`ghcr.io/vallierdev/uu-remote-linux`](https://github.com/VallierDev/uu-remote-linux/pkgs/container/uu-remote-linux)
Runs this project's host headless on a desktop-less NAS (x86_64, e.g. Synology DSM 7.2+ with Container Manager) for the
official UU Remote clients: **file transfer** (folders you mount at `/data`), **terminal** (bash inside the container) and
**port mapping** into your LAN. No remote desktop.
```sh
sudo mkdir -p /volume1/docker/uu-remote/config && sudo chmod 700 /volume1/docker/uu-remote/config
cd /volume1/docker/uu-remote
# compose.yaml: image ghcr.io/vallierdev/uu-remote-linux:latest, network_mode: host,
# volumes ./config:/config and /volume1/your-share:/data (see the Chinese section above)
sudo docker compose pull
sudo docker compose run --rm uu-remote login --no-gui # scan the QR with the UU mobile app; the QR is a credential
sudo docker compose up -d
sudo docker compose logs -f # wait for availability=Some("ready")
```
Update with `docker compose pull && docker compose up -d` (keep `config/`). Remove with `docker compose down`, then delete
the device in the official client.
**Unofficial project, not affiliated with NetEase.**
+19
View File
@@ -0,0 +1,19 @@
修复 H.265 + VAAPI 时手机卡在「正在传输」;VAAPI 可选加大编码缓冲。/ Fix H.265 + VAAPI stalling at "transferring"; optional VAAPI VBV buffer.
### 修复 / Fixed
- **H.265 用 VAAPI 硬件编码时没有画面**(#48,感谢 @NuoFang6):`hevc_vaapi` 只在关键帧处写帧分隔符,主机按分隔符切帧,
把整组画面当成一帧后全部被拦下,被控端几乎不发画面,手机停在「正在传输」。现在按图像边界切分 H.265 访问单元,
不再依赖帧分隔符;维护者补充了后缀 SEI 等尾随单元的处理。
已实测:作者在 Intel 核显 + 官方安卓客户端上(2560×1440,约 58 fps);维护者在 RTX 3090 上用固定输入探针验证
`hevc_nvenc` 与 `libx265` 均 90/90 帧可解码、首帧为关键帧。
- H.265 access units are now split on picture boundaries (RFC 7798), fixing hevc_vaapi sessions that sent almost nothing.
### 新增 / Added
- **`UU_VAAPI_BUFFER_MS`**(#47,感谢 @NuoFang6,源自 #42):可选加大 VAAPI 的编码缓冲(10–1000 ms),缓解高分辨率下
关键帧被压糊、画面周期性模糊。默认不启用。⚠️ 仅在一台机器上实测,代价是关键帧变大,建议从 250 ms 试起。
- Optional VAAPI VBV buffer `UU_VAAPI_BUFFER_MS` (off by default; verified on one machine only).
### 下载 / Download
`uu-remote-linux-v0.2.9-x86_64-linux.tar.gz`(主机 `uuremote-server` + 控制端 `uuremote-viewer`,附带 `contrib/`),或 `docker pull ghcr.io/vallierdev/uu-remote-linux:v0.2.9`。
**非官方项目,与网易无关。** / **Unofficial, not affiliated with NetEase.**
+126 -17
View File
@@ -94,16 +94,57 @@ fn nal_offsets_for(bytes: &[u8], kind: u8, codec: VideoCodec) -> Vec<usize> {
let matches = match codec {
VideoCodec::H264 => header < bytes.len() && bytes[header] & 31 == kind,
// HEVC has a two-byte header: forbidden_zero_bit=0, temporal_id_plus1 != 0.
VideoCodec::H265 => header + 1 < bytes.len() && bytes[header] & 128 == 0
&& bytes[header + 1] & 7 != 0 && (bytes[header] >> 1) & 63 == kind,
VideoCodec::H265 => hevc_nal_kind(bytes, header) == Some(kind),
};
if matches { result.push(i); }
i += prefix;
}
result
}
fn aud_offsets_for(bytes: &[u8], codec: VideoCodec) -> Vec<usize> {
nal_offsets_for(bytes, if codec == VideoCodec::H265 { 35 } else { 9 }, codec)
/// Validated HEVC NAL unit type from the two-byte header (`None` when it is incomplete or the
/// forbidden bit is set or temporal_id_plus1 is zero).
fn hevc_nal_kind(bytes: &[u8], header: usize) -> Option<u8> {
(header + 1 < bytes.len() && bytes[header] & 128 == 0 && bytes[header + 1] & 7 != 0)
.then(|| (bytes[header] >> 1) & 63)
}
/// Access-unit starts for H.265, independent of where the encoder puts its AUDs. VAAPI writes an
/// AUD only at IRAPs, so splitting on AUD alone groups a whole GOP into one "frame" (and that
/// frame then fails the IRAP gate, so nothing is sent). RFC 7798 §3.1 puts the boundary at the
/// first NAL after a VCL NAL that is either non-VCL (AUD/VPS/SPS/PPS/SEI) or starts a picture
/// (first_slice_segment_in_pic_flag), which also keeps multi-slice pictures in one unit.
fn hevc_au_offsets(bytes: &[u8]) -> Vec<usize> {
let mut result = Vec::new();
let mut previous_vcl = false;
let mut first = true;
let mut i = 0;
while i + 3 < bytes.len() {
let prefix = if bytes[i..].starts_with(&[0, 0, 0, 1]) { 4 }
else if bytes[i..].starts_with(&[0, 0, 1]) { 3 } else { i += 1; continue };
let header = i + prefix;
if let Some(kind) = hevc_nal_kind(bytes, header) {
let vcl = kind < 32;
let starts_picture = vcl && bytes.get(header + 2).is_some_and(|byte| byte & 0x80 != 0);
// RFC 7798 / H.265 7.4.2.4.4: only these non-VCL types may open the next access unit.
// Suffix SEI (40), filler (38) and end of sequence/bitstream (36, 37) stay with the
// picture they follow.
let opens_unit = matches!(kind, 32..=35 | 39 | 41..=44 | 48..=55);
if first || (previous_vcl && (opens_unit || starts_picture)) { result.push(i); }
// Trailing NALs (suffix SEI, filler, end markers) do not end "after a VCL NAL".
if vcl || opens_unit { previous_vcl = vcl; }
first = false;
}
i += prefix;
}
result
}
fn au_offsets_for(bytes: &[u8], codec: VideoCodec) -> Vec<usize> {
match codec {
VideoCodec::H264 => nal_offsets_for(bytes, 9, codec),
VideoCodec::H265 => hevc_au_offsets(bytes),
}
}
fn is_independent_frame_for(bytes: &[u8], codec: VideoCodec) -> bool {
match codec {
@@ -114,7 +155,7 @@ fn is_independent_frame_for(bytes: &[u8], codec: VideoCodec) -> bool {
}
}
#[cfg(test)]
fn aud_offsets(bytes: &[u8]) -> Vec<usize> { aud_offsets_for(bytes, VideoCodec::H264) }
fn aud_offsets(bytes: &[u8]) -> Vec<usize> { au_offsets_for(bytes, VideoCodec::H264) }
fn is_independent_frame(bytes: &[u8]) -> bool { is_independent_frame_for(bytes, VideoCodec::H264) }
#[derive(Debug)]
@@ -178,10 +219,17 @@ fn vaapi_options(settings: &VideoSettings, gop: &str) -> Vec<String> {
let (maxrate, buffer) = rate_args(settings, Encoder::Vaapi);
// QVBR is not uniformly available on Intel/AMD drivers. VBR + qmin sets a quality
// floor while retaining the viewer's bitrate cap; unsupported drivers fall back to CPU.
["-c:v", Encoder::Vaapi.name_for(settings.codec), "-profile:v", profile_for(settings.codec, true), "-g", gop, "-bf", "0",
"-rc_mode", "VBR", "-b:v", &settings.max_kbps().map_or("16M".into(), |k| format!("{}k",k*3/4)),
"-maxrate", &maxrate, "-bufsize", &buffer, "-qmin", &settings.cq().to_string(), "-async_depth", "1", "-aud", "1"]
.into_iter().map(str::to_owned).collect()
let mut options: Vec<String> = ["-c:v", Encoder::Vaapi.name_for(settings.codec), "-profile:v", profile_for(settings.codec, true),
"-g", gop, "-bf", "0", "-rc_mode", "VBR", "-b:v", &settings.max_kbps().map_or("16M".into(), |k| format!("{}k",k*3/4)),
"-maxrate", &maxrate, "-bufsize", &buffer, "-qmin", &settings.cq().to_string(), "-async_depth", "1"]
.into_iter().map(str::to_owned).collect();
// h264_vaapi writes an AUD per picture and the reader splits access units on it. hevc_vaapi
// does not: with `-aud 1` it writes an AUD only at IRAPs and drops every other picture from
// the bitstream (a 90-frame clip encoded to 3 IDRs and no P-frames), so HEVC leaves AUD off
// and hevc_au_offsets() splits pictures by their own boundaries. Parameter sets are still
// repeated in-band ahead of every IDR.
if settings.codec == VideoCodec::H264 { options.extend(["-aud".into(), "1".into()]); }
options
}
fn profile_for(codec: VideoCodec, vaapi: bool) -> &'static str {
@@ -480,7 +528,21 @@ async fn read_inprocess(
/// whole IDR frame, otherwise large desktops get near-grey keyframes that sharpen over the GOP (#8).
/// Half a second of bitrate still starved repeated 0.5 s-GOP keyframes at 3296x2036/2M; one second did not.
fn buffer_kbits(max_kbps: u32, encoder: Encoder) -> u32 {
if encoder == Encoder::Cpu { max_kbps.clamp(500, 8000) } else { (max_kbps / 8).clamp(100, 500) }
if encoder == Encoder::Cpu { max_kbps.clamp(500, 8000) }
else if encoder == Encoder::Vaapi {
let requested = std::env::var("UU_VAAPI_BUFFER_MS").ok();
vaapi_buffer_kbits(max_kbps, requested.as_deref()).unwrap_or((max_kbps / 8).clamp(100, 500))
}
else { (max_kbps / 8).clamp(100, 500) }
}
/// Opt-in VAAPI VBV buffer: `码率上限 × 毫秒 / 1000` for `UU_VAAPI_BUFFER_MS` in 10-1000 ms.
/// The 100-500 kbit default is sized for NVENC; VAAPI quantizes a whole desktop keyframe when
/// the buffer is that small, which reads as a blur that sharpens over each GOP (#42).
/// Unset, out of range or unparsable values keep the default buffer.
fn vaapi_buffer_kbits(max_kbps: u32, value: Option<&str>) -> Option<u32> {
let ms = value?.trim().parse::<u32>().ok().filter(|ms| (10..=1000).contains(ms))?;
Some((max_kbps.saturating_mul(ms) / 1000).max(1))
}
fn buffer_for(settings: &VideoSettings, encoder: Encoder) -> u32 {
@@ -651,7 +713,7 @@ async fn read_encoder_with(
pending.extend_from_slice(&chunk[..count]);
// A chunk can include the next AUD, so split before enforcing the bound.
loop {
let aud = aud_offsets_for(&pending, settings.codec);
let aud = au_offsets_for(&pending, settings.codec);
if aud.len() < 2 { break; }
let next = aud[1];
if next > MAX_ACCESS_UNIT { return Err("Encoder access unit exceeds limit".into()); }
@@ -686,7 +748,16 @@ fn probe_settings() -> Result<VideoSettings,String> {
None=>crate::capture_setting::QUALITY_AUTO,
Some(v)=>v.parse::<u64>().ok().filter(|q|(1..=5).contains(q)).ok_or("UU_PROBE_QUALITY must be 1-5")?,
};
Ok(VideoSettings {fps,quality,..VideoSettings::default()})
Ok(VideoSettings {fps,quality,codec:probe_codec(),..VideoSettings::default()})
}
/// The probe follows `UU_VIDEO_CODEC` so the HEVC path can be measured at all (H.264 otherwise),
/// and its first access unit is then checked against that codec instead of always H.264.
fn probe_codec() -> VideoCodec {
match std::env::var("UU_VIDEO_CODEC").ok().as_deref().map(str::to_ascii_lowercase).as_deref() {
Some("h265") | Some("hevc") => VideoCodec::H265,
_ => VideoCodec::H264,
}
}
fn probe_input_command(spec:&FfmpegSpec,input:&std::ffi::OsStr,loop_input:bool,settings:&VideoSettings,
@@ -700,7 +771,7 @@ fn probe_input_command(spec:&FfmpegSpec,input:&std::ffi::OsStr,loop_input:bool,s
command.args(scale_options(settings,encoder));
command.args(encoder_options(settings,encoder,&gop_frames(settings.fps,false).to_string(),None));
command.args(timing_args(timing,settings.fps));
command.args(["-frames:v",&wanted.to_string(),"-f","h264","pipe:1"]);
command.args(["-frames:v",&wanted.to_string(),"-f",if settings.codec==VideoCodec::H265 {"hevc"} else {"h264"},"pipe:1"]);
command
}
@@ -749,10 +820,10 @@ pub async fn probe_input(input:OsString,path:Option<String>)->Result<(),String>
let n=stdout.read(&mut chunk).await.map_err(|e|format!("Encoder read: {e}"))?;
pending.extend_from_slice(&chunk[..n]);
loop {
let aud=aud_offsets_for(&pending,settings.codec);
let aud=au_offsets_for(&pending,settings.codec);
let end=if aud.len()>1 { aud[1] } else if n==0 && !pending.is_empty() { pending.len() } else { break; };
if end>MAX_ACCESS_UNIT { return Err("Encoder access unit exceeds limit".into()); }
if count==0 && !is_independent_frame(&pending[..end]) { return Err("Video probe did not begin with IDR".into()); }
if count==0 && !is_independent_frame_for(&pending[..end], settings.codec) { return Err("Video probe did not begin with IDR".into()); }
if let Some(file)=file.as_mut() { file.write_all(&pending[..end]).map_err(|e|e.to_string())?; }
bytes+=end; count+=1;
pending.drain(..end);
@@ -787,7 +858,7 @@ pub async fn probe(size:(u32,u32),display:String,portal:Option<Arc<crate::portal
tokio::time::timeout(Duration::from_secs(15+wanted/30),async {
while count<wanted {
let frame=rx.recv().await.ok_or("Video probe encoder ended")?;
if count==0 && !is_independent_frame(&frame.data) { return Err("Video probe did not begin with IDR".to_owned()); }
if count==0 && !is_independent_frame_for(&frame.data, settings.codec) { return Err("Video probe did not begin with IDR".to_owned()); }
if let Some(file)=file.as_mut() { file.write_all(&frame.data).map_err(|e|e.to_string())?; }
bytes+=frame.data.len(); count+=1;
}
@@ -1066,6 +1137,20 @@ mod tests {
assert_eq!(buffer_kbits(30_000, Encoder::Cpu), 8000);
}
#[test]
fn vaapi_buffer_env_is_opt_in_and_bounded() {
assert_eq!(vaapi_buffer_kbits(30_000, None), None);
assert_eq!(vaapi_buffer_kbits(30_000, Some("250")), Some(7500));
assert_eq!(vaapi_buffer_kbits(30_000, Some(" 10 ")), Some(300));
assert_eq!(vaapi_buffer_kbits(30_000, Some("1000")), Some(30_000));
// Out of the documented range, empty or unparsable keeps the default buffer.
for value in ["", "9", "1001", "0", "abc", "-250", "250ms"] {
assert_eq!(vaapi_buffer_kbits(30_000, Some(value)), None, "{value}");
}
// A tiny cap must not produce a zero-sized buffer.
assert_eq!(vaapi_buffer_kbits(1, Some("10")), Some(1));
}
#[test]
fn vaapi_is_explicit_and_upload_follows_scale() {
assert_eq!(Encoder::from_setting(None, true), Encoder::Nvenc);
@@ -1207,7 +1292,7 @@ mod tests {
#[test]
fn hevc_annex_b_boundaries_and_irap_use_two_byte_headers() {
let bytes = [0,0,0,1,70,1,80,0,0,1,64,1,42,0,0,1,38,1,42,0,0,1,70,1,80];
assert_eq!(aud_offsets_for(&bytes, VideoCodec::H265), vec![0,19]);
assert_eq!(au_offsets_for(&bytes, VideoCodec::H265), vec![0,19]);
assert!(is_independent_frame_for(&bytes[..19], VideoCodec::H265));
for kind in 16..=21 {
assert!(is_independent_frame_for(&[0,0,1,kind << 1,1,42], VideoCodec::H265));
@@ -1218,6 +1303,27 @@ mod tests {
assert!(!is_independent_frame_for(&[0,0,1,166,1,42], VideoCodec::H265));
assert!(!is_independent_frame_for(&[0,0,1,38,1,42,0,0,1,2,1,42], VideoCodec::H265));
}
#[test]
fn hevc_access_units_do_not_depend_on_aud_placement() {
// VAAPI writes an AUD only at IRAPs: AUD VPS SPS PPS IDR, then one P per picture.
let vaapi = [0,0,0,1,70,1,0x80, 0,0,0,1,64,1,0x42, 0,0,0,1,66,1,0x42,
0,0,0,1,68,1,0x42, 0,0,0,1,38,1,0x80, 0,0,0,1,2,1,0x80, 0,0,0,1,2,1,0x80];
assert_eq!(hevc_au_offsets(&vaapi), vec![0, 35, 42]);
// x265/nvenc style: an AUD in front of every picture.
let with_aud = [0,0,0,1,70,1,0x80, 0,0,0,1,64,1,0x42, 0,0,0,1,38,1,0x80,
0,0,0,1,70,1,0x80, 0,0,0,1,2,1,0x80, 0,0,0,1,70,1,0x80, 0,0,0,1,2,1,0x80];
assert_eq!(hevc_au_offsets(&with_aud), vec![0, 21, 35]);
// A picture split over several slices stays one access unit.
let multi_slice = [0,0,0,1,38,1,0x80, 0,0,0,1,38,1,0x00, 0,0,0,1,2,1,0x80];
assert_eq!(hevc_au_offsets(&multi_slice), vec![0, 14]);
// Truncated/invalid NALs must not invent boundaries. An invalid header is skipped, and
// the first valid NAL after it still opens the first unit.
assert_eq!(hevc_au_offsets(&[0,0,1,70]), Vec::<usize>::new());
assert_eq!(hevc_au_offsets(&[0,0,1,128,1,0x80]), Vec::<usize>::new());
assert_eq!(hevc_au_offsets(&[0,0,1,128,1,0x80, 0,0,1,2,1,0x80]), vec![6]);
// A suffix SEI (40) after a picture stays in that picture's unit; the next slice opens the next one.
assert_eq!(hevc_au_offsets(&[0,0,1,0x26,1,0x80, 0,0,1,0x50,1,0x05, 0,0,1,0x02,1,0x80]), vec![0, 12]);
}
#[tokio::test]
async fn hevc_dependency_gate_recovers_only_at_irap_after_overflow() {
let (tx, mut rx) = mpsc::channel(1);
@@ -1250,6 +1356,8 @@ mod tests {
for pair in [["-c:v", "hevc_vaapi"], ["-profile:v", "main"], ["-bf", "0"], ["-bufsize", "500k"]] {
assert!(vaapi.windows(2).any(|window| window == pair));
}
// hevc_vaapi with -aud drops every non-IRAP picture, so H.265 must not ask for AUDs.
assert!(!vaapi.iter().any(|option| option == "-aud"));
assert_eq!(Encoder::Nvenc.name_for(VideoCodec::H265), "hevc_nvenc");
assert_eq!(Encoder::Cpu.name_for(VideoCodec::H264), "libx264");
}
@@ -1261,3 +1369,4 @@ mod tests {
assert!(!is_independent_frame(&[0,0,0,1,9,48,0,0,1,1,154]));
}
}