本插件100%ai生成，不含任何人工。 在此感谢我的ai伙伴：fable。 kisskiss 只有中文，因为外国人不用网易云。我的思路是：数字歌曲由网易云管理（用qq搜狗的同样可以使用musiclyricapp。只不过可能有点不同，要么自己修改，要么把歌曲批量导入网易云的一个歌单）。实体收藏使用discogs。两条路走，对我而言目前足够。 不懂的地方可以把此文档交给ai看。

English summary

The full documentation below is in Chinese, because this plugin is built around NetEase Cloud Music (a Chinese streaming service). If you don't use NetEase, the Discogs half still works standalone. This summary is for reviewers and non-Chinese readers.

Music Sync for Obsidian turns the songs you've listened to and the physical records you own into notes — one note per song / one note per record. Metadata, lyrics and tracklists only; no audio is downloaded.

Two sources, one engine:

• NetEase Cloud Music — reads the local cache of MusicLyricApp (metadata + timestamped lyrics); genre/region come from Last.fm; translated titles from NetEase's official endpoint.
• Discogs — uses the official API + a personal token to pull your entire collection (label / catalog no. / format / tracklist / country / community stats / videos, and more).

Notes are rendered from a swappable .md template and deduplicated by ID (netease_id / discogs_release_id). Covers can stay as online URLs or be downloaded locally. A live status panel shows progress and can be stopped anytime.

Desktop only (NetEase sync reads a local cache directory outside the vault). Your Last.fm key / Discogs token stay in local data.json — never written into notes, never shipped. The plugin uploads nothing; network calls are limited to Last.fm, NetEase title lookup, and Discogs.

See the placeholders, data sources and privacy sections below (Chinese) for full detail.

NetEase + Discogs Sync

把你听过的歌和收藏的实体唱片，以「一歌一笔记 / 一张唱片一笔记」的形式同步进 Obsidian —— 只要元数据、歌词、曲目，不下载音频。

两个来源，一套引擎：

• 网易云音乐：从 MusicLyricApp 的本地缓存读取（元数据 + 带时间戳歌词），流派/地区来自 Last.fm，译名来自网易云官方接口。
• Discogs：用官方 API + token 自动拉取你的整个 collection（实体唱片：厂牌/编号/载体/曲目/发行国/社区数据/视频等）。

生成的笔记按模板渲染，按 ID 去重。

仅桌面端（网易云同步需读取 vault 外的本地缓存目录）。

它能做什么

网易云：

• 读取 MusicLyricApp 的 JSON 缓存 → 生成歌曲笔记
• 交错双语歌词：原文一行（带时间戳）+ 翻译一行（带同一时间戳），和 .lrc 一致
• Last.fm 流派/地区：按主歌手查询 artist.getTopTags，去噪 + 归一地区为中文
• 歌曲译名来自网易云官方接口

Discogs：

• token 自动拉取整个 collection（无需手动导出 CSV）
• 逐张补详情：曲目表、发行国、精确发行日、版本说明、条码、碟数/克重、制作人、社区数据（拥有/想要/均分）、MV 视频链接

通用：

• 可换模板：用你自己的 .md 模板文件，改样式不改代码；网易云和 Discogs 各有独立模板
• 去重：按 ID（netease_id / discogs_release_id）跳过已生成的笔记；可选「覆盖模式」只更新派生字段，保留你手填的评分/标签/评论
• 封面：默认用在线 URL；可开启下载到本地
• 同步状态面板：实时进度条 + 随时停止
• 增强数据（流派/译名）本地缓存，重复同步不重复请求 API

准备工作

网易云：装 MusicLyricApp 并缓存歌曲

下载 MusicLyricApp，搜索/导入你的歌单和歌曲。它会把每首歌的元数据 + 歌词缓存成 JSON，默认在：

C:\Users\<你>\AppData\Roaming\MusicLyricApp\cache\

本插件只读这个目录，不联网抓网易云，天然绕过反爬。

网易云：（可选）申请 Last.fm API Key

要自动填流派/地区，需要一个免费的 Last.fm key：https://www.last.fm/api/account/create 不填也能用，只是 genre / region 会留空。

Discogs：申请 personal token

登录 Discogs → Settings → Developers → Generate token：https://www.discogs.com/settings/developers 把 token 填进插件设置即可，插件会用它自动识别你的用户名并拉取 collection。

安装

手动安装

1. 从 Releases 下载 main.js、manifest.json、styles.css
2. 放进你的 vault：<vault>/.obsidian/plugins/netease-sync/
3. Obsidian → 设置 → 第三方插件 → 刷新 → 启用

从源码构建

git clone <this-repo>
cd netease-sync
npm install
npm run build   # 产出 main.js

使用

网易云： 填好缓存目录 + 输出目录（+ 可选 Last.fm key），点左侧栏 🎵 图标或命令「同步网易云音乐」。

Discogs： 填好 Discogs Token + Discogs 输出目录，点 💿 图标或命令「同步 Discogs 唱片」。

同步时弹出状态面板：实时进度、当前处理项、新建/更新/跳过计数，可随时点「停止」。

第一次跑较慢（网易云要查 Last.fm + 译名；Discogs 每张要补详情），之后有缓存就快。

设置项

路径

API

同步选项

按钮：同步网易云、同步 Discogs、清空增强缓存。

自定义模板

留空对应的「模板文件」用内置模板；要自定义，新建一个 .md，用占位符，再在设置里搜索选中它。

📁 两个内置模板的完整文件放在仓库的 templates/ 目录：templates/netease.md、templates/discogs.md。可直接复制到 vault 里改。

通用占位符

网易云专用

Discogs 专用

列表字段的渲染规则

{{aliases}} {{genre}} {{styles}} {{tags}} 是列表，渲染取决于摆放位置：

• 独占一行（前面是 key:）→ YAML 多行列表；值为空则整行删除
• 行内（和别的文字同行）→ 逗号分隔

标量字段含 YAML 特殊字符（:、#、引号、逗号、前导 - 等）会自动加引号转义。

内置模板已包含上述全部占位符。{{idFieldName}} 为内部保留（渲染成当前来源的 ID 键名），一般不需手动使用。

工作原理

网易云 cache (*.json)          Discogs collection (API)
        │                              │
        └──────────┬───────────────────┘
                   ▼
             RawTrack（统一结构）
                   │  enrich：网易云→Last.fm+译名；Discogs→逐张补详情
                   ▼
             RenderModel  ──►  模板引擎（内置或你的 .md）  ──►  笔记.md
                   │  按 ID 去重
                   ▼
                输出目录

三层解耦：来源（读缓存 / 拉 API）/ 增强（补数据）/ 渲染（套模板）。加新来源只需实现一个 MusicSource，引擎/去重/模板/状态面板全复用。

数据来源（每个字段从哪来）

所有数据都来自下面几个公开接口，插件只做读取和拼装，不改写源站数据。

网易云

• MusicLyricApp：https://github.com/jitwxs/163MusicLyrics
• Last.fm API 文档：https://www.last.fm/api/show/artist.getTopTags
• 申请 Last.fm key：https://www.last.fm/api/account/create

Discogs

• 鉴权头：Authorization: Discogs token=<你的token>（token 只存本地）
• Discogs API 文档：https://www.discogs.com/developers
• 申请 token：https://www.discogs.com/settings/developers

隐私与安全

• 你的 Last.fm key / Discogs token 只存在本地 data.json，不会写进笔记，不随插件发布。
• 插件不上传任何数据；网络请求仅限查 Last.fm 流派、网易云译名、Discogs collection/详情。

致谢

• MusicLyricApp —— 网易云元数据 + 歌词缓存来源
• Last.fm —— 流派/地区
• Discogs —— 实体唱片元数据
• Obsidian

License

MIT