Tunesformer

🚀 TunesFormer

TunesFormer是一款高效的基于Transformer的双解码器模型，专门用于生成符合用户指定音乐形式的旋律。它能有效解决音乐生成中对特定形式旋律的需求，为音乐创作提供了强大的工具。

🚀 快速开始

安装依赖

安装 此仓库 中代码所需的依赖：

unidecode                    1.3.6
torch                        1.13.1+cu116
samplings                    0.1.7
transformers                 4.18.0

设置提示

在 prompt.txt 中设置条件音乐生成的提示：

S:2
B:9
E:4
B:9
L:1/8
M:3/4
K:D
 de |"D"

运行脚本

运行 generate.py 脚本。首次运行脚本时，下载的权重将被缓存以便后续重用。如果自动下载失败，你可以从 这里 手动下载权重。

python generate.py -num_tunes 3 -max_patch 128 -top_p 0.8 -top_k 8 -temperature 1.2 -seed 0 -show_control_code True

享受音乐

在 output_tunes 文件夹中享受生成的曲调！如果你想将这些ABC曲调转换为乐谱或音频，请参考 ABC Notation。

✨ 主要特性

• 高效双解码器模型：基于Transformer架构，专门设计用于生成符合用户指定音乐形式的旋律。
• 控制代码引导：利用控制代码（如S、B、E等），用户可以精确指定生成曲调的结构和形式。
• 支持ABC记谱法：与ABC记谱法集成，方便音乐的表示、编辑和分享。
• 可在线体验：GPT - 2版本可在 huggingface spaces 上在线使用和体验。

📦 安装指南

安装 此仓库 中代码所需的依赖：

unidecode                    1.3.6
torch                        1.13.1+cu116
samplings                    0.1.7
transformers                 4.18.0

💻 使用示例

基础用法

# 安装依赖
unidecode                    1.3.6
torch                        1.13.1+cu116
samplings                    0.1.7
transformers                 4.18.0

# 设置提示
S:2
B:9
E:4
B:9
L:1/8
M:3/4
K:D
 de |"D"

# 运行脚本
python generate.py -num_tunes 3 -max_patch 128 -top_p 0.8 -top_k 8 -temperature 1.2 -seed 0 -show_control_code True

高级用法

使用自己的数据集进行训练：

1. 首先，解压 data_curation.zip 文件。
2. 然后，将你自己的符号音乐数据（.xml、.mxl、.musicxml 格式）放入 xmls 文件夹。
3. 运行 batch_converter.py 文件，将你的数据转换为ABC记谱法并放入 abcs 文件夹。
4. 运行 add_control_codes.py 文件。这将为你的ABC记谱法添加控制代码，并将数据保存为 dataset.json。
5. 最后，运行 train.py 文件来训练你自己的模型。权重将保存为 weights.pth

📚 详细文档

模型描述

TunesFormer是一个高效的基于Transformer的双解码器模型，专为生成符合用户指定音乐形式的旋律而设计。它在论文 TunesFormer: Forming Irish Tunes with Control Codes by Bar Patching 中被提出，作者为Wu等人。代码发布在 此仓库 中，数据集发布在 huggingface 上。

TunesFormer在214,122首爱尔兰曲调上进行训练，采用了包括小节修补和控制代码在内的技术。小节修补减少了序列长度和生成时间，而控制代码引导TunesFormer生成符合所需音乐形式的旋律。

TunesFormer（GPT - 2版本）可在 huggingface spaces 上在线使用和体验。对于完整的双解码器版本的TunesFormer，请使用 官方GitHub仓库 中的脚本。

ABC记谱法

ABC记谱法是一种基于ASCII的纯文本音乐记谱系统，常用于转录传统音乐和在线分享乐谱。它提供了一种简单而简洁的方式来表示音乐元素，如音符、节奏、和弦等。

对于那些希望以各种方式与ABC记谱法进行交互的人，有以下几种工具可供使用：

1. 在线ABC播放器：这个基于网络的工具允许你输入ABC记谱法并收听相应的音频回放。通过将你的ABC代码粘贴到播放器中，你可以立即听到曲调的演奏效果。

2. ABC乐谱编辑器 - EasyABC：EasyABC是一款用户友好的软件应用程序，用于创建、编辑和格式化ABC记谱法。其图形界面使你能够输入ABC代码、预览乐谱并根据需要进行调整。

数据集

爱尔兰海量ABC记谱法（IrishMAN） 数据集包含216,284首ABC记谱法的爱尔兰曲调，分为99%（214,122首曲调）用于训练和1%（2,162首曲调）用于验证。这些曲调来自thesession.org和abcnotation.com，这两个网站都以分享传统音乐而闻名。为了确保格式的一致性，所有曲调都使用 脚本 转换为XML，然后再转换回ABC，并删除了包含自然语言的字段（如标题和歌词）。

每首曲调都自动标注了从ABC符号派生的控制代码，如以下部分所述。这些控制代码提供了对每首乐曲的音乐形式和结构的洞察。

在IrishMAN数据集中，一个经过 music21 过滤的 子集 包含34,211张主旋律谱，每张都有人工标注的和弦符号。正是从这个子集中，TunesFormer发展了其生成带和声旋律的能力。

