dsh-music-player 0.6.0 → 0.6.2

package/README.md

@@ -13,7 +13,7 @@ DeepSeek Harness 本地音乐/小说播放插件。
 - 本地音频流式播放（HTTP Range），刷新后断点续播
 - 顺序播放、单曲循环、乱序播放三种模式
 - 实时 8 段频谱可视化（真实 FFT 频段，解码时离线计算、跟随播放位置）
-- **实时歌词/字幕**：本地音频自动匹配同名 `.lrc` 逐行显示；在线 QQ 歌曲自动取官方歌词（外语歌带逐句翻译「原文 ／ 翻译」）；AI 讲书时显示当前朗读句子（逐句滚动）。歌词/字幕显示在播放条频谱之后、时长之前，仅在闲置（控件组折叠）时展示，鼠标进入操作时自动收起
+- **实时歌词/字幕**：本地音频自动匹配同名 `.lrc` 逐行显示；**本地没有同名 `.lrc` 时自动在线兜底**（QQ 音乐官方歌词 → LRCLIB 免费同步歌词，结果按曲目缓存避免重复请求）；在线 QQ 歌曲自动取官方歌词（外语歌带逐句翻译「原文 ／ 翻译」）；AI 讲书时显示当前朗读句子（逐句滚动）。歌词/字幕显示在播放条频谱之后、时长之前，仅在闲置（控件组折叠）时展示，鼠标进入操作时自动收起；**AI 讲书还有一条「已读字符/全书字符」的全书进度细线**（按已读字数实时计算，不依赖合成时长，切块不回退，操作时再显示「N%」）
 - 播放时申请屏幕唤醒锁，防止听歌时熄屏/休眠（支持 Wake Lock 的浏览器，如 Chrome/Edge）
 - 播放列表面板可自由拖动，右下角可拖拽调整大小，位置与尺寸跨刷新记忆
 - AI 讲书：本地 `.txt` / `.epub` 小说经 MiMo TTS 合成朗读，自动识别**书名/前言/章节/尾声**结构，播放条带**章节目录**跳转（打开即定位到当前正在播放的章节）、章节切歌，可选 4 种中文 AI 声音（默认白桦）
