基于 Rust + Tauri 2.0 + Svelte 5 + Vite 的桌面有声书播放器 拖入目录即听 · 黑色波形舞台 · 字母顺序递归收听 · 全键盘操作 · 每文件断点续听
「极速听书」是一款专注「快速收听大量本地有声书」的桌面应用。把一个文件夹拖进窗口(或点引导页大号「+」按钮选目录),程序会按字母顺序递归遍历所有子目录,把每个目录里的声音文件按顺序连成一条完整收听序列;播放界面是一幅纯黑舞台:当前文件的 wav 波形垂直居中、占主窗口一半高度(上下留空),已播绿色 / 未播亮灰,前景颜色变化即播放位置标记,左上角显示白色文件名。波形采用低精度稀疏采样——采样点数在文件加载时按屏幕宽度一次算好(与窗口宽度无关,缩放窗口不重取)、每点只解码约 10ms,单集 30 分钟的有声书秒级出图。退出时自动记住收听位置——不只记住当前文件,而是每一个文件的播放位置都单独记忆(播放完毕的自动清空),下次启动定位到退出的位置并暂停等待。
技术栈:
| 层 | 技术 |
|---|---|
| 后端 | Rust 1.77+,Tauri 2,symphonia(音频 seek + 稀疏采样提取波形峰值),tauri-plugin-dialog(系统目录选择) |
| 前端 | Svelte 5(runes),Vite 6,原生 <audio> 元素(asset 协议直读本地文件) |
| 通信 | Tauri IPC 命令 + asset 协议(本地音频零拷贝直读) |
本仓库已在 Debian 13 + Rust 1.98 + Node 24 环境验证:npm run build(前端,133 模块零警告)、后端逻辑模块 cargo test(扫描排序 / 状态持久化 / 波形稀疏采样 / IPC 契约 / ffmpeg 生成的真实 mp3 / m4a / flac / ogg 解码及 10 分钟长文件 seek 正确性与速度护栏,26/26 单测通过)与 cargo metadata 依赖解析全部通过;另以 mock Tauri API 的无头浏览器冒烟测试(Chromium)完整走会话恢复、文件导航、分页翻页、随机 / 循环切换、各浮层开关、列表点选、波形像素三色(黑底 / 亮灰 / 绿)、「屏幕宽度 = 采样点数」与窗口变化不重取的真实运行路径,全程零运行时错误。完整 GUI 链接(webkit2gtk)请在目标平台执行 npm run tauri dev / npm run tauri build 复验。
- 拖拽即开:把文件夹拖到窗口任意位置即可开始收听;误拖文件时自动打开其所在目录
- 点选即开:引导页大号「+」按钮弹出系统目录选择对话框,与拖拽完全等效(无需鼠标拖拽也能用)
- 一键关目录:
X键关闭当前目录回到引导页,同时清除该目录的位置记忆(下次启动不再自动恢复) - 递归有序收听:按字母顺序递归遍历所有子目录(自然排序:
track2.mp3排在track10.mp3之前) - 波形播放界面(黑色舞台):主窗口为纯黑波形舞台(与其他窗口配色一致);当前文件的 wav 波形垂直居中、占主窗口一半高度(上下留空),已播绿色 / 未播亮灰,前景颜色变化即播放位置标记;左上角显示白色文件名与相对目录(固定排版);点击波形直接跳转;波形低精度稀疏采样(采样点数按屏幕宽度在文件加载时一次算好,每点仅解码约 10ms;缩放窗口 / 开合列表浮层不重新采样,只把同一份峰值拉伸绘制),长文件秒级出图
- 右侧文件列表浮层(
T切换,默认显示):独立于主窗口的屏幕右侧浮层(黑色背景亮灰文字,紧凑小字号),每个目录的声音文件顺序显示(目录分组标注),回车翻页;列表始终锚定在当前播放的文件(首次打开选中第一个文件);顶 / 底分别让位给信息栏与控制栏,隐藏后波形自动变宽 - 顶部信息栏(
I切换):相对目录 / 文件名 · 播放进度(百分比 +00:00:00),随播放动态更新 - 底部控制栏(
C切换,两行式):最左侧大号播放 / 暂停按钮;右侧上半行靠右依次是随机 / 顺序开关、循环开关、音量图标(可点击静音 / 解除)与音量 slider;下半行是占满可用宽度的播放位置 slider,播放位置 / 总时长文字位于同行最右侧 - 随机播放:洗牌袋算法(一轮之内不重复),上一文件走历史栈
- 三级循环:不循环(默认)/ 列表循环 / 单曲循环,
L键循环切换 - 细粒度断点记忆:每个文件的播放位置独立记忆(播放完毕自动清空);切换文件再切回来,从上次的位置继续
- 退出即存档:退出时记住当前文件与位置,下次启动定位到该位置并暂停等待(断点续听)
- 常见格式全覆盖:mp3 / m4a / m4b / wav / flac / aac / ogg 等播放 + 波形双通道支持
| 类别 | 扩展名 | 播放 | 波形 |
|---|---|---|---|
| 常用格式 | mp3 wav m4a m4b flac aac |
WebView 原生 | symphonia 提取 |
| OGG 家族 | ogg oga(Vorbis) |
WebView 原生 | symphonia 提取 |
| 尽力播放(取决于系统 WebView 解码器) | opus aif aiff wma weba mp4 |
支持即可播 | 播放不受波形影响,不支持时显示占位提示 |
说明:播放走 WebView 的
<audio>元素(Windows WebView2 / macOS WKWebView / Linux WebKitGTK 对上表主流格式均有良好支持);波形由 Rust 侧 symphonia 稀疏采样提取,Opus / WMA / AIFF 等暂不支持波形分析,波形区显示「波形不可用」提示,播放完全不受影响。扩展名判断忽略大小写(.MP3与.mp3等价)。
| 按键 | 功能 |
|---|---|
→ 右方向键 |
快进 30 秒 |
← 左方向键 |
快退 30 秒 |
↑ 上方向键 |
音量 +5% |
↓ 下方向键 |
音量 -5% |
空格 |
播放 / 暂停 |
回车 Enter |
下一页(文件列表分页) |
PageDown |
下一个文件 |
PageUp |
上一个文件 |
Home |
第一个文件 |
End |
最后一个文件 |
Esc |
退出程序(帮助层开着时先关帮助层) |
+ 或 = |
音量 +5% |
- 或 _ |
音量 -5% |
,(含中文逗号 ,) |
快进 5 秒 |
.(含中文句号 。) |
快退 5 秒 |
I |
显示 / 隐藏顶部信息栏(默认显示) |
C |
显示 / 隐藏底部控制栏(默认显示) |
T |
显示 / 隐藏右侧文件列表浮层(默认显示;隐藏后波形自动变宽) |
R |
切换随机 / 顺序播放(默认顺序;控制栏隐藏时显示 toast 提示) |
L |
切换列表循环 / 单曲循环 / 不循环(默认不循环;控制栏隐藏时显示 toast 提示) |
X |
关闭当前目录,回到引导页(同时清除位置记忆) |
F1 |
显示快捷键帮助 |
| 操作 | 功能 |
|---|---|
| 引导页大号「+」按钮 | 点击弹出系统目录选择对话框(与拖拽等效) |
| 点击文件列表某一行 | 播放该文件 |
| 点击波形 | 跳转到对应位置 |
| 点击其他空白区域 | 播放 / 暂停 |
| 点击音量图标 | 静音(图标变为静音样式),再次点击解除静音;拖动音量滑杆也会自动解除 |
| 滚轮向上 | 音量 +5% |
| 滚轮向下 | 音量 -5% |
| 拖入文件夹 | 打开 / 切换主目录 |
- 播放 / 暂停:空格、鼠标点击空白区域、控制栏最左侧的大号按钮三种方式等效
- 快进 / 快退:左右方向键 ±30 秒,
,.(含中文标点)±5 秒;也可拖动底部进度条或点击波形跳转 - 音量与静音:上下方向键 /
+-/ 滚轮,每次 ±5%;控制栏滑杆可连续调节;点击音量图标静音(临时状态,不持久化),再次点击或主动调音量自动解除;音量随状态文件持久化 - 随机 / 顺序(
R或底部开关):随机采用「洗牌袋」——把除当前文件外的全部文件洗成一袋依次播放,一轮之内不重复;袋空后按循环模式决定停止(不循环)或重洗(列表循环)。随机模式下的「上一文件」走播放历史栈 - 循环三态(
L或底部开关循环切换):不循环(默认,列表播完即停)→列表循环(末尾回开头)→单曲循环(单个文件无限重复)→ 回到不循环 - 手动导航始终环形:
PageDown在最后一个文件时回到第一个(PageUp、Home、End同理);「不循环」只约束自动连播到列表末尾时的行为 - 播放到文件末尾:该文件的断点记忆立即清空,然后按循环模式继续
有声书/
├── 01-序章.mp3 ← ① 先列出本目录的声音文件(按文件名自然排序)
├── 第01章/
│ ├── 1.mp3 ← ② 再按目录名顺序进入第一个子目录,如此递归
│ └── 10.mp3 (自然排序:2 排在 10 前面)
├── 第02章/
│ └── 1.mp3 ← ③ 第二个子目录
└── 空目录/ ← 没有声音文件的目录不会出现在分组与导航序列里
准确规则:每个目录内,先显示本目录声音文件(自然排序),再依次进入按名称排序的各子目录递归;文件与目录均忽略大小写、数字按数值比较(track2 < track10)。目录符号链接不跟随(防目录环)。文件列表中目录变化处会插入一条暗色的分组行(根目录不插)。
| 项 | 要求 |
|---|---|
| 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)。
程序在播放过程中(防抖 1.2 秒)自动保存,并在窗口关闭时兜底保存一次。状态文件:
| 系统 | 路径 |
|---|---|
| Windows | %APPDATA%\jisu-tingshu\state.json |
| macOS | ~/Library/Application Support/jisu-tingshu/state.json |
| Linux | ~/.config/jisu-tingshu/state.json |
记住的内容:
| 内容 | 规则 |
|---|---|
| 当前文件与位置 | 退出时所在文件 + 播放位置(毫秒);下次启动定位到该位置并暂停,按空格继续 |
| 每个文件的断点 | 单独记忆每个文件的位置(毫秒);播放完毕自动清空;距开头不足 1 秒或距末尾不足 1 秒的进度不记忆(视为未听 / 已听完) |
| 播放偏好 | 音量、随机 / 顺序、循环模式、信息栏 / 控制栏 / 文件列表浮层可见性(静音为临时状态,不持久化) |
按 X 关闭目录:立即回到引导页,清除该目录(含子目录)全部文件的断点记忆与恢复指针,其他有声书目录的断点保留;音量 / 模式等偏好不受影响。删除状态文件则全部清零。下次启动时若上次目录已不可用,会回到引导界面。v1.0 ~ v1.2 的旧状态文件可无损升级读取(新字段自动回退默认值,已移除的外观 / 颜色字段自动忽略)。
jisu-tingshu/
├── index.html # Vite 入口 HTML(内联黑底防白闪)
├── package.json # 前端依赖与脚本(npm run tauri dev/build)
├── vite.config.js # Vite 配置
├── svelte.config.js
├── src/
│ ├── main.js # Svelte 5 mount 入口
│ ├── app.css # 全局样式(默认黑主题、toast)
│ ├── App.svelte # 主组件:播放引擎/导航/分页/洗牌袋/断点记忆/事件/列表浮层
│ └── lib/
│ └── format.js # 展示格式化工具(时间/百分比/断点短时)
│ └── components/
│ ├── HintScreen.svelte # 引导屏(拖拽提示/大号+按钮/扫描中/空目录/错误)
│ ├── InfoBar.svelte # 顶部信息栏(I 键切换)
│ ├── ControlBar.svelte # 底部控制栏(C 键切换;两行式:播放键最左+静音图标)
│ ├── WaveformView.svelte # 波形画布(双层离屏合成,前景色标记进度)
│ ├── FileList.svelte # 右侧列表浮层行(目录分组/播放高亮/断点徽标)
│ └── HelpOverlay.svelte # F1 帮助层
└── src-tauri/
├── Cargo.toml # Rust 依赖(tauri 2 / symphonia / tauri-plugin-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 # 递归扫描 + 自然排序(含单元测试)
├── waveform.rs # symphonia 稀疏采样波形提取 + 全量回退 + 会话级缓存(含单元测试)
├── state.rs # 状态持久化(含单元测试)
└── commands.rs # Tauri IPC 命令定义
- 播放零转码:
<audio>元素通过 asset 协议直接读取本地文件,seek / 音量 / 暂停全部由 WebView 原生媒体管线完成,不经过 IPC 传输音频数据 - 波形低精度稀疏采样:有声书单集普遍 10
30 分钟以上,全局波形只是密密麻麻的竖线、看不出明显静音段落,低精度采样完全够用——把屏幕宽度作为采样点数(约等于窗口最大化时的画布宽度,一列一点),在文件加载时一次算好,后端对每个位置 seek 过去只解码约 10ms 的一小窗取峰值;30 分钟的文件实际只解码约 30 秒音频,比全量解码快 12 个数量级(600 秒 mp3 实测约 2.8 秒,m4a 约 0.35 秒;沙箱 debug 构建,release 更快)。容器缺少时长元数据或该格式不支持 seek 时自动回退全量流式解码 + 最大值池化,结果依然正确,只是慢 - mp3 位水库兼容:mp3(Layer III)的位水库使 seek 后首帧可能被清零,稀疏采样对 mp3 跳过 seek 后首个解码包;PCM / AAC / FLAC / Vorbis 帧自包含,首包直接可信
- 双层离屏合成:波形按「未播色 / 已播色」预渲染成两张离屏画布,每帧只是两次
drawImage+ 一次矩形裁剪,60fps 毫无压力;窗口缩放只按新宽度拉伸重绘,同一份峰值复用(不重新采样、不重打后端) - 峰值缓存:每个(文件, 采样点数)组合的峰值缓存于会话内(点数固定为屏幕宽度,缩放窗口不改变缓存键),缓存上限 64 个组合,超出淘汰最早的;切回文件毫秒级出波形
- 波峰不丢:回退路径的降采样一律用最大值池化(max-pool),瞬态响度不会被平均抹平
- 高频状态隔离:波形播放头(每帧)与文本进度(约 5Hz 节流)分离驱动;
flat/lineOfIdx等大数据不进 Svelte 响应式,只有渲染相关状态用$state - 扫描在阻塞线程池:
spawn_blocking执行递归扫描与波形解码,UI 永不卡顿 - 状态防抖落盘:播放中 1.2 秒防抖保存,退出三重兜底(前端 destroy 前 + 窗口关闭事件 + Rust 侧 flush)
Q:为什么我听过的文件下次从头开始了?
播放到距末尾不足 1 秒的位置会被视为「已听完」并清除断点;另外按 X 关闭目录会清空该目录全部断点。
Q:Opus / WMA 文件没有波形? 这些格式的容器 / 解码器暂不在 Rust 侧 symphonia 的波形支持范围内。播放由 WebView 负责,通常不受影响;波形区会显示占位提示。
Q:波形是「稀疏采样」的,会不会不准? 波形列数 = 屏幕宽度(文件加载时一次算好,缩放窗口不重取),每列在整条时间轴上均匀取点、只解码约 10ms 窗口取峰值——对「看位置、看响度轮廓」这个用途绰绰有余;但因为不是逐帧解码,极短瞬态(如几十毫秒的点击音)可能不在采样窗口内,波幅与全量解码存在微小差异。这是速度(快 1~2 个数量级)与精度的刻意取舍。
Q:启动后没有自动播放? 断点续听刻意设计为暂停状态(定位到退出的位置,按空格继续)。全新打开目录则会自动播放第一个文件;若被系统自动播放策略拦截,会提示按空格开始。
Q:随机模式会不会一直跳同一首? 不会。洗牌袋保证一轮之内不重复;「不循环 + 随机」把袋里所有文件听完一遍后停止。
Q:播放到列表末尾停了,想继续听怎么办?
这是「不循环」模式的预期行为。按 L 切到「列表循环」,或按 Home 回到第一个文件。
Q:想重置全部记忆?
删除状态文件(见上文路径),或按 X 清除当前目录的记忆。
Q:为什么我打不了正式包?
确认系统依赖完整(见「环境要求」),首次 npm run tauri build 会下载打包工具(NSIS / linuxdeploy 等),需要网络。
本项目代码供学习与自由使用。