企业官网建设流程全解析

• 音视频

Foundation Sunshine（Sunshine-Foundation）是基于 LizardByte/Sunshine 的增强分支，聚焦于提升连接 Windows 主机的各类串流终端设备的游戏串流体验。本文以仓库根目录的 README.en.md 为主线，深入讲解其双格式 HDR 编码（HDR10 PQ + HLG）、逐帧亮度分析与动态元数据注入、ZakoVDD 虚拟显示器集成、NVIDIA RTX HDR / DLSS NR 画质增强等核心能力，并结合源码验证各机制的底层实现。读完本文，你将掌握 Foundation Sunshine 的安装启动流程、HDR 全链路的工作原理与配置要点、可选功能（虚拟 DualSense、USB 转发）的启用条件，以及各功能对应的源码入口与文档位置。

项目定位与快速开始

Foundation Sunshine 是一个自托管的游戏串流服务端（Host），与 Moonlight 客户端配合使用，主要面向 Windows 主机侧的串流场景。相比上游 Sunshine，该分支重点增强：HDR 全链路（PQ + HLG 双格式编码、动态元数据注入、Dolby Vision 状态展示）、虚拟显示器（深度集成 ZakoVDD）、远程麦克风、先进控制面板、低延迟编码、智能配对、控制器与设备支持（虚拟 DualSense、USB 转发）以及 NVIDIA 画质增强组件。

三步快速开始

1. 安装并启动：从项目官方发行渠道下载适用于 Windows 的安装包（发行页可能包含预发布版本，选择前请先阅读对应版本的发布说明），安装后启动 Sunshine。
2. 配置 Web 控制界面：在主机浏览器打开https://localhost:47990，首次启动时需要创建并保存登录凭据；浏览器可能会提示本地自签名证书，属正常现象，需手动信任后继续。
3. 添加应用并配对：在控制界面中添加要串流的应用程序，在 Moonlight 客户端中添加主机，然后在 Sunshine 中输入客户端显示的 PIN 完成配对。

[!NOTE] 虚拟显示器、DualSense、USB 转发与 NVIDIA 画质增强功能各有独立的驱动或组件要求，启用前请在控制面板中查看对应组件的安装状态与提示。

核心特性总览

根据 README.en.md 的说明，Foundation Sunshine 的核心特性可归纳为以下几条，其后各节会逐一展开：

• 全 HDR 管线支持：双格式 HDR10 (PQ) + HLG 编码，配合自适应元数据，覆盖更广的终端设备；
• 虚拟显示器：集成 ZakoVDD 的虚拟显示器管理，需要对应驱动；
• 远程麦克风：接收客户端麦克风输入，提供高质量语音透传；
• 高级控制面板：直观的 Web 控制界面，支持实时监控与配置管理；
• 低延迟传输：利用最新硬件能力优化编码处理；
• 智能配对：对配对设备进行智能管理与档案配置；
• 控制器与设备：全局及单应用级手柄选择、可选虚拟 DualSense（含音频触觉）、已配对客户端的 USB 转发；
• NVIDIA 画质增强：可选的 RTX HDR 与 DLSS NR；DLSS NR 支持 SDR 与原生 HDR，串流中可实时开关并调节处理比例（需兼容硬件与组件）；
• 流状态展示：报告协商出的 Dolby Vision Profile 8.1 / 8.4 及主机侧 RPU 注入状态，并可在最后一个视频会话结束后自动结束应用。

全 HDR 管线架构：HDR10 (PQ) + HLG 双格式并行

这是 Foundation Sunshine 最具技术含量的一项增强。传统串流方案仅支持 HDR10 (PQ) 绝对亮度映射，要求客户端显示设备精确匹配源端 EOTF 参数与峰值亮度；当终端能力不足或亮度参数不匹配时，会出现暗部细节丢失（crushed blacks）与高光截断（clipped highlights）等色调映射伪影。

Foundation Sunshine 在编码层引入 HLG（Hybrid Log-Gamma，ITU-R BT.2100）支持。HLG 采用相对亮度映射，带来三项技术优势：