@@ -85,7 +85,13 @@ dsh plugin --profile <profile> add ./dsh-music-player-0.1.0.tgz
       name: 'dsh-music-player'
 ```
 
-播放模式与音量保存在浏览器 `localStorage`，当前曲目与进度也会在刷新后恢复（浏览器的自动播放可能被拦截，点一次 ▶ 即可解锁）。
+播放模式与音量等播放偏好都保存在 **Host 端**（见下），刷新后当前曲目与进度也会恢复（浏览器的自动播放可能被拦截，点一次 ▶ 即可解锁）。
+
+> **状态持久化（重要）**：**所有**播放状态都持久化在 Host 端文件 `~/.dsh/music-player-prefs.json`，包括：
+> 音量、播放顺序、AI 讲书声音、播放范围、面板位置、上次播放的曲目/进度、每本小说的进度、QQ 搜索历史、QQ 面板所在层、QQ「我喜欢」收藏兜底。
+> 因此即使在 **dsh-desktop 桌面版**（每次启动随机端口、浏览器存储按源隔离）下，重启后这些状态照样能找回。
+> **升级兼容**：旧版本（<0.7）把同样的键存在浏览器 `localStorage` 里。升级后客户端**优先读 Host**，Host 没有的记录会**自动回退读取旧 `localStorage` 副本并迁移进 Host**，升级不丢用户数据。
+> 音乐/小说目录、自建歌单、QQ 登录态也持久化在 Host 端（见下文），同样不受影响。
 
 ## 自建歌单（收藏）
 
@@ -119,7 +125,7 @@ dsh plugin --profile <profile> add ./dsh-music-player-0.1.0.tgz
   - 分类歌单：60+ 分类（默认折叠显示 8 个，可展开），每个分类的歌单支持「加载更多」。
   - 排行榜：巅峰榜/地区榜/特色榜等分组，点榜单看歌曲（带榜单封面卡片），榜单详情底部「加载更多」可分页续载全部歌曲。
   - 新歌：新歌速递（最新/内地/港台/欧美/韩国等）。
-  - 搜索：搜歌曲与歌单，带搜索历史（localStorage，最近 10 条）。
+  - 搜索：搜歌曲与歌单，带搜索历史（Host 持久化，最近 10 条）。
 - **播放**：点击任意歌曲即可播放（同一播放条 + 频谱）；VIP 标识显示在歌名后，行尾显示歌手名。进入歌单/播放列表时自动定位到正在播放的那一首，且正在播放的条目以高亮选中态显示。
 - **收藏**：播放条爱心按钮把当前在线曲目收藏到 QQ 音乐「我喜欢」，已收藏歌曲爱心实时点亮。
 - **续播**：在线播放进度（当前曲目 + 队列）刷新后自动恢复，点 ▶ 续播。
@@ -141,6 +147,7 @@ dsh plugin --profile <profile> add ./dsh-music-player-0.1.0.tgz
    - **章节目录**（📖 按钮）：自动识别全书结构（书名/前言/章节/尾声），点击弹出**位于按钮正上方**的目录（自动定位到当前正在播放的章节），点击任意章节即从该章开头朗读
    - **后退 / 前进**：讲书模式下跳上一章 / 下一章（音乐模式下仍是上一首 / 下一首）
    - **AI 声音**：点音量按钮，在弹层选择声音——冰糖（女）、茉莉（女）、苏打（男）、白桦（男，默认）
+   - **全书进度**：播放条底部有一条「已读字符/全书字符」的进度细线，操作时显示「N%」——按已读字数实时计算，无需先合成全书就能给出稳定的整体进度（切块不回退；字符量来自源文本，因此总长总是可知，而总时长得合成完才知道），刷新页面后也会立即恢复显示（无需先点播放）
 4. 刷新页面后从上次位置续读（断点续播）。
 
 支持的格式：
@@ -173,7 +180,7 @@ dsh plugin --profile <profile> add ./   # 或直接改 profile 里的 link 目
 点面板顶部「选择音乐目录」，选一个包含音频文件的实际目录（默认 `~/Music`）。目录路径不可读或不存在时会回退到默认目录而不是报错。
 
 **改了音乐目录/新增了歌曲，但列表没更新？**
-播放器在启动时扫描，并在每次“选择音乐目录”时重扫。想强制刷新当前目录，重新打开一次面板或点一次目录设置即可（扫描上限 500 首、递归子目录深度上限 4 层）。
+播放器在启动时扫描一次，并支持手动重扫：点「选择音乐目录」旁边的新增 **「刷新」按钮**，会重新遍历当前目录并更新列表（音乐与小说通用；无需重选目录）。扫描上限 500 首、递归子目录深度上限 4 层。
 
 **`music_play` 工具说"音乐库为空"？**
 说明还没有可用的音乐目录。请先打开播放面板，点「选择音乐目录」配置一次。
@@ -187,6 +194,9 @@ AI 语音目前仅支持 xiaomi 提供方（限时免费）。请先在 DSH 模
 **听书偶尔"没声音但时间还在走"？**
 这种一般是某一段的合成结果异常（返回了退化/静音音频），或瞬时合成失败。0.3.3 起 Host 端会严格校验合成音频（拒绝空数据/非 PCM 等退化 WAV）并自动重试一次瞬时失败，同时把每次合成结果记录在诊断日志里。若再遇到，可访问 `http://<DSH地址>/dsh-music/tts-logs` 查看最近 60 条合成记录（含失败原因、退化音频事件），据此定位具体是哪个块出的问题。
 
+**本地音乐没有 .lrc，歌词是怎么来的？**
+播放器会**在线兜底取词**：先用文件名（可带歌手/时长）在 QQ 音乐匿名接口匹配官方歌词（外语歌带逐句翻译），QQ 无果再查 LRCLIB（免费公开歌词库，返回同步 LRC）。结果按曲目在进程内缓存（正命中 6 小时 / 空命中 30 分钟），避免重复请求；无匹配或失败时静默保持无歌词，不影响播放。歌词为版权内容，仅供个人试听。
+
 **想支持更多音频格式？**
 格式支持由 Host 端 `AUDIO_TYPES` 表驱动，在 `lib/index.js` 里加扩展名与 MIME 即可（播放器本身用浏览器原生 `<audio>` 解码，最终能否播放还取决于浏览器对该编码的支持）。