7,816 Star 的 Sunshine 魔改版:把 HDR、虚拟屏、DualSense 和 LLM 码率控制塞进同一个串流栈

Foundation Sunshine 实测拆解:1,370 个文件 / 342 个 cpp / 71 个 HLSL 着色器 / 20 个子模块 / 70 个 Release / 59.9 万次下载。附 HDR 双轨协商、动态 FEC 的 0.1% 概率目标、LLM 兜底的 ABR,以及四个必须知道的代价。

图:Foundation Sunshine 官方封面——让游戏串流更优雅

Sunshine 是把 Windows 电脑变成游戏串流主机的开源服务端,配合 Moonlight 客户端远程用桌面、应用和游戏。Foundation Sunshine 是它的一个深度魔改分支:HDR 全链路、虚拟显示器、环绕声与麦克风透传、DualSense 原生反馈、独立桌面 GUI,全部塞进同一个二进制。

项目:https://github.com/AlkaidLab/foundation-sunshine(7,816 Star · 227 Fork · GPL-3.0 · C++)

本文所有数字均为 2026-11-07 通过 GitHub REST API 与仓库文件树实测,非引用二手报道。


01 · 硬数据

维度实测值备注
Star / Fork7,816 / 227Star/Fork 比 34:1,围观远多于分叉
Watchers(subscribers)17极低,社区尚未形成回路
建库 / 最近 push2023-02-06 / 2026-11-07存续 3 年 9 个月
Commit 总数约 3,395含继承的上游历史
近 52 周 commit679平均每周 13 次
贡献者144前 10 位占 86.4%
Release 总数70(64 正式 / 6 预发布)累计下载 599,804 次
单个版本最高下载36,603(v2026.324)2026-03-24
Issue / PR476 / 732当前 62 open issue、34 open PR
仓库文件1,370 个 blob / 23.6 MB342 个 .cpp、292 个 .h、71 个 .hlsl
许可证GPL-3.0与上游一致,商业分发受限

贡献者排行里有个容易被误读的地方:

ReenigneArcher   769   ← 上游 Sunshine 维护者
qiin2333         619   ← 本项目主导者
loki (anon)      478
cgutman          407   ← 上游 moonlight-common-c 作者
Yundi339         183
dependabot[bot]  169

前四名里有三个是上游项目的人。这说明仓库保留了完整的 Sunshine 提交历史——它不是从零起飞,而是在一条 4.3 万 star 的干流上开了条支渠。真正的"基地"自己的量,是 qiin2333 与 Yundi339 的合计 802 次提交。

对比上游 LizardByte/Sunshine:43,106 Star、615 个文件、32.2 MB。Foundation 的文件数是上游的 2.2 倍,.cpp 是 2.4 倍(342 vs 143)——增量几乎全在 Windows 平台能力上。

02 · 它到底加了什么

上游 Sunshine 是一次"捕获 → 编码 → 传输"的通用实现。Foundation 在这条链路的每一个环节都插了东西:

模块清单(按 src/ 目录实测):

目录职责上游有吗
src/hdr/客户端显示能力、动态 HDR 协商、屏幕校准✗ 新增
src/streaming/ABR、RS FEC、码率预算、性能记录部分
src/ds5/DualSense 虚拟设备配置与 API✗ 新增
src/remote_usb/USB 设备转发✗ 新增
src/spatial_audio/环绕声、MAT(Dolby Atmos)实验链路✗ 新增
src/file_mapping/文件夹共享 + WSS 会话✗ 新增
src/ai/LLM 代理、凭据存储、SSE 流✗ 新增
src/webhook/事件通知投递✗ 新增
src/widget_http.cppXbox Game Bar 小部件状态接口✗ 新增
src/http/Boost.Beast 传输层(替换 Simple-Web-Server)重写

顶层还有个 gamebar-widget/——一个完整的 UWP 工程(34 个 .cs),把串流状态做成 Xbox Game Bar 里能用手柄导航的浮层。这种"顺手把一个小平台也吃下来"的做法,是这个仓库的典型风格。

20 个子模块

