Skip to content
项目

zerochocobo/Thru3D-Media-Server

在 GitHub 查看

zerochocobo/Thru3D-Media-Server has 57 GitHub stars and 1 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 15:13 UTC. Last push 2026-10-15.

这些数字如何统计

可以做什么

  • DLNA discovery and ContentDirectory browsing
  • External SRT, ASS, SSA, and WebVTT subtitle delivery for original videos through DLNA metadata and HTTP caption links
  • Realtime passthrough streaming with GPU matting and HEVC output
  • Realtime subtitle embedding in the passthrough stream

实测星标增长

24小时
0
7天
更新延迟
15天
更新延迟
1个月
更新延迟

各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。

关于

Thru3D Media Server - Local DLNA/UPnP media server for generate a realtime passthrough stream.

创作与媒体

README.zh-CN.md

原文

Thru3D媒体服务器

Thru3D媒体服务器原名为“VR视频透视服务器”(VR Video Passthrough Server)。

中文 | English | 日本語

项目官网:https://thru3d.com

Thru3D媒体服务器 的目标是让所有VR视频都可以透视,实现混合现实(MR)。

Thru3D媒体服务器概览

它是以 Windows 为主要运行平台的 VR DLNA 本地媒体服务器,提供多语言桌面界面和独立离线工具。软件通过 DLNA/UPnP 暴露本地视频库,并提供实时绿幕透视、Alpha透视、2D视频透视、2D转3D / VR、NVIDIA RTX视频超分辨率、VR硬字幕、匹配环境光,以及基于同名 .si.wav sidecar 的配音/同传播放。软件主要针对 VR180 半等柱体投影(half-equirectangular)视频优化,同时支持符合条件的普通2D视频。

桌面版本号见应用元数据。

Thru3D媒体服务器 是 Thru3D 系列的 Windows 媒体服务端,与 Thru3D Media Player 配套使用,也支持其他兼容的 DLNA 播放器。

Windows 打包程序名为 Thru3D_Media_Server.exe,输出目录为 dist/Thru3D_Media_Server/。

项目起源

本想做一个 VR 视频透视工具。
有人说: 你这是重复造轮子。
我说:那个多年前的旧轮子已经太老了,该换新的了。
七天后,新轮子诞生了。
这是属于 AI 时代的奇迹。

功能

  • DLNA 发现与 视频资源目录 浏览
  • 通过 DLNA 元数据与 HTTP 字幕链接,为原始视频提供外挂 SRT、ASS、SSA、WebVTT 字幕
  • 基于 GPU 抠像和 HEVC 编码的实时透视串流
  • 实时透视流内嵌字幕
  • 绿幕模式与 Alpha 直通模式
  • 离线透视视频生成
  • 基于 DA3 深度和 GPU 立体渲染的实时与离线 2D 转 3D / VR
  • 2D 转 3D 可选深度稳定,包括内置时域稳定和面向离线 16:9 任务的 NVDS ONNX 稳定
  • 面向符合条件的2D与VR源视频的实时/离线 NVIDIA RTX视频超分,支持自适应“8K VR / 4K 2D”输出
  • 2:1 SBS VR左右眼全GPU处理,离线4K VR转8K VR可输出8192x4096 HEVC
  • 超分目标提供 原生1x / 2K / 4K / 6K VR / 8K VR,其中原生1x在源分辨率上增强而不放大
  • RTX VSR目标质量提供低/中/高/超高,HDR观感提供关闭/自然/鲜明三档SDR画面处理,另有仅限离线的NVIDIA TrueHDR真HDR10输出,可调对比度、饱和度、中灰和峰值亮度
  • 实时与离线美颜(正在开发测试,可在设置界面中开启)
  • 实时与离线去马赛克(正在开发测试,可在设置界面中开启)
  • 基于同名 .si.wav sidecar 的配音/同传播放,提供 [SI] DLNA入口、时间选择、声道混音和轻度/正常/强力压低原声
  • DLNA Live 时间索引目录,可按 10 分钟分组、分钟目录和 5 秒播放点选择开始播放时间
  • 支持多个本地视频根目录
  • PySide6桌面UI,包含导航栏、功能卡片首页、离线工具、字幕样式、日志和设置页面
  • 可编辑DLNA服务器名称和HTTP端口,支持中文、英文、日文
  • 字幕预览与字幕样式配置
  • 实时匹配环境光,可设置色温、色调、曝光、对比度、Gamma、饱和度和预设
  • 面向8K级源视频的显存与吞吐优化,在硬件可承受范围内尽量维持目标输出帧率

| 主界面 |

透视视频效果图

Alpha Passthrough 绿幕 Passthrough
Alpha Passthrough 效果图 绿幕 Passthrough 效果图
截图

DLNA 外挂字幕

