This package contains implementation of the paper Perception-Inspired Graph Convolution for Music Understanding Tasks submitted to IJCAI 2024. We propose a novel graph convolutional layer that is inspired by the way we perceive and learn pitch in music theory. We show that our layer outperforms SOTA graph convolutional layers in four music understanding tasks. The tasks are cadence detection, roman numeral analysis, composer classification and voice separation.
Please install the version of torch that is compatible with your machine preferably using conda.
Use the following command to install torch with conda:
conda create -n musgconv python=3.9
conda activate musgconv
conda install pytorch cudatoolkit=<your version of cuda> -c pytorch
Similarly, make sure to install Pytorch Geometric
To install the rest of the requirements with pip do:
cd Path/to/musgconv
pip install -r requirements.txt
Install as a package:
pip install -e .
We provide two main scripts to reproduce the experiments and tables of the paper.
The first script is run_main_experiment.py
which compares SOTA architectures for each
of our tasks to the same architecture where the graph convolutions are replaced with MusGConv.
The second script is run_ablation_experiment.py
which compares the performance of MusGConv with different
configurations of the parameters of the MusGConv layer.
To run the main experiments, you can use the following command:
python ./experiments/run_main_experiment.py --gpus <number of gpus> --use_wandb --wandb_entity <your_wandb_entity>
To run the ablation experiments, you can use the following command:
python ./experiments/run_ablation_experiment.py --gpus <number of gpus> --use_wandb --wandb_entity <your_wandb_entity>
For our paper, we used WandB to log our experiments.
To reproduce our results, you can simply provide your own WandB entity. The project name, groups, jobs and run
names will be automatically generated to match the paper.
The results of the experiments will be logged in the same fashion as in the paper, so you can compare your results with ours.
If you don't have a WandB account, you can create one for free.
You can find our results here: https://wandb.ai/vocsep/MusGConv
If you don't want to use WandB, don't use the flag --use_wandb
.
To use GPU for training, you can use the flag --gpus
and specify the number of GPUs you want to use.
In our experiments, we used a single GTX 1080 Ti GPU with 11GB of memory. If your GPU has less memory, you need to reduce the batch size.
However, in the experiments above the batch size is set to match the results the paper.
To run the individual experiments, you can use the following commands:
To change the parameters of the experiments, you can use the arguments of the scripts, use script_name.py --help
to see the arguments.
#### Cadence Detection
```shell
python ./experiments/cadet.py
python ./experiments/chord_prediction.py
python ./experiments/composer_classification.py
python ./experiments/voice_separation.py
To run the experiments with different parameters you can add arguments on the command line. For example, to run the experiments with a different number of hidden layers, you can use the following command:
python ./experiments/cadet.py --n_layers 3
To see all the possible arguments, you can use the following command:
python ./experiments/cadet.py --help
All experiments are logged with WANDB so if you want to log the experiments you can add the following arguments:
python ./experiments/cadet.py --use_wandb --wandb_entity <your_wandb_entity>
We would like to give credit to the following repositories that we used to build our codebase: