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許可證。