使用文档 — WWPlayer

快速开始

1. 安装 WWPlayer

选择一种发布形式：

Microsoft Store / MSIX：由 Windows 安装和管理，适合日常使用。
Portable：运行解压目录中的 WWPlayer.exe，无需传统安装程序。

WWPlayer 当前面向 Windows 10 / 11 x64。内置播放器依赖本机显卡驱动、音频设备和系统媒体能力，建议保持 Windows 与显卡驱动为可用版本。

2. 添加第一个媒体来源

打开左侧“服务器”页面。
点击添加按钮。
选择 Emby、Jellyfin、飞牛影视、WebDAV、OpenList、OneDrive、SMB 或本地目录。
填写地址和登录信息，或完成文件夹选择、浏览器授权。
对需要检测的来源先执行“登录检测”“连接检测”或“访问检测”。
检测成功后保存。

3. 浏览并播放

媒体服务器会显示自身的首页、媒体库、继续观看和最近更新。
文件型来源可以浏览目录；支持刮削的来源还可以生成匹配后的媒体库视图。
打开影片详情，选择剧集和资源，然后开始播放。
同一影片存在多个来源时，Pro 版可以在详情页和播放器中聚合并切换资源。

4. 按需连接外部服务

TMDB：元数据、图片、发现栏目和匹配。
Trakt：播放记录、继续观看、推荐和追剧日历。
Bangumi：动画收藏状态和放送日历。
WWPlayer 账户：个人资料、云端配置和 NEXUS 在线分享。
WebDAV 配置备份：使用自己的 WebDAV 空间备份配置，属于 Pro 功能。

媒体服务器账号、WWPlayer 账户、Trakt、Bangumi 和 Microsoft Store 授权彼此独立，登录其中一个不会自动登录或解锁其他服务。

安装、更新与数据位置

Microsoft Store / MSIX

商店版的数据由 Windows 应用包管理：

稳定配置和用户托管数据位于应用包的 LocalState。
图片、元数据、缩略图、弹幕、播放缓存和日志等可再生成数据位于 LocalCache。

需要查找实际目录时，优先使用设置中的日志、缓存、截图或配置入口，不建议直接修改应用包目录。

Portable

Portable 只表示应用无需安装，不表示所有配置都写在程序旁边。正式 Portable 版本默认使用：

%LOCALAPPDATA%\WWPlayer-Portable

因此移动或删除程序目录通常不会自动带走配置。迁移设备时应使用账户同步、WebDAV 配置备份或应用提供的导入导出功能。

非商店开发或普通桌面环境

默认持久数据目录为：

%LOCALAPPDATA%\WWPlayer

具体文件布局可能随版本调整。除排障外，不要在程序运行时手动覆盖配置文件。

检查更新

进入“设置 > 关于”点击“检查更新”。商店版会跳转或交由 Microsoft Store 更新；其他发布形式以发布渠道提供的版本为准。

添加媒体来源

WWPlayer 将来源分成两类：

媒体服务器：Emby、Jellyfin、飞牛影视，提供账号、媒体库、详情、观看状态和服务端播放信息。
文件型媒体来源：本地目录、WebDAV、OpenList、OneDrive、SMB，提供目录和文件访问；部分来源支持扫描和 TMDB 匹配。

支持范围

来源	连接方式	主要能力
Emby	地址、用户名、密码	媒体库、详情、剧集、收藏、进度、资源、线路
Jellyfin	地址、用户名、密码	兼容 Jellyfin API 的媒体库、详情、进度和播放
飞牛影视	FN ID 或地址、账号	媒体库、详情和播放；以服务端实际接口为准
WebDAV	地址、目录、用户名、密码	文件浏览、扫描、播放；Pro 可进行 TMDB 匹配
OpenList	WebDAV 地址和账号	文件浏览、扫描、播放；Pro 可进行 TMDB 匹配
OneDrive	浏览器登录，或高级令牌配置	云盘目录、媒体扫描和播放
SMB	`\\NAS\Media` 或 `smb://NAS/Media`	局域网共享目录浏览和播放
本地目录	Windows 文件夹选择器	本地扫描、播放；Pro 可进行 TMDB 匹配

不同服务端版本、接口权限、反向代理和目录组织方式会影响可用能力。客户端只展示来源实际提供或成功匹配的数据，不会伪造不存在的媒体信息。

Emby

在添加来源中选择“Emby”。
填写名称。
输入主机、端口和可选路径。常见地址例如：
```
https://emby.example.com
http://192.168.1.20:8096
```
填写 Emby 用户名和密码。
按需选择是否使用系统代理。
点击“登录检测”。
检测成功后保存。

保存后可以在来源设置中管理名称、图标、线路和登录状态。多条线路适合内网、外网或备用入口；线路改变只影响该服务器后续请求，不会复制媒体库。

Jellyfin

添加方法与 Emby 相同，但应在来源类型中明确选择“Jellyfin”。WWPlayer 会使用 Jellyfin 类型对应的兼容请求，实际可用功能仍取决于 Jellyfin 版本、插件和账号权限。

