# 曲谱 JSON 文件说明
* **注意** 
	- 制谱优先使用AutoYuanQin\assets\tutorial_file目录下的制谱软件(index.html)，有任何疑问请来看这个使用说明
此文档供曲谱制作人阅读，本文档详细说明了一个标准格式的曲谱.json文件格式，包括各个字段的解释以及曲谱内容的格式要求。

重要：即使制作了曲谱的JSON文件，放到了正确的路径下，在调度器的JS脚本配置里也不会出现你制作的曲谱（上传方法如下）

## 上传方法
1.上传到BetterGI脚本仓库的repo\js\AutoLyre\assets\score_file路径下，根据已存在的曲谱在你的文件名前添加序号(例如 10.曲名.json)，完成后请联系BetterGI v7群主更新JS脚本

2.联系BetterGI v7（1029539994）群主帮你更新到仓库

3.发送邮件到hijiwos@hotmail.com并说明，你的谱子将会在一段时间内更新到仓库

## 曲谱制作器使用方法
**制谱器路径: AutoYuanQin\assets\tutorial_file\index.html(请确保 五线谱注解.png与制谱器位于同一目录下)**
**声明：本制谱器生成的曲谱文件为标准格式**

* 使用步骤如下（顺序）
	* 确定音域（共有三种音域可选[左中右共三个]，每个音域为一对红蓝大写字符[21个]）
		* 选择音符：点击左上角图片中的对应大写字母或@, 点击多个音符实现和弦
		* 完善音符：页面底部两行选择音符的具体类型，选好后点击按钮```确定（完善音符）```
		* 分节：确保当前页面的音符都已完善，点击按钮```分节```
		* 换行：确保当前页面的音符都已完善，点击按钮```换行```
		
		* **删除音符：** 如果您**写错了音符**，请**手动**删除**整个音符**并确保右上角代码框的**末尾**是 ```]、|、或一行的开头```
			* 音符删除示例：```A[16]B[32]``` 比如您想写 ```B[16]``` ，一不小心写成了三十二分音符，请删除整个音符~~B[32]~~，删除后的示例```A[16]```，然后再次进行音符 ```B```的写入
	* 写入曲谱信息（曲名、录谱人必填、bpm、拍号）
	* 导出曲谱
		点击按钮```导出乐谱JSON```，曲谱文件名请确认是```曲名.json```
	* 读取乐谱
		如果您写了一半，打算下次在写，可以使用导出曲谱功能保存曲谱，下次要写的时候点击按钮```读取乐谱JSON```，选择上次导出的文件即可

## 曲谱制作问题
`\assets\tutorial_file\五线谱注解.png` 包含了五线谱（高音区和低音区）对应的3组键盘键位（相邻的红蓝大写字母为一组，每组音域为三个八度）

有不懂的地方请在 `\assets\tutorial_file\example.json` 内找，这个谱子内包含了该脚本的五线谱相关的所有功能

## 曲谱文件位置
所有的曲谱文件应放置于 `AutoLyre\assets\score_file` 路径下，并在文件名前添加正确的序号

## 文件结构
一个标准的曲谱.json文件的基本结构如下：  
```json
{  
  "name": "",
  "author": "",
  "description": "",
  "bpm": "",
  "time_signature": "",
  "composer": "",
  "arranger": "",
  "notes": ""
}
```

**注意**：以上代码中仅 :  右侧的**双引号内**的部分可以更改，具体的曲谱格式请参考 `\assets\tutorial_file` 路径下的 `example.json`

## 字段说明
**name**: 曲谱名，必填。  

**author**: 录谱人，制作这个.json曲谱的作者名。  

**description**: 描述，可以随意填写关于该曲谱的附加信息  

**bpm**: 曲谱的BPM（Beats Per Minute），必填。  

**time_signature**: 拍号，必填，例如 3/4 代表 以四分音符为一拍每小节三拍（被设为一拍的音符仅支持2的幂）。  

**composer**: 曲师，选填。  

**arranger**: 谱师，选填。  

**notes**: 曲谱内容，必填，具体格式请参考以下解析规则。  

## Notes 解析规则（重要）
notes 字段中包含的是乐谱内容。音符**必须**使用**大写字母**，乐谱内容使用字符串表示，小节之间用 | 隔开。单个小节的解析规则如下：  

### A[4]
表示按下A键，A键视作四分音符。
<div align="center">
  <img src="assets\tutorial_file\四分音符示例.png"/>
  <p>四分音符示例</p>
</div>

### F[16-#]D[16-#]S[16-#]
表示**装饰音·倚音**  
<div align="center">
  <img src="assets\tutorial_file\装饰音·倚音示例.png"/>
  <p>装饰音·倚音示例</p>
</div>

以上每个装饰音的时值固定为拍号中的标准时值(3/4的标准时值为四分音符的时值)的1/16，也就是说以上示例中的**16没有意义，但是必须要写**

### Z[4-8.3]C[4-8.3]B[4-8.$]
表示一个**三连音**（六连音用法与此相似，仅需将3改成6，**其它类型的连音**也请使用3或6(即使是5连音)）
另外，连音内支持和弦
<div align="center">
  <img src="assets\tutorial_file\三连音示例.png"/>
  <p>三连音示例</p>
</div>

* Z[4-8.3]  

	4表示该三连音的总时值相当于四分音符，8表示当前音符在乐谱上显示的时值相当于八分音符的时值，3表示这是一个三连音的音符
	
