dsh-music-panel 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.3.0
+
+### 功能
+
+- 收藏「我喜欢」：底栏与歌曲行爱心，独立 tab，`favorites.json` 持久化
+- 最近播放：统计页新增「收听排行 / 最近播放」模式切换
+- 队列编辑：上移、下移、移除单曲、清空队列
+- 搜索增强：标题 / 歌手 / 专辑 / 文件夹 / 路径 + 全拼 / 首字母，多关键词 AND，记住最近 8 条搜索
+- 超大曲库虚拟列表：列表只渲染可视行 + overscan
+- 歌词校准：播放页按 ±0.5s 调整；可写回 MP3（ID3 USLT）/ FLAC（Vorbis LYRICS），写前备份 `.lyrics.bak`
+- 多标签页互斥：Web Locks 选主，只有主控页发声与计时；其余页提示「另一个标签页正在播放」
+
+### 依赖
+
+- 新增 `node-id3`、`flac-tagger`（歌词写回）、`pinyin-pro`（拼音搜索）
+
+### 数据
+
+- 新增 `<DSH_HOME>/music/favorites.json`
+- `stats.json` 增加 `lyricOffsetMs`
+
 ## 0.2.0
 
 ### 功能

package/README.md

@@ -29,6 +29,11 @@ DeepSeek Harness 的本地音乐插件：左侧栏一个音符入口，点开是
 - **设置面板**：主面板右上角齿轮打开，含「外观 / 歌词 / 音乐库 / 播放」四个标签页：外观调整迷你浮窗与圆形封面显示，歌词调整来源顺序、对齐、字号、翻译与状态栏歌词，音乐库管理音乐文件夹与子文件夹深度（保存后主面板自动重新扫描），播放控制启动恢复、自动播放与每首歌断点。
 - **外观设置**：迷你浮窗（右下角可拖动、记忆位置）、播放页圆形封面 / 黑胶底盘 / 封面旋转。
 - **歌词设置**：歌词来源顺序（内嵌 / LRC，可调）、对齐方式、字体大小与粗细、模糊非当前歌词、翻译开关与翻译字号缩放、状态栏歌词（输入框内或输入框上方显示当前唱词）。
+- **歌词校准**：播放页 → 歌词设置里按 ±0.5s 调整偏移；「写回文件」把校准后的 LRC 写回 MP3（ID3 USLT）/ FLAC（Vorbis LYRICS）内嵌歌词，写前自动备份为 `<文件>.lyrics.bak`。
+- **收藏与最近播放**：底栏 / 歌曲行爱心加入「我喜欢」tab；统计页可切换「收听排行 / 最近播放」。
+- **队列编辑**：播放队列支持上移、下移、移除单曲与清空。
+- **搜索**：标题 / 歌手 / 专辑 / 文件夹 / 路径 + 全拼 / 首字母（如 `zhoujielun`、`zjl`），并记住最近 8 条搜索。
+- **多标签页互斥**：用 Web Locks 选主，只有一个标签页发声与计时；其他标签页底栏提示「另一个标签页正在播放」。
 - **播放列表**：顶栏「全部歌曲」与每个歌单各占一个 tab，**页面结构完全一致**（搜索、排序、多选、播放全部、循环/随机、队列）；「全部歌曲」是不可编辑集合，歌单可点标题改名、删除、逐首移除。右侧 `+` 新建歌单（自动命名，重名递增）并立即选中。歌单存于 `<DSH_HOME>/music/playlists.json`。
 - **播放页**：点击底栏空白处（封面/标题/进度条以外）以滑入动画打开全屏播放页——左侧黑胶唱片（外盘 + 圆形封面，播放时旋转、暂停即停在当前角度），右侧歌词；点歌词可跳转，Esc 或顶部按钮收起。
 - **歌词**：优先读歌曲**内嵌歌词**（ID3 USLT/SYLT、FLAC LYRICS、MP4 ©lyr），带时间戳的自动滚动高亮，纯文本的静态可滚动展示；没有内嵌时回退到同目录同名 `.lrc`。支持一行多时间戳、元数据标签、原文+翻译同时间戳合并。
