Windows 桌面 Emby 客户端:桌面软件风格的浏览界面,播放交给 mpv。
- 多服务器:地址、端口分开填,随时切换;可编辑(换地址、端口不用重新登录)或重新登录;支持反向代理挂在子路径下的服务器
- 浏览:首页轮播、继续观看(可移除、可撤销)、各媒体库最新,「我的媒体」「继续观看」可展开成整页网格;媒体库分页、搜索、收藏;剧集详情(季、集、演职人员、类似作品、媒体信息)、整季单集页、演职人员作品页
- 播放:mpv + ModernZ 界面(顶栏居中标题 + 网速,鼠标一动就出控制栏);进度条悬停预览画面;直接播原始文件,同一部片有多个版本(1080p / 4K 等)时在详情页选;续播、整季连播、按进度预加载下一集、选集菜单(F8)、换集沿用音轨与字幕、外挂字幕
- 弹幕:填一个
/api/v2格式的弹幕接口地址(设置 → 弹幕,地址里可带令牌)即可。按剧名和集号自动匹配,匹配不上可在播放器里手动搜索选集,同一季之后的集自动沿用。滚动按屏幕刷新率逐帧绘制,24 帧的片子在高刷屏上也顺滑。D 键或控制栏「弹」开关,右键「弹」或 Shift+D 打开设置面板:屏蔽类型(滚动 / 顶部 / 底部 / 彩色)、不透明度、显示区域、字号、速度、描边、合并重复、时间偏移。屏蔽词在设置页填。弹幕按集缓存,接口暂时不通时用上次的缓存 - 本地缓存:边播边把播放位置前方一段存到本地,已下载的部分拖动、预览、重看都不等网络;上游卡住 3 秒自动另开连接;断网几分钟后恢复也能接着播;只保留最近播放的那一集(最多 20 GB)。设置里可以改成缓存整个视频(多用流量),「缓存管理」里查看占用、清理
- 出错处理统一:服务器、图片、字幕、弹幕的请求遇到 502 / 503 / 429 / 520–524、连不上时自动重试 2 次(等 0.5 秒、1.5 秒,服务器给了
Retry-After就按它,最多 5 秒;提交类请求只在连不上和 429 时重试,不重复提交);视频遇到 5xx 一直重试到恢复;401 / 403 / 404 等直接给出中文原因,不把错误页原文显示出来 - 进度用 Emby 标准的 Sessions 接口回传,其他客户端同步可见;token 只在 EmbyMini 进程里,mpv 和进度条预览进程都拿不到
在 Releases 下载最新的 EmbyMini_<版本>_x64-setup.exe 运行即可,覆盖安装会保留服务器配置。
0.2.0 起可以在「设置 → 关于」检查更新、一键安装(可单独给检查更新设代理,留空跟随系统代理)。
安装包没有签名,Windows 可能提示「已保护你的电脑」,点「更多信息」→「仍要运行」。可用同一 Release 里的 SHA256SUMS.txt 校验文件。
src-tauri/ Rust 后端(Tauri 2)
src/main.rs 命令注册、应用状态、退出时收尾
src/updater.rs 检查更新、下载安装
src/config.rs 本地配置:服务器列表、播放设置、地址规范化
src/emby.rs Emby HTTP:鉴权头、UA、通用请求、播放用的强类型
src/status.rs 对外 HTTP 的统一处理:状态码分类、重试、给人看的错误说明
src/images.rs 海报、背景图的本地磁盘缓存(emby-img 协议)
src/stream.rs 本地缓存代理:mpv 从 127.0.0.1 读视频和字幕,边播边分块落盘,卡住时对冲重连
src/player.rs mpv 外部进程 + JSON IPC:队列、预加载、选轨、进度回传、弹幕的取数与消息
src/danmaku.rs 弹幕接口:匹配、搜索、拉取、按集缓存
mpv/ 自带 mpv 配置:mpv.conf、input.conf、ModernZ、thumbfast(进度条预览)、选集菜单与暂停时不藏光标的脚本、
弹幕(scripts/danmaku.lua:排版、逐帧绘制、设置面板、手动匹配)(安装包里另附 mpv.exe)
testdata/ 单测用的回包样本(只保留测试用到的字段)
ui/ 前端(Svelte 5 + Vite);ui/dev/bridge.ts 是浏览器里开发界面用的转发桥
tools/mpv-shot.lua 不连服务器检查自带 mpv 配置的渲染效果(CI 用它截图)
| 做什么 | 命令 |
|---|---|
| 后端单测 | cargo test --manifest-path src-tauri/Cargo.toml |
| 前端类型检查 | npm --prefix ui run check(看退出码:svelte-check 与 tsc 两段) |
| 前端单测 | npm --prefix ui test |
| 没人用的导出、文件、依赖 | npm --prefix ui run knip |
| 浏览器里开发界面 | 导出 EMBY_SERVER / PORT / EMBY_USER / EMBY_PASS 后 cd ui && npx vite,打开 http://127.0.0.1:5173 |
| 桌面版开发(Windows) | ui\node_modules\.bin\tauri dev |
| 真服端到端(需要上面四个环境变量和 PATH 里的 mpv) | cargo test --manifest-path src-tauri/Cargo.toml e2e_real_server -- --ignored --nocapture |
| 本地缓存验收(同上;整片缓存模式,会下载几百 MB) | cargo test --manifest-path src-tauri/Cargo.toml e2e_cache_proxy -- --ignored --nocapture |
弹幕端到端(同上,另需 DANMU_API = 弹幕接口地址、DISPLAY;EMBY_TEST_ITEM 指定一集能匹配上的剧) |
cargo test --manifest-path src-tauri/Cargo.toml e2e_danmaku -- --ignored --nocapture |
| 测试包 | 手动触发 windows workflow;安装包在该次运行的 Artifacts 里(EmbyMini-setup) |
| 发版 | 把 src-tauri/tauri.conf.json 与 src-tauri/Cargo.toml 的 version 改成新版本并推送,再 git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z;构建、冒烟测试通过后自动发 Release(安装包、自动更新用的签名与 latest.json、SHA256SUMS.txt),版本号带 - 的标为预发布。打包需要仓库 Secrets 里的更新签名私钥 TAURI_SIGNING_PRIVATE_KEY / TAURI_SIGNING_PRIVATE_KEY_PASSWORD |
端到端测试会真实播放并回传进度,结束时把观看记录恢复成测试前的样子。
所有数据都在安装目录下的 data\,系统盘不留东西(默认安装目录是 %LOCALAPPDATA%\EmbyMini,安装时可以改到别的盘):
| 位置(相对安装目录) | 内容 |
|---|---|
data\config.json |
服务器列表(含登录 token,不存密码)、播放设置、弹幕设置(含接口地址)与手动匹配记录 |
data\mpv.conf |
个人 mpv 配置:自己新建,在自带配置之后加载,同名选项以它为准,升级不覆盖 |
data\logs\ |
日志(单个文件 2 MB 轮换,留最近 3 份;本地时间) |
data\webview\ |
界面数据(含上次浏览的列表快照,启动时先显示) |
data\cache\images\ |
海报、背景图缓存(上限 1 GB,按最近使用淘汰) |
data\cache\video\ |
视频缓存:只留最近播放的那一集和已就绪的下一集,换片时自动删;最多 20 GB,且给磁盘留至少 10 GB |
data\cache\subs\ |
外挂字幕缓存(上限 200 MB,按最近使用淘汰) |
data\cache\danmaku\ |
弹幕缓存:每集一个文件,24 小时内重看直接用,一周没更新的自动删 |
data\mpv-cache\ |
mpv 着色器缓存 |
安装目录不可写时(例如手动拷到只读位置)退回 %LOCALAPPDATA%\com.stqfdyr.embymini。旧版本放在 %APPDATA% / %LOCALAPPDATA% 下的配置,新版首次启动时自动搬过来并删掉旧目录。
「设置 → 播放 → 缓存管理」可以查看并清理视频、图片、字幕和弹幕、媒体库(列表快照)和临时缓存(mpv 着色器缓存、自动更新留在系统临时目录的安装包、进度条预览留下的图片)。
卸载走「设置 → 应用 → 已安装的应用」。勾选「删除应用程序数据」时 data\ 一并删除;自动更新不动它。
- mpv(GPL):安装包附带 shinchiro 构建
- ModernZ v0.3.3(LGPL-2.1,见
src-tauri/mpv/MODERNZ-LICENSE)。modernz.lua有少量改动(顶栏标题居中、加网速;下一集已就绪时下一集按钮变绿带闪电;加弹幕按钮),改动处标EmbyMini:;modernz-locale.json只保留英文和简体中文 - thumbfast(MPL-2.0,见
src-tauri/mpv/THUMBFAST-LICENSE):进度条悬停预览。少量改动(缩略图进程带上主播放器的请求头、UA、标明是预览的请求头和读超时;网络流只取关键帧、同时只有一个取图请求),标EmbyMini: