WWPLAYER Wiki — 功能文档

产品定位

WWPlayer 是一个 Windows 桌面媒体客户端，主要用于连接 Emby 服务端，浏览电影、剧集和媒体库，并使用桌面播放器播放远程媒体。

它可以把 Emby、TMDB、Trakt、本地视频文件、电视直播列表和自定义发现模块集中到一个界面中，但它本身不是 Emby 服务端：

不负责创建或管理 Emby 用户
不负责建立 Emby 媒体库
不替代服务端转码、刮削和权限管理
不会把本地媒体自动上传到 Emby
不会把 WebDAV 配置备份当作视频文件同步

支持能力总览

1. 内容来源

来源	支持内容	使用条件
Emby	电影、剧集、季度、单集、合集、媒体库分类、最近更新、继续观看	需要可用的 Emby 地址和账号
多个 Emby 服务端	服务端切换、线路切换、跨服务端搜索、收藏和继续观看聚合	多服务端聚合需要 Pro
TMDB	热门、趋势、高分内容、趋势图片和发现首页栏目	需要填写 TMDB API Key
Trakt	追剧日历、热门/趋势/期待、收藏、推荐、继续观看和播放记录	需要完成 Trakt 登录
本地文件夹	本地视频索引、海报/背景、播放和本地进度	需要选择 Windows 文件夹
M3U/M3U8	电视直播频道、频道分组和频道地址	需要本地列表文件或列表 URL

2. 核心能力

📚

媒体管理

浏览首页轮播、继续观看、最近更新、趋势和媒体库。跨服务端搜索并按来源分组。

▶️

播放能力

内置 libmpv 或外置 mpv 播放器。支持直连、HLS 等多种资源格式，自动恢复播放位置。

🎬

播放控制

进度拖动、速度调整、选集切换、下一集预加载。支持全屏、置顶和快捷键自定义。

💬

字幕与弹幕

切换音轨和字幕轨，导入本地字幕。配置弹幕 API，调整透明度、字号和显示区域。

🎨

画面优化

硬件解码、HDR 输出、色调映射。音频优化包括立体声下混、人声增强和夜间模式。

🔍

发现首页

聚合 TMDB、Trakt、追剧日历、收藏片单和自定义模块。可配置栏目顺序和轮播来源。

安装与首次使用

安装方式

WWPLAYER 现已上架 Microsoft Store，可直接在商店中搜索下载安装。

💡 提示

通过 Microsoft Store 安装可以享受自动更新和系统级沙箱保护。

添加 Emby 服务端

点击左侧服务端图标，进入"服务器管理"
添加服务端名称和线路地址，例如 https://emby.example.com
输入 Emby 用户名和密码，执行登录检测
检测通过后保存，并选择当前服务端和线路
返回首页，等待媒体库和继续观看内容加载

💡 提示

同一服务端可以配置多条线路，用于主线路、备用线路或不同网络入口。线路切换只影响后续请求和播放路线，不会改变服务端媒体库。

配置代理

进入"设置 > 网络"选择：

不使用代理
跟随系统代理
手动代理（需要填写代理地址，例如 http://127.0.0.1:7890）

媒体来源与内容管理

Emby 媒体库

登录后可以浏览 Emby 首页、媒体库、分类、最近更新和继续观看。打开电影或剧集详情后，可以查看：

标题、年份、评分、简介、海报和背景
演员、导演及人物详情
季度、剧集和集数分页
相似内容
视频、音频、字幕、分辨率、码率、封装和协议等资源信息
当前媒体在其他已配置服务端的候选资源（Pro）

收藏、片单和观看状态

收藏和片单用于整理想看或经常观看的内容。观看状态可以按媒体或剧集操作：

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

多服务端与聚合

Pro 版可以添加多个 Emby 服务端，并分别控制服务端是否参与聚合。聚合包括：

跨服务端搜索
跨服务端收藏
跨服务端继续观看
多服务端播放进度合并
同一媒体的多来源资源选择
继续观看来源选择和来源分组

本地媒体库

选择本地文件夹后，WWPlayer 会建立本地索引。识别的视频扩展名包括：

