https://github.com/encaik/simple-notation
简谱渲染是一个基于TypeScript开发的简单音乐渲染库，可以让用户使用简单的文本配置来渲染简谱。
https://github.com/encaik/simple-notation
music score simple-notation typescript vite
Last synced: 4 months ago
JSON representation
简谱渲染是一个基于TypeScript开发的简单音乐渲染库，可以让用户使用简单的文本配置来渲染简谱。
- Host: GitHub
- URL: https://github.com/encaik/simple-notation
- Owner: Encaik
- License: mit
- Created: 2024-07-18T09:31:51.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-11-20T02:47:29.000Z (8 months ago)
- Last Synced: 2025-11-20T04:17:51.434Z (8 months ago)
- Topics: music, score, simple-notation, typescript, vite
- Language: TypeScript
- Homepage: https://simple-notation.vercel.app
- Size: 126 MB
- Stars: 36
- Watchers: 1
- Forks: 4
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 简谱渲染
## 介绍
这是一个基于 TypeScript 开发的动态简谱渲染库，用户仅需文本输入，即可在网页上生成优美的简谱。
简谱应用:[https://simple-notation.vercel.app/](https://simple-notation.vercel.app/)
国内访问:[https://www.s-n.xyz](www.s-n.xyz)
(但加载速度可能仍然较慢)
[](https://simple-notation.vercel.app/)
[](https://codecov.io/gh/Encaik/simple-notation)
[](https://app.netlify.com/projects/sage-kheer-b2bd9f/deploys)
## 界面展示
## 使用方法
[](https://badge.fury.io/js/simple-notation)
### 1. 引入方式
#### 浏览器直接引入
1. ESM方式
将 `dist/simple-notation.js` 和 `dist/style.css` 拷贝到你的项目，并在 HTML 中引入：
```html
import { SimpleNotation } from './simple-notation.js';
import './style.css';
const container = document.getElementById('container');
const sn = new SimpleNotation(app, {
resize: true,
debug: true,
});
sn.loadData(...);
```
2. UMD方式
将 `dist/simple-notation.umd.js` 和 `dist/style.css` 拷贝到你的项目，并在 HTML 中引入：
```html
const container = document.getElementById('container');
const sn = new SN.SimpleNotation(container, {
})
sn.loadData(...);
```
#### npm 包引入
```bash
npm install simple-notation
```
1. ESM方式
```js
import { SimpleNotation } from 'simple-notation';
import 'simple-notation/dist/style.css';
const container = document.getElementById('container');
const sn = new SimpleNotation(container, { debug: true });
sn.loadData(...);
```
2. UMD方式
```js
const SN = require('simple-notation');
import'simple-notation/dist/style.css';
const container = document.getElementById('container');
const sn = new SN.SimpleNotation(container, { debug: true });
sn.loadData(...);
```
### 2. 加载数据
```js
sn.loadData({
info: {
title: '小星星',
composer: 'Mozart, W.A.',
lyricist: '佚名',
time: '4',
tempo: '88',
key: 'C',
beat: '4',
},
score: `1,1,5,5|6,6,5,-|4,4,3,3
2,2,1,-|5,5,4,4|3,3,2,-
5,5,4,4|3,3,2,-|1,1,5,5
6,6,5,-|4,4,3,3|2,2,1,-`,
lyric: `一闪一闪亮晶晶-
满天都是小星星-
挂在天空放光明-
好像千颗小眼睛-
一闪一闪亮晶晶-
满天都是小星星`,
});
```
### 3. 播放控制
`simple-notation` 提供了独立的播放器类 `SNPlayer`，可用于简谱的自动播放、暂停、继续、停止等操作，并支持光标联动。
```js
import { SNPlayer } from 'simple-notation';
// 需在 sn.loadData 后创建播放器实例
const player = new SNPlayer();
// 播放
player.play();
// 暂停
player.pause();
// 继续
player.resume();
// 停止
player.stop();
// 播放结束回调
player.onEnd(() => {
console.log('播放结束');
});
// 实际发声回调（非'-'音符）
player.onNotePlay((note, duration) => {
// 可在此处集成 WebAudio 或 MIDI 播放
console.log('播放音符', note, '时长', duration);
});
// 光标移动回调（每个音符都会触发，包括'-'）
player.onPointerMove((note) => {
// 可用于自定义高亮
console.log('光标移动到', note);
});
```
### 4. 光标层控制
播放器会自动联动光标层（高亮当前播放音符）。如需手动控制光标，可使用 `SNPointerLayer`：
```js
import { SNPointerLayer } from 'simple-notation';
// 显示/移动光标到指定音符
SNPointerLayer.showPointer('note-1', sn.el);
// 隐藏光标
SNPointerLayer.clearPointer();
```
> **注：** `note-1` 为 SVG 元素的 `sn-tag` 属性值，通常可通过回调参数中的 `note.tag` 获取。
### 5. 其他说明
- 支持自动响应容器大小变化（`resize: true`）。
- 支持调试模式（`debug: true`），会输出详细日志。
- 支持 ABC 记谱法（开发中）。
如需更详细的 API 说明和高级用法，请参考源码中的 JSDoc 注释和 `examples/` 目录下的实际用例。
## 乐器采样支持
本项目的乐器音源来自 [nbrosowsky/tonejs-instruments](https://github.com/nbrosowsky/tonejs-instruments) 仓库，根据 [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/) 许可证授权使用。
## 名字解释
- simple notation : 简谱
- score : 整个乐谱
- stave : 一行乐谱，可包含多个小节
- measure : 小节
更具体的可以参考此链接：[音乐术语中英对照](https://www.cnblogs.com/Stareven233/p/15755596.html)