• 场景参考式亮度适配（Scene-Referred Luminance Adaptation）：HLG 基于相对亮度曲线，显示端根据自身峰值亮度自动执行色调映射，低亮度设备上暗部细节保留显著优于 PQ；
• 高光区域平滑滚降（Smooth Highlight Roll-Off）：HLG 的对数-伽马混合传输函数在高光区域提供渐进式滚降，避免 PQ 硬截断导致的高光色阶断裂（banding）；
• 天然 SDR 向后兼容：HLG 信号可直接被 SDR 显示器解码为标准 BT.709 画面，无需额外的色调映射处理。

在源码层面，色彩空间与动态元数据格式的取舍由video::hdr_metadata::formats_for()统一裁决（见 src/video_hdr_metadata.h）：BT.2020 PQ 色彩空间（colorspace_e::bt2020）允许 HDR10+ 与 HDR Vivid；BT.2020 HLG（colorspace_e::bt2020hlg）只允许 HDR Vivid（HDR10+ 为绝对亮度语义，仅限 PQ）；其余色彩空间不产生任何动态元数据。其中 HDR Vivid 仅当视频格式为 HEVC（video_format == 1）时才有可承载的容器（Vivid 标准只定义了 AVS2 与 HEVC/VVC 的载体，未提及 AV1/OBU）。

逐帧亮度分析与自适应元数据生成

编码管线在 GPU 端集成了实时亮度分析模块，通过 Compute Shader 对每一帧执行以下处理：

• MaxFALL / MaxCLL 逐帧计算：实时统计帧级最大内容亮度（MaxCLL）与帧平均亮度（MaxFALL），并动态注入 HEVC/AV1 的 SEI/OBU 元数据；
• 异常值鲁棒过滤：采用百分位截断策略剔除极端亮度像素（如高光镜面反射），防止孤立亮点拉高全局亮度参考而导致整体画面偏暗。源码中hdr10plus_from_luminance()明确要求调用方传入第 99 百分位作为 maxSCL 上报值——因为 Windows 合成器的 scRGB 表面镜面过冲无界，真正的最大值会令所有消费端按 10000-nit 峰值做映射（见 src/video_hdr_metadata.h 中关于hdr10plus_pq_reference_nits = 10000.0f的注释）；
• 帧间指数平滑（EMA）：对连续帧的亮度统计应用指数移动平均滤波，消除场景切换时元数据突变引起的亮度闪烁。hdr_luminance_ema_t中 EMA 系数ALPHA = 0.15（越低越平滑但适应越慢），并内置场景切换检测：当亮度变化超过 3 倍（SCENE_CUT_THRESHOLD）时直接快照到新值而非缓慢过渡（见 src/video_hdr_metadata.h）。

针对 HDR Vivid，还实现了 32 帧滑动窗口的算术平均滤波（vivid_temporal_filter_t，符合 GB/T 46269.1-2025 Annex A.9 建议），以及场景切换检测器scene_change_detector_t：它在 PQ 域中综合均值、P10/P90 百分位与 HDR10+ 分布判断是否发生实质场景变化（阈值如均值差 ≥ 0.10、高低百分位差 ≥ 0.18 等），单点 scRGB 峰值（如光标、字幕）不足以触发切换。这些状态被封装在dynamic_metadata_temporal_state_t中，NVENC 与 AMF 两条原生编码路径共用同一实例，避免两条路径行为漂移。

HDR Vivid 启动门控

HLG 流有一个特殊问题：若起始 IDR 为纯 HLG、中途再切进 HDR Vivid，客户端会看到明显的画面跳变。为此源码实现了vivid_startup_guard_t与vivid_startup_gate_t（见 src/video_hdr_metadata.h）：在流启动阶段，需要连续 3 个独立、合理且稳定的 GPU 亮度采样（REQUIRED_SAMPLES = 3）才认定分析器输出可信；若超过 1500ms 预卷预算（PREROLL_TIMEOUT）仍未收敛，则先以纯 HLG 开始，待分析器追上后在 IDR 边界恢复 Vivid。这一状态机同样被 NVENC 与 AMF 路径共用，代码注释中明确说明：两条编码器对"HLG 何时开始携带 Vivid"给出不同答案，最终会表现为"AMD 机器上 HDR 观感不同"这类难以排查的 bug。