不要把 Jellyfin 伪装成 Emby 类型以绕过检测；正确的来源类型有助于应用选择对应兼容策略。

飞牛影视

选择“飞牛影视”。
输入 FN ID，或输入可访问的飞牛影视地址。
填写账号信息。
完成登录检测并保存。

飞牛影视的媒体字段和播放能力以其当前接口返回为准，不保证与 Emby 或 Jellyfin 完全一致。

WebDAV

选择“WebDAV”。
输入服务器地址、端口和路径。
可在“媒体目录”中限制扫描范围；留空时从配置的根目录开始。
填写 WebDAV 用户名和密码或应用密码。
执行连接检测并保存。

保存后后台会建立目录索引。免费版可以浏览文件并播放；Pro 版可以进一步进行 TMDB 自动匹配和手动更正。

OpenList

OpenList 通过其 WebDAV 入口接入，常见路径为 /dav。填写 OpenList 地址、端口、WebDAV 账号和媒体目录，检测成功后保存。

OpenList 中的远端存储能否稳定播放，取决于其返回的下载地址、重定向、有效期、Range 支持和上游网盘限制。

OneDrive

推荐使用浏览器授权：

选择“OneDrive”。
点击“使用浏览器登录 OneDrive”。
在浏览器中完成 Microsoft 账号授权。
返回 WWPlayer，等待账号和根目录确认。

高级用户也可以展开“高级令牌接入”，填写 Client ID、Refresh Token、Tenant、可选 Client Secret 和根目录 Item ID。不要将这些凭据发送给他人或写入公开 issue。

SMB

选择“SMB”。
输入共享路径，例如：
```
\\NAS\Media
smb://NAS/Media
```
执行访问检测并保存。

SMB 主要面向局域网共享。访问失败时先确认 Windows 本身能访问该共享、网络发现正常，并检查共享权限和凭据缓存。

本地目录

选择“本地”。
点击“选择文件夹”。
允许 WWPlayer 扫描目录。

本地来源可以直接浏览和播放文件。Pro 版可将识别出的电影、剧集和单集与 TMDB 匹配，形成带海报、背景、简介和分类的媒体库。

扫描、匹配与更正

文件型来源保存后会在后台扫描。来源卡片会显示目录数、文件数、已匹配数量和待匹配数量。

可用操作包括：

浏览文件或匹配后的媒体库；
重新扫描来源；
停止当前扫描；
对未匹配或错误匹配的项目执行手动匹配、更正或解除匹配；
删除来源。

自动匹配主要依赖文件名、目录层级、季度集数信息和外部元数据。建议使用清晰的命名，例如：

Movie Name (2024).mkv
Series Name (2024)\Season 01\Series Name S01E01.mkv

扫描失败不会自动删除已有索引。移除来源前应确认它不再被首页栏目、播放记录或其他配置引用。

浏览、搜索与详情页

来源首页

选择媒体服务器后，可以浏览服务端提供的：

首页轮播；
继续观看；
最近更新；
收藏；
媒体库和分类；
电影、剧集、季度和单集。

文件型来源可以进入文件浏览页；具备匹配数据时，还可进入电影和剧集媒体库视图。

搜索

搜索有三种范围：

当前来源搜索：只查询当前服务器或当前数据范围。
聚合搜索Pro：并行查询允许参与聚合的多个媒体服务器，并按来源整理结果。
模块搜索：已安装且启用“参与聚合搜索”的模块可以加入聚合结果。

旧搜索请求不会覆盖较新的关键词结果。某个来源失败时，其他已成功来源仍可显示。

详情页

详情页可能包含：

标题、原名、年份、简介、类型和分级；
海报、背景和艺术图；
TMDB、IMDb、豆瓣等可用评分；
演员、导演和人物详情；
预告片；
季度、剧集和观看进度；
相似内容和推荐；
视频、音频、字幕、分辨率、编码、动态范围、位深、码率和帧率；
同一媒体在其他来源中的候选资源。

服务端缺少字段时，对应区域可能不显示。相同标题不一定代表同一媒体；聚合会优先使用 TMDB、IMDb、TVDB 等公共身份和准确季集信息。

资源聚合与选源

Pro 版会在身份匹配成立时，把多个服务器和模块提供的同一影片或单集资源集中到详情页。资源仍保留真实来源，不会被复制到某一个服务器。

可按实际数据查看或筛选：

来源服务器和线路；
特殊格式；
分辨率；
视频编码和动态范围；
码率；
文件大小；
音轨和字幕。

剧集资源必须匹配到准确的系列、季度和集数。仅标题相同、身份不足的结果不会强行作为当前单集资源。

观影感受

详情页可以展示公共观影感受排名，并以 emoji 动画发射已有结果。

未登录 WWPlayer 账户也可查看和播放公共动画。
登录账户后可以选择自己的感受并提交。
每个账户对同一 TMDB 电影或剧集只保留一个当前感受；重新选择会替换旧值。
媒体服务器登录不等于 WWPlayer 账户登录。

“自动发射播放感受”只自动展示已有结果，不会代替用户提交选择。

首页与栏目

