NetEase + Discogs Sync
approvedby meowphy & Fable
Sync NetEase Cloud Music and Discogs collections into notes with metadata, lyrics and tracklists, deduplicated by ID. - This plugin has not been manually reviewed by Obsidian staff.
本插件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。
安装
手动安装
- 从 Releases 下载
main.js、manifest.json、styles.css - 放进你的 vault：
<vault>/.obsidian/plugins/netease-sync/ - 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 每张要补详情），之后有缓存就快。
设置项
路径
| 设置 | 说明 |
|---|---|
| 缓存目录 | MusicLyricApp cache 文件夹绝对路径（vault 外） |
| 输出目录 | 网易云歌曲笔记位置（vault 内相对路径） |
| 模板文件 | 网易云模板 .md（输入即搜索）；留空用内置模板 |
| Discogs 输出目录 | 唱片笔记位置（与网易云分开） |
| Discogs 模板文件 | Discogs 模板 .md；留空用内置模板 |
API
| 设置 | 说明 |
|---|---|
| Last.fm API Key | 查流派/地区用，密码框存储 |
| 启用 Last.fm 流派查询 | 关掉则跳过，genre/region 留空 |
| Discogs Token | 拉取 collection 用，密码框存储 |
同步选项
| 设置 | 说明 |
|---|---|
| 去重 | 按 ID 跳过已存在笔记 |
| 覆盖已存在 | 去重命中时：关=跳过；开=只更新派生字段，保留手填字段 |
| 网易云请求间隔 | 礼貌限速（ms），默认 400 |
| 流派数量上限 | 默认 6 |
| 下载封面到本地 | 关=在线 URL；开=下载图片到下方目录，离线可看 |
| 封面本地目录 | 下载封面的存放位置（vault 内相对路径） |
按钮：同步网易云、同步 Discogs、清空增强缓存。
自定义模板
留空对应的「模板文件」用内置模板；要自定义，新建一个 .md，用占位符，再在设置里搜索选中它。
📁 两个内置模板的完整文件放在仓库的
templates/目录：templates/netease.md、templates/discogs.md。可直接复制到 vault 里改。
通用占位符
| 占位符 | 内容 | 类型 |
|---|---|---|
{{title}} | 标题 | 标量 |
{{artist}} | 艺术家（逗号分隔） | 标量 |
{{year}} | 年份 | 标量 |
{{cover}} | 封面（URL 或本地路径） | 标量 |
{{coverEmbed}} | 封面嵌入语法（在线出 ，本地出 ![[path]]） | 标量 |
{{source}} | 来源（netease / discogs） | 标量 |
{{tags}} | 标签 | 列表 |
{{dateAdded}} | 生成日期 | 标量 |
网易云专用
| 占位符 | 内容 | 类型 |
|---|---|---|
{{aliases}} | 歌曲译名/别名 | 列表 |
{{datePublished}} | 发行日期 | 标量 |
{{album}} | 专辑 | 标量 |
{{duration}} | 时长（m:ss） | 标量 |
{{genre}} | 流派（Last.fm） | 列表 |
{{region}} | 地区（单个中文） | 标量 |
{{neteaseId}} | 网易云歌曲 ID（去重键） | 标量 |
{{url}} | 网易云链接 | 标量 |
{{lyrics}} | 交错双语歌词块 | 特殊（多行） |
Discogs 专用
| 占位符 | 内容 | 类型 |
|---|---|---|
{{released}} | 精确发行日（2009-11-00） | 标量 |
{{releasedFormatted}} | 易读发行日（Nov 2009） | 标量 |
{{country}} | 发行国 | 标量 |
{{discogsReleaseId}} | release ID（去重键） | 标量 |
{{catalogNumber}} | 唱片编号 | 标量 |
{{barcode}} | 条码 | 标量 |
{{label}} | 厂牌 | 标量 |
{{format}} | 载体（Vinyl, LP, Album） | 标量 |
{{formatQuantity}} | 碟片数 | 标量 |
{{weight}} | 克重 | 标量 |
{{genre}} | 流派 | 列表 |
{{styles}} | 风格（更细） | 列表 |
{{discogsRating}} | Discogs 个人评分（0 视为空） | 标量 |
{{discogsDateAdded}} | 收藏日期 | 标量 |
{{url}} | Discogs 链接 | 标量 |
{{notes}} | 版本说明 | 标量（多行） |
{{tracklist}} | 曲目表（编号+曲名+时长） | 标量（多行） |
{{credits}} | 制作人员 | 标量（多行） |
{{videos}} | MV 视频链接 | 标量（多行） |
{{communityStats}} | 社区数据表格（拥有/想要/均分） | 标量（多行） |
列表字段的渲染规则
{{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，引擎/去重/模板/状态面板全复用。
数据来源（每个字段从哪来）
所有数据都来自下面几个公开接口，插件只做读取和拼装，不改写源站数据。
网易云
| 数据 | 来源 | 说明 |
|---|---|---|
| 歌名/歌手/专辑/时长/发行日/封面 URL | MusicLyricApp 本地缓存 cache\*.json | MusicLyricApp 抓好的 SongVo；插件只读本地文件 |
| 歌词 / 翻译歌词 | 同上 LyricVo | 带时间戳，交错渲染 |
| 歌曲译名/别名 | https://music.163.com/api/song/detail?ids=[id] | 需 Referer: https://music.163.com 头；取 alias + transName |
| 流派 / 地区 | https://ws.audioscrobbler.com/2.0/?method=artist.getTopTags | Last.fm，按主歌手查 tags，去噪 + 地区归一为中文 |
- 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
| 数据 | 来源 | 说明 |
|---|---|---|
| 用户名（自动识别） | https://api.discogs.com/oauth/identity | 用 token 换当前登录用户名 |
| 收藏列表（标题/艺术家/年/厂牌/编号/载体/流派/风格/封面/你的评分/收藏日） | https://api.discogs.com/users/{用户名}/collection/folders/0/releases | 分页拉取整个 collection（folder 0 = All），basic_information 字段 |
| 详情（发行国/精确发行日/版本说明/曲目/条码/碟数/克重/制作人/社区数据/视频） | https://api.discogs.com/releases/{release_id} | 逐张请求补全 |
- 鉴权头：
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
For plugin developers
Search results and similarity scores are powered by semantic analysis of your plugin's README. If your plugin isn't appearing for searches you'd expect, try updating your README to clearly describe your plugin's purpose, features, and use cases.