完整 HDR 元数据透传与码流级注入

Foundation Sunshine 支持完整透传 HDR10 静态元数据（Mastering Display Info + Content Light Level）、HDR Vivid 动态元数据与 HLG 传输特性标识，确保 NVENC / AMF / QSV 编码器输出的码流携带符合 CTA-861 规范的完整色彩容积与亮度信息，使客户端解码器能准确还原源端 HDR 意图。

动态元数据在码流层面的落位由 src/video_hdr_bitstream.h 负责，其要点包括：

• 载体选择：HEVC 使用 prefix SEI NAL（nal_unit_type 39，payloadType 4），AV1 使用OBU_METADATA（metadata_type 4，即METADATA_TYPE_ITUT_T35）。H.264 被刻意排除——Sunshine 从不通过 H.264 串流 HDR，支持它只会产生无人可达状态的无测试代码；
• T.35 负载生成：serialize_hdr10plus_t35()与serialize_vivid_t35()生成完整的注册型 ITU-T T.35 负载（自itu_t_t35_country_code起）。HDR Vivid 负载使用中国国家码0x26、CUVA 终端提供商标识0x0004，并按 T/UWA 005.1 写入 minimum/average/variance/maximum 四组 12-bit PQ 码值（见 src/video_hdr_metadata.h 的serialize_vivid_t35()）；
• 拼接机制差异：NVENC 接受 T.35 负载并自行书写周边语法（NV_ENC_SEI_PAYLOAD/obuPayloadArray）；AMF 没有等价接口，只能手工把 ST 2094-40 / CUVA 负载拼进已编码码流——该拼接模块刻意保持与 AMF、D3D、FFmpeg 头文件无关，便于在任何平台上做单元测试；
• RPU 注入/剥离：Dolby Vision RPU（HEVC UNSPEC 62 NAL）可被注入到访问单元末尾（dovi_tool确立的播放器/设备兼容位置），也可被整体剥离（strip_hevc_dolby_vision_rpus()），且操作幂等。

Dolby Vision Profile 8.1 / 8.4 的动态协商

流状态功能中报告的 Dolby Vision 协商结果，由 src/hdr/dynamic_hdr_selection.h 实现。其设计要点：

• 能力上报：客户端通过 RTSP ANNOUNCE 的 SDP 携带dynamicHdrCaps位掩码（HDR10+、Vivid PQ、Vivid HLG、DV 8.1、DV 8.4），主机每会话做一次性决策（见 docs/dolby_vision_profile81.md）；
• 不主动下发原则：Dolby Vision Profile 8.1 不得未经请求而下发——未配置 Dolby Vision 解码器的客户端可能误处理 UNSPEC 62 NAL。而 HDR10+ 与 HDR Vivid 则有意不做此门控（沿用上游无条件发射的行为），仅对"上报了能力"的客户端生效，包括协商降级为纯 HDR10；
• 优先级规则：DV 8.1 在客户端上报且会话为 PQ 时优先；8.4 仅在客户端单独上报且会话为 HLG 时选择。偏好顺序为dolby_vision/automatic → DV → HDR10+ → HDR10；DV 还额外要求 HEVC 编码与客户端直连面（direct surface）能力。所有 wire 值均保持稳定，不随版本重编号；
• 回退原因上报：当客户端请求 DV 但未获选时，通过X-SS-Dynamic-HDR-Fallback上报原因（codec 不支持、色彩空间不支持、能力缺失、直连面缺失、偏好冲突等）。