MKV、MP4、M4V、AVI、MOV、WEBM、TS、M2TS、WMV、FLV

📝 本地媒体识别规则

优先读取视频旁边的同名 .nfo 或 .json 侧车文件，提供标题、年份、简介、海报等信息。没有侧车文件时，根据文件名生成标题。

播放器能力

内置播放器与外置 mpv

播放方式	适用场景	注意事项
内置 libmpv	直接使用应用内播放器，开箱即用	需要本机图形驱动和解码能力正常
外置 mpv	使用已有 mpv 安装、配置或脚本	需要手动选择有效的 mpv.exe

默认快捷键

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

快捷键可以在"设置 > 快捷键"中修改。

字幕和弹幕

播放器会显示服务端返回的字幕轨、音轨和语言信息。用户可以：

选择默认字幕和默认音频语言
播放时临时切换字幕或音轨
导入本地 SRT、ASS、SSA、SUB、VTT、SUP 字幕
调整字幕大小、位置和延迟
设置字幕字体、颜色、描边、阴影、背景样式和透明度

在"设置 > 字幕&弹幕"中最多添加 5 个弹幕 API，播放时可以重新匹配来源，调整透明度、字号、速度和显示区域。

硬件解码、HDR 和音频优化

推荐先使用自动设置，再根据本机情况调整：

视频输出：gpu-next 适合新版本 mpv，gpu 用于兼容场景
硬件解码：自动安全、D3D11VA、D3D11VA-copy 或软件解码
HDR 输出：跟随 Windows、强制 SDR、强制 HDR
音频优化：立体声下混、人声增强和夜间模式

⚠️ 黑屏或画面异常

遇到黑屏、花屏或 HDR 颜色异常时，建议按顺序恢复视频输出、GPU 适配器、硬件解码和 HDR 为自动，然后一次只改一个选项。

发现首页

发现首页是与当前 Emby 媒体库分开的内容入口。启用后，可以点击窗口左上角的 WWPlayer Logo 进入。发现首页和模块管理属于 Pro 能力。

可用内容来源

TMDB 热门电影、趋势电影、高分电影和热门剧集
Trakt 综合热门、趋势、最受期待、收藏和推荐
追剧日历
Emby 最近更新、媒体库和指定服务端
收藏、待看片单和自定义片单
本地媒体文件夹
IMDb 数据集分类
M3U/M3U8 电视直播
已安装的发现模块

可配置项目

用户可以调整栏目是否启用、栏目顺序、轮播来源、继续播放信息来源、是否关闭分页、是否作为默认启动首页、首页入口 Logo 等。

外部服务

TMDB

在"设置 > 外部连接"填写 TMDB API Key，并使用连通性检查确认配置。TMDB 可用于：

发现首页热门、趋势和高分内容
趋势内容的海报、背景或其他艺术图
首页轮播和部分详情视觉内容

Trakt

在"设置 > 外部连接"点击登录 Trakt，按浏览器页面完成授权。连接后可使用：

追剧日历
Trakt 继续观看记录
热门、趋势、期待、收藏和推荐栏目
播放记录同步

WebDAV 配置备份

Pro 用户可以使用 WebDAV 备份和恢复 WWPlayer 配置。备份内容使用单独的加密口令保护，上传的是配置数据，不是视频文件。

🔒 安全提示

不要在不可信设备上保存 WebDAV 密码和加密口令。

免费版与 Pro

免费版

添加并使用 1 个 Emby 服务端
浏览媒体库、搜索、详情、收藏和继续观看
使用内置播放器或外置 mpv
使用下一集预加载（资源满足条件时）
使用字幕、弹幕、音轨和播放速度控制
连接 Trakt 并同步播放记录
导入和导出服务端配置

Pro 版新增能力

添加多个 Emby 服务端
跨服务端搜索、收藏和继续观看聚合
跨服务端资源切换
多服务端播放进度合并
继续观看来源选择和跨来源整合
发现首页
发现模块安装和管理
自定义发现首页入口 Logo
WebDAV 多设备配置同步

设置说明

⚙️

通用

浅色模式、降低视觉效果、首页自动待机、趋势来源、背景图、日志导出等。

