dsh-music-panel 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # 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
+
+### 功能
+
+- 记忆播放：启动 / 刷新后恢复上次的队列、当前曲目与播放位置（默认暂停，点 ▶ 继续）；设置里可开「恢复后自动播放」与「每首歌记住播放位置」
+- 播放次数按 Last.fm / MusicBee 规则记录：曲目 > 30 秒，且播放到一半或 4 分钟（先到为准）才计一次，不再每次切歌就 +1
+- 有效播放时长：只累计播放中自然前进的时间，拖动进度条不计，单次不足 30 秒的片段不计
+- 统计页：主面板新增「统计」tab，支持最近一周 / 最近一月 / 全部时间，按时长 / 次数 / 最近排序，显示累计时长、播放次数、最近播放与汇总
+- 新增接口：`GET/POST /music/state`、`POST /music/playback`、`GET/POST /music/position`、`GET /music/stats`
+- 设置面板新增「播放」标签页
+
+### 数据
+
+- `stats.json` 扩展 `playSeconds`、`lastPlayedAt`、`lastPositionSec` 与最近 31 天的每日分桶；旧文件自动兼容
+- 新增 `<DSH_HOME>/music/playback.json` 保存上次播放状态
+
 ## 0.1.0
 
 首个公开版本。

package/README.md

@@ -23,10 +23,17 @@ DeepSeek Harness 的本地音乐插件：左侧栏一个音符入口，点开是
 - **歌曲列表**：封面缩略图、标题、歌手（带 CD 徽标）、专辑、时长、采样率；当前曲高亮。
 - **播放控制**：列表循环 / 单曲循环 / 不循环，随机播放，上一首、下一首、进度拖动、音量与静音。
 - **播放队列**：底部「队列」按钮展开当前队列，点击任意条目跳转；「更多」里显示格式 / 码率 / 采样率，可复制文件路径。
+- **记忆播放**：启动 / 刷新后恢复上次的队列、当前曲目与播放位置（默认停在暂停，点 ▶ 继续）；设置里可选「恢复后自动播放」和「每首歌记住播放位置」。
+- **统计**：主面板「统计」页按最近一周 / 最近一月 / 全部时间查看每首歌的累计播放时长、播放次数与最近播放，可按时长 / 次数 / 最近排序。播放次数按 Last.fm 规则（曲目 > 30 秒且播放到一半或 4 分钟）记录，播放时长只累计真正在播放的时间。
 - **列表操作**：搜索、排序（标题 / 文件名 / 专辑 / 艺术家 / 大小 / 年份 / 文件夹 / 播放次数 / 时长 / 修改时间 / 添加时间，点击同项切换升降序）、多选后「播放选中」或加入播放列表、清空列表。
-- **设置面板**：主面板右上角齿轮打开，含「外观 / 歌词 / 音乐库」三个标签页：外观调整迷你浮窗与圆形封面显示，歌词调整来源顺序、对齐、字号、翻译与状态栏歌词，音乐库管理音乐文件夹与子文件夹深度（保存后主面板自动重新扫描）。
+- **设置面板**：主面板右上角齿轮打开，含「外观 / 歌词 / 音乐库 / 播放」四个标签页：外观调整迷你浮窗与圆形封面显示，歌词调整来源顺序、对齐、字号、翻译与状态栏歌词，音乐库管理音乐文件夹与子文件夹深度（保存后主面板自动重新扫描），播放控制启动恢复、自动播放与每首歌断点。
 - **外观设置**：迷你浮窗（右下角可拖动、记忆位置）、播放页圆形封面 / 黑胶底盘 / 封面旋转。
 - **歌词设置**：歌词来源顺序（内嵌 / 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`。支持一行多时间戳、元数据标签、原文+翻译同时间戳合并。
@@ -67,6 +74,15 @@ plugin_manager install_bundle D:/SystemFiles/Documents/Project/DSH/plugins/dsh-m
 | PATCH | `/music/playlists/:id` | 重命名 / 加曲 / 删曲：`{ name?, add?: string[], remove?: string[] }` |
 | DELETE | `/music/playlists/:id` | 删除播放列表 |
 | POST | `/music/play` | 记一次播放，body `{ path }` |
+| GET | `/music/state` | 上次播放状态（队列 / 索引 / 位置 / 循环 / 顺序） |
+| POST | `/music/state` | 保存上次播放状态，body `{ queue, index, positionSec, durationSec, loop, order }` |
+| 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 |
 
 `stream` / `cover` 的 `path` 会 `realpath` 后重新校验是否位于已配置的根目录内，越界一律 404。
@@ -87,6 +103,20 @@ patch 的 `config` 是首次启动的种子：
 
 用户在设置面板的音乐库标签页保存后，以 `<DSH_HOME>/music/settings.json` 为准（`extensions: []` 表示使用全部支持的格式）。播放次数与首次入库时间存在 `<DSH_HOME>/music/stats.json`。
 
+## 播放状态与统计
+
+两个文件都在 `<DSH_HOME>/music/`：
+
+- `playback.json`：上次播放的队列（最多 500 条）、当前索引、位置、循环 / 顺序，用于启动恢复。
+- `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`，索引在扫描时生成并随曲库缓存。
+
 ## 播放宿主与后台播放
 
 - `<audio>` 元素挂在宿主的 `shell.overlay`（常驻浮层）里，主面板切走、会话切换都不会卸载它，所以播放不中断；播放状态由 `client.js` 里的引擎单例（`window.__dshMusicPlayer`）持有，模块被 HMR 重新执行也复用同一实例。
@@ -96,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。