基于 Rust + Tauri 2.0 + Svelte 5 + Vite 的桌面视频播放器 拖入目录即看 · 黑色影院舞台 · 字母顺序递归连看 · 多音轨 / 内嵌 + 外挂字幕 · 画面旋转缩放 · 全键盘操作 · 每文件断点续看
v1.0.8:单文件直开(拖拽或选择一个视频文件:直接定位播放该文件、立即开播,文件列表浮层本次会话默认收起——列表仍按其所在目录构建,连播 / 上一个下一个 / T 键打开列表一切照常)
v1.0.7:MKV 字幕索引会话引擎(Cues 跳跃 + 按播放窗口取块:首窗亚秒挂载、边播边补窗、seek 即查即得;删除 ffmpeg 引擎——实测被索引跳跃全面超越且免外部依赖;无索引文件自动降级原生全量走读 → JS 兜底)
v1.0.6:ffmpeg 探测跨平台兼容(Windows 显式找 PATH / 应用同目录下的 ffmpeg.exe,逐候选 -version 验证,坏应用别名自动跳过;便携部署可用)
v1.0.5:MKV 内嵌字幕三级引擎(PATH 有 ffmpeg 秒级提取 → Rust 原生 EBML 流式 → JS 兜底),大文件提取从分钟级降到秒级
v1.0.4:MKV 内嵌字幕流式提取(read_range 分块喂入,内存恒定、无文件大小限制,带进度与取消)
v1.0.3:音轨切换修复(异编码整 MediaSource 重建)· MKV/WebM 轨道分析与内嵌 SRT/ASS 字幕提取 · 外挂 .ass/.ssa · 不支持编码菜单置灰
「极速看片」是一款专注「快速观看本地视频」的桌面应用,布局与交互同极速听书一脉相承:把一个文件夹拖进窗口(或点引导页大号「+」按钮选目录),程序会按字母顺序递归遍历所有子目录,把每个目录里的视频文件按顺序连成一条完整观看序列;播放界面是一幅纯黑影院舞台:当前画面铺满主窗口,左上角显示白色文件名,右侧是独立的文件列表浮层,顶部信息栏 / 底部控制栏两行式覆盖。在此基础上补齐了视频特有的能力:多音轨切换、字幕、画面旋转与缩放。退出时自动记住观看位置——每一个文件的播放位置都单独记忆(播放完毕的自动清空),下次启动定位到退出的位置并暂停等待。
技术栈:
| 层 | 技术 |
|---|---|
| 后端 | Rust 1.77+,Tauri 2(tauri-plugin-dialog 系统目录选择;read_range 按区间吐字节供 moov / 轨道表分析;mkvsub.rs 内嵌字幕三级引擎:Cues 索引会话(窗口化跳跃)→ 原生 EBML 全量走读(带进度轮询)) |
| 前端 | Svelte 5(runes),Vite 6,原生 <video>(asset 协议直读本地文件),mp4box.js(轨道分析 + MSE 多音轨分段),hls.js(m3u8,按需动态加载),matroska-subtitles(MKV 字幕提取第三级兜底,浏览器 bundle 按需加载),ass-compiler(ASS/SSA 解析),WebVTT(字幕统一出口) |
| 通信 | Tauri IPC 命令 + asset 协议(本地媒体零拷贝直读) |
本仓库已在 Debian 13 + Node 24 环境验证:npm run build(前端,149 模块零警告);另以 mock Tauri API 的无头浏览器冒烟测试(Chromium)加载真实构建产物,用 ffmpeg 生成的真实多音轨 MP4(中/英/日 + 内嵌 mov_text 字幕)、双编码 MP4(AAC/Opus/AC-3)、多轨 MKV(AAC/MP3 + 内嵌 ASS/SRT 字幕)、WebM、本地 HLS 流与外挂 vtt/srt/ass 完整走会话恢复、HLS 播放、快进快退与自动连播、MKV 轨道分析与内嵌字幕提取(含 ASS 富文本、引擎快速路径命中与后端失败回退 JS 流式的完整降级链)、MSE 多音轨装载与切换(同编码无感 + 异编码重建)、不支持编码菜单置灰、内嵌 / 外挂字幕挂载、旋转缩放、放大拖拽、逐帧步进、各浮层开关、音量键盘 / 滚轮、状态存档字段、断点精确恢复(RAP + 缓冲就绪精调)与 X 键清记忆,85/85 断言通过(两遍回归),全程零运行时错误(v1.0.6 基线;v1.0.7 会话引擎在前端表现为新增命令缺失时自动走原降级链,mock 环境天然回归该路径)。
v1.0.7 重构(删除 ffmpeg 引擎、新增 Cues 索引会话)在 Windows 10 + Rust 1.98 环境验证:npm run build 前端 149 模块零警告;cargo test --release 后端 19/19 单测通过(含合成 Cues 索引的「窗口并集 == 全量走读逐块一致」、窗口边界互斥、无索引降级、定性错误文案对齐、会话失效与逐出、稀疏 4GB 巨块 seek);cargo build --release 完整应用编译通过;并以 9.9GB 蓝光重封装 MKV(5400rpm 机械硬盘)真机实测:会话打开 0.64s、首窗(21 块)0.73s、全片 90s×80 窗扫 33.7s(973 条索引 0 未命中,产出与全量走读逐字节一致),对照旧引擎全量走读 ~183s。
- 拖拽即开:把文件夹拖到窗口任意位置即可开始观看;拖拽单个视频文件则直接定位播放该文件(v1.0.8,列表浮层本次会话默认收起,T 键随时打开)
- 点选即开:引导页大号「+」按钮弹出系统目录选择对话框,与拖拽完全等效(无需鼠标拖拽也能用);「打开单个视频文件」次级入口直接播放选中的文件
- 一键关目录:
X键关闭当前目录回到引导页,同时清除该目录的位置记忆(下次启动不再自动恢复) - 递归有序连看:按字母顺序递归遍历所有子目录(自然排序:
ep2.mp4排在ep10.mp4之前),列表顺序连播,播完最后一个文件即停 - 多音轨(mp4box.js + MSE):MP4 里的全部音轨(语言标签 + 声道数)进弹出式菜单;默认选中界面语言(中文),且只在 MSE 支持的编码里挑;同编码切换无感(视频画面不中断);异编码切换(AAC ⇄ Opus 等)自动重建 MediaSource 后原位恢复;WebView 不支持的编码(如 AC-3)在菜单里置灰并标注原因;单音轨文件自动禁用菜单;MSE 完全不可用时回退原生播放并在菜单里说明。MKV / WebM 的音轨同样列出(含编码标签),但原生播放无法切换(Chromium 限制,选择时提示)
- 字幕(统一 WebVTT):弹出式菜单含「不启用」(默认:匹配界面语言的轨,没有匹配则不启用);支持 MP4 内嵌字幕(wvtt / tx3g 抽样提取转 VTT)、MKV 内嵌字幕(SRT / ASS,三级引擎:① Cues 索引会话——解析容器自带索引后按播放窗口直跳取块,首屏字幕亚秒级可用、播放中每 ~90 秒补一窗、seek 即查即得,不再顺序扫全文件;② 无索引文件(罕见封装)降级后端 Rust 原生 EBML 全量走读(内存恒定、任意大 MKV 可用,状态栏显示百分比);③ 两者都失败时前端 JS 流式兜底;可随时切走取消;ASS 经 ass-compiler 解析为斜体 / 粗体富文本)、外挂同名
.vtt直挂、外挂.srt自动转 VTT、外挂.ass/.ssa富文本解析(电影.zh.srt之类的语言后缀会进菜单标签);图形字幕(PGS / VOBSub)在菜单中置灰说明;没有字幕流时按钮禁用;HLS 字幕轨由 hls.js 自带渲染 - HLS:本地
.m3u8+ 分片目录直接可看(hls.js;asset 协议路径整体编码导致的相对分片失效已在前端重写解决) - 画面旋转(
R/ 控制栏按钮):每次顺时针 90°,任意角度下拖拽方向都跟手 - 画面缩放(
+-/ 滚轮无关,滚轮是音量):1×~5× 步进 0.25,放大后拖拽平移(屏幕位移经逆旋变换换算,画面边缘不脱离舞台),右下角 HUD 显示当前倍率与角度 - 逐帧步进(
,.含中文标点):按已知帧率(轨道分析 / rVFC 实测)走一帧,MSE 文件在已缓冲区精确落点 - 右侧文件列表浮层(
T切换,默认显示):独立于主窗口的屏幕右侧浮层(黑色背景亮灰文字,紧凑小字号),每个目录的视频文件顺序显示(目录分组标注),点击浮层底部页码翻页;列表始终锚定在当前播放的文件 - 顶部信息栏(
I切换):相对目录 / 文件名 · 音轨 / 字幕选择 · 缩放旋转状态(非默认时) · 播放进度(百分比 +00:00:00)· 第几个 / 共几个 - 底部控制栏(
C切换,两行式):最左侧大号播放 / 暂停按钮;右侧上半行靠右依次是上一文件 / 下一文件、快退 / 快进 30 秒、音轨选择(弹出菜单)、字幕选择(弹出菜单)、旋转、全屏、音量图标(可点击静音 / 解除)与音量 slider;下半行是占满可用宽度的播放位置 slider(已播部分绿色填充),播放位置 / 总时长文字位于同行最右侧 - 细粒度断点记忆:每个文件的播放位置独立记忆(播放完毕自动清空);切换文件再切回来,从上次的位置继续
- 退出即存档:退出时记住当前文件与位置,下次启动定位到该位置并暂停等待(断点续看;MSE 文件经「关键帧粗定位 + 缓冲就绪后精确落点」两段落位,恢复到退出帧)
- 常见格式全覆盖:mp4 / m4v / mov / webm / ogv / mkv / avi / 3gp 播放,m3u8 走 HLS;能否播放取决于系统 WebView 解码器
| 类别 | 扩展名 | 播放 | 音轨 / 字幕分析 |
|---|---|---|---|
| MP4 家族 | mp4 m4v mov |
多音轨走 MSE(mp4box.js) | mp4box.js(多音轨 / 内嵌字幕 / 帧率) |
| Matroska 家族 | mkv webm |
WebView 原生 | 手写 EBML 分析器(音轨 / 字幕轨 / 帧率)+ 后端三级引擎字幕提取(索引会话 / 原生 EBML / JS 兜底) |
| 开放格式 | ogv ogg |
WebView 原生 | —(单音轨直读) |
| 尽力播放 | avi 3gp |
取决于系统 WebView 解码器 | — |
| HLS | m3u8 |
hls.js(分片走 asset 协议) | hls.js 音轨 / 字幕轨 |
说明:播放走 WebView 的
<video>元素(Windows WebView2 / macOS WKWebView / Linux WebKitGTK 对上表主流格式均有良好支持);多音轨 / 内嵌字幕信息由前端按需分析获得——MP4 只读 moov 元数据区(moov 在文件头顺序读到、在文件尾特征扫描定位),MKV / WebM 只读第一个 Cluster 之前的头部轨道表(512KB 起步扩窗至 16MB),媒体数据永不过 IPC。扩展名判断忽略大小写(.MP4与.mp4等价)。
| 按键 | 功能 |
|---|---|
→ 右方向键 |
快进 30 秒 |
← 左方向键 |
快退 30 秒 |
↑ 上方向键 |
音量 +5% |
↓ 下方向键 |
音量 -5% |
空格 |
播放 / 暂停 |
回车 Enter |
播放 / 暂停 |
PageDown |
下一个文件 |
PageUp |
上一个文件 |
Home |
本文件开头 |
End |
本文件结尾 |
Esc |
全屏时退出全屏;非全屏时退出程序(帮助层开着时先关帮助层) |
+ 或 = |
画面放大(步进 0.25×,上限 5×) |
- 或 _ |
画面缩小(下限 1×) |
,(含中文逗号 ,) |
退后一帧 |
.(含中文句号 。) |
前进一帧 |
R |
顺时针旋转画面 90° |
X |
关闭当前文件 / 目录,回到引导页(同时清除位置记忆) |
I |
显示 / 隐藏顶部信息栏(默认显示) |
C |
显示 / 隐藏底部控制栏(默认显示) |
T |
显示 / 隐藏右侧文件列表浮层(默认显示;隐藏后画面自动变宽) |
F1 |
显示快捷键帮助 |
| 操作 | 功能 |
|---|---|
| 引导页大号「+」按钮 | 点击弹出系统目录选择对话框(与拖拽等效) |
| 点击文件列表某一行 | 播放该文件 |
| 点击画面 | 播放 / 暂停 |
| 双击画面 | 全屏 / 恢复;全屏 = 纯画面模式,顶栏 / 底栏 / 文件列表浮层一律立即自动隐藏 |
| 全屏中的键盘 / 滚轮 | 照常可用(快捷键 / 音量不受浮层隐藏影响);退出全屏后浮层按 I / C / T 偏好恢复 |
| 播放期间 | 自动阻止系统屏保与休眠(暂停 / 退出播放后恢复) |
| 放大后拖拽画面 | 移动可见的视频画面 |
| 点击音量图标 | 静音(图标变为静音样式),再次点击解除;拖动音量滑杆也会自动解除 |
| 滚轮向上 | 音量 +5% |
| 滚轮向下 | 音量 -5% |
| 拖入文件夹 | 打开 / 切换主目录 |
- 播放 / 暂停:空格、回车、鼠标单击画面、控制栏最左侧的大号按钮四种方式等效
- 快进 / 快退:左右方向键 ±30 秒(控制栏也有 −30s / +30s 按钮);Home / End 跳本文件开头 / 结尾;
,.(含中文标点)逐帧步进 - 音量与静音:上下方向键 / 滚轮,每次 ±5%;控制栏滑杆可连续调节;点击音量图标静音(临时状态,不持久化),再次点击或主动调音量自动解除;音量随状态文件持久化
- 上一 / 下一文件:
PageUp/PageDown(始终环形:最后一个的下一个回到第一个)与控制栏 ⏮ ⏭ 按钮;一个文件自动播完后顺序连播,列表末尾停止并提示「列表播放完毕」 - 音轨选择:弹出式菜单(控制栏「音轨」按钮),默认选中界面语言(中文,且只在 MSE 支持的编码里挑);多音轨 MP4 走 mp4box.js + MSE 双 SourceBuffer:同编码切换视频画面不中断,异编码切换(AAC ⇄ Opus 等)自动重建 MediaSource 原位恢复;WebView 不支持的编码(如 AC-3)置灰并标注;单音轨时按钮禁用;原生回退模式 / MKV 下菜单保留但切换受限(Chromium 系
<video>无音轨 API,选择时提示) - 字幕选择:弹出式菜单含「不启用」;内嵌(MP4 wvtt/tx3g、MKV SRT/ASS)/ 外挂(.vtt/.srt/.ass/.ssa)/ HLS 三类来源统一列出;默认匹配界面语言(中文),无匹配则不启用;图形字幕(PGS/VOBSub)置灰说明;无字幕流时按钮禁用
- 旋转与缩放:
R顺时针 90° 步进;+-缩放(1×~5×);放大后拖拽平移,缩放回 1× 时平移自动归零;两者随状态持久化 - 全屏(纯画面模式):双击画面 / 控制栏全屏按钮(原生窗口全屏);
Esc全屏时退出全屏、非全屏时退出程序。进入全屏后顶部信息栏、底部控制栏与右侧文件列表浮层立即全部隐藏(无论播放还是暂停),屏幕上只留视频画面,鼠标活动也不会浮现;退出全屏后三个浮层恢复为I/C/T键的偏好状态(三键在全屏中仍可切换偏好,退出后生效) - 防屏保 / 休眠:播放期间自动阻止系统屏保与休眠(Windows / macOS / Linux 全平台),暂停 / 播完 / 关闭目录即解除;优先用 WebView 原生 Wake Lock API,不可用时由 Rust 后备(SetThreadExecutionState / caffeinate / systemd-inhibit)兜底,进程退出后自动解除、无残留
剧集/
├── 01-先导片.mp4 ← ① 先列出本目录的视频文件(按文件名自然排序)
├── 第01季/
│ ├── 1.mp4 ← ② 再按目录名顺序进入第一个子目录,如此递归
│ └── 10.mp4 (自然排序:2 排在 10 前面)
├── 第02季/
│ └── 1.mp4 ← ③ 第二个子目录
└── 空目录/ ← 没有视频文件的目录不会出现在分组与导航序列里
准确规则:每个目录内,先显示本目录视频文件(自然排序),再依次进入按名称排序的各子目录递归;文件与目录均忽略大小写、数字按数值比较(ep2 < ep10)。目录符号链接不跟随(防目录环)。扫描同时收集各目录的外挂字幕(.vtt / .srt / .ass / .ssa),按「同名前缀 + 语言后缀」挂到对应视频上。
| 项 | 要求 |
|---|---|
| Rust | ≥ 1.77.2(安装:https://rustup.rs) |
| Node.js | ≥ 18(推荐 20+) |
| npm | ≥ 9 |
Linux 额外系统依赖(Debian/Ubuntu):
sudo apt-get install libwebkit2gtk-4.1-dev build-essential curl wget file \
libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-devWindows:需 WebView2(Win10/11 一般自带)+ MSVC Build Tools(通过 "Desktop development with C++")。
macOS:需 Xcode Command Line Tools(xcode-select --install)。
# 1. 安装依赖
npm install
# 2. 开发模式(热重载)
npm run tauri dev
# 3. 打包发布版(安装包 + 可执行文件)
npm run tauri build打包产物位置:src-tauri/target/release/bundle/(Windows 为 nsis/ 下的安装包与 msi/;macOS 为 dmg/;Linux 为 deb/ rpm/ appimage/)。
若只运行调试版可执行文件:cargo run --manifest-path src-tauri/Cargo.toml(调试构建需要 dev server,正式体验请用 npm run tauri dev 或 npm run tauri build)。
冒烟测试(无需 Rust / WebView,mock Tauri API 的无头浏览器回归):
npm run build
bash scripts/make_testmedia.sh # 生成多音轨 / 字幕 / HLS 测试媒体
npm i -g agent-browser && agent-browser install
node scripts/smoke/server.mjs & # mock 服务器(:4174)
bash scripts/smoke/drive.sh # 40 项断言 + 截图程序在播放过程中(防抖 1.2 秒)自动保存,并在窗口关闭时兜底保存一次。状态文件:
| 系统 | 路径 |
|---|---|
| Windows | %APPDATA%\jisu-kanpian\state.json |
| macOS | ~/Library/Application Support/jisu-kanpian/state.json |
| Linux | ~/.config/jisu-kanpian/state.json |
记住的内容:
| 内容 | 规则 |
|---|---|
| 当前文件与位置 | 退出时所在文件 + 播放位置(毫秒);下次启动定位到该位置并暂停,按空格继续(MSE 文件两段落位,恢复到退出帧) |
| 每个文件的断点 | 单独记忆每个文件的位置(毫秒);播放完毕自动清空;距开头不足 1 秒或距末尾不足 1 秒的进度不记忆(视为未看 / 已看完) |
| 播放偏好 | 音量、旋转角度、缩放倍率、音轨 / 字幕语言偏好、信息栏 / 控制栏 / 文件列表浮层可见性(静音为临时状态,不持久化) |
按 X 关闭目录:立即回到引导页,清除该目录(含子目录)全部文件的断点记忆与恢复指针,其他目录的断点保留;音量 / 旋转 / 缩放 / 语言等偏好不受影响。删除状态文件则全部清零。
jisu-kanpian/
├── index.html # Vite 入口 HTML(内联黑底防白闪)
├── package.json # 前端依赖与脚本(npm run tauri dev/build)
├── vite.config.js # Vite 配置(hls.js 动态分块)
├── svelte.config.js
├── prompt.txt # 需求原文 + 实现说明(与上游项目同款惯例)
├── scripts/
│ ├── make_icons.py # 图标源图生成(tauri icon 再生成全套)
│ ├── make_testmedia.sh # ffmpeg 生成冒烟测试媒体(多音轨/双编码/MKV+ASS/HLS)
│ └── smoke/ # 无头冒烟测试(mock Tauri + 79 项断言,含 Range/206)
│ ├── server.mjs # mock 服务器(dist + /files + /__invoke)
│ ├── tauri-mock.js # 页面侧 __TAURI_INTERNALS__ mock
│ └── drive.sh # agent-browser 驱动的回归脚本
├── docs/
│ ├── 使用说明.md # 面向最终使用者
│ └── 架构设计.md # 面向开发者(算法与取舍)
├── src/
│ ├── main.js # Svelte 5 mount 入口
│ ├── app.css # 全局样式(黑主题、toast)
│ ├── App.svelte # 主组件:播放引擎/导航/分页/断点记忆/事件/媒体管线
│ ├── lib/
│ │ ├── format.js # 展示格式化工具(时间/百分比/缩放标签)
│ │ ├── media.js # 扩展名/语言标签/编码名/字幕同名匹配/HLS 清单重写
│ │ ├── subtitles.js # WebVTT 统一出口(外挂 vtt/srt + 内嵌提取)
│ │ ├── filestream.js # 顺序流式读取器(read_range 分块,JS 兜底提取用)
│ │ ├── wakelock.js # 播放期间防屏保/休眠(Wake Lock + Rust 后备)
│ │ ├── mp4/
│ │ │ ├── analyzer.js # moov 定位(头序读/尾扫描)+ 轨道信息
│ │ │ └── mse-engine.js # MSE 多音轨引擎(分段/节流/seek/切轨/EOS 收尾)
│ │ └── mkv/
│ │ ├── loader.js # matroska-subtitles 浏览器 bundle 按需加载
│ │ ├── tracks.js # 手写 EBML 分析器(只读头部轨道表)
│ │ ├── subtitles.js # MKV 内嵌字幕:索引会话播放器(引擎 ①)+ 全量降级调度(②→③)
│ │ ├── ass.js # ASS/SSA → WebVTT 富文本(ass-compiler)
│ │ └── vendor/ # matroska-subtitles.min.js(含 LICENSE)
│ └── components/
│ ├── HintScreen.svelte # 引导屏(胶片视觉 + 大号 + 按钮)
│ ├── InfoBar.svelte # 顶部信息栏(I 键切换)
│ ├── ControlBar.svelte # 底部控制栏(两行式 + 音轨/字幕弹出菜单)
│ ├── VideoStage.svelte # 画面舞台(旋转/缩放/拖拽/单击双击判定)
│ ├── FileList.svelte # 右侧列表浮层行(目录分组/播放高亮/断点徽标)
│ └── HelpOverlay.svelte # F1 帮助层
└── src-tauri/
├── Cargo.toml # Rust 依赖(tauri 2 / dialog / serde / dirs)
├── build.rs
├── tauri.conf.json # 窗口/asset 协议/打包配置
├── capabilities/default.json # Tauri 2 权限(标题/关闭/全屏/目录选择)
├── icons/ # 全套图标(png/ico/icns)
└── src/
├── main.rs # 程序入口
├── lib.rs # Tauri Builder 装配(命令注册/窗口事件)
├── scanner.rs # 递归扫描 + 自然排序 + 外挂字幕收集(含单元测试)
├── state.rs # 状态持久化(含单元测试)
├── power.rs # 播放期间防屏保/休眠后备(含单元测试)
├── mkvsub.rs # MKV 内嵌字幕三级引擎(Cues 索引会话 / 原生 EBML 全量走读 + 进度)
├── mkvsub/tests.rs # 引擎单测(合成 Cues 索引 / 窗口与全量逐块一致 / 4GB 巨块 seek / 真实媒体对照)
└── commands.rs # Tauri IPC 命令(scan/read_range/stat/extract/progress/state/keep_awake/exit)
- 播放零转码:
<video>元素通过 asset 协议直接读取本地文件,seek / 音量 / 暂停全部由 WebView 原生媒体管线完成,不经过 IPC 传输媒体数据 - moov / 轨道表分析零浪费:MP4 的轨道信息只需要 moov 元数据区(通常几十 KB~几 MB),MKV 的轨道表在第一个 Cluster 之前的头部——两者都由 Rust
read_range按区间吐字节(moov 在文件头顺序读到、在文件尾特征扫描定位;MKV 从 512KB 起步扩窗至 16MB);播放期间几 GB 的 mdat 媒体数据一个字节都不走 IPC,MKV 内嵌字幕提取也已在 v1.0.5 下沉到 Rust 侧完成(仅第三级 JS 兜底路径才按 4MB 块流式过 IPC,见第 7 条) - MSE 多音轨按需启用:只有「多音轨且 MSE 支持至少一条音轨编码」的 MP4 才走 mp4box.js + MSE 双 SourceBuffer 路径(整文件读入内存,分段节流生成:前瞻超 24s 暂停、剩 12s 恢复,已送样例即时释放,内存稳定在 ~1× 文件大小);两轨送完后 endOfStream 收尾(否则播到样本尽头不触发 ended,连播失效);其余文件全部原生直读,零额外开销
- 同编码切轨画面不中断:只清音频 SourceBuffer 并单独
seekTrack重定位新轨,视频缓冲原封不动;异编码切轨(AAC ⇄ Opus 等)因 MSE 的 codecs 锁定与 Chromium 的 SourceBuffer 数量上限,采用整个 MediaSource 重建(mp4box 实例与整文件缓冲全程复用,零二次读盘),画面短暂重载后原位恢复 - 两段式精确 seek:MSE 路径粗定位到目标前最近的关键帧(RAP),待该处媒体段进缓冲后自动精调到目标帧——断点恢复能落回退出帧,逐帧步进在已缓冲区直接精确落点
- HLS 相对路径重写:asset 协议把整个文件路径整体编码(
%2F不是路径分隔符),浏览器按 URL 规则解析相对分片会丢目录——前端拿到 m3u8 后按文件系统路径把每个分片与URI="…"属性重写为绝对 asset URL - 字幕统一 WebVTT 出口 + MKV 三级引擎提取:MP4 内嵌 wvtt / tx3g 由 mp4box 抽样解出文本(MSE 模式复用引擎整文件缓冲,原生模式手动选择时才读入,超过 4GB 拒绝——mp4box 的 sample 提取要求字节全部驻留);MKV 内嵌 SRT / ASS 走三级降级:① Cues 索引会话(v1.0.7)——Matroska 自带的 Cues 索引记录每条轨道每个块的位置,
subtitle_session_open一次性解析 SeekHead + Cues(几百 KB、亚秒级)把目标轨位置表常驻后端内存,之后subtitle_window(from, to)按播放窗口直跳取块:只碰窗口内字幕块的几十 KB 字节,不顺序扫全文件——首屏字幕亚秒级可用,播放中每 ~90 秒补一窗(剩余 30 秒时预取),seek 落到未覆盖区间即查即得,新窗 cue 直接 addCue 追加不重建<track>;块时间取「簇时码 + 块相对时码」的权威计算(簇时码跨窗口缓存),任一索引条目未命中(skipped>0)立即整体降级 ②,不静默丢字幕;② 无 Cues / 索引缺 rel 定位(罕见封装,如 mkvmerge --no-cues)时后端原生 EBML 全量走读(spawn_blocking 后台线程,视频/音频块 seek 跳过,只有目标轨字幕块进内存,速度受磁盘顺序读限制,按文件偏移轮询 query_extract_progress 报百分比);③ 两者都失败(罕见的 lacing 分帧 / 容器损伤)才回退前端 JS 流式(matroska-subtitles 按需加载 147KB,分块喂入内存恒定)——后端报「轨道不存在 / 无内容」等定性错误时直接抛出不走兜底(JS 路径必撞同墙,白扫全文件只会浪费时间);切换字幕 / 文件立即作废并关闭会话;ASS / SSA(含外挂)由 ass-compiler 解析为斜体 / 粗体富文本,丢弃绘图指令与排版特效;外挂 srt 时间戳逗号→点转换;全部挂<track>,浏览器原生渲染 - hls.js 按需加载:只有播放 m3u8 时才动态 import(独立 chunk ~590KB),普通播放零负担
- 高频状态隔离:
flat[]等大数据不进 Svelte 响应式;拖拽平移的 pan 更新走「值不变不写」+ untrack,避免 effect 自触发循环;进度文字用 timeupdate 节流 - 扫描在阻塞线程池:
spawn_blocking执行递归扫描,UI 永不卡顿 - 状态防抖落盘:播放中 1.2 秒防抖保存,退出三重兜底(前端 destroy 前 + 窗口关闭事件 + Rust 侧 flush)
Q:多音轨 MP4 有什么限制? 多音轨路径需要把整个文件读进内存再分段(v1 设计取舍),数百 MB~2GB 的电影文件可用;更大的文件建议转单音轨或 HLS。MSE 不支持的编码(如个别平台的 HEVC)会自动回退原生播放并提示。
Q:为什么有些 MP4 的内嵌字幕选不上? v1 支持内嵌 wvtt(WebVTT-in-MP4)与 tx3g(mov_text)两种字幕编码,是最常见的两种;其他字幕编码(如 stpp)暂不支持,外挂 .vtt / .srt 不受影响。另:原生播放(非 MSE)模式下,MP4 内嵌字幕提取需要整文件读入内存,超过 4GB 的 MP4 会拒绝并提示改用外挂字幕(MSE 模式复用引擎缓冲无此限)。
Q:大文件 MKV(比如 5GB 以上)的内嵌字幕能用吗?提取要多久?
能用且秒级可用。v1.0.7 起为索引会话引擎:MKV 容器自带 Cues 索引(记录每个字幕块的位置),打开字幕轨时一次性解析索引(亚秒级),之后只按播放窗口直跳读取窗口内的几十 KB 字节——首屏字幕亚秒级挂载(实测 9.9GB 蓝光重封装在 5400rpm 机械硬盘上:全量扫描需 ~3 分钟,索引会话首窗 <1 秒、全片按窗取完 ~44 秒且全程领先播放头 35 倍以上);seek 前进 / 倒退即查即得,播放中每 90 秒后台补一窗。无索引的罕见封装(如 mkvmerge --no-cues)自动降级后端 Rust 原生全量走读(内存恒定、状态栏显示百分比;机械硬盘上大文件需分钟级),两者都失败(罕见的 lacing 分帧 / 容器损伤)才回退前端 JS 流式。v1.0.5v1.0.6 曾用 ffmpeg 子进程做首选引擎,v1.0.7 实测被索引跳跃全面超越后移除(同时免去外部依赖与便携部署负担)。所有路径内存占用都与文件大小无关,切走字幕 / 文件立即取消。v1.0.3 及之前因「整文件读入单个 ArrayBuffer」受 V8 约 4GB 上限约束才有「文件过大」的拒绝提示(v1.0.4 流式化已废除)。
Q:内嵌字幕什么时候会自动选中? 默认按界面语言(中文)匹配:外挂中文字幕优先(零成本),内嵌中文字幕在 MSE 模式(文件已在内存)也会自动选中;MKV 内嵌与原生模式 MP4 内嵌默认不自动选(保持「用户点开菜单」的确定性交互;MKV 会话路径虽已亚秒级,仍留手动选择),手动点击不受限。
Q:mkv / avi 能放吗? 取决于系统 WebView 的解码器(Windows WebView2 对 mkv 内的 H.264/AAC 通常可以,Linux WebKitGTK 视发行版而定)。不能播放时会提示「无法播放该文件」,其余文件不受影响。
Q:为什么我快进后位置有一点点偏差? MSE 多音轨文件的跳转先落在目标前最近的关键帧、再自动精调到目标帧(两段式);个别情况下精调被后续操作取消,会停在关键帧上(与目标相差通常不超过一个 GOP,几秒以内)。原生播放的文件没有这个现象。
Q:启动后没有自动播放? 断点续看刻意设计为暂停状态(定位到退出的位置,按空格继续)。全新打开目录会自动播放第一个文件;若被系统自动播放策略拦截,会提示按空格开始。
Q:想重置全部记忆?
删除状态文件(见上文路径),或按 X 清除当前目录的记忆。
Q:+ / - 不是调音量吗?
本程序的 + / - 是画面缩放(音量用 ↑↓ / 滚轮 / 滑杆),与极速听书的语义不同,属需求原文设定。
Q:长时间播放会触发屏保 / 休眠吗? 不会。播放期间程序会阻止系统屏保与休眠(双层:WebView 原生 Wake Lock API 优先,不可用时由 Rust 后备——Windows 用 SetThreadExecutionState,macOS 用 caffeinate,Linux 用 systemd-inhibit);暂停、播完或关闭目录即恢复正常电源策略。所有实现都随进程退出自动解除,不会残留系统级锁。
本项目代码供学习与自由使用。