🏠

首页

发现首页开关、栏目、布局、轮播来源、继续观看来源、分页、启动行为等。

🌐

网络

配置系统代理、手动代理、媒体流是否跟随代理，并执行代理检测。

🎬

播放器

播放内核、外置 mpv 路径、缓冲、默认字幕/音频、硬件解码、HDR 等。

💬

字幕&弹幕

字幕样式、字体、颜色、描边、背景、弹幕 API、弹幕字体和颜色。

⌨️

快捷键

修改播放/暂停、进度、音量、静音、全屏、下一集、字幕、音轨和速度等按键。

🗄️

服务器管理

配置服务端参与聚合的范围，以及各服务端是否允许下一集预加载。

🗑️

缓存

查看并清理元数据缓存、图片缓存，设置图片缓存过期天数。

🔗

外部连接

配置 TMDB、Trakt 和 WebDAV。

ℹ️

关于

查看版本、打开社区入口和创建桌面快捷方式。

数据保存与隐私

WWPlayer 只会根据用户启用的功能访问对应服务：Emby、TMDB、Trakt、WebDAV、弹幕 API、M3U 列表或本地媒体目录。

本地可能保存的数据

服务端地址、用户名、访问令牌、线路和登录状态
收藏、片单、搜索历史和播放偏好
本地媒体目录、索引、缩略图和本地播放记录
元数据、图片和播放器缓存
应用日志和可选的播放器日志

稳定配置文件默认位于：%LOCALAPPDATA%\WWPlayer\wwplayer-config.json

⚠️ 隐私提醒

不要在公开 issue、截图或日志中暴露密码、访问令牌、Cookie 和完整签名 URL。

常见问题与排障

登录失败

检查线路地址、端口、用户名、密码和代理。先在服务器管理页执行登录检测，检测通过后再保存。若浏览器可以打开而应用无法登录，重点检查代理模式、反向代理路径和服务端是否限制客户端请求。

图片或海报加载失败

检查图片请求是否需要代理、服务端图片地址是否可访问，以及代理规则是否拦截图片请求。仍然失败时，在"设置 > 缓存"清理图片缓存后重新加载。

播放失败或一直加载

按以下顺序排查：

在资源菜单中选择其他资源
切换当前服务端线路
检查账号是否仍有播放权限
检查代理是否允许媒体流访问
内置播放器恢复自动硬件解码和默认视频输出
使用外置 mpv 时重新确认 mpv.exe 路径
打开播放器日志，导出脱敏后的日志信息

无法拖动进度

检查当前资源是否支持 Range 和 seek。直播、部分 HLS、远程签名资源或服务端转码资源可能不支持任意位置跳转，这属于资源能力限制。

HDR、黑屏或画面异常

把视频输出、GPU 适配器、硬件解码和 HDR 输出恢复为自动，再逐项调整。也可以切换 gpu-next 与 gpu，或暂时使用软件解码。

发现首页没有内容

确认当前账号是 Pro、发现首页已启用，并检查 TMDB API Key、Trakt 登录状态、栏目开关、模块、M3U 列表和本地文件夹。

本地媒体没有显示

确认选择了正确的文件夹，并检查文件扩展名、权限和目录层级。想要获得准确标题、海报和简介时，在视频旁放置同名 .nfo 或 .json 侧车文件。

继续观看进度不一致

在发现首页设置中确认当前来源是"Trakt 记录"还是"本地记录"，再检查 Emby 账号、媒体匹配信息和最近一次播放上报。

如何恢复配置

优先使用 WebDAV 备份或本地 .bak 备份恢复。手动替换配置前退出 WWPlayer，并先复制当前配置作为回滚副本；不要在应用运行时直接覆盖配置文件。

WWPlayer 支持 Jellyfin 吗？

当前产品文档和界面以 Emby 服务端为支持基线。Jellyfin 的兼容性不在本版本的公开支持承诺内，具体能否使用取决于服务端接口和返回结果。

WWPlayer 是不是 Emby 服务端？

不是。WWPlayer 是连接 Emby 的桌面客户端，服务端仍然负责用户、媒体库、权限、转码和文件管理。