iJipu

by 蜗牛
5
4
3
2
1
Score: 43/100

Description

爱记谱(英文名:iJipu)—— 优秀高效的代码式简谱制谱引擎。

Reviews

No reviews yet.

Stats

4
stars
231
downloads
0
forks
42
days
3
days
3
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
2
total issues
1
open issues
1
closed issues
489
commits

Latest Version

4 days ago

Changelog

爱记谱 iJipu 0.49.0

跟随版(内嵌应用 0.81.0)(MINOR):内嵌应用重新生成,把作者行 emoji 估宽修复带进 Obsidian 里的内嵌界面。引擎号不变(仍 0.48.0),插件自身无功能改动。

为什么要重发

  • 0.48.1 只把插件自己的 vendor/engine 同步到修好的估宽函数,内嵌应用是构建产物(src/gen/webappAssets.ts,生成于 0.48.0 发版时),里面的引擎仍是旧估宽 —— 所以内嵌界面里 emoji 还会压字。
  • 这次用当前应用源码重跑嵌入版构建(npm run build:embed + scripts/embed-emit.mjs),内嵌产物里的引擎已含修复(Extended_Pictographic 命中 1 处)。

内嵌应用

  • 应用版本仍为 0.81.0(WEBAPP_META.appVersion),只更新构建产物(generatedAt = 2026-11-16T13:51:41Z,单文件 HTML 1,838,468 字节)。
  • npm run smoke:embed 通过:单文件产物启动成功、无运行时报错、桥端到端通过(应用 hello→ready、19 次桥调用)、宿主推 openFile 能真的打开、设置持久化走宿主。

引擎

  • 版本不变(0.48.0);vendor/engine 未改动(0.48.1 已同步完)。

插件自身

  • 无功能改动;只是内嵌应用资产重新生成。

README file from

Github

iJipu(爱记谱)—— 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 代码块在两端完全一致。

从社区目录安装(推荐)

  1. 打开 Obsidian → 设置 → 第三方插件 → 浏览;
  2. 搜索 iJipu,点安装 → 启用。

手动安装

  1. 到 Releases 下载 main.js、manifest.json、styles.css;
  2. 放到 <你的库>/.obsidian/plugins/ijipu/(目录名必须是 ijipu,与 manifest.json 的 id 一致);
  3. 在 设置 → 第三方插件 里启用 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(其自带许可)。