Skip to content

About

「极速听书」是一款专注「快速收听本地有声书」的桌面应用。把一个文件夹拖进窗口,程序会按字母顺序递归遍历所有子目录,把每个目录里的声音文件按顺序连成一条完整收听序列;播放界面是一幅纯黑舞台:当前文件的 wav 波形,已播绿色 / 未播亮灰,前景颜色变化即播放位置标记。波形采用低精度稀疏采样,单集 30 分钟的有声书秒级出图。退出时自动记住收听位置——不只记住当前文件,而是每一个文件的播放位置都单独记忆,下次启动定位到退出的位置并暂停等待。

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

极速听书(JisuTingshu)

基于 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-dev

Windows:需 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 命令定义

性能与设计要点(为什么流畅)

  1. 播放零转码:<audio> 元素通过 asset 协议直接读取本地文件,seek / 音量 / 暂停全部由 WebView 原生媒体管线完成,不经过 IPC 传输音频数据
  2. 波形低精度稀疏采样:有声书单集普遍 1030 分钟以上,全局波形只是密密麻麻的竖线、看不出明显静音段落,低精度采样完全够用——把屏幕宽度作为采样点数(约等于窗口最大化时的画布宽度,一列一点),在文件加载时一次算好,后端对每个位置 seek 过去只解码约 10ms 的一小窗取峰值;30 分钟的文件实际只解码约 30 秒音频,比全量解码快 12 个数量级(600 秒 mp3 实测约 2.8 秒,m4a 约 0.35 秒;沙箱 debug 构建,release 更快)。容器缺少时长元数据或该格式不支持 seek 时自动回退全量流式解码 + 最大值池化,结果依然正确,只是慢
  3. mp3 位水库兼容:mp3(Layer III)的位水库使 seek 后首帧可能被清零,稀疏采样对 mp3 跳过 seek 后首个解码包;PCM / AAC / FLAC / Vorbis 帧自包含,首包直接可信
  4. 双层离屏合成:波形按「未播色 / 已播色」预渲染成两张离屏画布,每帧只是两次 drawImage + 一次矩形裁剪,60fps 毫无压力;窗口缩放只按新宽度拉伸重绘,同一份峰值复用(不重新采样、不重打后端)
  5. 峰值缓存:每个(文件, 采样点数)组合的峰值缓存于会话内(点数固定为屏幕宽度,缩放窗口不改变缓存键),缓存上限 64 个组合,超出淘汰最早的;切回文件毫秒级出波形
  6. 波峰不丢:回退路径的降采样一律用最大值池化(max-pool),瞬态响度不会被平均抹平
  7. 高频状态隔离:波形播放头(每帧)与文本进度(约 5Hz 节流)分离驱动;flat / lineOfIdx 等大数据不进 Svelte 响应式,只有渲染相关状态用 $state
  8. 扫描在阻塞线程池:spawn_blocking 执行递归扫描与波形解码,UI 永不卡顿
  9. 状态防抖落盘:播放中 1.2 秒防抖保存,退出三重兜底(前端 destroy 前 + 窗口关闭事件 + Rust 侧 flush)

常见问题(FAQ)

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 等),需要网络。


许可

本项目代码供学习与自由使用。

About

「极速听书」是一款专注「快速收听本地有声书」的桌面应用。把一个文件夹拖进窗口,程序会按字母顺序递归遍历所有子目录,把每个目录里的声音文件按顺序连成一条完整收听序列;播放界面是一幅纯黑舞台:当前文件的 wav 波形,已播绿色 / 未播亮灰,前景颜色变化即播放位置标记。波形采用低精度稀疏采样,单集 30 分钟的有声书秒级出图。退出时自动记住收听位置——不只记住当前文件,而是每一个文件的播放位置都单独记忆,下次启动定位到退出的位置并暂停等待。

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages