Aliboder/dsh-music-panel

---

Screenshots · 截图

More screenshots · 更多截图

Statistics · 播放统计	Instrumental · 纯音乐播放页

Settings · 设置	Context menu · 右键菜单

Batch actions · 批量操作	Metadata matching · 在线匹配

Light theme · 浅色	Dark theme · 深色

---

中文

为什么是 dsh-music-panel

大多数音乐插件只做“能播”。dsh-music-panel 想做的是一台真正属于 DSH 的播放器：本地曲库、在线平台、歌词、缓存、元数据和播放统计共享同一套界面与队列，不需要在应用之间来回切换。

功能

本地曲库

• 多根目录扫描，可配置子文件夹深度；支持 MP3 / FLAC / M4A / AAC / OGG / OPUS / WAV / AIFF / WMA / APE。
• 歌曲 / 专辑 / 歌手 / 文件夹 / 喜欢 / 统计多种视图；按目录聚合并可单独隐藏。
• 列表循环、单曲循环、顺序播放、随机、上一首 / 下一首、进度拖动、音量与静音。
• 记忆上次播放曲目与进度，支持每首歌断点续播。
• 空格播放 / 暂停，Ctrl / ⌘ + ← / → 切歌，/ 聚焦搜索。

在线音乐

• 顶栏一键切换本地音乐、网易云、QQ 音乐、酷狗；播放队列跨来源保留。
• 扫码登录后读取云端歌单、喜欢、最近播放；未登录也可播放平台免费曲目。
• 歌单歌曲缓存：按 provider + playlistId 缓存 60 秒，导航项 hover / focus 预取；切回时先显示缓存，过期后后台校准。
• 在线歌单排序：平台顺序 / 名称 / 歌曲数，偏好保存在本机。
• 账号资料：设置 → 在线显示官方平台图标、当前昵称与头像；头像通过本机代理加载。
• VIP 识别：根据当前登录账号判断可播放性，VIP 曲目显示金色徽标。
• 音频缓存：边播边写、播完落盘，默认上限 10 GB、LRU 淘汰；设置 → 缓存可查看全部缓存歌曲并清空。
• 音量均衡：浏览器内置 EBU R128（BS.1770）分析，按曲目自动调整增益，不依赖 ffmpeg；首次分析后缓存结果。
• 在线歌词与翻译：网易云 trans、QQ 加密翻译流、酷狗 KRC 内嵌译文。

歌词、元数据与整理

• 内嵌歌词与 .lrc，播放页逐行高亮、翻译、字号 / 粗细 / 模糊 / 对齐可调、±0.5s 偏移。
• 在线歌词搜索并写回内嵌歌词，写前自动备份。
• 在线匹配网易云 / QQ 音乐 / iTunes / MusicBrainz 元数据，支持整曲或单字段匹配。
• 编辑标题、艺术家、专辑、年份、音轨号、碟号、风格、专辑艺术家、作曲、作词、注释、歌词。
• 替换封面、检测重复、批量收藏 / 加入歌单 / 编辑 / 删除到回收站。
• 删除操作进入插件回收站，可按原路径恢复，不是永久删除。

安装

要求：DSH Web / Desktop。 插件需要浏览器载体播放音频，并使用宿主已配置的网络与存储。

方式一：插件市场（推荐）

在 DSH 的 插件市场 搜索 dsh-music-panel，或让 Agent 执行：

plugin_manager install_bundle dsh-music-panel

安装后完整重启 DSH，左侧栏出现音乐图标。

方式二：npm

在 DSH profile 目录下：

pnpm add dsh-music-panel

然后重启 DSH。npm 包：https://www.npmjs.com/package/dsh-music-panel

快速开始

本地音乐

1. 点击左侧栏音乐图标打开面板。
2. 右上角齿轮 → 音乐库，添加一个或多个音乐文件夹。
3. 扫描完成后双击歌曲，或点「播放全部」。

在线音乐

1. 顶栏切到网易云 / QQ 音乐 / 酷狗。
2. 首次使用：齿轮 → 在线，点对应平台「登录」，用手机 App 扫码确认。
3. 直接点导航里的云端歌单开始播放；播放过的歌曲会自动进入音频缓存。
4. 需要清理时到 设置 → 缓存 查看或清空。

隐私

• 全部逻辑在本机运行；登录 Cookie / token 只写入 ~/.dsh/music/providers.json（权限 0600）。
• 缓存与播放记录位于 ~/.dsh/music/，可随时清理。
• 客户端不向外部域名发请求：在线搜索、取链、歌词、封面均由 Host 发起并同源代理。

兼容与限制