WWPlayer 的首页是一套可编辑内容工作台。首页功能对免费版和 Pro 版均开放；涉及多服务器聚合、文件刮削等受限来源时，仍按对应授权能力执行。

启用首页

在“设置 > 通用”打开“启用首页”。启用后可以使用顶部首页入口和首页管理功能。

新安装会提供默认首页。旧版本已有首页配置时，会保留原有栏目、顺序和来源。

多首页

可以创建多个首页，例如：

电影；
剧集；
动画；
儿童内容；
本地媒体；
直播。

首页管理支持：

新建空白首页；
新建默认首页；
导入首页文件；
修改名称和图标；
调整首页顺序；
设置主首页；
删除首页；
在顶部快速切换首页。

启动时进入主首页，不会把临时切换的首页自动改成主首页。

首页独立播放历史

首页可以启用“独立播放历史”。开启后：

从该首页开始的播放记录保留在该首页中；
不向其他本机继续播放来源或 Trakt 上报；
其他播放记录也不会自动进入该首页。

该功能适合需要隔离观看记录的首页。它不等同于 Windows 用户隔离，也不会创建独立媒体服务器账号。

轮播

每个首页可以单独设置轮播来源和数量。轮播可以引用内置来源、模块、服务器、片单或其他可用数据源。

首页还支持是否取消分页。关闭分页后，栏目会在同一首页中连续排列。

栏目来源

栏目可以使用：

TMDB 热门、趋势、高分、上映中和分类内容；
国内外流媒体平台和制作公司分类；
Trakt 热门、趋势、期待、推荐、收藏、列表和日历；
Bangumi 放送日历；
Emby、Jellyfin、飞牛影视媒体库和最近更新；
本地、WebDAV、OpenList 等已匹配媒体；
待看和自定义片单；
已安装模块；
M3U / M3U8 电视直播。

栏目布局

栏目编辑器提供以下布局：

趋势；
海报；
横版海报；
宽卡；
排行；
紧凑；
评分展示；
聚光；
拼贴；
大分类；
小分类；
排行榜；
本地文件夹；
日历；
电视。

并非每种来源都适合所有布局。日历和电视等专用布局会限制为对应的数据类型。

首页导入与导出

首页可以导出为：

<首页名称>.wwhome.json

文件包含首页布局和它引用的非内置模块，但不包含 WWPlayer 账户、媒体服务器登录信息、缓存或模块运行时存储。

导入时：

不覆盖现有首页；
为导入对象分配新的本机身份；
检查格式和模块依赖；
服务器、本地目录和片单等本机来源需要重新绑定；
任一必需模块校验失败时不会留下半成品首页。

片单与观看状态

待看与自定义片单

可以把电影或剧集加入待看，也可以创建自定义片单。片单可用于首页栏目、NEXUS 分享和本地导入导出。

片单导出要求每个项目具备 TMDB、IMDb 或 TVDB 等公共影片标识。没有公共身份的本地或模块项目需要先完成匹配，否则无法生成可移植片单。

媒体服务器收藏会按服务端能力回写。聚合收藏属于 Pro 功能，可从多个允许参与聚合的服务器读取并合并展示。

观看状态

常见操作包括：

标记电影已观看或未观看；
标记剧集到指定单集；
标记整季或整剧；
清除播放进度；
从继续观看中移除；
播放停止或完成时保存进度。

服务器媒体优先写回对应服务器；本地、存储和模块媒体使用本机播放记录。不同来源的同名媒体只有在身份足够明确时才会合并进度。

继续播放来源

继续播放详情可以在以下来源间切换：

普通记录；
聚合记录Pro；
Trakt 记录。

可以锁定一种来源作为首页默认继续播放类型。锁定只改变展示选择，不会把三类记录互相复制或改写。

播放器

内置 libmpv 与外置 mpv

播放方式	特点	注意事项
内置 libmpv	与 WWPlayer 界面、播放状态、截图、弹幕和设置完整集成	依赖本机驱动和内置内核能力
外置 mpv	使用用户选择的 `mpv.exe`	外置程序使用自己的配置和脚本，部分内置交互不可用

在“设置 > 播放器”中切换内核。外置 mpv 必须选择有效的 mpv.exe 路径。

Stable 与 Beta 内核

内置播放器提供 Stable 和 Beta 渠道。两者使用同一套播放状态和正式播放流程；Beta 允许启用下一集媒体预加载等实验能力。

如果更重视兼容性，使用 Stable。需要测试下一集预加载时选择 Beta。

播放路线

播放器会根据来源返回的资源和兼容策略建立一次明确的播放计划，常见形态包括：

静态直连文件；
服务端 stream 地址；
服务端管理的 HLS；
WebDAV、OpenList、OneDrive、SMB 或本地文件；
模块提供的 HTTP(S) 资源；
有界解析后的重定向、STRM 或链接资源。

播放失败时只会在明确允许的候选路线内进行有限切换，不会无限重试，也不会把任意错误伪装成成功。

播放控制

播放器支持：

