README file from
GithubiJipu(爱记谱)—— Obsidian 插件
在 Obsidian 笔记里写 ```jps 代码块(适合单行 / 片段乐谱),或把 .jps 存成文件再链接 / 内联嵌入,
都能把 .jps 简谱脚本渲染为可视化简谱(SVG),并可试听;
也可以点左侧栏图标(或在库里打开 .jps)用插件内嵌的完整 iJipu 编辑器编辑谱面。
渲染引擎复用 @ijipu/engine(与 iJipu 应用一致),设置项与 iJipu 一脉传承。
官网:https://ijipu.pages.dev
码即成,谱自现。
安装 / Installation
桌面端与手机端都支持(Windows / macOS / Linux / Android / iOS;
manifest.json的isDesktopOnly: false)。两端的差别只在"内嵌的完整 iJipu 编辑器": 它需要一个本机服务(用到只有桌面版 Obsidian 才提供的 Node.js 接口),因此桌面端才提供; 手机端改为用宿主自己的编辑器打开
.jps源码(带 iJipu 那套语法着色与语法错误提示), 点「看谱」即回到谱面预览 —— 渲染、试听、格式化、```jps代码块在两端完全一致。
从社区目录安装(推荐)
- 打开 Obsidian → 设置 → 第三方插件 → 浏览;
- 搜索 iJipu,点安装 → 启用。
手动安装
- 到 Releases 下载
main.js、manifest.json、styles.css; - 放到
<你的库>/.obsidian/plugins/ijipu/(目录名必须是ijipu,与manifest.json的id一致); - 在 设置 → 第三方插件 里启用 iJipu(看不到就重开 Obsidian)。
用法 / Usage
在任意笔记里写一个 jps 代码块(这仍是推荐用法之一,尤其适合单行 / 片段乐谱 ——
几句谱直接写在笔记里,不必为它单独建一个 .jps 文件;两种用法的取舍见下文「代码块还是 .jps 文件?」):
```jps
V: 1.0
B: 两只老虎
Z: 法国童谣 词曲
D: C
P: 4/4
J: 120
Q: 1 2 3 1 | 1 2 3 1 | 3 4 5 - | 3 4 5 - |
C: 两只老虎 两只老虎 跑得快 跑得快
```
- 渲染区显示简谱(多页自动分页),右上角有 ▶ 试听 / ⏹ 停止(Web Audio 合成,无需音频文件)。
- 语法解析失败会显示错误信息,不阻断正文。
- 默认「无空白」显示:默认的「谱面」视图裁到真实内容包围盒——只显示有墨迹的部分(整页白底、页边距内的空白都不显示),四周只留 2px。
- 操作按钮默认隐藏:工具条浮在谱面块外侧左上角(块正上方、左缘对齐,不压谱面),鼠标移到谱面块上才淡入 —— 于是 Obsidian「导出为 PDF / 打印」不会把操作界面带进成果;触屏设备常显。
- 编辑源码:谱面块右上角的
</>(与 Obsidian 自己给块挂的「编辑此块」同款位置与外观)—— 点它切回笔记源码(阅读视图会先切到实时预览)并把光标放进这个代码块,用 Obsidian 自带编辑器改(原生语法高亮、撤销栈、与其它代码块一致);光标移出该块即回到谱面。不再在预览里另开一个 textarea。 - 显示模式(三个图标按钮):整页(完整一页含页边距)/ 满宽(撑满笔记宽度)/ 谱面(裁掉页边距、只显示有墨迹的部分,默认);悬停有文字说明。
- 排版(田字格图标,与 iJipu 应用顶栏同一形状):显示/隐藏排版辅助虚线——显示后直接拖动虚线即可调整版面,松手即写入该谱源码的
# jps-config行(与 iJipu 一致,拖动过程只预览不落盘)。为能看见页边距,开启时会自动切到「整页」视图,关闭时恢复原视图。 - 设置(滑杆图标):打开对话框按字段精确设值(字体/字号/行距/渲染开关等不可拖动项),可按页签逐组改(页面 / 字体 / 行距 / 渲染 + 说明,与「设置 → iJipu」同款),并有「保存到谱面」(写
# jps-config)、「随谱固化(分享用)」、「保存为插件默认」三个去向。 对话框顶部会列出谱面自带设置 N 项(来自源码# jps-config)——一眼看出这份谱自己写了哪些设置。
可拖动的辅助虚线
| 虚线 | 拖动调整的字段 |
|---|---|
| 上 / 下 / 左 / 右 页边距 | margin_top / margin_bottom / margin_left / margin_right |
| 描述头区下沿线 | descAreaH(描述头内容区高;另有浅色中线为纯标注) |
| 第 1 行曲部线 | body_margin_top(曲部与描述头间距) |
| 多声部块内第 2+ 声部行线 | height_shengbu(声部行间距) |
| 其他曲部行线 | 上一行有歌词 → height_ciqu_lyric;否则 → height_ciqu |
| 歌词行线 | 第 1 行 → height_quci(曲-词间距);后续行 → height_cici(词-词间距) |
.jps 文件与嵌入
插件启用后,Obsidian 会把 .jps 识别为简谱文件:
| 用法 | 效果 |
|---|---|
[[我的谱.jps]] |
链接可直接点开 → 用简谱视图打开(试听 / 显示模式 / 排版 / ⇄ 源码编辑),不再提示"无法打开" |
![[我的谱.jps]] |
在笔记里内联渲染该谱(紧凑工具条,可试听);排版保存直接改写该 .jps 文件 |
文件树里双击 xxx.jps |
同上打开简谱视图;工具栏「✎ 源码」可切到纯文本编辑(改动自动保存,Ctrl+S 立即保存) |
| 文件树里右键文件夹 → 「新建 JPS 文件」 | 在该文件夹内新建一份 **.jps(默认模板内容)**并直接打开;重名时自动取 未命名.jps → 未命名 1.jps → …(与 Obsidian 自带「新建笔记」同款命名) |
点击 [[谱名.jps]](文件还不存在) |
按默认模板自动创建 谱名.jps(不是 谱名.jps.md)并打开:建在链接所在笔记的同级目录下;[[子/谱.jps]] 会连子目录一起建,[[/谱库/我的谱.jps]] 从库根算 |
链接支持 #子标题 与 |别名 写法(![[谱.jps|我的谱]]、![[谱.jps#第2段]]);找不到文件时会在原位给出提示而不是留空白。
代码块还是 .jps 文件?(两者都长期保留)
```jps 代码块不是过渡用法,它有一个 .jps 文件做不到的场景:
| 场景 | 该用哪个 | 原因 |
|---|---|---|
单行 / 片段乐谱(例:笔记里只想展示 1 2 3 1 | 3 4 5 - | 这一句) |
代码块 | 十几字节的源码直接写在笔记里,不用为一句谱单独建个文件 |
| 讲解 / 教程:一句谱 + 一段说明穿插 | 代码块 | 源码与讲解同处一篇笔记,复制、改写、对照都顺手 |
| 一个笔记里多个片段、各自调排版试效果 | 代码块 | 同一份源码可复制多份;嵌 .jps 只能"多个文件" |
| 完整的一首曲子(要长期维护、反复编辑) | .jps 文件 |
有独立文件、桌面端点开就进完整编辑器(内嵌 iJipu;手机端先看谱面预览,点工具条最右的「编辑」进)、可被多篇笔记引用 |
| 一处维护、多处引用 | .jps 文件 |
改文件即处处生效;代码块是各笔记各一份 |
库里已有大量 ```jps 笔记 |
保持不动 | 代码块路径继续维护,不会失效 |
两者互不影响:
.jps文件与```jps代码块都只读谱面自带的# jps-config(见下节)。
设置优先级
引擎默认(defaultPageConfig) < 插件设置(设置面板里的全局默认) < 谱面源码内的 # jps-config 行
设置写在哪:就写在谱面里 —— 用一行
# jps-config:{…}携带这份谱的设置(点工具条的「设置」按钮改,插件会自动写回这一行)。 这样每一份谱都是自包含的:把源码(或整个.jps文件)复制给别人,看到的排版一致。 ⚠ 笔记 frontmatter(ijipu_*)那一层已删除(0.32.0,用户决定):它对.jps文件用不上、 对"一个笔记里多个```jps块"又太粗(笔记级),且不随谱走;谱内# jps-config可逐块写。
-
谱面源码内的
# jps-config:{...}优先级最高(与 iJipu 应用一致:"每首谱用自己的设置")。iJipu 点「保存设置」时会把配置写进源码那一行,所以把 iJipu 里的 .jps 直接复制进 Obsidian,渲染结果与 iJipu 一致;插件设置只对源内没写的键生效。 -
差量写入:设置行只记录与「引擎默认值」不同的项(全部为默认时该行写
{})。 -
「保存到谱面」口径(用户 2026-10-15 定稿):遍历谱面原有的各项 —— 对话框里该项是默认值 ⇒ 从谱面删掉;随后把对话框里非默认的项全部写进谱面。⇒ 谱面里最终只留"非默认值",不看你在对话框里动没动过它(所以插件设置里的非默认项、以及"改回默认值"的项,都不会再出现"没保存 / 恢复原样")。原来那个语义重复的「随谱固化(分享用)」按钮已撤掉。
-
字体:候选项都是跨平台字体栈(末尾带兜底字体,如
'SimHei', sans-serif),换设备不会掉到不合适的默认字体;旧谱里的裸字体名读取时会自动补 fallback。 -
编辑器字体/字号不属于谱面设置(属本机偏好,在插件设置里调)——别人打开你的 .jps 不会被改;写进源码的
editorFont*旧键会被识别出来并提示"已不再随谱保存"。 -
预览工具条的「⚙ 设置」对话框里会列出「谱面自带设置 N 项」(源码
# jps-config写了哪几项、值是什么)。 -
插件设置的默认值体系与应用一致:本库默认层(
代码默认 ← 插件设置)被当作"应用里的代码默认值"看待 ⇒ 它不算"没随谱携带"(不会无端提示)。 -
插件设置面板每项即全局默认(谱面未自带设置时生效);改设置后打开中的谱面立刻重渲染。
-
设置面板按页签分组(
页面 / 字体 / 行距 / 渲染 / 音色库 / 说明),一屏只看一组、不必长距离滚动; 「说明」页签里写了"设置写在哪":谱面里的# jps-config(跟着谱走、可逐块写),以及用工具条「设置」按钮可视化改、自动写回。 -
收藏音色是分类流式列表(与 iJipu 应用「音色库」同一套 GM 14 类分类):按类折叠、每类可「选本组 / 消本组」, 顶部「全选 / 全消 / 反选 + 搜索」,右上角实时显示「已选 N / 128」。
-
注意「生效值」与「全局默认」是两层:谱面工具栏「⚙ 设置」里显示的是这一份谱的生效值 (含源码
# jps-config),与「设置 → iJipu」里的全局默认值不同是正常的; 在对话框里点「保存为插件默认」只记录你那次真正改动过的项(不会把某一份谱的源内值变成全库默认)。 -
改动即时生效:改谱面里的设置行、或改设置面板后,谱面立刻重渲染(无需重开笔记)。
谱内设置示例
D: C
P: 4/4
# jps-config:{"page":"A4_horizontal","note_size":15,"lianyinxian_type":1,"showInstrument":true}
Q: 1 2 3 4 |
手写时只需记住一条:键名 = 引擎
PageConfig的字段名(下表第三列那些名字,去掉反引号即可)。 数字与布尔可以写成字符串("15"、是/否、1/0);嵌套字段(segmentRowGap)写成一行映射{bz: 22, dsb: 22, tp: 14}。
设置键对照表(写进 # jps-config 用)
键 = iJipu 引擎
PageConfig字段名。boolean用true/false(也可写是/否、1/0),枚举用所给值。 一般不必手写:点工具条的「设置」按钮用图形界面改,插件会自动把差量写回那一行。
页面
| 设置项 | # jps-config 键 |
类型 | 取值 / 默认 |
|---|---|---|---|
| 纸张 | page |
枚举 | A4 / A5 / A4_horizontal / A5_horizontal(默认 A4) |
| 上边距 | margin_top |
数字 | 默认 40 |
| 下边距 | margin_bottom |
数字 | 默认 40 |
| 左边距 | margin_left |
数字 | 默认 50 |
| 右边距 | margin_right |
数字 | 默认 50 |
| 正文上间距 | body_margin_top |
数字 | 默认 20 |
| 描述头区高 | descAreaH |
数字 | 默认 80 |
| 作者两端对齐 | author_justify |
boolean | true / false(默认 true;多个 Z: 行时把最后一个空格前的标签按最长行拉齐) |
| 小节间距 | bar_gap |
数字 | 默认 0(设置面板未提供控件,仍可手写进 # jps-config) |
| 两端对齐最小小节数 | align_min_bars |
数字 | 默认 4 |
| 音符布局模式 | noteSpaceLayout |
枚举 | space(空间优先)/ duration(时值优先),默认 space |
| 显示小节计数 | showBarCount |
boolean | true / false(默认 true) |
| 序号间隔 | barCountInterval |
数字 | 默认 4(每隔几个小节显示一个方框序号) |
水印(adj965)
层序:曲谱(最上)→ 水印 → 背景;每页都画,且只显示在页面内的部分(走出页面的被裁掉)。 「显示比率」以页宽为 100%(图形宽度 = 页宽 × 比率,高度按原图比例);「位置」是元素中心相对页面中心的偏移(0,0 = 正中)。
在预览区直接调(
adj965d):打开工具条的「排版」后,Alt+滚轮 = 缩放该层(累计约 100px 一档)、Alt+Shift+滚轮 = 旋转、Alt+左键拖动 = 平移(按住Shift吸附居中); 水印与背景都可调时,谱面右下角的提示条里还有「调整对象」切换器。松手 / 停手约半秒后写进# jps-config。
| 设置项 | # jps-config 键 |
类型 | 取值 / 默认 |
|---|---|---|---|
| 启用水印 | wmEnabled |
boolean | 默认 false(须显式打开;勾上会写进谱面) |
| 水印类型 | wmType |
枚举 | text(文字)/ image(图形),默认 text |
| 水印文本 | wmText |
文本 | 默认「爱记谱・iJipu」(空则不画;可含换行) |
| 水印图形文件 | wmImage |
文本 | 默认空;相对这份 .jps 的路径,也可写 Obsidian 双链 [[图片.png]] 或 data: 内嵌 |
| 水印字号(文本) | wmSize |
数字 | 默认 22(pt,钳 6~400) |
| 水印显示比率(图形) | wmScale |
数字 | 默认 100(%,占页宽;钳 10~1000) |
| 水印旋转 | wmRotate |
数字 | 默认 -45(度,绕自身中心;钳 ±180) |
| 重复铺满 | wmRepeat |
boolean | 默认 false(true = 按行列间隔平铺满页面;网格以水印自身为基点,调位置或 Alt+拖动 时整片跟着走) |
| 平铺间隔 | wmRepeatGap |
数字 | 默认 300(%;空隙 = 水印自身尺寸 × 该值/100 ⇒ 300 时步进为自身 4 倍、100 时 2 倍) |
| 水印透明度 | wmOpacity |
数字 | 默认 15(0~100,100 = 不透明) |
| 水印位置 X | wmOffsetX |
数字 | 默认 0(pt,相对页面中心) |
| 水印位置 Y | wmOffsetY |
数字 | 默认 0(pt,相对页面中心) |
背景(adj965)
| 设置项 | # jps-config 键 |
类型 | 取值 / 默认 |
|---|---|---|---|
| 启用背景 | bgEnabled |
boolean | 默认 false(须显式打开;勾上会写进谱面) |
| 背景图形文件 | bgImage |
文本 | 默认空(空则不画);相对这份 .jps 的路径,也可写 [[图片.png]] 或 data: 内嵌 |
| 背景位置 X | bgOffsetX |
数字 | 默认 0(pt,相对页面中心) |
| 背景位置 Y | bgOffsetY |
数字 | 默认 0(pt,相对页面中心) |
| 背景显示比率 | bgScale |
数字 | 默认 100(%,占页宽;钳 10~1000) |
| 背景旋转 | bgRotate |
数字 | 默认 0(度,绕图片中心;钳 ±180) |
| 背景透明度 | bgOpacity |
数字 | 默认 100(0~100,100 = 不透明) |
字体
| 设置项 | # jps-config 键 |
类型 | 默认 |
|---|---|---|---|
| 标题字体 | biaoti_font |
字体名 | 微软雅黑/PingFang/Noto 系统栈 |
| 标题字号 | biaoti_size |
数字 | 20 |
| 副标题字体 | fubiaoti_font |
字体名 | 系统栈 |
| 副标题字号 | fubiaoti_size |
数字 | 15 |
| 描述头字体 | miaoshu_font |
字体名 | 系统栈 |
| 描述头字号 | miaoshu_size |
数字 | 13 |
| 说明文字字体 | notes_font |
字体名 | 系统栈 |
| 说明文字字号 | notes_size |
数字 | 12 |
| 歌词字体 | geci_font |
字体名 | 系统栈 |
| 歌词字号 | geci_size |
数字 | 11 |
| 音符字号 | note_size |
数字 | 13 |
| 音符(数字)字体 | shuzi_font |
字体名 | 系统栈 |
行距
| 设置项 | # jps-config 键 |
类型 | 默认 |
|---|---|---|---|
| 曲-词间距 | height_quci |
数字 | 20 |
| 词-词间距 | height_cici |
数字 | 10 |
| 曲-曲间距 | height_ciqu |
数字 | 20 |
| 曲-上词间距 | height_ciqu_lyric |
数字 | -5 |
| 声部间距 | height_shengbu |
数字 | 0 |
| 临时段上下间距 | segmentRowGap |
映射 | {bz: 22, dsb: 22, tp: 14}(bz/dsb 段上下层、替谱层与歌词行的纵向间距;可只写其中一项) |
渲染
| 设置项 | # jps-config 键 |
类型 | 取值 / 默认 |
|---|---|---|---|
| 歌词压缩(避免重叠) | lyricShrink |
boolean | true / false(默认 false) |
| 显示乐器名 | showInstrument |
boolean | true / false(默认 false) |
| 连音线样式 | lianyinxian_type |
数字 | 0 自动 / 1 圆弧 / 2 平顶(默认 0) |
网络使用与权限(披露)
Obsidian 的开发者政策要求明确披露网络访问,这里一次说清:
- 下载音源(唯一的外部网络请求):高保真试听需要一个 SoundFont 音源文件
(GeneralUser GS,约 32 MB,不随插件分发)。首次试听时,插件会从这个直链下载:
https://raw.githubusercontent.com/mrbumpy409/GeneralUser-GS/main/GeneralUser-GS.sf2(该地址由上游项目 GeneralUser-GS 提供)。 下载后缓存在本机(IndexedDB),之后试听不再联网。 该地址在部分网络下可能不可达(例如raw.githubusercontent.com被拦截)——此时会提示, 你可以在「设置 → iJipu」里手动导入本地.sf2文件,导入后同样只走本地缓存。 - 没有任何遥测 / 统计 / 账号:插件不收集、不上传任何数据,也不需要登录。
- 内嵌编辑器用一个"仅本机"的本地服务:
127.0.0.1上的临时 HTTP 服务 (端口固定优先47821,被占用则回退随机端口;URL 带一次性随机令牌)。 它只监听本机回环地址、不对外,仅用于把打包进main.js的网页交给内部 iframe 显示。 该服务只提供两样东西:那份单文件页面、以及页面用到的图标资源(白名单查表,不接受任意路径)。 - 文件访问范围:只读写你的 Obsidian 文库内的文件(通过 Obsidian 的文库接口),
不访问文库之外的任何路径;「默认应用」打开方式会把该
.jps交给系统关联程序(仅在你主动点击时)。
支持作者
喜欢这个插件?可在插件的设置页点「支持作者 ❤」扫码支持(与 iJipu 应用一致的微信赞赏码,https://ijipu.pages.dev/good.png)。也可访问 iJipu 官网。
标注
- 引擎:
@ijipu/engine(.jps 解析 → 排版 → SVG 渲染 → 播放序列 → Web Audio 试听)。 - 许可证:AGPL-3.0-or-later(全文见
LICENSE.md,版权与 SPDX 标识见NOTICE.md,与引擎一致)。 特别致谢「番茄简谱」原作与社区;音源 GeneralUser GS(其自带许可)。