hexo-yopu

Hexo 全能乐谱渲染插件，支持五种乐谱格式，完全兼容有谱么 JCX/data-model 格式和简谱空间简谱格式。内置 alphaTab 引擎实现专业级 Guitar Pro 解析。

支持的格式

| 格式 | 标签 | 说明 | |------|------|------| | JCX 和弦谱 | {% yopu %} | 尤克里里/吉他/钢琴 和弦谱 + 歌词排版 | | 有谱么导入 | {% datamodel %} | 直接粘贴 yopu.co 压缩谱子数据 | | 四线谱/六线谱 | (内嵌在 JCX 中) | 尤克里里 4 弦 / 吉他 6 弦 指弹谱 | | 简谱 | {% jianpu %} | 数字简谱，兼容简谱空间格式 | | 五线谱 | {% staff %} | 钢琴五线谱（高音/低音/大谱表） | | Guitar Pro | {% gp %} | 解析 .gp3/.gp4/.gp5/.gpx/.gp (alphaTab 双引擎) |

安装

npm install hexo-yopu --save

使用方法

1. JCX 和弦谱（有谱么格式）

{% yopu ukulele %}
{title: 小星星}
{artist: 传统儿歌}
{meta: 原调 1=C}

[Am] 一闪一闪 [C] 亮晶晶
[G] 满天都是 [Am] 小星星

{start_of_chorus}
[C] 挂在天上 [G] 放光明
[Am] 好像许多 [C] 小眼睛
{end_of_chorus}
{% endyopu %}

选项: instrument=ukulele|guitar|piano, key-shift=2, chord-style=inline|number, simplify-chords=true, scale=1.2

2. 简谱（简谱空间格式）

{% jianpu 我怀念的 孙燕姿 %}
/key(C)
ｂｐｍ 120

1 2 3 5 | 6 5 3 2 |
L: 我 问 为 什 么 那 女 孩
{% endjianpu %}

简谱语法:

• 音高: 1-7 (0=休止), 八度: 1' (高) 1, (低)
• 变音: #1 (升) b1 (降) n1 (还原)
• 时值: 1_ (八分) 1= (二分) 1. (附点) 1- (延长)
• 小节: | (单) || (双) |] (终止)
• 歌词: L: 词1 词2 词3
• 调号: /key(C) /key(Am)
• 速度: ｂｐｍ 120

3. 五线谱

{% staff piano %}
/key(C) bpm 120 time=4/4 clef=treble
C4 D4 E4 F4 | G4 A4 B4 C5 |
C5 B4 A4 G4 | F4 E4 D4 C4 |]
{% endstaff %}

选项: clef=treble|bass|grand, scale=1.0

4. Guitar Pro 文件

{% gp /music/song.gp5 %}
{% gp song.gpx track=1 scale=0.9 %}

GP 解析采用双引擎：优先使用 alphaTab（支持 GP3-7 + MusicXML），不可用时回退内置解析器（GP3/4/5 + GPX）。

5. 有谱么 data-model 导入

{% datamodel ukulele %}
%C3%96%C3%90%C3%82%C3%8A...
{% enddatamodel %}

直接从有谱么页面复制 data-model 属性值，插件自动解码（XOR 171 → DEFLATE → JSON）并转换为 JCX 格式渲染。

6. 指弹谱（JCX 内嵌）

{% yopu guitar %}
{title: 小练习}

{start_of_tab}
|----0---1---3---1---0---|
|----0---0---0---0---0---|
|----1---1---1---1---1---|
|----2---2---2---2---2---|
{% end_tab %}
{% endyopu %}

7. 单个和弦图

{% yopu ukulele %}
{define: Am frets 2 0 0 0 fingers 1 0 0 0}
[Am] 单和弦渲染测试
{% endyopu %}

配置

在 _config.yml 中:

yopu:
  enablePlayer: true    # 启用音频播放（默认开启）

插件结构

hexo-yopu/
├── package.json
├── index.js                 # Hexo 入口：5 个标签 + 资源注入
├── README.md
├── lib/                     # 服务端渲染引擎（Node.js，纯字符串 SVG）
│   ├── utils.js             # 音乐理论工具（转调、和弦分析、音高映射）
│   ├── text-width.js        # 文本宽度估算（无 DOM）
│   ├── data-decoder.js      # 有谱么 data-model 编解码（XOR 171 + zlib）
│   ├── jcx-parser.js        # JCX 格式解析器
│   ├── chord-renderer.js    # 和弦图 SVG 渲染器
│   ├── tab-parser.js        # ASCII 指弹谱解析器
│   ├── tab-renderer.js      # 指弹谱 SVG 渲染器
│   ├── jianpu-parser.js     # 简谱格式解析器
│   ├── jianpu-renderer.js   # 简谱 SVG 渲染器
│   ├── staff-renderer.js    # 五线谱 SVG 渲染器
│   ├── gp-parser.js         # Guitar Pro 解析器（alphaTab + 内置双引擎）
│   └── audio-data.js        # 音频合成数据
└── assets/                  # 客户端资源
    ├── ar.es.js             # DEFLATE 解压器（解码 data-model）
    ├── nier.es.js           # alphaTab 引擎（GP 解析 + MIDI 播放）
    ├── hexi.es.js           # Hexi 引擎（和弦图/指弹谱/节奏型）
    ├── hexi.css             # Hexi 样式
    ├── hexi-init.js         # Hexi 初始化
    ├── yopu.css             # 统一主题样式（明暗模式 + 打印）
    ├── yopu-player.js       # Web Audio 播放器（钢琴合成）
    └── yopu-init.js         # PJAX 感知初始化

工作原理

Markdown 文章
  │
  ├── hexo generate（服务端渲染）
  │     │
  │     ├── {% yopu %} → JCX 解析 → 和弦图 SVG + 歌词 HTML → <hexi-sheet>
  │     ├── {% datamodel %} → 解码 data-model → JCX 转换 → <hexi-sheet>
  │     ├── {% jianpu %} → 简谱解析 → 每小节 SVG → <div class="to-jianpu">
  │     ├── {% staff %} → 五线谱解析 → 大谱表 SVG → <div class="to-staff">
  │     └── {% gp %} → alphaTab / 内置解析 → JCX 转换 → 指弹谱 SVG
  │
  └── 浏览器加载（客户端增强）
        │
        ├── 静态 SVG 立即渲染（无需 JavaScript）
        ├── ar.es.js → 解码 data-model 属性
        ├── hexi.es.js → 增强和弦图交互、转调
        ├── nier.es.js → alphaTab MIDI 播放
        └── yopu-player.js → Web Audio 播放、音符高亮

许可

MIT