* C[4-8.3]  

	同上
	
* B[4-8.$]  

	$表示这是当前连音的最后一个音符

### D[4-16.3]G[4-16.3]H[4-16.3]W[4-16.3]R[4-16.$]
表示一个**五连音**，同理也可以是**N连音**
<div align="center">
  <img src="assets\tutorial_file\五连音示例.png"/>
  <p>五连音示例</p>
</div>

* D[4-16.3]

	4表示该连音的总时值相当于四分音符，16表示当前音符在乐谱上显示的时值相当于十六分音符的时值，3表示这个音符是一个连音的一部分

* R[4-16.$]

	$表示这是当前连音的最后一个音符
### (BG)[4-4.3]\(VF\)[4-8.$]
表示一个**三连音连音线**（与三连音用法相同，但是三连音连音线允许连线内出现不同类型的音符）
<div align="center">
  <img src="assets\tutorial_file\三连音连音线示例.png"/>
  <p>三连音连音线示例</p>
</div>

* (BG)[4-4.3]  

	第一个4表示整个三连音的总时值为一个四分音符，第二个4表示当前音符在乐谱上显示的时值相当于四分音符的时值，3表示这是一个三连音的音符
	
* (VF)[4-8.$]  

	4表示整个三连音的总时值为一个四分音符，8表示这是一个八分音符，$表示这是当前连音的最后一个音符

### @[2-8.6]\(AF\)[2-16.6]N[2-16.6]\(AF\)[2-16.6]N[2-16.6]\(AF\)[2-16.6]N[2-16.6]\(AF\)[2-16.6]N[2-16.6]\(AF\)[2-16.6]N[2-16.$]
表示一个**六连音连音线**（乐谱上表示为一个六连音连音线内包含1个八分休止符和10个十六分音符，区别于三连音，六连音的.后面的数字是6）
<div align="center">
  <img src="assets\tutorial_file\六连音连音线示例.png"/>
  <p>六连音连音线示例</p>
</div>

* @[2-8.6]  

	2表示该六连音的总时值相当于一个二分音符，8表示当前音符在乐谱上显示的时值相当于八分音符的时值，6表示这是一个六连音
	
* N[2-16.$]  

	16表示当前音符在乐谱上显示的时值相当于十六分音符的时值，$表示这是当前连音的最后一个音符

### @[4]
表示一个**休止符**
<div align="center">
  <img src="assets\tutorial_file\四分休止符示例.png"/>
  <p>四分休止符示例</p>
</div>

	中括号内表明这是几分休止符，例如这里表示四分休止符。

### (SH)[4-*]
表示一个**附点四分音符**
<div align="center">
  <img src="assets\tutorial_file\附点四分音符示例.png"/>
  <p>附点四分音符示例</p>
</div>

	表示按下S和H键(和弦)，这个和弦视作附点四分音符。

## 代码美化
曲谱JSON文件的"notes"的值视作一个字符串，在这个字符串内仅可以使用**换行符**美化代码，通过这种方法可以使用记事本等软件从.json文件中获取带有换行的曲谱代码（**notes内的换行符不会被读取执行**）  

### 格式
	每一小节的末尾加|\n  

	每一行的末尾加|\n\n
	
	曲谱的末尾无需加|和\n

例如: 
```json
{
  "name": "示例曲谱",
  "author": "录谱人A",
  "bpm": "120",
  "description": 预计时长: xxxxx, 五线谱网址: xxx.xxxx.xxx,
  "time_signature": "4/4",
  "composer": "曲师B",
  "arranger": "谱师C",
  "notes": "A[4](ASD)[8]Y[8-#]F[8-#](DFG)[8]R[4-*]T[8]|\n@[4](DFG)[8](CVB)[8]D[4]A[4]|\n\nA[4](ASD)[8]Y[8-#]F[8-#](DFG)[8]R[4]T[4]|\n@[4](DFG)[8](CVB)[8]D[4]A[4]"
}
```

## 附：
中括号 []（- 前表示音符类型，- 后用于区分特殊音符）

* [4]  

表示四分音符。  

* [16]  

表示十六分音符。  

* [-#]  

表示装饰音。  

* [-n.3]  

表示连音（使用时必须保证连音的最后一个音的标记为.$）。  

* [-n.$]  

表示当前连音的结束  

例如：[16-#] 表示十六分音符的装饰音，A[4-8.3]S[4-8.3]D[4-8.$] 表示一个总时值为4分音符的三连音。

## 示例
一个完整的曲谱.json文件示例如下（供示例，仅包含几个小节）：

文件名: `示例曲谱.json`

```json
{
  "name": "示例曲谱",
  "author": "录谱人",
  "bpm": "120",
  "description": "曲谱信息",
  "time_signature": "4/4",
  "composer": "曲师",
  "arranger": "谱师",
  "notes": "N[8-#]A[8-#](VS)[1]|\n(NF)[2-*](AG)[4]|\n(SH)[2-*](SH)[8](AG)[8]|\n(FW)[4](VF)[4](BG)[4](NH)[4]|\n\nB[8]N[8]X[16]Z[16]X[16]Z[16]B[8]N[8]X[16]Z[16]X[16]Z[16]|\nB[8]N[8]X[16]Z[16]X[16]Z[16]V[8]C[8]X[8]Z[8]"
}
```