@@ -74,6 +79,9 @@ plugin_manager install_bundle D:/SystemFiles/Documents/Project/DSH/plugins/dsh-m
 | POST | `/music/playback` | 累加有效播放时长，body `{ path, seconds }` |
 | GET | `/music/position?path=…` | 该曲上次停止位置（每首歌断点） |
 | POST | `/music/position` | 保存某曲停止位置，body `{ path, seconds }` |
+| GET | `/music/favorites` | 收藏列表（按收藏时间倒序） |
+| POST | `/music/favorites` | 切换收藏，body `{ path }` |
+| POST | `/music/lyrics/calibrate` | 保存歌词偏移 `{ path, offsetMs, write? }`；`write: true` 写回内嵌并清零偏移 |
 | GET | `/music/stats?range=week\|month\|all` | 按范围聚合的播放次数 / 时长 / 最近播放 |
 | GET | `/music/cover?path=…` | 内嵌封面；无封面返回 404 |
 
@@ -100,11 +108,14 @@ patch 的 `config` 是首次启动的种子：
 两个文件都在 `<DSH_HOME>/music/`：
 
 - `playback.json`：上次播放的队列（最多 500 条）、当前索引、位置、循环 / 顺序，用于启动恢复。
-- `stats.json`：每首歌的 `addedAt`、`plays`（Last.fm 规则计数）、`playSeconds`（有效播放秒数）、`lastPlayedAt`、`lastPositionSec`（每首歌断点，仅在设置里开启时写入），以及最近 31 天的每日分桶 `days`（供统计页的「最近一周 / 最近一月」使用）。
+- `favorites.json`：收藏（`path → 收藏时间`），「我喜欢」tab 与爱心按钮共用。
+- `stats.json`：每首歌的 `addedAt`、`plays`（Last.fm 规则计数）、`playSeconds`（有效播放秒数）、`lastPlayedAt`、`lastPositionSec`（每首歌断点，仅在设置里开启时写入）、`lyricOffsetMs`（歌词校准偏移），以及最近 31 天的每日分桶 `days`（供统计页的「最近一周 / 最近一月」使用）。
 
 写入时机：播放中每 5 秒保存一次状态；切歌、暂停、页面隐藏 / 关闭时立即 flush。播放时长只累计播放中自然前进的时间（拖动进度条不计），单次不足 30 秒的片段不进入统计（对齐网易云「有效播放」）。
 
-多标签页同时播放同一首歌时会各自计时，统计可能重复；这一期不做标签页互斥。
+多个标签页同时打开时，Web Locks 只让一个标签页成为“主控”播放与计时；其他标签页不发声，底部会提示由另一页播放，主控页关闭后其余页自动接任（但不会自动开始播放）。
+
+歌词写回依赖 `node-id3`（MP3 USLT）与 `flac-tagger`（FLAC Vorbis LYRICS）；M4A/Ogg 等格式只保存偏移，不重写容器。搜索拼音依赖 `pinyin-pro`，索引在扫描时生成并随曲库缓存。
 
 ## 播放宿主与后台播放
 
@@ -115,7 +126,11 @@ patch 的 `config` 是首次启动的种子：
 
 ## 已知限制
 
-- 收藏尚未实现（播放列表与统计已支持）。
+- 歌词写回仅支持 MP3 / FLAC；其他格式只保存偏移。写回会重写整个标签块，建议先备份（插件会自动生成 `<文件>.lyrics.bak`）。
+- 队列编辑为按钮式（上移 / 下移 / 移除 / 清空），暂不支持拖拽排序。
+- 多标签页主控切换后，新主控不会自动开始播放（避免浏览器自动播放拦截）。
+- 搜索历史存在 `localStorage`；桌面版每次启动端口不同、origin 会变，历史可能不跨启动保留。
+- 收藏尚未实现云同步/多端同步（纯本地文件）。
 - m4a 的文本标签可读，内嵌封面暂不解析（封面支持 mp3 / flac）。
 - 扫描缓存 30 秒；文件变化后点「重新扫描」强制刷新。
 - 播放依赖浏览器的 `<audio>`：DSH 的 Web GUI 在 `http://127.0.0.1` 下可用；远程访问（非回环）会返回 403。