{"id":19078106,"url":"https://github.com/hendriks73/directional_cnns","last_synced_at":"2025-04-30T04:41:37.737Z","repository":{"id":35894495,"uuid":"169568260","full_name":"hendriks73/directional_cnns","owner":"hendriks73","description":"Source code repository for the SMC paper \"Musical Tempo and Key Estimation using Convolutional Neural Networks with Directional Filters\".","archived":false,"fork":false,"pushed_at":"2023-03-24T22:35:34.000Z","size":225,"stargazers_count":34,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-30T12:41:24.617Z","etag":null,"topics":["classification","cnn","keras","key","ml","music","tempo"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hendriks73.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-02-07T12:28:16.000Z","updated_at":"2025-01-11T02:34:17.000Z","dependencies_parsed_at":"2022-09-08T17:32:00.247Z","dependency_job_id":null,"html_url":"https://github.com/hendriks73/directional_cnns","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hendriks73%2Fdirectional_cnns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hendriks73%2Fdirectional_cnns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hendriks73%2Fdirectional_cnns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hendriks73%2Fdirectional_cnns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hendriks73","download_url":"https://codeload.github.com/hendriks73/directional_cnns/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251644826,"owners_count":21620630,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["classification","cnn","keras","key","ml","music","tempo"],"created_at":"2024-11-09T02:05:40.684Z","updated_at":"2025-04-30T04:41:37.716Z","avatar_url":"https://github.com/hendriks73.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![CC BY 3.0](https://img.shields.io/badge/License-CC%20BY%203.0-blue.svg)](https://creativecommons.org/licenses/by/3.0/)\n\n# Directional CNNs\n\nThis repository accompanies the paper [Musical Tempo and Key Estimation using Convolutional Neural Networks with\nDirectional Filters](http://smc2019.uma.es/articles/P1/P1_07_SMC2019_paper.pdf) in order to improve reproducibility of the reported results.\n\nIf you just want to estimate *tempo* or *key* values using models from the paper, please take a look at\nthe [tempo-cnn](https://github.com/hendriks73/tempo-cnn) and [key-cnn](https://github.com/hendriks73/key-cnn) repos.\nThey hosts pre-trained models.\n\n\n## Audio Files\n\nUnfortunately, because of size limitations imposed by GitHub as well as copyright issues, this repository does not\ncontain all audio samples or extracted features. But you can download those and extract them yourself.\n\nDownload links: \n\n- [GTzan](http://marsyas.info/download/data_sets/) \n- [Ballroom](http://mtg.upf.edu/ismir2004/contest/tempoContest/node5.html) \n- [Extended Ballroom](http://anasynth.ircam.fr/home/media/ExtendedBallroom) \n- [GiantSteps Key](https://github.com/GiantSteps/giantsteps-key-dataset) \n- [GiantSteps Tempo](https://github.com/GiantSteps/giantsteps-tempo-dataset) \n- [GiantSteps MTG Key and Tempo](https://github.com/GiantSteps/giantsteps-mtg-key-dataset)\n- [LMD Key and Tempo](https://bit.ly/2Bl8D1J)\n\nShould you use any of the datasets in your academic work, please cite the corresponding publications.  \n\n## Annotations\n\nAll necessary ground truth annotations are in the [annotations](./annotations) folder. For easy parsing they are\nformatted in a simple tab separated values (`.tsv`) format, with columns `id \\t bpm \\t key \\t genre \\n`. The class\n[GroundTruth](./directional_cnns/groundtruth.py) is capable of reading and interpreting these files.  \n\n## Installation\n\nIn a clean Python 3.5/3.6 environment:\n\n    git clone https:/github.com/hendriks73/directional_cnns.git\n    cd directional_cnns\n    python setup.py install\n\n## Feature Extraction\n\nTo extract features, you can use the code in [feature_extraction.py](./directional_cnns/feature_extraction.py)\nor the command line script mentioned below.\nDepending on how you define sample identifiers, you may need to make some manual adjustments.\nThe created `.joblib` files are simple dictionaries, containing strings as keys and a spectrograms as values.\nNote that the extracted spectrograms for the key and the tempo task differ (CQT vs Mel).\n\nAfter installation, you may run the extraction using the following command line script:\n\n    directional_cnn_extraction -a AUDIO_FILES_FOLDER [-g GROUND_TRUTH.tsv]\n    \nThe ground truth file is optional. If given, only files that also occur in the ground truth are added\nto the created feature `.joblib` files.\n\n## Running\n\nYou can run the code either locally or on [Google ML Engine](https://gcpsignup.page.link/9kLi).\n\n### Local\n\nRunning this locally only makes sense on a GPU and even then it will take very long.  \n\nTo run the training/reporting locally, you can execute the script [training.py](./directional_cnns/training.py)\nor the command line script mentioned below with the following arguments (example for *key*):\n\n    --job-dir=./\n    --model-dir=./\n    --train-file=annotations/key_train.tsv --valid-file=annotations/key_valid.tsv\n    --test-files=annotations/giantsteps-key.tsv,annotations/gtzan_key.tsv,annotations/lmd_key_test.tsv\n    --feature-files=features/giantsteps_key.joblib,features/mtg_tempo_key.joblib,features/gtzan_key.joblib,features/lmd_key.joblib\n\nAfter installation, you may run the training code using the following command line script:\n\n    directional_cnn_training [arguments]\n\n\n### Remote\n\nTo run the training/reporting remotely on [Google ML Engine](https://gcpsignup.page.link/9kLi), you first need to\nsign up, upload all necessary feature- and annotation-files to Google storage and then adapt the provided\nscripts [trainandpredict_key_ml_engine.sh](./trainandpredict_key_ml_engine.sh) and\n[trainandpredict_tempo_ml_engine.sh](./trainandpredict_tempo_ml_engine.sh) accordingly.\n\n## License\n\nThis repository is licensed under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/).\nFor attribution, please cite:\n\n\u003e Hendrik Schreiber and Meinard Müller, [Musical Tempo and Key Estimation using Convolutional Neural Networks with\nDirectional Filters](http://smc2019.uma.es/articles/P1/P1_07_SMC2019_paper.pdf),\n\u003e In Proceedings of the Sound and Music Computing Conference (SMC), Málaga, Spain, May 2019. ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhendriks73%2Fdirectional_cnns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhendriks73%2Fdirectional_cnns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhendriks73%2Fdirectional_cnns/lists"}