将 UTF-8 字幕放在原始视频旁,例如 movie.mp4 搭配 movie.srt、movie.zh-CN.srt 或 movie.en.srt。匹配不区分大小写,文件名中的方括号按字面处理。ASS、SSA、VTT 也会下发,能否播放取决于客户端。

服务端同时提供字幕资源、三星 CaptionInfo / CaptionInfoEx 和 pv:subtitleFileUri 关联。SRT 提供 application/x-subrip 与 text/srt 两种资源,HTTP MIME 与各自声明一致。单字幕链接优先选 SRT,再按同名无语言后缀、中文、英文顺序选择。新增、重命名或删除字幕后,下次目录 Browse 即可更新;若播放器缓存了列表,请刷新媒体库。

原始视频的外挂字幕独立于实时字幕烧录开关。播放器仍需支持 DLNA 字幕发现,服务端元数据无法强制不支持的播放器加载字幕。字幕文件按原始字节提供,不自动转换编码。

运行要求

  • Windows 10 / 11
  • Python 3.12
  • NVIDIA GPU,用于GPU处理链路。粗略建议使用RTX 20系列及以上;RTX VSR还要求显卡和驱动支持NVIDIA RTX Video。具体型号请查询NVIDIA官方列表:https://developer.nvidia.com/cuda/gpus。推荐显存:实时服务器、RVM离线生成和普通DA3 2D转3D建议6 GB以上,MatAnyone2 / SAM3离线流程建议约15 GB以上。HD/Large DA3、NVDS和8K超分属于高负载离线流程。
  • FFmpeg / FFprobe

性能提示:4K SBS VR以超高质量转换到8K VR对GPU要求极高,RTX 5060 Ti实测处理速度约23–24 FPS。低端显卡建议降低“目标质量”,或在全局设置中降低“输出FPS”;NVENC P1只控制编码速度,与NGX目标质量不同。

快速启动

uv run python main.py

启动桌面 UI:

uv run python -m ui.app

端口与防火墙

软件启动实时服务器时会占用以下网络端口:

用途 协议 / 端口 说明
HTTP 媒体服务 TCP 8200 提供 DLNA 设备描述、媒体目录、缩略图、原始视频和实时透视视频流。可通过环境变量 PT_HTTP_PORT 修改。
SSDP / UPnP 发现 UDP 1900 用于让 VR 播放器在局域网内发现本机 DLNA 服务器。
启动状态 TCP 8299(仅本机) UI 启动过程中读取 GPU warmup / 启动状态使用。默认只给本机 UI 使用,可通过 PT_STARTUP_STATUS_PORT 修改。

首次启动时,程序会尝试自动添加 Windows 防火墙入站规则:

  • PTServer HTTP Private:允许专用网络上的 TCP 8200 入站。
  • PTServer SSDP Private:允许专用网络上的 UDP 1900 入站。

如果 Windows 弹出 UAC / 防火墙确认窗口,请选择允许。建议只允许“专用网络”,不要暴露到公用网络。

如果误点了拒绝,或播放器无法发现服务器,可以手动添加规则。以管理员身份打开 PowerShell 或命令提示符,执行:

netsh advfirewall firewall add rule name="PTServer HTTP Private" dir=in action=allow protocol=TCP localport=8200 profile=private edge=no enable=yes
netsh advfirewall firewall add rule name="PTServer SSDP Private" dir=in action=allow protocol=UDP localport=1900 profile=private edge=no enable=yes

如果你修改了 PT_HTTP_PORT,请把第一条命令中的 8200 换成实际端口。UDP 1900 是 UPnP/SSDP 标准发现端口,通常不需要修改。

也可以通过 Windows 图形界面设置:

  1. 打开“Windows 安全中心” -> “防火墙和网络保护” -> “高级设置”。
  2. 进入“入站规则”,新建规则。
  3. 规则类型选择“端口”。
  4. 分别添加 TCP 8200 和 UDP 1900。
  5. 操作选择“允许连接”。
  6. 配置文件建议只勾选“专用”。
  7. 名称可填写 PTServer HTTP Private 和 PTServer SSDP Private。

支持的 VR 视频播放器

基于 Meta Quest 3 设备测试。

播放器 Alpha 直通 灰色绿幕 ChromaKey 绿幕 网站 备注
Thru3D Media Player 支持 - - - 仅支持 Alpha 透视
Skybox VR Player 2.0.2 Preview 支持 - 支持 官网 安装说明
Moon Player - 支持 支持 官网 -
4XVR Video Player 支持 - 支持 官网 -
DeoVR player 支持 - 支持 官网 -
HereSphere VR Video Player 支持 - 支持 官网 -