.gitmodules 里 19 项,其中值得注意的有:

  • third-party/moonlight-common-c → 指向 qiin2333/moonlight-common-c 的 mic 分支(不是 LizardByte 官方)。协议扩展全在这里:麦克风回传、动态 HDR 字段、触觉事件。最近一次提交是 docs: register fork protocol extensions (#51)。
  • third-party/pyrowave → 自研实验视频路径,独立仓库。
  • src_assets/common/sunshine-control-panel → 桌面 GUI 子模块(Tauri + Vue 3 + Rust,455 Star),不是内嵌在主体里。
  • 四个 nvenc-headers 版本并存(1100 / 1200 / 1300 / 1301),注释写得很直白:“新的 API 线会抬高最低驱动要求,不能替换旧的回退路径。”

最后这条是典型的踩过坑之后留下的防御性设计——同一个功能保留四条 NVENC API 版本,代价是构建产物里塞了四份头文件。

03 · 三条技术主线

3.1 显示链路:把 HDR 从"一个开关"做成"一次协商"

上游的 HDR 是 dynamicRangeMode = 1 或 2,二选一。Foundation 把它拆成正交两个维度:基础视频模式(SDR / HDR10-PQ / HLG)与动态元数据格式(NONE / HDR10+ / Vivid-PQ / Vivid-HLG / Dolby Vision 8.1 / 8.4)。

Dolby Vision 的实现文档写得很坦诚——它明确说 8.1 不是 HDR10+ 的画质升级版,而是并列的终端原生输出通道:

HDR10+Dolby Vision Profile 8.1
基础视频HDR10 PQ / BT.2020 / 10-bit同左
动态元数据SMPTE ST 2094-40Dolby Vision RPU
元数据载体HEVC prefix SEI (T.35)HEVC UNSPEC 62 NAL
映射执行者客户端 shader 或设备 HDR10+ 引擎设备 Dolby Vision 引擎
HDR10 回退支持支持(BL 兼容 ID = 1)

收益不在"多传了画质",而在覆盖支持 DV 但不支持 HDR10+ 的终端(LG、索尼、部分小米/OPPO)。文档甚至写了一句反向自查:

如果客户端最终仍用自研 shader 解析 RPU 再自行映射,这条通道没有意义——继续优化现有 HDR10+ 链路更有价值。

协商流程上,一个会话只锁一种动态格式,运行中不切换:

RTX HDR 与 8.4 的互斥是个具体例子:RTX HDR 管线固定输出 PQ(TrueHDR 滤镜 → FP16 linear scRGB → PQ/P010),HLG 会话压根不激活滤镜。所以 gate 判断的是应用配置(session.synthetic_hdr.enabled)而不是会话里的滤镜状态——否则用滤镜状态做判断,RTX HDR 应用在 HLG 路径上会漏排除。

这类"为什么这么写"的解释,在仓库 86 篇 Markdown 文档里密度很高,是这个项目最值钱的部分之一。

3.2 网络自适应:0.1% 概率目标的 RS FEC

src/streaming/fec.h 只有 8 KB,做的事相当克制:不改视频 UDP 格式,不加逐包身份,不做带宽探测。

反馈机制:客户端每秒通过已有的加密 ENet 控制通道回一条 12 字节汇总,内容是"块完成或放弃时的数据分片缺失数"。主机用十个一秒桶保存有限历史,取最高桶的缺失比例。

决策逻辑,文档原文:

决策器结合实际待发送帧大小,调用已有 Boost.Math 的二项分布尾概率。对可表示的 RS 布局选择最低冗余,使独立同分布丢失模型下"一帧任意块不可恢复"的概率上界不超过 0.1%。

冗余定义 P = ceil(D × F / 100)。约束很清楚:

参数默认范围说明
自动 FEC关闭—客户端"跟随主机"时才自动选
默认/回退比例20%0–255%无反馈或反馈超 3 秒时用
自动比例上限50%0–100%只约束自动模式,不约束客户端固定值
历史窗口10 秒固定借鉴有限历史滤波,非通用最优
RS 布局最多 4 块每块 ≤ 255 分片协议硬限制

文档末尾有整段自我限定,读起来像验收报告而不是宣传材料:

最高桶比例是保守观测值,并非统计置信上界;0.1% 是模型目标,不是实际体验保证。相关丢失、发送突发、迟到和未观察帧都可能偏离该模型。没有突发丢包分类或专用适配。

还有一个工程细节值得单独拎出来:提高 FEC 比例需要先降编码目标腾出带宽预算,代码用"帧时间戳环"记录每帧提交时的额度,避免 NVENC/AMF 的延迟输出把旧帧套上新额度。比例提高要等编码器成功重配置,比例降低可以先减冗余。这种方向不对称的处理,说明作者真的被"改完设置立刻卡一下"坑过。

3.3 ABR:阈值回退 + LLM 兜底

src/streaming/abr.h 的头部注释直接给出两层结构:

Two-tier architecture:
  1. Real-time fallback: immediate threshold-based reactions to packet loss.
  2. Event-driven LLM: intelligent per-game target bitrate via LLM AI,
     triggered on app switches and network recovery.

注意分工:实时层负责"立刻降",LLM 负责"长期上限"。LLM 不参与逐包决策,只在应用切换和网络恢复时异步设定该游戏的目标码率天花板。客户端定期 POST 网络指标,拿回调整动作。

这个设计有明确的技术合理性——大模型延迟不可控,塞进实时回路必然抖动;作为"这个游戏该给多少码率"的先验则很合适。代价也明确:要配 API key,多一条外部依赖,且推荐值不可复现。src/ai/ 目录(凭据存储、代理、SSE 流)就是为这个配套的。

配套的 src/ai/proxy.cpp 还承担桌面 GUI 的 AI 日志诊断——本地日志喂给模型定位问题。这类功能对"只看结果的用户"价值有限,对"愿意读日志的人"是加分项。

3.4 设备侧:DualSense、USB、MAT

三块新增能力,复杂度递增:

  • DualSense:Sunshine.Ds5Sidecar.x64.zip 单独一个 89.1 MB 资产(比主安装包 36.8 MB 还大 2.4 倍)。装好后在被控端呈现原生 DS5,自适应扳机、音频触觉、灯光、触控板全部透传。
  • USB 转发:src/remote_usb/,需要装传输组件并按设备授权。
  • MAT(Dolby Atmos):src/spatial_audio/,实验性。文档说得很实在——采集钩子依赖 audioeng.dll 与 Dolby Access 的 DolbyMatEnc.dll / DolbyMatEngine.dll 的内部偏移,只在 mat_compat.h 列出的已验证文件哈希上运行。

最后这条是整篇文章里最该被强调的风险:Windows 累积更新或 Dolby Access 商店更新一改这几个 DLL,MAT 就不可用(普通音频不受影响)。宿主更新的自由度决定了这个功能会周期性失效,修一次要重新做原生验收、补哈希。

04 · 工程治理:86 篇文档与 4 个 CI Job

主流开源项目里,文档质量与代码质量经常脱节。这个项目的文档产出量值得单独统计:

类别数量例子
.md 文档86 篇 / 0.8 MB—
用户文档4 语言 × 6 篇README 有中/英/德/法/日五版
设计文档30+ 篇dolby_vision_profile81/84、dynamic-fec、http-transport、MAT-HOST
排障文档2 篇FAQ、troubleshooting
特殊文档1 篇WGC vs DDAPI 流畅度"论文"

那篇 WGC_vs_DDAPI_Smoothness_Fun_Guide.md 值得单独看。它用"杂鱼"口吻 + Mermaid 时序图解释了一个真问题:DDAPI 轮询新帧时长时间持有 GPU 锁,编码器被挡在门外,导致每帧包含的游戏运动量不等——即便 V-Sync 让显示间隔完全均匀,眼睛看到的仍是动量忽大忽小(judder)。

文档里给了个穿透力很强的表格:

帧率帧间距±3ms 抖动占比感受
30 fps33.3 ms9%有点涩
60 fps16.7 ms18%明显不顺
120 fps8.3 ms36%很不舒服
240 fps4.2 ms72%—

结论对高刷串流用户是硬信息:帧率越高,同样的捕获抖动占比越大,捕获方式的选择越重要。

测试侧相对克制:

项实测
tests/CMakeLists.txt897 行
add_executable / add_test46 / 42
CI Job4 个(setup_release、vdd_smoke、mat_smoke、build_win)
测试类型单元 + 契约 + 冒烟,MAT 侧 20 余个专用用例

MAT 那部分是认真的:tests/mat-live/ 下 20 多个文件,包含 Android instrumentation、加密 oracle、22.8 KB 的管道测试、4.6 KB 的看门狗测试。但文档也承认边界:

常规 CI 运行轻量主机契约、对象回调、IPC、管道和管理入口回归;客户端使用 mock,不启动原生捕获、现场信号或完整 RTSP/视频会话。

也就是说,“能不能跑"由 CI 保证,“效果好不好"只能靠人工验收。这在音视频领域是常态,不是缺陷,但用户不该指望 CI 绿灯等于画质达标。

发布节奏则明显偏"快”:70 个 Release,2025-12 一个月发了 6 个,2026-11 前 7 天里发了 2 个。版本号形如 v2026.1031.121458.杂鱼——日期 + 时分秒 + 后缀,没有语义化版本。预发布和正式版混在同一个列表里,首屏 “Latest” 徽章还会指向预发布版本。

05 · 四个必须知道的代价

代价一:客户端锁定

这是最重要的一条。HDR 协商、显示器管理、音频格式、触觉事件全部依赖 moonlight-common-c 的 mic 分支协议扩展。官方 Moonlight 客户端不认这些扩展,用上去的结果是功能静默消失,或出现显示异常、连接错误。

README 直接列了推荐客户端清单(V+ for PC、macOS Enhanced、Android/TV V+、鸿蒙版,以及 VoidLink、王冠版、包子版等合作客户端)。想用 Foundation 的完整能力,等于接受一套"服务端 + 指定客户端"的绑定组合。

代价二:不是"装上就能用”

安装清单实际包含:主程序安装包(36.8 MB)+ 虚拟显示器驱动(Zako Display Driver)+ DualSense Sidecar(89.1 MB,按需)+ USB 传输组件(按需)+ 桌面 GUI 子模块。系统要求 Windows 10 22H2 以上。

README 里的新手流程有 6 个步骤、两张表格,还专门提醒"第一次连接先用 1080p / 60 FPS / 20 Mbps,先关 HDR"。这不是文档啰嗦,是这东西的可调项太多。

代价三:96 个 open issue

open_issues_count = 96(含 PR),拆开是 62 个 issue + 34 个 PR。对一个 3 年、近 3,400 次提交的项目,这个比例不算失控,但意味着反馈周期可能较长。文档里已经沉淀了相当多"已知问题"——比如"安装模拟 DS5 组件后 Windows 桌面自动滚动",FAQ 的解法是"装最新测试版试试",属于未根治状态。

代价四:发布说明里有硬约束

最新正式版的发布说明出现了三条不该被忽略的提示:

N 卡用户请避开 616.55、616.64 版本驱动,这两个版本可能导致虚拟显示器无法激活,并出现串流 503 错误。

Sunshine 完全免费。如果你通过第三方平台付费购买,请申请退款。

虚拟显示器的系统要求:Windows 10 22H2 或更高版本。

第一条是实实在在的踩坑警告(驱动版本 × 虚拟屏激活 × 503 错误,三个词对上一类典型故障)。第二条说明市面上已经有人在倒卖这个免费工具。

06 · 该用哪个

场景建议
局域网串流,只要稳定低延迟,不折腾上游 Sunshine 足够,生态和客户端兼容性最好
无物理显示器 / 要 HDR / 要 7.1.4 与麦克风回传Foundation,且必须配它指定的客户端
需要 DualSense 自适应扳机远程可用Foundation,接受 89 MB Sidecar 与组件维护成本
需要 Dolby Vision 输出到电视Foundation 8.1/8.4 通道,但先确认终端与客户端都支持
追求"装完即用"两个都不太符合,Sunshine 系列天生是配置型工具

一句话总结:上游解决"能不能串",Foundation 解决"串得像不像本地"。 后者的代价是把上游 615 个文件的通用实现,扩成了 1,370 个文件的 Windows 专用栈——其中 342 个 .cpp、71 个 HLSL 着色器、20 个子模块、4 个 NVENC API 版本,每一项都是为"画面和声音更接近本地"付的账。


本文所述功能与限制均以 2026-11-07 仓库状态为准。项目迭代很快(单周内两次发布),具体可用性请以实际版本说明与真机测试为准。作者与项目无关联,不构成推荐。