此外，src/hdr/session_target.h 与 src/hdr/client_display_capabilities.h 处理会话级 HDR 亮度目标解析：客户端可上报 max_nits / min_nits / max_full_frame_nits 三字段（缺失、畸形或自相矛盾时整体拒绝并回退到安全默认值：max 1000 nits、min 0.001 nits、full-frame 1000 nits），再经resolve_effective_target()结合按客户端 UUID 配置的手动覆盖值（clients.json）与 Windows HDR 校准信息，得出最终的有效亮度目标，并标注其来源（client_report / manual_override / windows_hdr_calibration / safe_defaults）。

HDR 相关配置项

• hdr_luminance_analysis（src/config.cpp）：GPU 逐帧亮度分析开关，取值auto（默认，HDR 流自动启用、SDR 流停用）、on、off。解析时兼容true/enabled/yes/enable/1与false/disabled/no/disable/0等写法，非法值会被记录 warning；
• dd_hdr_option（docs/configuration.md）：显示设备额外的 HDR 配置，可按客户端请求将显示切换为所需 HDR 状态；
• dd_wa_hdr_toggle_delay（docs/configuration.md）：虚拟显示器（VDD）串流时若出现 HDR 颜色显示异常，Sunshine 可先关闭 HDR、等待指定毫秒数再重新打开以缓解问题。设置为 0 表示禁用（默认）；0～3000ms 内取值，推荐约 500ms。注意该 workaround 直接影响串流启动时间，仅在确实遇到 HDR 问题时使用。

虚拟显示器集成（需 Windows 10 22H2 或更新）

Foundation Sunshine 深度集成 ZakoVDD 虚拟显示器驱动，提供：

• 动态虚拟显示器创建与销毁；
• 自定义分辨率与刷新率支持（10-bit HDR 色深）；
• 多显示器配置管理；
• 无需重启的实时配置更改。

中文版 README.md 进一步补充了实现细节：通过 IOCTL 实时通信，串流开始/结束时自动创建/销毁虚拟显示器；每个客户端独立绑定 VDD 会话（GUID），支持多客户端快速切换；并提供Zako Direct 零拷贝借帧——直接借用 VDD 共享帧纹理，转换完成后立即归还，减少 VDD 捕获链路的 GPU 拷贝。

配置侧相关选项（src/config.cpp）包括：

• vdd_keep_enabled：由系统托盘控制，不通过 Web UI 修改；
• vdd_headless_create：由系统托盘控制，不通过 Web UI 修改；
• vdd_reuse：默认 false（为每个客户端重建 VDD）；
• vdd_borrowed_texture：默认 true（启用零拷贝借帧）；
• vdd_vulkan_hdr_bridge：默认 true（HDR VDD 会话自动启用）。

相关源码入口位于 src/display_device（VDD IOCTL、会话与设置）与 src/platform/windows/display_vdd.cpp。

音频增强与远程麦克风

• 7.1.4 环绕声（12 声道）：完整映射 Dolby Atmos 等沉浸式音频布局的声道。编码层基于 Opus 多声道编码器（opus_multistream，见 src/audio.cpp），并在 AC3/E-AC3 路径拒绝超过 5.1（6 声道）的布局；
• Opus DRED 深度冗余：基于神经网络的丢包恢复，100ms 冗余窗口在网络抖动时平滑补偿；
• 持续音频流：无中断的音频流，无声时自动填充静音数据，避免音频设备反复初始化；
• 虚拟扬声器位深匹配：自动检测并匹配 16bit/24bit 等位深格式的虚拟音频设备；
• 远程麦克风：支持接收客户端麦克风输入，提供高质量语音透传（Windows 侧实现见 src/platform/windows/virtual_device_host/microphone_client.cpp）。

NVIDIA 画质增强：RTX HDR 与 DLSS NR

NVIDIA 画质增强作为按需启用的组件式后端，配置与版本管理集中在 src/image_enhancement/config.h：