配置说明

  • PT_VIDEO_DIR 支持用 | 分隔的多个目录
  • 媒体根目录必须是本地路径。支持映射成本地盘符/目录的云盘,不支持UNC网络共享根路径。
  • PT_PASSTHROUGH_OUTPUT_MODE 支持 none、green、alpha、two_dvr、superres,也支持 green,alpha,two_dvr,superres 这类逗号分隔组合;旧的 all 表示 green + alpha
  • Alpha 模式下虚拟条目标题为 Alpha Passthrough
  • 实时 2D 转 3D 使用 PT_TWO_DVR_MODEL、PT_TWO_DVR_STRENGTH 和相关 PT_TWO_DVR_* 设置;离线 2D 转 3D / VR 在桌面 UI 中提供模型、画质速度、时域稳定和“目标文件存在则跳过”等控制。
  • 实时超分使用 PT_RTX_VSR_TARGET_HEIGHT、PT_RTX_VSR_QUALITY 和 PT_RTX_VSR_HDR_LOOK。自适应4096目标对识别出的2:1 SBS VR输出8192x4096,对普通2D输出3840x2160。HDR观感设为 truehdr 只影响离线任务,实时链路保持SDR观感。
  • 同名 .si.wav 文件会启用 [SI] DLNA入口。实时播放通过 /si_live 输出 MPEG-TS;选择虚拟 MP4 播放时使用 /media_si,复制原视频样本并搭配混音 AAC 音轨。
  • 工具箱可在生成同声/克隆音频后提前输出同名 .si.mix.m4a 和 .si.mix.json。虚拟 MP4 会校验输入文件、混音规则和输出音轨,再直接使用预生成 AAC,跳过整片混音编码。普通 SI 需匹配服务器默认参数;带 .si.duck.wav 的配音匹配配音模式固定参数。文件过期、损坏或设置不匹配时自动走原有音频缓存/转换流程;请保留原 .si.wav 和可选的 .si.duck.wav。
  • 有效的 .si.mix.m4a 会直接作为虚拟 MP4 音轨;浏览、后台预热和 HEAD/GET 都不会再向 runtime_cache/si_virtual_mp4 复制或生成源音轨、混音音轨。响应头 X-SI-Audio-Source: prepared-m4a 表示正在使用它;runtime-cache 表示使用服务器缓存/转换结果。
  • DLNA Live目录会按功能显示 [GREEN]、[ALPHA]、[2D>3D]、[SuperRes] 和 [SI] 标记,并提供本地化的 [选择时间索引] 目录。
  • 桌面设置页可修改DLNA服务器名称和HTTP端口;保存网络身份配置后需要重启服务器。
  • Windows发布包已包含验证过的CUDA 12.6 RTX VSR bridge、NGX运行库、本地CUDA runtime、许可证和版本信息,终端用户不需要自行编译bridge。
  • TensorRT 加速在桌面 UI 的“性能配置”中控制。请先进入 TensorRT -> 配置 构建缓存;首次构建可能需要数分钟。如果驱动、CUDA、TensorRT 或模型变化导致缓存缺失/过期,服务器会自动回退到 CUDA。
  • UI 配置与后台运行配置分离保存

网盘整合包

【夸克网盘】 【百度网盘】

项目结构

main.py        服务入口
config.py      运行时配置
dlna/          UPnP / DLNA 发现与目录
http_app/      FastAPI 路由
pipeline/      解码、抠像、编码、缩略图、字幕流水线
offline/       生产用离线转换入口
ui/            PySide6 桌面 UI、页面、国际化与进程控制
tools/         开发探针和诊断工具
models/        本地模型文件与清单
resources/     打包用 UI / 运行时资源
prompt/        交接记录与调研文档

引用的开源模型

Thru3D媒体服务器 本身不训练抠像模型,只使用下列上游项目提供的模型与模型文件。

模型 用途 上游链接
Robust Video Matting (RVM) 实时主抠像路径,包括 rvm_mobilenetv3_fp32.onnx 和 rvm_resnet50_fp32.onnx GitHub
MatAnyone2 离线转换与实验流程中使用的更慢但通常更高质量的抠像路径 GitHub
Segment Anything Model 3 (SAM 3) 用于高质量离线Alpha预处理流程的可选辅助分割模型 GitHub
Depth Anything 3 (DA3) 实时与离线 2D 转 3D / VR 使用的单目深度模型 GitHub
NVDS 面向 16:9 源的离线 2D 转 3D 深度 / near-map 时域稳定器 GitHub

引用的依赖

说明

  • 本项目当前主要面向本地 Windows 机器运行,而不是作为托管服务部署。
  • 各生成模式以独立DLNA条目按需处理,原始媒体保持不变并继续可播放。
  • 当前处理链路主要针对VR180半等柱体投影视频优化,同时支持部分普通2D视频流程。
  • 英文版请见 README.md,日文版请见 README.ja-JP.md。

许可

许可:AGPL-3.0-or-later。

项目许可见仓库根目录的许可证文件。上游模型仓库各自保留自己的许可与使用条款。