pip install -r requirements.txt如果需要使用VOCALOID功能，请在启动了docker的命令行运行：
Docker 启动：
docker pull voicevox/voicevox_engine:cpu-latest
docker run --rm -p '127.0.0.1:50021:50021' voicevox/voicevox_engine:cpu-latest文件菜单中可以导出为MP3。
导出为 MP3 需要安装 ffmpeg。若未安装，程序会自动回退为 WAV 格式。
macOS（Homebrew）：
brew install ffmpegWindows：
- winget：
winget install ffmpeg - Chocolatey：
choco install ffmpeg - 或从 ffmpeg.org 下载，将
bin目录加入 PATH
Linux：
- Ubuntu/Debian：
sudo apt install ffmpeg - Fedora：
sudo dnf install ffmpeg - Arch：
sudo pacman -S ffmpeg
安装后可用 ffmpeg -version 验证。
使用 PyInstaller 打包为单文件，内含音色库与示例工作区：
pip install pyinstaller
pyinstaller ascii_choir.spec输出在 dist/ASCII_Choir。详见 docs/PYINSTALLER_TUTORIAL.md。
- 音量变化（首先寻找下3小节内最近的音量记号，否则音量调节的端点默认设置为当前音量到[p]/[f]）
- [crescendo] （或[c]）
- [decrescendo] (或[d])
- 音符长度微调
- [~] 表示连奏
- [·] 表示断奏
- 音量设置
- [fff] 音量100%
- [ff] 音量90%
- [f] 音量80%
- [mf] 音量70%
- [mp] 音量50%
- [p] 音量40%
- [pp] 音量30%
- [ppp] 音量20%
- 升降号技能调整
- [deviation explicit on] 启用还原号。
- [deviation explicit off] 关闭还原号。此时升降号只作用于单音，不持续。
- 八度记号
- [8va] 高八度（ottava alta），将括号内音符整体升高一个八度
- [8vb] 低八度（ottava bassa），将括号内音符整体降低一个八度
- [15va] 高两个八度（quindicesima），将括号内音符整体升高两个八度
- [15vb] 低两个八度，将括号内音符整体降低两个八度
- 琶音装饰
[a]/[arpeggio]
- 快速连续弹奏多个音符，从最低音开始，同时终止。无括号时只作用于右边第一个音（单音或和弦）；有括号
[a](...)则作用于括号内所有音。
有效的例子：
| [a]1/3/5 2 3 | # 和弦 1/3/5 琶音，2、3 正常
| [arpeggio](1 2 3 4) | # 括号内四个音依次琶音
- 滑音
[gliss]
[gliss](起音 止音)从起音滑到止音。默认占 1 拍、两个音符。可用|跨小节或_缩短时值。
有效的例子：
| [gliss](1 5) | # 从 1 滑到 5，1 拍
| [gliss](1_ 5) | # 同上，时值由内容决定
| [gliss](1 5)_ | # 0.5 拍滑音
- 颤音
[tr]/[tr+]/[tr-]
[tr](主音)或[tr] 主音 后续内容：主音与上方大二度快速交替。[tr+]上颤音；[tr-]下颤音（主音与下方大二度交替）。可用-和_调整时值。
有效的例子：
| [tr](1) | # 1 与上方 2 交替，1 拍
| [tr] 1 - (.5 1 2 3)_ | # 无括号时，后续内容直到 | 为颤音范围
| [tr-](1) | # 1 与下方 7 交替
- 和声记号
- [+3][-3][+5][-5] 按音名往下/上数：+3 往上三度（如 E→G），-3 往下三度（如 E→C、G→E）；+5/-5 同理。不可用于含升降号（# b ^）的音符。
- 反复与结束记号
- [dc] Da Capo：从此处跳回开头，再演奏至 [fine] 结束。
- [fine]：在此处结束演奏。
有效的例子（先奏 A-B-[dc]，再从头奏 A-B 至 [fine] 结束）：
|1 2 3 4|
|5 6 7 1[dc]|
|1 2 3 4[fine]|
后面接圆括号，圆括号中的音符表示作用范围。 默认的音量是60%，如果不写圆括号，则表示作用范围从记号位置一直到互斥的下一个记号处或者末尾。 记号支持嵌套。
不正确的小节会被红色高亮，将鼠标移动上去。可以关闭该功能。
有效的例子：
|1 2 5 1|
有效的例子：
|3---|
4. _写在音符右边的时候表示调整音符的时值（除以2），如果有多音写在最后一个音的最后，可以叠加使用。括号可应用到 _ 上：(notes)_ 对括号内每一个音符均分后整体缩短一半，_ 的优先级高于 []。
有效的例子：
| 1_ 2_ 3 4 5 |
| 1 2 (3 4 5 6)_ |
有效的例子：
|(1 2 5 1 2 5 1 2 5 1 2 5)3|
有效的例子：
|.3---|3---|.4---|4---|.5---| 5---|.6---| 6- 5-|
&|(1 2 5 1 2 5 1 2 5 1 2 5)3|8|8|8|8|8|8|8|
&表示一条旋律。可以在多个行头使用&，表示这些旋律同步进行，从而实现多声部演奏。 每一篇章的 & 数量相同，篇章之间用两个回车（双换行）分隔。渲染时按篇章顺序拼接。 结尾的小节号 | 可省略（会被忽略）。
有效的例子：
& [8vb](|.3---|3---|.4---|4---|)
&|(1 2 5 1 2 5 1 2 5 1 2 5)3|8|8|8|
& [8vb](|.5---|5---|.6---|6- 5-|)
&|8|8|8|8|
有效的例子：
|0 - 0 1_ 2_ | 3 0~ |
有效的例子：
|0 - 0 (1 2)_ | 3 (4 5)_ 0_ 5 5_ | ~5 3 5 1. |
|5 6 7 1.|~3 2 1|
有效的例子：
|0 - 0 (.6/1 .7/2)_ | 1/3 (2/4 3/5 0)_ 3/5 3/5_ | ~3/~5 1/3 3/5 6/1. |
为了简记，也可以使用+3，-3，+5，-5等符号配置预制大三度/大五度上下和声。 有效的例子：
|0 - 0 [-3]((1 2)_ | 3 (4 5)_ 0_ 5 5_ | ~5 3 5 1. )|
有效的例子：
| 1 #1 ^1 b1 |
调性输入在最前面，对所有音符应用统一半音偏移。篇章之间可用新的 \tonality、\beat、\bpm 覆盖前面的设定，实现转调、转拍、变速。
\tonality{X}表示调性，对所有音符应用半音偏移。- 数字：直接表示上移或下移多少个半音，如
0、1、-1、+2。 - 字母+升降号：快捷写法，
C=0、D=2、#C=1、bD=1、bA=8 等。
有效的例子：
\tonality{0}
\tonality{b1}
\tonality{bA}
\tonality{bB}
\tonality{C}
\tonality{#C}
\tonality{+2}
篇章间覆盖（转调、转拍、变速）：
\tonality{C}
\beat{4/4}
\bpm{60}
|1 2 3 4|5 4 3 2|1 - - -|
\tonality{D}
\bpm{120}
|1 2 3 4|5 4 3 2|1 - - -|
拍号紧接在调性之后。
\beat{分子/分母}表示拍号，如 4/4、3/4、6/8。分母定义 1 拍（如 4/4 中四分音符=1拍），一小节=分子拍，便于计算。\beat{c}表示 common time（4/4），\beat{cut}表示 cut time（2/2）
有效的例子：
\beat{4/4}
\beat{3/4}
\beat{c}
\bpm{数值}表示每分钟拍数，用于设定曲目 tempo
有效的例子：
\bpm{120}
\bpm{60}
由于这是一个创作类软件，很多时候小节号会给记谱带来额外负担。 使用\no_bar_check即可禁用小节号，同时beat也无效。
\reverb{N} 对整曲施加混响，N 为 0–100，0 为无混响，100 为最大混响强度。作用于所有乐器。
\tonality{0}
\beat{4/4}
\bpm{120}
\reverb{30}
|1 2 3 4|5 6 7 1|
\tts{文本}、\tts{文本}{语言} 或 \tts{文本}{语言}{voice_id} 用于在篇章之间插入语音朗读，仅可插入在篇章之间（双换行分隔的块）。
- 支持语言：
zh中文、ja日语、en英语（默认） - voice_id（可选）：VOICEVOX 的 style_id。若填写，则用 VOICEVOX 合成，不再使用 edge-tts；需先启动 voicevox_engine（默认 http://127.0.0.1:50021），可在 TTS 菜单 → VOICEVOX 音色选择 中查看并复制命令
- 未填 voice_id 时：需安装
edge-tts，播放时需网络；音频解码优先用audioread，否则需pydub+ffmpeg
有效的例子：
\tonality{0}
\beat{4/4}
\bpm{120}
|1 2 3 4|
\tts{第一段结束}{zh}
|5 6 7 1|
\tts{Verse two}{en}
\tts{こんにちは}{ja}{1}
|1 2 3 4|5 6 7 1|
\lyrics{字1/字2/字3} 将斜杠分隔的每个字与一个音符对齐（连音线视为一个音符）。溢出自动添加到下一行第一个未对齐的音符。
\lyrics{...}{part_index}：声部索引，指定歌词追加到第几个声部（0 起）。多声部时，0=第一行旋律，1=第二行旋律，以此类推\lyrics{...}{part_index}{voice_id}：voice_id 为 VOICEVOX style_id（可选）。有 voice_id 时播放会用 VOICEVOX 歌唱合成歌声，替代 WAV 音色\lyrics{...}{part_index}{voice_id}{melody}：melody 为和声时旋律来源，0=第一音旋律，1=第二音旋律\lyrics{...}{part_index}{voice_id}{melody}{volume}：volume 为歌声音量 0–150，默认 60，>100 可做提升- 行内歌词：
1(啊) 2(一)在音符后加括号（未测试！！）
\tonality{0}
\beat{4/4}
\lyrics{do/re/mi/fa}
|1 2 3 4|5 6 7 1|
多声部示例（\lyrics{音节}{part_index}{voice_id}{melody}{volume} 五个参数依次为）：
- 音节：斜杠分隔的字，与音符一一对齐
- part_index：声部索引（0 起），0=第一行旋律，1=第二行旋律
- voice_id：VOICEVOX 的 style_id，有则用歌唱合成；可省略
- melody：和声时旋律来源，
0=第一音旋律，1=第二音旋律 - volume：歌声音量 0–150，默认 60，>100 可做提升
\tonality{0}
\beat{4/4}
\lyrics{啊/呀/哦}{0}{5}{0} // 音节/声部0/音色5/第一音旋律
& 1 2 3 | 4 5 6
和弦 melody 示例（同一声部有和弦时，0 取每和弦第一音、1 取第二音）：但目前只能启用一个
\tonality{0}
\beat{4/4}
\bpm{60}
\lyrics{低/低/音/音/唱/唱}{0}{5}{0} // melody=0：取 1/3、2/4、3/5、4/6、5/7、6/1. 中的 1、2、3、4、5、6
\lyrics{高/高/音/音/唱/唱}{0}{5}{1} // melody=1：取各和弦第二音 3、4、5、6、7、1.
& |1/3 2/4 3/5|4/6 5/7 6/1.|
行首 [cello]、[guitar]、[drums] 等指定该声部乐器。鼓声部 [drums] 使用 GM 打击乐映射，鼓声库需先运行 sound_library/build_drums.py 从原始素材生成。
[distortion:N] 或 [drive:N]（N 为 0–100）控制电吉他/电贝司的合成失真度。0 为原声，100 为最大失真。仅对 [guitar_electric]、[bass_electric] 生效。
& [guitar_electric][distortion:50]|1 2 3 4| # 50% 失真
& [guitar_electric][drive:80]|5 6 7 1| # 80% 失真
鼓声部使用与旋律一致的简谱格式（.1、.2、..#4 等），便于对齐。C 大调（\tonality{0}）下示例：
| MIDI | 名称 | 简谱（tonality 0） |
|---|---|---|
| 28 | Slap（鼓棒） | ...3 |
| 31 | Sticks（鼓棒） | ...5 |
| 35 | Acoustic Bass Drum | ...7 |
| 36 | Bass Drum 1 | ..1 |
| 37 | Side Stick（鼓棒敲边） | ..#1 |
| 38 | Acoustic Snare | ..2 |
| 39 | Hand Clap | ..#2 |
| 40 | Electric Snare | ..3 |
| 41 | Low Floor Tom | ..4 |
| 42 | Closed Hi-Hat | ..#4 |
| 43 | High Floor Tom | ..5 |
| 44 | Pedal Hi-Hat | ..#5 |
| 45 | Low Tom | ..6 |
| 46 | Open Hi-Hat | ..#6 |
| 47 | Low-Mid Tom | ..7 |
| 48 | Hi-Mid Tom | .1 |
| 49 | Crash Cymbal 1 | .#1 |
| 50 | High Tom | .2 |
| 51 | Ride Cymbal 1 | .#2 |
| 52 | Chinese Cymbal | .3 |
| 53 | Ride Bell | .4 |
| 55 | Splash Cymbal | .5 |
| 57 | Crash Cymbal 2 | .6 |
| 59 | Ride Cymbal 2 | .7 |
说明：鼓音使用简谱数字（含 .、..、#、b），与旋律记谱一致，便于多声部对齐。鼓声部不受 \tonality 控制，始终按 C 大调映射（如 .1=C、.6=A）。
\import{文件名} 在播放前会被自动展开为对应文件的内容，用于模块化组织简谱。
- 文件名相对于工作区根目录或当前文件所在目录解析
- 支持递归导入（被导入文件中的
\import会继续展开） - 检测循环导入并报错
有效的例子：
\tonality{0}
\beat{4/4}
\bpm{60}
\import{前奏.choir}
|1 2 3 4|5 6 7 1|
\import{副歌.choir}
TTS 菜单 → VOICEVOX 音色选择 可打开音色对话框：
- 左侧：扁平音色列表，点击即试听
- 右侧：选中音色的全身照与利用規約
- 复制 TTS 命令：将
\tts{こんにちは}{ja}{style_id}复制到剪贴板 - 复制 歌词命令：将
\lyrics{字/字}{0}{style_id}{0}复制到剪贴板（可追加{60}设置音量） - 清唱生成：用当前选中音色将当前编辑器中的简谱合成为歌声（无 WAV 伴奏），直接播放
使用前需启动 voicevox_engine（默认 http://127.0.0.1:50021）。
歌词歌声合成：当 \lyrics{...}{part}{voice_id}{melody}{volume} 中指定了 voice_id 时，播放该篇章会用 VOICEVOX 歌唱 API 合成歌声。volume 可选，默认 60。注意：歌唱仅支持 /singers 中的角色（如波音リツ），若所选音色不支持歌唱，程序会自动使用可用的歌唱角色。
从左侧工作区文件列表拖拽文件到输入框，可在落点插入 \import{文件名}，播放前会自动展开。
- Ctrl+F / ⌘F：打开查找对话框，支持查找下一个/上一个、区分大小写
- Ctrl+H / ⌘⌥F（Mac）：打开替换对话框，支持替换、全部替换
- 若有选中文本（单行），会预填到查找框
- Ctrl+Shift+F / ⌘⇧F：自动对齐同时演奏的多个小节号。勾选「行超宽时自动换新篇章」时，超宽行会自动换新篇章。
程序会记住上次打开的工作区及每个工作区的最后打开文件，下次启动时自动恢复。
自动使用淡色荧光高亮括号作用域。