值得注意的是版权状态。数据集中的所有曲调都属于公共领域，确保了研究和创意项目的道德和合法使用。

控制代码

受 CTRL 的启发，我们将控制代码纳入TunesFormer以表示音乐形式。这些代码位于ABC记谱法之前，使用户能够指定生成曲调的结构。引入了以下控制代码：

• S:小节数：确定整个旋律中的小节数。它根据几个可用于表示小节边界的符号进行计数：[|、||、|]、|:、:: 和 :|。在我们的数据集中，范围是1到8（例如，S:1 表示单小节旋律，S:8 表示有八个小节的旋律）。

• B:每小节的节拍数：指定一个小节内所需的节拍数。它根据节拍符号 | 进行计数。在我们的数据集中，范围是1到32（例如，B:1 表示单节拍小节，B:32 表示有32个节拍的小节）。

• E:编辑距离相似度：控制旋律中当前小节 $c$ 与前一个小节 $p$ 之间的相似度水平。它基于Levenshtein距离 $lev(c,p)$，量化小节之间的差异以创建变化或对比。从数学上讲，它可以表示为：

  eds(c,p) = 1 - lev(c,p) / max(|c|,|p|)
  

  其中 $|c|$ 和 $|p|$ 是两个小节的字符串长度。它被离散化为11个级别，范围从完全不匹配到完全匹配（例如，E:0 表示无相似度，E:10 表示完全匹配）。

使用说明

1. 安装 此仓库 中代码所需的依赖。
2. 在 prompt.txt 中设置条件音乐生成的提示。
3. 运行 generate.py 脚本。
4. 在 output_tunes 文件夹中享受生成的曲调！如果需要，可参考 ABC Notation 将ABC曲调转换为乐谱或音频。

注意事项

ABC记谱法是一种专门用于表示乐谱的记谱法，它遵循特定的标准格式。与TunesFormer交互时，所有训练过的ABC记谱法都遵循这些标准格式。

如果您不熟悉ABC记谱法的细节，我们强烈建议不要手动输入ABC记谱法。否则，模型可能无法正确识别和生成音乐。输入不正确的格式可能会导致不可预测的输出或其他问题。

一般建议是通过控制代码和ABC标题来调整所需的音乐结构和形式，而不是直接编辑ABC记谱法本身。

有关ABC记谱法标准的更多详细信息，您可以参考 官方ABC记谱法标准描述。

请务必按照提供的格式和指南进行操作，以充分发挥TunesFormer的功能并获得满意的音乐生成体验。

使用自己的数据集

按照以下步骤操作：

1. 首先，解压 data_curation.zip 文件。
2. 然后，将你自己的符号音乐数据（.xml、.mxl、.musicxml 格式）放入 xmls 文件夹。
3. 运行 batch_converter.py 文件，将你的数据转换为ABC记谱法并放入 abcs 文件夹。
4. 运行 add_control_codes.py 文件。这将为你的ABC记谱法添加控制代码，并将数据保存为 dataset.json。
5. 最后，运行 train.py 文件来训练你自己的模型。权重将保存为 weights.pth

命令行参数

usage: generate.py [-h] [-num_tunes NUM_TUNES] [-max_patch MAX_PATCH]
                   [-top_p TOP_P] [-top_k TOP_K] [-temperature TEMPERATURE]
                   [-seed SEED] [-show_control_code SHOW_CONTROL_CODE]

optional arguments:
  -h, --help            显示此帮助消息并退出
  -num_tunes NUM_TUNES  独立计算返回的曲调数量
  -max_patch MAX_PATCH  定义每个曲调的最大标记长度的整数
  -top_p TOP_P          定义文本生成采样操作范围内的标记的浮点数
  -top_k TOP_K          定义文本生成采样操作范围内的标记的整数
  -temperature TEMPERATURE
                        采样操作的温度
  -seed SEED            随机状态的种子
  -show_control_code SHOW_CONTROL_CODE
                        是否显示控制代码

BibTeX引用

@inproceedings{DBLP:conf/hcmir/WuLY023,
  author       = {Shangda Wu and
                  Xiaobing Li and
                  Feng Yu and
                  Maosong Sun},
  editor       = {Lorenzo Porcaro and
                  Roser Batlle{-}Roca and
                  Emilia G{\'{o}}mez},
  title        = {TunesFormer: Forming Irish Tunes with Control Codes by Bar Patching},
  booktitle    = {Proceedings of the 2nd Workshop on Human-Centric Music Information
                  Retrieval 2023 co-located with the 24th International Society for
                  Music Information Retrieval Conference {(ISMIR} 2023), Milan, Italy,
                  November 10, 2023},
  series       = {{CEUR} Workshop Proceedings},
  volume       = {3528},
  publisher    = {CEUR-WS.org},
  year         = {2023},
  url          = {https://ceur-ws.org/Vol-3528/paper1.pdf},
  timestamp    = {Tue, 19 Dec 2023 17:15:12 +0100},
  biburl       = {https://dblp.org/rec/conf/hcmir/WuLY023.bib},
  bibsource    = {dblp computer science bibliography, https://dblp.org}
}

📄 许可证

本项目采用MIT许可证。