• 仅支持 DSH Web / Desktop 宿主。
• 在线平台使用公开的非官方接口，可能失效、限流或改版；失败时会在界面提示，不影响本地播放。
• VIP / 付费曲目是否可播取决于当前登录账号，界面会显示金色徽标。
• 平台图标使用各平台 App Store 官方应用图标，仅用于平台识别，商标归各平台所有。

开发

npm test            # 19 test files
npm run check       # syntax + manifest checks
npm run pack:check  # package self-check

• Host：index.js + lib/**，提供 /music/* HTTP API。
• Web：client.js 由 src/** 分片构建，单文件、零运行时依赖，只依赖宿主注入的 react。

node scripts/build-client.mjs          # rebuild client.js
node scripts/build-client.mjs --check  # verify src and client.js agree

更多规范见 主题与组件规范 与 UI review。

License

MIT © Aliboder

---

English

Why dsh-music-panel

Most music plugins stop at “it plays”. dsh-music-panel is built as a real music player for DSH: local files, online providers, lyrics, caching, metadata, and listening stats share one interface and one queue — no app switching.

Features

Local library

• Multi-root scanning with configurable folder depth; MP3 / FLAC / M4A / AAC / OGG / OPUS / WAV / AIFF / WMA / APE.
• Songs, albums, artists, folders, favorites, and statistics views; folder grouping with per-folder hiding.
• Repeat modes, shuffle, previous / next, seek, volume, and mute.
• Restores the last track and position; optional per-track resume.
• Space play/pause, Ctrl / ⌘ + ← / → previous/next, / focus search.

Online music

• Switch between local, NetEase, QQ Music, and KuGou from the top bar; the queue is shared across sources.
• QR sign-in for cloud playlists, favorites, and recent plays; free tracks work without signing in.
• Playlist cache: 60-second per-playlist cache with hover/focus prefetch. Reopening shows cached tracks immediately, then revalidates in the background.
• Playlist sorting: platform order / name / track count, persisted locally.
• Account profiles: official provider icons, nickname, and avatar in Settings → Online; avatars are proxied by the Host.
• VIP awareness: playability follows the signed-in account; VIP tracks are marked.
• Audio cache: write-while-playing, default 10 GB with LRU eviction; Settings → Cache lists every cached track across providers.
• Volume leveling: built-in EBU R128 / BS.1770 analysis with per-track gain, no ffmpeg required; results are cached.
• Online lyrics and translations for all three providers.

Lyrics, metadata, and cleanup

• Embedded lyrics and .lrc; line highlighting, translation, typography controls, alignment, and ±0.5s offset.
• Online lyric search with backup before writing.
• Metadata matching via NetEase / QQ Music / iTunes / MusicBrainz, whole-track or per-field.
• Edit title, artist, album, year, track/disc number, genre, album artist, composer, lyricist, comment, and lyrics.
• Cover replacement, duplicate detection, batch favorite / add-to-playlist / edit / trash.
• Deletions go to the plugin trash and can be restored by original path.

Install

Requires DSH Web / Desktop. A browser runtime is needed for playback.

Plugin marketplace (recommended)

Search for dsh-music-panel in DSH, or run:

plugin_manager install_bundle dsh-music-panel

Then restart DSH completely. A music icon appears in the sidebar.

npm

From the DSH profile directory:

pnpm add dsh-music-panel

Then restart DSH. Package: https://www.npmjs.com/package/dsh-music-panel

Quick start

1. Open the music panel from the sidebar.
2. Settings → Library, add one or more music folders.
3. Double-click a track, or press “Play all”.
4. For online music, switch to a provider and sign in via QR in Settings → Online.
5. Open a cloud playlist from the navigation; played tracks are cached automatically.

Privacy

• Everything runs locally. Cookies and tokens are stored only in ~/.dsh/music/providers.json (mode 0600).
• Cache and history live under ~/.dsh/music/ and can be cleared at any time.
• The browser side never calls external domains: search, stream resolution, lyrics, and covers are proxied by the Host.

Limitations

• DSH Web / Desktop only.
• Online providers use public, unofficial APIs; they may change, throttle, or break. Failures are surfaced in the UI and do not affect local playback.
• VIP / paid track availability depends on the signed-in account and is marked in the UI.
• Provider icons come from the official App Store artwork and are used only for identification; trademarks belong to their owners.

Development

npm test
npm run check
npm run pack:check

• Host: index.js + lib/**, exposing /music/* HTTP routes.
• Web: client.js is built from src/** as a single CJS module with no runtime dependencies beyond the host-provided react.

node scripts/build-client.mjs
node scripts/build-client.mjs --check

See theme guidelines and UI review for conventions.

License

MIT © Aliboder