播放、暂停；
快退、快进；
进度拖动和缓冲范围；
音量、静音和最高音量设置；
播放速度和速度记忆；
窗口、窗口全屏和独占全屏；
记住窗口大小和位置；
选集和下一集；
音轨、字幕、弹幕和片段菜单；
播放中切换其他资源；
媒体信息和资源标签；
截图和 GIF；
播放器置顶；
OSD 网速、进度、时间和系统时间。

默认快捷键

操作	默认键
播放 / 暂停	`Space`
快退	`←`
快进	`→`
音量增大 / 减小	`↑` / `↓`
静音	`M`
全屏	`F`
下一集	`N`
字幕菜单	`S`
音轨菜单	`L`
降低 / 提高速度	`[` / `]`
恢复 1 倍速	`\`
退出全屏	`Esc`

可在“设置 > 快捷键”中重新绑定。发生按键冲突时，设置页会指出冲突操作。

拖动进度的前提

资源必须具备可靠的 seek 能力。直播、部分 HLS、过期签名地址、不支持 Range 的 HTTP 资源或某些服务端转码可能无法任意跳转。

不能拖动进度通常是资源能力限制，不代表播放器窗口已经损坏。可以先切换其他资源或线路确认。

缓冲与完整缓存

内置播放器可以设置：

缓冲时长；
缓存容量；
播放缓存目录；
“当前这一集完整缓存”。

开启完整缓存后，普通缓冲参数由完整缓存模式接管，同时不会进行下一集媒体预加载。完整缓存适合希望优先缓存当前媒体的场景，但需要更多磁盘空间和网络读取时间。

下一集预加载

下一集媒体预加载需要：

使用内置 Beta 内核；
全局开关已开启；
当前服务器允许预加载；
未启用“当前这一集完整缓存”；
下一集与当前播放属于相同来源身份；
资源形态受支持；
当前集已经进入尾段，并具备明确的缓存完成证据。

可预加载的资源包括受支持的 HTTP(S) MP4、MKV、WebM 和部分 HLS 点播。直播、无限 HLS、不稳定转码、未解析资源和身份不一致的跨来源项目不会强行预加载。

“已预加载”只表示准备了可消费的缓存数据，不表示下一集已经呈现首帧或上报为正在播放。停止、换源、关闭播放器或目标改变时，旧预加载会被取消。

视频与 HDR

内置播放器支持：

gpu-next 和 gpu 视频输出；
自动安全硬解、D3D11、D3D11 Copy 和软件解码；
自动或手动选择 GPU；
HDR 跟随 Windows、强制 SDR、强制 HDR；
Auto、Clip、BT.2390、Reinhard 色调映射；
HDR 峰值计算；
Anime4K 超分辨率Pro。

出现黑屏、花屏、掉帧或 HDR 颜色异常时，先将视频输出、GPU、硬解和 HDR 恢复为自动，再一次只调整一个选项。

Anime4K 会增加 GPU 负载。低功耗设备、核显或高分辨率片源应从较轻预设开始。

音频

音频设置包括：

关闭增强；
立体声下混；
人声增强；
夜间模式；
100% 至 200% 的播放器音量上限。

超过 100% 属于软件增益，可能造成失真。遇到爆音时恢复到 100%，并检查系统和音响设备音量。

自定义 mpv.conf

内置播放器可以启用自定义 mpv.conf。当配置文件接管某项能力时，设置页中的对应控件会显示由 mpv.conf 管理，例如：

默认字幕或音轨；
硬件解码；
GPU；
字幕样式；
音频增强；
Anime4K。

不要同时在配置文件和界面中反复写入相互冲突的参数。排障时可先关闭自定义配置确认问题是否仍然存在。

字幕、弹幕与片段

字幕来源

播放器按来源分类显示：

在线字幕Pro；
本地导入字幕；
服务端外挂字幕；
媒体内封字幕。

本地字幕支持常见的 SRT、ASS、SSA、SUB、VTT 和 SUP。是否能正确显示还取决于文件编码、字体、时间轴和 libmpv 对具体格式的支持。

字幕调整

可以设置：

默认字幕语言；
字幕开关和轨道；
字号和高度；
时间延迟；
字体和字体颜色；
默认、描边阴影、背景框样式；
描边、阴影、背景颜色和透明度。

播放中的调整可以即时预览。自定义 mpv.conf 接管字幕属性时，对应控件不可同时修改。

在线字幕

在线字幕属于 Pro 功能。进入字幕菜单的“在线字幕”，输入影片或剧集名称并搜索，然后选择结果下载和载入。

搜索结果来自当前可用的字幕提供方。没有结果、下载失败或字幕内容错误时，可以修改关键词或改用本地字幕；应用不会把失败结果伪装成已载入轨道。

弹幕

在“设置 > 字幕&弹幕”中可以：

启用或关闭弹幕；
添加、移除和排序最多 5 个兼容 API；
单独启用或停用某个 API；
设置字体、颜色、透明度和字号；
调整速度、显示区域、同屏数量和时间偏移；
屏蔽顶部、底部或滚动弹幕；
启用弹幕热度图。

播放器还支持载入本地弹幕文件。弹幕自动匹配依赖标题、季度、集数和 API 返回格式；匹配错误时可在播放器中重新选择来源或手动匹配。

第三方弹幕内容和接口可用性不由 WWPlayer 保证。

片头片尾与媒体片段

播放器的片段菜单支持：

关闭跳过；
手动提示跳过；
自动跳过；
查看和切换片段来源；
手动设置片头开始、片头结束和片尾开始；
清除手动标记。

片段可来自媒体服务器、外部片段服务或本机标记。可在“设置 > 外部连接”管理片段来源，并填写可选的 TheIntroDB API Key。

片段数据只影响正式播放起点和跳过行为，不会修改原始媒体文件。

截图与 GIF

播放器在真实视频画面已经呈现后才允许捕获：

短按截图按钮创建截图；
长按截图按钮录制最长约 10 秒的 GIF。

捕获后会进入独立编辑界面，不会立即写入用户目录。可以选择：

默认版式；
电影票版式；
横版拍立得版式；
是否显示徽标、资源信息、媒体时间和水印；
保存；
复制并保存；
设为个人中心背景；
取消。

截图和 GIF 的保存位置在“设置 > 储存与缓存”中配置。取消编辑不会留下已发布文件；保存成功后才写入目标目录。

GIF 编辑预览和导出会保留动画。复制后的 GIF 是否继续播放取决于接收应用对剪贴板格式的支持。

账户与配置同步

WWPlayer 账户是什么

WWPlayer 账户用于：

昵称和头像；
个人中心；
月度观看统计；
云端配置同步；
提交观影感受；
管理 NEXUS 在线分享。

它不替代媒体服务器账号、Microsoft Store 授权、Trakt 或 Bangumi 账号，也不会授予媒体访问权限或 Pro 权益。

注册、验证和登录

注册需要：

昵称；
邮箱；
至少 10 个字符的密码；
同意用户协议和隐私政策；
输入六位邮箱验证码。

验证码发送失败时可以显式重发，不需要重复创建账户。已有待验证账户可以从登录页继续“验证邮箱”。

忘记密码时，输入邮箱获取六位验证码，再设置 10 至 128 个字符的新密码。重置成功不会自动登录，原有会话会被撤销。

首次登录同步

每台设备、每个账户首次成功登录后，会读取最新云端配置并尝试恢复一次。

云端有配置时，恢复成功后记录本机首次同步已完成。
云端没有配置时，保留当前本机配置，不自动上传默认值。
恢复失败时保留有效登录，并提示同步未完成。
退出登录不会清除本机首次同步记录。
已完成首次同步后的普通启动、刷新账户或重新登录，不会反复覆盖本机修改。

手动上传和恢复

个人中心提供：

上传同步：用当前本机配置更新云端备份。
同步 / 恢复：把用户确认的云端版本恢复到本机。

上传使用版本检查。两台设备同时修改时，旧版本上传可能返回冲突；此时应刷新云端状态，确认要保留的版本后重新操作，不会自动重试覆盖。

恢复会保留本机 Store 授权和播放记录。恢复失败时不会报告假成功。

同步包含与排除

账户云端配置可以包含媒体服务器定义、线路、首页、模块和通用偏好，包括连接媒体所需的服务器登录信息。

以下内容不随账户配置恢复覆盖：

Microsoft Store 授权；
安装身份；
本机播放记录；
诊断数据；
窗口和设备专属路径；
本机字幕；
WebDAV 配置备份凭据。

传输使用 HTTPS；服务端验证账户后加密保存配置。该方案是托管加密，不是只有设备才能解密的端到端加密。

外部连接

TMDB

TMDB 用于元数据、搜索、艺术图、流媒体平台栏目和本地媒体匹配。

设置页允许填写个人 TMDB API Key。填写后，支持的 TMDB 请求会使用个人凭据直连；未填写时，应用会对受支持操作使用 WWPlayer 元数据服务。个人密钥无效或直连网络不可达时，不会静默冒充另一路线成功。

可以为 TMDB 单独设置系统代理、不使用代理或手动代理，并执行连接检测。

Trakt

连接 Trakt 后可以使用：

热门、趋势和期待内容；
推荐和个人列表；
Trakt 继续观看；
追剧日历；
播放开始、暂停和停止记录上报。

退出 Trakt 后，依赖 Trakt 的栏目和同步停止更新，本机与媒体服务器记录仍然保留。

模块或本地项目只有具备可信的 TMDB、IMDb、TVDB 或 Trakt 身份时才会上报；不会按文件名猜测账户中的影片。

Bangumi

Bangumi 使用 Access Token 连接。连接后可读取支持的收藏状态和动画放送日历。

在设置页点击“获取 Token”打开授权入口，取得令牌后粘贴并连接。令牌属于账户凭据，不要公开分享。

豆瓣评分

“豆瓣评分（实验性）”用于在可匹配时补充评分。实验功能可能受网页或接口变化影响；关闭后不影响 TMDB、IMDb 或服务器自身评分。

WebDAV 配置备份

WebDAV 配置备份属于 Pro 功能，只需要：

WebDAV 目录地址；
用户名；
WebDAV 登录密码或应用密码。

不再使用独立备份密码，也不会从登录密码派生备份密钥。

新备份是 WWPLAYER_WEBDAV_CONFIG_V2 配置快照。访问保护由 WebDAV 权限和 HTTPS 传输承担；快照可能包含媒体服务器凭据，因此能读取备份文件的 WebDAV 服务也可能读取其中配置。

WebDAV 登录凭据本身不会写进快照。更换 WebDAV 登录密码不会改变已有备份内容，只会影响后续连接。

旧版加密备份不会自动解密或静默当作空配置。遇到旧格式时，应从仍保留有效配置的设备重新上传新版备份。

模块

模块用于扩展首页数据、搜索、详情或播放资源。进入“设置 > 模块”可以查看内置来源和已安装模块。

安装方式

从本地导入 JavaScript 模块；
输入模块 URL 下载；
从 FWD 模块索引中预览并安装；
通过首页文件或 NEXUS 安装依赖模块。

安装前会检查模块声明和代码。模块在隔离 Worker 中运行，但模块仍可能访问它被授予的网络目标和用户填写的参数，只应安装可信来源。

模块能力

模块可以声明：

列表和分类；
搜索；
详情；
季度和剧集；
播放资源；
参数和凭据；
网络模式。

模块设置按全局、代码和来源参数分别保存。某个模块可选择是否参与聚合搜索。

模块播放

模块提供的资源使用与其他来源相同的播放器状态机。模块失败不会创建另一套播放器流程，也不会把纯元数据条目当成可播放资源。

模块项目会保存本机播放记录；连接 Trakt 且身份明确时可以正常上报。首页启用独立播放历史时，不对外上报。

更新和移除

带来源 URL 的模块可以从 URL 更新。移除模块时，会同步清理首页中引用它的栏目、分类单元和轮播引用。

更新或移除前应确认自定义首页是否依赖该模块。模块运行时数据不会自动发布到 NEXUS 或首页分享文件中。

NEXUS

NEXUS 用于分享和载入：

首页；
片单；
模块。

载入分享码

进入“设置 > NEXUS > 载入”。
输入分享码。
点击“载入”。
检查名称、类型和版本。
片单可选择进入片单页、指定首页，或同时进入两处。

也可以从本地 NEXUS 文件、旧首页 JSON、片单 JSON 或 JS 模块载入。

同步最新版本

在线载入项会记录来源和版本。点击“同步最新版本”会原位覆盖该载入项：

首页替换对应首页内容；
片单替换其所属片单或栏目；
模块替换对应模块；
不创建重复副本；
不保留本地修改；
不保留被替代的历史版本。

同步前应确认本地修改不再需要。分享已下架、版本不可用或依赖失效时会明确失败，不会偷偷换用其他版本。

分享到 NEXUS

在线发布需要登录 WWPlayer 账户。可以：

选择本机首页、片单或模块；
填写三段数字版本，例如 1.0.0；
填写描述；
为首页或模块添加可选截图；
为片单选择栏目样式；
设置公开分享者 ID；
上传到 NEXUS，或只导出本地文件。

模块必须填写描述。更新已发布作品时，新版本必须高于当前版本，更新后不提供旧版本下载。

首页和模块可能需要审核。审核中的作品不能再次更新；审核通过后分享码保持不变。

分享者 ID

分享者 ID 是公开署名，可与账户昵称不同，但需要保持唯一。修改后会统一更新本人所有在线分享。它不是账户 ID，也不能用于登录。

依赖与隐私

NEXUS 首页可以按需带入所需模块。模块会先经过校验，再与首页一起安装；已有完全相同模块会复用，发生冲突时会创建新本机身份并重写该首页引用。

分享内容不应包含账号、令牌、Cookie、私人服务器地址或其他敏感参数。发布前仍应检查模块代码、参数默认值、截图和描述。

免费版与 Pro

实际授权状态、价格、购买入口和有效期以应用内 Microsoft Store 信息为准。

免费版

免费版当前包括：

添加并使用 1 个 Emby、Jellyfin 或飞牛影视媒体服务器；
添加本地、WebDAV、OpenList、OneDrive 和 SMB 文件型来源；
浏览媒体服务器和文件目录；
使用首页、多首页、栏目和模块；
使用内置 libmpv 或外置 mpv；
使用字幕轨、本地字幕、弹幕、片段、截图和 GIF；
使用本机播放记录、片单和观看状态；
连接 TMDB、Trakt 和 Bangumi；
登录 WWPlayer 账户并使用账户配置同步；
载入和本地导出 NEXUS 内容。

Pro 新增能力

Pro 解锁：

不限于 1 个媒体服务器；
跨服务器搜索、收藏和继续观看聚合；
详情页和播放器中的跨服务器资源聚合与切换；
本地、WebDAV 和 OpenList 媒体的 TMDB 刮削、自动匹配和手动更正；
在线字幕搜索与载入；
Anime4K 超分辨率；
WebDAV 配置备份与恢复。

首页和模块本身不再是 Pro 专属功能。某个首页引用 Pro 数据能力时，只有受限部分会按当前授权状态收敛。

授权说明

Pro 由 Microsoft Store 授权状态决定。
WWPlayer 账户登录不会授予 Pro。
媒体服务器账号不会授予 Pro。
授权失效时，已保存配置不会自动删除，但运行时只使用当前版本允许的能力。
免费版只会使用配置中的第一个有效媒体服务器；升级后可重新使用其余已保存服务器。

设置参考

通用

启用首页；
关闭到托盘；
首页自动待机时间；
趋势来源和展示样式；
搜索框自动收起；
自动播放预告片；
自动发射播放感受；
详情简介收起；
继续播放卡片直接播放；
日志目录、日志导出和播放器诊断。

外观

浅色或深色主题；
强调色；
海报缩放；
详情磨砂背景；
轮播 TMDB 背景；
资源徽章包。

模块

管理 TMDB、Trakt 和第三方模块数据来源；从文件或 URL 导入模块；配置模块参数和聚合搜索参与状态。

NEXUS

载入、同步、导出和分享首页、片单与模块。

网络

“软件代理”和“TMDB”分别拥有代理设置：

跟随系统；
不使用代理；
手动代理。

手动地址示例：

http://127.0.0.1:7890

“忽略 SSL 证书校验”需要重启。它只应用于允许该策略的媒体请求，不会放宽 WWPlayer 中央账户等严格 TLS 边界。只有在明确了解自签名证书风险时才使用。

播放器

打开播放器时的窗口模式；
窗口大小和位置；
播放时最小化主窗口；
速度记忆；
内置 / 外置播放器；
Stable / Beta；
自定义 mpv.conf；
缓冲和完整缓存；
默认字幕和音轨；
视频输出、硬解、GPU；
Anime4K；
音频增强和音量上限；
资源标签和时轴缩略图；
OSD。

字幕&弹幕

管理字幕样式、弹幕开关、最多五个弹幕 API、弹幕字体、颜色、速度、区域、数量、偏移和屏蔽项。

快捷键

修改播放器按键。保存前解决冲突，避免一个按键同时对应多个操作。

服务器管理

聚合搜索、继续观看和收藏总开关Pro；
每个服务器是否参与聚合；
每个服务器参与哪些聚合类别；
下一集预加载总开关；
每个服务器是否允许下一集预加载。

来源的添加、登录、线路、扫描和删除位于主界面的“服务器”页面。

储存与缓存

截图和 GIF 保存位置；
元数据缓存占用和清理；
图片缓存占用、过期天数和容量上限；
播放缓存占用、目录和清理。

清理缓存不会删除媒体服务器、首页、片单或配置，但会使对应图片、元数据、缩略图或缓存媒体重新下载或生成。

外部连接

管理 TMDB、豆瓣评分、Trakt、Bangumi、片段来源和 WebDAV 配置备份。

关于

查看版本和授权状态、检查更新、打开商店和社区、切换应用图标、创建桌面快捷方式、查看隐私政策和开源软件声明。

数据、备份与隐私

本机保存的数据

按启用功能不同，本机可能保存：

媒体服务器和文件型来源配置；
用户名、访问令牌和必要凭据；
首页、栏目、模块和片单；
本机播放记录和观看偏好；
本地媒体索引和匹配结果；
元数据、图片、缩略图、弹幕和播放缓存；
截图、GIF 和个人中心背景；
应用日志和可选播放器诊断。

三种配置迁移方式

方式	适用场景	说明
WWPlayer 账户同步	同一账户多设备	首次自动恢复一次，也可手动上传和恢复
WebDAV 配置备份Pro	使用自己的 WebDAV 空间	不使用独立备份密码，备份可包含媒体凭据
首页、片单、NEXUS 文件	分享局部内容	不等于完整应用配置备份

这些方式不会同步媒体文件本身。

凭据保护

不要公开媒体服务器密码、访问令牌、Cookie、OneDrive Refresh Token 或完整签名 URL。
日志和截图在提交问题前应检查并脱敏。
不要把包含私人参数的模块直接发布到 NEXUS。
使用 HTTPS 连接公网服务器和 WebDAV。
不要在应用运行时手动编辑或覆盖配置。

清理和卸载

仅卸载程序不一定删除 LocalState、LocalCache 或 %LOCALAPPDATA% 中的数据。需要彻底清理时，应先备份所需配置，再通过 Windows 应用设置或对应数据目录处理。

不要把缓存目录当作唯一备份。元数据、图片和播放缓存都可能被应用清理和重新生成。

常见问题

免费版为什么不能添加第二个 Emby、Jellyfin 或飞牛影视服务器？

免费版媒体服务器上限为 1 个。升级 Pro 后可以添加多个，并启用跨服务器聚合。文件型来源不等同于媒体服务器上限。

首页和模块需要 Pro 吗？

不需要。1.3.0 中首页、多首页、栏目和模块对免费版开放。跨服务器聚合、在线字幕、Anime4K、WebDAV 配置备份和本地媒体刮削等能力仍需要 Pro。

文件已经扫描，为什么没有海报和详情？

免费版可以浏览文件，但本地、WebDAV 和 OpenList 的 TMDB 刮削与手动匹配属于 Pro。Pro 用户还应检查 TMDB 或元数据服务是否可用、文件命名是否清晰，以及来源是否仍在扫描。

登录媒体服务器失败

依次检查：

来源类型是否选择正确；
主机、端口和路径是否正确；
用户名和密码是否有效；
浏览器是否能从当前电脑访问服务器；
系统代理或手动代理是否允许该地址；
反向代理是否保留服务端需要的 API 路径；
自签名证书是否需要修复或临时调整证书策略。

先让“登录检测”成功，再保存来源。

图片、海报或背景加载失败

检查服务器图片地址和 TMDB 是否可访问；
检查软件代理和 TMDB 独立代理；
确认签名图片地址没有过期；
在“储存与缓存”中清理图片缓存后重试；
如果只有某个来源失败，检查该来源权限而不是清空全部配置。

首页没有内容

确认“启用首页”已打开；
检查当前首页栏目是否启用；
检查栏目绑定的服务器、目录、片单或模块是否仍存在；
导入首页后完成“绑定来源”；
检查 TMDB、Trakt、Bangumi 或模块状态；
确认当前网络代理允许访问对应服务。

搜索只显示当前服务器

当前来源搜索默认不会查询其他服务器。要跨服务器搜索，需要 Pro，并在“设置 > 服务器管理”中打开聚合搜索，允许目标服务器参与搜索。

模块还需要单独打开“参与聚合搜索”。

播放失败或一直加载

按顺序排查：

在详情页或播放器资源菜单选择其他资源；
切换同一服务器的其他线路；
确认账号仍有播放权限；
检查媒体流是否需要代理；
恢复自动硬解、自动 GPU 和默认视频输出；
暂时关闭自定义 mpv.conf；
外置 mpv 用户重新选择有效的 mpv.exe；
打开播放器诊断并导出脱敏日志。

401 / 403 通常是认证或权限问题；404 / 410 通常是资源或线路失效；5xx、超时和连接错误通常来自服务器或网络。

为什么不能拖动进度？

当前资源可能不支持 Range 或 seek。直播、部分 HLS、服务端转码、签名链接和远端代理资源不一定允许任意跳转。切换资源后若恢复正常，说明限制来自原资源路线。

HDR 画面发灰、过曝或黑屏

将 HDR 输出恢复为“跟随 Windows”。
将色调映射和峰值计算恢复为自动。
将 GPU 和硬件解码恢复为自动。
在 gpu-next 与 gpu 间测试。
检查 Windows HDR 开关、显示器模式和显卡驱动。
暂时关闭 Anime4K 和自定义 mpv.conf。

在线字幕入口显示 Pro

在线字幕搜索属于 Pro。免费版仍可使用服务器外挂字幕、媒体内封字幕和本地导入字幕。

弹幕没有显示

确认全局弹幕和当前播放器弹幕均已开启；
检查至少一个 API 已启用且地址有效；
检查标题、季度和集数匹配；
查看是否屏蔽了全部弹幕类型；
检查显示区域、同屏数量和时间偏移；
尝试载入本地弹幕文件。

下一集预加载没有启动

确认：

使用 Beta 内核；
下一集预加载总开关已开启；
当前服务器允许预加载；
没有开启当前这一集完整缓存；
当前集已进入尾段；
下一集属于相同来源；
资源不是直播、无限 HLS 或不受支持的转码形态。

没有预加载不会阻止正常切集，播放器会走正式播放流程。

账户登录成功但没有自动上传配置

这是预期行为。首次登录只读取云端最新配置；云端没有备份时保留本机配置，不会自动上传默认值。需要在个人中心显式点击“上传同步”。

账户同步提示版本冲突

另一台设备已经更新云端版本。刷新账户状态，确认本机和云端哪一份应保留，再重新执行上传或恢复。系统不会自动覆盖较新的版本。

WebDAV 配置备份为什么没有加密密码？

新版只使用 WebDAV 登录凭据，不再维护独立备份密码。备份文件依赖 WebDAV 权限和 HTTPS 保护，并可能包含媒体服务器凭据，应放在可信的私人 WebDAV 空间。

NEXUS 同步会保留本地修改吗？

不会。同步最新版本会原位覆盖该载入项，不检查或合并本地修改，也不会创建副本。需要保留修改时，应先导出本地文件或复制为新的本机对象。

Portable 配置为什么不在程序目录？

正式 Portable 版本把持久数据放在 %LOCALAPPDATA%\WWPlayer-Portable。这样更新或替换程序目录时不会覆盖配置。迁移电脑时需要另外迁移配置。

清理缓存会删除播放记录或服务器吗？

不会。元数据、图片和播放缓存是可再生成数据。服务器、账户会话、首页、片单和播放记录由各自的持久存储管理。

WWPlayer 是媒体服务器吗？

不是。WWPlayer 是客户端。Emby、Jellyfin、飞牛影视、WebDAV、OpenList、OneDrive、SMB 和本地文件系统仍然拥有媒体、账号、权限和文件。

如果界面文字、授权状态或发布渠道与本文档不同，以当前安装版本中的实际界面和 Microsoft Store 信息为准。