• RTX HDR：将 SDR 输入转换为 PQ HDR；不作用于原生 HDR 输入或 HLG 输出；启用后可能阻止 HLG 会话协商 Dolby Vision Profile 8.4（RTX HDR 管线被 PQ 钉死，即使客户端请求 HLG 也排除 8.4，见 src/hdr/dynamic_hdr_selection.h 中synthetic_hdr_enabled门控）；
• DLSS NR：信号保留型神经画质增强，支持 SDR 与原生 HDR；串流中可实时开关并调节处理比例（processing scale）。

使用流程：先在控制面板的"画质增强管理"页配置 RTX HDR 或 DLSS NR 组件，再为单个应用开启相应功能。配置采用事务式manager_t管理，流读取方持有不可变的版本引用；支持运行时校验码（digest）固定（runtime_pins，缺省条目在加载时计算并记录），且后端版本需通过valid_version()校验。更多构建细节见 docs/rtx_hdr_build.md。

[!IMPORTANT] 控制面板显示的 Dolby Vision Profile 8.1 / 8.4 与主机侧 RPU 注入状态，仅代表主机侧协商与注入结果，不代表客户端或显示设备已成功呈现 Dolby Vision；Profile 8.4 仍需真机端到端验证（见 docs/dolby_vision_profile84.md）。

其他按需启用功能

• 虚拟 DualSense：在控制面板的控制器中心选择手柄类型，可设全局默认值或为单个应用覆盖；需先安装可选 DualSense 组件，音频触觉还额外要求 USB/IP 传输及客户端能力。组件不可用时自动回退到自动手柄选择。组件生命周期细节见 docs/windows_dualsense_component_lifecycle.md；
• USB 转发：Windows 主机须先启用 USB 转发并具备可用的 USB/IP 传输组件，已配对客户端才能配置运行时转发；设备授权以控制面板中的状态提示为准。相关实现见 src/remote_usb 目录。

推荐 Moonlight 客户端

为获得最佳串流体验（README 中戏称"激活套装属性"），项目推荐搭配以下优化版 Moonlight 客户端（可在对应渠道获取）：

• PC（Windows x86_64 / Arm64、macOS、Linux）：Moonlight-PC；
• Android：威力加强版（Enhanced Edition）与王冠版（Crown Edition）Moonlight-Android；
• iOS：VoidLink Moonlight-iOS。

这些客户端配合本服务端可实现虚拟 DualSense、HDR 协商等增强能力的端到端支持。更多生态资源可参考上游的 awesome-sunshine 列表。

系统要求

[!WARNING] 以下表格会持续更新，请勿仅凭该信息购买硬件。

最低配置要求

4K 推荐配置

实际可用的编码格式、HDR 与画质增强能力取决于显卡、驱动与客户端；安装后请以 Sunshine 的编码器探测结果与控制面板状态为准。

故障排查与技术支持

遇到问题时的排查路径：

1. 查阅在线使用文档与上游 LizardByte 官方文档；
2. 在设置中启用详细日志级别（detailed log level）以定位相关信息；
3. 携带日志加入项目 QQ 交流群求助。

向项目反馈 issue 时，建议使用以下标签以便归类：

• hdr-support：HDR 相关问题；
• virtual-display：虚拟显示器问题；
• config-help：配置相关问题。

开发文档导航

对于希望深入源码或参与开发的读者，仓库提供以下文档：

• 构建说明：项目编译与构建指南；
• 配置指南：运行时配置项详解（含 HDR、显示设备、编码、DualSense、USB/IP 等完整参数说明）；
• WebUI 开发：Vue 3 + Vite 控制面板的完整开发指南。

源码地图：一文对应全部核心实现

总的来说，Foundation Sunshine 的技术重心清晰：以"覆盖更多终端设备"为目标重做 HDR 串流链路（PQ + HLG 双格式 + 动态元数据 + Dolby Vision 协商），以"开箱即用的 Windows 增强体验"为目标集成虚拟显示器、虚拟手柄、USB 转发与 NVIDIA 画质增强组件。理解上述 HDR 协商规则与各可选组件的启用条件，是充分驾驭这套串流栈的关键。

• 音视频